运行 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_ENVproduction
PORT监听端口
BETTER_AUTH_SECRET.env.production 里的会话密钥
CONFIG_ENCRYPTION_KEY.env.production 里的凭据加密密钥,生成后不要更换
SITE_URL规范源地址,用于页面元数据和绝对链接
DATABASE_DIALECTpostgres 或 sqlite
DATABASE_URLpostgresql:// URL,或 /data/app.db 这样的文件路径
JOBS_IN_PROCESS不要设置。设为 false 会关闭定时任务循环,此时必须由外部 cron 调用 pnpm jobs:run
AGENT_SERVICE_URL、AGENT_INTERNAL_SIGNING_SECRET仅在部署 agent 服务时需要:它的内网地址和双方共用的签名密钥

服务商凭据不放在这里,见管理配置。全部变量见环境变量。

构建并运行

构建

在检出目录里:

pnpm install
pnpm build:node

或者在仓库根目录构建镜像:

docker build -t kernlift-web .

应用迁移

设置好 DATABASE_DIALECT 和 DATABASE_URL,在新版本接收流量之前运行迁移器:

node scripts/db/migrate-runtime.mjs

它的记账表与 pnpm db:migrate 相同,两者可以用在同一个数据库上。

启动服务

node .output/server/index.mjs

这也是镜像的默认命令。定时任务随进程启动,每分钟执行一轮。有多个副本时,配置表里的一行锁保证每轮只有一个副本执行。

创建管理员

在与服务相同的环境里:

node .output/scripts/bootstrap-super-admin.mjs

它会提示输入邮箱和密码,密码不回显。没有终端时,改为在环境里设置 SUPER_ADMIN_EMAIL 和 SUPER_ADMIN_PASSWORD。

配置运行时服务

登录后打开 /setup。在 /admin/config/storage 填写 S3 兼容凭据。存储桶绑定驱动只存在于 Cloudflare。/admin/config/cache 的后端是进程内存,每个进程各有一份缓存。见配置文件存储与上传和缓存。

验证

  • /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。

下一步