部署到 Cloudflare Workers
把 Worker 部署在 D1 或经 Hyperdrive 连接的 Postgres 上,写入会话密钥,创建线上管理员,并按需加上 agent 容器。
在 Cloudflare 上,项目是一个 Worker,带一个 R2 桶和一个 KV 命名空间。数据库是 D1,或经 Hyperdrive 访问的 Postgres。agent 服务可选,以 Cloudflare 容器运行,且只支持 Postgres。首次生产部署或修改绑定后使用本指南。
准备工作
- Cloudflare 账号,且
wrangler已登录(npx wrangler login)。 deploy.config.json中是"platform": "cloudflare"。如果是别的平台,先执行pnpm kernlift deploy-target cloudflare,见 deploy.config.json。- 使用 Postgres 时:一个空的 Postgres 数据库及其连接 URL,见使用 Postgres 与 Supabase。
- 项目根目录的
.env.production。pnpm kernlift deploy-target cloudflare会生成它,里面有会话密钥。
在 Cloudflare 创建资源
先在要部署的 Cloudflare 账号中登录 Wrangler,将示例中的 my-saas 换成你的项目名。
选择数据库连接
D1 项目创建数据库并保存输出的 database_id。
npx wrangler d1 create my-saas-edgePostgres 项目在此处改为创建 Hyperdrive。将命令中的连接串替换为你的数据库连接串,保存输出的配置 ID。
npx wrangler hyperdrive create my-saas-db --connection-string='postgresql://USER:PASSWORD@HOST:5432/DB'把 D1 的 database_id、KV 的 id、R2 桶名和 Hyperdrive id 填进 wrangler.jsonc 里已有的条目。Wrangler 若询问是否自动添加绑定,请拒绝。模板已经声明了 EDGE_DB、BUCKET、CACHE 和 HYPERDRIVE,应用按这些名字查找绑定。见 D1 创建数据库、R2 创建桶、KV 创建命名空间和 Hyperdrive。
绑定资源
填写 wrangler.jsonc
把每个 replace-with-... 占位符换成真实 id,保留 worker name。D1 项目包含:
"r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-saas-assets" }],
"kv_namespaces": [{ "binding": "CACHE", "id": "<your KV namespace id>" }],
"d1_databases": [
{
"binding": "EDGE_DB",
"database_name": "my-saas-edge",
"database_id": "<your D1 database id>",
"migrations_dir": "./drizzle/migrations/sqlite"
}
]Postgres 项目没有 d1_databases 块。它在 vars 下把 DATABASE_DIALECT 设为 postgres、DATABASE_ADAPTER 设为 hyperdrive,并包含:
"hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<your Hyperdrive id>" }]设置生产变量
D1 项目的 vars 里 APP_ENV 默认是 development,改成 production。再加上 SITE_URL,值为你的公网源地址。不要把密钥写进这个文件。
重新生成绑定类型
pnpm cf-typegen重新渲染会把现有的 wrangler.jsonc 移到一边
pnpm kernlift deploy-target cloudflare --dialect postgres 把 D1 项目改成 Hyperdrive 项目,做法是按模板重新渲染 wrangler.jsonc。现有文件连同其中的资源 id 会移到 .kernlift/previous-deploy/wrangler.jsonc,把桶名和 KV id 从那里抄到新文件。
迁移并部署
应用迁移
D1:
pnpm db:migrate:d1:remotePostgres 则在检出目录里直接迁移数据库。Hyperdrive 是 Worker 绑定,所以迁移用的是 Postgres URL 本身:
DATABASE_DIALECT=postgres DATABASE_URL='postgresql://USER:PASSWORD@HOST:5432/DB' pnpm db:migrate写入会话密钥
密钥要挂在已存在的 Worker 上,所以在首次部署之后写入。值从 .env.production 经标准输入读取:
grep '^BETTER_AUTH_SECRET=' .env.production | cut -d= -f2- | npx wrangler secret put BETTER_AUTH_SECRET
grep '^CONFIG_ENCRYPTION_KEY=' .env.production | cut -d= -f2- | npx wrangler secret put CONFIG_ENCRYPTION_KEY创建线上管理员
D1 在检出目录里执行引导脚本,--remote 通过 wrangler 连到已部署的数据库:
DATABASE_DIALECT=d1 SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin --remotePostgres 则指向生产数据库:
DATABASE_DIALECT=postgres DATABASE_URL='postgresql://USER:PASSWORD@HOST:5432/DB' SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin脚本从环境变量读取邮箱和密码,不接受通过参数传入。
使用 pnpm run deploy
不带 run 的 pnpm deploy 是 pnpm 自己的工作区命令,不是项目脚本。
加上 agent 容器
项目不含 agent 时跳过本节。agent 需要 Postgres,所以项目必须使用 Hyperdrive。pnpm kernlift deploy-target cloudflare --agent 渲染出带 containers 和 durable_objects 块的 wrangler.jsonc,并把 agent 密钥补进 .env.production。
写入 agent 密钥
grep '^AGENT_INTERNAL_SIGNING_SECRET=' .env.production | cut -d= -f2- | npx wrangler secret put AGENT_INTERNAL_SIGNING_SECRET
grep '^AGENT_RESOURCE_GRANT_SECRET=' .env.production | cut -d= -f2- | npx wrangler secret put AGENT_RESOURCE_GRANT_SECRETAGENT_DATABASE_URL 用同样的方式写入。它是直连的 Postgres URL。容器不能使用 Hyperdrive 绑定,所以直接连接同一个数据库。
让 agent 能回访 Worker
把 wrangler.jsonc 里 vars 下的 AGENT_WEB_INTERNAL_URL 设为 Worker 的公网 URL。agent 服务通过它回调 Web 应用。
再部署一次
pnpm build
pnpm run deployWrangler 用 apps/agent-service/Dockerfile 构建容器镜像。只运行一个实例,因为服务在内存里持有运行状态。
验证
pnpm run deploy打印 Worker 的 URL,站点可以在该地址打开。- 以管理员身份打开
/setup,第一行写明 Cloudflare 和所用数据库,会话密钥为就绪。 /admin/config/auth里的 基础 URL 是站点实际对外的地址。站点用的是另一个域名时,在那里改掉。- 定时任务在一两分钟内变为就绪。
wrangler.jsonc里的 Cron Trigger 每分钟执行一轮。 - 包含 agent 时,
/app/agent打开工作台。 - 在仓库里,
pnpm build之后的pnpm smoke:worker会用一次性的 D1 数据库运行构建出的 Worker,pnpm validate:deploy-targets检查渲染出的配置。
故障排查
EDGE_DB D1 binding is required when DATABASE_ADAPTER=d1
Worker 没有名为 EDGE_DB 的 D1 绑定。检查 wrangler.jsonc 里的 d1_databases 后重新部署。
DATABASE_ADAPTER=hyperdrive needs the HYPERDRIVE Worker binding.
wrangler.jsonc 里缺少 hyperdrive 条目,或其中仍是占位 id。填入真实的 Hyperdrive id 后重新部署。
Worker 因会话密钥错误拒绝启动
APP_ENV 不是 development,且缺少 BETTER_AUTH_SECRET。用上面的命令写入。
页面因缺少表而报错
迁移只在本地数据库上执行过。运行 pnpm db:migrate:d1:remote,或对 Postgres URL 运行 pnpm db:migrate。
定时任务一直未就绪
检查 wrangler.jsonc 是否保留 "triggers": { "crons": ["* * * * *"] },以及已部署的 Worker 是否列出了该触发器。