SSH Server Ops Toolkit
sshops 是一个跨平台 SSH 运维工具箱，用来做 SSH 诊断、密钥初始化、SSH config 修复、传输兜底和远程命令执行。它面向本地 Windows/macOS/Linux 机器，远端目标通常是 Linux、POSIX 服务器、跳板机、堡垒机和 HPC 登录节点。
它的核心原则很简单：在让人或 Agent 修改远端机器之前，先把 SSH 的最后一公里查清楚。
目录
项目定位
sshops 是工具优先、技能其次的仓库：
- 人可以直接在终端运行脚本；
- Codex 可以通过仓库内置插件和技能使用它；
- Claude Code 可以通过插件布局或独立 skill 布局使用它。
它不试图替代 SSH，而是把 SSH 常见失败拆成可检查的层：本地工具、网络链路、认证方式、SSH config、文件传输能力、Conda/Paramiko 兜底环境，以及 HPC/跳板机场景里的额外限制。
一眼看懂
| 你想做什么 | 命令 | 风险级别 |
|---|
| 诊断本地 SSH、网络、认证和传输准备情况 | doctor | 只读 |
创建或修复一个 ~/.ssh/config Host 配置块 | configure | 修改本地配置 |
| 用一次密码会话安装公钥 | bootstrap-key | 修改远端账号配置 |
| 在 OpenSSH 传输不稳定时复制文件 | transfer | 本地或远端文件写入 |
| 用一致的 JSON 包装方式运行远程命令 | run | 取决于具体命令 |
能解决什么问题
常见 SSH 失败很少只是“SSH 坏了”。sshops 会帮助你区分这些情况：
- 本地
ssh、scp、sftp 缺失，或 PATH 上拿到的不是预期工具；
- TCP 链路、VPN、防火墙、端口或跳板路径不通；
- 交互式登录可用，但
BatchMode 公钥认证失败；
ssh 能登录，但 scp 或 sftp 传输不稳定；~/.ssh/config 里的 host、user、port、identity file 或认证策略写错；- 登录节点、跳板机、堡垒机、Slurm/HPC 集群和普通服务器需要不同操作流程。
核心功能
doctor：先诊断，后动手
doctor 是推荐的第一步。它会输出 JSON 报告，包含 local_tools、network、auth、transfer、python_env、likely_root_cause 和 recommended_next_step 等字段，方便人和 Agent 都能基于证据行动。
configure：修复 SSH config
configure 会写入或替换指定 alias 的 Host 配置块，避免手动编辑 ~/.ssh/config 时留下重复配置、错别字或错误密钥路径。
bootstrap-key：用一次密码会话安装公钥
当远端暂时只能密码登录时，bootstrap-key 可以通过本地环境变量读取短期密码，安装公钥后再验证公钥登录。不要把密码、Token、私钥或 MFA 码粘贴到聊天窗口、README 或日志里。
transfer：传输失败时的 Paramiko 兜底
优先使用原生 scp 或 sftp。当 OpenSSH 传输不可用或不稳定时，transfer 提供基于 Paramiko SFTP 的上传/下载兜底路径。
run：可复现的远程命令执行
run 用 OpenSSH 执行远程命令，可指定 alias、远程目录、Bash 包装和 BatchMode，适合先跑只读检查，再逐步执行更高风险操作。
平台支持
| 本地机器 | 推荐入口 | 说明 |
|---|
| Windows | powershell -ExecutionPolicy Bypass -File .\scripts\sshops.ps1 ... | 保留 Windows 优先流程和 OpenSSH ACL 修复能力。 |
| Windows | python .\scripts\sshops.py ... | 使用跨平台 Python CLI。 |
| macOS | python3 ./scripts/sshops.py ... | 需要 PATH 上有 OpenSSH 客户端工具。 |
| Linux | python3 ./scripts/sshops.py ... | 需要 PATH 上有 OpenSSH 客户端工具。 |
远端目标预期是 Linux、POSIX、gateway、bastion 或 HPC 登录节点。本项目不是 Windows Remoting 或 RDP 工具箱。
环境要求
必需：
- PATH 上存在 OpenSSH 客户端工具：
ssh、scp、sftp；
- Python 3.10 或更新版本，用于跨平台 CLI。
可选：
- Windows PowerShell 5.1+，或用于验证的 PowerShell Core；
tar，用于 tar-over-SSH 同步模式；- Conda 或其他带
paramiko 的 Python 环境，用于 bootstrap-key 和 transfer。
安装和验证
git clone https://github.com/Xiaoyun-0922/sshops.git
cd sshops
python scripts/validate-toolkit.py
Windows 上也可以运行原始 PowerShell 验证器：
git clone https://github.com/Xiaoyun-0922/sshops.git
cd sshops
powershell -ExecutionPolicy Bypass -File .\scripts\validate-toolkit.ps1
快速开始
1. 不保存 SSH config，先做诊断
macOS/Linux：
python3 ./scripts/sshops.py doctor \
--host-name login.example.edu \
--port 22 \
--user alice
Windows：
powershell -ExecutionPolicy Bypass -File .\scripts\sshops.ps1 doctor `
-HostName login.example.edu `
-Port 22 `
-User alice
2. 保存一个可复用 host alias
macOS/Linux：
python3 ./scripts/sshops.py configure \
--alias gpu-login \
--host-name login.example.edu \
--port 22 \
--user alice \
--identity-file ~/.ssh/id_ed25519_gpu \
--preferred-authentications publickey
Windows：
$keyPath = Join-Path $HOME ".ssh\id_ed25519_gpu"
powershell -ExecutionPolicy Bypass -File .\scripts\sshops.ps1 configure `
-Alias gpu-login `
-HostName login.example.edu `
-Port 22 `
-User alice `
-IdentityFile $keyPath `
-PreferredAuthentications publickey
3. 通过 alias 重新诊断
macOS/Linux：
python3 ./scripts/sshops.py doctor --alias gpu-login
Windows：
powershell -ExecutionPolicy Bypass -File .\scripts\sshops.ps1 doctor -Alias gpu-login
4. 运行一个远程命令
macOS/Linux：
python3 ./scripts/sshops.py run \
--alias gpu-login \
--remote-dir ~/repo \
--command "git status --short" \
--bash \
--batch-mode
Windows：
