部署到 Node.js | EmDash CMS Everything

EmDash 在 Node.js 22.16 或更高版本上运行。本指南使用 SQLite 配合本地或 S3 兼容存储；libSQL 和 PostgreSQL 在 Node.js 上的工作方式相同 — 请参阅数据库选项。

前提条件

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 上运行。迁移在第一个请求时应用。如果数据库为空且设置未完成，您的种子文件（如果没有则使用内置默认值）也会在第一个请求时应用。

计划任务

内置调度器仅在 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({
				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"]

种子文件在构建时读取并内联到 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 是用于加密插件密钥的静态加密密钥。该密钥在启动时验证；插件密钥加密在启用后使用它。在每次部署时设置它，这样密钥无需后续配置更改即可受到保护。

生成密钥并将结果添加到您的环境中：

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 以进行存活探测。