feat: 添加性能优化和架构文档,更新依赖和核心模块
refactor(browser_manager): 实现页面池机制以提升性能 refactor(image_manager): 添加模板缓存并集成页面池 refactor(bili_parser): 迁移到异步HTTP请求并实现会话复用 docs: 新增性能优化、架构设计和最佳实践文档 chore: 更新requirements.txt添加新依赖
This commit is contained in:
62
docs/core-concepts/architecture.md
Normal file
62
docs/core-concepts/architecture.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# 核心架构
|
||||
|
||||
NEO Bot Framework 不是那种随便写写的玩具。它的架构设计只有一个核心目标:**极致性能与稳定性的平衡**。
|
||||
|
||||
我们不搞花里胡哨的抽象,只做最有效的工程实践。
|
||||
|
||||
## 1. 运行时架构
|
||||
|
||||
### Python 3.14 + JIT
|
||||
我们激进地采用了 Python 3.14,并默认开启 JIT (Just-In-Time) 编译器。
|
||||
* **原理**: JIT 会在运行时分析热点代码,将其编译为机器码,跳过字节码解释过程。
|
||||
* **收益**: CPU 密集型任务(如复杂的正则匹配、数据处理)性能提升显著。
|
||||
|
||||
### Mypyc 编译 (AOT)
|
||||
光有 JIT 还不够。核心模块(`core/ws.py`, `core/managers/*.py`)支持通过 Mypyc 编译为 C 扩展。
|
||||
* **原理**: Mypyc 利用 Python 的类型提示,将 Python 代码直接翻译成 C 代码,并编译为二进制 `.pyd` 或 `.so` 文件。
|
||||
* **收益**: 核心路径的执行速度接近 C 语言,完全摆脱 GIL 的部分束缚。
|
||||
|
||||
### 异步 IO 模型
|
||||
* **Linux**: 强制使用 `uvloop`,这是目前最快的 Python 异步事件循环,基于 libuv(Node.js 同款)。
|
||||
* **Windows**: 使用原生 `ProactorEventLoop` (IOCP),虽然不如 uvloop,但在 Windows 上是最优解。
|
||||
* *注*: 我们禁用了 `winloop`,因为它与 Playwright 存在兼容性问题。
|
||||
|
||||
## 2. 网络架构
|
||||
|
||||
### 正向 WebSocket + FastAPI 混合模式
|
||||
这是一个独特的混合架构,兼顾了部署便利性和功能扩展性。
|
||||
|
||||
* **连接层 (Client)**: Bot 主动通过 WebSocket 连接到 OneBot (NapCat)。
|
||||
* **优势**: 不需要公网 IP,不需要内网穿透,只要能上网就能跑。
|
||||
* **服务层 (Server)**: Bot 内部启动一个 FastAPI 服务。
|
||||
* **优势**: 提供 HTTP API、Webhook 接收、静态资源托管(如帮助图片、Web 控制台)。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph Local [本地环境 / 服务器]
|
||||
Bot[NEO Bot]
|
||||
FastAPI[FastAPI Server]
|
||||
Browser[Playwright Pool]
|
||||
end
|
||||
|
||||
subgraph Remote [OneBot / 外部]
|
||||
NapCat[NapCatQQ]
|
||||
User[用户浏览器]
|
||||
end
|
||||
|
||||
Bot -- WebSocket (Client) --> NapCat
|
||||
User -- HTTP --> FastAPI
|
||||
Bot -- 控制 --> Browser
|
||||
```
|
||||
|
||||
## 3. 资源管理架构
|
||||
|
||||
### 单例管理器 (Singleton Managers)
|
||||
所有的核心组件(指令、权限、浏览器、图片)都是全局单例。
|
||||
* **零开销访问**: 任何插件都可以直接 import 使用,无需传递上下文。
|
||||
* **状态一致性**: 全局共享状态,拒绝数据同步问题。
|
||||
|
||||
### 资源池化 (Pooling)
|
||||
我们拒绝“用完即扔”的浪费行为。
|
||||
* **Browser Pool**: 浏览器页面预先创建,用完归还,拒绝反复启动进程。
|
||||
* **Connection Pool**: Redis 和 HTTP 请求共享连接池,拒绝反复握手。
|
||||
Reference in New Issue
Block a user