Codex Release Bot
210 lines
8.9 KiB
Markdown
210 lines
8.9 KiB
Markdown
# 脚本批量执行平台 — 技术说明（SSOT）
|
||
|
||
**最后更新**: 2026-05-22
|
||
**状态**: 已实现，待本地 / 外网 E2E 验证
|
||
|
||
## 1. 目标与约束
|
||
|
||
| 目标 | 实现方式 |
|
||
|------|----------|
|
||
| 2000+ 台批量执行 | 内置分批（默认 50 台/批），批内并发 10 |
|
||
| 长任务不阻塞 HTTP | `nohup` + 子机结束 `curl` 主站回调 |
|
||
| 短任务执行中可停止 | Agent `wait=false` → `pid` → `/exec/kill` |
|
||
| 减轻 MySQL 压力 | 执行态**只写 Redis**；MySQL **60s 分批刷盘** |
|
||
| 全链路可审计 | `audit_logs` 即时写入；`results._meta.events` 时间线 |
|
||
| 不用 WS 换票 / 异步 exec API | 同步 `POST /api/scripts/exec` + 页顶状态条轮询 |
|
||
|
||
**不可改 / 环境项**（`.env`）：
|
||
|
||
- `NEXUS_API_BASE_URL` — 长任务子机回调主站地址（必填，否则长任务 400）
|
||
- `NEXUS_SCRIPT_EXEC_BATCH_SIZE`（默认 50）、`NEXUS_SCRIPT_EXEC_CONCURRENCY`（默认 10）
|
||
|
||
**代码内常量**（`server/infrastructure/redis/script_execution_store.py`，不写 `.env`）：
|
||
|
||
| 常量 | 值 | 含义 |
|
||
|------|-----|------|
|
||
| `REDIS_TTL_SECONDS` | 7200 | 热数据最长 2h |
|
||
| `FLUSH_INTERVAL_SECONDS` | 60 | Redis→MySQL 刷盘周期 |
|
||
| `FLUSH_BATCH_LIMIT` | 50 | 每轮最多刷 50 条执行记录 |
|
||
| `STUCK_NO_PROGRESS_SECONDS` | 3600 | 卡住检测阈值（1h） |
|
||
|
||
## 2. 架构与数据流
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
UI[scripts.html / script-executions.html]
|
||
API[POST /api/scripts/exec]
|
||
SVC[ScriptService]
|
||
Redis[(Redis script_exec:id)]
|
||
Flush[script_execution_flush 60s]
|
||
MySQL[(script_executions)]
|
||
Agent[子机 Agent :8800]
|
||
CB[POST /api/agent/script-callback]
|
||
|
||
UI --> API --> SVC
|
||
SVC --> Redis
|
||
SVC --> Agent
|
||
Agent -->|长任务结束 curl| CB --> Redis
|
||
Flush --> MySQL
|
||
UI -->|GET executions/id| Redis
|
||
UI -.->|历史列表可能滞后| MySQL
|
||
```
|
||
|
||
### 2.1 Redis 热数据
|
||
|
||
- Key: `script_exec:{execution_id}` — JSON 全量快照（status、results、events、operator…）
|
||
- 队列: `script_exec:flush_queue` — 待刷 MySQL 的 id 集合
|
||
- 长任务回调: `script_job:{job_id}` — 一次性 secret（TTL 7 天，见 `script_jobs.py`）
|
||
|
||
### 2.2 MySQL 冷数据
|
||
|
||
- 表: `script_executions`
|
||
- `results` JSON：`{ "<server_id>": { ... }, "_meta": { "events": [...] } }`
|
||
- 刷盘后从 flush 队列移除；读接口**优先 Redis**，无 Redis 再读 MySQL
|
||
|
||
### 2.3 进度字段
|
||
|
||
- API 字段 `progress`: `"done/total"`（`pending` 计为未完成）
|
||
- 实现: `execution_progress_summary()` in `script_execution_store.py`
|
||
|
||
## 3. 执行模式
|
||
|
||
### 3.1 短任务（默认）
|
||
|
||
1. 主站 `POST` 子机 Agent `/exec` + `wait: false` → 得 `pid`，**立即** `patch_live` 写入 Redis（`phase: pending`）
|
||
2. 主站 `POST` `/exec/wait` 等待结束
|
||
3. 用户点「停止」→ 主站 `POST` `/exec/kill`（需**新版 Agent**）
|
||
4. 未升级 Agent：回退同步 `/exec` `wait=true`，**无法**中途停止
|
||
|
||
### 3.2 长任务（`long_task: true`）
|
||
|
||
1. 命令存库前缀 `[long_task] `
|
||
2. `script_jobs.build_long_task_command()`：`nohup` + 日志 `/var/log/nexus-job/{job_id}.log` + 结束 curl 主站
|
||
3. 点火成功 → `phase: pending` + `job_id` + `started_at`
|
||
4. 子机 `POST /api/agent/script-callback` → 更新 results + WebSocket `script_job_done`
|
||
5. 停止：kill `${LOG}.pid` + 撤销 Redis job secret
|
||
|
||
## 4. HTTP API（JWT，除回调）
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/scripts/exec-config` | `batch_size`, `concurrency` |
|
||
| POST | `/api/scripts/exec` | `server_ids`, `command`, `timeout`, `long_task`, `credential_id?` |
|
||
| GET | `/api/scripts/executions` | 分页历史 `limit`, `offset`, `status` |
|
||
| GET | `/api/scripts/executions/{id}` | `?fetch_logs=true` 拉子机 tail 日志 |
|
||
| POST | `/api/scripts/executions/{id}/stop` | 停止 pending |
|
||
| POST | `/api/scripts/executions/{id}/retry` | 失败/未完成重试；**新建** `execution_id`，响应含 `parent_execution_id` |
|
||
| POST | `/api/scripts/executions/{id}/mark-stuck` | 人工标记卡住 |
|
||
| POST | `/api/agent/script-callback` | `job_id`, `secret`, `server_id`, `exit_code`（无 JWT；Redis 限速） |
|
||
|
||
## 4.1 安全与执行面
|
||
|
||
| 风险 | 现状 | 缓解 |
|
||
|------|------|------|
|
||
| 子机 `subprocess_shell` / 长任务 `bash -c` | 运维必需能力 | 仅 API Key 可调 `/exec`；主站 `check_dangerous_command` **拒绝**危险模式；Agent 每次 exec 打 WARNING 审计日志 |
|
||
| 回调 HTTP 明文 | 生产配置错误 | `master_callback_url()` 非 localhost 强制 `https://` |
|
||
| 回调刷接口 | 无 JWT | `script_callback_rate`：每 job 10/min、每 IP 60/min |
|
||
| 重试语义 | 每次 retry 新建记录 | API 返回 `parent_execution_id` 关联原单；历史页按 id 追踪 |
|
||
|
||
子机应网络隔离：仅中心机 IP 可访问 Agent `:8800`。
|
||
|
||
## 5. 子机 Agent 接口
|
||
|
||
文件: `web/agent/agent.py`
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/exec` | `wait` 默认 true；false 返回 `pid` |
|
||
| POST | `/exec/wait` | 等待 `pid` |
|
||
| POST | `/exec/kill` | 终止 `pid` |
|
||
|
||
**部署**：各子机更新 Agent 后重启；否则短任务 stop 不可用。
|
||
|
||
## 6. 后台任务
|
||
|
||
- 模块: `server/background/script_execution_flush.py`
|
||
- 注册: `server/main.py` → `script_execution_flush_loop()`（primary worker）
|
||
- 每 60s：
|
||
1. `detect_stuck_executions()` — 单台 pending 超 1h → `server_auto_stuck`；整单无更新 1h → `auto_stuck`
|
||
2. `flush_pending_batch()` — 最多 50 条写入 MySQL
|
||
|
||
## 7. 审计（`audit_logs.action`）
|
||
|
||
| action | 触发场景 |
|
||
|--------|----------|
|
||
| `execute_started` | 创建执行记录 |
|
||
| `execute_command` | 记录实际下发命令摘要 |
|
||
| `stop_execution` | 用户停止 |
|
||
| `retry_execution` | 用户重试 |
|
||
| `mark_stuck` | 用户标记卡住 |
|
||
| `script_job_callback` | 长任务子机回调 |
|
||
| `auto_stuck` | 整单 1h 无 Redis 更新 |
|
||
| `server_auto_stuck` | 单台 pending 超 1h |
|
||
|
||
前端筛选: `web/app/audit.html` 已增加上述选项。
|
||
|
||
## 8. 前端页面
|
||
|
||
| 页面 | 路径 | 功能 |
|
||
|------|------|------|
|
||
| 脚本库 | `web/app/scripts.html` | 执行弹窗、分批、长任务勾选、页顶「批量执行状态」 |
|
||
| 执行历史 | `web/app/script-executions.html` | 列表、进度、停止/重试/卡住、详情+日志、10s 轮询 |
|
||
| 侧栏 | `web/app/layout.js` | 菜单项「执行历史」 |
|
||
|
||
页顶状态条按钮：刷新状态、状态+日志、停止、重试、标记卡住。
|
||
|
||
## 9. 涉及文件清单
|
||
|
||
### 后端
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `server/application/services/script_service.py` | 分批执行、Agent 调用、stop/retry/list |
|
||
| `server/application/services/script_jobs.py` | 长任务 nohup + job Redis |
|
||
| `server/application/services/script_job_callback.py` | 回调合并结果 |
|
||
| `server/infrastructure/redis/script_execution_store.py` | Redis 热数据、刷盘队列、卡住检测、progress |
|
||
| `server/background/script_execution_flush.py` | 60s 循环 |
|
||
| `server/infrastructure/database/script_repo.py` | `list_recent`, `update_status` |
|
||
| `server/api/scripts.py` | REST 路由 |
|
||
| `server/api/agent.py` | `script-callback` |
|
||
| `server/config.py` | `SCRIPT_EXEC_BATCH_SIZE`, `SCRIPT_EXEC_CONCURRENCY` |
|
||
| `server/main.py` | 注册 flush 后台任务 |
|
||
|
||
### 前端 / Agent
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `web/app/scripts.html` | 执行 UI + 状态条 |
|
||
| `web/app/script-executions.html` | 历史页 |
|
||
| `web/app/layout.js` | 侧栏 |
|
||
| `web/app/audit.html` | 审计筛选 |
|
||
| `web/agent/agent.py` | exec / wait / kill |
|
||
|
||
## 10. 已知限制
|
||
|
||
1. MySQL 视图比 Redis **最多晚 60s**（直接查库时）；页面轮询读 Redis 无影响。
|
||
2. 短任务 stop 依赖子机 Agent 新版本。
|
||
3. 自动卡住：单台按 `started_at`；整单按 `updated_at`（非单台日志活跃度）。
|
||
4. 危险命令仍由 `check_dangerous_command` 拦截。
|
||
5. 长任务依赖 `NEXUS_API_BASE_URL` 对子机可达，且生产须为 HTTPS（本地可用 `http://localhost`）。
|
||
6. **重试**会创建新的 `script_executions.id`；原单结果保留，通过 `parent_execution_id` 关联。
|
||
|
||
## 11. 测试清单（待执行）
|
||
|
||
- [ ] T-SE1: 选 3 台短任务，页顶进度 `3/3`，审计有 `execute_started`
|
||
- [ ] T-SE2: 选 60 台，确认分 2 批、合并一条状态卡
|
||
- [ ] T-SE3: 长任务 + 配置 `NEXUS_API_BASE_URL`，回调后状态变完成、WS 通知
|
||
- [ ] T-SE4: 长任务执行中「停止」，子机进程结束
|
||
- [ ] T-SE5: 新版 Agent 短任务执行中「停止」
|
||
- [ ] T-SE6: 执行历史页停止/重试/状态+日志
|
||
- [ ] T-SE7: 等待或调低 `STUCK_NO_PROGRESS_SECONDS` 验证 `server_auto_stuck` / `auto_stuck`
|
||
- [ ] T-SE8: Redis 有 key 时 MySQL 在 60s 内出现对应行
|
||
|
||
## 12. 相关 Changelog
|
||
|
||
| 文档 | 内容 |
|
||
|------|------|
|
||
| [2026-05-22-script-execution-platform.md](../changelog/2026-05-22-script-execution-platform.md) | 本次交付总览与文件变更索引 |
|
||
| [2026-05-22-script-exec-batching.md](../changelog/2026-05-22-script-exec-batching.md) | 内置分批与 exec-config |
|
||
| [2026-05-22-script-job-callback.md](../changelog/2026-05-22-script-job-callback.md) | 长任务回调与 Redis 刷盘摘要 |
|