235 lines
9.4 KiB
Markdown
235 lines
9.4 KiB
Markdown
# 🛠️ Ops-Assistant
|
||
|
||
多平台 Bot + 自动化运维一体的私人助理服务：**智能记账**、**Runbook 工单执行**、**模块化 OPS 命令**（Cloudflare / CPA / 订阅 / cfdav / 邮箱），带 Web 管理后台。
|
||
|
||
> 项目由 Xiaji-Go（记账机器人）演进更名而来；当前 `VERSION` 为 `0.0.1`（框架重构后重新起版，历史记账版本线为 v1.1.x）。
|
||
|
||
## 🆕 框架版更新要点
|
||
|
||
- **项目更名**：`xiaji-go` → `ops-assistant`（go.mod / 二进制 / systemd 同步）
|
||
- **模块化命令框架**：`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、飞书（通道层预留）
|
||
- **智能记账**：自然语言识别金额与消费分类（jieba 分词，150+ 预设关键词）
|
||
- **OPS 命令**：`/cf` `/cpa` `/cfdav` `/sub` `/mail`，写操作带 dry-run / 确认门控
|
||
- **Runbook 自动化**：YAML 定义、步骤编排、断言校验、任务审计
|
||
- **Web 管理后台**：记录查看 / 删除 / CSV 导出、模块与渠道配置、任务与审计查看
|
||
- **金额精确**：分（int64）存储，避免浮点误差
|
||
- **优雅关闭**：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+、GCC（gojieba 依赖 CGO）
|
||
make build
|
||
make build-linux
|
||
```
|
||
|
||
## ⚙️ 配置说明
|
||
|
||
```yaml
|
||
server:
|
||
port: 9621 # Web 后台端口
|
||
key: "your-secret-key" # 会话密钥
|
||
|
||
database:
|
||
path: "./xiaji.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:` 前缀）。
|
||
|
||
## 💬 记账功能
|
||
|
||
### QQ Bot 关键词
|
||
|
||
| 关键词 | 说明 |
|
||
|--------|------|
|
||
| `帮助` / `菜单` | 显示帮助 |
|
||
| `查看` / `记录` / `列表` | 最近 10 条记录 |
|
||
| `今日` / `今天` | 今日消费汇总 |
|
||
| 直接发消息 | 自动记账（如"午饭 25元"） |
|
||
|
||
### Telegram Bot 命令
|
||
|
||
`/start` `/help` `/list` `/today`，或直接发消息自动记账。
|
||
|
||
### 支持格式与分类
|
||
|
||
```
|
||
午饭 25元 / 打车 ¥30 / 买咖啡15块 / 超市买水果38.5
|
||
```
|
||
|
||
预设 150+ 关键词覆盖：🍜 餐饮、🚗 交通、🛒 购物、☕ 饮品、🍎 水果、🍪 零食、🏠 住房、📱 通讯、💊 医疗、🎮 娱乐、📚 教育、🚬 烟酒。
|
||
|
||
## 🧰 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 138sgd 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`：
|
||
|
||
- 📊 记账统计 / 最近记录 / 分类筛选 / CSV 导出
|
||
- 🧩 模块设置：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
|
||
│ ├── bot/ # Telegram Bot
|
||
│ ├── qq/ # QQ Bot（WebSocket）+ 订阅提醒调度
|
||
│ ├── feishu/ # 飞书适配（预留）
|
||
│ ├── service/ # 记账核心（jieba 分词）
|
||
│ ├── chart/ # 统计图表
|
||
│ └── 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（CGO：gojieba）
|
||
- **Web 框架**: Gin · **数据库**: SQLite (GORM)
|
||
- **分词**: gojieba · **QQ SDK**: tencent-connect/botgo v0.2.1（WebSocket）· **TG SDK**: go-telegram-bot-api v5
|
||
- **自动化**: 自研 runbook 执行器（YAML 编排 + 严格断言 + 任务审计）
|
||
|
||
## 📄 License
|
||
|
||
MIT |