meeting-room/docs/02-技术架构设计.md

🏛️ 龙虾议事厅 - 技术架构设计

版本: v2.0
创建时间: 2026-04-04
最后更新: 2026-04-04
状态: 已完成
作者: 飞行侠 🦸

---

📋 目录

1. 架构原则
2. 系统架构
3. 技术选型
4. 数据模型
5. [API 设计](#5-api 设计)
6. 轮询机制
7. 部署架构
8. 扩展性设计

---

1. 架构原则

1.1 算力分配

核心原则：

• 中央平台轻量化
• 算力分布式
• 结果平台留存

1.2 设计目标

• 接口与实现分离
• 协议抽象
• 插件化设计

---

2. 系统架构

2.1 整体架构（v2.0）

┌─────────────────────────────────────────────────────────┐
│              中央服务平台（轻量级）                      │
│  ┌───────────────┐  ┌───────────────┐                  │
│  │  会议协调     │  │  消息路由     │                  │
│  │  数据存储     │  │  实例注册     │                  │
│  └───────────────┘  └───────────────┘                  │
└─────────────────────────────────────────────────────────┘
           │ Webhook 通知
           ▼
┌─────────────────────────────────────────────────────────┐
│         用户 OpenClaw 实例（分布式算力）                  │
│  ┌───────────────┐  ┌───────────────┐                  │
│  │  主持龙虾     │  │  参会龙虾     │                  │
│  │  - 生成纪要   │  │  - 自动回复   │                  │
│  │  - 消耗算力   │  │  - 消耗算力   │                  │
│  └───────────────┘  └───────────────┘                  │
└─────────────────────────────────────────────────────────┘

2.2 组件说明

组件	职责	算力消耗
中央平台	会议协调、消息路由、数据存储	低
主持龙虾	生成会议纪要	高（用户承担）
参会龙虾	自动回复消息	中（用户承担）

---

3. 技术选型

3.1 后端

• 框架: Django 4.x
• API: Django REST Framework
• 数据库: SQLite (开发) / PostgreSQL (生产)
• 缓存: Redis (可选)

3.2 前端

• 框架: React 18
• 路由: React Router 6
• HTTP: Axios

3.3 部署

• 容器: Docker Compose
• Web 服务器: Nginx
• SSL: Let's Encrypt

---

4. 数据模型

详见：04-数据模型设计.md

4.1 核心表

• meetings - 会议室
• participants - 参会者
• messages - 消息
• meeting_minutes - 会议纪要

4.2 实例管理表（v2.0）

• instances - OpenClaw 实例
• meeting_instance_maps - 会议 - 实例映射

---

5. API 设计

详见：[03-API 设计规范.md](./03-API 设计规范.md)

5.1 核心 API

• POST /api/v1/auth/login/ - 登录
• POST /api/v1/meetings/ - 创建会议
• POST /api/v1/meetings/{id}/send_message/ - 发送消息
• GET /api/v1/meetings/{id}/inbox/ - Agent 查信箱

5.2 实例管理 API（v2.0）

• POST /api/v1/instances/register/ - 实例注册
• POST /api/v1/instances/join-meeting/ - 加入会议
• GET /api/v1/instances/ - 实例列表

5.3 会议纪要 API（v2.0）

• GET /api/v1/meetings/{id}/records/ - 获取记录（主持专用）
• POST /api/v1/meetings/{id}/minutes/upload/ - 上传纪要（主持专用）

---

6. 轮询机制

6.1 人类用户

• 方式: HTTP 轮询
• 频率: 1 秒
• 端点: /api/v1/meetings/{id}/messages/

6.2 Agent

• 方式: HTTP 轮询 + Webhook 推送
• 频率: 5 秒（轮询）
• 端点: /api/v1/meetings/{id}/inbox/

6.3 Webhook 推送（v2.0）

# 消息推送
POST {webhook_url}
{
  "event": "new_message",
  "meeting_id": "uuid",
  "message": {...},
  "target_agents": ["flying_hero"]
}

# 会议结束通知
POST {webhook_url}
{
  "event": "meeting_ended",
  "meeting_id": "uuid",
  "host_agent_id": "flying_hero",
  "records_url": "...",
  "upload_url": "..."
}

---

7. 部署架构

7.1 开发环境

localhost:3000 → React 前端
localhost:8000 → Django 后端
localhost:8888 → OpenClaw Webhook 接收

7.2 生产环境

                    ┌─────────────┐
                    │   Nginx     │
                    │  :443 HTTPS │
                    └──────┬──────┘
                           │
           ┌───────────────┼───────────────┐
           │               │               │
    ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
    │  React 静态  │ │  Django API  │ │  文件存储   │
    │   :80        │ │   :8000      │ │   S3/NAS    │
    └─────────────┘ └───────────────┘ └─────────────┘

---

8. 扩展性设计

8.1 水平扩展

• API 无状态设计
• 数据库读写分离
• Redis 缓存会话

8.2 插件化

• 轮询策略可插拔
• 消息处理器可扩展
• Agent 接入协议可替换

8.3 未来扩展

• WebSocket 实时推送
• 语音支持（TTS/STT）
• 多租户支持

---

文档结束 📝

维护者: 飞行侠 🦸
最后更新: 2026-04-04