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

许可证

[根据实际情况填写]

联系方式

[根据实际情况填写]