mcpField
G
genesis-railway

genesis-railway

github.com/lwlee2608云与 DevOps141 次安装5 天前更新
代码仓库

关于 genesis-railway

用于将 Genesis monorepo 部署到 Railway 的技能，面向包含 Go API、React 网页应用和 Postgres 的项目。它规定通过 Railway MCP 工具修改基础设施，并验证配置与部署结果。

主要功能

  1. 01按依赖顺序创建 Railway 服务
  2. 02发现并配置环境变量
  3. 03设置构建参数与健康检查
  4. 04验证部署和服务端点
  5. 05提供 Postgres 模板与 pgvector 指引

适用场景

  1. 01部署包含 API、网页和 Postgres 的 Genesis monorepo
  2. 02配置 Railway 服务及内部网络
  3. 03排查构建或健康检查失败

MCP 相关

需要 Railway MCP 服务工具来执行 Railway 变更、配置和验证。Railway CLI 仅用于登录、关联项目、初始化项目及添加 Postgres 模板。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/lwlee2608/genesis --skill genesis-railway

安装后在 Claude Code 中输入/genesis-railway确认已加载。

详细介绍

genesis-railway

使用 Railway MCP 工具将 genesis 单体仓库部署到 Railway。预期布局：services/<app>-server（带有 Dockerfile 和 /health 的 Go API）、services/<app>-web（由 nginx 提供服务的 React 应用，带有 Dockerfile），以及 Postgres。

Railway project: <app>
├── Postgres        # Railway Postgres template
├── <app>-server    # builds services/<app>-server/Dockerfile
└── <app>-web       # builds services/<app>-web/Dockerfile, gets the public domain
        web ──▶ server ──▶ Postgres   (private networking)

前提条件

Railway MCP 服务（mcp__railway__* 工具）。如果这些工具不可用，请停止并告知用户——不要退而猜测 CLI 命令。

Railway CLI（npm i -g @railway/cli 或 brew install railway），仅用于执行 railway login、railway init、railway add、railway link，以及读取解析后的变量。

规则

  1. 每项 Railway 变更都使用 MCP 工具。 设置、变量、卷、源和域名都通过 mcp__railway__* 处理。CLI 仅用于登录、链接，以及执行 railway add --database postgres。

  2. 切勿添加 railway.json / railway.toml。 配置即代码已弃用，并将于 2026-12-01 停止工作；且没有 MCP 工具会写入这些文件。所有构建/部署设置都通过 update-service 在服务上设置（步骤 3）。其后继方案 .railway/railway.ts（railway config pull/plan/apply，CLI ≥ 5）不在此范围内。

  3. 按依赖顺序创建服务。 被引用服务存在之前，${{Service.VAR}} 引用的值为空：先 Postgres，再 server，最后 web。

  4. 创建任何内容前，先找出必需变量。 在 cmd/<app>/main.go 中搜索会执行 os.Exit 的配置检查；每项检查都需要一个变量。配置键映射为环境变量时，将 . 替换为 _（http.port → HTTP_PORT）。

  5. 使用 Railway Postgres 模板。 该模板自带卷、Database 选项卡、备份，以及 DATABASE_URL / PG* 变量。只有在迁移中运行 CREATE EXTENSION vector 时，才改用 pgvector/pgvector 镜像服务（见 pgvector 例外）——模板镜像不包含该扩展。

  6. 先解析项目和环境 ID。 如果仓库根目录已链接，读取 ~/.railway/config.json（.projects["<abs repo path>"].project）。否则，运行 list-projects，或在仓库根目录运行 railway init --name <app>。使用 list-services 解析目标环境；配置和验证时使用明确的项目、环境和服务 ID。

