JuggleIM

一个高性能、可扩展的开源 IM 即时通讯系统

A high-performance, scalable open-source instant messaging (IM) system.

简体中文 | English

如果这个项目对你有帮助，欢迎点一个 ⭐ Star 支持我们，也方便你随时找到它！

📖 什么是 JuggleIM

JuggleIM 是一套开箱即用、可私有化部署的即时通讯（IM）后端服务。基于 Protobuf + WebSocket 长连接协议，专注于消息的高效分发与可靠存储，帮助你在几分钟内为 App、网站或业务系统搭建起属于自己的聊天能力。

无论是社交产品、客服系统、IoT 设备通信，还是直播弹幕、AI 机器人对话，JuggleIM 都能作为稳定的通讯底座。它天生支持多租户，一套服务即可承载多个相互隔离的应用；专业版支持集群横向扩展，可支撑亿级日活。

想直接体验？按照下方 Docker 快速开始，几分钟内运行完整服务。

✨ 核心特性

🚀 高性能 & 高可用

Protobuf + WebSocket 长连接，低流量、高性能，弱网环境下依然保持良好连通性
专业版支持集群部署，无限横向扩展，可支撑亿级日活应用
支持万人、十万人大群沟通不丢消息，支持无上限直播聊天室

🔒 安全 & 稳定

使用租户级凭证和客户端 Token 鉴权；生产环境建议通过 HTTPS/WSS 保障传输安全
多端同时在线、消息多端同步，确保状态多端一致

🌍 灵活部署 & 全球服务

支持公有云、私有云、托管云等多种部署形态
支持全球链路加速，可服务全球级应用

🧩 易集成 & 可扩展

提供 Android、iOS、Web、PC、Flutter、鸿蒙等多平台 SDK，附带 Demo 与文档
提供丰富的 REST API 和 WebHook，方便与现有系统集成
具备 AI 机器人对接能力，可轻松对接大模型
自带运维工具和管理后台，简单好维护

🧬 项目生态

JuggleIM 采用「核心服务 + 业务服务 + 多端 SDK + Demo」的分层架构，各仓库职责清晰，可按需组合、二次开发。

仓库	说明
im-server	底层 IM 核心服务，负责消息分发、存储等 IM 相关业务（本仓库）
jugglechat-server	Demo 业务服务，负责用户注册/登录、创建群组、添加好友等业务，可在此基础上二开
jugglechat-server-java	Demo 业务服务的 Java 版本
imserver-console	IM 服务的管理后台，用于操作 IM 配置、监控业务量
imsdk-android	安卓端 imsdk，内含 UI Demo，可用于二开
imsdk-ios	iOS 端 imsdk，内含 UI Demo，可用于二开
imsdk-web	Web 端 imsdk
imsdk-flutter	imsdk 的 Flutter 版本
imsdk-harmony	鸿蒙版本 imsdk，内含 UI Demo，可用于二开
jugglechat-web	集成 imsdk-web 的 Web 版 Demo，可用于二开
jugglechat-desktop	集成 imsdk-pc 的桌面版 Demo，可用于二开
jugglelive-web	集成 imsdk-web 的聊天室场景 Demo，可用于二开
bot-connector	机器人对接服务，用于打通 im-server 与三方机器人
imserver-sdk-go	封装 im-server 服务端 API 的 SDK，供业务方集成
imserver-sdk-java	imserver-sdk 的 Java 版本

桌面端 imsdk-pc 暂未开源，可联系客服了解。

🏗 系统架构

JuggleIM 以模块化 Go 服务运行：HTTP 和 WebSocket 网关通过内部 Actor/RPC 运行时，将请求路由到消息、身份关系、会话、历史、推送、文件、机器人和 RTC 等领域模块。

完整的组件边界、数据职责、私聊与群聊链路、安全边界和部署约束，请阅读 架构文档。English version

可通过 可复现性能测试工具 分别评估连接建立、私聊和群聊的 ACK 与端到端投递吞吐，并生成包含 P50/P95/P99 延迟及运行环境的机器可读结果。

🚀 使用 Docker 快速开始

通过 Docker Compose 一次启动 MySQL、JuggleIM 服务和管理后台：

git clone https://github.com/juggleim/im-server.git
cd im-server
docker compose up -d

容器健康检查通过后，可通过以下地址访问本地服务：

服务	地址	用途
服务端 API	`http://127.0.0.1:9001`	供业务服务器调用
导航服务	`http://127.0.0.1:9002`	向客户端返回长连接地址
WebSocket	`ws://127.0.0.1:9003`	供客户端 SDK 建立长连接
管理后台	`http://127.0.0.1:8090`	管理应用；默认账号密码：`admin` / `123456`

通过已验证的服务端 API 示例创建本地应用、注册两个合成测试用户并发送一条私聊消息：

bash examples/server-api-quickstart.sh

脚本会将生成的应用密钥保留在服务端，仅输出本地 SDK 测试所需的两个临时用户 Token。完整流程和安全边界请查看 服务端 API 快速开始。English version

使用 docker compose down 停止本地服务；如需同时删除 MySQL 数据卷，执行 docker compose down -v。

如服务未能正常启动，请按照 Docker Compose 故障排查指南 检查容器状态、日志、端口冲突、MySQL 健康状态和安全重置步骤。English version

生产环境、集群及托管部署方式请查看 部署指南。

🛠 手动部署

点击展开完整手动部署步骤

1. 安装并初始化 MySQL

创建 DB 实例：

CREATE SCHEMA `jim_db`;

初始化表结构（SQL 文件位于 sql/imserver.sql）：

mysql -u{db_user} -p{db_password} jim_db < sql/imserver.sql

