Skip to content

Architecture_Overview.md

Latest commit

 

History

History
273 lines (213 loc) · 7.86 KB

Architecture_Overview.md

File metadata and controls

273 lines (213 loc) · 7.86 KB

TelegramSearchBot 架构概览文档

项目简介

TelegramSearchBot 是一个功能丰富的 Telegram 机器人，提供消息搜索、AI 处理、媒体下载等多种功能。本项目采用模块化设计，支持多平台部署，但在 Windows 平台上有特定的依赖优化。

整体架构

系统架构图

┌─────────────────────────┐
│    Telegram Bot API     │
└──────────┬──────────────┘
           │
┌──────────┴──────────────┐
│   TelegramSearchBot     │
│    (主服务进程)         │
├─────────────────────────┤
│ • 消息处理              │
│ • 命令解析              │
│ • 服务调度              │
│ • 数据存储              │
└──────────┬──────────────┘
           │
    ┌──────┴──────┐
    │             │
┌───┴────┐ ┌─────┴────┐
│OCR进程 │ │ASR进程   │
│(可选)  │ │(可选)   │
└────────┘ └──────────┘

核心组件

1. 主服务 (TelegramSearchBot)

  • 入口点: Program.cs
  • 功能: 机器人启动、配置加载、依赖注入、消息循环
  • 平台支持: Windows/Linux/macOS (部分功能有平台限制)

2. 模块化设计

  • 控制器层: 处理各种命令和消息
  • 服务层: 核心业务逻辑实现
  • 数据访问层: Entity Framework Core 数据库操作
  • 工具层: 第三方服务集成

3. 进程架构

  • 单进程模式: 基础功能运行
  • 多进程模式: OCR、ASR 等内存敏感功能通过独立进程运行

技术栈

核心技术

  • 运行时: .NET 10.0
  • 框架: ASP.NET Core 托管模型
  • 数据库: SQLite (Entity Framework Core)
  • 搜索引擎: Lucene.NET
  • 向量搜索: Faiss.NET

第三方集成

  • Telegram Bot API: 消息收发
  • PaddleOCR: 文字识别 (Windows优化)
  • Whisper: 语音识别
  • OpenAI API: LLM 集成
  • Bilibili API: 视频信息获取
  • MCP Servers: 支持外部 MCP 工具服务器（通过 AddMcpServer 动态配置）

AI 服务

  • LLM 提供商: OpenAI、Ollama、Gemini
  • MCP 集成: 支持 Model Context Protocol，可调用外部工具服务器
  • 内置工具: 24+ 内置工具（文件操作、搜索、URL处理等）
  • 工具迭代限制: 防止无限循环（默认25次）
  • 记忆系统: 对话上下文管理

本地 Bot API 服务

  • 内置 Telegram Bot API: 可选启用内置 Bot API 服务
  • 外部 Local API: 也可连接到已在本机其他位置运行的 Local Bot API
  • 优势: 支持最大 2GB 文件发送（vs 云端 50MB）
  • 配置: 内置模式需要 TelegramBotApiId 和 TelegramBotApiHash（从 my.telegram.org 获取）；外部模式使用 ExternalLocalBotApiBaseUrl

平台兼容性

Windows 平台 (完全支持)

  • 原生依赖: OpenCV、PaddleOCR 运行时
  • 进程管理: Windows Job Objects API
  • 文件路径: Windows特定路径格式

Linux 平台 (部分支持)

  • 限制: OCR、ASR 功能受限
  • 解决方案: Docker 容器化部署
  • 依赖: 需要安装系统级依赖

macOS 平台 (实验性支持)

  • 限制: 与 Linux 类似，部分功能受限
  • 建议: 主要用于开发测试

模块详细说明

消息处理流程

Telegram 更新 → 命令解析 → 控制器分发 → 业务处理 → 结果返回

数据流

  1. 消息接收: Telegram Bot API → Update 处理器
  2. 消息存储: 存入 SQLite 数据库
  3. 索引构建: Lucene.NET 创建搜索索引
  4. 向量生成: Faiss 创建语义索引
  5. 搜索处理: 多维度搜索查询

服务分层

