# 🛠️ Ops-Assistant

多平台 Bot + 自动化运维一体的私人助理服务：**Runbook 工单执行**、**模块化 OPS 命令**（Cloudflare / CPA / 订阅 / cfdav / 邮箱），带 Web 管理后台。

> 当前 `VERSION` 为 `0.0.1`。项目定位为模块化 OPS 助手。

## 🆕 框架版更新要点

- **模块化命令框架**：`internal/core/module` 统一命令模板、门控（feature flag / confirm / dry-run）、错误标签（ecode）、结果格式化回传
- **Runbook 执行器增强**（`internal/core/runbook`）：
  - 新增动作：`http.get` / `http.post` / `assert.json`（支持 `expect_success` 严格断言，API 失败不再假阳性）
  - 目标主机管理（`ops_targets`，默认 seed：hwsg / wjynl）
  - 任务与步骤全程落库（`ops_jobs` / `ops_job_steps`），Web 后台可查
  - **查询类命令结果直接回传**（此前仅回执 job 号）
- **CF 模块增强**：DNS 查询支持**传域名自动解析 zone_id**；`dns list / zones / workers list` 结果可读回传；API `success:false` 时任务真失败并回传错误摘要
- **新增模块**：`cpa`（usage 备份/恢复）、`cfdav`、`mail`、`sub`（订阅管理与到期提醒）
- **QQ Bot**：AI 命令加载器、每日订阅提醒调度（09:00）
- **Web 后台**：模块设置页（CF / CPA / cfdav / AI）、OPS 任务页、渠道管理、审计页

## ✨ 功能特性

- **多平台接入**：QQ 官方 Bot（WebSocket）、Telegram Bot、飞书（通道层预留）
- **OPS 命令**：`/cf` `/cpa` `/cfdav` `/sub` `/mail`，写操作带 dry-run / 确认门控
- **Runbook 自动化**：YAML 定义、步骤编排、断言校验、任务审计
- **Web 管理后台**：模块与渠道配置、任务与审计查看
- **优雅关闭**：SIGTERM/SIGINT 干净退出

## 📦 快速开始

### 二进制运行

```bash
cp config.yaml.example config.yaml
vi config.yaml          # 填入 Bot Token 等
./ops-assistant
```

### Docker 运行

```bash
cp config.yaml.example config.yaml && vi config.yaml
docker-compose up -d
# 或
docker run -d --name ops-assistant -p 9621:9621 \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  -v $(pwd)/data:/app/data \
  ouaone/ops-assistant:latest
```

### 从源码编译

```bash
# 需要 Go 1.22+
make build
make build-linux
```

## ⚙️ 配置说明

```yaml
server:
  port: 9621                    # Web 后台端口
  key: "your-secret-key"        # 会话密钥

database:
  path: "./ops.db"              # SQLite 数据库路径

admin:
  username: "admin"             # Web 后台用户名
  password: "your_password"     # 弱密码启动时会告警

telegram:
  enabled: true
  token: "YOUR_BOT_TOKEN"

qqbot:
  enabled: false
  appid: "YOUR_APPID"
  secret: "YOUR_SECRET"
```

> **模块凭据**（CF API Token、CPA 管理令牌、cfdav 账号等）保存在数据库 `app_settings` 表，通过 Web 后台「模块设置」页配置，**不写入配置文件**；渠道 secrets 在数据库内加密存储（`enc:v1:` 前缀）。

## 🤖 Bot 与 OPS

Bot 主要用于接收 OPS 命令并返回执行结果。支持 QQ Bot、Telegram Bot；具体渠道开关与凭据在 Web 管理后台配置。

## 🧰 OPS 命令参考

> 需先在 Web 后台启用对应模块开关（如 `enable_module_cf`）并配置凭据。查询类命令**直接回传格式化结果**；写操作回执 job 号，支持 `--dry-run` 预览。

### Cloudflare（`/cf`）

| 命令 | 说明 |
|------|------|
| `/cf status` | runbook 链路自检 |
| `/cf zones` | 列出账号下站点 |
| `/cf dns list <zone_id 或域名>` | DNS 记录列表（域名自动解析；🟠 = 已开橙云） |
| `/cf dns update <id> <content>` | 更新记录内容 |
| `/cf dnsadd <name> <content> [on/off] [type]` | 新增记录 |
| `/cf dnsset <id 或 name> <content>` | 按名设置记录内容 |
| `/cf dnsdel <id 或 name>` | 删除记录 |
| `/cf dnsproxy <id 或 name> on\|off` | 切换橙云/灰云 |
| `/cf workers list` | Workers 脚本列表 |

### CPA（CLIProxyAPI 管理）

