zeabur-cluster-scale

Zeabur 集群扩缩容（LKE / EKS 节点池）

Zeabur CLI 尚不支持节点池操作——请直接调用 https://api.zeabur.com/graphql 上的 Zeabur GraphQL API。该 API 与底层云服务提供商的原生资源一一对应：节点池对应 EKS 托管节点组或 Linode LKE 节点池。

⚠️ 扩缩容会影响实际账单——必须获得明确确认

添加节点或节点池会提高集群的月度订阅价格；每次变更后，系统都会根据底层云服务提供商的资源自动重新计算价格。你是最后一道防线：用户明确确认具体变更前，绝不可执行变更操作。

执行任何变更操作前，须在一条消息中提供以下所有信息：

• 集群（名称 + 服务端 ID）
• 节点池（实例类型 + 当前节点数）
• 具体变更（例如 3 → 5 nodes，或“添加节点池 g6-standard-4 × 2”）
• 当前月度价格（来自 Server.price），并说明价格会在变更后自动上涨或下调

然后直接询问用户是或否，例如：

你即将将集群 my-cluster 上的节点池 g6-standard-4 从 3 个节点扩容至 5 个。当前价格为 每月 US$180，变更后价格将大致按比例上涨。是否确认？

绝不可根据含糊的回复推断用户已同意。在看到具体数字前，用户只说“ok”并不算确认。如有疑问，应再次确认，而不是执行变更。

身份验证

所有请求都需要 Bearer 令牌。请勿让令牌出现在进程列表中——将其写入权限为 0600 的 curl 配置文件，并通过 -K 传入，而不要在命令行中使用 -H "Authorization: ..."：

TOKEN="${ZEABUR_API_KEY:-$(grep '^token:' ~/.config/zeabur/cli.yaml | awk '{print $2}')}"
ZAPI_CFG=$(mktemp)
chmod 600 "$ZAPI_CFG"
printf 'header = "Authorization: Bearer %s"\n' "$TOKEN" > "$ZAPI_CFG"
unset TOKEN

• 如果设置了 ZEABUR_API_KEY 环境变量，优先使用它
• 否则，复用 CLI 令牌 ~/.config/zeabur/cli.yaml（运行 npx zeabur@latest auth login 后会生成——如果用户尚未登录，请使用 zeabur-auth skill）
• 每次工具/Bash 调用都会启动一个全新的 shell——请在使用 $ZAPI_CFG 的请求所在的同一个 shell 块中完成此设置，并在完成后运行 rm -f "$ZAPI_CFG"

所有节点池变更操作都需要对集群具有管理权限（所有者或管理员）。只有查看权限的协作者可以列出节点池，但不能更改它们。

1. 查找集群的服务端 ID

npx zeabur@latest server list -i=false

只有专用 Kubernetes 集群（LKE / EKS）才有节点池。如果不确定某个服务端是否为集群，请检查下方查询中的 clusterType——集群会返回 "dedicated_cluster" 和非空的 nodePools。

2. 列出节点池

curl -sS --max-time 30 -K "$ZAPI_CFG" https://api.zeabur.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"query($id: ObjectID!) { server(_id: $id) { name clusterType price nodePools { id instanceType nodeCount minNodes maxNodes readyNodes status } } }","variables":{"id":"<server-id>"}}'

字段说明：

• id — 云服务提供商侧的标识符（EKS 节点组名称或 LKE 节点池 ID）。在下方的变更操作中，将其作为 nodePoolID 传入。
• instanceType — 节点池所用的云服务提供商机器类型（例如，EKS 的 t3.2xlarge、LKE 的 g6-standard-4）
• nodeCount 与 readyNodes — 期望节点数与当前已投入服务的节点数。扩缩容操作进行期间，两者可能不同。
• minNodes / maxNodes — 自动扩缩容的下限/上限；未配置自动扩缩容时，两者均为 0
• price — 集群当前的月度订阅价格；请在确认消息中报出此价格

3. 扩展现有节点池

最常见的操作——直接更改池中的节点数：

