🏗️ 系统架构

1. im-gateway - 网关服务 (端口: 9191)

功能: 系统入口，负责请求路由、负载均衡、限流熔断

• 集成Sentinel实现网关限流和负载均衡
• 通过Nacos实现服务注册与发现，实现动态路由
• 根据Redis中的用户信息，定向转发长连接请求
• 支持全局签名校验、JWT认证、黑名单拦截与动态降级

2. im-auth - 认证服务 (端口: 8084)

功能: 用户身份验证和权限管理

• 用户登录、注册、令牌生成和验证
• 提供RSA公钥，用于登录时密码加密
• 手机短信验证码服务
• 支持用户名密码 / 手机短信 / 二维码登录，多策略认证

3. im-connect - 连接服务 (端口: 19000-19002)

功能: WebSocket长连接管理和消息推送

• 管理客户端长连接，支持心跳机制
• 通过RabbitMQ接收消息并推送给用户
• 支持多实例部署，自动负载均衡
• 增加连接限流与消息速率限制、监控与日志、虚拟线程优化

4. im-chat - 业务服务 (端口: 8085)

功能: 核心业务逻辑处理

• 消息发送、接收、存储和查询
• 群组管理、文件上传、群聊头像生成
• 消息分发到对应的im-connect服务
• 基于Redisson与Redis的并发锁与热点缓存优化

5. 模块总览

• im-ai（端口: 8088）: AI 服务（对话、嵌入、Prompt 管理、工具调用）
• im-oss（端口: 8087）: MinIO 文件服务，支持分片上传、断点续传、图像压缩/缩略图/水印、nsfw图片审查
• im-platform（端口: 8090）: 应用更新与短链服务（应用更新与短链），支持版本检查与预签名下载、Bloom去重 + Caffeine LRU + Redis短链缓存
• im-leaf（端口: 8086）: 分布式ID服务（Segment、Snowflake、UID、UUID），支持Nacos工作ID分配
• im-database（端口: 8100）: 数据库初始化与元数据服务
• im-meet（端口: 19100 WebSocket）: 实时会话服务（Netty WS）
• im-analysis（端口: 8089）: 文本分析服务（HanLP 分词、关键词、依存句法）
• im-proxy: 代理配置管理（Nginx 模板），辅助WebSocket代理与负载
• im-framework: 基础框架聚合（core/domain/common/crypto/spring/grpc/security/mq 等）

🔄 消息流转

用户发送消息流程:
1. 客户端 → im-gateway → im-chat
2. im-chat 处理业务逻辑
3. im-chat → RabbitMQ → im-connect
4. im-connect → 用户长连接 → 客户端

长连接管理流程:
1. 客户端通过im-gateway建立WebSocket连接
2. im-connect 注册用户信息和机器码到Redis
3. 定期心跳维持连接状态
4. 连接断开时清理Redis中的相关信息

🔄 端到端消息流程（详细步骤）

客户端 → im-gateway → im-chat → RabbitMQ → im-connect → 客户端

发送方（im-chat）

1. 构造消息 DTO（含 messageId — 全局唯一，建议 Snowflake 或 UUID；messageTempId 仅客户端使用）。
2. 持久化消息 + 写 outbox（同一事务）：
   • 将消息写入消息表（im_private_message/im_group_message），并在 outbox 表插入一条记录（outbox 保存 messageId/payload/targetBroker/状态）。
3. 提交事务（数据库事务提交成功即代表消息被可靠保存）。
4. 尝试发送到 RabbitMQ（read from outbox 或者立即 publish）：
   • 使用 Publisher Confirms（channel.confirmSelect()）和 mandatory 标志，确保 broker 接收（且消息标记为持久化）。
   • 若 publish 返回 confirm（ack），将 outbox 状态标为 SENT_TO_BROKER。
   • 若 publish 失败或无确认，保持 outbox 状态为 PENDING，后台任务会重试（见下）。
