chore: 整理项目结构，清理归档文件，更新部署配置
This commit is contained in:
Simon
@@ -0,0 +1,340 @@
|
||||
# JP-webcli 自动化部署工具 — 能力·限制·优化分析
|
||||
|
||||
> 分析日期：2026-06-25 | 基于 webcli_v7（Playwright Web CLI 方案）
|
||||
|
||||
---
|
||||
|
||||
## 一、现有能力矩阵
|
||||
|
||||
### 1.1 已验证的核心能力
|
||||
|
||||
| 能力 | 实现方式 | 可靠性 | 备注 |
|
||||
|------|---------|--------|------|
|
||||
| 自动登录 JumpServer | Playwright 填写表单 | ✅ 稳定 | 用户名 + 密码 |
|
||||
| OTP 双因素认证 | pyotp 自动生成 + 自动填写 | ✅ 稳定 | 发现"双回车"问题已修复 |
|
||||
| 资产列表导航 | 文本匹配 + ElementUI 按钮定位 | ✅ 稳定 | 依赖 DOM 结构 |
|
||||
| 连接对话框确认 | 多选择器回退 + JS fallback | ⚠️ 中等 | 7 种选择器兜底 |
|
||||
| Web 终端命令输入 | `keyboard.type()` + `Enter` | ✅ 稳定 | 支持 >10KB base64 载荷 |
|
||||
| SFTP 文件上传 | `set_input_files` | ⚠️ 中等 | 依赖 webkitdirectory 属性 |
|
||||
| 截图保存 | `page.screenshot()` | ✅ 稳定 | 用于人工验证 |
|
||||
| 分块 base64 传输 | 8 chunks × ~3-4KB | ✅ 稳定 | Hotfix#120 验证通过 |
|
||||
|
||||
### 1.2 已完成的部署验证
|
||||
|
||||
| Hotfix | 日期 | 关键验证 |
|
||||
|--------|------|---------|
|
||||
| #116 扫码获取 | 2026-06-22 | 首次 Web CLI 端到端部署 |
|
||||
| #120 扫码自动确认 | 2026-06-23 | SFTP 分块上传 + 29KB 源码部署 |
|
||||
| #48 Nginx Upstream | 2026-06-24 | 配置修复 + HTTPS 验证 |
|
||||
| SSO 单点登录 | 2026-06-25 | 环境变量注入 |
|
||||
|
||||
---
|
||||
|
||||
## 二、当前限制与已知问题
|
||||
|
||||
### 2.1 P0 — 输出捕获不可靠（当前焦点）
|
||||
|
||||
**问题描述：**
|
||||
- v7 使用 `terminal_page.keyboard.type()` 发送命令后，通过截图 + `.inner_html()` 读取输出
|
||||
- 截图需要人工观察，无法程序化判断执行成功/失败
|
||||
- DOM 文本提取 (`inner_html` / `text_content`) 依赖于 xterm.js 使用 **DOM 渲染器**；如果使用 Canvas/WebGL 渲染器，`.xterm-rows` 不存在
|
||||
|
||||
**失败模式：**
|
||||
```
|
||||
场景 A: xterm.js 使用 Canvas 渲染器
|
||||
→ .xterm-rows 不存在 → text_content() 返回空 → 输出丢失
|
||||
|
||||
场景 B: 命令输出超过可视区域
|
||||
→ inner_html() 只包含可视行 → 输出不完整
|
||||
|
||||
场景 C: 命令尚未执行完毕就读取
|
||||
→ 捕获到不完整输出 → 误判为成功/失败
|
||||
```
|
||||
|
||||
**解决方案（进行中）：** 见第三节 xterm.js 结构化捕获方案
|
||||
|
||||
### 2.2 P1 — 硬编码路径和配置
|
||||
|
||||
| 问题 | 影响 | 修复方向 |
|
||||
|------|------|---------|
|
||||
| 脚本路径硬编码在 `~/.workbuddy/skills/` | 无法在不同机器间移植 | 改为项目相对路径 |
|
||||
| `gen-deploy-commands.py` 中的容器名硬编码 | 容器名变化时部署脚本失效 | 参数化 |
|
||||
| OTP secret 存储在脚本目录 | 多项目共享困难 | 统一凭证管理 |
|
||||
|
||||
### 2.3 P1 — 缺乏执行结果自动判定
|
||||
|
||||
**当前行为：** 截图保存后由人工观察判断执行结果
|
||||
**期望行为：** 自动解析输出，判断 exit code、错误关键词、预期输出
|
||||
**阻塞因素：** 首先需要可靠的结构化输出捕获（P0）
|
||||
|
||||
### 2.4 P2 — 环境依赖
|
||||
|
||||
| 依赖 | 影响 |
|
||||
|------|------|
|
||||
| Chrome/Chromium 浏览器 | 无法在无 GUI 服务器上运行 |
|
||||
| Playwright (~500MB) | 首次安装磁盘占用大 |
|
||||
| Windows 系统 | `keyboard.type()` 依赖系统键盘布局 |
|
||||
| JumpServer 页面 DOM 结构 | ElementUI 版本升级可能破坏选择器 |
|
||||
|
||||
### 2.5 P2 — 缺乏健康检查和告警
|
||||
|
||||
- 无 JumpServer 页面可达性检查
|
||||
- 部署失败无企微通知
|
||||
- 无命令执行超时后的自动重试策略
|
||||
|
||||
---
|
||||
|
||||
## 三、xterm.js 结构化输出捕获方案（v8 设计）
|
||||
|
||||
### 3.1 核心原理
|
||||
|
||||
xterm.js 内部维护一个**行缓冲区**（`terminal.buffer.active`），所有终端输出都以结构化形式存储在此缓冲区中。通过 Playwright 的 `page.evaluate()` 可以直接访问该缓冲区。
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ xterm.js 架构 │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────────────────┐ │
|
||||
│ │ 输入事件 │───▶│ Terminal.write() │ │
|
||||
│ │ keyboard │ │ Terminal.writeln() │ │
|
||||
│ └──────────┘ └──────────┬───────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────────┐ │
|
||||
│ │ Buffer (内部) │ │
|
||||
│ │ ┌────────────────────────────────┐ │ │
|
||||
│ │ │ buffer.active (主缓冲区) │ │ │
|
||||
│ │ │ - getLine(y) → BufferLine │ │ │
|
||||
│ │ │ - translateToString() → str │ │ │
|
||||
│ │ │ - length, baseY, cursorX/Y │ │ │
|
||||
│ │ └────────────────────────────────┘ │ │
|
||||
│ │ ┌────────────────────────────────┐ │ │
|
||||
│ │ │ buffer.normal (回滚缓冲区) │ │ │
|
||||
│ │ └────────────────────────────────┘ │ │
|
||||
│ └──────────────┬───────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────────┐ │
|
||||
│ │ 渲染器 (Renderer) │ │
|
||||
│ │ ┌──────────┐ ┌──────────────────┐ │ │
|
||||
│ │ │ DOM 渲染 │ │ Canvas/WebGL渲染 │ │ │
|
||||
│ │ │ .xterm- │ │ <canvas> 元素 │ │ │
|
||||
│ │ │ rows │ │ │ │ │
|
||||
│ │ └──────────┘ └──────────────────┘ │ │
|
||||
│ └──────────────────────────────────────┘ │
|
||||
│ ↑ v7 从这里读文本 │
|
||||
│ ┌────────────────────────────────────┐ │
|
||||
│ │ v8 从这里读文本 → buffer.active │ │
|
||||
│ └────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**关键优势：** 无论 xterm.js 使用哪种渲染器（DOM/Canvas/WebGL），缓冲区始终可用——这是 xterm.js 的核心数据结构，不依赖渲染层。
|
||||
|
||||
### 3.2 探测脚本（已创建）
|
||||
|
||||
**文件：** `~/.workbuddy/skills/jumpserver-automation/scripts/probe_xterm_buffer_v2.py`
|
||||
|
||||
**运行方式：**
|
||||
```powershell
|
||||
cd $env:USERPROFILE\.workbuddy\skills\jumpserver-automation\scripts
|
||||
& "C:\Users\simon\.workbuddy\binaries\python\versions\3.13.12\python.exe" probe_xterm_buffer_v2.py
|
||||
```
|
||||
|
||||
**探测内容：**
|
||||
1. **全局 xterm 实例**：搜索 `window` 上的 Terminal 实例 (`_core`, `buffer`, `options` 等特征属性)，读 `buffer.active`
|
||||
2. **DOM .xterm-rows 结构**：遍历 `.xterm-rows > div > span`
|
||||
3. **辅助 textarea**：读取 `.xterm-helper-textarea`
|
||||
4. **渲染器检测**：判断 DOM vs Canvas 渲染器，检测 React Fiber
|
||||
5. **综合提取**：自动选择最佳方法并输出结构化文本
|
||||
|
||||
**输出文件：**
|
||||
- `webcli_output/probe_v2_pre_cmd.json` — 命令执行前探测
|
||||
- `webcli_output/probe_v2_results.json` — 综合结果
|
||||
- `webcli_output/probe_v2_output.txt` — 纯文本终端输出
|
||||
- `webcli_output/probe_v2_final.png` — 截图对照
|
||||
|
||||
### 3.3 预期结果与应对策略
|
||||
|
||||
| 探测结果 | 含义 | v8 策略 |
|
||||
|---------|------|---------|
|
||||
| `best_method = global_instance` | Terminal 实例在 window 上暴露 | ✅ 直接用 `buffer.active.getLine()` 读取 |
|
||||
| `best_method = dom_rows` | DOM 渲染器可用 | ⚠️ 可工作但依赖渲染器选择，降级为备用方案 |
|
||||
| `best_method = screen_textcontent` | 仅能通过 DOM 文本提取 | ❌ 需注入 Monkey Patch 拦截 `terminal.write()` |
|
||||
| `best_method = null` | 所有方法均失败 | ❌ 需 Monkey Patch 或重新评估方案 |
|
||||
|
||||
### 3.4 v8 输出捕获核心代码（预览）
|
||||
|
||||
```python
|
||||
def capture_terminal_output(page, wait_seconds=10):
|
||||
"""
|
||||
通过 xterm.js 缓冲区结构化捕获终端输出
|
||||
返回: { "text": str, "line_count": int, "method": str, "cols": int, "rows": int }
|
||||
"""
|
||||
page.wait_for_timeout(wait_seconds * 1000)
|
||||
|
||||
result = page.evaluate("""
|
||||
() => {
|
||||
// 策略1: 查找全局 Terminal 实例
|
||||
const xtermKeys = ['_core', 'buffer', 'options', 'cols', 'rows'];
|
||||
const allKeys = Object.getOwnPropertyNames(window);
|
||||
for (const key of allKeys) {
|
||||
try {
|
||||
const val = window[key];
|
||||
if (!val || typeof val !== 'object') continue;
|
||||
const matchCount = xtermKeys.filter(p => p in val).length;
|
||||
if (matchCount >= 3 && val.buffer && val.buffer.active) {
|
||||
const buf = val.buffer.active;
|
||||
const lines = [];
|
||||
const total = buf.length;
|
||||
const start = Math.max(0, total - Math.max(val.rows, 100));
|
||||
for (let y = start; y < total; y++) {
|
||||
try { lines.push(buf.getLine(y).translateToString(true)); }
|
||||
catch(e) { lines.push(''); }
|
||||
}
|
||||
return {
|
||||
method: 'buffer.active',
|
||||
text: lines.join('\\n'),
|
||||
line_count: lines.length,
|
||||
cols: val.cols,
|
||||
rows: val.rows,
|
||||
cursor: { x: buf.cursorX, y: buf.cursorY }
|
||||
};
|
||||
}
|
||||
} catch(e) {}
|
||||
}
|
||||
|
||||
// 策略2: DOM fallback
|
||||
const rowsEl = document.querySelector('.xterm-rows');
|
||||
if (rowsEl) {
|
||||
const lines = [];
|
||||
rowsEl.querySelectorAll(':scope > div').forEach(div => {
|
||||
let text = '';
|
||||
div.querySelectorAll('span').forEach(s => text += s.textContent || '');
|
||||
lines.push(text);
|
||||
});
|
||||
return { method: 'dom_rows', text: lines.join('\\n'), line_count: lines.length };
|
||||
}
|
||||
|
||||
return { method: 'none', text: '', line_count: 0 };
|
||||
}
|
||||
""")
|
||||
|
||||
return result
|
||||
```
|
||||
|
||||
### 3.5 Monkey Patch 方案（兜底）
|
||||
|
||||
如果 xterm.js 实例完全没有暴露在全局作用域，可以在 `page.goto()` 之后、终端加载之前注入拦截代码：
|
||||
|
||||
```python
|
||||
# 在页面加载时注入 Monkey Patch
|
||||
page.add_init_script("""
|
||||
// 拦截 xterm.js 的 write/writeln 方法
|
||||
const origDefineProperty = Object.defineProperty;
|
||||
let capturedOutput = [];
|
||||
|
||||
// 定时检查是否有 xterm 实例被创建
|
||||
const observer = new MutationObserver(() => {
|
||||
const term = document.querySelector('.xterm');
|
||||
if (term && term.__xterm_captured !== true) {
|
||||
term.__xterm_captured = true;
|
||||
// 通过终端 DOM 元素的内部引用获取 Terminal 实例
|
||||
// 这里的实现依赖具体的 JumpServer/Luna 版本
|
||||
}
|
||||
});
|
||||
observer.observe(document.body, { childList: true, subtree: true });
|
||||
|
||||
window.__xterm_output = () => capturedOutput.join('\\n');
|
||||
""")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、不适用的场景分析
|
||||
|
||||
### 4.1 Web CLI 方案本质局限
|
||||
|
||||
| 场景 | 为什么不适用 | 替代方案 |
|
||||
|------|------------|---------|
|
||||
| **完全无人值守 CI/CD** | Playwright 需要 GUI 浏览器，headless 模式不可靠（JumpServer 部分元素需要可视化渲染） | SSH Key 认证（v17）或 Koko API |
|
||||
| **大规模并行部署** | 每个浏览器实例 ~500MB 内存，并行 5+ 实例会耗尽资源 | Ansible/SSH 批量执行 |
|
||||
| **跨平台（macOS/Linux）** | `keyboard.type()` 受键盘布局影响；Chrome channel 名称不同 | 使用 `page.keyboard.insertText()` 替代 |
|
||||
| **网络不稳定环境** | Web CLI 依赖持久 WebSocket 连接，断连后需重新登录+MFA | SSH 自带重连机制更可靠 |
|
||||
| **非交互式后台任务** | Web CLI 本质是模拟人工操作，不适合长时间后台运行 | systemd timer / cron job |
|
||||
| **JumpServer 不可用时** | 整个方案的前提条件不成立 | 直接 SSH 到目标服务器（内网场景） |
|
||||
|
||||
### 4.2 截图方式的不适用场景
|
||||
|
||||
| 场景 | 失败原因 |
|
||||
|------|---------|
|
||||
| 终端输出超长（>1000行） | 截图只能捕获可视区域 |
|
||||
| 输出包含非 ASCII 字符渲染异常 | 截图无法提取文本内容用于程序判定 |
|
||||
| 颜色/格式区分的信息 | 截图后颜色信息丢失（除非用彩色截图） |
|
||||
| 需要 grep/正则匹配输出内容 | 截图是像素，无法进行文本搜索 |
|
||||
|
||||
---
|
||||
|
||||
## 五、优化路线图
|
||||
|
||||
### 近期（本周）
|
||||
|
||||
```
|
||||
[P0] probe_xterm_buffer_v2 运行 + 分析结果
|
||||
└→ 确认 xterm.js 缓冲区访问方式
|
||||
|
||||
[P0] webcli_v8: 结构化输出捕获
|
||||
├─ 用 buffer.active 替代 inner_html
|
||||
├─ 自动判断命令执行成功/失败
|
||||
└─ 输出保存为结构化 JSON
|
||||
|
||||
[P1] webcli_v8: 命令执行超时 + 重试
|
||||
├─ 等待策略从固定 sleep 改为轮询 buffer
|
||||
└─ 失败自动重试（最多 3 次）
|
||||
```
|
||||
|
||||
### 中期（本月）
|
||||
|
||||
```
|
||||
[P1] 路径参数化 + 配置文件
|
||||
├─ 所有硬编码路径→配置文件
|
||||
└─ gen-deploy-commands.py 容器名参数化
|
||||
|
||||
[P1] 部署结果企微通知
|
||||
└─ 成功/失败推送企微卡片消息
|
||||
|
||||
[P2] 健康检查脚本
|
||||
└─ JumpServer 页面可达性检测
|
||||
```
|
||||
|
||||
### 远期（探索）
|
||||
|
||||
```
|
||||
[P2] SSH Key 认证方案 (v17)
|
||||
└─ 完全无人值守自动化
|
||||
|
||||
[P2] JumpServer Koko API
|
||||
└─ 不依赖浏览器的 WebSocket 终端连接
|
||||
|
||||
[P2] 跨平台支持
|
||||
└─ macOS/Linux Playwright 兼容
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、下一步操作
|
||||
|
||||
1. **运行探测脚本**（需要你手动执行，因为需要 OTP + Chrome 浏览器）：
|
||||
```powershell
|
||||
cd $env:USERPROFILE\.workbuddy\skills\jumpserver-automation\scripts
|
||||
& "C:\Users\simon\.workbuddy\binaries\python\versions\3.13.12\python.exe" probe_xterm_buffer_v2.py
|
||||
```
|
||||
|
||||
2. **查看探测结果**：检查 `webcli_output/probe_v2_results.json`，确认 `best_method` 字段
|
||||
|
||||
3. **根据结果选择 v8 实现方案**：
|
||||
- 如果 `best_method = global_instance` → 直接用缓冲区读取，实现最简单
|
||||
- 如果 `best_method = dom_rows` → 可用但需验证跨版本兼容性
|
||||
- 如果 `best_method = null` 或 `screen_textcontent` → 需要 Monkey Patch 方案
|
||||
|
||||
4. **实现 webcli_v8.py**：基于探测结果选择最佳捕获策略
|
||||
Reference in New Issue
Block a user