simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feature/message-reliability
wecom_it_smart_desk/jumpserver-webcli/README.md
T

193 lines
10 KiB
Markdown
Raw Permalink Normal View History

chore: 整理项目结构，清理归档文件，更新部署配置
2026-07-04 21:01:39 +08:00
# 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 磁盘空间
Reference in New Issue Copy Permalink