kssh 完整使用手册

kssh 完整使用手册#

7 个 SSH 子命令 + 60 个宝塔子命令的完整 API 参考 + 实战 playbook

一、SSH 子命令 (7 个)#

kssh exec <target> -- <cmd>#

远程执行命令。target 格式 user@host,-- 后是要跑的 shell 命令(可多次)。

# 单条命令
kssh exec root@139.224.208.63 -- df -h

# 复杂命令 (bash -c 包裹)
kssh exec root@139 -- bash -c 'cd /tmp && tar xzf app.tgz && ./install.sh'

# 多条命令
kssh exec root@139 -- bash -c "systemctl restart nginx && curl localhost"

注意: shell 走 bash 解释, 引号用 \" 转义, 或者用 cat > /tmp/script.sh && kssh put 上传脚本后再 bash /tmp/script.sh。

kssh put <target> <local> <remote>#

上传文件或目录。

kssh put root@139 /tmp/app.tgz /www/wwwroot/app/app.tgz       # 单文件
kssh put root@139 ./dist/ /var/www/html/                       # 递归目录
kssh put root@139 /tmp/x /tmp/x --preserve                     # 保留 mtime

kssh get <target> <remote> <local>#

下载文件或目录。

kssh get root@139 /etc/nginx/nginx.conf ./nginx.conf
kssh get root@139 /var/log/nginx/ ./logs/                      # 递归
kssh get root@139 /tmp/x.tgz ./x.tgz --preserve                # 保留 mtime

kssh ls <target> <path>#

列远程目录, 类 ls -la。

kssh ls root@139 /www/wwwroot/
kssh ls root@139 /var/log/ --depth=3

kssh cp <target> <src> <dst>#

远程拷贝, 走 SFTP 协议。

kssh cp root@139 /tmp/a.log /var/log/b.log
kssh cp root@139 /etc/nginx/ /etc/nginx.bak/                  # 整目录

kssh which <target> <bin>#

查远程命令路径, 走 which/type -a/command -v。

kssh which root@139 python3
# → /www/server/python_manager/versions/3.9.25/bin/python3
# → /usr/bin/python3

kssh ping <target>#

快速测连 + 主机信息(OS / 内核 / uptime / 内存 / CPU)。

kssh ping root@139.224.208.63

二、宝塔子命令 (60 个, 9 大类)#

1. 系统总览 (7)#

2. 软件 / 服务 (5)#

3. 站点 (19)#

4. 数据库 (4)#

5. FTP (4)#

6. SSL 证书 (5)#

7. 防火墙 / SSH (6)#

8. 文件 / Shell (15)#

9. 计划任务 (3)#

10. 通用 raw#

# 任何 BT API 都能用
kssh bt $PANEL raw /site 'action=GetSiteDomains&webname=api.z.h3hu.com'
kssh bt $PANEL raw /files 'action=GetFileBody&path=/etc/nginx/nginx.conf'

raw 走 form POST, k=v 形式拼到 ?action= 后。

三、部署实战 playbook#

场景 1: 部署一个 Python 项目 (FastAPI/Django/Flask)#

PANEL=http://139.224.208.63:23010
PROJ=kus-fastapi
PORT=8765

# 1. 建站 (静态类型即可, 我们用 systemd)
kssh bt $PANEL site-add $PROJ.z.h3hu.com /www/wwwroot/$PROJ.z.h3hu.com --kind=Python --php-ver=00 --ps=老六FastAPI

# 2. 防火墙放行
kssh bt $PANEL fw-add $PORT --ps=$PROJ

# 3. 推代码 (排除 venv, 77MB 别传)
cd /home/projects/my-fastapi
tar czf /tmp/$PROJ.tgz --exclude=venv --exclude=__pycache__ --exclude=.env .
kssh put root@139 /tmp/$PROJ.tgz /www/wwwroot/$PROJ.z.h3hu.com/$PROJ.tgz

# 4. 远程装
kssh exec root@139 -- bash -c "cd /www/wwwroot/$PROJ.z.h3hu.com && tar xzf $PROJ.tgz && python3 -m venv venv && venv/bin/pip install -r requirements.txt"

# 5. systemd 守护
kssh put root@139 /tmp/$PROJ.service /etc/systemd/system/$PROJ.service
kssh exec root@139 -- bash -c "systemctl daemon-reload && systemctl enable --now $PROJ"

