部署配置

deploy.config.json 和改写它的 kernlift deploy-target 命令:允许的组合、每个平台拥有的文件、.env.production 的键,以及各平台如何迁移和创建管理员。

deploy.config.json 是提交到仓库的部署记录,写明项目部署到哪里。你克隆的仓库里已经带有它,kernlift deploy-target 改写它,vite.config.ts 读取它来选择构建目标,应用也把它打包进去,供 /setup 显示。文件里没有任何密钥。设计上的原因见部署模型。

字段

deploy.config.json
{
  "platform": "cloudflare",
  "agent": false,
  "database": "d1"
}
字段取值含义
platformcloudflare、fly、railway、docker项目部署到的唯一平台。决定构建目标,以及存在哪个平台的文件
agenttrue、false是否在 Web 应用旁边部署 agent 服务
databased1、postgres、sqlite生产数据库。无论这里写什么,本地开发都使用 SQLite 文件

没有这个文件的项目按 Cloudflare 构建。不要手工修改它。平台文件和它一起渲染,要改就用 kernlift deploy-target。参数见下文。

用 kernlift deploy-target 切换平台

kernlift deploy-target <cloudflare|fly|railway|docker> [flags] 在带有 deploy.config.json 的项目目录里运行。它改写这个文件和平台文件,把 deploy 脚本指向该平台的部署命令,把其他平台的文件移到 .kernlift/previous-deploy/,向 .env.production 补上缺少的键,并打印后续步骤。它不创建任何远端资源,也不迁移数据。克隆下来的项目只需要 kernlift 的这一条命令,其余都用脚本完成。

CLI 没有依赖,运行在 Node 20 或更新版本上。它的源码在你克隆的仓库的 tools/kernlift/ 里。用 pnpm kernlift deploy-target <platform> 运行。根 package.json 里的 kernlift 脚本执行的是 tools/kernlift/src/kernlift.js,不需要从 npm 下载任何包。

参数含义
--agent / --no-agent包含或去掉 agent 服务(默认:项目当前的选择)
--dialect <db>生产数据库(默认:新平台允许时沿用当前的,否则取该平台的第一个可选项)
--region <code>Fly.io 主区域(默认 iad)
--cwd <dir>项目目录(默认:当前目录)
--help打印用法

取值的参数写作 --flag value 或 --flag=value。--agent 和 --no-agent 不取值。

退出码:

退出码何时
0命令完成
1任何错误(信息打印到 stderr):未知的平台、平台不允许的组合,或目录里没有 deploy.config.json

允许的组合

platformagent: falseagent: true
cloudflared1、postgrespostgres
flypostgres、sqlitepostgres
railwaypostgrespostgres
dockerpostgres、sqlitepostgres

一共十一种组合。CLI 在写入文件之前拒绝其它组合。agent 需要 Postgres,因为它的运行需要事务,以及一个由两个进程共用的数据库。sqlite 是单机方案,d1 只存在于 Cloudflare。执行 kernlift deploy-target 时不带 --dialect,新平台允许当前数据库就沿用,否则取该行的第一个值。

每个平台拥有什么

platform项目根目录中的文件构建目标deploy 脚本
cloudflarewrangler.jsonccloudflarewrangler deploy
flyfly.toml,包含 agent 时还有 fly.agent.tomlnodefly deploy
railway.railway/railway.tsnoderailway up
dockercompose.yamlnodedocker compose --env-file .env.production up -d --build

node 构建目标由根目录的 Dockerfile 打包。agent 服务在所有平台上都使用 apps/agent-service/Dockerfile。无论选哪个平台,这两个 Dockerfile 都留在仓库里。

平台文件由 CLI 自带的模板渲染。kernlift deploy-target 对项目当前的平台再次渲染时,内容与新渲染结果不同的文件(填了资源 id 的 wrangler.jsonc、手工改动)会先移到 .kernlift/previous-deploy/ 再写入新文件。内容相同的文件不动。

各平台的行为

