gssh: SSH Session Manager

---

name: use-gssh description: "Manage SSH sessions with gssh CLI for agents" allowed-tools: Read, Write, Glob, Grep, Bash version: 1.0.0

设计原则：完全非交互、纯脚本化。所有密码和参数通过命令行传递，不支持交互式操作。

安装

npm install -g @zzzwy/gssh
# 更新
gssh update

启动

# 放后台启动
gssh-daemon &

# 推荐使用pm2 管理
pm2 start gssh-daemon --name gssh

连接认证

# 使用密码
gssh connect -u user -h host -p port -P "password"

# SSH 密钥
gssh connect -u user -h host -i ~/.ssh/id_ed25519

核心命令

| 命令 | 说明 | | --------------- | ---------------- | | connect | 建立 SSH 连接 | | exec | 执行命令 | | scp / sync | 文件传输与同步 | | sftp | SFTP 操作 | | forward | 端口转发 | | forwards | 列出所有端口转发 | | forward-close | 关闭端口转发 | | list | 列出 session | | use | 切换默认 session |

执行命令

# 普通命令
gssh exec "ls -la"

# 指定 session
gssh exec -s <session_id> "pwd"

# 带超时命令（秒）
gssh exec -t 10 "ls -la"

# 后台运行（推荐格式）
gssh exec "nohup python3 app.py > /dev/null 2>&1 &"

# sudo 命令
gssh exec --sudo --sudo-password "your-password" "sudo systemctl restart nginx"

# sudo 以其他用户运行
gssh exec --sudo --sudo-password "your-password" --sudo-user "www-data" "whoami"

# sudo login shell
gssh exec --sudo --sudo-password "your-password" --sudo-login "whoami"

文件传输

# 上传本地文件/文件夹 -> 远程
gssh scp -put local.txt /remote/path/
gssh sync -put local_dir /remote/path/

# 下载远程文件/文件夹 -> 本地
gssh scp -get /remote/file.txt ./
gssh sync -get /remote/dir ./

# SFTP 目录操作
gssh sftp -c ls -p /home/user
gssh sftp -c mkdir -p /home/user/newdir
gssh sftp -c rm -p /home/user/file.txt

端口转发

# 本地转发: localhost:8080 -> remote:80
gssh forward -l 8080 -r 80

# 远程转发: remote:9000 -> localhost:3000
gssh forward -R -l 9000 -r 3000

# 列出所有端口转发
gssh forwards

# 关闭端口转发
gssh forward-close <forward_id>

Session 管理

gssh list                    # 列出所有 session
gssh use <session-id>        # 切换默认 session
gssh disconnect             # 断开
gssh reconnect -s <id>     # 重连

选项汇总

| 选项 | 说明 | | ----------------- | ---------------------- | | -s | session ID | | -u | 用户名 | | -h | 主机地址 | | -p | 端口（默认 22） | | -P | SSH 密码 | | -i | SSH 密钥 | | -l | 本地端口 | | -r | 远程端口 | | -R | 远程端口转发 | | -put/-get | 上传/下载 | | -t | 超时（秒） | | --sudo | 启用 sudo 模式 | | --sudo-password | sudo 密码 | | --sudo-user | 以指定用户运行 sudo | | --sudo-login | sudo login shell（-i） |

限制与注意事项

sudo 限制

• 密码不能包含单引号：--sudo-password 中包含单引号会破坏 shell 语法
• 交互式命令不支持：sudo vim、sudo less、sudo -i（无密码）等需要 TTY 的命令不支持
• sudo 缓存：sudo 有默认 15 分钟的密码缓存，相同 session 内后续 sudo 命令无需重复输入密码

exec 命令限制

• 不支持交互式命令：vim、less、top、nano 等需要终端的交互式程序无法使用
• 密码暴露：密码通过命令行传递，在 ps aux 等命令中可能可见，请确保系统安全
• 管道命令需加引号：含 |、&&、||、>、<、换行等特殊字符的命令需整体加引号

可靠性说明

• 超时机制：-t 超时触发后，远端进程会被 SIGKILL 终止，当前连接立即可用于下一条命令，不需要重启 daemon
• 自动重连：连接断开后每 5 秒自动检测并重连，死连接（含网络分区场景）5 秒内可感知
• 大命令支持：exec 命令长度无 4096 字节限制，传输文件路径、长脚本均可正常工作