201 lines
5.2 KiB
Markdown
201 lines
5.2 KiB
Markdown
# Ops Assistant 独立项目 v1 方案
|
||
|
||
## 目标
|
||
把高频运维动作做成**固定命令 + 固定流水线**，AI 只负责解释，不参与关键执行决策。
|
||
|
||
---
|
||
|
||
## v1 范围（先做）
|
||
|
||
优先只落地 **CPA 管理中枢**：
|
||
|
||
1. 固定命令入口（Telegram/QQ/飞书统一）
|
||
2. Runbook（YAML）确定性执行器
|
||
3. 审计日志（步骤级）
|
||
4. 高风险能力默认关闭（Feature Flag）
|
||
|
||
后续再扩展：Cloudflare DNS、邮箱转发。
|
||
|
||
---
|
||
|
||
## 目录结构（新增）
|
||
|
||
```text
|
||
ops-assistant/
|
||
├── internal/
|
||
│ ├── core/
|
||
│ │ ├── command/ # 命令解析
|
||
│ │ ├── registry/ # 命令注册与路由
|
||
│ │ ├── runbook/ # runbook 结构、执行器、锁、target 解析
|
||
│ │ └── ops/ # ops 服务编排、重试
|
||
│ └── module/
|
||
│ └── cpa/ # CPA 模块命令与高风险闸门
|
||
├── runbooks/
|
||
│ ├── cpa_status.yaml
|
||
│ ├── cpa_usage_backup.yaml
|
||
│ └── cpa_usage_restore.yaml
|
||
└── docs/
|
||
└── ops-assistant-v1.md
|
||
```
|
||
|
||
---
|
||
|
||
## 命令清单（v1）
|
||
|
||
- `/cpa status`
|
||
- `/cpa usage backup`
|
||
- `/cpa usage restore <backup_id>`
|
||
- `/cpa codex clean`
|
||
- `/cpa codex test`
|
||
- `/cpa codex isolate`
|
||
|
||
### 约束
|
||
- 仅允许上述命令（严格白名单）
|
||
- 每个命令映射到唯一 runbook
|
||
- 不支持自由 shell 指令输入
|
||
|
||
---
|
||
|
||
## Runbook DSL（v1）
|
||
|
||
仅支持这些动作：
|
||
|
||
- `ssh.exec`：远程执行固定命令
|
||
- `http.get` / `http.post`：调用固定接口
|
||
- `file.upload`：上传压缩包到 staging
|
||
- `file.extract`：解压到 staging
|
||
- `assert.json`：断言字段值
|
||
- `sleep`：延迟
|
||
|
||
每个步骤必须有：
|
||
|
||
- `id`
|
||
- `action`
|
||
- `on_fail`（`stop` | `continue`）
|
||
|
||
所有变量只能来自：
|
||
|
||
- `inputs.*`（命令参数）
|
||
- `env.*`（服务端配置）
|
||
- `steps.<id>.output.*`（前置步骤输出）
|
||
|
||
---
|
||
|
||
## 审计与可追溯
|
||
|
||
建议新增两张表：
|
||
|
||
### 1) `ops_jobs`
|
||
- `id`
|
||
- `command`
|
||
- `runbook`
|
||
- `operator_id`
|
||
- `status`（pending/running/success/failed）
|
||
- `started_at`
|
||
- `ended_at`
|
||
|
||
### 2) `ops_job_steps`
|
||
- `id`
|
||
- `job_id`
|
||
- `step_id`
|
||
- `action`
|
||
- `status`
|
||
- `rc`
|
||
- `stdout_tail`
|
||
- `stderr_tail`
|
||
- `started_at`
|
||
- `ended_at`
|
||
|
||
> 所有 Bot 命令回执都返回 `job_id`，便于追踪。
|
||
|
||
---
|
||
|
||
## 风险控制
|
||
|
||
- 默认 `dry-run=true`（先演练）
|
||
- 高风险步骤（restore/import）必须：
|
||
- 双确认（命令 + confirm token）
|
||
- feature flag 开启才允许执行
|
||
- 审计日志不写明文 secrets
|
||
- 全部 secrets 走现有 `channel` 加密机制存储
|
||
|
||
---
|
||
|
||
## 与现有系统的集成点（独立项目并存）
|
||
|
||
1. **Bot 层**：在 Telegram/QQ/飞书消息处理中增加 `/cpa` 命令分流
|
||
2. **Web 层**：新增 `/ops` 页面查看任务状态与步骤日志
|
||
3. **模型层**：新增 `ops_jobs` / `ops_job_steps`
|
||
4. **配置层**：增加 `ops.targets`（如 hwsg/wjynl）
|
||
|
||
---
|
||
|
||
## 阶段性进度汇报原则（必须遵守）
|
||
|
||
**模板（四要素）**
|
||
1) 阶段名（设计/实现/自测/上线等）
|
||
2) 已执行动作（具体到做了什么）
|
||
3) 可验证证据（日志、产物路径、返回码、截图等）
|
||
4) 下一步与前置条件（还差什么、需谁确认）
|
||
|
||
**硬规则**
|
||
- 无证据不使用“完成/已执行/进行中”等措辞
|
||
- 遇到卡点必须立即说明：卡点 + 原因 + 需要的唯一输入
|
||
- 先清单后执行的任务，未确认不得执行
|
||
|
||
---
|
||
|
||
## 事故复盘（2026-03-13，CF DNS Runbook）
|
||
|
||
详见：`docs/cf-dns-runbook-incident-20260313.md`
|
||
|
||
要点摘要：
|
||
- 认证方式误判（API Token 被当作 API Key）。
|
||
- heredoc/转义在 ssh.exec 中导致脚本未执行。
|
||
- 最终采用 base64 + python3 -c exec 稳定执行。
|
||
- 强化“阶段性汇报必须带证据”的纪律。
|
||
|
||
---
|
||
|
||
## 验收标准（v1）
|
||
|
||
1. `/cpa status` 能返回结构化结果（非自由文本）
|
||
2. `/cpa usage backup` 能输出：备份路径 + sha256 + usage 快照
|
||
3. `/cpa usage restore <id>` 支持双校验（立即 + 延迟）
|
||
4. 任一步骤失败时可追溯到具体 step 日志
|
||
5. 未授权命令必须被拒绝并记录审计
|
||
|
||
---
|
||
|
||
## 当前已落地（2026-03-10）
|
||
|
||
1. 已打通命令入口：Telegram / QQ / 飞书
|
||
2. 已支持命令：
|
||
- `/cpa status`
|
||
- `/cpa usage backup`
|
||
- `/cpa usage restore <backup_id>`
|
||
3. 已提供查询接口：
|
||
- `GET /api/v1/ops/jobs`
|
||
- `GET /api/v1/ops/jobs/:id`（含 steps）
|
||
4. `assert.json` 已支持真实 JSON 路径断言
|
||
5. 已增加安全闸门：
|
||
- `allow_ops_restore` feature flag（默认 false）
|
||
- restore 需要 `--confirm YES_RESTORE`
|
||
- 支持 `--dry-run`
|
||
6. 已支持 `ops_targets` 目标主机表（优先解析 target 名称）
|
||
|
||
## 当前 Core 强化（2026-03-10 第二阶段）
|
||
|
||
1. 同 target 串行锁（避免并发覆盖）
|
||
2. 作业元信息增强：`target/risk_level/request_id/confirm_hash`
|
||
3. 统一错误码前缀（如 `ERR_FEATURE_DISABLED` / `ERR_CONFIRM_REQUIRED` / `ERR_STEP_FAILED`）
|
||
4. step 超时控制（默认 45s）
|
||
5. 任务取消接口：`POST /api/v1/ops/jobs/:id/cancel`
|
||
|
||
## 下一步落地建议
|
||
|
||
1. 为取消操作增加权限细分（`ops.cancel`）
|
||
2. 增加 job 重试接口（仅失败任务可重试）
|
||
3. 增加步骤级超时配置（runbook 可覆盖）
|
||
4. 增加 Cloudflare / Mail 模块（在 Core 验收完成后）
|