zeabur-server-ssh

Zeabur Server SSH + kubectl

**始终使用 npx zeabur@latest 调用 Zeabur CLI。**切勿直接使用 zeabur 或通过其他方式安装。

在用户的专用服务器上运行命令，并使用 kubectl 调试运行 ZeaburOS 的服务器上的 Kubernetes 工作负载。

使用 kubectl 前，先确认服务器类型

• ZeaburOS 服务器运行 k3s，并预装了 kubectl。本技能中的所有内容均适用。
• Ubuntu — 未运行 ZeaburOS 的租用服务器。它没有 k3s 和 kubectl；以下所有 kubectl 命令都会报错 command not found。普通 shell 命令仍可通过 server exec 运行。

租用的服务器仅提供 Ubuntu，因此切勿假设存在 kubectl。

通过 CLI 读取机器类型 — 不要 SSH 登录后再确认：

npx zeabur@latest server get <server-id> -i=false --json | jq -r .os

ZeaburOS 或 Ubuntu。server list 会通过 OS 列和 os 字段，一次性报告所有服务器的相同信息。

需要 CLI 0.21.0 或更高版本。如果返回的 os 为 null，说明 CLI 版本较旧 — 可以让 npx zeabur@latest 获取当前版本，或改用 API（有关定义 $ZAPI_CFG 的令牌设置，请参阅 zeabur-server-rent 技能）：

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) { hasK3s } }","variables":{"id":"<server-id>"}}'

hasK3s 有三种状态，第三种状态容易踩坑：true 表示 ZeaburOS，false 仅表示 Ubuntu，而 null 表示服务器早于此字段 — 这类服务器确实运行 ZeaburOS。因此，应检查 hasK3s === false，切勿使用 !hasK3s；后者会包含所有更早的服务器，并错误地将其报告为普通 VPS。

如果未事先检查，而 kubectl 命令报错 command not found，这同样说明服务器是普通 Ubuntu VPS；请告知用户，而不是重试命令。安装 ZeaburOS 后才会有 kubectl；有关安装方式，请参阅 zeabur-server-rent 技能。

**一个例外。**以上内容回答的是这是什么类型的机器。如果用户明确询问机器上是否存在某个二进制文件，请检查该机器 — ZeaburOS 服务器始终有 kubectl，但普通 Ubuntu VPS 的所有者可能自行安装了它，而 OS 字段无法告知你这一点。

运行命令：server exec（推荐）

一步即可在服务器上运行命令。CLI 会在内部获取凭据并建立连接，因此你无需处理密码 — 包含特殊字符的密码也能正常使用，而且不需要 ssh2/sshpass。

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

示例：

# Single command
npx zeabur@latest server exec --id <server-id> -- sudo kubectl get pods -A -o wide

# Compound command — quote it as ONE argument so && / | stay intact
npx zeabur@latest server exec --id <server-id> -- 'echo "=== PODS ===" && sudo kubectl get pods -A && echo "=== EVENTS ===" && sudo kubectl get events -A --sort-by=.lastTimestamp | tail -20'

注意：

• -- 之后的所有内容都是远程命令，会像 ssh host <command> 一样拼接。复合命令（包含 && / | / 重定向）应作为单个参数加引号。
• stdout/stderr 会实时传输；远程命令的退出代码会被传递回来（管道只报告最后一个阶段的状态 — … | tail 会隐藏上游失败，因此不要依赖管道的退出代码）。
• 如果不知道服务器 ID，请先列出服务器：

  npx zeabur@latest server list -i=false
  

  （或使用 zeabur-server-list 技能）。

常用 kubectl 命令

仅适用于 ZeaburOS 服务器。 在普通 Ubuntu VPS 上，这些命令都会失败并提示 kubectl: command not found——请参阅上文。

将以下任一命令作为 server exec 的命令传入。始终使用 sudo kubectl—— SSH 用户可能无法直接访问 k3s kubeconfig。任何包含管道符（|）或 && 的命令都必须 作为单个参数加引号，否则本地 shell 会将其拆分，并在本地运行部分命令——例如： server exec --id <id> -- 'sudo kubectl top pods -A --sort-by=memory | head -20'。

任务	命令
列出所有 pod	sudo kubectl get pods -A -o wide
仅列出异常 pod	sudo kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded
Pod 日志	sudo kubectl logs <pod-name> -n <namespace> --tail=100
进入容器执行命令	sudo kubectl exec <pod-name> -n <namespace> -- <command>
节点资源	sudo kubectl top nodes
Pod 资源	sudo kubectl top pods -A --sort-by=memory | head -20
查看 Pod 详情	sudo kubectl describe pod <pod-name> -n <namespace>
最近的事件	sudo kubectl get events -A --sort-by=.lastTimestamp | tail -30
重启部署	sudo kubectl rollout restart deployment/<name> -n <namespace>

备用方案：手动 SSH（仅在无法使用 server exec 时）

仅在无法使用 server exec 时（例如，使用较旧的 CLI）才使用此方案。否则， 请优先使用上文的 server exec——使用特殊字符密码时，此方案容易出问题。

第 1 步：获取 SSH 凭据

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

输出为 JSON：{"ip":"1.2.3.4","port":22,"username":"root","password":"xxx"}

第 2 步：连接

默认使用 Node.js ssh2 方法；只有在已确认 sshpass 可用时才使用它。不要运行 which sshpass 进行检查——这会浪费一步，而且它通常并未安装。

# sshpass (only if already known to be available)
sshpass -p '<password>' ssh -o StrictHostKeyChecking=no -p <port> <username>@<ip> sudo kubectl get pods -A

# Node.js ssh2 (the Zeabur agent sandbox has it pre-installed)
NODE_PATH=$([ -d /root/.global/node_modules ] && echo /root/.global/node_modules || echo /home/vercel-sandbox/.global/node_modules) node -e "
const {Client} = require('ssh2');
const c = new Client();
c.on('ready', () => {
  c.exec('<command>', (err, stream) => {
    if (err) { console.error(err); process.exit(1); }
    let out = '', errOut = '';
    stream.on('data', d => out += d);
    stream.stderr.on('data', d => errOut += d);
    stream.on('close', code => {
      if (out) console.log(out);
      if (errOut) console.error(errOut);
      c.end();
      process.exit(code);
    });
  });
}).connect({host:'<ip>', port:<port>, username:'<username>', password:'<password>'});
"

提示

• 组合命令：在一次 server exec 调用中用 && 批量执行相关检查，以减少往返次数。
• 使用 -o wide：在 Pod 列表中添加节点名称和 IP，有助于排查调度问题。
• 命名空间很重要：Zeabur 服务通常运行在非默认命名空间中。先使用 -A（所有命名空间）找到正确的命名空间，再用 -n <namespace> 指定范围。
• 先阅读项目文档：如果修复尝试失败，请进入容器并检查 README/配置，再考虑查看指标：sudo kubectl exec <pod> -n <ns> -- cat /app/README.md
• 要查找服务器 ID，请使用 zeabur-server-list 技能。对于不需要服务器级访问权限的简单容器命令，请使用 zeabur-service-exec 技能。