zeabur-server-ssh

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Zeabur Server SSH + kubectl

Always use
npx zeabur@latest
to invoke Zeabur CLI. Never use
zeabur
directly or any other installation method.

Run commands on a user's dedicated server, and use kubectl to debug Kubernetes workloads on servers that run ZeaburOS.

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

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

Check which kind of server you are on before using kubectl

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

ZeaburOS servers run k3s with kubectl pre-installed. Everything in this skill applies.
Ubuntu — a rented server that is not running ZeaburOS. It has no k3s and no kubectl; every
```
kubectl
```
command below fails with
```
command not found
```
.
```
server exec
```
still works for ordinary shell commands.

Renting provisions Ubuntu only, so never assume kubectl exists.

Read the machine's kind from the CLI — do not SSH in to work it out:

bash

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

ZeaburOS

Ubuntu

server list

reports the same thing for every server at once, as an

OS

column and an

os

field.

Needs CLI 0.21.0 or newer. If
os
comes back
null
, the CLI is older — either let
npx zeabur@latest
fetch the current version, or fall back to the API (see the
zeabur-server-rent
skill for the token setup that defines
$ZAPI_CFG
):
bash
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
is three-state and the third state is a trap:
true
is ZeaburOS,
false
is Ubuntu only, and
null
is a server predating the field — which does run ZeaburOS. So the test is
hasK3s === false
, never
!hasK3s
; the latter sweeps in every older server and wrongly reports it as a plain VPS.

If you did not check first and a

kubectl

command fails with

command not found

, that is the same signal — tell the user the server is a plain Ubuntu VPS instead of retrying the command. Installing ZeaburOS is what adds kubectl; the

zeabur-server-rent

skill covers how.

One exception. All of the above answers what kind of machine this is. If the user asks specifically whether some binary is present, check the machine — a ZeaburOS server always has

kubectl

, but a plain Ubuntu VPS may have had it installed by its owner, and the OS field cannot tell you that.

ZeaburOS服务器 运行k3s且预安装了kubectl。本技能的所有内容均适用。
Ubuntu服务器 —— 未运行ZeaburOS的租用服务器。这类服务器没有k3s和kubectl；以下所有
```
kubectl
```
命令都会因
```
command not found
```
失败。
```
server exec
```
仍可用于普通shell命令。

租用的服务器仅提供Ubuntu系统，因此切勿默认kubectl已存在。

通过CLI查看服务器类型——不要通过SSH登录来判断：

bash

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（参考
zeabur-server-rent
技能中的令牌设置，定义
$ZAPI_CFG
）：
bash
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字段无法告知这一点。

Run a command:

server exec

(recommended)

运行命令：

server exec

（推荐）

Run a command on the server in one step. The CLI fetches the credentials and opens the connection internally, so you never handle the password — passwords with special characters just work, and no

ssh2

sshpass

is needed.

bash

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

Examples:

bash

undefined

一步到位在服务器上运行命令。CLI会自动获取凭证并建立连接，因此你无需处理密码——含特殊字符的密码也能正常工作，无需使用

ssh2

sshpass

。

bash

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

示例：

bash

undefined

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'


Notes:

- Everything after `--` is the remote command, joined like `ssh host <command>`.
  Quote a compound command (with `&&` / `|` / redirects) as a **single argument**.
