部署到 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, // Optional 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"]

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

建置映像並執行容器：

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  # add the result to your environment

金鑰由您提供，永遠不會儲存在資料庫中；只有加密的密文會被儲存。將其備份到持久位置（密碼管理器、 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 進行存活探測。