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. 克隆项目
git clone <repository-url>
cd nl-im-service
2. 安装Go依赖
go mod download
3. 配置数据库
3.1 创建MySQL数据库
CREATE DATABASE nl_im_plus CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
3.2 导入默认用户数据（可选）
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 文件，配置以下内容：
# 数据库配置
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. 创建上传目录
mkdir -p uploads/images
mkdir -p uploads/videos
7. 启动服务
# 方式1: 直接运行
go run cmd/server/main.go
# 方式2: 编译后运行
go build -o server.exe cmd/server/main.go
./server.exe
8. 验证服务
访问健康检查接口：
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接口统一返回以下格式：
{
"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跨域支持
许可证
[根据实际情况填写]
联系方式
[根据实际情况填写]