5. 后台补偿任务：周期性扫描 outbox 状态为 PENDING/FAILED 的记录，重试 publish，或人工介入。

Broker（RabbitMQ）配置要点

• 交换机/队列都设置为 durable
• 发布消息时设置 persistent=true
• 使用 publisher confirms（比事务更轻量且推荐）
• 考虑使用 quorum queues 或 高可用镜像/cluster 来避免单节点丢失
• 设置 dead-letter-exchange（DLX）用于无法投递/多次重试的消息

消费者（im-connect）

1. 消费到消息后，先 ack RabbitMQ（或按你设计先处理再 ack，注意需要保证不丢失）。常见做法：
   • 先把消息持久化（如果需要），然后 ack；或
   • 使用 manual ack：处理成功后 ack，处理失败 nack/reject（可重入或进 DLX）
2. 幂等处理：在投递前查询是否已处理（查 messageId 的 delivery 表或 status 字段）；若已投递则忽略
3. 路由到客户端：找到用户对应的 WebSocket 连接（从 Redis 注册表），将消息发送到客户端
4. 等待客户端 ACK（可选但强烈建议）：
   • 客户端收到后返回 DELIVERY_ACK(messageId) 给 im-connect
   • im-connect 更新 DB（或通过 RPC/HTTP 回调 im-chat）把消息状态标为 DELIVERED
   • 若客户端未 ACK，im-connect 可重试若干次后将状态设为 UNDELIVERED 并进入重试策略/告警

客户端

• 客户端在接收消息后应回送 ACK（并持久保存消息、更新 UI），并对重复消息做去重（通过 messageId）

🛠️ 技术栈

后端技术

• Java 21: 运行时环境
• Spring Boot 3.5.9: 应用框架
• Spring Cloud Alibaba 2025.0.0.0: 微服务框架
• Spring WebFlux: 响应式Web框架
• MyBatis Plus: 数据持久层框架
• Netty: 服务端长连接网络框架

中间件服务

• Nacos: 服务注册发现、配置管理
• Redis: 缓存、会话管理
• RabbitMQ: 消息队列、异步通信
• MinIO: 对象存储、文件管理
• SRS: 流媒体服务、WebRTC支持

部署环境

• Docker: 容器化部署
• Nginx: 反向代理、负载均衡
• JDK 21: Java运行环境

🚀 快速开始

环境要求

• JDK: 21.0.0+
• Docker: 20.10.0+
• Docker Compose: 2.0.0+
• 操作系统: Linux/Windows/macOS

注意: 建议使用Linux环境部署，以获得最佳性能表现

1. 启动中间件服务

# 启动 Redis
docker run --name redis -p 6379:6379 -v /root/redis/conf/redis.conf:/usr/local/etc/redis/redis.conf -d redis --appendonly yes

# 启动 Nacos
docker run -itd --name nacos --env PREFER_HOST_MODE=hostname --env MODE=standalone --env NACOS_AUTH_IDENTITY_KEY=${NACOS_AUTH_IDENTITY_KEY} --env NACOS_AUTH_IDENTITY_VALUE=${NACOS_AUTH_IDENTITY_VALUE} --env NACOS_AUTH_TOKEN=${NACOS_AUTH_TOKEN} -p 8848:8848 -p 9848:9848 -p 9849:9849 nacos/nacos-server:v2.2.1

# 启动 RabbitMQ
docker run -d --hostname my-rabbit --name rabbit -p 15672:15672 -p 5671-5672:5671-5672 rabbitmq
docker exec -it rabbit /bin/bash
rabbitmq-plugins enable rabbitmq_management

# 启动 MinIO
docker run -p 9000:9000 -p 9090:9090 --name minio -d --restart=always -e "MINIO_ROOT_USER=${MINIO_ROOT_USER}" -e "MINIO_ROOT_PASSWORD=${MINIO_ROOT_PASSWORD}" -v /root/minio/data:/data -v /root/minio/config:/root/.minio minio/minio server /data --console-address ":9090" --address ":9000"

