nl-im-service/README.md

# 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跨域支持

## 许可证

[根据实际情况填写]

## 联系方式

[根据实际情况填写]