diff --git a/README.md b/README.md index aca195a..44e7bf5 100644 --- a/README.md +++ b/README.md @@ -1,186 +1,94 @@ # 🛠️ Ops-Assistant -一个支持 **Telegram Bot** 和 **QQ Bot** 的智能记账机器人,带 Web 管理后台。 +一个面向运维场景的 **命令化 + Runbook** 自动化助手。通过 Telegram / QQ / 飞书等入口,触发 **可审计、可回溯、可控风控** 的运维流程。 -> 当前稳定版本:`v1.1.12` +> 当前稳定版本:`v0.0.1` -## 🆕 v1.1.12 更新 +## 🎯 设计目标 -- 新增渠道管理页:`/channels`(移动端优先,统一 UI) -- 新增审计页面:`/audit`(中文化) -- 新增一键生效接口:`POST /api/v1/admin/channels/:platform/apply` -- 渠道配置安全增强:`***` 脱敏占位符不会覆盖真实 secrets -- apply 失败返回增强:失败时返回 `stage` 与 `committed` 字段 -- 首页/登录/渠道/审计页面版本显示统一为 `vX.Y.Z` +- **固定命令 + 固定流水线**:AI 只做解释,不参与关键执行决策 +- **步骤级审计**:每一步都有状态、输出、耗时与错误记录 +- **高风险能力默认关闭**:必须显式开关 + 二次确认 +- **Runbook 驱动**:流程可复用、可回溯、可迁移 -## ✨ 功能特性 +## ✅ 当前能力 -- **多平台支持**:同时接入 Telegram Bot 和 QQ Bot(WebSocket 模式) -- **智能记账**:发送自然语言自动识别金额和消费分类(基于 jieba 分词) -- **150+ 预设分类关键词**:餐饮、交通、购物、饮品、水果、住房、医疗、娱乐等 -- **Web 管理后台**:响应式设计,支持记录查看、删除、CSV 导出 -- **金额精确**:使用分(int64)存储,避免浮点精度问题 -- **优雅关闭**:支持 SIGTERM/SIGINT 信号,干净退出 +### 核心功能 +- 统一命令入口(Telegram / QQ / 飞书) +- Runbook 执行引擎(YAML) +- 步骤级审计与回溯 +- 目标主机管理(ops targets) +- 风险控制与干跑(dry-run) -## 📦 快速开始 +### 已支持模块 +- **CPA 模块** + - `/cpa status` + - `/cpa usage backup` + - `/cpa usage restore [--confirm YES_RESTORE] [--dry-run]` -### 二进制运行 +- **Cloudflare 模块(CF)** + - `/cf status` + - `/cf zones` + - `/cf dns list ` + - `/cf dns update [ttl] [proxied:true|false]` + - `/cf dnsadd [on|off] [type]` + - `/cf dnsset [true]` + - `/cf dnsdel YES` + - `/cf dnsproxy on|off` + - `/cf workers list` + +> 详细命令设计见:`docs/cf-commands-design.md` + +## 🧩 Runbook DSL(概览) +支持动作: +- `ssh.exec` +- `http.get` / `http.post` +- `file.upload` / `file.extract` +- `assert.json` +- `sleep` + +变量来源: +- `inputs.*` +- `env.*` +- `steps..output` + +## 🗂️ 项目结构 + +``` +ops-assistant/ +├── cmd/ # 入口 +├── internal/ +│ ├── core/ # 命令解析/执行/审计/风险控制 +│ └── module/ # CPA/CF/Mail 等模块 +├── runbooks/ # YAML Runbook +├── templates/ # Web 控制台模板 +├── docs/ # 设计/规范/复盘 +└── config.yaml.example # 配置示例 +``` + +## ⚙️ 快速开始 ```bash -# 1. 复制配置文件 +# 1. 复制配置 cp config.yaml.example config.yaml -# 2. 编辑配置(填入 Bot Token 等信息) +# 2. 编辑配置(Bot Token / 管理员账号等) vi config.yaml # 3. 运行 ./ops-assistant ``` -### Docker 运行 +## 🔒 风控与审计 +- 高风险操作默认关闭(feature flag) +- 需要二次确认的命令必须带确认词 +- 每个命令产生 `ops_jobs` 记录,步骤落地 `ops_job_steps` -```bash -# 1. 准备配置文件 -cp config.yaml.example config.yaml -vi config.yaml - -# 2. 使用 docker-compose -docker-compose up -d - -# 或直接 docker run -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 - -# 交叉编译 Linux -make build-linux -``` - -## ⚙️ 配置说明 - -```yaml -server: - port: 9621 # Web 后台端口 - key: "your-secret-key" # 会话密钥 - -database: - path: "./xiaji.db" # SQLite 数据库路径 - -admin: - username: "admin" # Web 后台用户名 - password: "your_password" # Web 后台密码 - -telegram: - enabled: true # 是否启用 Telegram Bot - token: "YOUR_BOT_TOKEN" # BotFather 获取的 Token - -qqbot: - enabled: false # 是否启用 QQ Bot - appid: "YOUR_APPID" # QQ 开放平台 AppID - secret: "YOUR_SECRET" # QQ 开放平台 AppSecret -``` - -## 💬 使用方式 - -### Telegram Bot 命令 - -| 命令 | 说明 | -|------|------| -| `/start` | 欢迎信息 | -| `/help` | 使用帮助 | -| `/list` | 最近 10 条记录 | -| `/today` | 今日消费汇总 | -| 直接发消息 | 自动记账(如"午饭 25元") | - -### QQ Bot 关键词 - -| 关键词 | 说明 | -|--------|------| -| `帮助` / `菜单` / `功能` | 显示帮助 | -| `查看` / `记录` / `列表` | 最近 10 条记录 | -| `今日` / `今天` | 今日消费汇总 | -| 直接发消息 | 自动记账 | - -### 记账格式 - -支持多种自然语言格式: - -``` -午饭 25元 -打车 ¥30 -买咖啡15块 -车费10元 -超市买水果38.5 -``` - -### 消费分类 - -系统预设了 150+ 个关键词,自动匹配以下分类: - -| 分类 | 示例关键词 | -|------|-----------| -| 🍜 餐饮 | 早饭、午饭、晚饭、外卖、火锅、面条 | -| 🚗 交通 | 打车、车费、地铁、公交、加油 | -| 🛒 购物 | 买、淘宝、超市、衣服、手机 | -| ☕ 饮品 | 咖啡、奶茶、星巴克、可乐 | -| 🍎 水果 | 水果、苹果、香蕉、西瓜 | -| 🍪 零食 | 零食、面包、蛋糕、甜品 | -| 🏠 住房 | 房租、水电、物业、宽带 | -| 📱 通讯 | 话费、流量、充值 | -| 💊 医疗 | 看病、药、医院、挂号 | -| 🎮 娱乐 | 电影、游戏、健身、旅游 | -| 📚 教育 | 书、课、培训、学费 | -| 🚬 烟酒 | 烟、白酒、红酒 | - -## 🌐 Web 管理后台 - -访问 `http://localhost:9621`: - -- 📊 今日支出 / 本月支出 / 总记录数统计 -- 📋 最近 50 条记录列表 -- 🔍 按分类筛选 -- 🗑️ 删除记录 -- 📥 CSV 导出(Excel 兼容 BOM 编码) - -## 🏗️ 项目结构 - -``` -ops-assistant/ -├── cmd/main.go # 入口文件 -├── config/config.go # 配置加载与验证 -├── version/version.go # 版本信息 -├── models/models.go # 数据模型与分类关键词 -├── internal/ -│ ├── bot/telegram.go # Telegram Bot -│ ├── qq/qq.go # QQ Bot (WebSocket) -│ ├── service/finance.go # 记账核心服务(jieba 分词) -│ └── web/server.go # Web 管理后台 -├── templates/index.html # Web 前端页面 -├── config.yaml.example # 配置示例 -├── Dockerfile # Docker 镜像 -├── docker-compose.yml # Docker Compose -└── Makefile # 构建脚本 -``` - -## 📋 技术栈 - -- **语言**: 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 模式) +## 📌 相关文档 +- `docs/ops-assistant-v1.md`:v1 方案 +- `docs/cf-commands-design.md`:CF 命令设计 +- `docs/cf-dns-runbook-incident-20260313.md`:事故复盘 +- `docs/debug/cf-dnsproxy-dnsadd-20260319.md`:本次修复记录 ## 📄 License - MIT