🏗️ 系统架构设计
本文档详细介绍 Sakura-Bot 的系统架构、模块设计和核心技术。
分类: 开发者文档
类型: 参考资料
难度: ⭐⭐
更新时间: 2026-05-01
📐 整体架构
系统概览
Sakura-Bot 采用模块化微服务架构，将功能拆分为多个独立模块，提高可维护性和可扩展性。
┌─────────────────────────────────────────────────────────────┐
│ 用户层 │
│ Telegram 频道用户 · 管理员 · 问答Bot用户 · WebUI 管理员 │
└────────────────────┬────────────────────────────────────────┘
│
┌────────────────────┴────────────────────────────────────────┐
│ Bot 层 │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ 主Bot │ │ 问答Bot │ │
│ │ (main.py) │ │ (qa_bot.py) │ │
│ │ │ │ │ │
│ │ - 频道监控 │ │ - 自然对话 │ │
│ │ - 消息总结 │ │ - 语义检索 │ │
│ │ - 投票功能 │ │ - 配额管理 │ │
│ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ │
│ │ WebUI API │ (FastAPI + Vue.js) │
│ │ - 仪表盘统计 │ │
│ │ - 频道管理 │ │
│ │ - 总结触发 │ │
│ │ - 转发管理 │ │
│ │ - 数据库管理 │ │
│ └──────────────┘ │
└────────────────────┬────────────────────────────────────────┘
│
┌────────────────────┴────────────────────────────────────────┐
│ 核心层 (core/) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ AI客户端 │ │ 数据库 │ │ 向量存储 │ │ 配置管理 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │会话管理 │ │ 意图解析 │ │ 记忆管理 │ │ 问答引擎 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└────────────────────┬────────────────────────────────────────┘
│
┌────────────────────┴────────────────────────────────────────┐
│ 数据层 │
│ MySQL · ChromaDB · 配置文件 · 会话文件 │
└─────────────────────────────────────────────────────────────┘🎯 设计原则
1. 模块化设计
- 单一职责: 每个模块只负责一个功能域
- 松耦合: 模块间通过清晰接口通信
- 高内聚: 相关功能组织在一起
2. 异步优先
- 使用
async/await处理 I/O 操作 - 支持 Telegram 并发请求
- 提高系统响应速度
3. 错误处理
- 自定义异常类
- 智能重试机制
- 优雅降级策略
4. 可扩展性
- 插件化命令处理
- 可配置的 AI 提供商
- 灵活的存储后端
📦 核心模块
1. AI 模块 (core/ai/)
职责: 封装 AI API 调用，支持多种 AI 提供商。
核心功能:
- LLM 推理（总结生成、问答）
- Embedding 生成（向量化）
- Reranker 调用（结果重排）
- 错误处理和重试
关键类:
python
class AIClient:
async def generate_summary(messages: list[Message]) -> str
async def analyze_with_ai(text: str) -> str
async def generate_embedding(text: str) -> list[float]
async def rerank(query: str, documents: list[str]) -> list[int]支持的 AI 提供商:
- OpenAI (GPT-4, GPT-3.5)
- DeepSeek (deepseek-chat)
- SiliconFlow (Embedding, Reranker)
- 任何 OpenAI 兼容的 API
2. 数据库模块 (core/infrastructure/database/)
职责: 管理所有数据持久化操作。
数据表:
| 表名 | 用途 |
|---|---|
summaries | 存储频道总结记录 |
usage_quota | 问答Bot配额管理 |
channel_profiles | 频道画像数据 |
conversation_history | 多轮对话历史 |
poll_regenerations | 投票重新生成记录 |
poll_voters | 投票者记录 |
forwarding_stats | 转发统计信息 |
cross_bot_* | 主 Bot 与 QA Bot 跨进程通信队列 |
submissions | 投稿审核记录 |
支持的数据库:
- MySQL（当前唯一支持的关系数据库）
关键特性:
- aiomysql 连接池管理
- 自动初始化和迁移
- 表名/列名白名单校验
- WebUI 数据库管理接口支持分页查询和受控写操作
- 主 Bot 与 QA Bot 通过 MySQL 队列进行跨进程通信
3. 向量存储模块 (core/ai/vector_store.py)
职责: 管理 ChromaDB 向量数据库，实现语义检索。
核心功能:
- 添加总结向量
- 语义搜索
- 向量更新和删除
- 元数据过滤
使用的技术:
- ChromaDB: 向量数据库
- BGE 模型: 中文 Embedding (bge-m3, bge-large-zh-v1.5)
- 余弦相似度: 相似度计算
工作流程:
总结生成 → 生成 Embedding → 存储到 ChromaDB
用户查询 → 生成查询向量 → 语义检索 → 返回 Top-K 结果4. 会话管理模块 (conversation_manager.py)
职责: 管理问答Bot的多轮对话上下文。
核心功能:
- 会话创建和超时管理
- 对话历史存储
- 上下文格式化
- 会话清理
会话生命周期:
用户首次提问 → 创建新会话
30分钟内新消息 → 继续当前会话
超过30分钟 → 创建新会话
用户发送 /clear → 手动清除会话5. 意图解析模块 (intent_parser.py)
职责: 解析用户自然语言查询，识别意图和参数。
识别能力:
- 时间范围: 今天、昨天、本周、上周、最近N天
- 关键词: AI、GPT、Python 等
- 主题: 技术、新闻、讨论
- 查询类型: 总结查询、统计查询、状态查询
返回结果:
python
{
"intent": "summary_query", # 意图类型
"time_range": 7, # 时间范围（天）
"keywords": ["AI", "GPT"], # 关键词
"topics": ["技术"], # 主题
}6. 记忆管理模块 (memory_manager.py)
职责: 管理频道画像和记忆数据。
核心功能:
- 频道画像生成和更新
- 关键词提取
- 主题分类
- 智能搜索
频道画像维度:
- 风格: tech/casual/neutral
- 主题: 常讨论的主题列表
- 关键词频率: 关键词出现频率
- 情感倾向: positive/neutral/negative
- 统计信息: 平均消息长度、总结总数
7. 问答引擎模块 (core/ai/qa_engine_v3.py)
职责: 实现 RAG（检索增强生成）问答流程。
工作流程:
用户查询
↓
意图解析
↓
语义检索 (Top-20)
↓
关键词检索 (备选)
↓
RRF 融合
↓
Reranker 重排序 (Top-20 → Top-5)
↓
RAG 生成回答
↓
返回结果核心算法:
- RRF (Reciprocal Rank Fusion): 融合多路检索结果
- Reranker: BGE-reranker-v2-m3 精排
- RAG 生成: 基于精选上下文生成回答
8. 重排序模块 (core/ai/reranker.py)
职责: 使用 Reranker 模型对检索结果精排。
工作原理:
输入: 查询 + 20个候选文档
↓
Reranker 模型计算相关性得分
↓
按得分排序
↓
输出: Top-5 最相关文档使用模型:
- BGE-reranker-v2-m3 (中文优化)
- 通过交叉注意力计算相关性
9. Telegram 与 UserBot 模块 (core/telegram/, core/handlers/)
职责: 封装 Telegram MTProto API 操作。
核心功能:
- 用户客户端（频道消息抓取）
- Bot 客户端（命令处理）
- 消息发送
- 频道管理
10. 命令处理模块 (core/commands/)
职责: 处理所有 Telegram Bot 命令。
命令分类:
- AI 配置命令: 提示词、AI 配置
- 频道命令: 添加/删除/查看频道
- 调度命令: 设置自动总结时间
- 投票命令: 投票配置
- 系统控制: 暂停/恢复/重启
- 历史记录: 查看/导出/统计
- 转发管理: 规则、过滤、底栏和统计
- UserBot 管理: 状态、加入、离开和频道列表
实现方式:
- 使用装饰器注册命令
- 支持中英文别名
- 状态管理（多步骤交互）
- Main Bot 欢迎和帮助消息提供内联键盘入口，复用既有命令处理器
11. WebUI API 模块 (core/web_api/ + web/)
职责: 提供浏览器端管理面板和 REST API。
后端能力:
- FastAPI 路由与中间件
- JWT 认证与管理员权限校验
- 仪表盘、频道、调度、转发、系统、统计、向量存储和数据库管理 API
- 配置保存后显式触发热重载
前端能力:
- Vue 3 + Vite + TypeScript + Naive UI
- 深色/浅色主题持久化
- 转发规则可视化编辑和底栏占位符插入
- 数据库表分页浏览和受控维护操作
部署方式:
- Docker 多阶段构建会先构建
web/前端，再由 FastAPI 挂载静态资源 - 本地开发可在
web/中运行 Vite 开发服务，并代理到后端 API
🔄 数据流
总结生成流程
定时任务触发
↓
获取频道消息
↓
AI 生成总结
↓
生成 Embedding
↓
存储到数据库
↓
存储向量到 ChromaDB
↓
发送到管理员/频道
↓
生成投票（可选）
↓
完成问答流程
用户发送问题
↓
意图解析
↓
配额检查
↓
语义检索
↓
重排序
↓
AI 生成回答
↓
更新配额
↓
返回回答🔐 安全设计
1. 数据隔离
- 不同用户的对话历史完全隔离
- 不同频道的配置独立存储
- 管理员权限验证
2. 配额管理
- 用户级配额（每日限制）
- 系统总配额（防滥用）
- 管理员豁免
- 自动重置机制
3. 错误处理
- 自定义异常类
- 详细错误日志
- 用户友好的错误消息
- 降级策略
🚀 性能优化
1. 数据库优化
- MySQL 连接池: 减少连接开销并提升并发能力
- 索引优化: 关键字段建立索引
- 分页查询: WebUI 和统计接口使用分页/偏移量避免一次加载大量数据
- 行数统计优化: 数据库管理页面复用优化后的表行数查询
- 查询缓存: 热点数据缓存
2. AI 调用优化
- 提示词优化: 精简高效
- 温度控制: 平衡创造性和准确性
- 重试机制: 自动重试临时错误
- 降级方案: AI 失败时的备选方案
3. 并发处理
- 异步 I/O: 所有 I/O 操作异步化
- 任务队列: 后台任务处理
- 进程隔离: 问答Bot独立进程
📊 监控与日志
日志级别
- DEBUG: 详细调试信息
- INFO: 一般信息
- WARNING: 警告信息
- ERROR: 错误信息
- CRITICAL: 严重错误
日志位置
- 应用日志:
logs/sakura_bot.log - 错误日志:
logs/error.log - QA Bot 日志:
logs/qa_bot.log
监控指标
- 总结生成成功率
- AI 调用延迟
- 查询响应时间
- 配额使用情况
🔧 配置管理
环境变量 (data/.env)
主要配置项：
- Telegram 凭证
- AI API 配置
- 数据库配置
- 日志级别
- 功能开关
配置文件 (data/config.json)
运行时配置：
- 频道列表
- 投票配置
- 提示词配置
- 问答Bot人格
🧪 测试策略
单元测试
- 每个模块独立测试
- 使用 pytest fixtures
- Mock 外部依赖
- 覆盖率目标 ≥ 90%
集成测试
- 模块间交互测试
- 数据库集成测试
- AI API 集成测试
端到端测试
- 完整工作流测试
- 用户场景测试
📚 相关文档
🔗 相关资源
- 开发者文档 - 开发者指南
- 贡献指南 - 如何贡献
- GitHub Issues - 问题跟踪
🌸 Sakura-Bot 架构设计
模块化 · 可扩展 · 高性能