yunxiafei
d013d969d9
- 项目概述与技术栈
- 系统架构设计
- 数据模型定义
- HTTP API 设计
- WebSocket 协议
- 部署架构
- 安全设计
- 开发计划
版本: v1.0
作者: 小白 🐶
315 lines
8.0 KiB
Markdown
315 lines
8.0 KiB
Markdown
# PIT 网关路由应用
|
||
|
||
> Personal Intelligent Team Router Service
|
||
|
||
## 项目概述
|
||
|
||
PIT（Personal Intelligent Team）网关路由应用是 PIT 系统的核心组件，负责连接用户交互层和 Agent 层，实现消息路由、会话管理、Agent 调度等功能。
|
||
|
||
### 核心目标
|
||
|
||
- 提供统一的 WebSocket 接入点
|
||
- 实现多 Agent 智能路由
|
||
- 管理会话生命周期
|
||
- 支持 Agent 负载均衡
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 | 版本 | 说明 |
|
||
|------|------|------|------|
|
||
| 语言 | Python | 3.12 | 高性能异步支持 |
|
||
| Web框架 | Flask | 3.0+ | 轻量级、灵活 |
|
||
| WebSocket | Flask-SocketIO | 5.3+ | 实时双向通信 |
|
||
| ORM | SQLAlchemy | 3.1+ | 数据库抽象层 |
|
||
| 认证 | Flask-Login + JWT | - | 用户身份验证 |
|
||
| 缓存 | Redis | 7+ | 会话缓存、消息队列 |
|
||
| 部署 | Gunicorn + Nginx | - | 生产环境部署 |
|
||
|
||
---
|
||
|
||
## 系统架构
|
||
|
||
```
|
||
用户交互层 (Clients)
|
||
↓ WebSocket / HTTP
|
||
PIT 网关路由应用 (Gateway Router)
|
||
├── 接入层 (Access Layer)
|
||
│ ├── HTTP Server (Flask)
|
||
│ ├── WebSocket (SocketIO)
|
||
│ └── Auth Middleware
|
||
├── 业务层 (Business Layer)
|
||
│ ├── Session Manager
|
||
│ ├── Message Router
|
||
│ └── Agent Scheduler
|
||
└── 数据层 (Data Layer)
|
||
├── SQLite (持久化)
|
||
├── Redis (缓存)
|
||
└── Config Store
|
||
↓ PIT Channel 插件
|
||
Agent 层 (OpenClaw Gateways)
|
||
```
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
pit-router/
|
||
├── app/
|
||
│ ├── __init__.py # Flask 应用工厂
|
||
│ ├── config.py # 配置管理
|
||
│ ├── models/ # 数据模型层
|
||
│ │ ├── user.py # 用户模型
|
||
│ │ ├── session.py # 会话模型
|
||
│ │ ├── agent.py # Agent 模型
|
||
│ │ ├── gateway.py # Gateway 模型
|
||
│ │ └── message.py # 消息模型
|
||
│ ├── routes/ # HTTP 路由层
|
||
│ │ ├── auth.py # 认证路由
|
||
│ │ ├── sessions.py # 会话路由
|
||
│ │ ├── agents.py # Agent 路由
|
||
│ │ └── gateways.py # Gateway 路由
|
||
│ ├── socketio/ # WebSocket 处理层
|
||
│ │ ├── handlers.py # Socket.IO 事件处理
|
||
│ │ └── events.py # 事件定义
|
||
│ ├── services/ # 业务逻辑层
|
||
│ │ ├── session_service.py # 会话服务
|
||
│ │ ├── agent_service.py # Agent 服务
|
||
│ │ ├── message_service.py # 消息服务
|
||
│ │ └── scheduler.py # Agent 调度器
|
||
│ └── utils/ # 工具函数
|
||
├── migrations/ # 数据库迁移
|
||
├── tests/ # 测试
|
||
├── requirements.txt # Python 依赖
|
||
├── config.yaml # 配置文件
|
||
├── docker-compose.yaml # Docker 编排
|
||
└── run.py # 启动入口
|
||
```
|
||
|
||
---
|
||
|
||
## 数据模型
|
||
|
||
### 用户模型 (User)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | String(36) | 主键 UUID |
|
||
| username | String(80) | 用户名，唯一索引 |
|
||
| password_hash | String(256) | 密码哈希 |
|
||
| email | String(120) | 邮箱，唯一 |
|
||
| nickname | String(80) | 昵称 |
|
||
| role | String(20) | 角色：admin/user |
|
||
| status | String(20) | 状态：active/disabled |
|
||
| created_at | DateTime | 创建时间 |
|
||
| last_login_at | DateTime | 最后登录时间 |
|
||
|
||
### 会话模型 (Session)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | String(36) | 主键 UUID |
|
||
| user_id | String(36) | 用户 ID，外键 |
|
||
| agent_id | String(36) | Agent ID，外键 |
|
||
| gateway_id | String(36) | Gateway ID，外键 |
|
||
| title | String(200) | 会话标题 |
|
||
| channel_type | String(20) | 渠道类型：web/desktop/mobile |
|
||
| status | String(20) | 状态：active/paused/closed |
|
||
| message_count | Integer | 消息计数 |
|
||
| created_at | DateTime | 创建时间 |
|
||
| last_active_at | DateTime | 最后活跃时间 |
|
||
|
||
### Agent 模型
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | String(36) | 主键 UUID |
|
||
| name | String(80) | Agent 名称 |
|
||
| display_name | String(80) | 显示名称 |
|
||
| gateway_id | String(36) | Gateway ID，外键 |
|
||
| model | String(80) | 使用的模型 |
|
||
| capabilities | JSON | 能力列表 |
|
||
| status | String(20) | 状态：online/offline/busy |
|
||
| priority | Integer | 优先级 |
|
||
| weight | Integer | 权重（用于调度） |
|
||
| last_heartbeat | DateTime | 最后心跳时间 |
|
||
|
||
### Gateway 模型
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | String(36) | 主键 UUID |
|
||
| name | String(80) | Gateway 名称，唯一 |
|
||
| url | String(256) | Gateway 地址 |
|
||
| token | String(256) | 认证 Token（加密存储） |
|
||
| status | String(20) | 状态：online/offline |
|
||
| agent_count | Integer | Agent 数量 |
|
||
| last_heartbeat | DateTime | 最后心跳时间 |
|
||
|
||
---
|
||
|
||
## HTTP API 设计
|
||
|
||
### 认证 API
|
||
|
||
```
|
||
POST /api/auth/register - 注册新用户
|
||
POST /api/auth/login - 用户登录，返回 JWT Token
|
||
POST /api/auth/logout - 用户登出
|
||
POST /api/auth/refresh - 刷新 Token
|
||
GET /api/auth/me - 获取当前用户信息
|
||
```
|
||
|
||
### 会话 API
|
||
|
||
```
|
||
GET /api/sessions - 获取会话列表
|
||
POST /api/sessions - 创建会话
|
||
GET /api/sessions/:id - 获取会话详情
|
||
DELETE /api/sessions/:id - 关闭会话
|
||
GET /api/sessions/:id/messages - 获取会话消息
|
||
```
|
||
|
||
### Agent API
|
||
|
||
```
|
||
GET /api/agents - 获取 Agent 列表
|
||
GET /api/agents/:id - 获取 Agent 详情
|
||
GET /api/agents/:id/status - 获取 Agent 实时状态
|
||
PUT /api/agents/:id/config - 更新 Agent 配置
|
||
```
|
||
|
||
### Gateway API
|
||
|
||
```
|
||
GET /api/gateways - 获取 Gateway 列表
|
||
POST /api/gateways - 注册 Gateway
|
||
DELETE /api/gateways/:id - 注销 Gateway
|
||
GET /api/gateways/:id/status - 获取 Gateway 状态
|
||
```
|
||
|
||
---
|
||
|
||
## WebSocket 协议
|
||
|
||
### 事件定义
|
||
|
||
| 事件 | 方向 | 说明 |
|
||
|------|------|------|
|
||
| connect | C→S | 连接请求 |
|
||
| connected | S→C | 连接成功 |
|
||
| session.create | C→S | 创建会话 |
|
||
| session.created | S→C | 会话已创建 |
|
||
| session.join | C→S | 加入会话 |
|
||
| session.joined | S→C | 已加入会话 |
|
||
| message.send | C→S | 发送消息 |
|
||
| message | S→C | 收到消息 |
|
||
| message.stream | S→C | 流式消息 |
|
||
| error | S→C | 错误通知 |
|
||
|
||
---
|
||
|
||
## 部署架构
|
||
|
||
### Docker Compose
|
||
|
||
```yaml
|
||
version: '3.8'
|
||
|
||
services:
|
||
pit-router:
|
||
build: .
|
||
ports:
|
||
- "9000:9000"
|
||
environment:
|
||
- FLASK_ENV=production
|
||
- SECRET_KEY=${SECRET_KEY}
|
||
- JWT_SECRET=${JWT_SECRET}
|
||
- DATABASE_URL=sqlite:///data/pit.db
|
||
- REDIS_URL=redis://redis:6379
|
||
volumes:
|
||
- pit-data:/app/data
|
||
- pit-logs:/app/logs
|
||
depends_on:
|
||
- redis
|
||
restart: unless-stopped
|
||
|
||
redis:
|
||
image: redis:7-alpine
|
||
volumes:
|
||
- redis-data:/data
|
||
restart: unless-stopped
|
||
|
||
volumes:
|
||
pit-data:
|
||
pit-logs:
|
||
redis-data:
|
||
```
|
||
|
||
---
|
||
|
||
## 安全设计
|
||
|
||
### 认证机制
|
||
|
||
| 机制 | 说明 |
|
||
|------|------|
|
||
| JWT Token | 无状态认证 |
|
||
| Token 过期 | 24 小时 |
|
||
| Refresh Token | 7 天 |
|
||
|
||
### 安全措施
|
||
|
||
| 措施 | 说明 |
|
||
|------|------|
|
||
| HTTPS | 强制 HTTPS |
|
||
| CORS | 配置允许的源 |
|
||
| Rate Limit | 请求频率限制 |
|
||
| Input Validation | 输入验证 |
|
||
| SQL Injection | SQLAlchemy ORM 防护 |
|
||
| XSS | 内容转义 |
|
||
|
||
---
|
||
|
||
## 开发计划
|
||
|
||
### Phase 1: 核心功能 (2-3 天)
|
||
|
||
- [ ] 数据模型实现
|
||
- [ ] 认证 API
|
||
- [ ] 会话 API
|
||
- [ ] WebSocket 处理
|
||
- [ ] Agent 调度
|
||
|
||
### Phase 2: 扩展功能 (1-2 天)
|
||
|
||
- [ ] Gateway 管理
|
||
- [ ] 配置管理
|
||
- [ ] 日志系统
|
||
- [ ] 监控接口
|
||
|
||
### Phase 3: 测试部署 (1-2 天)
|
||
|
||
- [ ] 单元测试
|
||
- [ ] 集成测试
|
||
- [ ] Docker 部署
|
||
- [ ] Nginx 配置
|
||
|
||
---
|
||
|
||
## 相关项目
|
||
|
||
- [PIT Channel 插件](http://localhost:3000/yunxiafei/pit-channel) - OpenClaw Channel 插件
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
---
|
||
|
||
*创建时间: 2026-03-14 | 作者: 小白 🐶*
|