2. 安装 MongoDB（可选）

仅在使用 MongoDB 存储消息数据（msgStoreEngine: mongo）时需要。

3. 启动 im-server

运行目录为 im-server/launcher，其中 conf 目录存放配置文件，logs 目录为运行日志目录。

编辑配置文件 im-server/launcher/conf/config.yml：

defaultPort: 9003       # im-server 默认监听端口
nodeName: testNode      # 节点名称
nodeHost: 127.0.0.1     # 节点 IP
msgStoreEngine: mysql   # 消息存储引擎：mysql（默认）或 mongo

log:
  logPath: ./logs       # 运行日志目录
  logName: jim-info     # 运行日志前缀名
  visual: false         # 是否开启可视化日志（写入 KV 数据库，可在管理后台界面化查询）

mysql:                  # MySQL 相关配置
  user: root
  password: 123456
  address: 127.0.0.1:3306
  name: im_db

# mongodb:              # MongoDB 配置，msgStoreEngine 为 "mongo" 时生效
#   address: 127.0.0.1:27017
#   name: jim_msgs

apiGateway:             # 服务端 API 端口，供业务 APP 服务端调用
  httpPort: 9001

navGateway:             # 导航服务端口，供客户端 SDK 获取长连接地址
  httpPort: 9002

connectManager:         # WebSocket 长连接端口
  wsPort: 9003

adminGateway:           # 自带管理后台，默认账号密码 admin/123456
  httpPort: 8090

启动服务，在 im-server/launcher 目录下执行：

go run main.go

4. 配置外网访问地址

需要对外暴露的端口：

端口	协议	说明
9001	http	服务端 API 端口，供业务服务器（如 jugglechat-server）调用
9002	http	导航服务端口，用于获取 WebSocket 长连接地址
9003	websocket	IM 长连接端口，供客户端 SDK 建立长连接
8090	http	管理后台端口，默认账号密码 admin/123456

配置方式可根据环境灵活选择（公网 IP、Nginx 反向代理、负载均衡等）。仅内网调试可只用内网 IP。

将长连接地址配置到系统中，在数据库插入一条配置：

insert into globalconfs (conf_key, conf_value) values ('connect_address', '{"default":["127.0.0.1:9003"]}');

将 127.0.0.1 替换成机器内网 IP 或对外公网 IP/域名，该地址会由导航服务下发给客户端 SDK。

🏢 创建应用（租户）

JuggleIM 是一套多租户系统，一套服务中可创建多个 appkey（租户），租户间数据相互隔离。

通过管理 API 创建租户（app_key 为租户标识，需系统内唯一）：

curl --request POST \
  --url http://127.0.0.1:8090/admingateway/apps/create \
  --data '{
    "app_key":"appkey",
    "app_name":"appname"
}'

响应示例：

{
    "code": 0,
    "msg": "success",
    "data": {
        "app_name": "appname",
        "app_key": "appkey",
        "app_secret": "hciKcc6sXRDjYUQp"
    }
}

也可登录管理后台 http://127.0.0.1:8090（默认账号密码 admin/123456）查看和维护应用列表。

🔌 业务服务器 / 客户端集成

1）业务服务器集成

配置项	示例	备注
IM 服务端 API 地址	`http://127.0.0.1:9001`	供业务服务器访问 IM 的 API，可注册用户、创建群、发系统消息等，详见 API 文档
app_key	`appkey1`	应用租户标识，系统内唯一
app_secret	`hciKcc6sXRDjYUQp`	鉴权秘钥，创建应用时生成（自定义需为 16 位字符串）。仅在业务服务器端使用，切勿泄露到客户端

2）客户端 SDK 集成

配置项	示例	备注
IM 连接地址	`ws://127.0.0.1:9003`	客户端 SDK 初始化时传入，参考快速开始
app_key	`appkey1`	与业务服务器端保持一致

💬 社群讨论

对 IM 感兴趣、有集成问题想交流的朋友，欢迎加入社群一起讨论 👇

Telegram 中文群
GitHub Discussions：提问、讨论想法和展示项目
GitHub Issues：提交可复现的 Bug 和明确的功能需求

🤝 参与贡献

欢迎任何形式的贡献！你可以：

提交 Issue 反馈 Bug 或提出需求
提交 Pull Request 改进代码或文档
分享你基于 JuggleIM 构建的项目

⭐ Star History

如果 JuggleIM 帮到了你，别忘了给我们一个 Star，你的支持是我们持续迭代的动力！

📄 License

本项目基于 LICENSE 开源协议发布。

Navigation Menu

Uh oh!

JuggleIM

📖 什么是 JuggleIM

✨ 核心特性

🗂 目录

🧬 项目生态

🏗 系统架构

🚀 使用 Docker 快速开始

🛠 手动部署

1. 安装并初始化 MySQL

2. 安装 MongoDB（可选）

3. 启动 im-server

4. 配置外网访问地址

🏢 创建应用（租户）

🔌 业务服务器 / 客户端集成

💬 社群讨论

🤝 参与贡献

⭐ Star History

📄 License

Uh oh!

FilesExpand file tree

README_zh.md

Latest commit

History

README_zh.md

File metadata and controls

JuggleIM

📖 什么是 JuggleIM

✨ 核心特性

🗂 目录

🧬 项目生态

🏗 系统架构

🚀 使用 Docker 快速开始

🛠 手动部署

1. 安装并初始化 MySQL

2. 安装 MongoDB（可选）

3. 启动 im-server

4. 配置外网访问地址

🏢 创建应用（租户）

🔌 业务服务器 / 客户端集成

💬 社群讨论

🤝 参与贡献

⭐ Star History

📄 License