部署项目

从四个平台里选一个,写入生成的密钥,迁移、部署,并创建线上管理员。

本教程把你在本地跑起来的项目放到公网地址上。一个项目只部署到一个平台: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 服务适用场景
CloudflareD1,或经 Hyperdrive 连接的 PostgresCloudflare 容器,仅限 Postgres想用 Worker 以及 D1、R2、KV 绑定
Fly.io挂卷的 SQLite,或 Postgres内网中的第二个应用,仅限 Postgres想让容器靠近用户,并自备 Postgres
RailwayPostgres第二个服务想让平台把 Postgres 和应用一起建好
Docker挂卷的 SQLite,或自带的 Postgrescompose 服务,仅限 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 进程。

下一步