部署配置
deploy.config.json 和改写它的 kernlift deploy-target 命令:允许的组合、每个平台拥有的文件、.env.production 的键,以及各平台如何迁移和创建管理员。
deploy.config.json 是提交到仓库的部署记录,写明项目部署到哪里。你克隆的仓库里已经带有它,kernlift deploy-target 改写它,vite.config.ts 读取它来选择构建目标,应用也把它打包进去,供 /setup 显示。文件里没有任何密钥。设计上的原因见部署模型。
字段
{
"platform": "cloudflare",
"agent": false,
"database": "d1"
}| 字段 | 取值 | 含义 |
|---|---|---|
platform | cloudflare、fly、railway、docker | 项目部署到的唯一平台。决定构建目标,以及存在哪个平台的文件 |
agent | true、false | 是否在 Web 应用旁边部署 agent 服务 |
database | d1、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 |
允许的组合
platform | agent: false | agent: true |
|---|---|---|
cloudflare | d1、postgres | postgres |
fly | postgres、sqlite | postgres |
railway | postgres | postgres |
docker | postgres、sqlite | postgres |
一共十一种组合。CLI 在写入文件之前拒绝其它组合。agent 需要 Postgres,因为它的运行需要事务,以及一个由两个进程共用的数据库。sqlite 是单机方案,d1 只存在于 Cloudflare。执行 kernlift deploy-target 时不带 --dialect,新平台允许当前数据库就沿用,否则取该行的第一个值。
每个平台拥有什么
platform | 项目根目录中的文件 | 构建目标 | deploy 脚本 |
|---|---|---|---|
cloudflare | wrangler.jsonc | cloudflare | wrangler deploy |
fly | fly.toml,包含 agent 时还有 fly.agent.toml | node | fly deploy |
railway | .railway/railway.ts | node | railway up |
docker | compose.yaml | node | docker 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/ 再写入新文件。内容相同的文件不动。
各平台的行为
cloudflare | fly | railway | docker | |
|---|---|---|---|---|
| 迁移 | d1 用 pnpm db:migrate:d1:remote;postgres 对 Postgres URL 执行 pnpm db:migrate | postgres 用 release_command;sqlite 在进程启动时 | web 服务的 preDeploy | migrate 服务 |
| 迁移器 | Wrangler 的 D1 迁移,或 scripts/db/migrate.ts | scripts/db/migrate-runtime.mjs | scripts/db/migrate-runtime.mjs | scripts/db/migrate-runtime.mjs |
| 线上管理员 | DATABASE_DIALECT=d1 时 pnpm db:bootstrap-super-admin --remote;Postgres 时带上 DATABASE_URL | fly 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 = 1 | Web 进程内循环 | Web 进程内循环 |
| 密钥存储 | wrangler secret put | fly secrets import | railway variables | --env-file .env.production |
| agent 服务 | 绑定为 AGENT_SERVICE 的容器 | 应用 <name>-agent,fly.agent.toml | 服务 agent,单副本 | 服务 agent |
| Web 访问 agent 的地址 | 容器绑定 | http://<name>-agent.internal:3001 | http://agent.railway.internal:3001 | http://agent:3001 |
| agent 访问 Web 的地址 | AGENT_WEB_INTERNAL_URL,即 Worker 的公网 URL | http://<name>.internal:3000 | http://web.railway.internal:3000 | http://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_PASSWORD | docker 且 postgres | 32 个随机字节,十六进制;自带 Postgres 的密码 |
AGENT_INTERNAL_SIGNING_SECRET | agent 为 true | 32 个随机字节,十六进制;Web 应用与 agent 服务共用 |
AGENT_RESOURCE_GRANT_SECRET | agent 为 true | 32 个随机字节,十六进制 |
在 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:node | pnpm build:node 之后,在一次性的 SQLite 数据库上检查 Node 构建 |
pnpm smoke:worker | pnpm build 之后,在一次性的 D1 数据库上检查 Worker 构建 |