部署到 Railway

由 .railway/railway.ts 创建 Railway 项目、服务和 Postgres,写入生成的密钥,部署,并创建线上管理员。

在 Railway 上,项目是一个由根目录 Dockerfile 构建的 web 服务和一个 Postgres 数据库,两者都声明在 .railway/railway.ts 里。agent 服务可选,作为名为 agent 的第二个服务运行。首次生产部署时使用本指南。

准备工作

  • railway CLI 已登录(railway login)。
  • deploy.config.json 中是 "platform": "railway"。执行 pnpm kernlift deploy-target railway 来设置,需要 agent 服务时加上 --agent。见 deploy.config.json。
  • 项目根目录有 .railway/railway.ts 和 .env.production,这条命令会写出它们。

Railway 项目使用 Postgres。不需要事先准备数据库。配置里声明了一个,并把它的 DATABASE_URL 传给各个服务。

创建项目

kernlift deploy-target railway 会按你的项目打印这两步。

创建 Railway 项目

railway init --name my-saas

应用配置

railway config apply --yes

它创建 web 服务、Postgres 数据库,以及包含 agent 时的 agent 服务。railway config plan 只展示变更,不执行。

写入密钥并部署

设置公网地址

在 .env.production 里,把 SITE_URL 设为 web 服务的公网地址:你自己的域名,或 Railway 分配的域名。

给 web 服务设置变量

每个值都从 .env.production 读取,不需要在命令行里输入。

railway variables --service web --set "BETTER_AUTH_SECRET=$(grep '^BETTER_AUTH_SECRET=' .env.production | cut -d= -f2-)"
railway variables --service web --set "CONFIG_ENCRYPTION_KEY=$(grep '^CONFIG_ENCRYPTION_KEY=' .env.production | cut -d= -f2-)"
railway variables --service web --set "SITE_URL=$(grep '^SITE_URL=' .env.production | cut -d= -f2-)"

密钥只用这种方式设置,不要写进 .railway/railway.ts。

部署

railway up

pnpm run deploy 执行的是同一条命令。web 服务的 pre-deploy 步骤执行 node scripts/db/migrate-runtime.mjs,所以迁移在新版本接收流量之前完成。

创建线上管理员

在 web 服务里打开 shell:

railway ssh --service web

然后运行镜像自带的脚本,它会提示输入邮箱和密码:

node .output/scripts/bootstrap-super-admin.mjs

定时任务需要 web 服务在运行

定时任务运行在 web 服务里。服务不在运行时,履约重试和 AI 任务轮询都不会执行,直到服务恢复运行。

加上 agent 服务

项目不含 agent 时跳过本节。"agent": true 时,.railway/railway.ts 声明一个单副本的 agent 服务,由 apps/agent-service/Dockerfile 构建,并把 web 服务指向 http://agent.railway.internal:3001。

设置 agent 密钥

railway variables --service web --set "AGENT_INTERNAL_SIGNING_SECRET=$(grep '^AGENT_INTERNAL_SIGNING_SECRET=' .env.production | cut -d= -f2-)"
railway variables --service agent --set "AGENT_INTERNAL_SIGNING_SECRET=$(grep '^AGENT_INTERNAL_SIGNING_SECRET=' .env.production | cut -d= -f2-)"
railway variables --service agent --set "AGENT_RESOURCE_GRANT_SECRET=$(grep '^AGENT_RESOURCE_GRANT_SECRET=' .env.production | cut -d= -f2-)"

部署

railway up

验证

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

故障排查

web 服务因会话密钥错误拒绝启动

web 服务上没有设置 BETTER_AUTH_SECRET。重新执行 railway variables 命令并再次部署。

OAuth 登录或邮件链接指向了错误的地址

/admin/config/auth 里的 基础 URL 与公网地址不一致。在那里改正即可,不需要重新部署。

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

检查 web 服务是否在运行。如果设置了 JOBS_IN_PROCESS=false,就必须由外部 cron 执行 pnpm jobs:run。

TypeScript 在 .railway/railway.ts 里报错

该文件以 @ts-nocheck 开头,因为它由 railway CLI 检查,本项目不检查它。保留这一行。

下一步