docs: 重构文档结构，规范编号并整合冗余内容
## 主要变更 ### 文档重构（减少 1199 行，-23%） - 01-架构设计.md: 503→369 行 (-27%)，删除 DDL/配置示例，精简鉴权/存储描述 - 02-接口文档.md: 1313→570 行 (-57%)，删除 Go 接口/Orchestrator 实现/配置管理 - 07-成本控制.md: 65→59 行 (-9%)，代码块替换为文件引用 ### 文档编号规范化 - 08-功能创意.md → 删除（内容整合到 README.md "功能扩展方向"） - 10-Eino框架与编排设计.md → 08-Eino框架与编排设计.md - 情景切换.md → 09-情景切换.md - 12-鉴权体系.md → 10-鉴权体系.md - 13-令牌桶限流.md → 11-令牌桶限流.md ### 交叉引用更新 - 01-架构设计.md: 更新对鉴权体系/令牌桶限流的引用为新编号 - README.md: 更新文档索引表、推荐阅读顺序、新增功能扩展方向 ### 删除过时文档 - 09-技术名词解释.md（内容已整合到 03-技术选型.md） - 10-Eino重构方案.md（历史记录，已完成） - 11-Eino框架技术文档.md（已合并到 08） - 情景切换功能完整文档.md（已规范化为 09） ## 重构原则 - 架构文档聚焦系统结构，移除实现细节 - 接口文档保留纯契约，删除内部实现 - 编号连续（01-11），语义清晰 - 通过交叉引用连接相关文档，避免重复
This commit is contained in:
193
docs/01-架构设计.md
193
docs/01-架构设计.md
@@ -199,36 +199,35 @@ graph LR
|
||||
| 模块 | 职责 |
|
||||
|------|------|
|
||||
| WebSocket Handler | 管理客户端连接生命周期，JWT 认证，conversation_id 恢复，单播消息推送 |
|
||||
| Session Manager | 维护用户会话状态、对话历史。三级存储（Memory → Redis → PostgreSQL），30 分钟 TTL，Write-Through 到 PG |
|
||||
| Eino 编排层 | 基于 CloudWeGo Eino Graph 的声明式 AI 编排。7 节点 DAG（STT→History→ChatModel→Msg2Str→Splitter→TTS→Done），Stream 模式调用，Callback 实现 LLM token 实时推送 |
|
||||
| AI Orchestrator | `EinoOrchestrator` 适配器，包装 Eino Graph 实现 `Orchestrator` 接口。context 取消 + 超时控制 |
|
||||
| Session Manager | 维护用户会话状态、对话历史，三级存储架构，30 分钟 TTL |
|
||||
| Eino 编排层 | 基于 CloudWeGo Eino Graph 的声明式 AI 编排，7 节点 DAG 流水线，Stream 模式调用 |
|
||||
| AI Orchestrator | EinoOrchestrator 适配器，包装 Eino Graph 实现 Orchestrator 接口 |
|
||||
| AI Service Layer | AI 服务抽象层，多 provider 支持（Deepgram/MiMo/OpenAI 等） |
|
||||
| Auth | 用户认证与授权。JWT (HS256) 双 token 轮转，bcrypt 密码哈希，Gin 中间件 |
|
||||
| Store | 持久化存储层。UserRepository / MessageRepository / SessionRepository，内存 + PostgreSQL 双实现 |
|
||||
| Auth | 用户认证与授权，JWT 双 token 轮转，bcrypt 密码哈希 |
|
||||
| Store | 持久化存储层，Repository 接口与实现（内存 + PostgreSQL） |
|
||||
| REST API | 健康检查、认证、对话管理端点 |
|
||||
| Logger | Zap 结构化日志 |
|
||||
| Models | 数据模型定义 |
|
||||
| Migrations | 数据库版本化迁移，嵌入式 SQL 文件自动执行 |
|
||||
| Migrations | 数据库版本化迁移 |
|
||||
| Model Router | 根据请求类型选择 AI 模型（待实现） |
|
||||
| Rate Limiter | 令牌桶限流。详细设计见 [令牌桶限流设计](./13-令牌桶限流设计.md) |
|
||||
| Rate Limiter | 令牌桶限流，详见 [11-令牌桶限流.md](./11-令牌桶限流.md) |
|
||||
|
||||
## 前端组件
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| LandingPage | 未登录时的着陆页（营销展示），内嵌 LoginModal 登录/注册弹窗 |
|
||||
| AuthPage | 登录/注册表单（备用，已被 LandingPage + LoginModal 替代） |
|
||||
| LandingPage | 未登录时的着陆页，内嵌 LoginModal 登录/注册弹窗 |
|
||||
| CameraManager | 摄像头流采集 |
|
||||
| MicManager | 麦克风音频采集 |
|
||||
| EdgeProcessor | VAD + 关键帧检测（Canvas 像素比较） |
|
||||
| WebSocketManager | WS 连接生命周期管理 |
|
||||
| EdgeProcessor | VAD + 关键帧检测 |
|
||||
| WebSocketManager | WebSocket 连接生命周期管理 |
|
||||
| ChatPanel | 消息展示、流式回复、文本输入、场景选择 |
|
||||
| VideoPreview | 摄像头画面预览 |
|
||||
| SessionSidebar | 左侧抽屉式对话列表（搜索、重命名、删除、时间分组） |
|
||||
| ConfigPanel | 右侧抽屉式配置面板（主题、TTS 开关、detail level、语言、场景、登出） |
|
||||
| Toast | 轻量通知提示（3 秒自动消失） |
|
||||
| SessionSidebar | 左侧对话列表（搜索、重命名、删除、时间分组） |
|
||||
| ConfigPanel | 右侧配置面板（主题、TTS 开关、detail level、语言、场景、登出） |
|
||||
| Toast | 轻量通知提示 |
|
||||
|
||||
核心 Hook：`useVisionSession()` 封装一次完整的视觉对话会话（摄像头、VAD、WebSocket、消息状态、认证、场景模式）。`useSessionList()` 通过 REST API 管理对话列表 CRUD（列表、创建、删除、重命名、加载消息）。
|
||||
核心 Hook：`useVisionSession()` 封装完整的视觉对话会话（摄像头、VAD、WebSocket、消息状态、认证、场景模式）。`useSessionList()` 通过 REST API 管理对话列表 CRUD。
|
||||
|
||||
### 前端会话状态模型（三态）
|
||||
|
||||
@@ -310,188 +309,56 @@ erDiagram
|
||||
}
|
||||
```
|
||||
|
||||
### 表结构
|
||||
|
||||
```sql
|
||||
-- 用户表
|
||||
CREATE TABLE users (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
username VARCHAR(64) NOT NULL UNIQUE,
|
||||
password_hash VARCHAR(256) NOT NULL,
|
||||
created_at TIMESTAMPTZ DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ DEFAULT now()
|
||||
);
|
||||
|
||||
-- 会话表
|
||||
CREATE TABLE sessions (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
title VARCHAR(128) DEFAULT '新对话',
|
||||
config JSONB DEFAULT '{}',
|
||||
created_at TIMESTAMPTZ DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ DEFAULT now()
|
||||
);
|
||||
|
||||
-- 消息表
|
||||
CREATE TABLE messages (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
session_id UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
|
||||
role VARCHAR(16) NOT NULL,
|
||||
content TEXT NOT NULL,
|
||||
tokens_used INTEGER DEFAULT 0,
|
||||
created_at TIMESTAMPTZ DEFAULT now()
|
||||
);
|
||||
|
||||
-- 刷新令牌表
|
||||
CREATE TABLE refresh_tokens (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
token_hash VARCHAR(256) NOT NULL UNIQUE,
|
||||
expires_at TIMESTAMPTZ NOT NULL,
|
||||
created_at TIMESTAMPTZ DEFAULT now()
|
||||
);
|
||||
```
|
||||
系统采用关系型数据库存储持久化数据，包括用户账户、对话会话、消息记录和刷新令牌。数据库表定义详见 `backend/migrations/` 目录下的 SQL 迁移文件。
|
||||
|
||||
### 存储策略
|
||||
|
||||
| 场景 | 存储方案 | 说明 |
|
||||
|------|---------|------|
|
||||
| 默认 | Memory（进程内） | 零依赖，快速启动。MemoryManager 支持 Write-Through 到 PG |
|
||||
| 持久化 | Memory + PostgreSQL | 通过 `storage.persistence.enabled: true` 启用，MemoryManager 注入 PG Repository |
|
||||
| 多实例 | Redis（独立） | 通过配置切换到 RedisManager，适合多实例部署 |
|
||||
| 三级存储 | TieredManager | L1 Memory → L2 Redis → L3 PostgreSQL，自动降级 |
|
||||
系统采用**三级存储架构**（TieredManager）实现会话状态管理，平衡性能与可靠性：
|
||||
|
||||
**三级存储架构**（`TieredManager`）：
|
||||
- **L1 Memory**：进程内缓存，提供微秒级读写性能
|
||||
- **L2 Redis**：分布式缓存层，支持多实例部署，提供毫秒级访问
|
||||
- **L3 PostgreSQL**：持久化存储层，确保数据可靠性
|
||||
|
||||
```
|
||||
TieredManager
|
||||
├── L1: Memory（进程内缓存，微秒级读写）
|
||||
├── L2: Redis（分布式缓存，毫秒级读写）
|
||||
└── L3: PostgreSQL（持久化存储，冷数据）
|
||||
```
|
||||
|
||||
- **读取路径**：L1 → L2 → L3，逐级回源，命中后向上回填
|
||||
- **写入路径**：L1 → L2（同步） → L3（异步）
|
||||
- **健康检查**：后台 goroutine 每 30 秒 ping Redis，故障时自动降级为 L1+L3 模式
|
||||
- **冷热分离**：L1/L2 存"热数据"（当前对话上下文），L3 存"冷数据"（历史记录）
|
||||
会话数据按 TTL（默认 30 分钟）在三级存储间流转，支持 Redis 故障时自动降级到 Memory + PostgreSQL 模式。配置灵活，可根据部署规模选择单级（Memory）、双级（Memory + PostgreSQL）或完整三级存储方案。
|
||||
|
||||
## 认证设计
|
||||
|
||||
采用 **JWT 双 token 轮转认证机制**，结合 bcrypt 密码哈希和 Refresh Token Rotation 安全策略。详细设计见 [鉴权体系设计](./12-鉴权体系设计.md)。
|
||||
系统采用 **JWT 双 token 轮转认证机制**，结合 bcrypt 密码哈希和 Refresh Token Rotation 安全策略。
|
||||
|
||||
### 核心组件
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| TokenManager | JWT 生成与验证（HS256 算法） |
|
||||
| AuthService | 认证业务逻辑（注册/登录/刷新/登出） |
|
||||
| AuthMiddleware | Gin 中间件，校验 access_token 并注入用户信息 |
|
||||
| PasswordUtil | bcrypt 密码哈希（cost=10） |
|
||||
|
||||
### 认证流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as 客户端
|
||||
participant G as Go 网关
|
||||
participant DB as PostgreSQL
|
||||
|
||||
Note over C,DB: 注册流程
|
||||
C->>G: POST /api/auth/register {username, password}
|
||||
G->>G: bcrypt hash 密码
|
||||
G->>DB: INSERT users
|
||||
G->>G: 生成 access_token + refresh_token
|
||||
G->>DB: 存 SHA256(refresh_token)
|
||||
G-->>C: {user, access_token, refresh_token}
|
||||
|
||||
Note over C,DB: 登录流程
|
||||
C->>G: POST /api/auth/login {username, password}
|
||||
G->>DB: 查 users by username
|
||||
G->>G: bcrypt.CompareHashAndPassword
|
||||
G->>G: 生成 token pair
|
||||
G->>DB: 存 SHA256(refresh_token)
|
||||
G-->>C: {user, access_token, refresh_token}
|
||||
|
||||
Note over C,DB: Token 刷新（轮转）
|
||||
C->>G: POST /api/auth/refresh {refresh_token}
|
||||
G->>G: 校验签名和过期
|
||||
G->>DB: 验证 hash 存在
|
||||
G->>DB: 撤销旧 refresh_token
|
||||
G->>G: 生成新 token pair
|
||||
G->>DB: 存新 refresh_token hash
|
||||
G-->>C: {access_token, refresh_token}
|
||||
```
|
||||
|
||||
### Token 策略
|
||||
|
||||
- **access_token**：15 分钟有效，用于 API 认证和 WebSocket 连接
|
||||
- **refresh_token**：7 天有效，用于刷新 access_token
|
||||
- **Refresh Token Rotation**：每次 refresh 都生成新的 token pair，旧 refresh_token 立即失效
|
||||
- **复用检测**：检测到已删除的 refresh_token 被复用时，吊销该用户的所有 refresh_token
|
||||
|
||||
### 安全机制
|
||||
|
||||
1. **密码安全**：bcrypt 算法（cost=10），自动生成盐值，防彩虹表攻击
|
||||
2. **Token 安全**：
|
||||
- access_token 短有效期（15 分钟），降低泄露风险
|
||||
- refresh_token 使用 SHA256 哈希存储，不存储原始 token
|
||||
- Refresh Token Rotation 防重放攻击
|
||||
- 复用检测 + 自动吊销机制
|
||||
3. **传输安全**：HTTPS 强制，CORS 限制，HttpOnly Cookie 存储 refresh_token
|
||||
4. **防攻击策略**：
|
||||
- 防暴力破解：可选速率限制
|
||||
- 防枚举攻击：统一错误信息
|
||||
- 防 Token 泄露：复用检测 + 自动吊销
|
||||
|
||||
### WebSocket 认证
|
||||
|
||||
连接地址：`ws://host/ws?token=<access_token>&conversation_id=<uuid>`
|
||||
|
||||
- HTTP Upgrade 前校验 token
|
||||
- 校验失败返回 401 Unauthorized
|
||||
- 校验成功后，user_id 和 username 注入到连接上下文
|
||||
|
||||
### 配置
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
jwt_secret: "" # JWT 签名密钥（必须通过 CAMTALK_AUTH_JWT_SECRET 环境变量设置）
|
||||
access_ttl: 15 # access_token 有效期（分钟）
|
||||
refresh_ttl: 10080 # refresh_token 有效期（分钟，7天）
|
||||
```
|
||||
|
||||
> **安全要求**：`JWT_SECRET` **必须**通过环境变量设置，不能写入配置文件。生产环境使用 `openssl rand -hex 32` 生成随机密钥。
|
||||
核心机制包括：双 token 轮转（access_token 15 分钟 + refresh_token 7 天）、密码安全（bcrypt cost=10）、token 安全（SHA256 哈希存储、复用检测）、WebSocket 连接认证（基于 access_token 的 HTTP Upgrade 校验）等。认证流程、安全机制、配置要求等详细设计见 [10-鉴权体系.md](./10-鉴权体系.md)。
|
||||
|
||||
## 部署架构
|
||||
|
||||
系统采用分层部署架构，支持单实例和多实例水平扩展：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
User["用户浏览器"] --> Nginx
|
||||
|
||||
|
||||
subgraph Nginx["Nginx 反向代理"]
|
||||
Static["/ → 前端静态资源"]
|
||||
API["/api/* → Go Gateway"]
|
||||
WS_Proxy["/ws → Go Gateway"]
|
||||
end
|
||||
|
||||
|
||||
subgraph Gateway_Pool["Go Gateway 实例"]
|
||||
G1["Gateway-1"]
|
||||
G2["Gateway-2"]
|
||||
GN["Gateway-N"]
|
||||
end
|
||||
|
||||
|
||||
Nginx --> G1
|
||||
Nginx --> G2
|
||||
Nginx --> GN
|
||||
|
||||
|
||||
G1 --> Redis
|
||||
G2 --> Redis
|
||||
GN --> Redis
|
||||
|
||||
|
||||
G1 --> PG_DB["PostgreSQL"]
|
||||
G2 --> PG_DB
|
||||
GN --> PG_DB
|
||||
|
||||
|
||||
G1 --> AI_Services["AI Services（外部 API）"]
|
||||
G2 --> AI_Services
|
||||
GN --> AI_Services
|
||||
|
||||
Reference in New Issue
Block a user