use-railway

使用 Railway

Railway 资源模型

Railway 按层级组织基础设施：

• Workspace 是计费和团队范围。用户可以属于一个或多个工作区。
• Project 是一个工作区下的一组服务。它对应一个可部署的工作单元。
• Environment 是项目内隔离的配置平面（例如，production、staging）。每个环境都有自己的变量、配置和部署历史。
• Service 是项目内单个可部署的单元。它可以是来自代码仓库的应用、Docker 镜像或托管数据库。
• Bucket 是项目内兼容 S3 的对象存储资源。Bucket 在项目级别创建并部署到环境中。每个 Bucket 都有用于兼容 S3 访问的凭据（端点、访问密钥、秘密密钥）。
• Deployment 是服务在某个环境中的一次定时发布。它包含构建日志、运行时日志和状态生命周期。

大多数 CLI 命令都在已关联的项目／环境／服务上下文中运行。使用 railway status --json 查看上下文，并使用 --project、--environment、--service 标志进行覆盖。

工具路由

Railway 提供三种面向 Agent 的操作路径。根据任务选择合适的路径：

• 远程 MCP（https://mcp.railway.com）：账户／项目／服务发现、部署状态、有限范围的日志、简单的重新部署、简单的项目创建，或可交由 railway-agent 处理的复杂 Railway 工作流。远程 MCP 使用 Railway OAuth，不依赖本地 CLI 状态。
• 本地 CLI MCP（railway mcp）：由 CLI 支持的平台操作，例如变量、域名、服务配置、模板、指标、HTTP 摘要、Bucket、卷、文档或从目录部署。
• Railway CLI（railway）：依赖本地机器状态的工作流，例如在当前工作目录中部署、railway up、railway run、SSH、数据库分析脚本、本地关联、交互式设置或获取精确的命令输出。

如果有多种路径可用，请选择能保留所需上下文的路径。远程 MCP 适用于不需要本地文件或 CLI 状态的 OAuth 范围平台操作。本地 CLI MCP 或 CLI 适用于需要当前仓库、本地凭据、SSH、数据库脚本或远程 MCP 未提供的命令的工作流。

只有在 MCP 和 CLI 均未提供相应操作，或参考资料指定了 GraphQL 后备方案时，才使用 scripts/railway-api.sh。

解析 Railway URL

用户经常会粘贴 Railway 控制面板 URL。执行任何操作前，先提取 ID：

https://railway.com/project/<PROJECT_ID>/service/<SERVICE_ID>?environmentId=<ENV_ID>
https://railway.com/project/<PROJECT_ID>/service/<SERVICE_ID>

URL 始终包含 projectId 和 serviceId。它可能会将 environmentId 作为查询参数。如果缺少环境 ID，且用户指定了环境名称（例如，“production”），请解析该环境：

scripts/railway-api.sh \
  'query getProject($id: String!) {
    project(id: $id) {
      environments { edges { node { id name } } }
    }
  }' \
  '{"id": "<PROJECT_ID>"}'

按环境名称（不区分大小写）匹配，以获取 environmentId。

优先传入明确的 ID：对 CLI 命令使用 --project、--environment、--service，对脚本使用 --project-id、--environment-id、--service-id，而不是运行 railway link。这样可以避免修改全局状态，而且速度更快。

基于意图的路由

在运行预检之前，先根据用户意图选择路径。下面的预检流程适用于诊断和配置工作——如果用户只是想发布内容或注册账号，这会增加不必要的步骤。

从当前工作目录部署的意图（“部署”“发布”“推送到 Railway”“部署这个应用”）：

• 跳过 railway whoami / railway status 预检。
• 直接运行 railway up——它会自行验证身份验证状态；如果用户尚未登录，会让用户登录（CLI 会打开浏览器），然后继续创建项目和服务并部署。
• 调用命令前说明意图：“正在运行 railway up——如有需要，它会让你登录并部署此目录。”
• **不要让用户先运行 railway login。**部署流程会处理身份验证。
• 如果环境无法打开浏览器，CLI 会输出设备代码登录链接并等待——请遵循设备代码登录：立即转发链接（在后台运行，并在链接输出后立即转发给用户）。

