部署到 Node.js | EmDash CMS Everything

EmDash 可在任何 Node.js 22+ 託管平台上執行。本指南使用 SQLite 搭配本機或 S3 相容儲存；libSQL 和 PostgreSQL 在 Node.js 上的運作方式相同 — 參見資料庫選項。

前置要求

Node.js v22.12.0 或更高版本
Node.js 託管提供者或 VPS

設定

為 Node.js 部署設定 EmDash：

import { defineConfig } from "astro/config";
import node from "@astrojs/node";
import emdash, { local, s3 } from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
	output: "server",
	adapter: node({ mode: "standalone" }),
	integrations: [
		emdash({
			database: sqlite({ url: "file:./data/emdash.db" }),
			storage: local({
				directory: "./data/uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

建置與執行

建置專案：
```
npm run build
```
啟動伺服器：
```
node ./dist/server/entry.mjs
```

伺服器預設在 http://localhost:4321 執行。遷移在首次請求時套用。如果資料庫為空且設定未完成，你的種子檔案（如果沒有則使用內建預設值）也會在首次請求時套用。

正式環境儲存

對於正式環境，使用 S3 相容儲存代替本機檔案系統：

import emdash, { s3 } from "emdash/astro";

export default defineConfig({
	integrations: [
		emdash({
			database: sqlite({ url: `file:${process.env.DATABASE_PATH}` }),
			storage: s3({
				endpoint: process.env.S3_ENDPOINT,
				bucket: process.env.S3_BUCKET,
				accessKeyId: process.env.S3_ACCESS_KEY_ID,
				secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
				publicUrl: process.env.S3_PUBLIC_URL, // 選用的 CDN URL
			}),
		}),
	],
});

Docker

新增 .dockerignore 以保持建置上下文較小：

node_modules
dist
.git

建立 Dockerfile：

FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

RUN mkdir -p data

ENV HOST=0.0.0.0
ENV PORT=4321

EXPOSE 4321
CMD ["node", "./dist/server/entry.mjs"]

種子檔案在建置時讀取並內嵌到打包檔案中，因此不需要複製到執行時映像中。遷移在部署後的首次請求時執行；種子僅在資料庫沒有集合且設定未完成時套用 — 現有資料永遠不會被覆寫。

如果遇到該錯誤，在 npm ci 之前在建置階段安裝工具鏈：

# 基於 Alpine 的映像（node:22-alpine）
RUN apk add --no-cache python3 make g++

# 基於 Debian 的映像（node:22-slim）
RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ \
    && rm -rf /var/lib/apt/lists/*

建置映像並執行容器：

docker build -t my-emdash-site .
docker run -p 4321:4321 -v emdash-data:/app/data my-emdash-site

Docker Compose 檔案使用具名磁碟區管理同一容器：

services:
  emdash:
    build: .
    ports:
      - "4321:4321"
    volumes:
      - emdash-data:/app/data
    restart: unless-stopped

volumes:
  emdash-data:

在背景啟動堆疊：

docker compose up -d

環境變數

建議：加密金鑰

EMDASH_ENCRYPTION_KEY 是用於加密外掛密鑰的靜態儲存金鑰。金鑰在啟動時驗證；外掛密鑰加密在啟用後使用它。在每次部署時設定它，這樣密鑰無需後續設定變更即可得到保護。

產生金鑰並將結果新增到你的環境中：

npx emdash secrets generate  # 將結果新增到你的環境中

金鑰由你提供，永遠不會儲存在資料庫中；只儲存加密的密文。將其備份到持久的地方（密碼管理器、KMS 或團隊的密鑰儲存）— 遺失它意味著遺失用它加密的每個密鑰。

選用：穩定值覆寫

EmDash 自動產生預覽 HMAC 密鑰和留言者 IP 雜湊鹽，並在首次使用時將它們持久化到資料庫中。以下環境變數將它們固定為你控制的值 — 當單獨的行程需要與主網站共用密鑰時很有用。

變數	描述
`EMDASH_PREVIEW_SECRET`	自動產生的預覽 HMAC 密鑰的覆寫。
`EMDASH_IP_SALT`	自動產生的留言者 IP 雜湊鹽的覆寫。
`EMDASH_AUTH_SECRET`	選用。如果設定，將用作 IP 鹽來源（除非同時設定了 `EMDASH_IP_SALT`，後者優先），使已依賴它的安裝的留言者 IP 雜湊保持穩定。新部署請保持未設定。

資料庫與儲存

變數	描述	範例
`DATABASE_PATH`	SQLite 資料庫路徑	`/data/emdash.db`
`HOST`	伺服器主機	`0.0.0.0`
`PORT`	伺服器連接埠	`4321`
`S3_ENDPOINT`	S3 端點 URL	`https://xxx.r2.cloudflarestorage.com`
`S3_BUCKET`	S3 儲存桶名稱	`my-media-bucket`
`S3_ACCESS_KEY_ID`	S3 存取金鑰	`AKIA...`
`S3_SECRET_ACCESS_KEY`	S3 密鑰	`...`
`S3_PUBLIC_URL`	媒體的公開 URL	`https://cdn.example.com`

持久儲存

SQLite 需要持久的磁碟儲存。確保你的託管平台提供：

掛載的磁碟區或持久磁碟
資料庫目錄的寫入權限
資料庫檔案的備份機制

健康檢查

為負載平衡器新增健康檢查端點：

export const GET = () => {
  return new Response("OK", { status: 200 });
};

設定平台檢查 /health 用於存活探測。