templates

用途

Templates 是 Railway 的模板市场技能，用于搜索并部署 Railway 模板市场中的服务。当用户提出「添加 Postgres」「添加 Redis」「添加数据库」「添加 Ghost」「添加 Strapi」「添加 n8n」或其他服务，或想按用途（如 CMS、存储、监控）查找模板、询问「有哪些可用模板」、希望部署预配置服务时，应使用本技能。

主要能力

• 搜索模板：列出可用模板，支持按数量、是否已验证、是否推荐进行过滤。
• 获取模板详情：按模板代码获取模板的 id、名称、描述和 serializedConfig。
• 部署模板：将模板部署到指定项目、环境和 workspace。
• 连接服务：部署后通过引用变量连接其他服务。

常见模板代码：

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

其他模板可使用搜索查询获取。

使用方式

前置条件

获取项目上下文：

railway status --json

提取：

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

获取 workspace 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 私有网络。可选方案：使用公共 URL 变量（如 ${{MongoDB.MONGO_PUBLIC_URL}}）；更好的做法是通过后端 API 路由。

示例：添加 PostgreSQL

bash <<'SCRIPT'
# 1. 获取上下文
railway status --json
# → project.id = "proj-123", environment.id = "env-456"

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

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

# 4. 部署
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'
# 搜索已验证模板
scripts/railway-api.sh \
  'query {
    templates(first: 50, verified: true) {
      edges {
        node { name code description category }
      }
    }
  }' '{}'
# 按 "CMS" 类别或描述过滤结果
SCRIPT

适用场景

• 需要快速为项目添加数据库（Postgres、Redis、MySQL、MongoDB）。
• 需要部署 CMS（Ghost、Strapi）、自动化工具（n8n）、存储（Minio）、监控（Uptime Kuma）等预配置服务。
• 需要按用途查找可用模板。
• 需要将模板部署到指定 Railway 项目与环境，并连接其他服务。

限制与错误处理

模板通常创建：预配置镜像/源的服务、环境变量（连接字符串、密钥）、持久化数据卷（数据库）、外部访问的 TCP 代理（按需）。

成功部署返回：

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

错误处理：

错误	原因	解决方案
Template not found	代码无效	搜索模板或检查拼写
Rate limit exceeded	搜索过于频繁	等待 1 分钟后重试
Permission denied	用户缺少权限	需要 DEVELOPER 角色或更高
Project not found	项目 ID 无效	运行 railway status --json

可组合性：

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

关于收费、价格、平台支持范围等具体信息，资料中暂未提供。