diff --git a/README.md b/README.md new file mode 100644 index 0000000..f90ce78 --- /dev/null +++ b/README.md @@ -0,0 +1,404 @@ +# 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 +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跨域支持 + +## 许可证 + +[根据实际情况填写] + +## 联系方式 + +[根据实际情况填写] +