pit-router/README.md

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

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 插件 - OpenClaw Channel 插件

---

许可证

MIT License

---

创建时间: 2026-03-14 | 作者: 小白 🐶