# JuggleIM
**一个高性能、可扩展的开源 IM 即时通讯系统**
*A high-performance, scalable open-source instant messaging (IM) system.*
[](./LICENSE)
[](https://github.com/juggleim/im-server)
[](https://github.com/juggleim/im-server/actions/workflows/ci.yml)
[](https://github.com/juggleim/im-server/releases)
[](https://github.com/juggleim/im-server/stargazers)
[](https://github.com/juggleim/im-server/network/members)
[](https://github.com/juggleim/im-server/commits)
**简体中文** | **[English](./README.md)**
**[官网](https://www.juggle.im)** ·
**[文档](https://www.juggle.im/docs/guide/intro/)** ·
**[快速部署](https://www.juggle.im/docs/guide/deploy/quickdeploy/)** ·
**[API 文档](https://www.juggle.im/docs/server/api/)** ·
**[提问](https://github.com/juggleim/im-server/discussions/categories/q-a)**
如果这个项目对你有帮助，欢迎点一个 ⭐ **Star** 支持我们，也方便你随时找到它！
---
## 📖 什么是 JuggleIM
JuggleIM 是一套**开箱即用、可私有化部署**的即时通讯（IM）后端服务。基于 Protobuf + WebSocket 长连接协议，专注于消息的高效分发与可靠存储，帮助你在几分钟内为 App、网站或业务系统搭建起属于自己的聊天能力。
无论是社交产品、客服系统、IoT 设备通信，还是直播弹幕、AI 机器人对话，JuggleIM 都能作为稳定的通讯底座。它天生支持**多租户**，一套服务即可承载多个相互隔离的应用；专业版支持集群横向扩展，可支撑**亿级日活**。
> 想直接体验？按照下方 [Docker 快速开始](#-使用-docker-快速开始)，几分钟内运行完整服务。
## ✨ 核心特性
**🚀 高性能 & 高可用**
- Protobuf + WebSocket 长连接，低流量、高性能，弱网环境下依然保持良好连通性
- 专业版支持集群部署，无限横向扩展，可支撑亿级日活应用
- 支持万人、十万人大群沟通不丢消息，支持无上限直播聊天室
**🔒 安全 & 稳定**
- 使用租户级凭证和客户端 Token 鉴权；生产环境建议通过 HTTPS/WSS 保障传输安全
- 多端同时在线、消息多端同步，确保状态多端一致
**🌍 灵活部署 & 全球服务**
- 支持公有云、私有云、托管云等多种部署形态
- 支持全球链路加速，可服务全球级应用
**🧩 易集成 & 可扩展**
- 提供 Android、iOS、Web、PC、Flutter、鸿蒙等多平台 SDK，附带 Demo 与文档
- 提供丰富的 REST API 和 WebHook，方便与现有系统集成
- 具备 AI 机器人对接能力，可轻松对接大模型
- 自带运维工具和管理后台，简单好维护
## 🗂 目录
- [项目生态](#-项目生态)
- [系统架构](#-系统架构)
- [使用 Docker 快速开始](#-使用-docker-快速开始)
- [手动部署](#-手动部署)
- [创建应用（租户）](#-创建应用租户)
- [业务集成](#-业务服务器--客户端集成)
- [社群讨论](#-社群讨论)
- [Star History](#-star-history)
## 🧬 项目生态
JuggleIM 采用「核心服务 + 业务服务 + 多端 SDK + Demo」的分层架构，各仓库职责清晰，可按需组合、二次开发。
| 仓库 | 说明 |
| :--- | :--- |
| **[im-server](https://github.com/juggleim/im-server/)** | 底层 IM 核心服务，负责消息分发、存储等 IM 相关业务（本仓库） |
| [jugglechat-server](https://github.com/juggleim/jugglechat-server) | Demo 业务服务，负责用户注册/登录、创建群组、添加好友等业务，可在此基础上二开 |
| [jugglechat-server-java](https://github.com/juggleim/jugglechat-server-java) | Demo 业务服务的 Java 版本 |
| [imserver-console](https://github.com/juggleim/imserver-console) | IM 服务的管理后台，用于操作 IM 配置、监控业务量 |
| [imsdk-android](https://github.com/juggleim/imsdk-android) | 安卓端 imsdk，内含 UI Demo，可用于二开 |
| [imsdk-ios](https://github.com/juggleim/imsdk-ios) | iOS 端 imsdk，内含 UI Demo，可用于二开 |
| [imsdk-web](https://github.com/juggleim/imsdk-web) | Web 端 imsdk |
| [imsdk-flutter](https://github.com/juggleim/imsdk-flutter) | imsdk 的 Flutter 版本 |
| [imsdk-harmony](https://github.com/juggleim/imsdk-harmony) | 鸿蒙版本 imsdk，内含 UI Demo，可用于二开 |
| [jugglechat-web](https://github.com/juggleim/jugglechat-web) | 集成 imsdk-web 的 Web 版 Demo，可用于二开 |
| [jugglechat-desktop](https://github.com/juggleim/jugglechat-desktop) | 集成 imsdk-pc 的桌面版 Demo，可用于二开 |
| [jugglelive-web](https://github.com/juggleim/jugglelive-web) | 集成 imsdk-web 的聊天室场景 Demo，可用于二开 |
| [bot-connector](https://github.com/juggleim/bot-connector) | 机器人对接服务，用于打通 im-server 与三方机器人 |
| [imserver-sdk-go](https://github.com/juggleim/imserver-sdk-go) | 封装 im-server 服务端 API 的 SDK，供业务方集成 |
| [imserver-sdk-java](https://github.com/juggleim/imserver-sdk-java) | imserver-sdk 的 Java 版本 |
> 桌面端 imsdk-pc 暂未开源，可联系客服了解。
## 🏗 系统架构
JuggleIM 以模块化 Go 服务运行：HTTP 和 WebSocket 网关通过内部 Actor/RPC 运行时，将请求路由到消息、身份关系、会话、历史、推送、文件、机器人和 RTC 等领域模块。
[](./docs/architecture_zh.md)
完整的组件边界、数据职责、私聊与群聊链路、安全边界和部署约束，请阅读 **[架构文档](./docs/architecture_zh.md)**。[English version](./docs/architecture.md)
可通过 **[可复现性能测试工具](./BENCHMARKS.md)** 分别评估连接建立、私聊和群聊的 ACK 与端到端投递吞吐，并生成包含 P50/P95/P99 延迟及运行环境的机器可读结果。
## 🚀 使用 Docker 快速开始
通过 Docker Compose 一次启动 MySQL、JuggleIM 服务和管理后台：
```bash
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
bash examples/server-api-quickstart.sh
```
脚本会将生成的应用密钥保留在服务端，仅输出本地 SDK 测试所需的两个临时用户 Token。完整流程和安全边界请查看 **[服务端 API 快速开始](./docs/server-api-quickstart_zh.md)**。[English version](./docs/server-api-quickstart.md)
使用 `docker compose down` 停止本地服务；如需同时删除 MySQL 数据卷，执行 `docker compose down -v`。
如服务未能正常启动，请按照 **[Docker Compose 故障排查指南](./docs/docker-troubleshooting_zh.md)** 检查容器状态、日志、端口冲突、MySQL 健康状态和安全重置步骤。[English version](./docs/docker-troubleshooting.md)
生产环境、集群及托管部署方式请查看 **[部署指南](https://www.juggle.im/docs/guide/deploy/quickdeploy/)**。
## 🛠 手动部署