zeabur-server-rent

Zeabur 服务器租用

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

租用会部署基础操作系统——ZeaburOS 是后续步骤

server rent 只会提供 Ubuntu 和 SSH，不包含其他内容。不会安装 Zeabur 服务，因此新租用的服务器暂时无法托管 Zeabur 项目。

这是有意为之，并非故障。用户可以随意使用这台机器：docker compose、1Panel、寶塔，或其他任何方式。ZeaburOS——基于 k3s 构建的 Zeabur 托管环境——会在之后单独安装，本技能也涵盖此步骤。

租用前询问用户想要哪种操作系统

有两种选择，不能互换。请明确询问；不要根据上下文推断，也不要默认选择：

选项	说明	适用情况
Ubuntu	普通的自主管理 VPS。租用完成后即告结束。	用户想要一台可按自己喜好配置的机器。
ZeaburOS	Ubuntu 加 Zeabur 服务。要将 Zeabur 项目部署到此服务器，必须选择此项。	用户想在此服务器上部署项目。租用后还需要几分钟进行安装。

请将其表述为一个问题，例如：

你希望将此服务器设置为 ZeaburOS（这样你就能在上面部署 Zeabur 项目），还是保留为由你自行管理的普通 Ubuntu VPS？

“用户说想部署一个应用”并不代表回答了这个问题——很多用户会在自己的机器上使用 docker compose 部署。无论如何都要询问。

⚠️ 租用需要支付真实费用——必须获得明确确认

server rent 会立即从用户的付款方式或 Zeabur 余额中扣款。-y 标志会跳过 CLI 自带的确认提示，因此你是最后一道防线：在用户明确确认具体价格选项之前，绝不能运行 server rent。

租用前，你必须在一条消息中向用户说明以下所有信息：

• 提供商（例如 DigitalOcean）
• 区域（例如 New York / nyc3）
• 套餐/规格（例如 s-2vcpu-4gb — 2 vCPU / 4 GB RAM）
• 月费（例如 US$27/月）
• 用户选择的操作系统（来自上一步）
• 说明租用后会立即扣费

然后提出一个直接的是/否问题，例如：

你即将租用 DigitalOcean New York s-2vcpu-4gb，US$27/月，并将其设置为 ZeaburOS。现在将从你的付款方式扣款。确认购买吗？

只有在用户明确且肯定地确认这一具体价格选项后，才能继续。

绝不能从含糊的回复中推断用户同意购买——单独一个数字（如“2”）、一句“好的”，或用户在看到具体价格前做出的选择，都不算确认。只有当数字对应于用户已看到的编号选项，且其中明确列出提供商、区域、规格和价格时，数字回复才算有效确认。如有疑问，请再次确认，不要租用。

工作流

1. 浏览可用选项（使用 zeabur-server-catalog 技能进行筛选）

npx zeabur@latest server catalog -i=false

2. 根据 JSON 输出选择提供商、区域和套餐

3. 询问用户想要哪种操作系统

请参阅上文。本步骤将决定是否执行第 6 步。

4. 展示具体选项并获取用户的明确确认

提供商、区域、规格、月费、操作系统以及立即扣费的说明。即使用户之前笼统地要求租用服务器，也不得跳过此步骤。

5. 租用（仅在确认后进行）

npx zeabur@latest server rent --provider hetzner --region fsn1 --plan CAX11 -y -i=false

配置需要几分钟。请轮询，直到机器启动：

npx zeabur@latest server get <server-id> -i=false

等待 provisioningStatus 变为 READY，且 VM STATUS 变为 RUNNING。

6. 如果用户选择了 ZeaburOS：安装 Zeabur 服务

按照下文的“在服务器上安装 ZeaburOS”进行操作。如果用户选择了 Ubuntu，则已完成——请参阅“使用普通 Ubuntu VPS”。

在服务器上安装 ZeaburOS

仅限尚未使用的机器——刚租用的机器、刚重新安装基础操作系统的机器，或停留在加入网格步骤的 WonderMesh 设备。此操作会在正在运行的系统之上安装 k3s，不会清除系统：在空机器上安全，但在已投入使用的机器上结果不可预测。

