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

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

中文 · English

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

License: MIT
GitHub release (latest by date)
Build

两种玩法，各取所需：

| 你的身份 | 接入方式 |
|---|---|
| 🎯 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 等）
- ✅ 双通道执行：优先 exec_command，自动降级交互 shell，适配只允许 PTY 的受限服务器
- ✅ 完整 API：/health、/execute、/stream(SSE)、/input、/ws(Socket.IO)
- ✅ 端口自动发现：实际监听地址写入 active_port.txt，AI 免配置直接读取
- ✅ 空闲保活：默认 60 秒无命令自动发无害命令，防止堡垒机断连
- ✅ 直观控制台：彩色展示脱敏后的启动参数、连接状态、收到的指令、退出码与服务器返回
- ✅ 安全默认：仅监听 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            # 连接参数数据类
├── config.py                # 本地配置
├── logger.py                # 滚动日志 + 脱敏
├── requirements.txt         # 运行/构建依赖（已锁定版本，CI 可复现）
├── putty.spec               # PyInstaller 打包配置
├── 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 | 连接失败重试次数 |
| keepalive_enabled | true | 空闲保活开关 |
| keepalive_interval_seconds | 60 | 空闲多久触发保活 |
| 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 返回的完整数据 |

9. 日志与排错

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

控制台用 >>> 标识收到的参数或指令，用  源码方式运行。

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 —— 英文版

14. 许可证

MIT © plugin-bastion-bridge-qizhi contributors

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