ops-assistant/README.md

🛠️ 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 干净退出

📦 快速开始

二进制运行

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

Docker 运行

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

从源码编译

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

⚙️ 配置说明

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                 # 构建 / 版本 / 发布

🔧 开发与发布

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 联调探针（不动线上服务，用数据库副本跑）：

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