curl -sS --max-time 30 -K "$ZAPI_CFG" https://api.zeabur.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation($sid: ObjectID!, $pid: String!, $n: Int!) { scaleNodePool(serverID: $sid, nodePoolID: $pid, nodeCount: $n) }","variables":{"sid":"<server-id>","pid":"<node-pool-id>","n":5}}'

更改后，每隔约 30 秒轮询一次列表查询，直到 readyNodes 等于新的 nodeCount，并且池的 status 状态正常（EKS 为 ACTIVE，LKE 为 ready）——配置通常需要几分钟。等待时间必须设上限：如果池的 status 显示失败或降级，立即停止并转达该状态；如果约 15 分钟后仍未收敛，停止轮询并报告当前状态，不要无限等待。成功后，向用户报告更新后的节点池和价格。

如果更改请求超时或在传输层失败，切勿盲目重试。 服务端可能已经应用更改——先重新获取节点池列表，仅在状态表明更改未发生时才重试。盲目重试 addNodePool 可能导致重复配置（并重复计费）；盲目重试 removeNodePool 则可能在 ID 被旧列表重复使用时命中另一个池。

缩容： 告知用户，被移除的节点会先排空，其工作负载会重新调度到剩余节点上——确保剩余容量足以承载当前工作负载（如有需要，可通过 zeabur-service-metric 技能检查）。绝不能将集群唯一的节点池缩容至 0。

4. 添加节点池

当用户需要不同的机器类型（例如添加更大的机器或 GPU 节点），而非增加相同类型的机器时使用：

curl -sS --max-time 30 -K "$ZAPI_CFG" https://api.zeabur.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation($sid: ObjectID!, $t: String!, $n: Int!) { addNodePool(serverID: $sid, instanceType: $t, nodeCount: $n) { id instanceType nodeCount status } }","variables":{"sid":"<server-id>","t":"g6-standard-4","n":2}}'

instanceType 会原样传递给提供商——你需要先查找有效的类型：

• LKE（Linode）：curl -s https://api.linode.com/v4/linode/types——公开接口，无需身份验证。使用类型 id（例如 g6-standard-4、g6-dedicated-8）。
• EKS（AWS）：集群所在区域提供的任何 EC2 实例类型（例如 t3.2xlarge、m6i.xlarge）。不确定时，询问用户或采用现有池的实例类型。

无效或不在当前区域提供的实例类型会在提供商侧导致失败——错误消息会原样出现在 GraphQL errors 数组中。

5. 移除节点池

具有破坏性。 池中的所有节点都会被排空并删除；工作负载会重新调度到剩余的池上。绝不能移除集群的最后一个节点池。除上述明确确认外，还必须告知用户将移除的节点池名称。

curl -sS --max-time 30 -K "$ZAPI_CFG" https://api.zeabur.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation($sid: ObjectID!, $pid: String!) { removeNodePool(serverID: $sid, nodePoolID: $pid) }","variables":{"sid":"<server-id>","pid":"<node-pool-id>"}}'

移除完成检查：轮询列表查询（等待上限与上文相同），直到 nodePools 中不再显示该池，然后报告更新后的价格。

推荐的操作指引流程

当用户要求扩缩容（或反映容量不足）时：

1. 先展示当前状态——列出节点池、就绪节点数和当前月费
2. 提出具体变更方案——说明涉及哪个池、节点数（或新增的实例类型）以及对费用的影响
3. 获取明确确认——参阅顶部的确认要求
4. 执行更改，然后观察状态——按上文设置的等待上限轮询，直到满足相应操作的完成条件（扩缩容／添加：readyNodes 匹配且 status 状态正常；移除：池已从列表中消失）；报告完成情况和更新后的价格

错误

• 401 / 未通过身份验证——令牌缺失或已过期：重新运行 npx zeabur@latest auth login，或检查 ZEABUR_API_KEY
• “requires manage access”——用户不是集群所有者或管理员；需请所有者执行更改
• nodePools 为空——该服务不是专用 Kubernetes 集群（单 VM 专用服务器无法通过此方式扩容；建议使用 zeabur-server-rent 租用更多容量）
• 提供商侧错误（例如实例类型无效、所在区域容量不足）会原样显示在 GraphQL errors 数组中——将错误转达给用户，并建议更换类型或区域