┌──────────────────────────────────────────────────────────────┐
│                    本地 (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 磁盘空间

README.md Unescape Escape

JumpServer Web CLI 自动化部署工具集

概述

核心架构

核心文件清单

本地命令生成器（项目内）

Web CLI 自动化引擎（用户技能目录）

部署命令示例（各 hotfix 目录）

技术演进历史

演进路线

关键经验教训

使用流程

标准部署流程

文件上传流程（SFTP 模式）

部署命令生成器说明

gen-deploy-commands.py

gen-single-shot.py

任务清单（待办）

P0 - 紧急

P1 - 重要

P2 - 改进

已知问题

README.md