# 6. 配反代 (走宝塔 conf-set)
cat > /tmp/$PROJ.conf <<EOF
server { listen 80; listen 443 ssl http2; server_name $PROJ.z.h3hu.com;
  ssl_certificate /www/server/panel/vhost/cert/$PROJ.z.h3hu.com/fullchain.pem;
  ssl_certificate_key /www/server/panel/vhost/cert/$PROJ.z.h3hu.com/privkey.pem;
  location / { proxy_pass http://127.0.0.1:$PORT; proxy_set_header Host \$host; }
  location ~ \\.well-known { allow all; }
  include /www/server/panel/vhost/nginx/well-known/$PROJ.z.h3hu.com.conf;
}
EOF
kssh put root@139 /tmp/$PROJ.conf /tmp/$PROJ.conf
kssh bt $PANEL conf-set $PROJ.z.h3hu.com --file /tmp/$PROJ.conf
kssh bt $PANEL re-web

# 7. 申请 SSL
kssh bt $PANEL lets-encrypt $PROJ.z.h3hu.com --method=http
# 把 cert 拷贝到宝塔 cert 目录
kssh exec root@139 -- python3 -c "import shutil,os; s='/www/server/panel/vhost/letsencrypt/$PROJ.z.h3hu.com'; d='/www/server/panel/vhost/cert/$PROJ.z.h3hu.com'; os.makedirs(d,exist_ok=True); [shutil.copy(f'{s}/{f}',d) for f in ['privkey.pem','fullchain.pem']]"
# 重启 nginx
kssh exec root@139 -- bash -c "nginx -s reload"

场景 2: 整站下线 (清干净)#

PANEL=http://139.224.208.63:23010
SITE=kus-fastapi.z.h3hu.com

# 1. 拿站点 id
SITE_ID=$(kssh exec root@139 -- /usr/local/bin/kssh bt $PANEL sites 2>/dev/null | grep -oP "$SITE\K.*?(?= )" | head -1)
# (或者看 sites 输出)

# 2. 删站点 (含 ftp/database/path)
kssh bt $PANEL site-del $SITE_ID $SITE --ftp --database --path

# 3. 删开放过的端口
kssh bt $PANEL fw-del 8765

场景 3: 一键看 139 全状态#

PANEL=http://139.224.208.63:23010
echo "=== 系统 ==="
kssh bt $PANEL system
kssh bt $PANEL disk
kssh bt $PANEL load
echo "=== 站点 ==="
kssh bt $PANEL sites
echo "=== 端口 ==="
kssh bt $PANEL fw-list
echo "=== 任务 ==="
kssh bt $PANEL cron-list

四、认证 / 签名 / 凭据#

签名算法#

request_token = md5( request_time + md5(api_sk) )

• request_time: 当前 unix 秒
• api_sk: /www/server/panel/config/api.json 的 token_crypt 字段(不是 key!)
• md5: 16 进制小写

凭据存放#

# 文件路径: ~/.config/kssh/bt/{host}.key
# {host} 规则: 冒号 : 换下划线 _, 点 . 保留
# 例: http://139.224.208.63:23010 → 139.224.208.63_23010.key
echo 'dRxPn1piHEICNBC6r11Kocbh9caCzZtA' > ~/.config/kssh/bt/139.224.208.63_23010.key
chmod 600 ~/.config/kssh/bt/139.224.208.63_23010.key

IP 白名单#

/www/server/panel/config/api.json 的 limit_addr 数组(支持 IP 或域名)。宝塔 11.8 必需配置才能用 API。

Cookie 持久化#

首次调用会 POST 登录拿 Set-Cookie, 存到 ~/.config/kssh/bt/{host}.cookie。后续自动带, 免重签。

五、踩坑清单#

六、源码 + 部署#

• 源码: /home/projects/kssh/
• Cargo 依赖: russh 0.44 / russh-sftp 2.3 / clap 4 / tokio / reqwest (rustls) / md5
• 编译: cargo build --release (7.1MB binary)
• 安装: cp target/release/kssh /usr/local/bin/kssh
• 版本: 0.1.0
• 总命令数: 7 (SSH) + 60 (BT) = 67