部署项目
从四个平台里选一个,写入生成的密钥,迁移、部署,并创建线上管理员。
本教程把你在本地跑起来的项目放到公网地址上。一个项目只部署到一个平台:Cloudflare、Fly.io、Railway
或 Docker 主机。选择记录在 deploy.config.json 里,仓库中只保留该平台的配置文件。本页是最短路径,
每个平台另有完整指南。
准备工作
- 项目能在本地构建:
pnpm build无错误结束。 - 目标平台的 CLI 已安装并登录:
wrangler、fly、railway,或 Docker Compose。 - 在 Cloudflare 或 Fly.io 上使用 Postgres 时:一个 Postgres 数据库及其连接 URL。Railway 和 Docker 会自己创建。
选择平台
| 平台 | 数据库 | agent 服务 | 适用场景 |
|---|---|---|---|
| Cloudflare | D1,或经 Hyperdrive 连接的 Postgres | Cloudflare 容器,仅限 Postgres | 想用 Worker 以及 D1、R2、KV 绑定 |
| Fly.io | 挂卷的 SQLite,或 Postgres | 内网中的第二个应用,仅限 Postgres | 想让容器靠近用户,并自备 Postgres |
| Railway | Postgres | 第二个服务 | 想让平台把 Postgres 和应用一起建好 |
| Docker | 挂卷的 SQLite,或自带的 Postgres | compose 服务,仅限 Postgres | 自己管理服务器 |
Cloudflare 使用 Worker 构建;其余三个使用 Node 构建,由根目录的 Dockerfile 打包。agent 服务在任何
平台都是可选的,并且始终需要 Postgres。这张表背后的模型见部署模型。
部署
确认或切换平台
仓库在 deploy.config.json 里记录了部署平台。查看当前选择:
cat deploy.config.json对你要用的平台运行一次 deploy-target,即使它就是已记录的那个:刚克隆的仓库没有 .env.production,
这条命令会生成它。该命令写入该平台的文件,把其他平台的文件移到 .kernlift/previous-deploy/,
补全 .env.production,并打印剩下的步骤。它不创建任何远程资源,也不搬数据。
pnpm kernlift deploy-target fly --no-agent
pnpm cf-typegen可用选项见 部署配置参考。
检查生产环境的值
.env.production 里是生成好的会话密钥和公网地址。它被 git 忽略,绝不提交。把其中的
SITE_URL 改成站点实际对外的地址。下面的命令都从这个文件经标准输入读取密钥,
值不会出现在命令行上。
在所选平台上迁移并部署
pnpm db:migrate:d1:remote
pnpm build
pnpm run deploy
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在此之前,wrangler.jsonc 里的 D1、R2、KV 必须是真实 id。完整指南:
部署到 Cloudflare Workers。
使用 pnpm run deploy
不带 run 的 pnpm deploy 是 pnpm 自己的工作区命令,不是项目脚本。
创建线上管理员
线上数据库不是你本地那个,需要单独创建管理员。在 Fly.io、Railway 和 Docker 上,镜像里带有一个脚本, 会提示输入邮箱和密码:
fly ssh console --app my-saas --pty -C "node .output/scripts/bootstrap-super-admin.mjs"
docker compose --env-file .env.production exec web node .output/scripts/bootstrap-super-admin.mjs在 Railway 上,用 railway ssh --service web 打开 shell,再执行
node .output/scripts/bootstrap-super-admin.mjs。在 Cloudflare D1 上,在已登录 wrangler 的检出目录
里执行:
DATABASE_DIALECT=d1 SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin --remote验证
打开线上地址的 /setup,以管理员身份登录。然后打开 /admin/config/auth,检查 基础 URL;站点用的是
另一个域名时,在那里改掉。
- 第一行写明平台、数据库以及是否包含 agent 服务。
- 会话密钥为就绪。
- 定时任务在首次部署后一两分钟内变为就绪。
清单读取的是线上数据库,所以从这里开始配置需要的服务商,先配邮件投递。存储在
/admin/config/storage 配置;在 Cloudflare 上也可以使用运行时检测到的存储桶绑定。
故障排查
应用因会话密钥错误拒绝启动
APP_ENV 不是 development,而 BETTER_AUTH_SECRET 没有写到平台上。用所在平台的命令重新写入。
OAuth 登录或邮件链接指向了错误的地址
OAuth 回调和邮件链接使用 /admin/config/auth 里的 基础 URL。在那里改正即可,约 30 秒内生效,
不需要重新部署。
/setup 上定时任务一直未就绪
没有任何东西在触发任务轮次。该项会指出所在平台的开关:Cloudflare 上是 wrangler.jsonc 里的
Cron Trigger,其它平台上是一个在运行的 Web 进程。