# webchat

**Repository Path**: hu-jiefei/webchat

## Basic Information

- **Project Name**: webchat
- **Description**: 仿微信web端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-04
- **Last Updated**: 2026-05-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebChat 即时通讯

[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.6.13-brightgreen)](https://spring.io/projects/spring-boot)
[![MyBatis-Plus](https://img.shields.io/badge/MyBatis--Plus-3.5.5-blue)](https://baomidou.com/)
[![JWT](https://img.shields.io/badge/JWT-0.12.x-orange)](https://github.com/jwtk/jjwt)
[![WebSocket](https://img.shields.io/badge/WebSocket-STOMP-important)](https://stomp.github.io/)
[![Redis](https://img.shields.io/badge/Redis-Lettuce-red)](https://redis.io/)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

**WebChat** 是一个功能完备、生产就绪的即时通讯（IM）后端系统，支持单聊、群聊、文件传输、在线状态、操作日志等企业级核心特性。采用 Spring Boot 2.6.13 + WebSocket + JWT + MyBatis-Plus + Redis 构建，提供高并发、高可用的实时消息服务。

---

## 📖 目录

- [核心功能](#-核心功能)
- [技术栈](#-技术栈)
- [架构设计](#-架构设计)
- [数据库设计](#-数据库设计)
- [快速开始](#-快速开始)
- [API接口概览](#-api接口概览)
- [配置说明](#-配置说明)
- [项目特色](#-项目特色)
- [后续规划](#-后续规划)
- [贡献指南](#-贡献指南)
- [许可证](#-许可证)

---

## 🎯 核心功能

### 1. 用户认证系统
- 注册、登录、登出（JWT Token）
- BCrypt 密码加密
- **单点登录互踢机制**（后登录踢前登录）
- 登录失败限流（5次错误锁定15分钟）
- Token Redis 缓存校验

### 2. 用户管理
- 个人资料查询与修改
- 头像上传（UUID命名，类型分目录）
- 用户搜索（用户名/昵称模糊搜索，限20条）
- 最后登录时间记录

### 3. 好友系统
- 发送/处理好友申请（同意/拒绝，防重复）
- 好友列表（含详细信息）
- 好友备注
- 删除好友（双向删除，清理关联会话）

### 4. 群组聊天
- 创建群组（批量邀请成员，群主自动设为管理员）
- 群列表与群详情（含成员信息）
- 邀请/移除群成员（权限控制：群主/管理员）
- 退出群聊 / 解散群组（群主专属）
- 群成员数量自动统计

### 5. 实时消息系统
- **单聊 & 群聊** 消息发送
- 支持6种消息类型：文本、图片、文件、语音、系统消息、视频
- WebSocket + STOMP 实时推送
- 消息持久化到 MySQL（分页查询，默认20条/页）
- 消息撤回（软标记 `isRecalled`）与逻辑删除（`isDeleted`）
- 业务级消息ID：`MSG` + 时间戳 + 随机数
- 注解驱动推送：`@PushMessage`

### 6. 会话管理
- 会话列表（单聊+群聊，显示最后一条消息、时间、未读数）
- 会话置顶功能（`isTop`，按置顶 & 最新消息时间排序）
- 自动创建/更新会话

### 7. 文件上传系统
- 支持头像、图片、语音、视频、文件、封面上传
- UUID 文件名，按类型分目录存储
- 单文件≤10MB，请求≤50MB
- 静态资源访问映射

### 8. 在线状态管理
- WebSocket 连接/断开时自动记录上下线
- 查询用户在线状态 / 获取所有在线用户列表（Redis Hash）

### 9. 操作日志系统
- AOP 切面自动记录（`@OperationLog`）
- 记录用户、模块、操作描述、URI、参数、IP、User-Agent、耗时、成功/失败、错误信息
- 异步保存到数据库

### 10. 安全与权限
- JWT 认证（`@RequireLogin` 注解）
- Token 过期校验 + Redis Token 缓存
- WebSocket 握手拦截器认证
- 统一异常处理与响应格式
- CORS 跨域配置

---

## 🧰 技术栈

| 类别               | 技术选型                                                        |
|-------------------|----------------------------------------------------------------|
| **核心框架**       | Spring Boot 2.6.13 (Web, WebSocket, Data-Redis, Cache, AOP, Validation) |
| **ORM**           | MyBatis-Plus 3.5.5（自动CRUD，Lambda查询，分页，逻辑删除）        |
| **数据库**         | MySQL 8.0                                                       |
| **缓存**          | Redis + Lettuce 连接池（最大活跃8，最大空闲8，最小空闲0）         |
| **安全认证**       | JWT (jjwt 0.12.x) + Spring Security Crypto (BCrypt)             |
| **消息协议**       | WebSocket + STOMP                                                |
| **工具库**         | Lombok, Apache Commons Lang3, Jackson, SLF4J+Logback            |
| **构建工具**       | Maven 3.6+ (Java 1.8)                                           |

---

## 🏗️ 架构设计

### 分层架构
```
Controller → Service → Mapper → Database
↓          ↓         ↓
DTO       Entity    XML
↓          ↓
VO        Utils
```

### AOP 切面应用
- `LoginAspect`：统一登录验证（基于 `@RequireLogin`）
- `OperationLogAspect`：自动记录操作日志（基于 `@OperationLog`）
- `PushMessageAspect`：消息推送拦截（基于 `@PushMessage`）

### WebSocket 架构流程
```
握手阶段: HandshakeInterceptor (验证Token，注入Principal)
↓
连接建立: CustomHandshakeHandler (绑定用户)
↓
事件监听: WebSocketEventListener (上线/下线，更新Redis)
↓
消息推送: SimpMessagingTemplate (点对点 / 广播)
```

### Redis 应用场景
- Token 缓存（单点登录互踢）
- 登录失败计数（限流）
- 在线用户状态（Hash）
- 会话临时数据

---

## 🗄️ 数据库设计

| 表名               | 说明               | 预估记录数         |
|-------------------|--------------------|--------------------|
| `user`            | 用户表             | 千 ~ 万级          |
| `friend`          | 好友关系表         | 万 ~ 十万级        |
| `friend_request`  | 好友申请表         | 万级               |
| `group`           | 群组表             | 千 ~ 万级          |
| `group_member`    | 群成员表           | 万 ~ 十万级        |
| `message`         | 消息记录表         | 百万 ~ 千万级      |
| `user_session`    | 会话列表表         | 万 ~ 十万级        |
| `sys_operation_log`| 操作日志表        | 百万级             |

> 注：完整建表语句请参考项目中的 `docs/schema.sql`。

---

## 🚀 快速开始

### 前置条件
- JDK 1.8+
- Maven 3.6+
- MySQL 8.0+
- Redis 6.0+

### 1. 克隆项目
```bash
git clone https://github.com/your-company/webchat-backend.git
cd webchat-backend
```

### 2. 导入数据库
```bash
# 创建数据库
CREATE DATABASE webchat CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 执行建表脚本
mysql -u root -p webchat < docs/schema.sql
```

### 3. 修改配置文件
编辑 `src/main/resources/application-dev.yml`：
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/webchat?useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: your_password
  redis:
    host: localhost
    port: 6379
    password: your_redis_password
jwt:
  secret: your_jwt_secret_key
  expire: 86400000   # 24小时
```

### 4. 编译运行
```bash
mvn clean package
java -jar target/webchat-1.0.0.jar --spring.profiles.active=dev
```

### 5. 访问测试
- WebSocket 端点：`ws://localhost:8080/ws`
- REST API 根路径：`http://localhost:8080/api`
- 健康检查：`GET /actuator/health`

---

## 📡 API 接口概览

| 模块     | 方法 | 端点                                   | 说明                |
|----------|------|----------------------------------------|---------------------|
| 认证     | POST | `/api/auth/register`                   | 用户注册            |
|          | POST | `/api/auth/login`                      | 用户登录            |
|          | POST | `/api/auth/logout`                     | 用户登出            |
| 用户     | GET  | `/api/user/info`                       | 获取当前用户信息     |
|          | GET  | `/api/user/search`                     | 搜索用户            |
|          | PUT  | `/api/user/avatar`                     | 更新头像            |
| 好友     | POST | `/api/friend/request`                  | 发送好友申请        |
|          | PUT  | `/api/friend/request/handle`           | 处理申请（同意/拒绝）|
|          | GET  | `/api/friend/list`                     | 获取好友列表        |
|          | DELETE| `/api/friend/delete/{friendId}`        | 删除好友            |
| 群组     | POST | `/api/group/create`                    | 创建群组            |
|          | GET  | `/api/group/list`                      | 我的群聊列表        |
|          | GET  | `/api/group/detail/{groupId}`          | 群详情              |
|          | POST | `/api/group/invite`                    | 邀请群成员          |
|          | DELETE| `/api/group/member/remove`             | 移除群成员          |
| 会话     | GET  | `/api/session/list`                    | 会话列表            |
| 消息     | GET  | `/api/message/history`                 | 分页历史消息        |
|          | POST | `/api/message/recall/{messageId}`      | 撤回消息            |
| 上传     | POST | `/api/upload/avatar`                   | 上传头像            |
|          | POST | `/api/upload/image`                    | 上传图片            |
|          | POST | `/api/upload/file`                     | 上传文件            |
|          | ...  | ...                                    | 语音、视频、封面    |

> 详细 API 文档请参考项目中的 `docs/api-doc.md` 或导入 Postman Collection。

---

## ⚙️ 配置说明

| 配置项                          | 说明                         | 默认值               |
|--------------------------------|------------------------------|----------------------|
| `jwt.secret`                   | JWT 签名密钥                 | 必填                 |
| `jwt.expire`                   | Token 有效期（毫秒）         | `86400000` (24h)     |
| `login.max-fail-attempts`      | 最大连续失败次数             | `5`                  |
| `login.lock-duration`          | 锁定时间（分钟）             | `15`                 |
| `file.upload.max-file-size`    | 单文件最大大小               | `10MB`               |
| `file.upload.max-request-size` | 请求最大大小                 | `50MB`               |
| `redis.lettuce.pool.max-active`| Redis 连接池最大活跃连接     | `8`                  |

---

## ✨ 项目特色

- **完整的IM闭环**：覆盖单聊、群聊、文件、好友、群管理等核心场景。
- **企业级安全**：JWT + BCrypt + Redis Token缓存 + 单点登录互踢 + 限流防护。
- **高性能设计**：Redis缓存热点数据，MyBatis-Plus分页查询，WebSocket异步推送。
- **高可维护性**：AOP解耦业务与横切逻辑，注解驱动开发，统一异常处理。
- **生产就绪**：操作日志全记录，错误追踪，在线状态监控。
- **可扩展性**：分层清晰，接口设计遵循RESTful，易于二次开发。

---

## 📅 后续规划

- [ ] 消息端到端加密（E2EE）
- [ ] 离线消息推送（APNs / FCM）
- [ ] 语音/视频通话（WebRTC）
- [ ] 多端同步（桌面、移动端）
- [ ] 分布式部署支持（基于Redis Pub/Sub的消息路由）
- [ ] 消息已读回执与正在输入状态
- [ ] 开放API与Webhook事件

---

## 🤝 贡献指南

欢迎提交Issue和Pull Request。请确保：
1. 代码符合 Google Java Style Guide
2. 所有测试通过：`mvn test`
3. 提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/)

---

## 🎉 项目在线体验

欢迎访问 WebChat 即时通讯系统的在线演示地址：  
👉 **[http://112.124.63.30:8002](http://112.124.63.30:8002)**

### 体验说明
- 你可以**注册新账号**，或使用测试账号快速登录：
    - 账号：`zhangsan`
    - 密码：`123456a`
- 登录后即可体验：
    - 单聊/群聊实时消息
    - 语音录制与发送
    - 图片/文件上传
    - 朋友圈动态发布与互动
    - 好友管理等功能

> 请注意：演示环境仅供功能体验，数据可能会定期清理。如有任何问题或建议，欢迎提交 Issue。

---

## 📄 许可证

[MIT License](LICENSE) © 2025 WebChat Contributors

---

> 💡 **提示**：生产环境部署前请务必修改默认密钥、数据库密码，并启用HTTPS+WSS。