ChatRoom 架构文档
系统概览
ChatRoom 是一个实时聊天室应用，采用前后端分离架构，支持 WebSocket 实时通信。
技术栈
- 后端: Go 1.24, Gin, GORM, gorilla/websocket
- 前端: React 19, TypeScript, Vite
- 数据库: PostgreSQL 16
- 监控: Prometheus, Grafana
架构图
┌─────────────────────────────────────────────────────────────────┐
│ Client Layer │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Browser │ │ Browser │ │ Browser │ │
│ │ (React) │ │ (React) │ │ (React) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └────────────────┼────────────────┘ │
│ │ │
│ HTTP/WebSocket Connections │
└──────────────────────────┼───────────────────────────────────────┘
│
┌──────────────────────────┼───────────────────────────────────────┐
│ Application Layer │
├──────────────────────────┼───────────────────────────────────────┤
│ ▼ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Gin HTTP Server │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ REST API │ │ WebSocket │ │ Static │ │ │
│ │ │ Handlers │ │ Handler │ │ Files │ │ │
│ │ └──────┬──────┘ └──────┬──────┘ └─────────────┘ │ │
│ └─────────┼────────────────┼────────────────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Auth Module │ │ WebSocket Hub │ │
│ │ ┌───────────┐ │ │ ┌─────────┐ ┌─────────┐ │ │
│ │ │ JWT │ │ │ │ RoomHub │ │ RoomHub │ ... │ │
│ │ │ Handler │ │ │ │ (1) │ │ (2) │ │ │
│ │ └───────────┘ │ │ └────┬────┘ └────┬────┘ │ │
│ │ ┌───────────┐ │ │ │ │ │ │
│ │ │ Refresh │ │ │ ┌────┴────┐ ┌────┴────┐ │ │
│ │ │ Token │ │ │ │ Clients │ │ Clients │ │ │
│ │ └───────────┘ │ │ └─────────┘ └─────────┘ │ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
│
┌──────────────────────────┼───────────────────────────────────────┐
│ Data Layer │
├──────────────────────────┼───────────────────────────────────────┤
│ ▼ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ PostgreSQL │ │
│ │ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────────┐ │ │
│ │ │ users │ │ rooms │ │ messages │ │refresh_tokens│ │ │
│ │ └─────────┘ └─────────┘ └──────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘模块说明
cmd/server
程序入口，负责：
- 加载配置
- 初始化日志
- 连接数据库
- 启动 HTTP 服务器
internal/config
配置管理，从环境变量读取：
APP_PORT: 服务端口DATABASE_DSN: 数据库连接串JWT_SECRET: JWT 密钥APP_ENV: 运行环境
internal/auth
认证模块：
- JWT 令牌生成和验证
- 密码哈希 (bcrypt)
- 刷新令牌管理
- Gin 认证中间件
internal/server
HTTP 路由和处理器：
- REST API 端点
- 健康检查端点
- 静态文件服务
internal/ws
WebSocket 管理：
Hub: 全局连接管理RoomHub: 房间级广播Client: 单个连接抽象
internal/db
数据库连接和迁移：
- GORM 初始化
- 自动迁移
internal/models
数据模型：
User: 用户Room: 房间Message: 消息RefreshToken: 刷新令牌
internal/mw
HTTP 中间件：
- 速率限制
internal/metrics
Prometheus 指标：
- HTTP 请求计数
- 请求延迟
- WebSocket 连接数
数据流
认证流程
1. 用户注册 → POST /api/v1/auth/register → 创建用户记录
2. 用户登录 → POST /api/v1/auth/login → 返回 access_token + refresh_token
3. API 请求 → Authorization: Bearer <token> → 验证 JWT
4. 令牌刷新 → POST /api/v1/auth/refresh → 返回新令牌对WebSocket 消息流
1. 客户端连接 → ws://host/ws?room_id=X&token=Y
2. 服务端验证 → 检查 JWT 和房间存在性
3. 加入房间 → Client 注册到 RoomHub
4. 广播加入 → 通知房间内其他用户
5. 发送消息 → Client.readPump → 持久化 → RoomHub.broadcast
6. 接收消息 → RoomHub.run → fan-out 到所有 Client
7. 断开连接 → 广播离开 → 清理资源部署架构
单实例部署
┌─────────────┐ ┌─────────────┐
│ Nginx │────▶│ ChatRoom │────▶ PostgreSQL
│ (Reverse │ │ App │
│ Proxy) │ └─────────────┘
└─────────────┘Kubernetes 部署
┌─────────────────────────────────────────────────────┐
│ Kubernetes │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Ingress │ │ Service │ │ ConfigMap │ │
│ └──────┬──────┘ └──────┬──────┘ └─────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Deployment (HPA) │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Pod 1 │ │ Pod 2 │ │ Pod N │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ PostgreSQL Service │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘扩展考虑
水平扩展
当前 WebSocket Hub 仅在单进程内共享。水平扩展需要：
- Redis Pub/Sub: 跨实例消息广播
- Sticky Sessions: 确保 WebSocket 连接路由到同一实例
- 共享状态: 在线用户状态存储到 Redis
消息队列
高吞吐场景可引入消息队列：
Client → API → Message Queue → Worker → Database
↓
WebSocket Hub安全考虑
- JWT 密钥: 生产环境必须使用强随机密钥
- HTTPS: 生产环境必须启用 TLS
- 速率限制: 防止 API 滥用
- 输入验证: 所有用户输入都经过验证
- XSS 防护: 前端渲染时转义用户内容