cloudflareflyrailwaydocker
迁移d1 用 pnpm db:migrate:d1:remote;postgres 对 Postgres URL 执行 pnpm db:migratepostgres 用 release_command;sqlite 在进程启动时web 服务的 preDeploymigrate 服务
迁移器Wrangler 的 D1 迁移,或 scripts/db/migrate.tsscripts/db/migrate-runtime.mjsscripts/db/migrate-runtime.mjsscripts/db/migrate-runtime.mjs
线上管理员DATABASE_DIALECT=d1 时 pnpm db:bootstrap-super-admin --remote;Postgres 时带上 DATABASE_URLfly ssh console --pty -C "node .output/scripts/bootstrap-super-admin.mjs"railway ssh --service web,再运行同一个脚本docker compose exec web 运行同一个脚本
定时任务Cron Trigger,每分钟一次Web 进程内循环;min_machines_running = 1Web 进程内循环Web 进程内循环
密钥存储wrangler secret putfly secrets importrailway variables--env-file .env.production
agent 服务绑定为 AGENT_SERVICE 的容器应用 <name>-agent,fly.agent.toml服务 agent,单副本服务 agent
Web 访问 agent 的地址容器绑定http://<name>-agent.internal:3001http://agent.railway.internal:3001http://agent:3001
agent 访问 Web 的地址AGENT_WEB_INTERNAL_URL,即 Worker 的公网 URLhttp://<name>.internal:3000http://web.railway.internal:3000http://web:3000
Postgres 的来源你的数据库,经 HYPERDRIVE 绑定你的数据库,作为 DATABASE_URL 密钥.railway/railway.ts 里的 postgres 资源compose 的 postgres 服务
SQLite 文件不提供data 卷上的 /data/app.db不提供data 卷上的 /data/app.db

.env.production

由 kernlift deploy-target 在项目根目录生成并补全。文件权限为 0600,被 git 和 Docker 构建上下文忽略。已有的文件会保留。之后的运行只添加缺失的键,不修改也不删除任何值。

键何时生成值
BETTER_AUTH_SECRET始终32 个随机字节,十六进制
CONFIG_ENCRYPTION_KEY始终32 个随机字节,十六进制;用来加密后台配置里的服务商密钥,生成后不要更换
SITE_URL始终创建项目时给出的站点 URL;请改成部署后的源地址
POSTGRES_PASSWORDdocker 且 postgres32 个随机字节,十六进制;自带 Postgres 的密码
AGENT_INTERNAL_SIGNING_SECRETagent 为 true32 个随机字节,十六进制;Web 应用与 agent 服务共用
AGENT_RESOURCE_GRANT_SECRETagent 为 true32 个随机字节,十六进制

在 fly 上使用 Postgres 时,DATABASE_URL 由你自己加进去,导入 Fly 密钥时会一并带上。在 cloudflare 上,agent 容器直连 Postgres 的 URL 以 AGENT_DATABASE_URL 密钥保存。这些值经标准输入送到平台,不会被打印。它和 .env 是两个文件,后者存放你本机的开发值。

.kernlift/previous-deploy/

kernlift deploy-target 切换平台时,项目根目录里属于其它平台的文件会按原相对路径移到这里,例如 .kernlift/previous-deploy/wrangler.jsonc。不删除任何文件。那里已有的副本不会被覆盖。后来的副本取下一个空闲的名字,wrangler.jsonc.1,然后是 .2。

这个目录用来找回内容,比如早先 wrangler.jsonc 里的资源 id。切回某个平台时,它的文件仍由模板重新渲染,不会从这里恢复。

检查

命令检查什么
pnpm validate:deploy-targets每个允许的组合都渲染出正确的文件,不允许的组合被拒绝,根目录的文件与渲染器一致,Node 构建能启动
pnpm smoke:nodepnpm build:node 之后,在一次性的 SQLite 数据库上检查 Node 构建
pnpm smoke:workerpnpm build 之后,在一次性的 D1 数据库上检查 Worker 构建

下一步