railway-service

Railway 服务管理

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

适用场景

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

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

对于 GitHub 仓库源： 使用 railway-new 技能创建空服务，然后使用 railway-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'
${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
  'mutation createService($input: ServiceCreateInput!) {
    serviceCreate(input: $input) { id name }
  }' \
  '{"input": {"projectId": "PROJECT_ID"}}'
SCRIPT

示例：使用镜像创建服务

bash <<'SCRIPT'
${CLAUDE_PLUGIN_ROOT}/skills/lib/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. 使用 railway-environment 技能通过暂存更改 API 配置源
3. 应用更改以触发部署

创建后：配置实例

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

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

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

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

检查服务状态

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'
${CLAUDE_PLUGIN_ROOT}/skills/lib/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'
${CLAUDE_PLUGIN_ROOT}/skills/lib/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	Emoji 或图片 URL（包括动态 GIF）

链接服务

切换当前目录已链接的服务：

railway service link

或直接指定：

railway service link <service-name>

可组合性

• 使用本地代码创建服务：使用 railway-new skill（负责脚手架搭建和创建）
• 配置服务：使用 railway-environment skill（变量、命令、镜像等）
• 删除服务：使用 railway-environment skill，并设置 isDeleted: true
• 应用更改：使用 railway-environment skill
• 查看日志：使用 railway-deployment skill
• 部署本地代码：使用 railway-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 镜像必须可访问（公开可用，或具有注册表凭据）。