步骤

  1. 创建服务——在已链接的仓库根目录运行 railway add --database postgres（远程 MCP 没有模板工具；CLI 会将服务命名为 Postgres），然后运行 create-service 创建 <app>-server，再创建 <app>-web（不带镜像）。
  2. 设置变量——通过 set-variables 并设置 skipDeploys: true：
    • Server：PORT=8080、HTTP_PORT=${{PORT}}（两者都要设置——server 读取 HTTP_PORT；如果不设置，健康检查会探测错误的端口）、DB_URL=${{Postgres.DATABASE_URL}}?sslmode=disable、LOG_LEVEL=info，以及规则 4 中找到的所有变量（生成密钥并告知用户）。
    • Web：BACKEND_URL=http://${{<app>-server.RAILWAY_PRIVATE_DOMAIN}}:8080
  3. 设置配置——在 server 和 web 上通过 update-service 设置：rootDirectory: services/<app>-{server,web}、dockerfilePath: Dockerfile、watchPatterns: ["services/<app>-{server,web}/**"]（相对于仓库根目录）、restartPolicyType: ON_FAILURE、restartPolicyMaxRetries: 1。Server 还需设置：healthcheckPath: /health、healthcheckTimeout: 60（仅限启动；如需增加，说明理由）。
  4. 读回确认——通过 get-service-config 读取两个服务的实时 config；通过 list-variables 确认步骤 3 的设置以及 server 的 PORT=HTTP_PORT=8080。如果值被隐藏，请运行 railway variables --json --project <project-id> --environment <environment-id> --service <server-id>，但不要暴露密钥。修复不匹配项并重新检查；如果无法验证，则停止。
  5. 设置源——完成步骤 2–4 后，先对 server、再对 web 运行 connect-service-source：repo: <owner>/<repo>、branch: main。这会启动构建并启用 GitHub 自动部署。从响应或限定范围的 list-deployments 记录已触发的部署 ID，并根据源和触发时间进行匹配；如果存在歧义，应报告歧义，不要猜测。
  6. 域名——在 web 上运行 generate-domain。
  7. 链接子目录，以便 CLI 能在这些目录中正常工作（cd 时使用绝对路径）： 
    cd <abs>/services/<app>-server && railway link -p <app> -e production -s <app>-server
cd <abs>/services/<app>-web    && railway link -p <app> -e production -s <app>-web

其他基础设施

如果 docker-compose.yml 中除了 Postgres 还有更多基础设施（Redis、MinIO 等），请从官方 Railway 模板创建每项服务，而不是使用普通镜像，并且要在服务器之前创建，以便引用其变量。仅当没有可用模板时，才使用带有 image: 的 create-service。

pgvector 例外情况

替代步骤 1 中的 Postgres，并补充模板原本会提供的内容：

  • 使用 image: pgvector/pgvector:<tag from docker-compose.yml> 通过 create-service 创建 Postgres。
  • 使用 set-variables（skipDeploys: true）设置：POSTGRES_DB=<app_underscore>、POSTGRES_USER=postgres、POSTGRES_PASSWORD=<openssl rand -hex 24>、PGDATA=/var/lib/postgresql/data/pgdata（卷根目录非空）、PGHOST=${{RAILWAY_PRIVATE_DOMAIN}}、PGPORT=5432、PGUSER=${{POSTGRES_USER}}、PGPASSWORD=${{POSTGRES_PASSWORD}}、PGDATABASE=${{POSTGRES_DB}}（设置这组 PG* 变量会启用仪表板的 Database 选项卡）、DATABASE_URL=postgres://${{POSTGRES_USER}}:${{POSTGRES_PASSWORD}}@${{RAILWAY_PRIVATE_DOMAIN}}:5432/${{POSTGRES_DB}}。
  • 在 Postgres 上使用 create-volume，设置 mountPath: /var/lib/postgresql/data。
  • 仪表板中不会有 Database 选项卡；只有模板才会提供该选项卡。

验证流程

  1. 对每个记录的 ID 轮询限定范围的 list-deployments，直到状态为 SUCCESS；绝不能用其他部署替代。如果状态为 FAILED/CRASHED，使用 types: ["build", "deploy"] 获取其 get-logs 并报告原因。如果操作受阻或轮询停止，则报告 ID、状态和后续操作，并注明尚未验证。使用 environment-status 检查 Postgres。
  2. curl --fail --max-time 10 https://<web domain>/health 必须返回预期的后端健康响应；HTTP 错误或响应正文不符合预期都表示验证失败。
  3. 对于代理故障，通过 MCP 或限定范围的 CLI 检查解析后的 BACKEND_URL。如果为 http://:8080，则对 web 执行 redeploy，并使用新的部署 ID 重复验证。

常见错误

  • 只设置 PORT。 服务器读取的是 HTTP_PORT；未设置该变量时，健康检查会探测错误的端口，导致每次部署都失败。
  • 在 pgvector 镜像服务上未设置 PGDATA。 卷根目录非空，因此 Postgres 必须使用子目录才能初始化。
  • 在设置变量/配置前连接源代码。 首次构建会立即启动，并因配置缺失而运行失败。
  • 模板可用时仍使用普通镜像服务。 这样只会白白失去 Database 选项卡和备份功能。
  • 在 watchPatterns 或服务名称中使用占位符 project-00。 ${{project-00-server.RAILWAY_PRIVATE_DOMAIN}} 之类的引用会解析为空。

评论

支持 Markdown