Simon
10 KiB
10 KiB
JumpServer Web CLI 自动化部署工具集
概述
通过 JumpServer Luna Web 终端的浏览器自动化（Playwright），实现在目标服务器上自动执行命令行操作、文件上传下载等自动化部署、测试、维护能力。
核心架构
┌──────────────────────────────────────────────────────────────┐
│ 本地 (Windows/PowerShell) │
│ ┌─────────────────┐ ┌──────────────────────────────────┐ │
│ │ gen-deploy-*.py │──▶│ 生成 base64 编码的命令 + 载荷 │ │
│ │ gen-single-shot │ │ 输出到 webcli_*.sh │ │
│ └─────────────────┘ └──────────┬───────────────────────┘ │
│ │ │
│ ┌────────────────────────────────▼───────────────────────┐ │
│ │ jumpserver_webcli_v7.py │ │
│ │ Playwright 浏览器自动化 │ │
│ │ ┌──────────────────────────────────────────────────┐ │ │
│ │ │ 1. 打开 JumpServer URL │ │ │
│ │ │ 2. 自动登录 (密码 + OTP) │ │ │
│ │ │ 3. 导航到目标资产 (10.90.5.110) │ │ │
│ │ │ 4. 在 Web 终端中执行命令 │ │ │
│ │ │ 5. 截图 + 保存输出 │ │ │
│ │ └──────────────────────────────────────────────────┘ │ │
│ └───────────────────────┬───────────────────────────────┘ │
└──────────────────────────┼──────────────────────────────────┘
│ HTTPS
┌──────────────────────────▼──────────────────────────────────┐
│ JumpServer (jumpserver.dc.servyou-it.com) │
│ Luna Web Terminal ──▶ 税友集团 ──▶ hz-oa-ai-g-dataquery │
│ │ │
│ 10.90.5.110 │
│ ┌──────────┐ │
│ │ Docker │ │
│ │ wecom_it │ │
│ │ _backend │ │
│ └──────────┘ │
└──────────────────────────────────────────────────────────────┘
核心文件清单
本地命令生成器（项目内）
| 文件 | 用途 |
|---|---|
deploy-staging/gen-deploy-commands.py |
生成分步部署命令（Part A/B） |
deploy-staging/gen-single-shot.py |
生成单次执行命令 |
deploy-staging/gen-deploy-commands-bash.py |
Bash 版本生成器 |
deploy-staging/hotfix-*/webcli_*.sh |
生成的 Web CLI 命令脚本 |
deploy-staging/hotfix-*/run_v7_*.py |
Playwright 自动化编排脚本 |
deploy-staging/hotfix-120-qrcode-auto-confirm/upload_chunks_sftp.py |
SFTP 分块上传 |
Web CLI 自动化引擎（用户技能目录）
| 文件 | 用途 |
|---|---|
~/.workbuddy/skills/jumpserver-automation/scripts/jumpserver_webcli_v7.py |
当前主力：Playwright Web CLI 自动化 |
~/.workbuddy/skills/jumpserver-automation/scripts/probe_xterm_buffer_v2.py |
xterm.js 缓冲区探测：5 种方法测试结构化输出捕获 |
~/.workbuddy/skills/jumpserver-automation/scripts/jumpserver_webcli_v6.py |
v6 版本（支持超时等待） |
~/.workbuddy/skills/jumpserver-automation/scripts/jumpserver_webcli_v5.py |
v5 版本 |
~/.workbuddy/skills/jumpserver-automation/scripts/jumpserver_webcli_probe.py |
初始探测脚本 |
~/.workbuddy/skills/jumpserver-automation/scripts/jumpserver_config.py |
跳板机配置 |
部署命令示例（各 hotfix 目录）
| 目录 | 用途 |
|---|---|
deploy-staging/hotfix-116-qrcode-scan-get/ |
扫码获取热修复（v1-v4 webcli） |
deploy-staging/hotfix-120-qrcode-auto-confirm/ |
扫码自动确认热修复（v5 webcli，含 SFTP） |
deploy-staging/hotfix-48-nginx-upstream/ |
Nginx upstream 修复 |
deploy-staging/hotfix-sso-enabled/ |
SSO 启用热修复 |
技术演进历史
演进路线
v1-v6: SSH/plink 直接连接
├─ v1-v7: Paramiko SSH 库 (Python)
│ └─ 问题：堡垒机菜单导航不可靠，认证流程复杂
├─ v8-v10: plink.exe (PuTTY CLI)
│ └─ 问题：输出捕获不稳定，中文编码问题
├─ v11-v16: wexpect (Windows expect)
│ └─ 问题：交互式菜单匹配不稳定，超时控制困难
└─ 所有 SSH 方法共同问题：
├─ 双因素认证（密码+OTP）流程脆弱
├─ 堡垒机菜单导航需要精确的 expect 匹配
└─ 网络不稳定时重连复杂
v7+: Web CLI (Playwright 浏览器自动化) ✅ 当前方案
├─ webcli_probe: 探测 JumpServer Luna 终端的 Web 结构
├─ webcli_v1-v3: 基本登录 + 命令执行
├─ webcli_v4-v5: 增加 OTP 自动填充、截图验证
├─ webcli_v6: 增加超时等待、错误重试
└─ webcli_v7: 当前生产版本
优势：
├─ 绕过 SSH 认证复杂性，直接操作浏览器
├─ 可视化确认执行结果（截图）
├─ 支持长命令输入（>10KB base64 载荷）
├─ SFTP 文件上传（set_input_files）
└─ 稳定的 OTP 自动填充
v17 (开发中): SSH Key 认证
└─ generate_ssh_keys.py + jumpserver_auto_v17_key_auth.py
目标：完全自动化，无需浏览器
状态：概念验证阶段
API 方式（探索中）
└─ create_connection_token.py, test_connection_token.py
目标：通过 JumpServer API 获取 WebSocket token
状态：API 可用但 Koko 终端协议未完全理解
关键经验教训
-
不要走 SSH 直接连接路径：JumpServer 的堡垒机菜单 + OTP 双重认证使得 SSH 自动化极其脆弱。Web CLI 通过浏览器绕过这些问题。
-
base64 编码大文件传输：单次 Web CLI 输入约 10-15KB 安全上限。超过需分块（chunk_a 到 chunk_h），每块 ~3-4KB base64。
-
分阶段执行：部署应分 Part 1（文件传输）+ Part 2（部署执行）+ Part 3（验证），每阶段独立运行，便于定位问题。
-
OTP 双回车问题：发送 OTP 验证码后，某些情况下需要按 2 次回车才能触发验证流程（
test_double_enter.py记录了此发现）。 -
编码一致性：所有 .sh 文件必须 UTF-8 编码（
webcli_v3_cmd.utf8.sh），否则 Web CLI 终端可能乱码。 -
等待策略：Docker 操作后必须
sleep 8以上等待容器重启，否则docker ps和 curl 验证会失败。
使用流程
标准部署流程
# 1. 生成部署命令
cd deploy-staging
python gen-deploy-commands.py # 生成 part_a.txt / part_b.txt
# 2. (可选) 生成 webcli shell 脚本
python gen-single-shot.py # 生成 single_shot_cmd.txt
# 3. 通过 Playwright Web CLI 执行
cd C:\Users\simon\.workbuddy\skills\jumpserver-automation\scripts
python jumpserver_webcli_v7.py -c (Get-Content D:\...\webcli_v5_cmd.sh -Raw)
文件上传流程（SFTP 模式）
# 使用 webcli_v7 的 SFTP 功能上传
python upload_chunks_sftp.py
# 自动将 chunk_a 到 chunk_h 上传到 /tmp/qrcode_v5/
部署命令生成器说明
gen-deploy-commands.py
- 功能：读取本地 shell 脚本，base64 编码后嵌入 Web CLI 命令
- 输入：
hotfix-qrcode-step5.sh+backend/app/config.py - 输出：
/tmp/deploy-step5/part_a.txt+part_b.txt - Part A：写文件 + 执行部署脚本（前台等待结果）
- Part B：查看执行日志 + curl 验证
gen-single-shot.py
- 功能：将所有操作合并为单条命令（用
;连接） - 优势：一次粘贴，无需分步操作
- 限制：命令总长度受 Web CLI 输入框限制（~20KB）
任务清单（待办）
P0 - 紧急
- xterm.js 输出捕获分析 + probe_v2 探测脚本（2026-06-25）
- 运行 probe_xterm_buffer_v2.py 确认缓冲区访问方式
- 实现 webcli_v8.py（结构化缓冲区读取，替代截图验证）
- 将 jumpserver_webcli_v7.py 路径从硬编码改为项目相对路径
- 创建 webcli 健康检查脚本（检测 JumpServer 页面是否可访问）
P1 - 重要
- 封装 deploy-webcli 为独立 Python 包（pip install）
- 实现 Web CLI 命令队列（批量执行 + 结果收集）
- 集成 OTP 自动获取到 webcli_v7（当前需手动获取）
- 迁移 gen-deploy-commands.py 中的硬编码路径到项目根路径
P2 - 改进
- SSH Key 认证方案验证（v17）
- JumpServer API Token 方式探索
- Web CLI 执行结果自动解析（正则提取 exit code）
- 告警集成：部署失败时企微通知
已知问题
deploy-server/目录未迁移（含部署包和 docker-compose，>500MB）- plink.exe 依赖 Windows 环境（无法跨平台）
- webcli_v7 需要 Chrome/Chromium 浏览器
- Playwright 浏览器实例需要 ~500MB 磁盘空间