README.md
Rama master · réplica de lectura del repositorio original.
<div align="center">
<img height="120" src="./docs/logo.png" alt="JuggleIM Logo">
# JuggleIM
**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)
**[简体中文](./README_zh.md)** | **English**
**[Website](https://www.juggle.im)** ·
**[Docs](https://www.juggle.im/docs/guide/intro/)** ·
**[Quick Deploy](https://www.juggle.im/docs/guide/deploy/quickdeploy/)** ·
**[API Reference](https://www.juggle.im/docs/server/api/)** ·
**[Ask a Question](https://github.com/juggleim/im-server/discussions/categories/q-a)**
If this project helps you, please give it a ⭐ **Star** — it keeps the project easy to find and motivates us to keep building!
</div>
---
## 📖 What is JuggleIM
JuggleIM is a **ready-to-use, self-hostable** instant messaging (IM) backend. Built on a Protobuf + WebSocket long-connection protocol, it focuses on efficient message delivery and reliable storage, letting you add chat capabilities to your app, website, or business system in minutes.
Whether you are building a social product, a customer-service system, IoT device communication, live-stream chat, or AI bot conversations, JuggleIM serves as a solid messaging foundation. It is **multi-tenant** by design — a single deployment can host multiple fully isolated applications — and the professional edition scales horizontally to support **hundreds of millions of daily active users**.
> Want to try it right away? Jump to the [Docker Quick Start](#-quick-start-with-docker) below.
## ✨ Key Features
**🚀 High Performance & High Availability**
- Protobuf + WebSocket long connections — low bandwidth, high throughput, and reliable connectivity even on poor networks
- Professional edition supports clustered deployment with unlimited horizontal scaling, powering apps with hundreds of millions of DAU
- Handles large groups of 10,000–100,000 members without losing messages, plus unlimited-size live chat rooms
**🔒 Secure & Reliable**
- Tenant-scoped credentials and token-based client authentication, with HTTPS/WSS recommended for production transport security
- Multi-device online presence and message sync keep state consistent across all endpoints
**🌍 Flexible Deployment & Global Reach**
- Supports public cloud, private cloud, and managed cloud deployment models
- Global link acceleration for worldwide-scale applications
**🧩 Easy to Integrate & Extend**
- SDKs for Android, iOS, Web, PC, Flutter, and HarmonyOS, each with a demo and docs
- Rich REST APIs and WebHooks for integrating with your existing systems
- Built-in AI bot connectivity — easily plug in large language models
- Comes with ops tooling and an admin console for simple maintenance
## 🗂 Table of Contents
- [Ecosystem](#-ecosystem)
- [Architecture](#-architecture)
- [Quick Start with Docker](#-quick-start-with-docker)
- [Manual Deployment](#-manual-deployment)
- [Create an Application (Tenant)](#-create-an-application-tenant)
- [Integration](#-business-server--client-integration)
- [Community](#-community)
- [Star History](#-star-history)
## 🧬 Ecosystem
JuggleIM follows a layered architecture — "core service + business service + multi-platform SDKs + demos" — with clearly separated repositories that can be composed and customized as needed.
| Repository | Description |
| :--- | :--- |
| **[im-server](https://github.com/juggleim/im-server/)** | Core IM service handling message delivery, storage, and related IM logic (this repo) |
| [jugglechat-server](https://github.com/juggleim/jugglechat-server) | Demo business service handling user registration/login, group creation, friends, etc. — a base for your own development |
| [jugglechat-server-java](https://github.com/juggleim/jugglechat-server-java) | Java version of the demo business service |
| [imserver-console](https://github.com/juggleim/imserver-console) | Admin console for IM configuration and business metrics |
| [imsdk-android](https://github.com/juggleim/imsdk-android) | Android imsdk with a UI demo, ready for customization |
| [imsdk-ios](https://github.com/juggleim/imsdk-ios) | iOS imsdk with a UI demo, ready for customization |
| [imsdk-web](https://github.com/juggleim/imsdk-web) | Web imsdk |
| [imsdk-flutter](https://github.com/juggleim/imsdk-flutter) | Flutter version of imsdk |
| [imsdk-harmony](https://github.com/juggleim/imsdk-harmony) | HarmonyOS imsdk with a UI demo, ready for customization |
| [jugglechat-web](https://github.com/juggleim/jugglechat-web) | Web demo integrating imsdk-web, ready for customization |
| [jugglechat-desktop](https://github.com/juggleim/jugglechat-desktop) | Desktop demo integrating imsdk-pc, ready for customization |
| [jugglelive-web](https://github.com/juggleim/jugglelive-web) | Live chat-room demo integrating imsdk-web, ready for customization |
| [bot-connector](https://github.com/juggleim/bot-connector) | Bot connector service bridging im-server and third-party bots |
| [imserver-sdk-go](https://github.com/juggleim/imserver-sdk-go) | SDK wrapping the im-server server-side API for easy integration |
| [imserver-sdk-java](https://github.com/juggleim/imserver-sdk-java) | Java version of imserver-sdk |
> The desktop imsdk-pc is not yet open-sourced — contact support for details.
## 🏗 Architecture
JuggleIM runs as a modular Go service: HTTP and WebSocket gateways route requests through an internal actor/RPC runtime to messaging, identity, conversation, history, push, file, bot, and RTC modules.
[](./docs/architecture.md)
Read the **[architecture guide](./docs/architecture.md)** for component boundaries, data ownership, private and group message flows, security boundaries, and deployment constraints. [简体中文版](./docs/architecture_zh.md)
Evaluate performance with the **[reproducible benchmark harness](./BENCHMARKS.md)**, which reports connection setup separately from private-chat and group-chat ACK and delivery throughput, including P50/P95/P99 latency and machine-readable results.
## 🚀 Quick Start with Docker
Run a complete local JuggleIM stack with MySQL and the admin console:
```bash
git clone https://github.com/juggleim/im-server.git
cd im-server
docker compose up -d
```
Once the containers are healthy, the local services are available at:
| Service | Address | Purpose |
| :--- | :--- | :--- |
| Server API | `http://127.0.0.1:9001` | Called by your business server |
| Navigator | `http://127.0.0.1:9002` | Returns the client connection address |
| WebSocket | `ws://127.0.0.1:9003` | Used by client SDKs for long connections |
| Admin console | `http://127.0.0.1:8090` | Manage applications; default login: `admin` / `123456` |
Create a local application, register two synthetic users, and send a private message with the verified server API example:
```bash
bash examples/server-api-quickstart.sh
```
The script keeps the generated application secret on the server side and prints the two temporary user tokens needed for local SDK testing. See the **[server API quick start](./docs/server-api-quickstart.md)** for the complete flow and security boundaries. [简体中文版](./docs/server-api-quickstart_zh.md)
Stop the local stack with `docker compose down`. To remove its MySQL data as well, use `docker compose down -v`.
If the stack does not become healthy, follow the **[Docker Compose troubleshooting guide](./docs/docker-troubleshooting.md)** for status checks, logs, port conflicts, MySQL health, and safe reset steps. [简体中文版](./docs/docker-troubleshooting_zh.md)
For production, clustering, and managed deployment options, see the **[Deployment Guide](https://www.juggle.im/docs/guide/deploy/quickdeploy/)**.
## 🛠 Manual Deployment
<details>
<summary>Click to expand the full manual deployment steps</summary>
### 1. Install and Initialize MySQL
Create the database schema:
```sql
CREATE SCHEMA `jim_db`;
```
Initialize the table structure (the SQL file lives at `sql/imserver.sql`):
```bash
mysql -u{db_user} -p{db_password} jim_db < sql/imserver.sql
```
### 2. Install MongoDB (optional)
Only required when using MongoDB to store message data (`msgStoreEngine: mongo`).
### 3. Start im-server
The working directory is `im-server/launcher`, where `conf` holds config files and `logs` is the runtime log directory.
**Edit the config file** `im-server/launcher/conf/config.yml`:
```yaml
defaultPort: 9003 # im-server default listening port
nodeName: testNode # node name
nodeHost: 127.0.0.1 # node IP
msgStoreEngine: mysql # message store engine: mysql (default) or mongo
log:
logPath: ./logs # runtime log directory
logName: jim-info # runtime log filename prefix
visual: false # enable visual logs (write to a KV store, queryable in the admin console)
mysql: # MySQL configuration
user: root
password: 123456
address: 127.0.0.1:3306
name: im_db
# mongodb: # MongoDB config, active when msgStoreEngine is "mongo"
# address: 127.0.0.1:27017
# name: jim_msgs
apiGateway: # server-side API port for business app servers
httpPort: 9001
navGateway: # navigator endpoint used by client SDKs
httpPort: 9002
connectManager: # WebSocket long-connection port
wsPort: 9003
adminGateway: # built-in admin console, default credentials admin/123456
httpPort: 8090
```
**Start the service** from the `im-server/launcher` directory:
```bash
go run main.go
```
### 4. Configure Public Access Addresses
Ports that need to be exposed:
| Port | Protocol | Description |
| ---: | :---: | :--- |
| 9001 | http | Server-side API port, called by business servers (e.g. jugglechat-server) |
| 9002 | http | Navigator port, used to discover the WebSocket connection address |
| 9003 | websocket | IM long-connection port for client SDKs |
| 8090 | http | Admin console port, default credentials admin/123456 |
Configure exposure however suits your environment (public IP, Nginx reverse proxy, load balancer, etc.). For local testing, an intranet IP is enough.
**Register the long-connection address** by inserting a config row into the database:
```sql
insert into globalconfs (conf_key, conf_value) values ('connect_address', '{"default":["127.0.0.1:9003"]}');
```
Replace `127.0.0.1` with your machine's intranet IP or public IP/domain. This address is delivered to client SDKs by the navigator service.
</details>
## 🏢 Create an Application (Tenant)
JuggleIM is a **multi-tenant** system — a single deployment can host multiple appkeys (tenants) with fully isolated data.
**Create a tenant via the admin API** (`app_key` is the tenant identifier and must be unique):
```bash
curl --request POST \
--url http://127.0.0.1:8090/admingateway/apps/create \
--data '{
"app_key":"appkey",
"app_name":"appname"
}'
```
Example response:
```json
{
"code": 0,
"msg": "success",
"data": {
"app_name": "appname",
"app_key": "appkey",
"app_secret": "hciKcc6sXRDjYUQp"
}
}
```
You can also log in to the admin console at `http://127.0.0.1:8090` (default credentials `admin/123456`) to view and manage your applications.
## 🔌 Business Server / Client Integration
**1) Business Server Integration**
| Item | Example | Notes |
| ---: | :---: | :--- |
| IM server-side API address | `http://127.0.0.1:9001` | Used by your business server to call IM APIs (register users, create groups, send system messages, etc.). See the [API Reference](https://www.juggle.im/docs/server/api/) |
| app_key | `appkey1` | Tenant identifier, unique within the system |
| app_secret | `hciKcc6sXRDjYUQp` | Auth secret generated on app creation (must be 16 chars if custom). **Use only on the business server — never expose it to clients** |
**2) Client SDK Integration**
| Item | Example | Notes |
| ---: | :---: | :--- |
| IM connection address | `ws://127.0.0.1:9003` | Passed to the client SDK on init. See [Quick Start](https://www.juggle.im/docs/client/quickstart/android/) |
| app_key | `appkey1` | Must match the value used on the business server |
## 💬 Community
Interested in IM or have integration questions? Join the community and let's chat 👇
- [Telegram Group (Chinese)](https://t.me/juggleim_zh)
- [GitHub Discussions](https://github.com/juggleim/im-server/discussions) for questions, ideas, and project showcases
- [GitHub Issues](https://github.com/juggleim/im-server/issues) for reproducible bugs and scoped feature requests
## 🤝 Contributing
Contributions of all kinds are welcome! You can:
- Open an [Issue](https://github.com/juggleim/im-server/issues) to report bugs or request features
- Submit a Pull Request to improve the code or docs
- Share the projects you build on top of JuggleIM
## ⭐ Star History
If JuggleIM has helped you, please give us a Star — your support drives our continued development!
[](https://www.star-history.com/#juggleim/im-server&Date)
## 📄 License
This project is released under the [LICENSE](./LICENSE).