BeeLinkIM 是一个使用 Go 语言 编写的分布式实时聊天服务器，支持水平扩展。它提供 WebSocket 长连接通信，具备一对一私聊、消息持久化、集群消息路由等核心能力，可作为即时通讯（IM）系统的后端服务。
- 💬 一对一实时聊天 —— 基于 WebSocket 长连接，毫秒级消息推送
- 🔐 JWT 认证鉴权 —— HS256 签名，支持 Header 和 Query 两种传参方式
- 🌐 分布式集群支持 —— 多节点部署，通过 Redis + RocketMQ 实现跨服务器消息路由
- 📦 消息持久化 —— MySQL 存储聊天记录，GORM 自动建表
- ⚡ Redis 缓存加速 —— 房间会话缓存、消息序列号、分布式锁
- 🔄 消息有序性保证 —— Redis 原子自增序列号，消息去重与排序
- ❤️ 心跳保活机制 —— Ping/Pong 心跳检测，自动清理死连接
- 🛡️ 优雅关闭 —— 监听系统信号，等待现有请求处理完毕后安全退出
| 层级 | 技术 |
|---|---|
| 语言 | Go 1.25 |
| HTTP 框架 | Gin |
| WebSocket | gorilla/websocket |
| ORM | GORM + MySQL 8.0 |
| 缓存 / 锁 | go-redis + redislock |
| 消息队列 | Apache RocketMQ |
| 配置管理 | Viper |
| 日志 | Zap + lumberjack |
| 认证 | golang-jwt |
| 容器化 | Docker + Docker Compose |
┌─────────────────────────────────────────────┐
│ 客户端 (WebSocket / HTTP) │
└───────────┬─────────────────────────────────┘
│
┌─────▼──────┐
│ Gin 路由 │ ← CORS / JWT鉴权 / 在线统计
└─────┬──────┘
│
┌─────▼──────┐
│ 业务服务层 │ ← 聊天核心逻辑、消息分发
└─────┬──────┘
│
┌────────┼────────┐
│ │ │
┌──▼──┐ ┌──▼──┐ ┌───▼───┐
│MySQL│ │Redis│ │RocketMQ│
└─────┘ └─────┘ └───────┘
发送者 ──WebSocket──▶ 服务端
│
① 获取/创建房间会话 (Redis/MySQL)
② 原子自增序列号 (Redis HIncrBy)
③ 异步持久化消息 (MySQL)
④ 路由分发：
│
本地用户？───┼─── 跨服务器？
│ │
Hub直接推送 RocketMQ 发布
│
目标服务器消费
│
Hub推送给本地用户
BeeLinkIM/
├── cmd/
│ └── chat-server/main.go # 服务入口，依赖注入与启动编排
├── configs/
│ └── config.yaml # 应用配置文件
├── internal/
│ ├── api/ # WebSocket 协议升级器
│ ├── dto/ # 统一响应结构体
│ ├── handler/ # HTTP 处理器（健康检查/登录/搜索/上传/在线数）
│ ├── middleware/ # 中间件（JWT鉴权/CORS/在线统计）
│ ├── mq/ # RocketMQ 生产者管理
│ ├── repository/
│ │ ├── mysqlx/ # MySQL 数据访问（房间/消息）
│ │ └── redisx/ # Redis 数据访问（会话缓存/锁/序列号/用户路由）
│ ├── router/ # Gin 路由注册
│ ├── service/ # 核心业务层（WebSocket生命周期/消息发送/MQ消费）
│ └── ws/ # WebSocket Hub + Client（连接管理）
├── pkg/
│ ├── config/ # Viper 配置加载
│ ├── errorx/ # 自定义错误码
│ ├── jwt/ # JWT 生成/解析
│ └── logger/ # Zap 日志初始化
├── Dockerfile # 多阶段 Docker 构建
├── docker-compose.yml # 一键部署（MySQL + Redis + RocketMQ + App）
├── go.mod / go.sum # Go 模块依赖
└── LICENSE
- Go 1.25+
- MySQL 8.0+
- Redis 7+
- RocketMQ 5.x（NameServer + Broker）
1. 克隆项目
git clone https://github.com/your-org/BeeLinkIM.git
cd BeeLinkIM2. 修改配置
编辑 configs/config.yaml，填写你的数据库、缓存、消息队列连接信息：
server:
port: 8080
mode: debug
mysql:
dsn: "root:yourpassword@tcp(127.0.0.1:3306)/chat_db?charset=utf8mb4&parseTime=True&loc=Local"
redis:
addr: "127.0.0.1:6379"
password: ""
rocketmq:
name_server: "127.0.0.1:9876"
app:
server_id: "server-01"
jwt_secret: "your-jwt-secret-key"3. 编译并启动
go mod tidy
go build -o chat-server ./cmd/chat-server
./chat-serverdocker-compose up -d这将自动启动 MySQL、Redis、RocketMQ NameServer/Broker 以及聊天服务。
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/health |
健康检查 |
GET |
/online |
获取在线人数 |
POST |
/login |
用户登录 |
POST |
/upload |
文件上传 |
GET |
/search |
搜索接口 |
GET |
/api/v1/hello |
测试接口 |
| 方法 | 路径 | 认证方式 | 说明 |
|---|---|---|---|
GET |
/chat/ws |
JWT（Header 或 Query） | 建立 WebSocket 长连接 |
客户端发送：
{
"to_uid": 1002,
"content": "你好！"
}服务端推送：
{
"from_uid": 1001,
"to_uid": 1002,
"content": "你好！",
"sequence": 42
}采用 JWT（HS256 对称加密），Token 有效期 7 天。支持两种传参方式：
- HTTP Header（推荐用于 REST API）：
Authorization: Bearer <your-token> - Query 参数（用于 WebSocket，浏览器无法自定义 Header）：
/chat/ws?token=<your-token>
| 字段 | 类型 | 说明 |
|---|---|---|
| id | BIGINT | 主键自增 |
| uid1 | BIGINT | 较小的用户ID（唯一索引） |
| uid2 | BIGINT | 较大的用户ID（唯一索引） |
| 字段 | 类型 | 说明 |
|---|---|---|
| id | BIGINT | 主键自增 |
| room_id | BIGINT | 房间ID（索引） |
| from_uid | BIGINT | 发送者ID（索引） |
| to_uid | BIGINT | 接收者ID（索引） |
| content | TEXT | 消息内容 |
| sequence | BIGINT | 房间内唯一序号（唯一索引） |
| 错误码 | 说明 |
|---|---|
| 0 | 成功 |
| 1000 | 服务器错误 |
| 1001 | 参数错误 |
| 1002 | 未授权/未登录 |
| 1003 | 无权限 |
| 2001 | 房间不存在 |
| 2002 | 消息发送失败 |
| 2003 | 分布式锁获取失败 |
| 2004 | 用户不在线 |
MIT © 2026 CanWeakerWriteStrongCode