Controller 层

  • SearchController: 搜索功能
  • AI/LLM/GeneralLLMController: AI 对话
  • Bilibili/BiliMessageController: B站内容处理
  • Download/*Controller: 媒体下载

Service 层

  • SearchService: 核心搜索逻辑
  • MessageService: 消息管理
  • AIServices: AI 功能封装
  • StorageServices: 文件存储管理

Infrastructure 层

  • DataDbContext: 数据库访问
  • LuceneManager: 搜索引擎管理
  • FaissVectorService: 向量索引管理

配置管理

配置文件

  • appsettings.json: 基础配置
  • 环境变量: 生产环境配置
  • 数据库配置: 动态配置存储

功能开关

  • LLM 提供商配置
  • 搜索功能开关
  • AI 工具启用状态

部署架构

单机部署

  • 适用场景: 个人使用、小型群组
  • 部署要求: 单服务器即可运行
  • 资源需求: 2GB RAM, 1核CPU

容器化部署

  • Docker: 支持 Docker 容器化
  • 镜像: 基于 .NET 10.0 运行时
  • 编排: 支持 Docker Compose

高可用部署 (未来规划)

  • Orleans 集群: 基于 Actor 模型的分布式架构
  • 负载均衡: 多实例部署
  • 数据分片: 水平扩展支持

监控与运维

日志系统

  • 框架: Serilog
  • 输出: 文件、控制台、OpenTelemetry
  • 级别: 支持动态调整

性能监控

  • 指标: 响应时间、内存使用、CPU占用
  • 工具: 内置性能计数器
  • 告警: 异常检测与通知

维护工具

  • 数据备份: 自动数据库备份
  • 索引重建: 搜索索引维护
  • 缓存清理: 定期缓存管理

开发规范

代码风格

  • 缩进: 4空格
  • 命名: PascalCase 类名, camelCase 变量
  • 格式化: 遵循 .editorconfig 配置

项目结构

TelegramSearchBot/
├── Controller/          # 请求处理
├── Service/            # 业务逻辑
├── Model/              # 数据模型
├── Interface/          # 接口定义
├── AppBootstrap/       # 进程管理
├── Migrations/         # 数据库迁移
└── Resources/          # 静态资源

测试策略

  • 单元测试: xUnit 测试框架
  • 集成测试: 端到端功能测试
  • 性能测试: 负载测试工具

安全考虑

数据安全

  • 敏感数据: API密钥环境变量存储
  • 用户隐私: 消息内容加密存储
  • 访问控制: 基于角色的权限管理

系统安全

  • 输入验证: 防止注入攻击
  • 文件上传: 类型和大小限制
  • 网络通信: HTTPS 强制使用

性能优化

缓存策略

  • 内存缓存: 频繁访问数据
  • 文件缓存: 媒体文件缓存
  • Redis: 分布式缓存支持

异步处理

  • I/O操作: 全部异步实现
  • 并发控制: 限流和队列管理
  • 资源池: 连接池复用

扩展性设计

插件架构

  • 模块化: 支持功能插件
  • 热加载: 运行时插件更新
  • 接口定义: 标准化扩展点

配置驱动

  • 功能开关: 运行时配置调整
  • 服务注册: 依赖注入配置
  • 路由规则: 动态URL处理

故障处理

异常处理

  • 全局异常: 统一的错误处理
  • 重试机制: 网络请求重试
  • 降级策略: 服务不可用时的备选方案

监控告警

  • 健康检查: 服务状态监控
  • 错误追踪: 异常日志分析
  • 性能告警: 资源使用监控

版本兼容性

.NET 版本

  • 当前: .NET 10.0
  • 最低: .NET 8.0 (LTS)
  • 升级策略: 跟随 LTS 版本

依赖管理

  • NuGet: 包版本锁定
  • 兼容性: 定期依赖更新
  • 安全补丁: 及时安全更新

文档资源

  • 用户指南: Bot_Commands_User_Guide.md
  • MCP文档: README_MCP.md
  • 向量搜索: README_FaissVectorSearch.md
  • API文档: 内联代码注释
  • 部署指南: Docker 相关文档
  • 开发指南: 代码贡献规范

最后更新: 2026-03-26 文档版本: 1.1