diff --git a/.gitignore b/.gitignore index f0f23e7..ba4d679 100644 --- a/.gitignore +++ b/.gitignore @@ -28,4 +28,4 @@ config.yaml Thumbs.db # Go -vendor/ \ No newline at end of file +vendor/ops-runner diff --git a/README.md b/README.md index b74f581..237c287 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,53 @@ -# 🦞 虾记 Xiaji-Go +# 🛠️ Ops-Assistant -一个支持 **Telegram Bot** 和 **QQ Bot** 的智能记账机器人，带 Web 管理后台。 +多平台 Bot + 自动化运维一体的私人助理服务：**智能记账**、**Runbook 工单执行**、**模块化 OPS 命令**（Cloudflare / CPA / 订阅 / cfdav / 邮箱），带 Web 管理后台。 -> 当前稳定版本：`v1.1.12` +> 项目由 Xiaji-Go（记账机器人）演进更名而来；当前 `VERSION` 为 `0.0.1`（框架重构后重新起版，历史记账版本线为 v1.1.x）。 -## 🆕 v1.1.12 更新 +## 🆕 框架版更新要点 -- 新增渠道管理页：`/channels`（移动端优先，统一 UI） -- 新增审计页面：`/audit`（中文化） -- 新增一键生效接口：`POST /api/v1/admin/channels/:platform/apply` -- 渠道配置安全增强：`***` 脱敏占位符不会覆盖真实 secrets -- apply 失败返回增强：失败时返回 `stage` 与 `committed` 字段 -- 首页/登录/渠道/审计页面版本显示统一为 `vX.Y.Z` +- **项目更名**：`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 任务页、渠道管理、审计页 ## ✨ 功能特性 -- **多平台支持**：同时接入 Telegram Bot 和 QQ Bot（WebSocket 模式） -- **智能记账**：发送自然语言自动识别金额和消费分类（基于 jieba 分词） -- **150+ 预设分类关键词**：餐饮、交通、购物、饮品、水果、住房、医疗、娱乐等 -- **Web 管理后台**：响应式设计，支持记录查看、删除、CSV 导出 -- **金额精确**：使用分（int64）存储，避免浮点精度问题 -- **优雅关闭**：支持 SIGTERM/SIGINT 信号，干净退出 +- **多平台接入**：QQ 官方 Bot（WebSocket）、Telegram Bot、飞书（通道层预留） +- **智能记账**：自然语言识别金额与消费分类（jieba 分词，150+ 预设关键词） +- **OPS 命令**：`/cf` `/cpa` `/cfdav` `/sub` `/mail`，写操作带 dry-run / 确认门控 +- **Runbook 自动化**：YAML 定义、步骤编排、断言校验、任务审计 +- **Web 管理后台**：记录查看 / 删除 / CSV 导出、模块与渠道配置、任务与审计查看 +- **金额精确**：分（int64）存储，避免浮点误差 +- **优雅关闭**：SIGTERM/SIGINT 干净退出 ## 📦 快速开始 ### 二进制运行 ```bash -# 1. 复制配置文件 cp config.yaml.example config.yaml - -# 2. 编辑配置（填入 Bot Token 等信息） -vi config.yaml - -# 3. 运行 -./xiaji-go +vi config.yaml # 填入 Bot Token 等 +./ops-assistant ``` ### Docker 运行 ```bash -# 1. 准备配置文件 -cp config.yaml.example config.yaml -vi config.yaml - -# 2. 使用 docker-compose +cp config.yaml.example config.yaml && vi config.yaml docker-compose up -d - -# 或直接 docker run -docker run -d \ - --name xiaji-go \ - -p 9521:9521 \ +# 或 +docker run -d --name ops-assistant -p 9621:9621 \ -v $(pwd)/config.yaml:/app/config.yaml:ro \ -v $(pwd)/data:/app/data \ - ouaone/xiaji-go:latest + ouaone/ops-assistant:latest ``` ### 从源码编译 @@ -61,8 +55,6 @@ docker run -d \ ```bash # 需要 Go 1.22+、GCC（gojieba 依赖 CGO） make build - -# 交叉编译 Linux make build-linux ``` @@ -70,7 +62,7 @@ make build-linux ```yaml server: - port: 9521 # Web 后台端口 + port: 9621 # Web 后台端口 key: "your-secret-key" # 会话密钥 database: @@ -78,109 +70,165 @@ database: admin: username: "admin" # Web 后台用户名 - password: "your_password" # Web 后台密码 + password: "your_password" # 弱密码启动时会告警 telegram: - enabled: true # 是否启用 Telegram Bot - token: "YOUR_BOT_TOKEN" # BotFather 获取的 Token + enabled: true + token: "YOUR_BOT_TOKEN" qqbot: - enabled: false # 是否启用 QQ Bot - appid: "YOUR_APPID" # QQ 开放平台 AppID - secret: "YOUR_SECRET" # QQ 开放平台 AppSecret + enabled: false + appid: "YOUR_APPID" + secret: "YOUR_SECRET" ``` -## 💬 使用方式 +> **模块凭据**（CF API Token、CPA 管理令牌、cfdav 账号等）保存在数据库 `app_settings` 表，通过 Web 后台「模块设置」页配置，**不写入配置文件**；渠道 secrets 在数据库内加密存储（`enc:v1:` 前缀）。 -### Telegram Bot 命令 - -| 命令 | 说明 | -|------|------| -| `/start` | 欢迎信息 | -| `/help` | 使用帮助 | -| `/list` | 最近 10 条记录 | -| `/today` | 今日消费汇总 | -| 直接发消息 | 自动记账（如"午饭 25元"） | +## 💬 记账功能 ### QQ Bot 关键词 | 关键词 | 说明 | |--------|------| -| `帮助` / `菜单` / `功能` | 显示帮助 | +| `帮助` / `菜单` | 显示帮助 | | `查看` / `记录` / `列表` | 最近 10 条记录 | | `今日` / `今天` | 今日消费汇总 | -| 直接发消息 | 自动记账 | +| 直接发消息 | 自动记账（如"午饭 25元"） | -### 记账格式 +### Telegram Bot 命令 -支持多种自然语言格式： +`/start` `/help` `/list` `/today`，或直接发消息自动记账。 + +### 支持格式与分类 ``` -午饭 25元 -打车 ¥30 -买咖啡15块 -车费10元 -超市买水果38.5 +午饭 25元 / 打车 ¥30 / 买咖啡15块 / 超市买水果38.5 ``` -### 消费分类 +预设 150+ 关键词覆盖：🍜 餐饮、🚗 交通、🛒 购物、☕ 饮品、🍎 水果、🍪 零食、🏠 住房、📱 通讯、💊 医疗、🎮 娱乐、📚 教育、🚬 烟酒。 -系统预设了 150+ 个关键词，自动匹配以下分类： +## 🧰 OPS 命令参考 -| 分类 | 示例关键词 | -|------|-----------| -| 🍜 餐饮 | 早饭、午饭、晚饭、外卖、火锅、面条 | -| 🚗 交通 | 打车、车费、地铁、公交、加油 | -| 🛒 购物 | 买、淘宝、超市、衣服、手机 | -| ☕ 饮品 | 咖啡、奶茶、星巴克、可乐 | -| 🍎 水果 | 水果、苹果、香蕉、西瓜 | -| 🍪 零食 | 零食、面包、蛋糕、甜品 | -| 🏠 住房 | 房租、水电、物业、宽带 | -| 📱 通讯 | 话费、流量、充值 | -| 💊 医疗 | 看病、药、医院、挂号 | -| 🎮 娱乐 | 电影、游戏、健身、旅游 | -| 📚 教育 | 书、课、培训、学费 | -| 🚬 烟酒 | 烟、白酒、红酒 | +> 需先在 Web 后台启用对应模块开关（如 `enable_module_cf`）并配置凭据。查询类命令**直接回传格式化结果**；写操作回执 job 号，支持 `--dry-run` 预览。 + +### Cloudflare（`/cf`） + +| 命令 | 说明 | +|------|------| +| `/cf status` | runbook 链路自检 | +| `/cf zones` | 列出账号下站点 | +| `/cf dns list ` | DNS 记录列表（域名自动解析；🟠 = 已开橙云） | +| `/cf dns update ` | 更新记录内容 | +| `/cf dnsadd [on/off] [type]` | 新增记录 | +| `/cf dnsset ` | 按名设置记录内容 | +| `/cf dnsdel ` | 删除记录 | +| `/cf dnsproxy 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 [admin]` | 新增用户 | +| `/cfdav del ` | 删除用户 | +| `/mail status` | 邮箱服务状态 | +| `/sub add` | 新增订阅（引导式流程） | +| `/sub list` | 订阅列表 | +| `/sub report [category\|cycle\|due <7\|30\|overdue>]` | 订阅报表 | +| `/sub del ` | 删除订阅 | +| `/sub cancel` | 取消进行中的新增流程 | +| `/ops modules` | 查看模块启用状态 | + +## 📜 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:9521`： +访问 `http://localhost:9621`： -- 📊 今日支出 / 本月支出 / 总记录数统计 -- 📋 最近 50 条记录列表 -- 🔍 按分类筛选 -- 🗑️ 删除记录 -- 📥 CSV 导出（Excel 兼容 BOM 编码） +- 📊 记账统计 / 最近记录 / 分类筛选 / CSV 导出 +- 🧩 模块设置：CF / CPA / cfdav / AI +- 🔌 渠道管理：QQ / Telegram / 飞书 配置与连接测试 +- 🧾 OPS 任务与目标主机管理 +- 🛡️ 审计日志 ## 🏗️ 项目结构 ``` -xiaji-go/ -├── cmd/main.go # 入口文件 +ops-assistant/ +├── cmd/ +│ ├── main.go # 服务入口 +│ ├── ops-runner/ # CLI 直跑 runbook（运维侧入口） +│ └── runbook_test.go # runbook 联调探针（-tags runbooktest） ├── config/config.go # 配置加载与验证 -├── version/version.go # 版本信息 -├── models/models.go # 数据模型与分类关键词 +├── models/models.go # 数据模型（GORM + AutoMigrate） ├── internal/ -│ ├── bot/telegram.go # Telegram Bot -│ ├── qq/qq.go # QQ Bot (WebSocket) -│ ├── service/finance.go # 记账核心服务（jieba 分词） -│ └── web/server.go # Web 管理后台 -├── templates/index.html # Web 前端页面 +│ ├── 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 镜像 -├── docker-compose.yml # Docker Compose -└── Makefile # 构建脚本 +├── 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 "/cf dns list " ``` ## 📋 技术栈 -- **语言**: Go 1.22 -- **Web 框架**: Gin -- **数据库**: SQLite (GORM) -- **分词**: gojieba (结巴分词 Go 版) -- **Telegram SDK**: go-telegram-bot-api v5 -- **QQ SDK**: tencent-connect/botgo v0.2.1 (WebSocket 模式) +- **语言**: 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 +MIT \ No newline at end of file diff --git a/ops-runner b/ops-runner deleted file mode 100755 index 6b79ff5..0000000 Binary files a/ops-runner and /dev/null differ