部署模型
一个项目一个平台、两种构建目标、每个平台允许的数据库与 agent 组合、密钥放在哪里、迁移何时执行,以及定时任务如何启动。
一个项目只部署到一个平台:Cloudflare、Fly.io、Railway 或 Docker 主机。这个选择保存在提交到仓库的
文件 deploy.config.json 中。它决定执行哪种构建、仓库里有哪个平台的文件、可以用哪些数据库、
迁移和定时任务如何启动。路由、守卫、仓储和校验器在所有平台上都一样。具体步骤见
部署项目。
一个项目一个平台
{
"platform": "cloudflare",
"agent": false,
"database": "d1"
}这个文件已经提交在你克隆的仓库里,由 kernlift deploy-target <platform> 改写。文件里
没有任何密钥。构建读取它来选择目标,应用也会把它打包进去,所以线上的 /setup 显示的就是这次构建
对应的平台、数据库和 agent 选择。
项目根目录只有所选平台的文件:wrangler.jsonc,或 fly.toml 与 fly.agent.toml,或
.railway/railway.ts,或 compose.yaml。package.json 里的 deploy 脚本执行该平台的部署命令。
全部字段和文件见 deploy.config.json。
两种构建目标
| 目标 | 平台 | 服务端入口 | 产物 | 启动方式 |
|---|---|---|---|---|
cloudflare | Cloudflare | src/server-entry.ts | dist/ | wrangler deploy |
node | Fly.io、Railway、Docker | src/server-entry.node.ts | .output/ | node .output/server/index.mjs |
pnpm build 根据 deploy.config.json 选择目标,所以无论在哪里构建(包括平台的远程构建器),产物
都相同。pnpm build:cloudflare 和 pnpm build:node 用来显式指定目标。没有这个文件的项目按
Cloudflare 构建。
Worker 入口还带有 Cron Trigger 的处理函数和 agent 容器类。Node 入口两者都没有,它在进程加载时启动
定时任务循环。根目录的 Dockerfile 为三个 Node 平台打包 Node 构建,见
运行 Node 构建。
平台、数据库与 agent 矩阵
| Cloudflare | Fly.io | Railway | Docker | |
|---|---|---|---|---|
| 不含 agent 时的数据库 | D1,或经 Hyperdrive 的 Postgres | Postgres,或挂卷的 SQLite | Postgres | Postgres,或挂卷的 SQLite |
| 含 agent 时的数据库 | 经 Hyperdrive 的 Postgres | Postgres | Postgres | Postgres |
| agent 服务 | Cloudflare 容器 | <name>-agent 应用 | agent 服务 | compose 的 agent 服务 |
| 对象存储 | R2 绑定或 S3 兼容存储 | S3 兼容存储 | S3 兼容存储 | S3 兼容存储 |
| 缓存 | KV 或进程内存 | 进程内存 | 进程内存 | 进程内存 |
agent 需要一个支持事务、并由 Web 应用和 agent 服务共用的数据库,所以它始终跑在 Postgres 上。SQLite
是单机方案:数据库文件归一台机器所有。D1 只存在于 Cloudflare。表外的组合会被
kernlift deploy-target 在写入任何文件之前拒绝。
agent 服务只有一个实例,因为它在内存里持有运行状态。它只能经平台的内网访问。不部署它,Web 应用 依然完整,见 Agent 运行时。
密钥
生产密钥只生成一次,写入 .env.production:会话密钥、包含 agent 时的 agent 签名密钥,以及 Docker 上
自带 Postgres 的密码。文件权限为 0600,被 git 和 Docker 构建上下文忽略。再次运行 CLI 只补全缺失的键,
不会轮换已有的值。
这些值再从该文件进入平台的密钥存储:wrangler secret put、fly secrets import、
railway variables,或 docker compose --env-file .env.production。命令经标准输入读取它们,所以
密钥不会被打印、不会出现在命令行上,也不会写进提交的文件。服务商凭据不在此列。它们保存在数据库里,
在 /admin/config/* 管理。
迁移先于流量
schema 只由迁移链构建,每个平台都在新版本接收请求之前应用迁移。
| 平台 | 由谁应用迁移 |
|---|---|
| Cloudflare + D1 | pnpm db:migrate:d1:remote,在 pnpm run deploy 之前执行 |
| Cloudflare + Postgres | 在检出目录里对 Postgres URL 执行 pnpm db:migrate |
| Fly.io + Postgres | fly.toml 里的 release_command,在临时机器上执行 |
| Fly.io + SQLite | 应用进程在启动服务之前执行;发布用的临时机器不挂卷 |
| Railway | web 服务的 preDeploy 步骤 |
| Docker | compose 的 migrate 服务;它成功后 web 才启动 |
Node 平台执行 node scripts/db/migrate-runtime.mjs,它不需要 TypeScript 运行器,记账表与
pnpm db:migrate 相同,所以两者可以用在同一个数据库上。
创建线上管理员是单独的一步,因为线上数据库不是本地那个。Node 镜像带有
node .output/scripts/bootstrap-super-admin.mjs。Cloudflare 在检出目录里执行
pnpm db:bootstrap-super-admin,D1 加上 --remote。
定时任务
后台工作通过 runScheduledJobs() 每分钟执行一轮:履约重试、积分过期和未完成的 AI 任务。由谁发起
一轮取决于构建目标。
- Cloudflare:
wrangler.jsonc里每分钟一次的 Cron Trigger 调用 Worker 的scheduled处理函数。 - Fly.io、Railway、Docker:Web 进程内的循环。每个副本都跑这个循环,配置表里的一行锁保证每轮 只有一个副本执行。不需要单独的任务进程,也不配置平台 cron。
Web 进程停止后不会执行任何任务,所以 fly.toml 保留 min_machines_running = 1。设置
JOBS_IN_PROCESS=false 会关闭循环,此时必须由外部 cron 调用 pnpm jobs:run。
每一轮都会记录执行时间。超过五分钟没有新的一轮,或上一轮有失败的任务时,/setup 把定时任务
显示为未就绪,并指出所在平台的开关。
切换平台做了什么
kernlift deploy-target <platform> 用 CLI 自带的模板重新渲染部署配置。它改写 deploy.config.json,
写入新平台的文件,把 deploy 脚本指向新平台,并把缺失的键补进 .env.production。原平台的文件移到
.kernlift/previous-deploy/。不删除任何文件,那里已有的副本也不会被覆盖。
切换只是文件操作。它不创建远程资源,不影响正在运行的部署,也不搬数据。下一次 pnpm build 跟随新的
目标。参数见 部署配置参考。
本地开发
本地开发在所有平台下都一样:pnpm dev,使用一个 SQLite 文件。生产用 Postgres 的项目,本地仍然用
SQLite 开发。
DATABASE_DIALECT=sqlite
DATABASE_URL=./local.dbpnpm db:migrate
SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin
pnpm dev引导步骤创建第一位管理员、权限集合与超级管理员角色,并写入运营基线内容。没有演示数据,外部服务商的 成功绝不伪造。
数据库适配器
schema 分为 SQLite 和 Postgres 两个家族,每个仓储都针对两者编写。DATABASE_DIALECT 决定家族。
DATABASE_ADAPTER 决定如何连接,默认等于方言。
| 适配器 | 方言 | 用在哪里 | 配置 |
|---|---|---|---|
sqlite | sqlite | 本地开发,Fly.io 与 Docker 的挂卷方案 | DATABASE_URL 是文件路径 |
d1 | d1 | Cloudflare | EDGE_DB 绑定 |
postgres | postgres | Fly.io、Railway、Docker、任意 Node 主机 | DATABASE_URL=postgresql://... |
hyperdrive | postgres | 使用 Postgres 的 Cloudflare | DATABASE_ADAPTER=hyperdrive 与 HYPERDRIVE 绑定 |
turso | sqlite | 使用 libSQL 的 Node 主机 | DATABASE_ADAPTER=turso、DATABASE_URL、DATABASE_AUTH_TOKEN |
Worker 不能复用为另一个请求打开的 socket,所以 hyperdrive 适配器为每个请求创建 Postgres 客户端,
连接池交给 Hyperdrive。项目可以注册自己的适配器,见
编写自定义数据库适配器。
Supabase 托管 Postgres
Supabase 和 Neon 都是托管的 Postgres 端点,走通用 Drizzle Postgres 适配器。应用不把 Supabase 专有的 API、客户端 SDK、认证助手、存储 API 或 RLS 作为业务依赖。授权始终留在服务端的认证、RBAC 和仓储层。
DATABASE_DIALECT=postgres
DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/postgres见使用 Postgres 与 Supabase和 使用 Turso。
Cloudflare Workers 与 D1
wrangler.jsonc 定义了 Worker 入口 src/server-entry.ts、D1 绑定 EDGE_DB、DATABASE_DIALECT=d1,
以及 D1 迁移目录 ./drizzle/migrations/sqlite。D1 属于 SQLite schema 家族,所以应用与本地 SQLite
相同的迁移。D1 没有交互式事务,开启事务的代码在那里改为依次执行各条语句。
变更 schema
schema 变更需要在两种方言下各有一条匹配的迁移:
pnpm db:generate:sqlite --name=my-change
pnpm db:generate:postgres --name=my-change
pnpm validate:migrationspnpm db:generate:sqlite 写入 drizzle/migrations/sqlite,pnpm db:generate:postgres 写入
drizzle/migrations/postgres。两个目录从不共享。pnpm db:generate 为 schema
的差异写出一条新迁移,不用于准备数据库。
基于 S3 兼容协议的存储
上传、删除和签名 URL 通过 S3 兼容协议完成,使用 /admin/config/storage 中后台管理的 S3 兼容配置:
端点、区域、存储桶、访问密钥、私密密钥、可选的 CDN 或公开访问域名,以及图片/视频/音频/文件上传的
MIME 类别。Cloudflare R2、阿里云 OSS、MinIO、AWS S3 等服务商共用这条路径。
存储凭据是后台设置,不放在环境变量里,所以每个平台都以相同方式配置存储。在 Cloudflare 上,存储桶绑定 是同一存储接口后面的第二种驱动。其它平台没有绑定,使用 S3 兼容凭据。
外部服务商验证
本地验证覆盖状态机和缺少服务商时的失败路径。真实服务商检查需要沙箱或生产凭据:
pnpm validate:external-readiness
EXTERNAL_VALIDATE_STRICT=true pnpm validate:external就绪报告写入 openspec/EXTERNAL_VALIDATION_STATUS.json。有意保留未完成的 OpenSpec 3.3 任务是
auth-account 3.3、billing-payment 3.3、analytics-support 3.3、ai-workspace 3.3 和
newsletter-waitlist 3.3,在配置真实的 Google OAuth、支付、分析、AI 和邮件订阅凭据之前保持未勾选。
发布护栏
- 发布前运行
pnpm validate:all。 - 修改部署模板或 Dockerfile 后运行
pnpm validate:deploy-targets。 - 修改 Drizzle schema 或迁移文件后运行
pnpm validate:migrations。 - 部署前运行
pnpm build,再对要发布的构建做冒烟检查:Cloudflare 在pnpm build之后运行pnpm smoke:worker,其它平台在pnpm build:node之后运行pnpm smoke:node。 - SQLite/D1 迁移放在
drizzle/migrations/sqlite,Postgres 迁移放在drizzle/migrations/postgres。 - 把
A32-A34与A82-A98排除在路由和设计生成输入之外。 - 保持
/zh路由对等。 - 不添加 mock 服务商,也不伪造服务商 id、结账 URL、提现成功、邮件 id、AI 输出或分析报表。