zeabur-deploy

Zeabur 部署

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

前置条件 — 确定目标项目

使用此技能前，必须先确定要部署到哪个 Zeabur 项目。如果对话历史和项目文件都没有提及项目，请运行：

npx zeabur@latest project list -i=false --json

• 如果存在项目，请询问用户要使用哪一个。
• 如果列表为空，或用户想创建新项目，必须调用 zeabur-project-create 技能。请勿直接运行 project create CLI 命令 — 该技能会通过服务器列表处理区域选择，这是必需步骤。

在确认目标项目之前，请勿继续部署。

部署到指定的专用服务器

如果用户要求部署到特定的服务器（例如“部署到我的 AWS Tokyo 服务器”），请勿通过 SSH 登录服务器。运行 ZeaburOS 的服务器由平台管理 — 应通过 Zeabur CLI 部署服务，而不是手动将文件放到机器上。

只有 ZeaburOS 服务器才能托管项目。 租用的服务器起初是纯 Ubuntu 系统（基础操作系统和 SSH，没有 Zeabur 服务）；必须先在其上安装 ZeaburOS — 参见 zeabur-server-rent 技能。如果部署到服务器失败是因为该服务器没有 Zeabur 服务，原因就在于此；请告知用户，不要尝试通过 SSH 配置机器。

查找绑定到服务器的项目：

1. 从 npx zeabur@latest server list -i=false 获取服务器 ID（也可以从对话上下文中获取）。
2. 在 project list --json 输出中，查找 Region.ID 与 server-<server-id> 匹配的项目。
3. 如果存在匹配的项目，请使用其项目 ID 进行部署。
4. 如果不存在匹配的项目，请调用 zeabur-project-create 技能，在该服务器上创建项目。

选择部署方式

Zeabur 支持两种项目部署方式：

方式	使用时机
直接部署（默认）	用户说“部署此项目/网站/应用”。无需 Git 仓库。快速且简单。
Git 部署	用户明确要求通过 Git/GitHub 部署，或希望通过 CI/CD 在推送代码时自动重新部署。

除非用户明确要求基于 Git 部署，否则默认使用直接部署。

直接部署（默认）

通过一条命令将当前本地目录部署到 Zeabur。

标志

标志	必填	描述
--project-id	是（非交互模式）	要部署到的项目 ID
--json	建议使用	以 JSON 格式输出
--name	否	服务名称（默认为目录名称）
--service-id	否	要重新部署到的服务 ID（省略则创建新服务）
--environment-id	否	环境 ID（默认为第一个环境）

注意： 请勿在部署命令中使用 --create、-r 或 --region 标志。如果用户需要创建新项目或选择区域，请先使用 zeabur-project-create 技能。

首次部署

首次部署时，省略 --service-id — 系统会自动创建新服务：

npx zeabur@latest deploy --project-id <project-id> --json

响应中包含 service_id。后续所有部署都必须保存并使用此 service_id。 请立即将其写入当前项目的 CLAUDE.md：

## Zeabur Deployment
- Project ID: <project-id>
- Service ID: <service-id>

重新部署（更新现有服务）

重要：重新部署代码更改时，必须传入 --service-id 来更新现有服务。省略 --service-id 会在每次部署时创建一个新的重复服务。

npx zeabur@latest deploy --project-id <project-id> --service-id <service-id> --json

请勿将此流程用于预构建服务或市场服务的版本升级／降级（例如“将 PostgreSQL 升级到 16”“将 n8n 降级到 1.2”）。这是切换版本，而不是重新部署代码——请改用 zeabur-update-service 技能更新标签。用重新部署代替标签更改，可能会导致服务已挂载的磁盘变成孤立磁盘或被清空。

如果尚不存在项目，请调用 zeabur-project-create 技能（不要直接运行 CLI 命令）。

Git 部署（应用户要求）

如果用户明确希望通过 Git 部署（例如用于 CI/CD，或在推送时自动重新部署）：

1. 首先，确保代码已推送到 GitHub 仓库。
2. 通过 CLI 部署：

# Non-interactive mode — required parameters only
npx zeabur@latest service deploy --json -i=false \
  --project-id <project-id> \
  --template GIT \
  --repo-id <repo-id> \
  --branch-name <branch>

# With optional service name
npx zeabur@latest service deploy --json -i=false \
  --project-id <project-id> \
  --template GIT \
  --repo-id <repo-id> \
  --branch-name <branch> \
  --name "<service-name>"

Git 部署标志

标志	必需	说明
--template GIT	是	指定基于 Git 的部署
--project-id	非交互模式	项目 ID（交互模式下会提示输入）
--repo-id	非交互模式	GitHub 仓库 ID
--branch-name	非交互模式	要部署的 Git 分支
--name	否	服务名称（默认为仓库名称）
--keyword	否	用于搜索 GitHub 仓库的关键词（交互模式）

Git 部署工作流

Git 部署工作流：

# 1. Search for the user's GitHub repo
npx zeabur@latest service search-repo <keyword> --json -i=false
# Returns: [{"Name":"my-app","Owner":"user","URL":"...","ID":12345}, ...]
# If multiple results are returned, ask the user which repo to deploy.
# The agent (not the CLI) is responsible for disambiguation.

# 2. Deploy from GitHub using the repo ID from search results
npx zeabur@latest service deploy --json -i=false \
  --project-id $PROJECT_ID \
  --template GIT \
  --repo-id <repo-id> \
  --branch-name main

部署后，Zeabur 会在每次向所选分支推送时自动重新部署。

仅当用户明确要求基于 Git 部署时，才引导用户使用此流程。

提示

• 直接部署只需要 --project-id——系统会自动创建新服务。无需 Git 历史记录或 GitHub 账户。
• 对于静态站点，Zeabur 会自动检测并正确提供服务。
• 首次部署后，务必同时保存 Project ID 和 Service ID。 这样可以避免重新部署时创建重复服务。
• 部署后，使用 zeabur-deployment-logs 技能检查构建日志和运行时日志。