不要在用户已经配置好的机器上运行此操作。 k3s 会占用端口（6443、NodePort 端口范围、4222 上的 NATS），重写 iptables 规则，并在已有 Docker 的情况下同时带来自己的容器运行时。在运行 docker compose、1Panel、寶塔 或类似软件的机器上，安装能否成功取决于已安装的内容，而且可能会导致正在运行的服务中断。

对于这类机器，请引导用户前往控制面板：服务器的 Settings → Danger Zone → Reinstall OS，并选择 ZeaburOS。重装能让结果可预测，但会清除磁盘。请明确告知用户，并提醒他们先备份——是否重装由用户决定，而不是你。

两种方向的切换都会破坏现有数据。从 ZeaburOS 切换到标准发行版，以及从标准发行版切换到 ZeaburOS，都需要重装，都会清除机器上的数据。

如果机器尚未使用，请运行此命令。

Zeabur CLI 尚未提供此功能——请直接调用 Zeabur GraphQL API：https://api.zeabur.com/graphql。

运行此命令

整段代码会完成身份验证、启动安装并等待安装完成。替换服务器 ID 后原样运行——其中每一部分都不可或缺，下文会说明原因。

SERVER_ID="<server-id>"

command -v jq >/dev/null 2>&1 || { echo "jq is required to read the API responses" >&2; exit 1; }

# Keep the token out of the process list: write it into a 0600 curl config
# passed with -K, never as -H "Authorization: ..." on the command line.
TOKEN="${ZEABUR_API_KEY:-$(grep '^token:' ~/.config/zeabur/cli.yaml 2>/dev/null | awk '{print $2}')}"
if [ -z "$TOKEN" ]; then
  echo "No Zeabur token found — set ZEABUR_API_KEY or run: npx zeabur@latest auth login" >&2
  exit 1
fi
ZAPI_CFG=$(mktemp)
chmod 600 "$ZAPI_CFG"
trap 'rm -f "$ZAPI_CFG"' EXIT
printf 'header = "Authorization: Bearer %s"\n' "$TOKEN" > "$ZAPI_CFG"
unset TOKEN

zapi() {
  curl -sS --max-time 30 -K "$ZAPI_CFG" https://api.zeabur.com/graphql \
    -H "Content-Type: application/json" -d "$1"
}

# GraphQL reports failures as HTTP 200 with an `errors` array, so a request that
# "succeeded" can still be a hard failure. Stop on one instead of polling past it.
die_on_error() {
  if printf '%s' "$1" | jq -e 'has("errors")' >/dev/null 2>&1; then
    printf '%s' "$1" | jq -r '.errors[] | "\(.extensions.code // "ERROR"): \(.message)\(if .extensions.description then " — " + .extensions.description else "" end)"' >&2
    exit 1
  fi
}

# Start the install. This returns immediately — the work runs in the background.
RESP=$(zapi "{\"query\":\"mutation(\$id: ObjectID!) { installK3s(serverID: \$id) }\",\"variables\":{\"id\":\"$SERVER_ID\"}}")
die_on_error "$RESP"

# Wait for it, against a real 15-minute deadline.
DEADLINE=$(( $(date +%s) + 900 ))
while [ "$(date +%s)" -lt "$DEADLINE" ]; do
  sleep 30
  RESP=$(zapi "{\"query\":\"query(\$id: ObjectID!) { server(_id: \$id) { hasK3s provisioningStatus } }\",\"variables\":{\"id\":\"$SERVER_ID\"}}")
  die_on_error "$RESP"
  HAS_K3S=$(printf '%s' "$RESP" | jq -r '.data.server.hasK3s // "unknown"')
  STATUS=$(printf '%s' "$RESP" | jq -r '.data.server.provisioningStatus // "unknown"')
  echo "hasK3s=$HAS_K3S provisioningStatus=$STATUS"
  if [ "$HAS_K3S" = "true" ]; then echo "ZeaburOS is installed"; exit 0; fi
  if [ "$STATUS" = "FAILED" ]; then echo "Install failed: $RESP" >&2; exit 1; fi
done
echo "Still installing after 15 minutes — check the server's page in the dashboard" >&2
exit 2

各部分这样编写的原因：

