齐治堡垒机桥接器 AFAP/plugin-bastion-bridge-qizhi

齐治堡垒机 SSH 桥接器 · Qizhi Bastion SSH Bridge

中文 · English

让 AI 通过 RESTful API 接管齐治堡垒机里的服务器。
把「只能在专用 exe 客户端里点来点去」的运维操作，变成任何程序都能调用的本地接口。

两种玩法，各取所需：

| 你的身份 | 接入方式 |
| 🎯 DeepSeek Harness 用户 | 一行命令安装技能插件；需要操作服务器时，在对话中输入 /bastion-qizhi 手动唤起 |
| 🌐 任何 AI / Agent / 脚本 | 桥接器本质是本地 RESTful API（HTTP / SSE / WebSocket），本文档就是完整 API 说明——只要能发 HTTP 请求的 AI 都能接入（DeepSeek、Claude Code、Cursor、自研 Agent、curl 脚本……），与语言和框架无关 |

1. 它解决了什么问题

齐治堡垒机的 Web 控制台点击 SSH 资源时，只能唤起 putty.exe 等人机交互式终端——人可以看到屏幕敲命令，但 AI 程序无法稳定地发送命令并拿到结构化返回结果，于是「让 AI 运维服务器」始终差最后一公里。

本项目把 putty.exe 替换为一个专用桥接器：

1. 齐治控制台照常唤起 putty.exe（兼容 PuTTY 风格传参）；
2. 桥接器解析目标主机/端口/账号/口令，用 Paramiko 建立 SSH 连接；
3. 在本机 127.0.0.1 启动一个 HTTP/WebSocket API；
4. AI 助手通过 REST 接口执行命令、流式查看输出、发送交互输入——像亲手敲命令一样运维服务器。

┌──────────────┐ 唤起并传参 ┌───────────────────┐ SSH ┌──────────────┐ │ 齐治堡垒机 │ ───────────▶ │ 桥接器 putty.exe │ ───────────▶ │ 目标服务器 │ │ Web 控制台 │ │ (本项目构建产物) │ │ (Linux/Unix) │ └──────────────┘ └─────────┬─────────┘ └──────────────┘ │ 127.0.0.1:<端口> │ HTTP / SSE / WebSocket ┌────────▼─────────┐ │ AI 助手 / 脚本 │
│ (DeepSeek 等) │
└──────────────────┘

💡 API 是唯一的接入契约：桥接器不绑定任何特定 AI。无论 AI 跑在哪个框架里，只要它能调用 POST /execute、GET /stream、POST /input（完整说明见第 7 节与 docs/通用桥接器使用说明.md），就能立刻运维目标服务器。
DeepSeek Harness 技能插件只是把这份 API 说明书「翻译」成了该平台的技能格式。

2. 功能特性

- ✅ 单一 EXE、免安装：PyInstaller 单文件打包，直接替换原 putty.exe 即可，无需管理员权限运行
- ✅ 兼容齐治传参：支持 PuTTY 显式参数、-load 临时会话文件（\、=、: 三种格式自动解析）
- ✅ 兼容老旧服务器：内置旧版 KEX/加密/MAC 算法（group14-sha1、3des-cbc、hmac-sha1 等）
- ✅ 默认交互 Shell 通道：齐治接入客户端经本地端口转发时 exec_command 常只回登录横幅，默认直接走持久 PTY shell；ssh_prefer_shell=false 可切回 exec 通道
- ✅ 完整 API：/health、/execute、/stream(SSE)、/input、/ws(Socket.IO)
- ✅ 端口自动发现：实际监听地址写入 active_port.txt，AI 免配置直接读取
- ✅ 空闲保活：默认空闲 3 分钟自动发无害命令防止断连；有指令在执行中（含长任务等返回）时自动顺延，不打扰
- ✅ 直观控制台：彩色标题 + 清晰分块，展示脱敏后的启动参数、版本、运行配置、连接状态、指令、退出码与服务器返回
- ✅ 安全默认：仅监听 127.0.0.1；命令与返回正文只在当前控制台预览，不写入日志文件
- ✅ DeepSeek Harness 技能插件：仅在输入 /bastion-qizhi 时加载，不自动注入模型上下文

3. 效果预览

| 场景 | 截图 |
| 在 DeepSeek Harness 对话中输入 /bastion-qizhi，手动唤起技能并执行 | |
| AI 通过桥接器 API 在目标服务器执行命令、拿到结构化结果 | |
| 用 Postman 调试本地 REST API（/health、/execute） | |

说明：示例中的 8766 为默认端口，实际端口以桥接器启动时写出的 active_port.txt 为准。

4. 目录结构

