zeabur-template-deploy

用途

Zeabur Template Deploy 用于通过命令行部署 Zeabur 模板以及市场中的预构建服务与数据库。当用户需要部署模板、安装模板，或部署常见服务（如 MongoDB、PostgreSQL、Redis 等）时，可使用该技能。

主要能力

通过 CLI 部署 Zeabur 模板与市场预构建服务。
支持按模板代码直接部署市场模板。
支持获取原始模板 YAML 后进行自定义修改再部署。
支持部署完全自定义或多服务的模板 YAML 文件。
支持通过 --var 传入模板变量，适配非交互模式。

使用方式

始终使用 npx zeabur@latest 调用 Zeabur CLI，不要直接使用 zeabur 或其他安装方式。若 npx 不可用，需先安装 Node.js。在 CLI 自动化中始终使用非交互模式（-i=false）。

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

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

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

# 1. 按关键词搜索模板
npx zeabur@latest template search mongodb -i=false --json

# 2. 按模板代码部署（代码来自搜索结果中的 "Code" 字段）
npx zeabur@latest template deploy -i=false \
  -c <TEMPLATE_CODE> \
  --project-id <project-id>

示例：部署 MongoDB

# 搜索返回 MongoDB 的代码 "KXL04P"
npx zeabur@latest template search mongodb -i=false --json

# 按代码直接部署
npx zeabur@latest template deploy -i=false \
  -c KXL04P \
  --project-id abc123

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

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

# 1. 获取原始 YAML
npx zeabur@latest template get -c KXL04P --raw > template.yaml

# 2. 按需编辑 template.yaml

# 3. 部署自定义后的模板
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 ADMIN_EMAIL=admin@example.com

部署本地文件：

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。

# 推荐——通过市场代码部署（有内部 DNS）
npx zeabur@latest template search postgresql -i=false --json
npx zeabur@latest template deploy -i=false -c <CODE> --project-id <id>

# 不推荐——自定义 YAML 可能缺少内部 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：

# 正确
spec:
  services:
    - name: my-service
      template: PREBUILT
      spec:                    # <-- 必需的嵌套
        source:
          image: postgres:17

# 错误——会失败并提示 "missing property 'spec'"
spec:
  services:
    - name: my-service
      template: PREBUILT
      source:                  # <-- 缺少 spec 包装
        image: postgres:17

常见问题

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

适用场景

需要快速部署 Zeabur 市场中的常见服务或数据库。
需要在部署前对模板 YAML 进行自定义调整。
需要在自动化流程中以非交互方式部署模板并传入变量。

限制

自定义 PREBUILT 模板 YAML 可能无法注册内部 DNS，导致同项目其他服务无法通过主机名连接。
非交互模式下必须提供所有必需变量，否则部署失败。
模板 YAML 必须遵循 spec.services[].spec.source 的嵌套结构。
关于收费、价格、平台支持范围等更多信息，资料中暂未提供。