# 启动 SRS (注意: CANDIDATE必须设置为物理机IP)
docker run -it -p 1935:1935 -p 1985:1985 -p 8080:8080 -p 1990:1990 -p 8088:8088 --env CANDIDATE=192.168.1.9 -p 8000:8000/udp registry.cn-hangzhou.aliyuncs.com/ossrs/srs:6.0-d2

# 启动 PostgreSQL
docker run -d --name postgres -p 35432:5432 -e POSTGRES_USER=${POSTGRES_USER} -e POSTGRES_PASSWORD=${POSTGRES_PASSWORD} -e POSTGRES_DB=${POSTGRES_DB} -v D:/Docker-vm/postgresql/vectordata:/var/lib/postgresql/data ankane/pgvector

2. 配置应用

# application.yml 示例配置
spring:
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
      config:
        server-addr: localhost:8848
        file-extension: yml

  redis:
    host: localhost
    port: 6379

  rabbitmq:
    host: localhost
    port: 5672
    username: ${RABBITMQ_USER}
    password: ${RABBITMQ_PASSWORD}

# 文件存储配置
minio:
  endpoint: localhost:9000
  accessKey: ${MINIO_ACCESS_KEY}
  secretKey: ${MINIO_SECRET_KEY}
  bucket: im-files

# SRS配置
srs:
  webrtc: http://localhost:8080
  rtmp: rtmp://localhost:1935

3. 启动应用服务

推荐使用两种方式启动服务：

方式一：手动依次启动

1. im-database (端口：8086)
2. im-auth (端口: 8084)
3. im-chat (端口: 8085)
4. im-connect (端口: 19000-19002)
5. im-gateway (端口: 9191)
6. im-oss (端口: 8087)
7. im-platform (端口: 8090)
8. im-ai (端口: 8088)
9. im-analysis (端口: 8089)

方式二：使用构建脚本一键启动

# Windows 系统
deploy-all.bat

# Linux/macOS 系统
./deploy-all.sh

4. 访问服务

• 网关服务: http://localhost:9191
• 认证服务: http://localhost:8084
• 业务服务（im-chat）: http://localhost:8085
• 文件服务（im-oss）: http://localhost:8087
• ID服务: http://localhost:8086
• AI服务: http://localhost:8088
• 文本分析: http://localhost:8089
• 平台服务: http://localhost:8090
• Nacos控制台: http://localhost:8848/nacos (账号: nacos/nacos)
• RabbitMQ管理: http://localhost:15672 (账号: guest/guest)
• MinIO控制台: http://localhost:9090 (账号: minioadmin/minioadmin)
• SRS服务: http://localhost:8080
• PostgreSQL: localhost:35432
• 连接服务 WebSocket: ws://localhost:19000/im、ws://localhost:19001/im、ws://localhost:19002/im
• 实时会话 WebSocket: ws://localhost:19100

🔧 开发指南

项目结构

├── im-gateway/          # 网关服务
├── im-auth/             # 认证服务
├── im-connect/          # 长连接连接服务
├── im-chat/             # 业务服务
├── im-leaf/             # ID生成服务
├── im-oss/              # 文件管理服务
├── im-platform/         # 平台服务
├── im-ai/               # AI 服务
├── im-analysis/         # 文本分析服务
├── im-database/         # 数据库服务
├── im-meet/             # 实时会话服务
├── im-logging/          # 日志服务
├── im-lbs/              # 地理位置服务
├── im-quartz/           # 定时任务服务
├── im-framework/        # 公共模块
│   ├── im-core/         # 核心工具
│   ├── im-domain/       # 领域模型
│   ├── im-general/      # 通用组件
│   ├── im-grpc/         # gRPC相关
│   ├── im-security/     # 安全模块
│   ├── im-spring/       # Spring扩展
│   └── im-common/       # 工具类库
└── docs/                # 项目文档

