use-railway

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Use Railway

使用Railway

Railway resource model

Railway资源模型

Railway organizes infrastructure in a hierarchy:

Workspace is the billing and team scope. A user belongs to one or more workspaces.
Project is a collection of services under one workspace. It maps to one deployable unit of work.
Environment is an isolated configuration plane inside a project (for example,
```
production
```
,
```
staging
```
). Each environment has its own variables, config, and deployment history.
Service is a single deployable unit inside a project. It can be an app from a repo, a Docker image, or a managed database.
Deployment is a point-in-time release of a service in an environment. It has build logs, runtime logs, and a status lifecycle.

Most CLI commands operate on the linked project/environment/service context. Use

railway status --json

to see the context, and

--project

--environment

--service

flags to override.

Railway采用层级结构组织基础设施：

Workspace为计费和团队范围，一个用户可隶属于一个或多个Workspace。
Project是一个Workspace下的服务集合，对应一个可部署的工作单元。
Environment是项目内的隔离配置平面（例如
```
production
```
、
```
staging
```
），每个环境有独立的变量、配置和部署历史。
Service是项目内的单个可部署单元，可以是代码仓库中的应用、Docker镜像或托管数据库。
Deployment是服务在某个环境中的特定时间点发布版本，包含构建日志、运行时日志和状态生命周期。

大多数CLI命令基于已关联的project/environment/service上下文执行。使用

railway status --json

查看当前上下文，也可通过

--project

、

--environment

、

--service

标志覆盖默认上下文。

Preflight

前置检查

Before any mutation, verify context:

bash

command -v railway                # CLI installed
railway whoami --json             # authenticated
railway --version                 # check CLI version
railway status --json             # linked project/environment/service

If the CLI is missing, guide the user to install it.

bash

bash <(curl -fsSL cli.new) # Shell script (macOS, Linux, Windows via WSL)
brew install railway # Homebrew (macOS)
npm i -g @railway/cli # npm (macOS, Linux, Windows). Requires Node.js version 16 or higher.

If not authenticated, run

railway login

. If not linked, run

railway link --project <id-or-name>

If a command is not recognized (for example,

railway environment edit

), the CLI may be outdated. Upgrade with:

bash

railway upgrade

执行任何变更操作前，请验证上下文：

bash

command -v railway                # 检查CLI是否已安装
railway whoami --json             # 检查认证状态
railway --version                 # 查看CLI版本
railway status --json             # 查看已关联的project/environment/service

若未安装CLI，请引导用户执行以下命令安装：

bash

bash <(curl -fsSL cli.new) # Shell脚本（适用于macOS、Linux、Windows via WSL）
brew install railway # Homebrew（适用于macOS）
npm i -g @railway/cli # npm（适用于macOS、Linux、Windows），要求Node.js版本16或更高

若未完成认证，执行

railway login

。若未关联项目，执行

railway link --project <id-or-name>

。

若命令不被识别（例如

railway environment edit

），可能是CLI版本过旧，执行以下命令升级：

bash

railway upgrade

Common quick operations

常用快速操作

These are frequent enough to handle without loading a reference:

bash

railway status --json                                    # current context
railway whoami --json                                    # auth and workspace info
railway project list --json                              # list projects
railway service status --all --json                      # all services in current context
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 up --detach -m "<summary>"                       # deploy current directory

以下是高频操作，无需查阅参考文档即可执行：

bash

railway status --json                                    # 查看当前上下文
railway whoami --json                                    # 查看认证及Workspace信息
railway project list --json                              # 列出所有项目
railway service status --all --json                      # 查看当前上下文内的所有服务
railway variable list --service <svc> --json             # 列出变量
railway variable set KEY=value --service <svc>           # 设置变量
railway logs --service <svc> --lines 200 --json          # 查看近期日志
railway up --detach -m "<summary>"                       # 部署当前目录

Routing

操作路由

For anything beyond quick operations, load the reference that matches the user's intent. Load only what you need, one reference is usually enough, two at most.

Intent	Reference	Use for
Create or connect resources	setup.md	Projects, services, databases, templates, workspaces
Ship code or manage releases	deploy.md	Deploy, redeploy, restart, build config, monorepo, Dockerfile
Change configuration	configure.md	Environments, variables, config patches, domains, networking
Check health or debug failures	operate.md	Status, logs, metrics, build/runtime triage, recovery
Request from API, docs, or community	request.md	Railway GraphQL API queries/mutations, metrics queries, Central Station, official docs

If the request spans two areas (for example, "deploy and then check if it's healthy"), load both references and compose one response.

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

