部署模型

一个项目一个平台、两种构建目标、每个平台允许的数据库与 agent 组合、密钥放在哪里、迁移何时执行,以及定时任务如何启动。

一个项目只部署到一个平台:Cloudflare、Fly.io、Railway 或 Docker 主机。这个选择保存在提交到仓库的 文件 deploy.config.json 中。它决定执行哪种构建、仓库里有哪个平台的文件、可以用哪些数据库、 迁移和定时任务如何启动。路由、守卫、仓储和校验器在所有平台上都一样。具体步骤见 部署项目。

一个项目一个平台

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。

两种构建目标

目标平台服务端入口产物启动方式
cloudflareCloudflaresrc/server-entry.tsdist/wrangler deploy
nodeFly.io、Railway、Dockersrc/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 矩阵

CloudflareFly.ioRailwayDocker
不含 agent 时的数据库D1,或经 Hyperdrive 的 PostgresPostgres,或挂卷的 SQLitePostgresPostgres,或挂卷的 SQLite
含 agent 时的数据库经 Hyperdrive 的 PostgresPostgresPostgresPostgres
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 + D1pnpm db:migrate:d1:remote,在 pnpm run deploy 之前执行
Cloudflare + Postgres在检出目录里对 Postgres URL 执行 pnpm db:migrate
Fly.io + Postgresfly.toml 里的 release_command,在临时机器上执行
Fly.io + SQLite应用进程在启动服务之前执行;发布用的临时机器不挂卷
Railwayweb 服务的 preDeploy 步骤
Dockercompose 的 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.db
pnpm 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 决定如何连接,默认等于方言。

适配器方言用在哪里配置
sqlitesqlite本地开发,Fly.io 与 Docker 的挂卷方案DATABASE_URL 是文件路径
d1d1CloudflareEDGE_DB 绑定
postgrespostgresFly.io、Railway、Docker、任意 Node 主机DATABASE_URL=postgresql://...
hyperdrivepostgres使用 Postgres 的 CloudflareDATABASE_ADAPTER=hyperdrive 与 HYPERDRIVE 绑定
tursosqlite使用 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:migrations

pnpm 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 输出或分析报表。

相关文件

deploy.config.json
vite.config.ts
src/server/platform/deployment.ts
src/server-entry.ts
src/server-entry.node.ts
Dockerfile
apps/agent-service/Dockerfile

下一步