openclaw/ops-assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: README 重写为 ops-assistant 框架版

Browse Source 
- 版本说明更正（0.0.1 起版，注明由 xiaji-go 演进而来）
- 新增 OPS 命令参考（/cf /cpa /cfdav /sub /mail）
- 新增 Runbook 自动化章节（严格断言 / 结果回传 / 任务审计）
- 补充开发与发布流程、模块凭据存储说明
This commit is contained in:
openclaw
2026-09-13 07:44:57 +08:00
parent 811574cc6b
commit e6e033e248
3 changed files with 152 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+1 -1
View File
@@ -28,4 +28,4 @@ config.yaml
Thumbs.db Thumbs.db
# Go # Go
vendor/ vendor/ops-runner
README.md
+151 -103
View File
@@ -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） - **项目更名**：`xiaji-go` → `ops-assistant`（go.mod / 二进制 / systemd 同步）
- 新增审计页面：`/audit`（中文化） - **模块化命令框架**：`internal/core/module` 统一命令模板、门控（feature flag / confirm / dry-run）、错误标签（ecode）、结果格式化回传
- 新增一键生效接口：`POST /api/v1/admin/channels/:platform/apply` - **Runbook 执行器增强**（`internal/core/runbook`）：
- 渠道配置安全增强：`***` 脱敏占位符不会覆盖真实 secrets - 新增动作：`http.get` / `http.post` / `assert.json`（支持 `expect_success` 严格断言，API 失败不再假阳性）
- apply 失败返回增强：失败时返回 `stage` 与 `committed` 字段 - 目标主机管理（`ops_targets`，默认 seed：hwsg / wjynl）
- 首页/登录/渠道/审计页面版本显示统一为 `vX.Y.Z` - 任务与步骤全程落库（`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 模式） - **多平台接入**：QQ 官方 Bot（WebSocket）、Telegram Bot、飞书（通道层预留）
- **智能记账**：发送自然语言自动识别金额和消费分类（基于 jieba 分词） - **智能记账**：自然语言识别金额与消费分类（jieba 分词，150+ 预设关键词）
- **150+ 预设分类关键词**：餐饮、交通、购物、饮品、水果、住房、医疗、娱乐等 - **OPS 命令**：`/cf` `/cpa` `/cfdav` `/sub` `/mail`，写操作带 dry-run / 确认门控
- **Web 管理后台**：响应式设计，支持记录查看、删除、CSV 导出 - **Runbook 自动化**：YAML 定义、步骤编排、断言校验、任务审计
- **金额精确**：使用分（int64）存储，避免浮点精度问题 - **Web 管理后台**：记录查看 / 删除 / CSV 导出、模块与渠道配置、任务与审计查看
- **优雅关闭**：支持 SIGTERM/SIGINT 信号，干净退出 - **金额精确**：分（int64）存储，避免浮点误差
- **优雅关闭**：SIGTERM/SIGINT 干净退出
## 📦 快速开始 ## 📦 快速开始
### 二进制运行 ### 二进制运行
```bash ```bash
# 1. 复制配置文件
cp config.yaml.example config.yaml cp config.yaml.example config.yaml
vi config.yaml # 填入 Bot Token 等
# 2. 编辑配置（填入 Bot Token 等信息） ./ops-assistant
vi config.yaml
# 3. 运行
./xiaji-go
``` ```
### Docker 运行 ### Docker 运行
```bash ```bash
# 1. 准备配置文件 cp config.yaml.example config.yaml && vi config.yaml
cp config.yaml.example config.yaml
vi config.yaml
# 2. 使用 docker-compose
docker-compose up -d docker-compose up -d
# 或
# 或直接 docker run docker run -d --name ops-assistant -p 9621:9621 \
docker run -d \
--name xiaji-go \
-p 9521:9521 \
-v $(pwd)/config.yaml:/app/config.yaml:ro \ -v $(pwd)/config.yaml:/app/config.yaml:ro \
-v $(pwd)/data:/app/data \ -v $(pwd)/data:/app/data \
ouaone/xiaji-go:latest ouaone/ops-assistant:latest
``` ```
### 从源码编译 ### 从源码编译
@@ -61,8 +55,6 @@ docker run -d \
```bash ```bash
# 需要 Go 1.22+、GCC（gojieba 依赖 CGO） # 需要 Go 1.22+、GCC（gojieba 依赖 CGO）
make build make build
# 交叉编译 Linux
make build-linux make build-linux
``` ```
@@ -70,7 +62,7 @@ make build-linux
```yaml ```yaml
server: server:
port: 9521 # Web 后台端口 port: 9621 # Web 后台端口
key: "your-secret-key" # 会话密钥 key: "your-secret-key" # 会话密钥
database: database:
@@ -78,109 +70,165 @@ database:
admin: admin:
username: "admin" # Web 后台用户名 username: "admin" # Web 后台用户名
password: "your_password" # Web 后台密码 password: "your_password" # 弱密码启动时会告警
telegram: telegram:
enabled: true # 是否启用 Telegram Bot enabled: true
token: "YOUR_BOT_TOKEN" # BotFather 获取的 Token token: "YOUR_BOT_TOKEN"
qqbot: qqbot:
enabled: false # 是否启用 QQ Bot enabled: false
appid: "YOUR_APPID" # QQ 开放平台 AppID appid: "YOUR_APPID"
secret: "YOUR_SECRET" # QQ 开放平台 AppSecret secret: "YOUR_SECRET"
``` ```
## 💬 使用方式 > **模块凭据**（CF API Token、CPA 管理令牌、cfdav 账号等）保存在数据库 `app_settings` 表，通过 Web 后台「模块设置」页配置，**不写入配置文件**；渠道 secrets 在数据库内加密存储（`enc:v1:` 前缀）。
### Telegram Bot 命令 ## 💬 记账功能
| 命令 | 说明 |
|------|------|
| `/start` | 欢迎信息 |
| `/help` | 使用帮助 |
| `/list` | 最近 10 条记录 |
| `/today` | 今日消费汇总 |
| 直接发消息 | 自动记账（如"午饭 25元"） |
### QQ Bot 关键词 ### QQ Bot 关键词
| 关键词 | 说明 | | 关键词 | 说明 |
|--------|------| |--------|------|
| `帮助` / `菜单` / `功能` | 显示帮助 | | `帮助` / `菜单` | 显示帮助 |
| `查看` / `记录` / `列表` | 最近 10 条记录 | | `查看` / `记录` / `列表` | 最近 10 条记录 |
| `今日` / `今天` | 今日消费汇总 | | `今日` / `今天` | 今日消费汇总 |
| 直接发消息 | 自动记账 | | 直接发消息 | 自动记账（如"午饭 25元"） |
### 记账格式 ### Telegram Bot 命令
支持多种自然语言格式： `/start` `/help` `/list` `/today`，或直接发消息自动记账。
### 支持格式与分类
``` ```
午饭 25元 午饭 25元 / 打车 ¥30 / 买咖啡15块 / 超市买水果38.5
打车 ¥30
买咖啡15块
车费10元
超市买水果38.5
``` ```
### 消费分类 预设 150+ 关键词覆盖：🍜 餐饮、🚗 交通、🛒 购物、☕ 饮品、🍎 水果、🍪 零食、🏠 住房、📱 通讯、💊 医疗、🎮 娱乐、📚 教育、🚬 烟酒。
系统预设了 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` | 查看模块启用状态 |
## 📜 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 管理后台 ## 🌐 Web 管理后台
访问 `http://localhost:9521`： 访问 `http://localhost:9621`：
- 📊 今日支出 / 本月支出 / 总记录数统计 - 📊 记账统计 / 最近记录 / 分类筛选 / CSV 导出
- 📋 最近 50 条记录列表 - 🧩 模块设置：CF / CPA / cfdav / AI
- 🔍 按分类筛选 - 🔌 渠道管理：QQ / Telegram / 飞书 配置与连接测试
- 🗑️ 删除记录 - 🧾 OPS 任务与目标主机管理
- 📥 CSV 导出（Excel 兼容 BOM 编码） - 🛡️ 审计日志
## 🏗️ 项目结构 ## 🏗️ 项目结构
``` ```
xiaji-go/ ops-assistant/
├── cmd/main.go # 入口文件 ├── cmd/
│ ├── main.go # 服务入口
│ ├── ops-runner/ # CLI 直跑 runbook（运维侧入口）
│ └── runbook_test.go # runbook 联调探针（-tags runbooktest）
├── config/config.go # 配置加载与验证 ├── config/config.go # 配置加载与验证
├── version/version.go # 版本信息 ├── models/models.go # 数据模型（GORM + AutoMigrate）
├── models/models.go # 数据模型与分类关键词
├── internal/ ├── internal/
│ ├── bot/telegram.go # Telegram Bot │ ├── core/
│ ├── qq/qq.go # QQ Bot (WebSocket) │ │ ├── command/ # 命令解析
│ ├── service/finance.go # 记账核心服务（jieba 分词） │ │ ├── ecode/ # 错误码与标签
│ └── web/server.go # Web 管理后台 │ │ ├── module/ # 命令模板 / 门控 / 格式化回传
├── templates/index.html # Web 前端页面 │ │ ├── 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 # 配置示例 ├── config.yaml.example # 配置示例
├── Dockerfile # Docker 镜像 ├── Dockerfile / docker-compose.yml
├── docker-compose.yml # Docker Compose └── Makefile # 构建 / 版本 / 发布
└── 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 - **语言**: Go 1.22（CGO：gojieba）
- **Web 框架**: Gin - **Web 框架**: Gin · **数据库**: SQLite (GORM)
- **数据库**: SQLite (GORM) - **分词**: gojieba · **QQ SDK**: tencent-connect/botgo v0.2.1（WebSocket）· **TG SDK**: go-telegram-bot-api v5
- **分词**: gojieba (结巴分词 Go 版) - **自动化**: 自研 runbook 执行器（YAML 编排 + 严格断言 + 任务审计）
- **Telegram SDK**: go-telegram-bot-api v5
- **QQ SDK**: tencent-connect/botgo v0.2.1 (WebSocket 模式)
## 📄 License ## 📄 License
MIT MIT
ops-runner
BIN
View File
Binary file not shown.