• mutation 返回并不代表安装已完成。 安装在后台进行——通过 SSH 连接机器、安装 k3s，并等待节点启动——需要几分钟。返回 true 只表示请求已被接受并开始执行。切勿仅凭 mutation 就报告成功。
• 成功的标志是 hasK3s: true，而不是 provisioningStatus: "READY"。 状态会从 READY 变为 INITIALIZING，再变回 READY，因此安装开始前状态也会是 READY。如果轮询此状态，过早检查时就会报告成功——而且看起来确实如此，因为机器当时真的处于 READY 状态。
• 单独检查 FAILED 状态，这样安装失败时会立即结束等待，而不是一直等到超时。
• 每次响应都会先检查 errors。 GraphQL 会通过 HTTP 200 和 errors 数组返回失败，且不包含 data。因此，未经授权的令牌、错误的服务器 ID，或下文列出的任何前置条件失败，否则都会被误认为“仍在安装”，白白等待完整的 15 分钟，最后也没有有用的信息。extensions.code 是下表中的机器可读代码；extensions.description 是面向用户的说明。
• 使用 jq 解析，而不是对原始 JSON 使用 grep。 一旦响应在冒号后多出空格，grep '"hasK3s":true' 就会失效；而且它会默认放行——未匹配到内容时会被误认为“仍在安装”。出于同样的原因，如果没有 jq，此代码段会拒绝启动，而不会默默地错误解析。
• 等待时间有截止期限，不是循环计数。 加上请求耗时后，30 × sleep 30 会超过 15 分钟；使用时间戳进行比较，才能确保实际等待时间不超过所述时限。
• 找不到令牌时立即停止。 否则会发送未经身份验证的请求，导致的 401 会被误解为“服务器故障”，而不是“你尚未登录”。
• trap 会在中间命令失败时删除 curl 配置。 每次工具/Bash 调用都会启动一个新的 shell，因此请将整个代码段放在一起运行——$ZAPI_CFG 不会保留到下一次调用。

如果已设置 ZEABUR_API_KEY，优先使用它；否则令牌来自 ~/.config/zeabur/cli.yaml，该文件由 npx zeabur@latest auth login 写入（如果用户尚未登录，请使用 zeabur-auth skill）。

错误

以下情况会导致变更一开始就失败。请转述错误含义，而不是原样转述 GraphQL 错误：

代码	发生了什么	告诉用户什么
K3S_ALREADY_INSTALLED	服务器已运行 ZeaburOS	无需操作——已可用于部署项目
SERVER_NOT_READY	仍在配置中	等待 provisioningStatus: READY，然后重试
K3S_INSTALL_IN_PROGRESS	安装已在运行，或刚刚完成	不要再次发送变更——直接开始轮询
SERVER_NOT_FOUND	ID 错误，或服务器已被删除	使用 server list 重新检查 ID

如果变更在传输层超时，绝不要盲目重试。 安装可能已在服务器端运行。请先轮询上面的查询，只有在服务器恢复到文档所述的安装前状态——hasK3s: false 且 provisioningStatus: "READY"——时，才重新发送变更。

绝不要自动重试状态为 FAILED 的安装。 FAILED 是终止状态，表示安装确实在机器上失败；重试只会重复失败。请报告失败情况，并由用户决定下一步操作。

付款错误

如果用户没有绑定信用卡或余额不足，CLI 会返回：

ERROR  Rent server failed: please bind a credit card or recharge credits first
INFO   Please bind a credit card or top up your balance at: https://zeabur.com/account/billing

操作： 指引用户前往 https://zeabur.com/account/billing 添加付款方式或充值，然后重试。

使用普通 Ubuntu VPS

无需其他操作——通过 SSH 登录，并按用户偏好的方式配置机器（docker compose、1Panel、寶塔等）。使用 zeabur-server-ssh 技能：

npx zeabur@latest server exec --id <server-id> -- <command>

此类机器上没有 kubectl，也没有可管理的 Zeabur 服务。

不要对未运行 ZeaburOS 的服务器运行 zeabur-project-create。 此类服务器上没有 Zeabur 服务，因此在其上创建项目会失败——请先安装 ZeaburOS。