# echo-im
**Repository Path**: Austin_00/echo-im
## Basic Information
- **Project Name**: echo-im
- **Description**: 一个IM（即时通讯）项目的后端系统。支持IM系统核心功能：好友、私聊、群聊、离线消息、发送语音、图片、文件、emoji表情、回执消息、视频聊天等
严格遵循IM系统的四大原则：实时性、幂等性、不丢失、时序性。
主要基于 Spring Boot 和 Netty 开发
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://gitee.com/brother-one/echo-im
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 40
- **Created**: 2025-12-12
- **Last Updated**: 2025-12-12
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
Echo IM 1.2.0
基于 SpringBoot + Netty 的高性能即时通讯系统
---
## 📋 项目简介
Echo IM 是一个**生产级**即时通讯系统，采用微服务架构 + DDD 领域驱动设计，严格遵循 IM 四大核心原则（实时性、不丢失、幂等性、时序性）。
**核心亮点**：
- ✅ 多消息中间件架构（RabbitMQ/Redis/RocketMQ可切换）
- ✅ 去中心化消息推送，无单点故障
- ✅ 离线消息双重存储（Redis + MySQL）
- ✅ 应用层 ACK 机制 + MQ 任务补偿
- ✅ Flyway 数据库版本管理
- ✅ Vue3 + TypeScript 前端
**适用场景**：IM 系统学习、毕设项目、简历加分、二次开发
---
## 🚀 快速开始
### 环境要求
| 组件 | 版本 |
|------|------|
| JDK | 17+ |
| Maven | 3.6+ |
| MySQL | 8.0+ |
| Redis | 6.0+ |
| RabbitMQ | 3.x (可选 Redis/RocketMQ) |
| Nginx | 最新版 (生产环境必需) |
### Docker Compose 一键启动
```bash
cd doc/dev-ops
docker-compose -f docker-compose-enviroment.yml up -d
```
启动后服务：
- MySQL: `localhost:3306` (root/test123456)
- Redis: `localhost:6379`
- RabbitMQ: `localhost:5672` (guest/guest)
- RabbitMQ 管理界面: http://localhost:15672
### 配置说明
**1. 数据库初始化**
v1.2.0 使用 Flyway 自动迁移，首次启动会自动创建所有表结构和索引。
**2. 核心配置（application-dev.yml）**
```yaml
spring:
datasource:
url: jdbc:mysql://localhost:3306/echo_im
username: root
password: test123456
data:
redis:
host: 127.0.0.1
port: 6379
rabbitmq:
host: 127.0.0.1
port: 5672
username: guest
password: guest
# 消息中间件选择（rabbitmq/redis/rocketmq/load-balanced）
im:
message-broker:
type: rabbitmq # 开发环境推荐单一中间件
```
### 启动服务
**开发环境（IDEA）**：
```
1. im-engin-server -> ImEnginServerApplication
2. im-platform-server -> ImPlatformServerApplication
3. im-storage-server -> ImStorageServerApplication
```
**生产环境（JAR）**：
```bash
# 打包
mvn clean package -DskipTests
# 启动
nohup java -jar im-engin-server/target/im-engin-server.jar &
nohup java -jar im-platform-server/target/im-platform-server.jar &
nohup java -jar im-storage-server/target/im-storage-server.jar &
```
### Nginx 负载均衡配置
**为什么需要 Nginx？**
前端需要连接 WebSocket，多个 im-engin-server 实例时需要 Nginx 做负载均衡。
**配置示例**：
```nginx
# WebSocket 负载均衡（ip_hash 保持会话一致性）
upstream websocket_backend {
ip_hash;
server 127.0.0.1:9091;
server 127.0.0.1:9092;
server 127.0.0.1:9093;
}
# HTTP API 负载均衡
upstream api_backend {
server 127.0.0.1:8080;
server 127.0.0.1:8180;
}
server {
listen 80;
server_name im.example.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";
}
# HTTP API 代理
location /api/ {
proxy_pass http://api_backend/;
}
}
```
**详细配置**：见 `doc/nginx/echo-im.conf`
**前端配置**：
```typescript
// 生产环境通过 Nginx
const wsUrl = 'wss://im.example.com/ws';
const apiUrl = 'https://im.example.com/api';
```
### 验证部署
```bash
# 1. 检查服务端口
lsof -i:8080,8081,9091
# 2. API 文档
curl http://localhost:8080/doc.html
# 3. 注册测试用户
curl -X POST http://localhost:8080/auth/register \
-H "Content-Type: application/json" \
-d '{"username":"test","password":"123456"}'
# 4. WebSocket 连接测试
# 浏览器访问: http://www.websocket-test.com/
# 连接地址: ws://localhost:9091/ws
```
---
## 📖 核心特性
### IM 四大原则实现
| 原则 | 实现方案 |
|------|---------|
| **实时性** | Netty NIO + WebSocket 长连接 + RabbitMQ 异步解耦 |
| **不丢失** | 应用层 ACK + 离线消息双存储 + MQ 任务补偿 |
| **幂等性** | 客户端 SEQ + 服务端 MsgId 双重保证 |
| **时序性** | 雪花算法 MsgId + SEQ 局部时序 |
### 功能清单
- ✅ **多端登录**：同一用户多终端，同终端互斥
- ✅ **消息类型**：文本、图片、语音、文件、视频、表情
- ✅ **消息功能**：离线消息、历史消息、消息撤回、已读回执
- ✅ **好友管理**：添加、删除、备注、在线状态
- ✅ **群组功能**：创建、解散、邀请、移除、@功能
- ✅ **文件存储**：MinIO 对象存储
- ✅ **多消息中间件**：RabbitMQ/Redis/RocketMQ 可切换
---
## 🔌 技术栈
### 后端
| 技术 | 版本 | 说明 |
|------|------|------|
| Spring Boot | 3.3.1 | 微服务框架 |
| Netty | - | 高性能网络框架 |
| MySQL | 8.0+ | 数据库 |
| Redis | 6.0+ | 缓存 + 用户状态 |
| RabbitMQ | 3.x | 消息队列（可切换Redis/RocketMQ） |
| Flyway | 10.10.0 | 数据库版本管理 |
| Sa-Token | 1.38.0 | 认证授权 |
| MinIO | 8.5.1 | 对象存储 |
| MyBatis-Plus | 3.5.7 | ORM 框架 |
### 前端
| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.x | 渐进式框架 |
| TypeScript | 5.x | 类型安全 |
| Vite | 5.x | 构建工具 |
| Element Plus | 2.x | UI 组件库 |
| Pinia | 2.x | 状态管理 |
---
## 🏗️ 架构设计
### 总体架构
```
┌─────────────┐
│ Nginx │ 负载均衡 + 反向代理
└──────┬──────┘
│
┌──────┴──────────────────────────────┐
│ │
│ ┌─────────────┐ ┌──────────────┐ │
│ │ im-platform │ │ im-engin │ │
│ │ (8080) │ │ (9091) │ │
│ └──────┬──────┘ └──────┬───────┘ │
│ │ │ │
│ └────────┬───────┘ │
│ │ │
│ ┌───────────────▼──────────────┐ │
│ │ RabbitMQ / Redis / RocketMQ│ │
│ └───────────────┬──────────────┘ │
│ │ │
│ ┌───────────────▼──────────────┐ │
│ │ im-storage (8082) │ │
│ └──────────────────────────────┘ │
└─────────────────────────────────────┘
│
┌──────┴──────┐
│ │
┌───▼───┐ ┌────▼────┐
│ MySQL │ │ Redis │
└───────┘ └─────────┘
```
### 消息流转
```
用户A 发消息
↓
im-platform-server (接收HTTP请求)
↓
MessageBroker (路由到对应中间件)
↓
RabbitMQ/Redis/RocketMQ
↓
im-engin-server (用户B所在服务器)
↓
WebSocket 推送给用户B
```
### 多消息中间件架构
**核心设计**：每个 im-engin-server 只连接一个中间件，im-platform-server 根据用户所在的 serverId 智能路由。
```
im-engin-server-1 → RabbitMQ
im-engin-server-2 → Redis
im-engin-server-3 → RocketMQ
im-platform-server → LoadBalancer → 选择对应的中间件发送
```
**负载均衡策略**：
- **round-robin**：轮询
- **random**：随机
- **weighted**：加权
- **hash**：哈希（推荐，保证同一serverId路由到同一中间件）
---
## 📂 项目结构
```
echo-im/
├── im-common/ # 公共模块（工具类、常量、异常）
├── im-repository/ # 仓储模块（数据持久化）
├── im-infrastructure/ # 基础设施（Redis、MQ、MinIO）
│ └── mq/ # 消息中间件抽象层
│ ├── MessageBroker.java # 统一接口
│ ├── impl/
│ │ ├── RabbitMQMessageBroker.java
│ │ ├── RedisMessageBroker.java
│ │ └── RocketMQMessageBroker.java
│ └── strategy/ # 负载均衡策略
├── im-domain/ # 领域模块（核心业务逻辑）
├── im-client-starter/ # 客户端 SDK（消息路由、用户状态）
├── im-engin-server/ # 消息引擎（Netty + WebSocket）
├── im-platform-server/ # 平台服务（HTTP API）
├── im-storage-server/ # 存储服务（异步持久化）
├── im-offline-notify-server/ # 离线通知（邮件、推送）
├── echo-im-web/ # Vue3 前端
└── doc/
├── nginx/ # Nginx 配置
├── sql/ # SQL 脚本
└── md/ # 技术文档
```
---
## 📝 技术文档
| 文档 | 说明 |
|------|------|
| [架构设计](doc/ARCHITECTURE.md) | 整体架构 + 消息流转 + 多中间件设计 |
| [Nginx配置](doc/nginx/README.md) | 负载均衡配置说明 |
| [IM核心特性](doc/md/IM核心特性.md) | 四大原则详解 |
| [ACK队列](doc/md/ACK队列技术选型.md) | ACK机制实现 |
| [CHANGELOG](CHANGELOG.md) | 版本更新日志 |
---
## 🛠️ 开发进度
### v1.2.0 (当前版本) ✅
- [x] 多消息中间件支持（RabbitMQ/Redis/RocketMQ）
- [x] 智能负载均衡（4种策略）
- [x] Flyway 数据库迁移
- [x] Vue3 前端重构
- [x] 数据库索引优化（27个索引）
- [x] BCrypt 密码加密
- [x] 全局异常处理
### v1.3.0 (规划中) 🚧
- [ ] IM 管理控制台
- [ ] 数据统计面板
- [ ] 实时监控大屏
- [ ] 消息云端审核
- [ ] 好友分组
- [ ] 黑名单功能
### v2.0.0 (未来) 🔮
- [ ] 音视频通话
- [ ] 屏幕共享
- [ ] 移动端 SDK
- [ ] Elasticsearch 消息搜索
- [ ] Kubernetes 部署
---
## 🏗️ 参与贡献
### 分支说明
| 分支 | 说明 |
|------|------|
| master | 主分支，稳定版本 |
| develop | 开发分支，接受 PR |
### 贡献步骤
1. Fork 项目到你的仓库
2. 创建特性分支：`git checkout -b feature/xxx`
3. 提交代码：`git commit -m 'Add xxx'`
4. 推送到分支：`git push origin feature/xxx`
5. 提交 Pull Request
### 提问反馈
- [Gitee Issue](https://gitee.com/brother-one/echo-im/issues)
- 微信交流群（见下方二维码）
---
## 交流合作
---
## 📜 开源协议
[MIT License](LICENSE)
---
⭐ 如果这个项目对你有帮助，请给个 Star 支持一下！⭐
Made with ❤️ by Echo IM Team
© 2024 Echo IM. All rights reserved.