部署到 Node.js | EmDash CMS Everything

EmDash 在 Node.js 22.16 或更高版本上執行。本指南為單一伺服器使用 SQLite 和本機儲存。當多個執行個體需要共用一個資料庫時使用 PostgreSQL 或 libSQL，當媒體需要獨立於伺服器磁碟存續時使用 S3 相容儲存。

先決條件

Node.js v22.16.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 上執行。使用預設的 auto 遷移模式時，第一個請求會套用待處理的核心遷移。全新資料庫還會接收嵌入的種子。管理核心資料庫遷移介紹了如何在恢復正式環境流量之前進行遷移。

排程工作

內建排程器僅在 Node.js 程序執行時運作。它處理排程發佈、外掛工作和一般維護。

在正式環境中保持至少一個 Node.js 程序持續執行。當所有程序停止或休眠時，排程工作會暫停。

外掛沙盒

市集外掛和 sandboxed: [] 下列出的外掛需要沙盒執行器。在 Node.js 上，執行器是 @emdash-cms/sandbox-workerd，它在 workerd 子程序中執行外掛。外掛沙盒涵蓋了安裝、workerd 程序如何執行以及其故障模式。

選擇正式環境資料服務

當資料庫保留在持久卷上而媒體移至 S3 相容儲存時，使用以下模式：

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

export default defineConfig({
	integrations: [
			emdash({
				database: sqlite({ url: `file:${process.env.DATABASE_PATH}` }),
				storage: s3(),
		}),
	],
});

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"]

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

建置映像檔並執行容器：

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 目前不加密外掛密鑰或任何其他儲存資料。如果設定了該變數，EmDash 在啟動時檢查其格式，但外掛密鑰值在資料庫中保持明文。

如果設定該變數，請產生一個有效值並將結果新增到你的環境中：

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

該值由營運人員提供，不儲存在資料庫中。遺失它對資料復原沒有影響，因為沒有儲存資料依賴於它。將資料庫及其備份視為敏感資料，因為它們包含明文外掛密鑰。

可選：穩定值覆寫

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_REGION`	S3 區域	`auto`
`S3_PUBLIC_URL`	媒體公開 URL	`https://cdn.example.com`

持久化儲存

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

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

同時備份 SQLite 檔案和上傳目錄。復原時替換之前先停止程序。參見備份。

健康檢查

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

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

此端點證明 Node.js 程序可以提供 Astro 路由。它不證明資料庫、儲存後端、遷移狀態或外掛沙盒是健康的。在向新版本傳送流量之前，請單獨驗證這些相依性。

傳送流量前驗證

啟動新建置後，驗證正式環境請求使用的相同執行時服務：

請求 /health 和一個公開內容頁面。兩者都必須傳回成功回應。
從建置的專案執行 npx emdash migrate --check。它必須報告設定的資料庫沒有待處理或未知的遷移。
登入 /_emdash/admin，建立或編輯一個臨時草稿並發佈。確認公開頁面顯示了變更。
上傳一個臨時媒體檔案並開啟其傳回的 URL。驗證後刪除該檔案。
如果站點使用沙盒外掛，呼叫一個外掛路由或掛鉤，確認伺服器日誌沒有沙盒不可用或 workerd 啟動錯誤。

在所有適用檢查通過之前，不要將新執行個體加入負載平衡器。