chore: initial commit
This commit is contained in:
你的用户名
348
docs/architecture_diagrams.md
Normal file
348
docs/architecture_diagrams.md
Normal file
@@ -0,0 +1,348 @@
|
||||
# funstat BOT MCP 封装 - 架构流程图
|
||||
|
||||
## 1. 整体系统架构
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "用户层"
|
||||
U1[用户 1]
|
||||
U2[用户 2]
|
||||
U3[用户 N...]
|
||||
end
|
||||
|
||||
subgraph "Claude Code"
|
||||
C1[Claude Instance 1]
|
||||
C2[Claude Instance 2]
|
||||
C3[Claude Instance N]
|
||||
end
|
||||
|
||||
subgraph "MCP Server"
|
||||
MCP[MCP 工具接口]
|
||||
Q[请求队列<br/>Rate Limiter]
|
||||
S[智能调度器]
|
||||
Cache[结果缓存<br/>Redis/内存]
|
||||
end
|
||||
|
||||
subgraph "Telegram 客户端层"
|
||||
TC1[Telethon Client 1]
|
||||
TC2[Telethon Client 2]
|
||||
TC3[Telethon Client N]
|
||||
end
|
||||
|
||||
subgraph "Telegram 生态"
|
||||
Bot[@openaiw_bot<br/>funstat/infostat]
|
||||
end
|
||||
|
||||
U1 --> C1
|
||||
U2 --> C2
|
||||
U3 --> C3
|
||||
|
||||
C1 --> MCP
|
||||
C2 --> MCP
|
||||
C3 --> MCP
|
||||
|
||||
MCP --> Q
|
||||
Q --> S
|
||||
S --> Cache
|
||||
|
||||
S --> TC1
|
||||
S --> TC2
|
||||
S --> TC3
|
||||
|
||||
TC1 --> Bot
|
||||
TC2 --> Bot
|
||||
TC3 --> Bot
|
||||
|
||||
Bot --> TC1
|
||||
Bot --> TC2
|
||||
Bot --> TC3
|
||||
|
||||
TC1 --> S
|
||||
TC2 --> S
|
||||
TC3 --> S
|
||||
|
||||
S --> Cache
|
||||
Cache --> MCP
|
||||
MCP --> C1
|
||||
MCP --> C2
|
||||
MCP --> C3
|
||||
|
||||
style MCP fill:#e1f5ff
|
||||
style Q fill:#fff9c4
|
||||
style S fill:#c8e6c9
|
||||
style Cache fill:#ffccbc
|
||||
style Bot fill:#f3e5f5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 单次请求完整流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 用户
|
||||
participant C as Claude Code
|
||||
participant M as MCP Server
|
||||
participant RL as Rate Limiter
|
||||
participant Cache as 缓存
|
||||
participant TC as Telethon Client
|
||||
participant Bot as @openaiw_bot
|
||||
|
||||
U->>C: 发起查询<br/>"搜索 python 群组"
|
||||
C->>M: openaiw_search_groups(query="python")
|
||||
|
||||
M->>Cache: 检查缓存
|
||||
alt 缓存命中
|
||||
Cache-->>M: 返回缓存结果
|
||||
M-->>C: 返回结果
|
||||
C-->>U: 展示结果
|
||||
else 缓存未命中
|
||||
M->>RL: 请求令牌
|
||||
RL->>RL: 检查速率限制
|
||||
|
||||
alt 未达到限制
|
||||
RL-->>M: 授予令牌
|
||||
M->>TC: send_message("/search python")
|
||||
TC->>Bot: 发送消息
|
||||
Bot->>Bot: 处理查询
|
||||
Bot-->>TC: 返回搜索结果
|
||||
TC-->>M: 解析响应
|
||||
M->>Cache: 存储结果
|
||||
M-->>C: 返回结果
|
||||
C-->>U: 展示结果
|
||||
else 达到限制
|
||||
RL->>RL: 等待令牌补充
|
||||
Note over RL: 等待 50-100ms
|
||||
RL-->>M: 授予令牌
|
||||
M->>TC: send_message("/search python")
|
||||
TC->>Bot: 发送消息
|
||||
Bot-->>TC: 返回结果
|
||||
TC-->>M: 解析响应
|
||||
M-->>C: 返回结果
|
||||
C-->>U: 展示结果
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 批量并发请求处理流程
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "并发请求"
|
||||
R1[请求 1<br/>搜索群组]
|
||||
R2[请求 2<br/>查询用户]
|
||||
R3[请求 3<br/>热门群组]
|
||||
R4[请求 N...]
|
||||
end
|
||||
|
||||
subgraph "请求队列"
|
||||
Q[FIFO Queue<br/>最大 1000]
|
||||
end
|
||||
|
||||
subgraph "速率限制器"
|
||||
RL[Token Bucket<br/>18 令牌/秒]
|
||||
T1[令牌 1]
|
||||
T2[令牌 2]
|
||||
T3[令牌 3]
|
||||
end
|
||||
|
||||
subgraph "账号池"
|
||||
A1[账号 1<br/>空闲]
|
||||
A2[账号 2<br/>使用中]
|
||||
A3[账号 3<br/>空闲]
|
||||
end
|
||||
|
||||
subgraph "负载均衡"
|
||||
LB{负载均衡器<br/>最少使用策略}
|
||||
end
|
||||
|
||||
R1 --> Q
|
||||
R2 --> Q
|
||||
R3 --> Q
|
||||
R4 --> Q
|
||||
|
||||
Q --> RL
|
||||
|
||||
RL --> T1
|
||||
RL --> T2
|
||||
RL --> T3
|
||||
|
||||
T1 --> LB
|
||||
T2 --> LB
|
||||
T3 --> LB
|
||||
|
||||
LB --> A1
|
||||
LB --> A2
|
||||
LB --> A3
|
||||
|
||||
A1 --> Bot1[@openaiw_bot]
|
||||
A2 --> Bot2[@openaiw_bot]
|
||||
A3 --> Bot3[@openaiw_bot]
|
||||
|
||||
style Q fill:#fff9c4
|
||||
style RL fill:#c8e6c9
|
||||
style LB fill:#e1f5ff
|
||||
style Bot1 fill:#f3e5f5
|
||||
style Bot2 fill:#f3e5f5
|
||||
style Bot3 fill:#f3e5f5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 多账号负载均衡策略
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 收到请求
|
||||
|
||||
收到请求 --> 检查账号池
|
||||
|
||||
检查账号池 --> 选择策略
|
||||
|
||||
选择策略 --> 轮询: Round Robin
|
||||
选择策略 --> 最少使用: Least Used
|
||||
选择策略 --> 加权: Weighted
|
||||
|
||||
轮询 --> 选择账号1
|
||||
最少使用 --> 检查使用率
|
||||
加权 --> 根据权重选择
|
||||
|
||||
检查使用率 --> 选择最空闲账号
|
||||
|
||||
选择账号1 --> 发送请求
|
||||
选择最空闲账号 --> 发送请求
|
||||
根据权重选择 --> 发送请求
|
||||
|
||||
发送请求 --> 检查结果
|
||||
|
||||
检查结果 --> 成功: 正常响应
|
||||
检查结果 --> FloodWait: Flood Wait 错误
|
||||
检查结果 --> 失败: 其他错误
|
||||
|
||||
成功 --> 更新统计
|
||||
FloodWait --> 标记账号: 等待中
|
||||
失败 --> 故障转移
|
||||
|
||||
故障转移 --> 选择下一个账号
|
||||
选择下一个账号 --> 发送请求
|
||||
|
||||
标记账号 --> 选择其他账号
|
||||
选择其他账号 --> 发送请求
|
||||
|
||||
更新统计 --> [*]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 限流与重试机制
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start[开始请求] --> CheckCache{检查缓存?}
|
||||
|
||||
CheckCache -->|命中| ReturnCache[返回缓存结果]
|
||||
CheckCache -->|未命中| GetToken[获取令牌]
|
||||
|
||||
GetToken --> HasToken{有令牌?}
|
||||
|
||||
HasToken -->|是| SelectAccount[选择账号]
|
||||
HasToken -->|否| WaitToken[等待令牌<br/>50ms]
|
||||
|
||||
WaitToken --> GetToken
|
||||
|
||||
SelectAccount --> SendRequest[发送请求]
|
||||
|
||||
SendRequest --> CheckResponse{检查响应}
|
||||
|
||||
CheckResponse -->|成功| ParseResponse[解析响应]
|
||||
CheckResponse -->|FloodWait| HandleFlood{重试次数<3?}
|
||||
CheckResponse -->|网络错误| HandleError{重试次数<3?}
|
||||
CheckResponse -->|超时| HandleTimeout[返回超时提示]
|
||||
|
||||
HandleFlood -->|是| WaitFlood[等待 Flood 时间]
|
||||
HandleFlood -->|否| ReturnError[返回错误]
|
||||
|
||||
HandleError -->|是| RetryRequest[重试请求]
|
||||
HandleError -->|否| ReturnError
|
||||
|
||||
WaitFlood --> RetryRequest
|
||||
RetryRequest --> SendRequest
|
||||
|
||||
ParseResponse --> CacheResult[缓存结果]
|
||||
CacheResult --> ReturnResult[返回结果]
|
||||
|
||||
ReturnCache --> End[结束]
|
||||
ReturnResult --> End
|
||||
ReturnError --> End
|
||||
HandleTimeout --> End
|
||||
|
||||
style Start fill:#e1f5ff
|
||||
style End fill:#c8e6c9
|
||||
style CheckCache fill:#fff9c4
|
||||
style CacheResult fill:#ffccbc
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 请求限制说明
|
||||
|
||||
### 单账号限制
|
||||
- **速率**: ~18-20 请求/秒
|
||||
- **队列**: 最多 100 个待处理请求
|
||||
- **超时**: 20 秒无响应则超时
|
||||
|
||||
### 多账号限制（3 个账号）
|
||||
- **总速率**: ~54-60 请求/秒
|
||||
- **队列**: 最多 500 个待处理请求
|
||||
- **故障转移**: 自动切换到其他账号
|
||||
|
||||
### 缓存机制
|
||||
- **热门查询**: 缓存 1 小时
|
||||
- **用户信息**: 缓存 24 小时
|
||||
- **命中率**: 预计 30-40%
|
||||
|
||||
---
|
||||
|
||||
## 7. 普通用户调用方式
|
||||
|
||||
### 方式 1: 通过 Claude Code (推荐)
|
||||
|
||||
```
|
||||
用户: 帮我搜索 "python" 相关的 Telegram 群组
|
||||
|
||||
Claude: [自动调用 openaiw_search_groups]
|
||||
查询中...
|
||||
|
||||
找到以下群组：
|
||||
1. Python 学习交流群
|
||||
2. Python 开发者社区
|
||||
...
|
||||
```
|
||||
|
||||
### 方式 2: 通过 API 调用
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/search \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"query": "python"}'
|
||||
```
|
||||
|
||||
### 方式 3: 通过 Web 界面
|
||||
|
||||
```
|
||||
访问: http://localhost:8080/web
|
||||
输入查询 → 点击搜索 → 查看结果
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 性能指标
|
||||
|
||||
| 配置 | 账号数 | 吞吐量 | 延迟 | 成本 |
|
||||
|-----|-------|--------|------|------|
|
||||
| 小规模 | 1 | 15-18 req/s | 1-2s | $5/月 |
|
||||
| 中等 | 3 | 45-54 req/s | 1-3s | $15/月 |
|
||||
| 大规模 | 10 | 150-180 req/s | 1-2s | $50/月 |
|
||||
|
||||
Reference in New Issue
Block a user