部署到 Railway
由 .railway/railway.ts 创建 Railway 项目、服务和 Postgres,写入生成的密钥,部署,并创建线上管理员。
在 Railway 上,项目是一个由根目录 Dockerfile 构建的 web 服务和一个 Postgres 数据库,两者都声明在 .railway/railway.ts 里。agent 服务可选,作为名为 agent 的第二个服务运行。首次生产部署时使用本指南。
准备工作
railwayCLI 已登录(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 uppnpm 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 检查,本项目不检查它。保留这一行。