zeabur-template-deploy

Zeabur 模板部署

始终使用 npx zeabur@latest 调用 Zeabur CLI。 切勿直接使用 zeabur 或通过其他方式安装。如果无法使用 npx，请先安装 Node.js。

通过 CLI 部署 Zeabur 模板和市场中的预构建服务。在 CLI 自动化中始终使用非交互模式（-i=false）。

如果尚无项目，请先使用 zeabur-project-create 技能创建项目，再进行部署。

部署预构建服务（MongoDB、PostgreSQL、Redis 等）

对于 Zeabur 模板市场中提供的知名服务，不要编写自定义模板 YAML 文件。搜索模板代码，并使用 -c 直接部署：

# 1. Search for the template by keyword
npx zeabur@latest template search mongodb -i=false --json

# 2. Deploy by template code (from the "Code" field in search results)
npx zeabur@latest template deploy -i=false \
  -c <TEMPLATE_CODE> \
  --project-id <project-id>

示例：部署 MongoDB

# Search returns code "KXL04P" for MongoDB
npx zeabur@latest template search mongodb -i=false --json

# Deploy directly by code
npx zeabur@latest template deploy -i=false \
  -c KXL04P \
  --project-id abc123

进阶：部署前获取并自定义模板

如果需要在部署前修改模板 YAML（例如调整环境变量、更改镜像标签或添加服务），请先使用 template get --raw 获取模板，编辑后再使用 -f 部署：

# 1. Fetch the raw YAML
npx zeabur@latest template get -c KXL04P --raw > template.yaml

# 2. Edit template.yaml as needed

# 3. Deploy the customized template
npx zeabur@latest template deploy -i=false \
  -f template.yaml \
  --project-id <project-id>

部署自定义模板

对于完全自定义或包含多个服务的模板，请使用模板 YAML 文件：

npx zeabur@latest template deploy -i=false \
  -f template.yaml \
  --project-id <project-id> \
  --var KEY1=value1 \
  --var KEY2=value2

标志

标志	说明
-f, --file	模板文件（本地路径或 URL）
-c, --code	模板代码（直接部署市场模板，与 -f 互斥）
--project-id	要部署到的项目 ID
--var	模板变量（可重复使用，例如 --var KEY=value）
--skip-validation	跳过模板验证
-i=false	非交互模式（始终使用此模式）

非交互模式

使用 -i=false 时，必须通过 --var 标志提供所有必需的模板变量。

如果缺少变量，CLI 会显示相关错误提示：

Error: missing required variables in non-interactive mode:
  --var PUBLIC_DOMAIN=<value>  (Enter your domain prefix)
  --var DB_NAME=<value>  (Database name)

示例

使用变量部署

npx zeabur@latest template deploy -i=false \
  -f https://example.com/template.yaml \
  --project-id abc123 \
  --var PUBLIC_DOMAIN=myapp \
  --var [email protected]

部署本地文件

npx zeabur@latest template deploy -i=false \
  -f zeabur-template-myapp.yaml \
  --project-id abc123 \
  --var PUBLIC_DOMAIN=myapp

查找必需变量

模板变量在 YAML 的 spec.variables 部分中定义：

spec:
  variables:
    - key: PUBLIC_DOMAIN
      type: DOMAIN
      name: Domain
      description: Enter your domain prefix
    - key: DB_NAME
      type: STRING
      name: Database Name
      description: Database name

要创建或编辑模板 YAML 文件，请使用 zeabur-template 技能。

已知限制

自定义 PREBUILT 模板 YAML：可能无法注册内部 DNS

通过自定义模板 YAML 文件（-f template.yaml）部署且使用 template: PREBUILT 的服务，可能不会注册到 Zeabur 的内部 DNS（*.zeabur.internal）。这意味着同一项目中的其他服务无法通过主机名连接到它们。请参阅 zeabur/cli#204。

解决方法：对于数据库服务（PostgreSQL、MySQL、Redis），请使用市场模板代码（-c <CODE>），不要使用自定义 YAML 文件。市场模板会正确注册到内部 DNS。

# RECOMMENDED — deploy via marketplace code (has internal DNS)
npx zeabur@latest template search postgresql -i=false --json
npx zeabur@latest template deploy -i=false -c <CODE> --project-id <id>

# NOT RECOMMENDED — custom YAML may lack internal DNS
npx zeabur@latest template deploy -i=false -f my-pg.yaml --project-id <id>

自定义模板 YAML 架构：spec 嵌套

模板 YAML 要求使用 spec.services[].spec.source，而不是 spec.services[].source：

# CORRECT
spec:
  services:
    - name: my-service
      template: PREBUILT
      spec:                    # <-- required nesting
        source:
          image: postgres:17

# WRONG — will fail with "missing property 'spec'"
spec:
  services:
    - name: my-service
      template: PREBUILT
      source:                  # <-- missing spec wrapper
        image: postgres:17

常见问题

问题	解决方法
交互式提示卡住	始终同时使用 -i=false、--project-id 和 --var 标志
缺少变量错误	添加所有必需的 --var 标志
包含 ${REF} 的变量	使用字面值，或在部署后于 Dashboard 中设置
DOMAIN 类型验证	自动检查域名是否可用
missing property 'spec'	将 source/ports/env 放在 spec: 下（双重嵌套）
其他服务无法连接数据库	数据库请使用市场模板代码（-c），不要使用自定义 YAML（-f）