运行 Node 构建
用 pnpm build:node 或根目录的 Dockerfile 构建 Node 服务,提供它需要的环境变量,迁移,然后在任意主机上运行。
除 Cloudflare 以外,所有平台运行的都是同一个 Node 服务。pnpm build:node 构建它,根目录的 Dockerfile 打包它,Fly.io、Railway 和 Docker Compose 各自用生成的配置部署这个镜像。本指南说明这个构建里有什么,以及如何在没有专门指南的主机上运行它。三个受支持的平台请直接看部署到 Fly.io、部署到 Railway或用 Docker Compose 部署。
准备工作
- 一台装有 Node 22 或 Docker 的主机。
- 一个数据库:Postgres(见使用 Postgres 与 Supabase),或单实例时放在重启后不丢失的磁盘上的 SQLite 文件。
- 一个会话密钥。
kernlift deploy-target生成的.env.production里已经有。
构建产物
| 路径 | 内容 |
|---|---|
.output/server/index.mjs | 服务端。pnpm start 运行它;监听 PORT,镜像里是 3000 |
.output/scripts/bootstrap-super-admin.mjs | 对部署自己的数据库创建管理员,不需要 TypeScript 运行器 |
scripts/db/migrate-runtime.mjs | 用纯 Node 应用迁移链 |
drizzle/migrations/ | 迁移器读取的 SQLite 与 Postgres 迁移链 |
根目录的 Dockerfile 执行 pnpm build:node,把这四项复制进 node:22 镜像,并装上数据库驱动(better-sqlite3、postgres、drizzle-orm)。驱动在运行时按名字加载,不在打包产物里。镜像以 node 用户运行,暴露 3000 端口,并提供 /data 目录,用来放挂载卷上的 SQLite 文件。agent 服务是另一个镜像:apps/agent-service/Dockerfile。
deploy.config.json 里是 fly、railway 或 docker 时,pnpm build 产出的就是这个构建;pnpm build:node 则始终产出它。
环境变量
服务从进程环境读取设置。
| 变量 | 值 |
|---|---|
APP_ENV | production |
PORT | 监听端口 |
BETTER_AUTH_SECRET | .env.production 里的会话密钥 |
CONFIG_ENCRYPTION_KEY | .env.production 里的凭据加密密钥,生成后不要更换 |
SITE_URL | 规范源地址,用于页面元数据和绝对链接 |
DATABASE_DIALECT | postgres 或 sqlite |
DATABASE_URL | postgresql:// URL,或 /data/app.db 这样的文件路径 |
JOBS_IN_PROCESS | 不要设置。设为 false 会关闭定时任务循环,此时必须由外部 cron 调用 pnpm jobs:run |
AGENT_SERVICE_URL、AGENT_INTERNAL_SIGNING_SECRET | 仅在部署 agent 服务时需要:它的内网地址和双方共用的签名密钥 |
构建并运行
应用迁移
设置好 DATABASE_DIALECT 和 DATABASE_URL,在新版本接收流量之前运行迁移器:
node scripts/db/migrate-runtime.mjs它的记账表与 pnpm db:migrate 相同,两者可以用在同一个数据库上。
创建管理员
在与服务相同的环境里:
node .output/scripts/bootstrap-super-admin.mjs它会提示输入邮箱和密码,密码不回显。没有终端时,改为在环境里设置 SUPER_ADMIN_EMAIL 和 SUPER_ADMIN_PASSWORD。
验证
/setup上会话密钥和定时任务为就绪;后者在首次启动后需要一两分钟。- 在仓库里,
pnpm build:node之后的pnpm smoke:node会用一次性的 SQLite 数据库启动这个构建,检查页面能渲染、没有 agent 服务时 agent 接口返回 503、并且记录了一轮定时任务。 pnpm validate:deploy-targets检查镜像运行的是 Node 构建,并带有迁移文件和迁移器。
故障排查
.output/server/index.mjs is missing
上一次构建是 Cloudflare 构建,产物在 dist/。运行 pnpm build:node。
DATABASE_URL is required when DATABASE_ADAPTER=postgres
DATABASE_DIALECT 是 postgres,但 DATABASE_URL 为空。设置连接串。
服务因会话密钥错误拒绝启动
APP_ENV 不是 development,且 BETTER_AUTH_SECRET 缺失或仍是模板默认值。设置生成的值。
/setup 上定时任务一直未就绪
Web 进程没在运行,或者设置了 JOBS_IN_PROCESS=false 但没有任何程序调用 pnpm jobs:run。