service

服务管理

检查状态、更新属性和创建高级服务。

适用场景

• 用户询问服务状态、运行状况或部署情况
• 用户询问“我的服务已部署吗？”
• 用户想要重命名服务或更改服务图标
• 用户想要关联其他服务
• 用户想要将 Docker 镜像部署为新服务（高级）

注意： 如果要使用本地代码创建服务（常见情况），请优先使用 new 技能，它会一并处理项目设置、脚手架搭建和服务创建。

对于 GitHub 仓库源： 使用 new 技能创建空服务，然后使用 environment 技能通过分阶段更改 API 配置 source.repo。

创建服务

通过 GraphQL API 创建新服务。没有对应的 CLI 命令。

获取上下文

railway status --json

提取：

• project.id - 用于创建服务
• environment.id - 用于暂存实例配置

创建服务的 Mutation

mutation serviceCreate($input: ServiceCreateInput!) {
  serviceCreate(input: $input) {
    id
    name
  }
}

ServiceCreateInput 字段

字段	类型	描述
projectId	String!	项目 ID（必填）
name	String	服务名称（省略时自动生成）
source.image	String	Docker 镜像（例如，nginx:latest）
source.repo	String	GitHub 仓库（例如，user/repo）
branch	String	仓库源的 Git 分支
environmentId	String	如果已设置且为分支环境，则仅在该环境中创建

示例：创建空服务

bash <<'SCRIPT'
scripts/railway-api.sh \
  'mutation createService($input: ServiceCreateInput!) {
    serviceCreate(input: $input) { id name }
  }' \
  '{"input": {"projectId": "PROJECT_ID"}}'
SCRIPT

示例：使用镜像创建服务

bash <<'SCRIPT'
scripts/railway-api.sh \
  'mutation createService($input: ServiceCreateInput!) {
    serviceCreate(input: $input) { id name }
  }' \
  '{"input": {"projectId": "PROJECT_ID", "name": "my-service", "source": {"image": "nginx:latest"}}}'
SCRIPT

连接 GitHub 仓库

不要使用带有 source.repo 的 serviceCreate - 请改用分阶段更改 API。

流程：

1. 创建空服务：serviceCreate(input: {projectId: "...", name: "my-service"})
2. 使用 environment 技能通过分阶段更改 API 配置源
3. 应用更改以触发部署

创建后：配置实例

使用 environment 技能配置服务实例：

{
  "services": {
    "<serviceId>": {
      "isCreated": true,
      "source": { "image": "nginx:latest" },
      "variables": {
        "PORT": { "value": "8080" }
      }
    }
  }
}

重要： 新服务实例始终要包含 isCreated: true。

然后使用 environment 技能应用更改并部署。

变量引用请参阅 reference/variables.md。

检查服务状态

railway service status --json

返回已关联服务当前的部署状态。

部署历史记录

railway deployment list --json --limit 5

展示状态

显示：

• 服务：名称和当前状态
• 最新部署：状态（SUCCESS、FAILED、DEPLOYING、CRASHED 等）
• 部署时间：当前部署开始生效的时间
• 最近部署：最近 3-5 次部署的状态和时间戳

部署状态

状态	含义
SUCCESS	已部署并正在运行
FAILED	构建或部署失败
DEPLOYING	正在部署
BUILDING	正在构建
CRASHED	运行时崩溃
REMOVED	部署已移除

更新服务

通过 GraphQL API 更新服务名称或图标。

获取服务 ID

railway status --json

从响应中提取 service.id。

更新名称

bash <<'SCRIPT'
scripts/railway-api.sh \
  'mutation updateService($id: String!, $input: ServiceUpdateInput!) {
    serviceUpdate(id: $id, input: $input) { id name }
  }' \
  '{"id": "SERVICE_ID", "input": {"name": "new-name"}}'
SCRIPT

更新图标

图标可以是图片 URL 或动态 GIF。

类型	示例
图片 URL	"icon": "https://example.com/logo.png"
动态 GIF	"icon": "https://example.com/animated.gif"
Devicons	"icon": "https://devicons.railway.app/github"

Railway Devicons： 通过 https://devicons.railway.app/{query} 查询常用开发者图标（例如，github、postgres、redis、nodejs）。可在 https://devicons.railway.app 浏览所有图标

bash <<'SCRIPT'
scripts/railway-api.sh \
  'mutation updateService($id: String!, $input: ServiceUpdateInput!) {
    serviceUpdate(id: $id, input: $input) { id icon }
  }' \
  '{"id": "SERVICE_ID", "input": {"icon": "https://devicons.railway.app/github"}}'
SCRIPT

ServiceUpdateInput 字段

字段	类型	描述
name	String	服务名称
icon	String	表情符号或图片 URL（包括动态 GIF）

关联服务

为当前目录切换已关联的服务：

railway service link

或者直接指定：

railway service link <service-name>

组合能力

• 使用本地代码创建服务：使用 new skill（负责脚手架搭建和创建）
• 配置服务：使用 environment skill（变量、命令、镜像等）
• 删除服务：使用 environment skill，并设置 isDeleted: true
• 应用更改：使用 environment skill
• 查看日志：使用 deployment skill
• 部署本地代码：使用 deploy skill

错误处理

未关联服务

No service linked. Run `railway service link` to link a service.

没有部署

Service exists but has no deployments yet. Deploy with `railway up`.

未找到服务

Service "foo" not found. Check available services with `railway status`.

未找到项目

用户可能不在已关联的项目中。请检查 railway status。

权限被拒绝

用户至少需要 DEVELOPER 角色才能创建服务。

无效镜像

Docker 镜像必须可访问（公开可用或已提供注册表凭据）。