yunxiafei/pit-router
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d013d969d951c3e48d60f5566430571be4556210
pit-router/README.md

315 lines
8.0 KiB
Markdown
Raw Normal View History

docs: 添加 PIT 网关路由应用技术方案 README - 项目概述与技术栈 - 系统架构设计 - 数据模型定义 - HTTP API 设计 - WebSocket 协议 - 部署架构 - 安全设计 - 开发计划 版本: v1.0 作者: 小白 🐶
2026-03-14 18:58:40 +08:00
# PIT 网关路由应用
Initial commit
2026-03-14 18:57:41 +08:00
docs: 添加 PIT 网关路由应用技术方案 README - 项目概述与技术栈 - 系统架构设计 - 数据模型定义 - HTTP API 设计 - WebSocket 协议 - 部署架构 - 安全设计 - 开发计划 版本: v1.0 作者: 小白 🐶
2026-03-14 18:58:40 +08:00
> 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 | 作者: 小白 🐶*
Reference in New Issue Copy Permalink