部署到 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 用于存活探测。