意图	参考文档	适用场景
创建或关联资源	setup.md	项目、服务、数据库、模板、Workspace
代码发布或版本管理	deploy.md	部署、重新部署、重启、构建配置、单体仓库、Dockerfile
修改配置	configure.md	环境、变量、配置补丁、域名、网络
健康检查或故障排查	operate.md	状态、日志、指标、构建/运行时问题诊断、恢复
API、文档或社区请求	request.md	Railway GraphQL API查询/变更、指标查询、Central Station、官方文档

若请求涉及多个领域（例如“部署后检查健康状态”），请加载对应的多份参考文档，并整合为一个统一的响应。

Execution rules

执行规则

Prefer Railway CLI. Fall back to
```
scripts/railway-api.sh
```
for operations the CLI doesn't expose.
Use
```
--json
```
output where available for reliable parsing.
Resolve context before mutation. Know which project, environment, and service you're acting on.
For destructive actions (delete service, remove deployment, drop database), confirm intent and state impact before executing.
After mutations, verify the result with a read-back command.

优先使用Railway CLI。对于CLI未支持的操作，可使用
```
scripts/railway-api.sh
```
作为替代方案。
尽可能使用
```
--json
```
输出格式，以确保解析可靠性。
执行变更操作前先确认上下文，明确当前操作的project、environment和service。
对于破坏性操作（删除服务、移除部署、删除数据库），需先确认用户意图和操作影响，再执行。
变更操作完成后，通过读取类命令验证执行结果。

Composition patterns

组合流程模式

Multi-step workflows follow natural chains:

First deploy: setup (create project + service), configure (set variables and source), deploy, operate (verify healthy)
Fix a failure: operate (triage logs), configure (fix config/variables), deploy (redeploy), operate (verify recovery)
Add a domain: configure (add domain + set port), operate (verify DNS and service health)
Docs to action: request (fetch docs answer), route to the relevant operational reference

When composing, return one unified response covering all steps. Don't ask the user to invoke each step separately.

多步骤工作流遵循自然执行链条：

首次部署：配置（创建项目+服务）、设置（配置变量和源码）、部署、运维（验证健康状态）
故障修复：运维（诊断日志）、设置（修复配置/变量）、部署（重新部署）、运维（验证恢复状态）
添加域名：设置（添加域名+配置端口）、运维（验证DNS和服务健康状态）
文档转操作：请求（获取文档答案）、路由至相关操作参考文档

整合流程时，请返回一个包含所有步骤的统一响应，不要让用户单独触发每个步骤。

Setup decision flow

配置决策流程

When the user wants to create or deploy something, determine the right action from current context:

Run
```
railway status --json
```
in the current directory.
If linked: add a service to the existing project (
```
railway add --service <name>
```
). Do not create a new project unless the user explicitly says "new project" or "separate project".
If not linked: check the parent directory (
```
cd .. && railway status --json
```
).
- Parent linked: this is likely a monorepo sub-app. Add a service and set
```
rootDirectory
```
  to the sub-app path.
- Parent not linked: run
```
railway list --json
```
  and look for a project matching the directory name.
  - Match found: link to it (
```
railway link --project <name>
```
    ).
  - No match: create a new project (
```
railway init --name <name>
```
    ).
When multiple workspaces exist, match by name from
```
railway whoami --json
```
.

Naming heuristic: app names like "flappy-bird" or "my-api" are service names, not project names. Use the directory or repo name for the project.

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

在当前目录执行
```
railway status --json
```
。
已关联项目：为现有项目添加服务（
```
railway add --service <name>
```
）。除非用户明确要求“新项目”或“独立项目”，否则不要创建新项目。
未关联项目：检查父目录（
```
cd .. && railway status --json
```
）。
- 父目录已关联：这很可能是单体仓库中的子应用。添加服务并将
```
rootDirectory
```
  设置为子应用路径。
- 父目录未关联：执行
```
railway list --json
```
  ，查找与当前目录名称匹配的项目。
  - 找到匹配项：关联该项目（
```
railway link --project <name>
```
    ）。
  - 未找到匹配项：创建新项目（
```
railway init --name <name>
```
    ）。
当存在多个Workspace时，根据
```
railway whoami --json
```
中的名称进行匹配。

命名规则：类似“flappy-bird”或“my-api”的名称是服务名，而非项目名。项目名应使用目录或仓库名称。

Response format

响应格式

For all operational responses, return:

What was done (action and scope).
The result (IDs, status, key output).
What to do next (or confirmation that the task is complete).

Keep output concise. Include command evidence only when it helps the user understand what happened.

所有操作类响应需包含以下内容：

已执行操作（动作和范围）。
执行结果（ID、状态、关键输出）。
下一步操作（或任务完成确认）。

响应内容需简洁，仅在帮助用户理解操作过程时才包含命令执行证据。