templates

模板

从 Railway 的模板市场中搜索并部署服务。

适用场景

• 用户要求“添加 Postgres”“添加 Redis”“添加数据库”
• 用户要求“添加 Ghost”“添加 Strapi”“添加 n8n”或其他服务
• 用户想查找适用于某种场景的模板（例如“CMS”“存储”“监控”）
• 用户询问“有哪些可用模板？”
• 用户想部署预配置的服务

常见模板代码

类别	模板	代码
数据库	PostgreSQL	postgres
	Redis	redis
	MySQL	mysql
	MongoDB	mongodb
CMS	Ghost	ghost
	Strapi	strapi
存储	Minio	minio
自动化	n8n	n8n
监控	Uptime Kuma	uptime-kuma

其他模板请使用下方的搜索查询。

前置条件

获取项目上下文：

railway status --json

提取：

• id - 项目 ID
• environments.edges[0].node.id - 环境 ID

获取工作区 ID：

bash <<'SCRIPT'
scripts/railway-api.sh \
  'query getWorkspace($projectId: String!) {
    project(id: $projectId) { workspaceId }
  }' \
  '{"projectId": "PROJECT_ID"}'
SCRIPT

搜索模板

使用可选筛选条件列出可用模板：

bash <<'SCRIPT'
scripts/railway-api.sh \
  'query templates($first: Int, $verified: Boolean) {
    templates(first: $first, verified: $verified) {
      edges {
        node {
          name
          code
          description
          category
        }
      }
    }
  }' \
  '{"first": 20, "verified": true}'
SCRIPT

参数

参数	类型	描述
first	Int	结果数量（最多约 100 个）
verified	Boolean	仅显示已验证的模板
recommended	Boolean	仅显示推荐的模板

速率限制

每分钟 10 次请求。请勿频繁搜索。

获取模板详情

按代码获取特定模板：

bash <<'SCRIPT'
scripts/railway-api.sh \
  'query template($code: String!) {
    template(code: $code) {
      id
      name
      description
      serializedConfig
    }
  }' \
  '{"code": "postgres"}'
SCRIPT

返回：

• id - 模板 ID（部署时需要）
• serializedConfig - 服务配置（部署时需要）

部署模板

步骤 1：获取模板

bash <<'SCRIPT'
scripts/railway-api.sh \
  'query template($code: String!) {
    template(code: $code) {
      id
      serializedConfig
    }
  }' \
  '{"code": "postgres"}'
SCRIPT

步骤 2：部署到项目

bash <<'SCRIPT'
scripts/railway-api.sh \
  'mutation deployTemplate($input: TemplateDeployV2Input!) {
    templateDeployV2(input: $input) {
      projectId
      workflowId
    }
  }' \
  '{
    "input": {
      "templateId": "TEMPLATE_ID_FROM_STEP_1",
      "serializedConfig": SERIALIZED_CONFIG_FROM_STEP_1,
      "projectId": "PROJECT_ID",
      "environmentId": "ENVIRONMENT_ID",
      "workspaceId": "WORKSPACE_ID"
    }
  }'
SCRIPT

重要：serializedConfig 是模板查询返回的原始 JSON 对象，而不是字符串。

连接服务

部署模板后，使用引用变量连接其他服务。

完整的变量语法和连接模式请参阅 variables.md。

模式

${{ServiceName.VARIABLE_NAME}}

常见数据库变量

服务	连接变量
PostgreSQL (Postgres)	${{Postgres.DATABASE_URL}}
Redis	${{Redis.REDIS_URL}}
MySQL	${{MySQL.MYSQL_URL}}
MongoDB	${{MongoDB.MONGO_URL}}

后端与前端

后端服务可以使用私有 URL（内部网络）：

${{Postgres.DATABASE_URL}}

前端应用运行在浏览器中，无法访问 Railway 的私有网络。可选方案：

1. 使用公共 URL 变量（例如 ${{MongoDB.MONGO_PUBLIC_URL}}）
2. 更好的做法：通过后端 API 转发

示例：添加 PostgreSQL

bash <<'SCRIPT'
# 1. Get context
railway status --json
# → project.id = "proj-123", environment.id = "env-456"

# 2. Get workspace ID
scripts/railway-api.sh \
  'query { project(id: "proj-123") { workspaceId } }' '{}'
# → workspaceId = "ws-789"

# 3. Fetch Postgres template
scripts/railway-api.sh \
  'query { template(code: "postgres") { id serializedConfig } }' '{}'
# → id = "template-abc", serializedConfig = {...}

# 4. Deploy
scripts/railway-api.sh \
  'mutation deploy($input: TemplateDeployV2Input!) {
    templateDeployV2(input: $input) { projectId workflowId }
  }' \
  '{"input": {
    "templateId": "template-abc",
    "serializedConfig": {...},
    "projectId": "proj-123",
    "environmentId": "env-456",
    "workspaceId": "ws-789"
  }}'
SCRIPT

示例：搜索 CMS 模板

bash <<'SCRIPT'
# Search verified templates
scripts/railway-api.sh \
  'query {
    templates(first: 50, verified: true) {
      edges {
        node { name code description category }
      }
    }
  }' '{}'
# Filter results for "CMS" category or search descriptions
SCRIPT

创建的内容

模板通常会创建：

• 带预配置镜像/源的服务
• 环境变量（连接字符串、密钥）
• 用于持久化数据的卷（数据库）
• 用于外部访问的 TCP 代理（按需）

响应

部署成功后会返回：

{
  "data": {
    "templateDeployV2": {
      "projectId": "proj-123",
      "workflowId": "deployTemplate/project/proj-123/xxx"
    }
  }
}

错误处理

错误	原因	解决方案
未找到模板	代码无效	搜索模板或检查拼写
超出速率限制	搜索次数过多	等待 1 分钟后重试
权限被拒绝	用户无访问权限	需要 DEVELOPER 角色或更高权限
未找到项目	项目 ID 无效	运行 railway status --json

组合使用

• 连接服务：使用 environment 技能添加变量引用
• 查看已部署的服务：使用 service 技能
• 查看日志：使用 deployment 技能
• 添加域名：使用 domain 技能