CamTalk/docs/02-系统架构.md

系统架构

概述

三层架构：前端做轻量预处理，后端做智能编排，云端 AI 服务按需调用。在保证交互体验的同时控制成本。

三层架构

层级	职责	关键约束
客户端（浏览器）	媒体采集、边缘预处理、UI 渲染	浏览器资源有限，模型需轻量
Go 网关	会话管理、AI 服务编排、流式管道	高并发、低延迟、状态管理
AI 服务	LLM 推理、语音识别、语音合成	按量计费，需控制调用频率

为什么要单独加一层 Go 网关，而不是让前端直连 AI API？1）API Key 安全性；2）统一的速率限制和成本管控；3）多模型路由逻辑集中在一处便于维护。

技术栈

前端

技术	选型	选择理由
框架	React 18 + TypeScript	组件化开发，类型安全，生态成熟
构建	Vite	开发热更新快，构建产物小
实时通信	WebSocket（原生 API） + 自封装连接管理	浏览器原生支持，封装心跳/重连/消息分发
边缘推理	ONNX Runtime Web	浏览器端跑轻量模型（VAD、关键帧检测）
语音检测	@ricky0123/vad-web	基于 WebRTC VAD，纯前端零延迟
媒体采集	MediaDevices API	浏览器原生摄像头/麦克风访问

后端

技术	选型	选择理由
语言	Go	高并发 goroutine 模型，适合长连接管理
HTTP 框架	Gin	高性能 HTTP 路由，中间件生态成熟
WebSocket	gorilla/websocket	Go 生态最成熟的 WebSocket 库
会话存储	Redis（已实现） / Memory（默认）	高速 KV 存储，Memory 为默认实现，Redis 已实现可通过配置切换
持久化存储	PostgreSQL（已实现）	对话历史、用户数据、会话持久化。MemoryManager 支持 Write-Through 到 PG
配置管理	Viper + godotenv	支持 YAML + .env + 环境变量覆盖，详见 03-接口文档.md 第六章
日志	Zap	高性能结构化日志

AI 服务

能力	主选方案	备选方案	选型考量
多模态 LLM	GPT-4o（默认）	通义千问等 OpenAI 兼容模型	通过 OpenAI 兼容接口，可灵活切换
语音识别 STT	Deepgram（默认）	MiMo ASR（小米）	支持多 provider 切换
语音合成 TTS	OpenAI TTS（默认）	MiMo TTS（小米）	支持多 provider 切换

不必绑定单一厂商。Go 网关的 AI 服务层统一封装不同服务商的调用接口，通过配置切换 provider。

核心交互流程

一次完整的"用户提问 → AI 回答"流程：

Browser                Go Gateway          STT         LLM         TTS
  |                       |                  |           |           |
  |-- VAD 检测到语音结束 --->|                  |           |           |
  |                       |                  |           |           |
  |-- [音频+图像] -------->|                  |           |           |
  |                       |--- 音频流 ------->|           |           |
  |                       |<-- 流式文本 ------|           |           |
  |                       |                  |           |           |
  |                       |--- [图像+文本+上下文] -------->|           |
  |                       |<-- 流式回答文本 --------------|           |
  |<-- 推送回答文本 --------|                  |           |           |
  |                       |--- 回答文本 ---------------------------->|
  |                       |<-- 流式音频 --------------------------------|
  |<-- 推送音频流 ----------|                  |           |           |
  |                       |                  |           |           |
  |-> 播放音频 + 渲染文字   |                  |           |           |

关键优化：LLM 文本流和 TTS 音频流是并行推送的——客户端先展示文字，同时开始播放语音，用户感知延迟大幅降低。

后端模块

模块	职责	关键实现	状态
WebSocket Handler	管理客户端连接生命周期，单播消息推送	goroutine per connection，JWT 认证，conversation_id 恢复	✅ 已完成
Session Manager	维护用户会话状态、对话历史	Memory（默认）/ Redis（可切换），30 分钟 TTL，Write-Through 到 PG（详见 03-接口文档.md 第五章）	✅ 已完成
AI Orchestrator	编排 STT→LLM→TTS 流式并行管道	context 取消 + 超时控制 + 句子切分	✅ 已完成
AI Service Layer	AI 服务抽象层（STT/LLM/TTS）	多 provider 支持（Deepgram/MiMo/OpenAI 等）	✅ 已完成
Auth	用户认证与授权	JWT (HS256) 双 token 轮转，bcrypt 密码哈希，Gin 中间件	✅ 已完成
Store	持久化存储层	UserRepository / MessageRepository / SessionRepository，内存 + PostgreSQL 双实现	✅ 已完成
REST API	健康检查、认证、对话管理端点	Gin 路由，输入校验，权限校验	✅ 已完成
Error Handler	统一错误码定义与发送	错误码枚举	✅ 已完成
Logger	日志初始化封装	Zap 结构化日志	✅ 已完成
Models	数据模型定义	WebSocket 消息、会话、配置、用户等	✅ 已完成
Migrations	数据库版本化迁移	嵌入式 SQL 文件，自动执行，版本跟踪	✅ 已完成
Model Router	根据请求类型选择 AI 模型	规则引擎 + 成本阈值	📋 规划中
Rate Limiter	防止单用户过度消耗 API 额度	令牌桶算法	📋 规划中

AI Orchestrator 核心接口（internal/orchestrator/orchestrator.go）：