plugin-bastion-bridge-qizhi/
├── main.py # 入口：解析参数 → 建连 → 起 API ├── params.py # 齐治/PuTTY 参数解析 ├── ssh_client.py # SSH 引擎（Paramiko） ├── api_server.py # 本地 AI API（Flask + SocketIO） ├── connection.py # 连接参数数据类 ├── command_guard.py # 服务端内部模块 ├── config.py # 本地配置 ├── logger.py # 滚动日志 + 脱敏 ├── requirements.txt # 运行/构建依赖（已锁定版本，CI 可复现） ├── putty.spec # PyInstaller 打包配置 ├── tests/ # 单元测试（CI 执行 python -m unittest discover -s tests） ├── skill/bastion-qizhi/ # DeepSeek Harness 技能插件（安装后位于用户目录 ~\.dsh\skills\bastion-qizhi） │ ├── SKILL.md # 技能指令（AI 的操作手册） │ ├── scripts/bridge.py # AI 可调用的命令行客户端（纯标准库） │ └── references/ # API 参考 + 排错手册 ├── scripts/ │ ├── install.ps1 # 一键安装（技能插件 + 可选桥接器 EXE） │ └── uninstall.ps1 # 一键卸载/还原 ├── docs/ │ └── 通用桥接器使用说明.md # 面向使用者/AI 的通用桥接器接口使用说明 ├── screenshot/ # 效果截图（README「效果预览」用） └── .github/workflows/release.yml # 打 tag 自动构建 putty.exe 并发布 Release

5. 快速开始

5.1 一行命令安装 DeepSeek Harness 技能插件（推荐）

powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/AFAP/plugin-bastion-bridge-qizhi/main/scripts/install.ps1 | iex"

脚本会把技能包安装到 %USERPROFILE%\.dsh\skills\bastion-qizhi\（若设置了 DSH_HOME 则用 DSH_HOME）。
DeepSeek Harness 实时监听该目录，安装后无需重启：

- 在 DSH 对话中直接输入 /bastion-qizhi 唤起技能。
- 该技能不会自动进入模型目录或上下文；只有明确输入斜杠命令时才会加载。

5.2 同时部署桥接器 EXE（从 Release 下载）

本地克隆仓库后运行（可离线安装技能） powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -InstallBridge

脚本会：从最新 Release 下载 putty.exe → 备份原文件 → 替换到 C:\Program Files (x86)\QizhiTech\AccessClient\putty.exe（需要管理员权限时自动弹出 UAC）。

5.3 源码构建（开发者）

仓库不携带本地构建脚本与产物，编译由 GitHub Actions 自动完成：

- 打 tag（如 v1.1.0）→ Actions 在 Windows 环境按锁定的 requirements.txt 用 PyInstaller 构建 dist\putty.exe 并自动发布 Release（含 SHA-256 校验和）；
- 无 tag 时也可在 Actions 页面点 Run workflow 手动构建验证。

本地想跑一遍：python -m pip install -r requirements.txt 后执行 python -m PyInstaller putty.spec --clean --noconfirm，产物在 dist\putty.exe。

6. 部署（替换 putty.exe）

拿到 putty.exe（Release 下载或本地构建）后，用它覆盖齐治客户端目录中的原文件：

C:\Program Files (x86)\QizhiTech\AccessClient\putty.exe

6.1 ① 备份原文件（务必先做）

Copy-Item "C:\Program Files (x86)\QizhiTech\AccessClient\putty.exe" "C:\Program Files (x86)\QizhiTech\AccessClient\putty.exe.bak" -Force
使用 scripts\install.ps1 -InstallBridge 时会自动备份为 putty.exe.bak.<时间戳>，无需手动执行本步。

6.2 ② 覆盖部署

Copy-Item ".\dist\putty.exe" "C:\Program Files (x86)\QizhiTech\AccessClient\putty.exe" -Force

6.3 ③ 验证

在齐治控制台点击 SSH 资源 → 桥接器自动建立连接并启动 API；查看实际端口：%LOCALAPPDATA%\sshbridge\QizhiSSHBridge\active_port.txt。

6.4 想还原官方 putty.exe？

Copy-Item "C:\Program Files (x86)\QizhiTech\AccessClient\putty.exe.bak" "C:\Program Files (x86)\QizhiTech\AccessClient\putty.exe" -Force

或运行 scripts\uninstall.ps1 -RestoreBridge（自动从最新的 .bak 还原，需要管理员权限时自动提权）。

7. REST API 速查

| 操作 | 请求 |
| 健康检查 | GET /health |
| 执行命令 | POST /execute {"command": "df -h", "timeout": 30} |
| 流式输出(SSE) | GET /stream?command=dmesg%20%7C%20tail |
| 交互输入 | POST /input {"data": "y\n"} |
| WebSocket | ws://127.0.0.1:<端口>/ws（Socket.IO，事件 execute/stream/input） |

健康检查
curl http://127.0.0.1:8766/health

执行命令
curl -X POST http://127.0.0.1:8766/execute -H "Content-Type: application/json" -d '{"command": "uname -a"}'

响应：

{ "stdout": "Linux server 5.15.0 ...\n", "stderr": "", "exit_code": 0 }

完整接口文档见 docs/通用桥接器使用说明.md 与技能包内 references/api.md。

8. 配置项

配置文件：%LOCALAPPDATA%\sshbridge\QizhiSSHBridge\config.json（首次运行自动生成）

