部署到 Fly.io

创建 Fly 应用,导入生成的密钥,部署 Node 镜像并执行迁移,创建线上管理员,并按需加上 agent 应用。

在 Fly.io 上,项目是一个由根目录 Dockerfile 构建的应用。数据库是挂在卷上的 SQLite 文件(单机),或你自备的 Postgres。agent 服务可选,作为 Fly 内网中的第二个应用运行,且只支持 Postgres。首次生产部署时使用本指南。

准备工作

  • fly CLI 已登录(fly auth login)。
  • deploy.config.json 中是 "platform": "fly"。执行 pnpm kernlift deploy-target fly 来设置,按需加上 --dialect、--agent 或 --region。见 deploy.config.json。
  • 项目根目录有 fly.toml 和 .env.production,这条命令会写出它们。
  • 使用 Postgres 时:一个数据库及其连接 URL,见使用 Postgres 与 Supabase。

示例中应用名为 my-saas,区域为 iad。请使用你 fly.toml 里的 app 和 primary_region。

创建应用并写入密钥

kernlift deploy-target fly 会按你的项目打印这些步骤。

设置公网地址

在 .env.production 里,把 SITE_URL 设为站点实际对外的地址。使用 Postgres 时,在同一个文件里加一行 DATABASE_URL=,值为连接 URL。

创建应用

fly apps create my-saas

使用 SQLite 时,还要创建存放数据库文件的卷:

fly volumes create data --app my-saas --region iad --size 1 --yes

导入密钥

值从 .env.production 经标准输入读取。SQLite:

grep -E '^(BETTER_AUTH_SECRET|CONFIG_ENCRYPTION_KEY|SITE_URL)=' .env.production | fly secrets import --app my-saas

Postgres 则把数据库 URL 一并导入:

grep -E '^(BETTER_AUTH_SECRET|CONFIG_ENCRYPTION_KEY|SITE_URL|DATABASE_URL)=' .env.production | fly secrets import --app my-saas

部署

部署 Web 应用

fly deploy

pnpm run deploy 执行的是同一条命令。Fly 构建根目录的 Dockerfile,并在新版本接收流量之前应用迁移。使用 Postgres 时,release_command 在临时机器上执行 node scripts/db/migrate-runtime.mjs。使用 SQLite 时,应用进程先迁移卷上的文件,再启动服务。

创建线上管理员

fly ssh console --app my-saas --pty -C "node .output/scripts/bootstrap-super-admin.mjs"

脚本在应用内部运行,针对它自己的数据库,并提示输入邮箱和密码。

保持一台机器在线

定时任务运行在 Web 进程里,所以 fly.toml 设置了 min_machines_running = 1。机器停止后,履约重试和 AI 任务轮询不再执行。使用 SQLite 时不要把应用扩到一台以上,因为数据库文件只属于一台机器。

加上 agent 应用

项目不含 agent 时跳过本节。"agent": true 时,项目里还有 fly.agent.toml,对应 my-saas-agent 应用;fly.toml 把 Web 应用指向 http://my-saas-agent.internal:3001。agent 应用没有对外服务,也不会在运行中途被自动停机。

创建 agent 应用并导入它的密钥

fly apps create my-saas-agent
grep -E '^(AGENT_INTERNAL_SIGNING_SECRET|AGENT_RESOURCE_GRANT_SECRET|DATABASE_URL)=' .env.production | fly secrets import --app my-saas-agent

把签名密钥给 Web 应用

grep -E '^AGENT_INTERNAL_SIGNING_SECRET=' .env.production | fly secrets import --app my-saas

部署 agent 服务

fly deploy -c fly.agent.toml

只运行一台机器,因为服务在内存里保存运行状态。

验证

  • fly deploy 打印应用地址,站点可以在该地址打开。
  • 以管理员身份打开 /setup,第一行写明 Fly.io 和所用数据库,会话密钥为就绪。
  • /admin/config/auth 里的 基础 URL 是站点实际对外的地址。站点用的是另一个域名时,在那里改掉。
  • 定时任务在一两分钟内变为就绪。
  • 包含 agent 时,/app/agent 打开工作台。
  • 在仓库里,pnpm build:node 之后的 pnpm smoke:node 检查你要发布的构建,pnpm validate:deploy-targets 检查渲染出的 fly.toml。

故障排查

部署在 release command 阶段失败

迁移连不上 Postgres。检查 DATABASE_URL 是否已导入应用,以及数据库是否接受来自 Fly 的连接。

应用因会话密钥错误拒绝启动

BETTER_AUTH_SECRET 没有导入。重新执行导入命令。

/setup 上定时任务一直未就绪

检查 fly.toml 是否保留 min_machines_running = 1。如果设置了 JOBS_IN_PROCESS=false,就必须由外部 cron 执行 pnpm jobs:run。

工作台提示未部署 agent 服务

Web 应用访问不到 my-saas-agent.internal:3001,或者两个应用里的 AGENT_INTERNAL_SIGNING_SECRET 不一致。用同一份 .env.production 给两个应用导入该密钥。

下一步