- stdout/stderr stream live; the remote command's **exit code is propagated**
  (a pipeline reports only its **last** stage's status — `… | tail` hides an
  upstream failure, so don't rely on the exit code across a pipe).
- If you don't know the server ID, list servers first:
  ```bash
  npx zeabur@latest server list -i=false

(or use the

zeabur-server-list

skill).

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，先列出服务器：
  ```bash
  npx zeabur@latest server list -i=false

（或使用

zeabur-server-list

技能）。

Common kubectl Commands

常用kubectl命令

ZeaburOS servers only. On a plain Ubuntu VPS these all fail with
kubectl: command not found
— see the section above.

Pass any of these as the command to

server exec

. Always use
sudo kubectl
— the SSH user may not have direct access to the k3s kubeconfig. Any command with a pipe (

) or

&&

must be quoted as a single argument, or the local shell splits it and runs part locally — e.g.

server exec --id <id> -- 'sudo kubectl top pods -A --sort-by=memory | head -20'

Task	Command
List all pods	`sudo kubectl get pods -A -o wide`
Problem pods only	`sudo kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded`
Pod logs	`sudo kubectl logs <pod-name> -n <namespace> --tail=100`
Exec into container	`sudo kubectl exec <pod-name> -n <namespace> -- <command>`
Node resources	`sudo kubectl top nodes`
Pod resources	`sudo kubectl top pods -A --sort-by=memory \| head -20`
Describe pod	`sudo kubectl describe pod <pod-name> -n <namespace>`
Recent events	`sudo kubectl get events -A --sort-by=.lastTimestamp \| tail -30`
Restart deployment	`sudo kubectl rollout restart deployment/<name> -n <namespace>`

仅适用于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`
重启Deployment	`sudo kubectl rollout restart deployment/<name> -n <namespace>`

Fallback: manual SSH (only if

server exec

is unavailable)

备选方案：手动SSH（仅当

server exec

不可用时使用）

Use this only if

server exec

isn't available (e.g. an older CLI). Otherwise prefer

server exec

above — this path is fragile with special-character passwords.

仅在

server exec

不可用（例如CLI版本较旧）时才使用此方法。否则优先使用上文的

server exec

——此方法在处理含特殊字符的密码时较为脆弱。

Step 1: Get SSH credentials

步骤1：获取SSH凭证

bash

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

Output is JSON:

{"ip":"1.2.3.4","port":22,"username":"root","password":"xxx"}

bash

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

输出为JSON格式：

{"ip":"1.2.3.4","port":22,"username":"root","password":"xxx"}

Step 2: Connect

步骤2：建立连接

Use the Node.js

ssh2

method by default; use

sshpass

only when its availability is already known. Do NOT run

which sshpass

to check — it wastes a step where it's never installed.

bash

undefined

默认使用Node.js的

ssh2

方法；仅当已知

sshpass

可用时才使用它。不要运行

which sshpass

来检查——这会浪费时间，因为它通常未安装。

bash

undefined

sshpass (only if already known to be available)

sshpass（仅当已知可用时使用）

sshpass -p '<password>' ssh -o StrictHostKeyChecking=no -p <port> <username>@<ip> sudo kubectl get pods -A


```bash

sshpass -p '<password>' ssh -o StrictHostKeyChecking=no -p <port> <username>@<ip> sudo kubectl get pods -A


```bash

Node.js ssh2 (the Zeabur agent sandbox has it pre-installed)

Node.js ssh2（Zeabur代理沙箱已预安装）

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>'}); "

undefined

undefined

Tips

小贴士

Combine commands: batch related checks with
```
&&
```
in a single
```
server exec
```
call to reduce round trips.
Use
-o wide
: adds node name and IP to pod listings, useful for scheduling issues.
Namespace matters: Zeabur services usually run in non-default namespaces. Use
```
-A
```
(all namespaces) first to locate the right one, then scope with
```
-n <namespace>
```
.
Read project docs first: if a fix attempt fails, exec into the container and check README/config before blindly checking metrics:
```
sudo kubectl exec <pod> -n <ns> -- cat /app/README.md
```
To find server IDs, use the
```
zeabur-server-list
```
skill. For simpler container commands that don't need server-level access, use the
```
zeabur-service-exec
```
skill.

组合命令：在单个
```
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
```
技能。

zeabur-server-ssh

Original

Translation

Zeabur Server SSH + kubectl

Zeabur Server SSH + kubectl

Check which kind of server you are on before using kubectl

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

Run a command:
`server exec`
(recommended)

运行命令：
`server exec`
（推荐）

Single command

单个命令

Compound command — quote it as ONE argument so && / | stay intact

复合命令——将其作为单个参数引用，以保证&& / | 保持完整

Common kubectl Commands

常用kubectl命令

Fallback: manual SSH (only if
`server exec`
is unavailable)

备选方案：手动SSH（仅当
`server exec`
不可用时使用）

Step 1: Get SSH credentials

步骤1：获取SSH凭证

Step 2: Connect

步骤2：建立连接

sshpass (only if already known to be available)

sshpass（仅当已知可用时使用）

Node.js ssh2 (the Zeabur agent sandbox has it pre-installed)

Node.js ssh2（Zeabur代理沙箱已预安装）

Tips

小贴士

zeabur-server-ssh

Original

Translation

Zeabur Server SSH + kubectl

Zeabur Server SSH + kubectl

Check which kind of server you are on before using kubectl

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

Run a command: server exec (recommended)

运行命令：server exec（推荐）

Single command

单个命令

Compound command — quote it as ONE argument so && / | stay intact

复合命令——将其作为单个参数引用，以保证&& / | 保持完整

Common kubectl Commands

常用kubectl命令

Fallback: manual SSH (only if server exec is unavailable)

备选方案：手动SSH（仅当server exec不可用时使用）

Step 1: Get SSH credentials

步骤1：获取SSH凭证

Step 2: Connect

步骤2：建立连接

sshpass (only if already known to be available)

sshpass（仅当已知可用时使用）

Node.js ssh2 (the Zeabur agent sandbox has it pre-installed)

Node.js ssh2（Zeabur代理沙箱已预安装）

Tips

小贴士

Run a command:
`server exec`
(recommended)

运行命令：
`server exec`
（推荐）

Fallback: manual SSH (only if
`server exec`
is unavailable)

备选方案：手动SSH（仅当
`server exec`
不可用时使用）