代码规范

• 遵循阿里巴巴Java开发手册
• 使用统一的代码格式化工具
• 完善的注释和文档
• 单元测试覆盖率 > 80%

API文档

启动服务后，访问以下地址查看API文档：

• Swagger UI: http://localhost:8085/doc.html
• OpenAPI: http://localhost:8085/v3/api-docs

🧪 测试

# 运行单元测试
mvn test

# 运行集成测试
mvn verify

# 生成测试报告
mvn jacoco:report

📦 部署

Docker部署

# 构建镜像
mvn clean package -DskipTests

# 使用Docker Compose一键部署所有服务
docker-compose up -d

生产环境配置

• 使用Nginx进行反向代理和负载均衡
• 配置SSL证书，支持HTTPS
• 设置合适的JVM参数
• 配置日志收集和监控告警

📊 性能指标

• 并发连接: 支持10,000+ WebSocket连接
• 消息延迟: 平均延迟 < 100ms
• 系统吞吐: 10,000+ TPS
• 响应时间: 99%请求 < 200ms

测试环境: 8核16G云服务器，JDK 21，Docker部署

📝 更新日志（概览）

• 新增模块
  • im-oss: 增加图像处理（压缩、缩略图、水印），支持分片/断点续传与MD5校验，支持nfsw图片审查
  • im-platform: 增加应用更新与短链接服务（Bloom 去重、Caffeine LRU、Redis 缓存、访问计数分层归并）
  • im-leaf: 集成多策略ID生成与Nacos工作ID分配
  • im-ai: 接入 Spring AI（对话/嵌入/工具），完善Prompt与Session管理
  • im-analysis: 提供分词/关键词/依存句法等文本分析能力
  • im-proxy: Nginx代理模板生成与维护
  • im-meet: 基于Netty的实时会话服务（WebSocket）
• 网关增强
  • 新增全局签名校验、JWT认证、黑名单拦截、动态降级过滤器与路由缓存（见 im-gateway 目录）
• 连接服务增强
  • 引入连接/消息限流、监控服务与虚拟线程优化；完善消息处理管线（见 im-connect 目录）
• 业务服务优化
  • 基于Redisson的并发锁与Redis热点缓存；完善群聊/好友等操作的幂等与性能日志（见 im-chat 目录）
• 文件服务修复
  • 修复 MinIO 客户端签名问题并增强稳定性（见 im-oss 中 PearlMinioClient.java）

🙏 致谢

• Spring Boot - Java应用框架

• Spring Cloud Alibaba - 微服务方案

• Nacos - 服务注册发现

• Redis - 内存数据库

• RabbitMQ - 消息队列

• MinIO - 对象存储

• SRS - 流媒体服务器

🤝 贡献指南

我们欢迎所有形式的贡献！请查看 CONTRIBUTING.md 了解详情。

贡献方式

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

开发交流

• 提交 Issue 报告问题或建议新功能
• 加入技术交流群讨论技术细节

📞 联系我们

• 项目主页: https://github.com/LucklySpace/Lucky-cloud
• 问题反馈: Issues

📢 免责声明

本项目仅供学习和参考使用，不得用于任何商业用途。作者不对使用本项目可能引起的任何直接或间接损失承担责任。

1. 本项目是一个开源学习项目，旨在提供即时通讯技术的学习和研究参考。
2. 项目中涉及的技术方案、代码实现仅供参考，不保证其在生产环境中的稳定性、安全性和可靠性。
3. 用户在使用本项目时应自行承担所有风险，包括但不限于数据丢失、系统损坏、通信安全等问题。
4. 作者不提供任何形式的技术支持和保障，也不对项目的使用效果做任何承诺和保证。
5. 如将本项目用于商业用途，需自行承担可能的法律风险和责任。

💬 项目状态

本项目目前处于积极维护状态，持续更新和完善功能。

⭐ 如果这个项目对您有帮助，请给我们一个星标！