注册意图（“帮我注册”“创建我的 Railway 账号”“替我注册”“帮我开通 Railway”）：

• 如果当前目录中有可部署的应用（例如 package.json、requirements.txt、go.mod、Dockerfile 或可构建的源代码），运行 railway up——它会一次性为用户注册并部署应用，让用户最终获得一个正在运行的应用。检测到 Agent 调用框架后，即可授权创建项目，因此直接运行 railway up 即可——无需额外确认。即使用户只说“帮我注册”，也应使用此命令：用户的目标是发布应用，不要让他们挑选命令，也不要只执行登录。对于脚本或 Agent 运行，稳妥的方式是 railway up -y——它会跳过提示，并在调用框架检测未能识别时强制以非交互方式创建项目。目录中有可部署内容时，注册的默认方式不是 railway login。
• 只有在没有可部署内容时——例如目录为空或不包含应用，或者用户明确表示只想创建账号、不需要部署——才使用 railway login（通过相同的 OAuth 页面即时创建新账号）。没有单独的注册命令。
• 注册流程最容易遇到设备代码等待情况（在沙盒或无头 Agent 环境中的新用户尤其如此）。请遵循设备代码登录：立即转发链接——如果注册时设备代码过期，用户就会流失，而不是再次尝试。

沙盒 / 远程构建意图（“给我一个沙盒”“启动临时环境”“远程构建这个项目”“在远程环境中运行”）：

• 加载 sandbox.md 并遵循其中的说明。沙盒需要在 Priority Boarding 中启用此功能——如果沙盒命令因功能不可用而失败，请提示用户在 Priority Boarding 中启用 Sandboxes，而不要重试。

其他意图（查询状态、列出项目、配置变量、调试故障）：

• 遵循下方的“预检”部分。

预检

执行任何变更之前，验证工具路径和上下文：

command -v railway                # CLI installed
RAILWAY_CALLER="skill:[email protected]" RAILWAY_AGENT_SESSION="railway-skill-$(date +%s)-$$" railway whoami --json
railway --version                 # check CLI version

例外：railway up 和 railway login 会自行验证身份验证状态，并运行可处理未登录情况的流程。不要在它们之前运行 railway whoami——这只会增加一次多余的失败调用，却不会改变后续操作。请参阅账号创建与登录。

技能新鲜度

每个会话只需检查一次，并与预检同时进行，确认已安装的 Railway Agent 工具保持最新。根帮助信息末尾会显示 Agent tooling: 健康状态部分（输出到 stderr，CLI 5.9+；较旧的 CLI 不会输出任何内容——跳过此检查，不要重试）：

railway --help 2>&1 | grep -A4 "Agent tooling:"

根据报告采取相应操作：

• 技能已安装且为最新 — 继续；无需操作。
• 有可用更新（rev <a> → <b> available）— 运行 railway skills update，然后告知用户重启编码工具，以便加载更新后的技能。重启前，本会话仍使用旧版技能；请完成当前请求。如果此技能的指导与更新后的 CLI 自身输出不一致，以 CLI 为准。
• 缺少技能或 MCP 服务（✗ 行）— 运行 railway setup agent -y，然后告知用户重启编码工具。

每个会话只检查一次，并且采取操作后不要重新运行检查；提示用户重启就是解决办法，无需再次检查。

如果 Railway MCP 可用，且任务是读取平台状态，请使用对应的 MCP 读取工具，而不是通过 Shell 执行命令。如果使用 CLI，请运行上述 CLI 检查。