| 命令 | 说明 |
|------|------|
| `/cpa status` | usage 快照（requests / tokens） |
| `/cpa usage backup` | 实时导出 usage 并打包备份（含 sha256/meta） |
| `/cpa usage restore <备份包>` | 恢复 usage（import 接口优先，不停服） |

### 其他模块

| 命令 | 说明 |
|------|------|
| `/cfdav users` | cfdav 用户列表 |
| `/cfdav add <email> <password> [admin]` | 新增用户 |
| `/cfdav del <user_id>` | 删除用户 |
| `/mail status` | 邮箱服务状态 |
| `/sub add` | 新增订阅（引导式流程） |
| `/sub list` | 订阅列表 |
| `/sub report [category\|cycle\|due <7\|30\|overdue>]` | 订阅报表 |
| `/sub del <id>` | 删除订阅 |
| `/sub cancel` | 取消进行中的新增流程 |
| `/ops modules` | 查看模块启用状态 |
| `/rate 138 sgd to cny` | 实时货币转换（Google / Visa / Mastercard） |

## 📜 Runbook（自动化工单）

`runbooks/*.yaml` 定义自动化任务，由执行器按步骤编排运行：

- **动作**：`ssh.exec`（远程目标）、`shell.exec`（本机）、`http.get` / `http.post`、`file.upload` / `file.extract`、`assert.json`、`sleep`
- **严格断言**：`assert.json` 支持 `expect_success: true` —— API 返回 `success:false` 时任务判失败，错误码与摘要直接回传给用户（杜绝"执行成功但结果无效"的假阳性）
- **结果回传**：查询类命令的 stdout 经模块格式化后直接发回聊天窗口
- **全程审计**：每次执行落库 `ops_jobs` / `ops_job_steps`（rc、stdout/stderr tail、耗时），Web 后台「OPS 任务」页可查

示例（`runbooks/cf_dns_list.yaml`）：解析 zone → API 查询 → `assert.json` 校验 `success=true` → 格式化回传。

## 🌐 Web 管理后台

访问 `http://localhost:9621`：

- 🧩 模块设置：CF / CPA / cfdav / AI
- 🔌 渠道管理：QQ / Telegram / 飞书 配置与连接测试
- 🧾 OPS 任务与目标主机管理
- 🛡️ 审计日志

## 🏗️ 项目结构

```
ops-assistant/
├── cmd/
│   ├── main.go              # 服务入口
│   ├── ops-runner/          # CLI 直跑 runbook（运维侧入口）
│   └── runbook_test.go      # runbook 联调探针（-tags runbooktest）
├── config/config.go         # 配置加载与验证
├── models/models.go         # 数据模型（GORM + AutoMigrate）
├── internal/
│   ├── core/
│   │   ├── command/         # 命令解析
│   │   ├── ecode/           # 错误码与标签
│   │   ├── module/          # 命令模板 / 门控 / 格式化回传
│   │   ├── policy/          # feature flag / confirm / dry-run
│   │   ├── registry/        # 模块注册
│   │   ├── runbook/         # 执行器（ssh/shell/http/assert）
│   │   ├── ops/             # OPS 服务编排
│   │   └── ai/              # AI 命令加载
│   ├── module/              # 业务模块：cf / cpa / cfdav / mail / sub / rate
│   ├── bot/                 # Telegram Bot
│   ├── qq/                  # QQ Bot（WebSocket）+ 订阅提醒调度
│   ├── feishu/              # 飞书适配（预留）
│   └── web/                 # Web 后台（Gin）
├── runbooks/                # 自动化 runbook（YAML）
├── templates/               # Web 前端页面
├── config.yaml.example      # 配置示例
├── Dockerfile / docker-compose.yml
└── Makefile                 # 构建 / 版本 / 发布
```

## 🔧 开发与发布

```bash
make build            # 编译（自动读取 VERSION）
make bump-patch       # 版本 +1（patch/minor/major 同理）
make set-version VERSION=1.2.3
make release-check    # 发布前检查（工作区干净 + 版本格式）
make package-release  # 产出 dist/ 二进制 + sha256
make tag-release      # 打 tag 并推送
make docker && make docker-push
```

Runbook 联调探针（不动线上服务，用数据库副本跑）：

```bash
go build -tags runbooktest -o runbook_test ./cmd
./runbook_test <db_copy> <base_dir> "/cf dns list <zone_id>"
```

## 📋 技术栈

- **语言**: Go 1.22
- **Web 框架**: Gin · **数据库**: SQLite (GORM)
**QQ SDK**: tencent-connect/botgo v0.2.1（WebSocket）· **TG SDK**: go-telegram-bot-api v5
- **自动化**: 自研 runbook 执行器（YAML 编排 + 严格断言 + 任务审计）

## 📄 License

MIT