templates

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Templates

模板

Search and deploy services from Railway's template marketplace.

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

When to Use

使用场景

User asks to "add Postgres", "add Redis", "add a database"
User asks to "add Ghost", "add Strapi", "add n8n", or any other service
User wants to find templates for a use case (e.g., "CMS", "storage", "monitoring")
User asks "what templates are available?"
User wants to deploy a pre-configured service

用户要求“添加Postgres”、“添加Redis”、“添加数据库”
用户要求“添加Ghost”、“添加Strapi”、“添加n8n”或其他任何服务
用户想要查找特定用例的模板（例如：“CMS”、“存储”、“监控”）
用户询问“有哪些可用模板？”
用户想要部署预配置的服务

Common Template Codes

常用模板代码

Category	Template	Code
Databases	PostgreSQL	`postgres`
	Redis	`redis`
	MySQL	`mysql`
	MongoDB	`mongodb`
CMS	Ghost	`ghost`
	Strapi	`strapi`
Storage	Minio	`minio`
Automation	n8n	`n8n`
Monitoring	Uptime Kuma	`uptime-kuma`

For other templates, use the search query below.

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

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

Prerequisites

前提条件

Get project context:

bash

railway status --json

Extract:

```
id
```
- project ID
```
environments.edges[0].node.id
```
- environment ID

Get workspace ID:

bash

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

获取项目上下文：

bash

railway status --json

提取：

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

获取工作区ID：

bash

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

Search Templates

搜索模板

List available templates with optional filters:

bash

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

列出可用模板，可添加可选过滤器：

bash

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

Arguments

参数

Argument	Type	Description
`first`	Int	Number of results (max ~100)
`verified`	Boolean	Only verified templates
`recommended`	Boolean	Only recommended templates

参数	类型	描述
`first`	整数	结果数量（最大约100）
`verified`	布尔值	仅显示已验证模板
`recommended`	布尔值	仅显示推荐模板

Rate Limit

请求限制

10 requests per minute. Don't spam searches.

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

Get Template Details

获取模板详情

Fetch a specific template by code:

bash

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

Returns:

```
id
```
- template ID (needed for deployment)
```
serializedConfig
```
- service configuration (needed for deployment)

通过代码获取特定模板：

bash

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

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

Deploy Template

部署模板

Step 1: Fetch Template

步骤1：获取模板

bash

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

bash

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

Step 2: Deploy to Project

步骤2：部署到项目

bash

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

Important:

serializedConfig

is the exact JSON object from the template query, not a string.

bash

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对象，而非字符串。

Connecting Services

连接服务

After deploying a template, connect other services using reference variables.

For complete variable syntax and wiring patterns, see variables.md.

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

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

Pattern

模式

${{ServiceName.VARIABLE_NAME}}

${{ServiceName.VARIABLE_NAME}}

Common Database Variables

常用数据库变量

Service	Connection Variable
PostgreSQL (Postgres)	`${{Postgres.DATABASE_URL}}`
Redis	`${{Redis.REDIS_URL}}`
MySQL	`${{MySQL.MYSQL_URL}}`
MongoDB	`${{MongoDB.MONGO_URL}}`

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

Backend vs Frontend

后端 vs 前端

Backend services can use private URLs (internal network):

${{Postgres.DATABASE_URL}}

Frontend applications run in the browser and cannot access Railway's private network. Options:

Use public URL variables (e.g.,
```
${{MongoDB.MONGO_PUBLIC_URL}}
```
)
Better: Route through a backend API

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

${{Postgres.DATABASE_URL}}

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

使用公共URL变量（例如
```
${{MongoDB.MONGO_PUBLIC_URL}}
```
）
更佳方案：通过后端API路由

Example: Add PostgreSQL

示例：添加PostgreSQL

bash

bash <<'SCRIPT'

bash

bash <<'SCRIPT'

1. Get context

1. 获取上下文

railway status --json

→ project.id = "proj-123", environment.id = "env-456"

2. Get workspace ID

2. 获取工作区ID

scripts/railway-api.sh
'query { project(id: "proj-123") { workspaceId } }' '{}'

→ workspaceId = "ws-789"

3. Fetch Postgres template

3. 获取Postgres模板

scripts/railway-api.sh
'query { template(code: "postgres") { id serializedConfig } }' '{}'

→ id = "template-abc", serializedConfig = {...}

4. Deploy

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

undefined

undefined

Example: Search for CMS Templates

示例：搜索CMS模板

bash

bash <<'SCRIPT'

bash

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

筛选“CMS”分类的结果或搜索描述内容

SCRIPT

undefined

SCRIPT

undefined

What Gets Created

创建内容说明

Templates typically create:

Service with pre-configured image/source
Environment variables (connection strings, secrets)
Volume for persistent data (databases)
TCP proxy for external access (where needed)

模板通常会创建：

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

Response

响应

Successful deployment returns:

json

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

部署成功后返回：

json

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

Error Handling

错误处理

Error	Cause	Solution
Template not found	Invalid code	Search templates or check spelling
Rate limit exceeded	Too many searches	Wait 1 minute, then retry
Permission denied	User lacks access	Need DEVELOPER role or higher
Project not found	Invalid project ID	Run `railway status --json`

错误	原因	解决方案
模板未找到	代码无效	搜索模板或检查拼写
请求限制超出	搜索过于频繁	等待1分钟后重试
权限不足	用户无访问权限	需要DEVELOPER或更高角色
项目未找到	项目ID无效	运行 `railway status --json`

Composability

可组合性

Connect services: Use
```
environment
```
skill to add variable references
View deployed service: Use
```
service
```
skill
Check logs: Use
```
deployment
```
skill
Add domains: Use
```
domain
```
skill

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