wecom_it_smart_desk/jumpserver-webcli/README.md

# 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 终端协议未完全理解
```

### 关键经验教训

1. **不要走 SSH 直接连接路径**：JumpServer 的堡垒机菜单 + OTP 双重认证使得 SSH 自动化极其脆弱。Web CLI 通过浏览器绕过这些问题。

2. **base64 编码大文件传输**：单次 Web CLI 输入约 10-15KB 安全上限。超过需分块（chunk_a 到 chunk_h），每块 ~3-4KB base64。

3. **分阶段执行**：部署应分 Part 1（文件传输）+ Part 2（部署执行）+ Part 3（验证），每阶段独立运行，便于定位问题。

4. **OTP 双回车问题**：发送 OTP 验证码后，某些情况下需要按 2 次回车才能触发验证流程（`test_double_enter.py` 记录了此发现）。

5. **编码一致性**：所有 .sh 文件必须 UTF-8 编码（`webcli_v3_cmd.utf8.sh`），否则 Web CLI 终端可能乱码。

6. **等待策略**：Docker 操作后必须 `sleep 8` 以上等待容器重启，否则 `docker ps` 和 curl 验证会失败。

## 使用流程

### 标准部署流程

```powershell
# 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 模式）

```powershell
# 使用 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 - 紧急
- [x] 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 磁盘空间