// Orchestrator AI 编排器接口。
type Orchestrator interface {
    ProcessQuery(ctx context.Context, sessionID string, req models.WsQuery,
        history []models.Message, sender Sender) error
}

Pipeline 实现（internal/orchestrator/pipeline.go）流程：

1. Base64 解码音频/图片
2. 调用 stt.Recognize() → 发送 stt_result
3. 调用 llm.ChatStream() 获取流式输出，goroutine 消费 token → 发送 llm_chunk + 句子切分
4. 另一 goroutine 从句子 channel 读取 → 调用 tts.SynthesizeStream() → 发送 tts_audio
5. 流结束 → 发送 llm_done
6. TTS 失败静默跳过，STT/LLM 失败发送对应 error 消息

关键优化：LLM 文本流和 TTS 音频流并行推送——客户端先逐 token 展示文字，同时 TTS 逐句子合成并推送音频，用户感知延迟大幅降低。详细的 AI 服务层接口和编排策略见 03-接口文档.md 第三、四章。

前端组件

组件	职责
AuthPage	登录/注册表单，前端校验，Tab 切换
CameraManager	摄像头流采集
MicManager	麦克风音频采集
EdgeProcessor	VAD + 关键帧检测（Canvas 像素比较）
WebSocketManager	WS 连接生命周期管理
ChatPanel	消息展示、流式回复、文本输入、场景选择
VideoPreview	摄像头画面预览
SessionSidebar	左侧抽屉式对话列表（搜索、重命名、删除）
ConfigPanel	右侧抽屉式配置面板（主题、TTS 开关、detail level、语言、场景、账户）
Toast	轻量通知提示（3 秒自动消失）

核心 Hook：useVisionSession() 封装一次完整的视觉对话会话（摄像头、VAD、WebSocket、消息状态、认证、场景模式）。

// useVisionSession 核心职责（简化示意）
function useVisionSession() {
  // 组合：useCamera + useMicrophone + useVAD + useWebSocketManager + useObservationMode
  // 管理：消息状态、流式回复、处理标志、配置、统计、模式

  // VAD onSpeechEnd: 捕获帧 + 音频 → 发送 query 消息
  // 服务端消息处理：stt_result / llm_chunk / llm_done / tts_audio / error
  // 文本输入：sendTextMessage() 支持手动输入文字（跳过 STT）
  // 场景模式：config 消息支持 scenario 字段（free_chat / interviewer / english_teacher 等）
  // 打断：interrupt() 发送中断消息 + 停止 TTS + 保存部分回复
  // 认证：WebSocket 连接携带 JWT token，支持 conversation_id 恢复历史对话
}

存储策略（分阶段）

阶段	存储方案	持久化内容	理由
当前默认	Memory（进程内）	会话状态 + 对话历史	零依赖，快速启动。MemoryManager 支持 Write-Through 到 PG
已实现	Memory + PostgreSQL	用户数据、对话历史、会话元数据	通过 storage.driver: postgres 启用，MemoryManager 注入 PG Repository
已实现	Redis（独立）	会话状态 + 对话历史	通过配置切换到 RedisManager，适合多实例部署

冷热分离：Redis/Memory 存"热数据"（当前对话上下文，微秒级读写），PostgreSQL 存"冷数据"（历史记录）。MemoryManager 的 Write-Through 机制确保每次 AppendMessage 同时写入 PG，重启后可从 PG 恢复会话。

PostgreSQL 表设计（已实现）

实际迁移文件位于 backend/migrations/，通过 go:embed 嵌入，启动时自动执行：

-- 001_users.up.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 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()
);

-- 002_messages.up.sql
CREATE TABLE messages (
    id          BIGSERIAL PRIMARY KEY,
    session_id  UUID NOT NULL,
    role        VARCHAR(16) NOT NULL,
    content     TEXT NOT NULL,
    tokens_used INTEGER DEFAULT 0,
    created_at  TIMESTAMPTZ DEFAULT now()
);

-- 003_sessions.up.sql
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()
);

部署架构

用户浏览器
    ↓
Nginx（同源反代 + 负载均衡）
  ├── /            → 前端静态资源（CDN 或本地 dist）
  ├── /api/*       → Go Gateway（REST API）
  └── /ws          → Go Gateway（WebSocket）
        ├── Gateway-1 ──→ Redis
        ├── Gateway-2 ──→ Redis
        └── Gateway-N ──→ AI Services（外部 API）

跨域策略：Nginx 将前端和后端统一到同一域名下，浏览器无跨域问题。

Nginx 配置

server {
    listen 80;
    server_name camtalk.example.com;

    # 前端静态资源
    location / {
        root /var/www/camtalk/dist;
        try_files $uri $uri/ /index.html;
    }

    # REST API 反代
    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # WebSocket 反代
    location /ws {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 86400s;   # 长连接超时 24h
        proxy_send_timeout 86400s;
    }
}

WebSocket 是长连接，Nginx 必须配置 Upgrade 和 Connection 头。proxy_read_timeout 需要覆盖心跳间隔（客户端 30s ping），否则 Nginx 会主动断开空闲连接。

开发环境

开发时前端（Vite :5173）和后端（Gin :8080）不同端口。前端 WebSocket 地址基于 window.location.host 动态构建，通过 Vite server.proxy 转发到后端，无需硬编码端口。

vite.config.ts 中配置了 /ws（WebSocket）和 /api（REST）的代理，目标为 http://localhost:8080。