405 lines
12 KiB
Markdown
405 lines
12 KiB
Markdown
# IM系统后端服务
|
||
|
||
## 项目简介
|
||
|
||
IM系统后端服务是一个基于Go语言开发的即时通讯系统后端，提供用户认证、好友管理、实时聊天、音视频通话、文件上传等完整的IM功能。
|
||
|
||
## 技术栈
|
||
|
||
### 核心框架
|
||
- **Go 1.24.1** - 编程语言
|
||
- **Gin v1.11.0** - HTTP Web框架
|
||
- **GORM v1.31.1** - ORM数据库操作框架
|
||
- **MySQL** - 关系型数据库
|
||
- **Redis v8.11.5** - 缓存和消息队列
|
||
|
||
### 实时通信
|
||
- **Gorilla WebSocket v1.5.3** - WebSocket通信
|
||
- **Pion TURN/STUN v2.1.6** - WebRTC中继服务器
|
||
|
||
### 认证与安全
|
||
- **JWT v5.3.0** - JSON Web Token认证
|
||
- **bcrypt** - 密码加密
|
||
|
||
### 工具库
|
||
- **Viper v1.21.0** - 配置管理
|
||
- **Ants v2.11.3** - 协程池管理
|
||
- **golang.org/x/crypto** - 加密工具
|
||
|
||
## 开发环境要求
|
||
|
||
- Go 1.24.1 或更高版本
|
||
- MySQL 5.7+ 或 MySQL 8.0+
|
||
- Redis 6.0+
|
||
- Git
|
||
|
||
## 从拉取到本地开发的步骤
|
||
|
||
### 1. 克隆项目
|
||
|
||
```bash
|
||
git clone <repository-url>
|
||
cd nl-im-service
|
||
```
|
||
|
||
### 2. 安装Go依赖
|
||
|
||
```bash
|
||
go mod download
|
||
```
|
||
|
||
### 3. 配置数据库
|
||
|
||
#### 3.1 创建MySQL数据库
|
||
|
||
```sql
|
||
CREATE DATABASE nl_im_plus CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||
```
|
||
|
||
#### 3.2 导入默认用户数据（可选）
|
||
|
||
```bash
|
||
mysql -u root -p nl_im_plus < 添加默认用户信息.sql
|
||
```
|
||
|
||
默认用户信息：
|
||
- 用户ID: 10001-10020
|
||
- 默认密码: `12345678`
|
||
- 邮箱格式: user001@example.com - user020@example.com
|
||
- 手机号格式: 13800138001 - 13800138020
|
||
|
||
### 4. 配置Redis
|
||
|
||
确保Redis服务已启动，默认配置：
|
||
- 地址: localhost:6379
|
||
- 密码: 无（或根据实际情况配置）
|
||
|
||
### 5. 配置文件设置
|
||
|
||
编辑 `configs/config.yaml` 文件，配置以下内容：
|
||
|
||
```yaml
|
||
# 数据库配置
|
||
database:
|
||
dsn: "root:password@tcp(localhost:3306)/nl_im_plus?charset=utf8mb4&parseTime=True&loc=Local"
|
||
|
||
# Redis配置
|
||
redis:
|
||
addr: "localhost:6379"
|
||
password: "" # 如果有密码则填写
|
||
db: 0
|
||
|
||
# JWT配置
|
||
jwt:
|
||
secret: "your-jwt-secret-key" # 生产环境请使用强随机密钥
|
||
|
||
# 应用配置
|
||
app:
|
||
port: "12080" # 服务端口
|
||
node_id: "node-01" # 节点ID（集群模式下必须唯一）
|
||
|
||
# 雪花ID配置（可选）
|
||
snowflake:
|
||
datacenter_id: 1 # 数据中心ID (0-31)
|
||
machine_id: 1 # 机器ID (0-31)
|
||
|
||
# TURN服务器配置（WebRTC）
|
||
turn:
|
||
enabled: true
|
||
public_ip: "your-public-ip" # 公网IP
|
||
listen_port: 3478
|
||
shared_secret: "your-shared-secret"
|
||
```
|
||
|
||
### 6. 创建上传目录
|
||
|
||
```bash
|
||
mkdir -p uploads/images
|
||
mkdir -p uploads/videos
|
||
```
|
||
|
||
### 7. 启动服务
|
||
|
||
```bash
|
||
# 方式1: 直接运行
|
||
go run cmd/server/main.go
|
||
|
||
# 方式2: 编译后运行
|
||
go build -o server.exe cmd/server/main.go
|
||
./server.exe
|
||
```
|
||
|
||
### 8. 验证服务
|
||
|
||
访问健康检查接口：
|
||
```bash
|
||
curl http://localhost:12080/api/health
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
nl-im-service/
|
||
├── cmd/ # 应用程序入口
|
||
│ └── server/
|
||
│ ├── main.go # 主程序入口，初始化所有服务并启动HTTP服务器
|
||
│ ├── build.bat # Windows构建脚本
|
||
│ └── dist/ # 编译后的可执行文件目录
|
||
│
|
||
├── configs/ # 配置文件目录
|
||
│ └── config.yaml # 应用配置文件（数据库、Redis、JWT等配置）
|
||
│
|
||
├── internal/ # 内部代码目录（不对外暴露）
|
||
│ ├── api/ # API处理器层（HTTP请求处理）
|
||
│ │ ├── auth_handler.go # 认证相关API（登录、注册、验证码）
|
||
│ │ ├── user_handler.go # 用户管理API（用户信息、用户列表）
|
||
│ │ ├── contact_handler.go # 联系人管理API（好友、分组、好友申请）
|
||
│ │ ├── room_handler.go # 房间管理API（创建房间、获取房间信息）
|
||
│ │ ├── handler.go # 消息和系统API（发送消息、历史消息、健康检查）
|
||
│ │ └── attachment_handler.go # 附件管理API（上传、下载、删除附件）
|
||
│ │
|
||
│ ├── service/ # 业务服务层（核心业务逻辑）
|
||
│ │ ├── auth_service.go # 认证服务（登录、注册、验证码生成和验证）
|
||
│ │ ├── user_service.go # 用户服务（用户CRUD操作）
|
||
│ │ ├── contact_service.go # 联系人服务（好友管理、分组管理、好友申请处理）
|
||
│ │ ├── room_service.go # 房间服务（房间创建、房间ID生成）
|
||
│ │ ├── chat_service.go # 聊天服务（消息处理、WebSocket分发、Redis集群消息）
|
||
│ │ ├── attachment_service.go # 附件服务（文件上传、存储、验证）
|
||
│ │ └── login_log_service.go # 登录日志服务（记录登录历史）
|
||
│ │
|
||
│ ├── model/ # 数据模型层（数据库实体和DTO）
|
||
│ │ ├── types.go # 数据模型定义（User、ChatMessage、Contact等）
|
||
│ │ └── response.go # 响应模型定义（统一API响应格式）
|
||
│ │
|
||
│ ├── middleware/ # 中间件层（请求处理中间件）
|
||
│ │ ├── auth.go # JWT认证中间件（Token验证、用户信息注入）
|
||
│ │ ├── response.go # 响应时间中间件（记录请求开始时间）
|
||
│ │ └── request_log.go # 请求日志中间件（记录所有API请求信息）
|
||
│ │
|
||
│ ├── utils/ # 工具函数层（通用工具）
|
||
│ │ ├── jwt.go # JWT工具（Token生成、解析、验证）
|
||
│ │ ├── password.go # 密码工具（密码加密、验证）
|
||
│ │ ├── response.go # 响应工具（统一响应格式、错误处理）
|
||
│ │ ├── snowflake.go # 雪花ID生成器（全局唯一ID生成）
|
||
│ │ └── ip_location.go # IP归属地查询工具（查询IP地理位置）
|
||
│ │
|
||
│ ├── manager/ # 连接管理器
|
||
│ │ └── client_manager.go # WebSocket客户端管理器（连接注册、注销、消息广播）
|
||
│ │
|
||
│ ├── turnserver/ # TURN服务器
|
||
│ │ └── server.go # TURN/STUN服务器（WebRTC中继服务）
|
||
│ │
|
||
│ └── ws/ # WebSocket工作池
|
||
│ └── worker.go # WebSocket消息处理工作池（异步处理WebSocket消息）
|
||
│
|
||
├── uploads/ # 文件上传目录
|
||
│ ├── images/ # 图片存储目录
|
||
│ └── videos/ # 视频存储目录
|
||
│
|
||
├── go.mod # Go模块定义文件
|
||
├── go.sum # Go依赖校验文件
|
||
├── IM_API_Collection.postman_collection.json # Postman API测试集合
|
||
├── 添加默认用户信息.sql # 默认用户数据SQL脚本
|
||
└── README.md # 项目说明文档（本文件）
|
||
```
|
||
|
||
## 核心功能模块
|
||
|
||
### 1. 用户认证模块
|
||
- 用户注册（邮箱/手机号 + 密码）
|
||
- 用户登录（账号 + 密码）
|
||
- JWT Token生成和验证
|
||
- 邮箱/短信验证码发送和验证
|
||
- 登录日志记录
|
||
|
||
### 2. 用户管理模块
|
||
- 用户信息查询和更新
|
||
- 用户列表查询（分页）
|
||
- 用户创建和删除（管理员功能）
|
||
|
||
### 3. 联系人管理模块
|
||
- 好友搜索
|
||
- 添加好友（发送好友申请）
|
||
- 好友申请处理（接受/拒绝）
|
||
- 好友列表查询
|
||
- 好友信息更新（备注、分组、置顶、免打扰）
|
||
- 联系人分组管理（创建、更新、删除）
|
||
|
||
### 4. 房间管理模块
|
||
- 创建聊天房间（P2P/群聊）
|
||
- 获取房间信息
|
||
- 房间ID生成（P2P使用用户ID组合，群聊使用雪花ID）
|
||
|
||
### 5. 消息管理模块
|
||
- 发送消息（文本、图片、音频、视频、文件等）
|
||
- 获取历史消息（分页）
|
||
- WebSocket实时消息推送
|
||
- 消息持久化存储
|
||
|
||
### 6. 附件管理模块
|
||
- 文件上传（图片最大10MB，视频最大500MB）
|
||
- 文件信息查询
|
||
- 文件列表查询（分页）
|
||
- 文件删除
|
||
|
||
### 7. WebRTC音视频通话
|
||
- TURN/STUN服务器配置
|
||
- ICE服务器信息获取
|
||
- 音视频通话信令处理
|
||
|
||
### 8. 日志系统
|
||
- 接口请求日志（记录所有API请求）
|
||
- 登录日志（记录所有登录尝试）
|
||
- IP归属地查询
|
||
|
||
## API接口文档
|
||
|
||
### 统一响应格式
|
||
|
||
所有API接口统一返回以下格式：
|
||
|
||
```json
|
||
{
|
||
"code": 0, // 业务状态码：0=成功，非0=失败
|
||
"message": "获取成功", // 响应消息
|
||
"result": {}, // 响应数据
|
||
"type": "success", // 响应类型："success"或"error"
|
||
"interface_info": {
|
||
"result_time": "22 ms", // 响应时间
|
||
"ecs": "localhost" // 服务器标识
|
||
}
|
||
}
|
||
```
|
||
|
||
**重要说明：**
|
||
- 所有接口统一返回HTTP 200状态码
|
||
- 错误通过响应体中的`code`字段标识
|
||
- 业务状态码：0=成功，400=参数错误，401=未认证，404=资源不存在，500=服务器错误
|
||
|
||
### 请求方式
|
||
|
||
- 只支持 **GET** 和 **POST** 两种请求方式
|
||
- 更新操作使用 `POST /api/xxx/update/:id`
|
||
- 删除操作使用 `POST /api/xxx/delete/:id`
|
||
|
||
### Postman测试集合
|
||
|
||
项目根目录提供了 `IM_API_Collection.postman_collection.json` 文件，可以直接导入到Postman中使用。
|
||
|
||
包含的接口：
|
||
- 认证模块（登录、注册、验证码）
|
||
- 用户管理
|
||
- 联系人管理
|
||
- 房间管理
|
||
- 消息管理
|
||
- 附件管理
|
||
- 系统接口
|
||
|
||
## 数据库表结构
|
||
|
||
### 核心表
|
||
- `users` - 用户基本信息表
|
||
- `user_contacts` - 用户联系人表（好友关系）
|
||
- `contact_groups` - 联系人分组表
|
||
- `chat_rooms` - 聊天房间表
|
||
- `chat_messages` - 聊天消息表
|
||
- `friend_requests` - 好友申请表
|
||
- `verification_codes` - 验证码表
|
||
- `attachments` - 附件表
|
||
|
||
### 日志表
|
||
- `api_request_logs` - 接口请求日志表
|
||
- `login_logs` - 登录日志表
|
||
|
||
## 配置说明
|
||
|
||
### 数据库配置
|
||
- 支持MySQL 5.7+和MySQL 8.0+
|
||
- 字符集：utf8mb4
|
||
- 时区：Local
|
||
|
||
### Redis配置
|
||
- 用于缓存用户在线状态
|
||
- 用于集群消息广播
|
||
- 用于存储用户路由信息
|
||
|
||
### JWT配置
|
||
- Token过期时间：7天（可在代码中修改）
|
||
- 签名算法：HS256
|
||
|
||
### 雪花ID配置
|
||
- 数据中心ID：0-31
|
||
- 机器ID：0-31
|
||
- 用于生成全局唯一的群聊房间ID
|
||
|
||
### TURN服务器配置
|
||
- 用于WebRTC音视频通话的中继服务
|
||
- 需要配置公网IP
|
||
- 默认端口：3478
|
||
|
||
## 开发注意事项
|
||
|
||
### 1. 代码规范
|
||
- 所有代码都有详细的中文注释
|
||
- 遵循Go语言代码规范
|
||
- 使用统一的错误处理方式
|
||
|
||
### 2. 数据库操作
|
||
- 使用GORM进行数据库操作
|
||
- 所有表都有中文注释
|
||
- 支持自动数据库迁移
|
||
|
||
### 3. 日志记录
|
||
- 本地IP的请求不会记录到日志
|
||
- 接口请求日志异步写入，不影响性能
|
||
- 登录日志记录所有登录尝试（成功和失败）
|
||
|
||
### 4. 文件上传
|
||
- 图片限制：10MB
|
||
- 视频限制：500MB
|
||
- 文件存储在 `uploads` 目录
|
||
|
||
### 5. 列表返回
|
||
- 所有列表接口在数据为空时返回空数组 `[]`，而不是 `null`
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 数据库连接失败
|
||
**A:** 检查 `configs/config.yaml` 中的数据库配置，确保数据库服务已启动，用户名密码正确。
|
||
|
||
### Q2: Redis连接失败
|
||
**A:** 检查Redis服务是否启动，配置中的地址和密码是否正确。
|
||
|
||
### Q3: 端口被占用
|
||
**A:** 修改 `configs/config.yaml` 中的 `app.port` 配置，或关闭占用端口的程序。
|
||
|
||
### Q4: Token验证失败
|
||
**A:** 检查JWT配置中的secret是否正确，Token是否过期。
|
||
|
||
### Q5: 文件上传失败
|
||
**A:** 检查 `uploads` 目录是否存在且有写入权限，文件大小是否超过限制。
|
||
|
||
## 项目特性
|
||
|
||
- ✅ 统一的API响应格式
|
||
- ✅ JWT身份认证
|
||
- ✅ WebSocket实时通信
|
||
- ✅ WebRTC音视频通话支持
|
||
- ✅ 完整的日志系统（请求日志、登录日志）
|
||
- ✅ IP归属地查询
|
||
- ✅ 雪花ID全局唯一ID生成
|
||
- ✅ 文件上传和管理
|
||
- ✅ 好友管理和分组
|
||
- ✅ 消息持久化存储
|
||
- ✅ 分页查询支持
|
||
- ✅ CORS跨域支持
|
||
|
||
## 许可证
|
||
|
||
[根据实际情况填写]
|
||
|
||
## 联系方式
|
||
|
||
[根据实际情况填写]
|
||
|