| 配置项 | 默认值 | 说明 |
| api_host | 127.0.0.1 | 切勿改为 0.0.0.0，否则局域网可调用 |
| api_port | 8766 | 被占用时自动顺延 8767、8768… |
| ssh_connect_timeout | 15 | SSH 握手超时（秒） |
| retry_max_attempts | 3 | 连接失败重试次数 |
| ssh_prefer_shell | true | 默认走持久交互 shell；设为 false 使用 exec 通道（要求服务器支持） |
| keepalive_enabled | true | 空闲保活开关 |
| keepalive_interval_seconds | 180 | 空闲多久触发保活（有指令在执行时顺延） |
| keepalive_command | ls | 保活命令（须无害） |
| log_level | INFO | DEBUG / INFO / WARNING / ERROR |
| log_max_bytes | 10485760 | 单日志文件上限（10MB） |
| log_backup_count | 5 | 滚动保留份数 |
| console_log | true | 是否显示彩色控制台状态、指令与返回预览 |
| console_verbose | false | 是否在控制台同时显示详细 INFO/DEBUG 技术日志 |
| console_output_limit | 12000 | 单个指令或输出字段的控制台预览上限；不影响 API 返回的完整数据 |

通道说明：默认 ssh_prefer_shell=true 时命令在 PTY 交互 shell 里执行，stderr 会合并进 stdout（JSON 里的 stderr 为空），退出码仍取自命令本身的 $?。需要区分两路输出时，把 ssh_prefer_shell 设为 false，但要求目标服务器真的支持 exec_command。

9. 日志与排错

日志：%LOCALAPPDATA%\sshbridge\QizhiSSHBridge\logs\bridge.log（滚动保留 5 份）

控制台用 >>> 标识收到的参数或指令，用 <<< 标识服务器返回，并展示来源、耗时、退出码以及 stdout/stderr 字符数。密码和交互输入正文始终隐藏；指令与返回正文仅显示在当前控制台，bridge.log 仍只记录长度、退出码和连接状态等元数据。

| 现象 | 排查方向 |
| 点击 SSH 没反应 | 检查 putty.exe 是否替换到正确路径 |
| API 连不通 | 看 active_port.txt 实际端口（可能已顺延） |
| /health 返回 connected: false | 看日志末尾：认证失败 / 网络不通 / 参数解析失败 |
| no acceptable kex algorithm | 已内置 Paramiko 2.12.0 兼容旧算法，若仍出现请提 Issue |

完整排错手册见 docs/通用桥接器使用说明.md 与技能包内 references/troubleshooting.md。

10. 安全与合规（务必阅读）

- 本项目替换 putty.exe 后会接管堡垒机下发的口令，请仅在被授权环境中部署。
- API 无鉴权但仅监听 127.0.0.1，本机任何进程均可调用——请勿在多人共用终端上运行。
- 口令、Token 与 API Key 参数会脱敏，命令与输出正文不写入日志文件。
- 交互 shell 模式下，命令正文会短暂写入目标机 mktemp 生成的临时脚本（权限 0600），执行后立即删除；这是为了隔开命令 stdin 与桥接器包装行。
- 控制台可能展示服务器业务输出；操作结束后请关闭窗口，不要截图或转发敏感内容。
- 详见 SECURITY.md。

11. FAQ

Q：杀毒软件报毒？ PyInstaller 单文件 EXE 常见误报，请加白名单，或用 python main.py <参数> 源码方式运行。

Q：支持哪些齐治版本？ 参数解析基于 PuTTY 兼容传参实现；若贵司版本传参不同，查看日志 Parsing argv: 行后在 params.py 增加分支即可（欢迎提 PR）。

Q：多个桥接器实例会冲突吗？ 不会。端口自动顺延，各自写入 active_port.txt，以文件为准。

Q：密码会不会泄漏？ 仅存在于进程内存；日志、to_dict() 诊断输出均脱敏为 ***。

12. 开发与构建

模块分层：入口 main.py → 参数 params.py → SSH 引擎 ssh_client.py → API api_server.py，对外 API 契约与 docs/通用桥接器使用说明.md 保持一致，适配其他堡垒机厂商时只需替换 params.py 并调整 main.py 的应用名/端口。

CI 发布流程：给仓库打 tag（如 v1.0.0）→ GitHub Actions 在 Windows 环境按锁定的 requirements.txt 构建 putty.exe → 自动发布到 Release（含 SHA-256 校验和）。
手动构建也可在 Actions 页面点 Run workflow。

13. 相关文档

- docs/通用桥接器使用说明.md —— 通用堡垒机桥接器接口使用说明（使用者/AI 视角）
- SECURITY.md —— 安全设计与风险告知
- README.en.md —— English version

14. License

MIT © plugin-bastion-bridge-qizhi contributors

免责声明：本工具仅供授权运维、安全测试与学习研究使用。使用者须保证对目标服务器及堡垒机环境拥有合法操作权限，因滥用造成的后果与项目维护者无关。