# 直播IM系统开发指南

> **版本**: v3.0 | **更新时间**: 2024年12月25日 | **维护状态**: 🟢 活跃开发中

## 📋 目录

- [项目概述](#项目概述)
- [系统架构](#系统架构)
- [核心模块](#核心模块)
- [开发任务清单](#开发任务清单)
- [技术实现要点](#技术实现要点)
- [部署配置](#部署配置)
- [测试要点](#测试要点)
- [常见问题](#常见问题)
- [开发进度](#开发进度)

---

## 📖 项目概述

### 目标

搭建一个支持 **1-5万在线用户** 的直播+社交IM系统（单机部署）

### 技术栈

- **后端框架**: Spring Boot
- **实时通信**: WebSocket (Netty)
- **数据库**: MySQL 8.0
- **缓存**: Redis 6.0
- **反向代理**: Nginx
- **开发语言**: Java 8+

### 核心场景

- ✅ 直播间实时弹幕（支持千人直播间）
- ✅ 用户一对一私聊
- ✅ 好友关系管理
- ✅ 礼物打赏（直播间+私聊）
- ✅ 多媒体消息（图片、语音、视频）
- ⚠️ 社交互动通知（部分完成）

### 性能目标（单机）

| 指标 | 目标值 |
|------|--------|
| WebSocket连接数 | 5万+ |
| 消息吞吐量 | 5000条/秒 |
| 接口响应时间 (P99) | <100ms |
| 直播间弹幕延迟 | <200ms |
| 系统可用性 | 99%+ |

---

## 🏗️ 系统架构

### 整体架构图

```
客户端 (Android/iOS/Web)
    ↓
Nginx (负载均衡 + WebSocket代理)
    ↓
Spring Boot应用
    ├── WebSocket服务 (Netty)
    ├── HTTP API服务
    ├── 消息路由服务
    └── 业务逻辑服务
    ↓
数据层
    ├── MySQL (持久化存储)
    ├── Redis (缓存 + 在线状态 + 离线消息)
    └── 文件存储 (本地/OSS)
```

---

## 🧩 核心模块

### 模块1：用户认证模块 ✅

**功能清单**
- ✅ 用户注册/登录
- ✅ JWT Token生成与验证
- ✅ Token刷新机制
- ✅ 用户信息管理

**核心类**
- `LoginController` - 认证接口
- `JwtUtil` - JWT工具类
- `AuthService` - 认证业务逻辑
- `UserService` - 用户管理

---

### 模块2：WebSocket连接管理模块 ✅

**功能清单**
- ✅ WebSocket连接建立
- ✅ 用户在线状态管理
- ✅ 心跳检测（30秒间隔）
- ✅ 断线重连处理
- ✅ 连接映射维护（userId → WebSocket Session）

**核心类**
- `WebSocketConfig` - WebSocket配置
- `LiveChatHandler` - 直播间消息处理器
- `PrivateChatHandler` - 私聊消息处理器
- `HeartbeatScheduler` - 心跳检测定时任务
- `OnlineStatusService` - 在线状态服务

**关键流程**

| 事件 | 处理逻辑 |
|------|----------|
| 用户连接 | 保存连接 → 更新Redis在线状态 → 拉取离线消息 |
| 用户断开 | 移除连接 → 更新Redis状态 → 清理直播间在线列表 |
| 心跳超时 | 自动断开连接（90秒超时） |

---

### 模块3：消息路由模块 ✅

**功能清单**
- ✅ 单聊消息路由（点对点）
- ✅ 群聊消息广播（直播间）
- ✅ 消息分发逻辑
- ✅ 离线消息处理

**核心类**
- `MessageRouter` - 消息路由器（内置在Handler中）
- `MessageDispatcher` - 消息分发器（内置在Handler中）
- `LiveChatHandler` - 广播服务
- `OfflineMessageService` - 离线消息服务

**路由策略**

```
单聊消息:
  查询接收者在线状态
  ├── 在线 → 通过WebSocket直接推送
  └── 离线 → 存入Redis离线消息队列

直播间消息:
  获取房间所有在线用户（Redis Set）
  └── 批量异步推送（线程池处理）
```

---

### 模块4：消息存储模块 ✅

**功能清单**
- ✅ 消息持久化（MySQL）
- ✅ 消息缓存（Redis，7天TTL）
- ✅ 历史消息查询
- ✅ 离线消息队列
- ✅ 消息已读状态

**核心类**
- `LiveChatService` - 消息业务逻辑
- `LiveChatDao` - 消息数据访问
- `OfflineMessageService` - 消息缓存服务
- `ConversationService` - 会话管理

**存储策略**

| 存储层 | 用途 | 策略 |
|--------|------|------|
| MySQL | 持久化存储 | 所有消息先存MySQL |
| Redis | 热点缓存 | 7天TTL，加速查询 |
| Redis List | 离线消息 | 最多100条，7天过期 |
| 分页查询 | 历史消息 | 按时间倒序，20条/页 |

---

### 模块5：好友关系模块 ✅
**功能：**
- 添加好友（发送申请）✅
- 处理好友申请（同意/拒绝）✅
- 删除好友 ✅
- 好友列表查询 ✅
- 用户搜索 ✅
- 好友在线状态 ✅

**已实现的类：**
- `FriendController` - 好友接口 ✅
  - 搜索用户 (GET /api/front/users/search)
  - 发送好友请求 (POST /api/front/friends/request)
  - 获取好友请求列表 (GET /api/front/friends/requests)
  - 处理好友请求 (POST /api/front/friends/requests/{requestId}/handle)
  - 获取好友列表 (GET /api/front/friends)
  - 删除好友 (DELETE /api/front/friends/{friendId})

**业务流程：**
- 发送申请 → 保存申请记录 → 推送通知给对方 ✅
- 同意申请 → 双向添加好友关系 → 推送通知 → 创建会话 ✅
- 删除好友 → 删除好友关系 → 保留历史消息 ✅

**数据库表：**
- `eb_friend` - 好友关系表 ✅
- `eb_friend_request` - 好友申请表 ✅

---

### 模块6：直播间管理模块 ✓
**功能：**
- 进入直播间 ✓
- 离开直播间 ✓
- 直播间在线用户列表 ✓
- 直播间弹幕发送 ✓
- 直播间人数统计 ✓

**需要实现的类：**
- `LiveRoomController` - 直播间接口 ✓
- `LiveRoomService` - 直播间业务逻辑 ✓
- `RoomMemberService` - 房间成员管理 ✓ (内置在Handler中)
- `BarrageService` - 弹幕服务 ✓ (LiveChatService)

**关键功能：**
- 进入房间：加入Redis Set、广播进入消息、返回房间信息 ✓
- 发送弹幕：频率限制（1秒1条）⚠️、敏感词过滤 ⚠️、广播给所有人 ✓
- 离开房间：从Redis Set移除、广播离开消息 ✓

---

### 模块7：礼物打赏模块 ✓
**功能：**
- 礼物列表管理 ✓
- 直播间送礼 ✓
- 私聊送礼 ✓
- 礼物记录查询 ✓
- 余额扣除与收益增加 ✓

**需要实现的类：**
- `GiftController` - 礼物接口 ✓
- `GiftService` - 礼物业务逻辑 ✓
- `GiftRecordService` - 礼物记录服务 ✓
- `RechargeOptionService` - 充值选项服务 ✓
- `UserService` - 用户余额管理 ✓ (已有)
- `UserBillService` - 用户账单服务 ✓ (已有)

**业务流程：**
- 验证余额 → 扣除金币 → 增加收益 → 保存记录 → 生成账单 → 返回结果 ✓

**数据库表：**
- `eb_gift` - 礼物表 ✓
- `eb_gift_reward_record` - 礼物打赏记录表 ✓
- `eb_gift_detail` - 送礼物明细表 ✓
- `eb_gift_quantity` - 礼物数量列表（充值选项）✓

**API接口：**
- `GET /api/front/gift/list` - 获取礼物列表 ✓
- `GET /api/front/gift/balance` - 获取用户余额 ✓
- `POST /api/front/gift/send` - 赠送礼物 ✓
- `GET /api/front/gift/recharge/options` - 获取充值选项 ✓
- `POST /api/front/gift/recharge/create` - 创建充值订单 ✓

**文档：**
- 详细开发文档：`Zhibo/zhibo-h/礼物打赏模块开发说明.md` ✓
- 快速开始指南：`Zhibo/zhibo-h/礼物打赏模块快速开始.md` ✓
- 部署清单：`Zhibo/礼物打赏模块部署清单.md` ✓

---

### 模块8：多媒体消息模块 ✓
**功能：**
- 图片上传与发送 ✓
- 语音上传与发送 ✓
- 视频上传与发送 ✓
- 文件存储（本地/OSS）✓
- 缩略图生成 ✓

**需要实现的类：**
- `UploadController` - 文件上传接口 ✓ (UserUploadController)
- `FileStorageService` - 文件存储服务 ✓
- `ImageService` - 图片处理（压缩、缩略图）✓
- `MediaMessageService` - 多媒体消息服务 ✓

**处理流程：**
- 客户端先上传文件 → 返回URL → 发送消息时带上URL和元信息 ✓

---

### 模块9：消息已读回执模块 ✓
**功能：**
- 标记消息已读 ✓
- 未读消息统计 ✓
- 已读状态推送 ✓
- 会话未读数更新 ✓

**需要实现的类：**
- `ReadReceiptService` - 已读回执服务 ✓ (内置在ConversationService中)
- `UnreadCountService` - 未读数统计 ✓ (内置在ConversationService中)

**实现逻辑：**
- 用户查看消息 → 批量更新已读状态 → 推送已读回执给发送方 → 更新会话未读数 ✓

---

### 模块10：好友私聊消息模块 ✅ (已实现)
**功能：**
- 好友之间发送文本消息 ✅
- 好友之间发送图片消息 ✅
- 好友之间发送语音消息 ✅
- 好友之间发送视频消息 ✅
- 消息已读状态 ✅
- 正在输入提示 ✅
- 离线消息推送 ✅

**已实现的类：**
- `PrivateChatHandler` - 私聊WebSocket处理器 ✅
- `ConversationService` - 会话服务 ✅
- `ConversationController` - 会话接口 ✅
- `OfflineMessageService` - 离线消息服务 ✅

**核心功能：**
- 通过WebSocket实现实时消息推送 ✅
- 支持多设备同时在线 ✅
- 自动保存离线消息 ✅
- 消息已读回执 ✅
- 正在输入状态同步 ✅

**WebSocket路径：** `/ws/chat/{conversationId}?userId={userId}`

**消息类型：**
- `chat` - 聊天消息
- `read` - 已读通知
- `typing` - 正在输入
- `new_message` - 新消息通知

---

### 模块11：群组聊天模块 ❌ (未实现)
**功能：**
- 撤回自己发送的消息（2分钟内）❌
- 推送撤回通知 ❌
- 更新消息状态 ❌

**需要实现的类：**
- `MessageRecallService` - 消息撤回服务 ❌

**撤回逻辑：**
- 验证权限和时间 → 更新消息状态 → 推送撤回通知 → 更新会话最后消息 ❌

**优先级：** 低 - 非核心功能

---

**功能：**
- 创建群组 ❌
- 邀请成员加入群组 ❌
- 群组消息发送 ❌
- 群组消息广播 ❌
- 群组成员管理 ❌
- 群主/管理员权限 ❌
- 群公告 ❌
- @提醒功能 ❌

**需要实现的类：**
- `GroupChatHandler` - 群聊WebSocket处理器 ❌
- `GroupService` - 群组服务 ❌
- `GroupController` - 群组接口 ❌
- `GroupMemberService` - 群成员服务 ❌

**数据库表：**
- `eb_group` - 群组表 ❌
- `eb_group_member` - 群成员表 ❌
- `eb_group_message` - 群消息表 ❌

**优先级：** 中 - 增强社交互动
**预计工作量：** 4-5天

---

### 模块12：消息撤回模块 ❌ (未实现)
**功能：**
- 系统通知管理 ✅ (后台已实现)
- 点赞通知 ❌
- 评论通知 ❌
- 关注通知 ❌
- @提醒通知 ❌
- 系统公告 ⚠️ (基础功能已实现)

**已实现的类：**
- `SystemNotificationController` - 系统通知接口 ✅ (后台管理)
- `SystemNotificationService` - 通知业务逻辑 ✅
- `SystemNotification` - 通知实体 ✅

**待实现：**
- 前端通知推送接口 ❌
- 实时推送服务 (WebSocket/FCM) ❌
- 社交互动通知 (点赞、评论、关注) ❌

**优先级：** 中 - 增强用户体验

---

**功能：**
- 撤回自己发送的消息（2分钟内）❌
- 推送撤回通知 ❌
- 更新消息状态 ❌

**需要实现的类：**
- `MessageRecallService` - 消息撤回服务 ❌

**撤回逻辑：**
- 验证权限和时间 → 更新消息状态 → 推送撤回通知 → 更新会话最后消息 ❌

**优先级：** 低 - 非核心功能
**预计工作量：** 1-2天

---

### 模块13：消息转发模块 ❌ (未实现)
**功能：**
- 转发消息给好友 ❌
- 转发消息到群组 ❌
- 批量转发 ❌
- 转发历史记录 ❌

**需要实现的类：**
- `MessageForwardService` - 消息转发服务 ❌

**优先级：** 低 - 辅助功能
**预计工作量：** 1-2天

---

### 模块14：语音/视频通话模块 ❌ (未实现)
**功能：**
- 一对一语音通话 ❌
- 一对一视频通话 ❌
- 通话邀请/接听/拒绝 ❌
- 通话记录 ❌
- 通话质量监控 ❌

**需要实现的类：**
- `CallService` - 通话服务 ❌
- `CallController` - 通话接口 ❌
- `CallSignalingHandler` - 信令WebSocket处理器 ❌

**技术方案：**
- 使用WebRTC实现音视频通话
- 使用WebSocket传输信令
- 可选：集成第三方服务（声网、腾讯云）

**优先级：** 低 - 高级功能
**预计工作量：** 5-7天

---

### 模块15：消息搜索模块 ❌ (未实现)
**功能：**
- 搜索聊天记录 ❌
- 按时间范围搜索 ❌
- 按消息类型搜索 ❌
- 搜索结果高亮 ❌

**需要实现的类：**
- `MessageSearchService` - 消息搜索服务 ❌

**技术方案：**
- 使用MySQL全文索引
- 或使用Elasticsearch

**优先级：** 中 - 提升用户体验
**预计工作量：** 2-3天

---

### 模块16：消息引用/回复模块 ❌ (未实现)
**功能：**
- 引用消息回复 ❌
- 显示被引用的消息 ❌
- 点击引用跳转到原消息 ❌

**需要实现的类：**
- 扩展现有的消息模型 ❌

**优先级：** 低 - 辅助功能
**预计工作量：** 1-2天

---

### 模块17：消息表情回应模块 ❌ (未实现)
**功能：**
- 对消息添加表情回应 ❌
- 查看谁回应了表情 ❌
- 取消表情回应 ❌

**需要实现的类：**
- `MessageReactionService` - 消息回应服务 ❌

**数据库表：**
- `eb_message_reaction` - 消息回应表 ❌

**优先级：** 低 - 增强互动
**预计工作量：** 1-2天

---

### 模块18：敏感词过滤模块 ❌ (未实现)
**功能：**
- 敏感词库管理 ❌
- DFA算法过滤 ❌
- 消息内容检测 ❌

**需要实现的类：**
- `SensitiveWordFilter` - 敏感词过滤器 ❌
- `SensitiveWordService` - 敏感词管理 ❌

**过滤策略：**
- 使用DFA算法构建敏感词树 ❌
- 消息发送前过滤 ❌
- 替换为***或直接拒绝 ❌

**优先级：** 高 - 内容安全必需
**建议：** 可先使用第三方内容审核API (如阿里云、腾讯云)

---

### 模块19：限流防刷模块 ⚠️ (需完善)
**功能：**
- 消息发送频率限制 ❌ (未实现)
- 接口调用限流 ❌ (未实现)
- IP黑名单 ⚠️ (基础功能存在)
- 用户封禁 ⚠️ (基础功能存在)

**需要实现的类：**
- `RateLimiterService` - 限流服务 ❌
- `RateLimitInterceptor` - 限流拦截器 ❌
- `RateLimitAspect` - 限流切面 ❌

**限流策略：**
- 使用Redis + 令牌桶算法 ❌
- 弹幕：1秒1条 ❌
- 私聊：1秒3条 ❌
- 图片：1分钟10张 ❌

**优先级：** 高 - 防止恶意刷屏和攻击
**建议：** 使用Redisson的RRateLimiter或Guava的RateLimiter

---

## 三、开发任务清单（7天计划）

### Day 1：基础架构 ✓
- [x] 创建Spring Boot项目 ✓
- [x] 配置MySQL、Redis连接 ✓
- [x] 集成MyBatis-Plus ✓
- [x] 实现JWT认证 ✓
- [x] 实现用户注册/登录接口 ✓

### Day 2：WebSocket核心 ✓
- [x] 配置WebSocket ✓
- [x] 实现连接管理器 ✓
- [x] 实现心跳检测 ⚠️ (需完善)
- [x] 实现在线状态管理 ✓
- [x] 测试连接建立和断开 ✓

### Day 3：消息收发 ✅
- [x] 实现单聊消息发送 ✅
- [x] 实现消息路由逻辑 ✅
- [x] 实现消息存储 ✅
- [x] 实现离线消息 ✅
- [x] 实现历史消息查询 ✅

### Day 4：直播间功能 ✓
- [x] 实现进入/离开直播间 ✓
- [x] 实现弹幕发送 ✓
- [x] 实现弹幕广播 ✓
- [x] 实现在线人数统计 ✓
- [ ] 实现敏感词过滤 ❌

### Day 5：社交功能 ✅
- [x] 实现好友申请/处理 ✅
- [x] 实现好友列表 ✅
- [x] 实现用户搜索 ✅
- [x] 实现礼物打赏（直播间+私聊）✅
- [x] 实现消息已读回执 ✅
- [ ] 实现消息撤回 ❌ (非必需)

### Day 6：多媒体消息 ✓
- [x] 实现图片上传 ✓
- [x] 实现语音上传 ✓
- [x] 实现视频上传 ✓
- [x] 实现多媒体消息发送 ✓
- [ ] 实现通知推送 ❌

### Day 7：测试优化 ⚠️
- [ ] 功能测试 ⚠️ (进行中)
- [ ] 压力测试 ❌ (未开始)
- [ ] 性能优化 ⚠️ (需完善)
- [ ] 部署上线 ⚠️ (需完善)
- [ ] 限流防刷 ❌ (待实现)
- [ ] 敏感词过滤 ❌ (待实现)

---

## 四、关键技术实现要点

### 1. WebSocket消息格式（统一JSON）

**客户端发送：**
```json
{
  "action": "sendMessage|sendBarrage|enterRoom|leaveRoom|heartbeat",
  "data": {
    // 具体数据
  }
}
```

**服务端推送：**
```json
{
  "type": "message|barrage|gift|notification|system",
  "data": {
    // 具体数据
  }
}
```

### 2. Redis数据结构设计（单机版）

```
在线用户：Hash
Key: online:users
Field: userId
Value: {sessionId, connectTime, lastHeartbeat}
TTL: 5分钟（心跳更新）

直播间在线：Set
Key: room:online:{roomId}
Member: userId
TTL: 1小时

用户连接映射：String
Key: user:conn:{userId}
Value: sessionId
TTL: 5分钟

离线消息队列：List（限制长度）✅
Key: offline:msg:{userId}
Value: [完整消息JSON1, 完整消息JSON2, ...]
LTRIM: 保留最新100条
TTL: 7天

消息缓存：String (TTL=7天)
Key: msg:{msgId}
Value: JSON消息体
TTL: 7天

会话未读数：Hash
Key: conversation:unread:{userId}
Field: conversationId
Value: unreadCount

限流令牌桶：String
Key: ratelimit:{type}:{userId}
Value: tokens
TTL: 1秒

用户在线状态：String
Key: user:online:{userId}
Value: 1/0
TTL: 5分钟

直播间人数统计：String
Key: room:viewers:{roomId}
Value: count
TTL: 1小时

热点数据缓存：String
Key: cache:{type}:{id}
Value: JSON数据
TTL: 根据类型设置（用户信息1小时，直播间列表5分钟）
```

### 3. 消息路由核心逻辑（单机版）

```java
// 单聊路由
if (目标用户在线) {
    通过WebSocket直接推送
} else {
    存入离线消息队列（Redis List）
    发送推送通知（可选）
}

// 直播间广播
获取房间所有在线用户（Redis Set）
for (每个用户) {
    异步推送消息（线程池处理）
}

// 消息持久化（异步批量）
消息先放入内存队列（LinkedBlockingQueue）
定时任务（1秒一次）批量写入MySQL（200条/批）
写入失败重试3次，最终失败记录日志
```

### 4. 性能优化关键点（单台服务器）

**连接优化：**
- 使用Netty替代Spring WebSocket（性能提升3-5倍）
- 单机支持5-10万连接（8核16G配置）
- 系统参数优化（文件描述符、TCP参数）

**消息优化：**
- 弹幕限流：1秒1条（Redis令牌桶）
- 批量入库：200条/批次（异步批量写入）
- 启用WebSocket压缩（减少50%流量）

**存储优化：**
- 消息缓存7天（Redis）
- 历史消息分页查询（MySQL索引优化）
- 离线消息限制100条（Redis List）
- 热点数据缓存（本地缓存Caffeine + Redis）

**广播优化：**
- 异步推送（线程池处理）
- 失败重试1次（避免阻塞）
- 单次超时100ms
- 大直播间分组推送（每组500人）

**数据库优化：**
- 连接池优化（HikariCP）
- 索引优化（覆盖索引、联合索引）
- 慢查询优化
- 定期清理历史数据

**缓存优化：**
- 二级缓存（Caffeine + Redis）
- 热点数据预加载
- 缓存穿透防护（布隆过滤器）
- 合理设置过期时间

**网络优化：**
- CDN加速（图片、视频）
- 长连接复用
- 心跳包优化（30秒一次）
- 消息压缩（Gzip）

---

## 七、WebSocket消息类型

### 客户端发送

**直播间弹幕 (LiveChatHandler):**
- `heartbeat` - 心跳
- `sendBarrage` - 发送弹幕
- `enterRoom` - 进入直播间
- `leaveRoom` - 离开直播间
- `sendGift` - 送礼物

**私聊消息 (PrivateChatHandler):**
- `chat` - 发送聊天消息
  - `messageType`: text/image/voice/video
- `read` - 标记已读
- `typing` - 正在输入

**待实现:**
- `recallMessage` - 撤回消息 ❌
- `forwardMessage` - 转发消息 ❌
- `replyMessage` - 引用回复 ❌

### 服务端推送

**直播间消息:**
- `barrage` - 弹幕消息
- `gift` - 礼物消息
- `enterRoom` - 进入房间通知
- `leaveRoom` - 离开房间通知
- `system` - 系统消息

**私聊消息:**
- `chat` - 聊天消息
- `new_message` - 新消息通知
- `read` - 已读回执
- `typing` - 正在输入通知
- `connected` - 连接成功
- `error` - 错误消息

**待实现:**
- `recall` - 撤回通知 ❌
- `forward` - 转发通知 ❌
- `call_invite` - 通话邀请 ❌
- `call_accept` - 通话接听 ❌
- `call_reject` - 通话拒绝 ❌

---

## 八、部署配置（单台服务器优化版）

### 服务器配置建议

**推荐配置（支持5-10万用户）：**
- CPU：8核或16核
- 内存：16G或32G
- 硬盘：SSD 500G
- 带宽：20M或更高
- 系统：CentOS 7.9 / Ubuntu 20.04
- 软件：JDK 11+、MySQL 8.0、Redis 6.0、Nginx

**最低配置（支持3-5万用户）：**
- CPU：4核
- 内存：8G
- 硬盘：SSD 200G
- 带宽：10M
- 系统：CentOS 7.9 / Ubuntu 20.04

**成本估算：** 约500-1500元/月（云服务器）

### 应用配置（生产环境）

```yaml
server:
  port: 8080
  tomcat:
    threads:
      max: 300
      min-spare: 50
    max-connections: 10000
    accept-count: 500

spring:
  # MySQL配置
  datasource:
    url: jdbc:mysql://localhost:3306/im_system?useSSL=false&serverTimezone=Asia/Shanghai&useUnicode=true&characterEncoding=utf8
    username: root
    password: your_password
    hikari:
      maximum-pool-size: 50
      minimum-idle: 10
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000
    
  # Redis配置
  redis:
    host: localhost
    port: 6379
    password: your_redis_password
    database: 0
    lettuce:
      pool:
        max-active: 100
        max-idle: 20
        min-idle: 5
        max-wait: 3000
    timeout: 3000
    
jwt:
  secret: your-secret-key-change-in-production-min-32-chars
  expiration: 604800000  # 7天
  
# WebSocket配置（使用Netty）
netty:
  websocket:
    port: 9090
    boss-threads: 1
    worker-threads: 8
    max-frame-size: 65536
    heartbeat-interval: 30000  # 30秒
    heartbeat-timeout: 90000   # 90秒
    max-connections: 100000    # 最大连接数
  
# 消息配置
message:
  batch-size: 200              # 批量入库大小
  batch-timeout: 1000          # 批量超时时间(ms)
    
# 限流配置
rate-limit:
  barrage:
    rate: 1                    # 弹幕：1条/秒
    capacity: 5                # 令牌桶容量
  private-message:
    rate: 3                    # 私聊：3条/秒
    capacity: 10
  image-upload:
    rate: 10                   # 图片：10张/分钟
    capacity: 20
    
# 文件上传配置
upload:
  path: /data/upload
  max-size: 10485760           # 10MB
  image-max-size: 5242880      # 5MB
  video-max-size: 104857600    # 100MB
  
# 缓存配置
cache:
  caffeine:
    user-info:
      max-size: 10000
      expire-after-write: 3600  # 1小时
    room-info:
      max-size: 5000
      expire-after-write: 300   # 5分钟
```

### 系统优化配置

**1. Linux系统参数优化（/etc/sysctl.conf）**
```bash
# 增加文件描述符限制
fs.file-max = 1000000

# TCP优化
net.ipv4.tcp_max_syn_backlog = 8192
net.core.somaxconn = 8192
net.core.netdev_max_backlog = 8192
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_fin_timeout = 30

# 应用后执行
sysctl -p
```

**2. 用户限制优化（/etc/security/limits.conf）**
```bash
* soft nofile 100000
* hard nofile 100000
* soft nproc 100000
* hard nproc 100000
```

**3. MySQL优化（my.cnf）**
```ini
[mysqld]
# 连接数
max_connections = 500

# 缓冲池大小（建议设置为内存的50-70%）
innodb_buffer_pool_size = 8G

# 日志文件大小
innodb_log_file_size = 512M

# 查询缓存
query_cache_size = 128M
query_cache_type = 1

# 慢查询日志
slow_query_log = 1
long_query_time = 2
```

**4. Redis优化（redis.conf）**
```ini
# 最大内存（建议设置为物理内存的50%）
maxmemory 8gb

# 淘汰策略
maxmemory-policy allkeys-lru

# 持久化（根据需求选择）
save 900 1
save 300 10
save 60 10000

# AOF持久化（可选）
appendonly yes
appendfsync everysec
```

### Nginx配置（WebSocket代理）

```nginx
upstream websocket_backend {
    server 127.0.0.1:9090;
}

upstream http_backend {
    server 127.0.0.1:8080;
}

server {
    listen 80;
    server_name yourdomain.com;
    
    # WebSocket代理
    location /ws/ {
        proxy_pass http://websocket_backend;
        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_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_connect_timeout 60s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;
    }
    
    # HTTP API代理
    location /api/ {
        proxy_pass http://http_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_connect_timeout 10s;
        proxy_send_timeout 30s;
        proxy_read_timeout 30s;
    }
    
    # 静态文件
    location /upload/ {
        alias /data/upload/;
        expires 30d;
    }
}
```

---

## 九、测试要点（单台服务器）

### 功能测试
- [ ] 用户登录注册
- [ ] WebSocket连接建立
- [ ] 单聊消息收发
- [ ] 直播间弹幕
- [ ] 好友申请处理
- [ ] 礼物打赏
- [ ] 图片/语音消息
- [ ] 消息已读
- [ ] 消息撤回
- [ ] 离线消息

### 性能测试（使用JMeter/Gatling）

**1. 连接压测**
- [ ] 连接数：5000（目标达成）
- [ ] 连接数：10000（目标达成）
- [ ] 连接数：50000（挑战目标）
- [ ] 连接建立速度：500连接/秒
- [ ] 连接稳定性：24小时不断线

**2. 消息吞吐量测试**
- [ ] 吞吐量：1000条/秒
- [ ] 吞吐量：3000条/秒
- [ ] 吞吐量：5000条/秒（目标）
- [ ] 弹幕广播延迟：P99 < 200ms
- [ ] 私聊消息延迟：P99 < 100ms

**3. 接口性能测试**
- [ ] 登录接口：QPS 500+，响应时间 < 50ms
- [ ] 消息列表：QPS 1000+，响应时间 < 100ms
- [ ] 好友列表：QPS 800+，响应时间 < 80ms
- [ ] 直播间列表：QPS 1500+，响应时间 < 100ms

**4. 数据库压测**
- [ ] MySQL读QPS：2000+
- [ ] MySQL写QPS：1000+
- [ ] Redis读QPS：10000+
- [ ] Redis写QPS：5000+

**5. 稳定性测试**
- [ ] 24小时压测
- [ ] 内存泄漏检测
- [ ] CPU使用率 < 70%
- [ ] 内存使用率 < 80%

### 压测工具推荐
- **JMeter**: HTTP接口压测
- **Gatling**: WebSocket压测
- **wrk**: 轻量级HTTP压测

---

## 十、常见问题处理（单台服务器）

### 1. 消息丢失怎么办？
- 实现消息ACK确认机制（客户端确认收到）
- 离线消息队列保底（Redis List）
- 客户端重发机制（3次重试）
- 数据库最终一致性（异步入库）

### 2. 直播间消息风暴？
- 消息限流（1秒1条，Redis令牌桶）
- 超过阈值丢弃（保护服务器）
- 降级策略（高峰期只推送重要消息）
- 大直播间分组推送（每组500人）

### 3. 单机性能瓶颈？
- 优化代码（减少不必要的计算）
- 使用Netty替代Spring WebSocket
- 启用本地缓存（Caffeine）
- 数据库连接池优化
- Redis连接池优化
- 考虑升级服务器配置

### 4. 如何保证消息顺序？
- 单聊：按时间戳排序（客户端排序）
- 直播间：不保证严格顺序（可接受）
- 重要消息：使用消息ID递增（数据库自增ID）

### 5. WebSocket连接频繁断开？
- 增加心跳间隔（30秒）
- 客户端自动重连（指数退避）
- Nginx超时时间调整（300秒）
- 检查网络质量（弱网优化）

### 6. Redis内存不足？
- 设置过期时间（消息7天过期）
- 淘汰策略（LRU）
- 定期清理冷数据
- 考虑增加内存

### 7. MySQL慢查询？
- 添加索引（覆盖索引、联合索引）
- 优化SQL语句
- 分页查询（避免全表扫描）
- 缓存热点数据（Redis）

### 8. 如何监控系统健康？
- 日志监控（查看错误日志）
- 性能监控（CPU、内存、网络）
- 连接数监控（WebSocket连接数）
- 慢查询监控（MySQL慢查询日志）

### 9. 成本优化建议
- 使用云服务器按量付费
- CDN加速（减少带宽成本）
- 数据压缩（减少存储成本）
- 冷数据归档（对象存储）

---

---

## 十一、扩展性设计（未来扩展到更大规模）

如果未来需要支持10万+甚至50万用户，可以考虑以下升级方案：

### 1. 集群部署
- 多台WebSocket服务器（3-5台）
- Nginx负载均衡（IP Hash策略）
- 使用RabbitMQ实现跨服务器消息转发

### 2. 数据库优化
- MySQL读写分离（1主2从）
- 分库分表（按用户ID取模）
- 使用分布式数据库（TiDB）

### 3. 缓存优化
- Redis Cluster（3主3从）
- 本地缓存+Redis二级缓存
- 缓存预热

### 4. 监控告警
- Prometheus + Grafana
- ELK日志分析
- 实时告警系统

---

**文档版本：** v3.0  
**适用对象：** Java后端开发者  
**开发周期：** 2周（含测试优化）  
**用户规模：** 5-10万（单台服务器）


---

## 📊 开发进度总结

### 已完成模块 ✅

1. **用户认证模块** ✅
   - 登录、注册、验证码功能完整
   - JWT Token生成与验证
   - Token刷新机制

2. **用户资料模块** ✅
   - 用户信息管理、头像上传
   - 个人资料修改
   - 手机号换绑

3. **直播间模块** ✅
   - 直播间列表、详情、创建、删除
   - SRS推流回调集成
   - 直播间在线人数统计

4. **消息聊天模块** ✅
   - 私信会话列表、消息发送接收
   - WebSocket实时通信
   - 会话搜索功能
   - 消息已读状态

5. **直播间弹幕模块** ✅
   - 弹幕发送、接收、广播
   - WebSocket实时推送
   - 进入/离开房间通知

6. **多媒体消息模块** ✅
   - 图片、语音、视频上传
   - 文件存储服务 (本地/OSS/COS/七牛云)
   - 图片压缩和缩略图

7. **礼物打赏模块** ✅
   - 礼物列表管理
   - 礼物赠送功能（完整事务处理）
   - 用户余额管理
   - 充值选项配置
   - 账单记录生成
   - 支持直播间和私聊场景

8. **在线状态模块** ✅
   - 用户在线状态管理
   - 心跳检测机制 (30秒间隔)
   - 超时自动断开 (90秒)

9. **离线消息模块** ✅
   - 离线消息存储 (Redis + MySQL)
   - 消息推送机制
   - 离线消息拉取

10. **好友关系模块** ✅
    - 用户搜索功能
    - 好友申请/处理
    - 好友列表查询
    - 删除好友
    - 好友在线状态

11. **好友私聊消息模块** ✅
    - 好友之间实时消息
    - 多媒体消息支持
    - 消息已读状态
    - 正在输入提示
    - 离线消息推送
    - 用户搜索功能
    - 好友申请/处理
    - 好友列表查询
    - 删除好友
    - 好友在线状态

### 待完成的IM通信模块 ❌

1. **群组聊天模块** ❌ (未实现)
   - 创建群组、邀请成员 ❌
   - 群组消息发送与广播 ❌
   - 群组成员管理 ❌
   - 群主/管理员权限 ❌
   - **优先级：** 中
   - **预计工作量：** 4-5天

2. **消息撤回模块** ❌ (未实现)
   - 撤回消息（2分钟内）❌
   - 推送撤回通知 ❌
   - **优先级：** 低
   - **预计工作量：** 1-2天

3. **消息转发模块** ❌ (未实现)
   - 转发消息给好友/群组 ❌
   - 批量转发 ❌
   - **优先级：** 低
   - **预计工作量：** 1-2天

4. **语音/视频通话模块** ❌ (未实现)
   - 一对一语音/视频通话 ❌
   - 通话邀请/接听/拒绝 ❌
   - 通话记录 ❌
   - **优先级：** 低
   - **预计工作量：** 5-7天
   - **技术方案：** WebRTC或第三方SDK

5. **消息搜索模块** ❌ (未实现)
   - 搜索聊天记录 ❌
   - 按时间/类型搜索 ❌
   - **优先级：** 中
   - **预计工作量：** 2-3天

6. **消息引用/回复模块** ❌ (未实现)
   - 引用消息回复 ❌
   - 跳转到原消息 ❌
   - **优先级：** 低
   - **预计工作量：** 1-2天

7. **消息表情回应模块** ❌ (未实现)
   - 对消息添加表情回应 ❌
   - 查看回应列表 ❌
   - **优先级：** 低
   - **预计工作量：** 1-2天

### 待完成的业务功能模块 ❌

8. **作品管理模块** ❌ (未实现)
   - 作品发布、编辑、删除 ❌
   - 作品列表查询 ❌
   - 作品点赞、收藏 ❌
   - **优先级：** 中
   - **预计工作量：** 3-4天

9. **评论功能模块** ❌ (未实现)
   - 评论发布、回复 ❌
   - 评论列表查询 ❌
   - 评论点赞 ❌
   - **优先级：** 中
   - **预计工作量：** 2-3天
   - **注意：** 商品评论已实现，但作品评论未实现

10. **社交功能模块** ⚠️ (部分实现)
   - 关注/取消关注 ❌
   - 粉丝列表 ❌
   - 关注列表 ❌
   - 好友管理 ✅ (已完成)
   - **优先级：** 高
   - **预计工作量：** 2-3天

11. **搜索功能模块** ⚠️ (部分实现)
   - 用户搜索 ✅ (已完成)
   - 直播间搜索 ❌
   - 作品搜索 ❌
   - 搜索历史 ❌
   - 热门搜索 ❌
   - **优先级：** 中
   - **预计工作量：** 2-3天

12. **分类管理模块** ⚠️ (基础功能存在)
   - 分类列表 ⚠️ (商品分类已实现)
   - 直播间分类 ❌
   - 作品分类 ❌
   - 分类筛选 ❌
   - **优先级：** 低
   - **预计工作量：** 1-2天

13. **通知推送模块** ⚠️ (部分实现)
   - 系统通知 ⚠️ (后台管理已实现)
   - 前端通知接口 ❌
   - 实时推送 (WebSocket) ❌
   - FCM集成 ❌
   - 推送历史 ❌
   - **优先级：** 中
   - **预计工作量：** 3-4天

14. **支付集成模块** ⚠️ (部分实现)
   - 微信支付 ✅ (已实现)
   - 支付宝支付 ❌
   - 充值功能 ✅ (已实现)
   - 支付回调处理 ✅ (已实现)
   - 礼物充值 ✅ (已实现)
   - **优先级：** 高 (礼物打赏需要)
   - **预计工作量：** 2-3天 (仅支付宝)

15. **限流防刷模块** ❌ (未实现)
   - 消息发送频率限制 ❌
   - 接口调用限流 ❌
   - 防刷机制 ❌
   - **优先级：** 高
   - **预计工作量：** 2-3天

16. **敏感词过滤模块** ❌ (未实现)
   - 敏感词库管理 ❌
   - 内容过滤 ❌
   - **优先级：** 高
   - **预计工作量：** 2-3天

### 完成度统计

- **已完成模块**: 11个
- **部分完成模块**: 4个
- **未完成IM通信模块**: 7个
- **未完成业务功能模块**: 9个
- **总体完成度**: 约 55%

**IM核心功能完成度**: 约 75%
- 一对一私聊 ✅
- 直播间弹幕 ✅
- 离线消息 ✅
- 群组聊天 ❌
- 语音/视频通话 ❌

**业务功能完成度**: 约 60%

### 核心功能完成度

- **直播核心功能**: 95% ✅
  - 直播间管理 ✅
  - 弹幕系统 ✅
  - 礼物打赏 ✅
  - 推流集成 ✅
  - 在线人数统计 ✅
  - **缺失**: 限流防刷 ❌

- **社交功能**: 70% ⚠️
  - 私信聊天 ✅
  - 在线状态 ✅
  - 好友管理 ✅
  - 用户搜索 ✅
  - 关注功能 ❌
  - 评论功能 ❌

- **用户系统**: 90% ✅
  - 认证登录 ✅
  - 资料管理 ✅
  - 余额管理 ✅
  - 账单记录 ✅
  - 充值功能 ✅
  - **缺失**: 支付宝支付 ❌

- **内容管理**: 45% ⚠️
  - 多媒体上传 ✅
  - 作品管理 ❌
  - 分类管理 ✅ (商品分类、直播间分类、作品分类已实现)
  - 搜索功能 ⚠️ (用户搜索已实现)

- **安全防护**: 20% ❌
  - 限流防刷 ❌
  - 敏感词过滤 ❌
  - IP黑名单 ⚠️
  - 用户封禁 ⚠️

### 最新更新

**2024年12月25日 - 系统功能完成度分析**

**已完成的核心功能：**
- ✅ 用户认证与资料管理 (90%)
- ✅ 直播间管理与弹幕系统 (95%)
- ✅ 私信聊天与会话管理 (100%)
- ✅ 好友关系管理 (100%)
- ✅ 礼物打赏系统 (100%)
- ✅ 多媒体消息 (100%)
- ✅ 在线状态与心跳检测 (100%)
- ✅ 离线消息处理 (100%)
- ✅ WebSocket实时通信 (100%)

**待完成的重要功能：**
- ❌ 限流防刷机制 (0%) - **高优先级**
- ❌ 敏感词过滤 (0%) - **高优先级**
- ❌ 关注/粉丝功能 (0%) - **高优先级**
- ❌ 作品管理 (0%) - **中优先级**
- ❌ 评论功能 (0%) - **中优先级**
- ❌ 搜索功能 (30%) - **中优先级**
- ❌ 通知推送 (20%) - **中优先级**

**技术债务：**
- 需要添加限流防刷机制保护系统
- 需要实现敏感词过滤保证内容安全
- 需要完善错误处理和日志记录
- 需要进行性能测试和优化

### 下一步开发计划

**第一阶段：IM核心功能完善 (2-3周) - 高优先级**

1. **群组聊天模块** ❌
   - 创建群组、邀请成员
   - 群组消息发送与广播
   - 群组成员管理
   - 群主/管理员权限
   - **预计工作量**: 4-5天

2. **消息搜索模块** ❌
   - 搜索聊天记录
   - 按时间/类型搜索
   - **预计工作量**: 2-3天

3. **消息撤回模块** ❌
   - 撤回消息（2分钟内）
   - 推送撤回通知
   - **预计工作量**: 1-2天

**第二阶段：安全与稳定性 (1-2周) - 高优先级**

4. **限流防刷机制** ⚠️
   - 实现消息发送频率限制
   - 实现接口调用限流
   - 防止恶意刷屏和攻击
   - **预计工作量**: 2-3天

5. **敏感词过滤** ⚠️
   - 实现敏感词库管理
   - 实现内容过滤机制
   - 保证内容安全
   - **预计工作量**: 2-3天

6. **性能测试与优化** ⚠️
   - 压力测试
   - 性能瓶颈分析
   - 数据库优化
   - **预计工作量**: 3-5天

**第三阶段：社交功能完善 (1-2周) - 高优先级**

7. **关注/粉丝功能** ❌
   - 关注/取消关注
   - 粉丝列表
   - 关注列表
   - **预计工作量**: 2-3天

8. **支付宝支付集成** ❌
   - 支付宝SDK集成
   - 支付回调处理
   - **预计工作量**: 2-3天

**第四阶段：内容管理 (2-3周) - 中优先级**

9. **作品管理模块** ❌
   - 作品发布、编辑、删除
   - 作品列表查询
   - 作品点赞、收藏
   - **预计工作量**: 3-4天

10. **评论功能模块** ❌
   - 评论发布、回复
   - 评论列表查询
   - 评论点赞
   - **预计工作量**: 2-3天

11. **搜索功能完善** ⚠️
   - 直播间搜索
   - 作品搜索
   - 搜索历史
   - 热门搜索
   - **预计工作量**: 2-3天

**第五阶段：辅助功能 (2-3周) - 低优先级**

12. **通知推送完善** ⚠️
   - 前端通知接口
   - 实时推送 (WebSocket)
   - FCM集成
   - **预计工作量**: 3-4天

13. **分类管理** ⚠️
    - 直播间分类
    - 作品分类
    - 分类筛选
    - **预计工作量**: 1-2天

14. **消息转发模块** ❌
    - 转发消息给好友/群组
    - **预计工作量：** 1-2天

15. **消息引用/回复模块** ❌
    - 引用消息回复
    - **预计工作量：** 1-2天

16. **消息表情回应模块** ❌
    - 对消息添加表情回应
    - **预计工作量：** 1-2天

17. **语音/视频通话模块** ❌ (可选)
    - 一对一语音/视频通话
    - **预计工作量：** 5-7天
    - **技术方案：** WebRTC或第三方SDK

**总预计开发时间**: 8-12周

---

## 📊 项目状态总结

### 可以投入使用的IM功能 ✅
- 用户注册登录
- 直播间管理与观看
- 实时弹幕聊天
- **好友一对一私聊** (文本/图片/语音/视频)
- 好友管理
- 礼物打赏
- 多媒体消息
- 在线状态
- 消息已读状态
- 正在输入提示
- 离线消息推送

### 需要补充的IM功能 ⚠️
- **群组聊天** - 多人聊天场景
- **消息搜索** - 查找历史消息
- **消息撤回** - 撤回错误消息
- **限流防刷** - 防止恶意攻击
- **敏感词过滤** - 内容安全

### 可选的高级IM功能 (低优先级)
- 消息转发
- 消息引用/回复
- 消息表情回应
- 语音/视频通话

### 建议开发顺序
1. **优先完善IM核心功能**（群组聊天、消息搜索、消息撤回）
2. **然后完善安全防护**（限流、敏感词）
3. **再进行性能测试和优化**
4. **接着开发社交功能**（关注、评论）
5. **最后完善辅助功能**（搜索、通知、高级IM功能）

---

**最后更新时间**: 2024年12月25日
**当前版本**: v1.0
**维护状态**: 🟢 活跃开发中
**核心功能完成度**: 85%
**整体完成度**: 65%