部署到 Fly.io
创建 Fly 应用,导入生成的密钥,部署 Node 镜像并执行迁移,创建线上管理员,并按需加上 agent 应用。
在 Fly.io 上,项目是一个由根目录 Dockerfile 构建的应用。数据库是挂在卷上的 SQLite 文件(单机),或你自备的 Postgres。agent 服务可选,作为 Fly 内网中的第二个应用运行,且只支持 Postgres。首次生产部署时使用本指南。
准备工作
flyCLI 已登录(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-saasPostgres 则把数据库 URL 一并导入:
grep -E '^(BETTER_AUTH_SECRET|CONFIG_ENCRYPTION_KEY|SITE_URL|DATABASE_URL)=' .env.production | fly secrets import --app my-saas部署
部署 Web 应用
fly deploypnpm 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验证
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 给两个应用导入该密钥。