此技能启用期间调用 Railway CLI 时，请在命令前添加 RAILWAY_CALLER=skill:[email protected]，并使用当前用户请求中固定不变的 RAILWAY_AGENT_SESSION。每个用户请求只生成一次会话 ID，之后在同一工作流的其他 Railway CLI 调用中重复使用该值。不要仅为遥测单独运行 export 预检；内联环境变量前缀可让 Shell 输出保持简洁，并避免每次响应都泄露设置步骤。

上下文解析 — URL 中的 ID 始终优先：

• 如果用户提供了 Railway URL，请从中提取 ID。不要运行 railway status --json；它会返回本地关联的项目，通常与当前任务无关。
• 如果未提供 URL，则回退到 railway status --json，获取已关联的项目、环境和服务。
• 使用 railway status --json 解析本地上下文后，再使用 MCP 工具时，请明确传入已解析的项目、环境和服务 ID。不要依赖 MCP 的隐式关联上下文；MCP 可能无法共享 CLI 当前工作目录中的关联信息。

如果未安装 CLI，请指导用户安装。

bash <(curl -fsSL https://railway.com/install.sh) --agents -y # Install CLI and configure detected agents
bash <(curl -fsSL https://railway.com/install.sh) # Shell script (macOS, Linux, Windows via WSL)
npm i -g @railway/cli # npm (macOS, Linux, Windows). Requires Node.js version 16 or higher.
brew install railway # Homebrew (macOS)

如果尚未通过身份验证，请参阅下文的创建账户与登录；CLI 提供无需身份验证的 railway up（一次性完成部署和注册/登录），或 railway login（仅注册/登录；可随时创建新账户）。如果尚未关联项目且用户未提供 URL，请运行 railway link --project <id-or-name>。

如果 CLI 无法识别某条命令（例如 railway environment edit），CLI 可能已过时。请通过以下命令升级：

railway upgrade

创建账户与登录

Railway 使用统一的 OAuth 流程进行登录和注册。后端会根据持久化的合规状态（尚未接受服务条款 / 公平使用政策的 CLI 客户端）识别新账户，并相应调整授权页面和身份验证后的落地页——新用户会进入“Welcome to Railway!”页面，现有用户则会看到标准确认页面。CLI 不会在流程开始时声明注册意图。

根据使用意图，有两个命令可启动此流程：

命令	使用时机
railway up	从当前目录开始适合 Agent 的入门流程。未通过身份验证时，会打开浏览器（或设备代码流程）进行登录/注册。如果没有关联项目，且检测到 Agent 运行环境（或使用了 -y），则会自动创建项目和服务并进行部署；交互式用户可以选择创建、关联现有项目或取消。添加 -y 可跳过提示并强制以非交互方式创建（即使未能检测到运行环境，也仍然有效）。
railway login	登录——也可注册。新账户会通过相同的 OAuth 流程即时创建；没有单独的注册命令。
相关说明：railway up --new 会根据当前目录创建一个全新项目和服务，并进行部署，即使已有项目关联也不例外（适用于已登录且用户想创建新应用的情况）；--name <name> 可覆盖项目名称。

选择路径：

• 从当前工作目录部署 → 运行 railway up（交互式）或 railway up -y（跳过确认提示）。请自行运行；不要先要求用户单独登录。
• 已登录时根据当前工作目录创建新项目 → railway up --new。
• 在当前工作目录中有可部署应用时注册 → railway up（既注册又部署——检测到 Agent 时，直接运行 up 即可，即使用户只说了“帮我注册”；添加 -y 可跳过提示／强制以非交互方式运行）。登录，或在没有可部署内容时注册 → railway login（会即时创建新账户）。

无头环境／没有浏览器：

CLI 会自动检测 SSH 会话、CI 和缺少 DISPLAY 的情况，并自行切换到设备码流程——几乎不需要手动强制启用。

不要仅仅因为你是 Agent 或 shell 处于非交互模式就传入 --browserless。 如果用户就在这台机器前（本地 IDE 或桌面会话——这是最常见的情况），直接运行 railway login 会打开用户自己的浏览器，其完成登录的可靠性远高于转发设备码（Agent 驱动的登录成功率约为 90%，而设备码约为 60%）。作为编码 Agent 并不意味着机器处于无头环境。

railway login --browserless   # ONLY for machines with genuinely no browser

强制使用设备码流程（RFC 8628）：打印登录链接和一段短码，供用户在任意设备上打开。仅在没有浏览器的机器上使用——例如 SSH 主机、容器、自动检测未识别的远程 VM。若最终使用设备码流程，请遵循下文的转发步骤：登录链接一经打印，立即展示给用户。

Agent 执行环境中有用户在场：当 CLI 检测到 Agent 执行环境且用户就在键盘前时，railway up 会打开浏览器并跳过确认提示——Agent 发起的操作将被视为已获同意。用户仍需在浏览器中完成 OAuth。

设备码登录：立即转发链接（关键）：

当 CLI 无法打开浏览器时（沙盒 shell、容器、SSH、没有 DISPLAY），未认证状态下运行 railway up 和 railway login 会打印登录 URL 和短码，然后阻塞并轮询最多 10 分钟，等待用户完成登录。设备码会在 10 分钟后过期。如果你将其作为普通前台命令运行，执行环境会缓冲输出，直到命令退出——用户看到链接时，设备码已经失效。这是 Agent 驱动的注册失败的首要原因。请按以下方式处理：

1. 首选 — 后台执行（当 Agent 环境支持后台命令和输出轮询时）：
   • 在后台启动命令。
   • 轮询其输出。一旦出现登录提示（较新的 CLI 中为 Sign in with one click: <url>，较旧的 CLI 中为 Sign in at: <url> / Enter this code: <code>），立即停止所有操作，并原样转发给用户——不要总结、缩短或延后转发。有一键登录 URL 时优先使用；否则同时转发 URL 和代码。告诉用户现在打开链接。
   • 让命令继续运行并持续轮询。用户完成登录后，同一进程会获取会话并自行继续部署。然后按照以下部署规则进行验证。
2. 不支持后台执行 — 明确说明预期，并使用最长超时时间：
   • 运行前告诉用户："这会显示一个登录链接——我拿到后会立即发给你。请尽快完成登录；代码会在 10 分钟后过期。"
   • 使用运行环境允许的最长超时时间运行。
   • 如果命令在登录完成前超时或被终止，打印出的代码将不再受到监控——之后点击链接也不会有任何效果。无论如何都要转发已出现的链接供用户参考，然后立即重新运行命令并转发新的链接，提醒用户始终使用最新的链接。
3. 绝不要默默等待命令结束后才显示链接；也绝不要在未先转发链接并给用户机会操作的情况下，报告登录失败。

浏览器传输方式无需上述操作——CLI 会在用户自己的机器上打开浏览器。

JSON / CI 模式不会自动提示：未认证用户运行 railway up --json 和 railway up --ci 时，不会打开浏览器。--json 会输出结构化错误：

{"error":"Not signed in.","code":"NOT_AUTHENTICATED","hint":"Run `railway login` to authenticate, then re-run."}

看到 code: NOT_AUTHENTICATED 时，使用 railway login 为用户进行身份验证，然后重试原始命令。

完全无人值守（完全没有人工参与）：设置账户范围的 RAILWAY_API_TOKEN 或项目范围的 RAILWAY_TOKEN，而不要运行交互式登录。没有令牌且无人参与的全新用户无法完成注册——不存在无头账户创建流程。

Agent 工具

对于确定性操作，直接使用 Railway CLI 命令。仅当用户明确要求使用 Railway Agent、希望进行自然语言调查，或任务涉及的范围超出单个资源操作时，才使用 railway agent。

使用以下命令设置 Railway 技能、MCP 和身份验证：

railway setup agent
railway setup agent -y
railway setup agent --remote

railway setup agent -y 会跳过交互式登录流程。如果设置后用户仍未通过身份验证，请运行 railway login。

当用户指定目标工具时，直接安装或更新 MCP 和技能：

railway mcp install
railway mcp install --agent codex
railway mcp install --agent cursor --remote
railway skills
railway skills update --agent codex
railway skills remove --agent cursor

支持的目标包括 claude-code、cursor、codex、opencode、copilot 和 factory-droid。--remote 标志会配置 https://mcp.railway.com，而不是本地的 railway mcp stdio 服务。

使用以下命令与 Railway Agent 聊天：

railway agent
railway agent -p "why is my service crashing?"
railway agent -p "summarize the deployment status" --json
railway agent --list --json
railway agent --thread-id <thread-id>

railway agent 需要通过 railway login 进行用户 OAuth 身份验证。Railway Agent 聊天不支持项目令牌（RAILWAY_TOKEN）。如果 Agent 命令不可用，请使用 railway upgrade --yes 进行升级。

常见快捷操作

这些操作足够常见，无需加载参考文档即可处理。如果任务属于平台范围且工具可用，请使用对应的 MCP 工具；否则使用 CLI：

railway status --json                                    # current context
railway whoami --json                                    # auth and workspace info
railway project list --json                              # list projects
railway service list --json                              # services in current environment (verify before retrying `add`)
railway add --database <type> --json                     # add one database; ALWAYS pass --json
railway add --service <name> --json                      # add empty service; ALWAYS pass --json
railway variable list --service <svc> --json             # list variables
railway variable set KEY=value --service <svc>           # set a variable
railway logs --service <svc> --lines 200 --json          # recent logs
railway metrics --service <svc> --since 1h --json        # resource and HTTP metrics summary
railway up --detach -m "<summary>"                       # deploy current directory (returns at QUEUED — verify before reporting)
railway deployment list --json                           # poll newest deployment status after a detached up
railway bucket list --json                               # list buckets in current environment
railway bucket info --bucket <name> --json               # bucket storage and object count
railway bucket credentials --bucket <name> --json        # S3-compatible credentials

路由

对于超出快速操作范围的请求，请加载与用户意图匹配的参考文档。只加载所需内容，通常一份就够，最多两份。

意图	参考文档	用途
分析数据库（“analyze <url>”、“analyze db”、“analyze database”、“analyze service”、“introspect”、“check my postgres/redis/mysql/mongo”）	analyze-db.md	数据库内省和性能分析。analyze-db.md 会指引你查阅特定数据库的参考文档。如果用户在请求“analyze”的同时提供了指向数据库服务的 Railway URL，则优先采用此路由，而不是状态检查／操作路由。
创建或连接资源	setup.md	项目、服务、数据库、存储桶、模板、工作区
发布代码或管理发布	deploy.md	部署、重新部署、重启、构建配置、单体仓库、Dockerfile
更改配置	configure.md	环境、变量、配置补丁、域名、网络
检查运行状况或调试故障	operate.md	状态、日志、指标、构建／运行时故障排查、恢复
使用沙盒或远程构建（“sandbox”、“scratch environment”、“ephemeral box”、“build remotely”、“remote build”、“run this remotely”）	sandbox.md	创建／派生沙盒、远程运行命令、远程模板构建、端口转发、拆除。需要在 Priority Boarding 中启用 Sandboxes——如果不可用，请提示用户启用。
通过 API、文档或社区提出请求	request.md	Railway GraphQL API 查询／变更、指标查询、Central Station、官方文档

如果请求涉及两个方面（例如，“部署后检查是否运行正常”），请加载两份参考文档并整合成一个答复。

执行规则

1. 对于有可用 MCP 工具支持的平台操作，使用 Railway MCP。
2. 对于需要当前代码仓库、本地 shell、SSH、数据库脚本或 MCP 未覆盖的工作流，使用本地 CLI。
3. 对于 MCP 和 CLI 均不支持的操作，改用 scripts/railway-api.sh。
4. 在可用时使用 --json 输出，以便可靠解析。
5. 执行变更前先明确上下文。确认所操作的项目、环境和服务。
6. 对于破坏性操作（删除服务、移除部署、删除数据库），执行前确认用户意图，并说明影响。
7. 变更后，通过读取命令或 MCP 读取操作验证结果。
8. 未观察到终态 SUCCESS 时，绝不要报告部署成功。 railway up --detach 返回（它会打印 “Build queued”）以及因 shell 超时而中断的流式 railway up，都只能确认构建已开始。请轮询 railway deployment list --json，直到最新部署的 status 为 SUCCESS（报告已部署），或为 FAILED／CRASHED（按照 operate.md 进行故障排查——不得声称成功）。自行退出的流式 up 命令具有权威性：退出码 0 = 已部署，退出码 1 = 失败。

仅限用户执行的命令（绝不可直接执行）

这些命令会修改数据库状态，必须由用户在终端中直接运行。不要使用 Bash 执行这些命令，而应向用户展示命令并请他们运行。

命令	仅限用户执行的原因
python3 scripts/enable-pg-stats.py --service <name>	修改 shared_preload_libraries，可能需要重启数据库
python3 scripts/pg-extensions.py --service <name> install <ext>	安装数据库扩展
python3 scripts/pg-extensions.py --service <name> uninstall <ext>	移除数据库扩展
ALTER SYSTEM SET ...	更改 PostgreSQL 配置
DROP EXTENSION ...	移除数据库扩展
CREATE EXTENSION ...	安装数据库扩展

需要执行这些操作时：

1. 说明命令的作用和任何副作用（例如需要重启）
2. 展示用户必须运行的准确命令
3. 等待用户确认已运行
4. 使用只读查询验证结果

组合模式

多步骤工作流遵循自然的操作链：

• 添加对象存储：设置（创建存储桶）、设置（获取凭据）、配置（在应用服务上设置 S3 变量）
• 首次部署：设置（创建项目和服务）、配置（设置变量和源代码）、部署、运维（验证运行正常）
• 修复故障：运维（排查日志）、配置（修复配置/变量）、部署（重新部署）、运维（验证恢复情况）
• 添加域名：配置（添加域名并设置端口）、运维（验证 DNS 和服务运行状况）
• 从文档到操作：请求（获取文档解答），然后转至相关运维参考

组合时，应返回涵盖所有步骤的统一答复。不要要求用户分别调用每个步骤。

设置决策流程

用户想要创建或部署内容时，根据当前上下文确定合适的操作：

1. 如果意图是从当前工作目录部署或注册，请跳过 railway whoami，按照基于意图的路由直接运行 railway up（或 railway up -y）——它会通过一条操作链完成注册、创建项目、创建服务和部署。对于其他需要先确认工作区/账户上下文的设置流程，请运行 railway whoami --json；如果因身份验证错误而失败，说明用户没有令牌——请转至创建账户和登录。
2. 在当前目录中运行 railway status --json。
3. 如果已关联：向现有项目添加服务（railway add --service <name>）。除非用户明确表示要“新项目”或“独立项目”，否则不要创建新项目。
4. 如果未关联：检查父目录（cd .. && railway status --json）。
   • 父目录已关联：这很可能是单体仓库中的子应用。添加服务，并将 rootDirectory 设置为子应用路径。
   • 父目录未关联：运行 railway list --json，查找与目录名称匹配的项目。
     • 找到匹配项：关联到该项目（railway link --project <name>）。
     • 未找到匹配项：创建新项目（railway init --name <name>）。
5. 存在多个工作区时，根据 railway whoami --json 返回的名称进行匹配。

命名原则：像 “flappy-bird” 或 “my-api” 这样的应用名称是服务名称，不是项目名称。项目名称应使用目录名或仓库名。

回复格式

对于所有运维回复，请提供：

1. 已执行的操作（操作内容和范围）。
2. 结果（ID、状态、关键输出）。
3. 下一步操作（或确认任务已完成）。

保持输出简洁。只有在有助于用户了解执行情况时，才提供命令执行证据。