企业官网建设流程全解析

简介：鸽哒IM即时通讯系统是一套类微信的独立部署源码，覆盖安卓、苹果、PC三端，面向需要私有化部署或定制即时通讯能力的开发团队与技术学习者。客户端采用纯原生开发，功能齐全，支持好友、私聊、群聊、朋友圈、红包、语音视频、表情包等；后台基于Java开发，提供Linux、Windows、Docker三种部署方式，支持集群与高并发场景，并内置3DES加密传输、阅后即焚、消息过期销毁等安全机制。资源包共995个文件，包含407个jar（服务端及后台逻辑）、342个png与52个gif（界面与表情资源）、49个js和40个css（前端页面）、8个bat及4个sh（启动部署脚本）、5个sql（数据库结构）等，整体约383.23MB，目录结构完整，便于按模块研究。已有855人学习下载，适合有Java/移动端基础、希望从零掌握完整IM系统前后端架构的工程师参考。

1. 鸽哒IM是什么：一套能直接交付的三端IM，不只是“源码包”

单聊、群聊、上下线通知、历史消息，这套交互看起来简单，一旦要自研，连接管理和消息可靠性就够喝一壶。鸽哒IM就是这样一套能直接绕开重复劳动的即时通讯系统源码，服务端加上安卓、苹果、PC三端客户端一次给全，而且是全开源形式，适合做私有化IM底座，或者拿它改造成业务消息系统。它的价值不在一行行轮子代码，而在一整套“建连—收发—存储—多端同步”的链路可以本地跑通、按自己业务改。

如果你现在的诉求是“最短时间让产品里多出聊天能力”，这套源码比从零搭服务端再写三端要省钱；如果团队本来就想自研IM，它还能当现成的架构参考。前提是得清楚它的技术边界，别当黑匣子用。这篇就按服务端架构、三端编译、二次开发、踩坑记录、上线验证的顺序展开，每步都给出能直接抄的参数和命令。

2. 先拆骨架再动手：鸽哒IM的服务端架构与三端连接模型

2.1 为什么聊天服务端不能只靠HTTP接口

早期很多团队想走捷径，让客户端每隔几秒轮询一次HTTP接口拿新消息。这种做法在100人以内看不出毛病，用户量一上来，三个问题会同时爆发：轮询带来的无效请求把带宽吃满，消息延迟平均拉到5秒以上，服务端连接数被瞬时峰值打穿。即时通讯的核心是“服务端主动把消息推给客户端”，这一点HTTP短连接天生做不到，需要一条客户端和服务端之间长期保持的TCP长连接。

鸽哒IM这类三端成套的开源IM，服务端骨架一般是“Spring Boot + Netty”或者“Java + Netty + 业务层”的组合。Spring Boot负责对外HTTP接口，比如登录、拉取好友列表、拉历史消息；Netty负责维护长连接，处理客户端的上行消息和下行推送。两层分开有个明显好处：HTTP接口和长连接服务的生命周期不一样，前者随时可以滚动重启，后者一旦重启所有在线用户都要重连，所以连接层要独立部署、独立扩缩容。

决定长连接质量的有三个参数：心跳间隔、读空闲超时、消息编解码。心跳间隔我一般设30秒，客户端在后台被系统挂起时心跳会停，服务端读空闲超时设90秒，超过就主动断开，把连接让给活着的用户。Netty的IdleStateHandler配置直接决定“僵尸连接”清理效率，这段配置是整个连接层最容易被忽略又最影响在线率的地方。

2.2 协议层与接入层：一台服务端如何同时服务三端

安卓原生、iOS原生、PC端（Electron或Qt）是三种完全不同的运行环境，但它们连到服务端后，走的必须是一套统一的通信协议。鸽哒IM这类源码的做法一般是这样：服务端定义一套JSON格式的消息包，安卓和iOS用自研的Socket客户端收发这套包，PC端因为跑在Chromium里，通常用WebSocket接入，但业务消息体仍然对齐同一套JSON结构。服务端只认协议不认端型，端型只影响登录握手时上报的deviceType字段。

协议里必须包含的字段，我列在下面这张表里，这也是大多数IM协议的标准骨架：

客户端发消息时把这条JSON塞进TCP帧，服务端解包后先做合法性校验，再走消息路由。粘包和半包问题由Netty的LengthFieldBasedFrameDecoder解决，这也是为什么不要在业务层再手写拆包逻辑的原因——框架已经处理好的事，自己重复做反而容易埋坑。

2.3 数据层设计：用户、关系、消息三组表的分工

聊天的数据层和普通业务系统有个明显差别：消息表是持续增长的超大表，用户和关系链是相对稳定的热数据。所以表设计不能全塞在一个库里。鸽哒IM这类源码一般把数据分成三块：用户信息表、关系链表、消息记录表。

用户表看的是账号和资料，关系链表看的是好友和群成员关系，消息表看的是聊天记录。常见表结构如下：

• im_user：user_id、user_name、password_hash、nick_name、avatar、status、create_time
• im_friend：owner_uid、friend_uid、remark、is_top、create_time
• im_group：group_id、group_name、owner_uid、avatar、create_time
• im_group_member：group_id、uid、role、mute_flag、join_time
• im_message：msg_id、chat_type、from_uid、to_uid、msg_type、content、msg_time、status

消息表不建议和业务表混在一个实例里。超过千万级消息后，单表查询性能会快速下降，常见做法是按月分表或者按聊天类型分表，历史消息单独走归档库。这套源码如果后续要接数据大屏或者质检系统，消息表单独拆出来也更方便同步。

3. 本地跑通鸽哒IM：服务端部署与三端编译的完整命令

3.1 部署环境准备：JDK、MySQL、Redis 和端口规划

把鸽哒IM源码包解压后，先别急着编译，先做环境准备。服务端依赖的东西不多，但版本要对上。JDK用1.8或11，MySQL用5.7以上的版本并且字符集必须切到utf8mb4，Redis用3.x以上。这三个版本如果不对，后面编译通过也会在启动时报各种玄学错误。

端口规划尽量保持默认，省得改配置改出低级问题。一般IM服务端至少需要四个端口：HTTP接口8080、长连接服务8088、管理后台8089、可选的文件服务8090。如果本机8080被其他服务占用了，优先杀掉占用进程而不是改端口，因为三端代码里可能写死了默认地址，后面排查起来非常麻烦。

数据库初始化前需要确认MySQL的max_allowed_packet参数。消息内容偶尔会塞大字段，比如图片Base64或者长文本，默认的4MB可能不够。我一般在my.cnf里把它调到64MB，消息系统高峰期大包收发才不会翻车。

# 调整MySQL参数，重启后生效 # [mysqld] # max_allowed_packet = 64M # character_set_server = utf8mb4

3.2 初始化数据库并启动服务端

初始化数据库是第一步，这一步走不顺后面全部白搭。源码的deploy目录下一般带init.sql，如果没带，就根据实体类自动建表。用命令行导入时要注意：不要把整个init.sql盲目执行，先看一眼里面有没有多余测试数据。

# 1. 创建数据库实例，字符集用 utf8mb4 mysql -uroot -p -e "CREATE DATABASE geda_im DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;" # 2. 导入初始化表结构 mysql -uroot -p geda_im < deploy/sql/init.sql # 3. 构建服务端工程 cd server mvn clean package -DskipTests # 4. 启动服务端，关键参数直接写在启动命令行里 java -jar target/im-server.jar \ --spring.profiles.active=prod \ --server.port=8080 \ --im.netty.port=8088 \ --spring.datasource.url="jdbc:mysql://127.0.0.1:3306/geda_im?useUnicode=true&characterEncoding=utf8mb4" \ --spring.datasource.username=root \ --spring.datasource.password=yourpassword \ --spring.redis.host=127.0.0.1 \ --spring.redis.port=6379

这里几个参数值得说明：im.netty.port就是长连接服务监听的端口，三端客户端配置里填的也是这个。spring.datasource.url里必须带characterEncoding=utf8mb4，否则中文消息会变成乱码，这是老IM项目最常见的低级坑。Spring Boot加载外部参数的方式不止命令行一种，也可以用application-prod.yml文件，但命令行带参在排障时更直观，环境变量和配置文件不一致的问题能少一半。

启动日志里看到“Netty server started on port 8088”和“Spring Boot started successfully”两行，就说明服务端活了。这时候可以用telnet或者nc测一下长连接端口通不通，不用急着启动客户端。

3.3 Android 编译：从工程到可安装APK

安卓端编译前需要确认本机有没有Android SDK环境变量。源码工程里一般有local.properties文件用来记录SDK路径，这个文件不在git里，需要自己创建。

# 在 android 目录下创建 local.properties cat > android/local.properties << EOF sdk.dir=/Users/yourname/Library/Android/sdk EOF # 命令行构建 release 包 cd android ./gradlew assembleRelease # 输出路径 # app/build/outputs/apk/release/app-release.apk

gradle第一次跑会自动下载依赖，耗时取决于网络状况，大概率遇到依赖下载失败的情况。如果卡在某个库上下不来，别反复重试，先检查gradle仓库配置是不是用的国内镜像源，把repositories里的仓库地址替换成阿里云镜像，成功率翻倍。构建成功后在Android模拟器上先跑一遍，模拟器里验证登录、单聊、群聊三个主流程，确认长连接端口通着再上真机。

3.4 iOS 与 PC 端：Xcode 归档和 Electron 打包

iOS端编译比安卓多了两件事：CocoaPods安装依赖和Xcode签名配置。如果没有装过CocoaPods，先装再说。进入ios目录后执行pod install，生成xcworkspace工程文件，之后所有操作都在这个workspace里做。

cd ios pod install --repo-update open IMClient.xcworkspace

在Xcode里把Bundle Identifier改成自己的，然后在Signing & Capabilities里勾选Automatically manage signing，选中自己的开发者账号。真机调试时如果报“The file couldn’t be opened because you don’t have permission”，是证书和描述文件不匹配，去Apple Developer后台重新生成描述文件就好。发布时选Product → Archive，然后Distribute App，选App Store Connect上传。

PC端一般是Electron套壳。它复用的逻辑最多，但编译时长也不短。npm install如果慢，先切到国内npm源再装。

cd pc npm install --registry=https://registry.npmmirror.com npm run build:prod

Electron打包完后会生成安装包，Windows下是exe或msi，macOS下是dmg。PC端连服务端时走WebSocket，地址配置在pc/src/config.js里，别写成localhost，真机连局域网时会被坑死。

4. 改成自己的IM：鸽哒IM二次开发与自定义消息扩展

4.1 接入自己的用户体系：认证改造

开源IM一般自带用户名密码登录，但真实业务场景里用户体系已经在别的系统里了，直接拿IM的用户表重建一套账号体系根本不现实。常见改造思路是：保留IM服务端的用户表，但登录验证走业务系统的接口。

具体做法是在登录接口上做一次适配。客户端传token到IM服务端，IM服务端用这个token去调业务系统的校验接口，校验通过后自动在本地用户表里同步一份用户资料，再给客户端发登录成功的回执。这个逻辑放在HTTP登录接口里改，不碰Netty连接层，风险最小。

// LoginController.java 中的改造思路 @PostMapping("/login") public Result login(@RequestBody LoginRequest req) { // 1. 先调业务系统的 token 校验接口 AuthResult auth = authService.validateToken(req.getToken()); if (!auth.isValid()) { return Result.error("token invalid"); } // 2. 同步或创建 IM 用户 IMUser user = userRepository.findByBizUid(auth.getUid()); if (user == null) { user = userRepository.create(auth.getUid(), auth.getNickName()); } // 3. 生成 IM 内部会话 token 并返回 return Result.ok(v1Api.createSession(user.getUserId())); }

这套改造里有个必须注意的事：业务系统返回的uid和IM内部的userId要做映射，不能直接把业务uid塞进IM协议里。否则以后做跨系统用户合并或数据迁移时，到处都要改，那时候就真没有后悔药了。

4.2 自定义消息类型：从服务端分发到三端渲染

IM系统做到后面都会遇到一个需求：普通文本消息不够用，要发位置、发名片、发订单卡片。很多团队第一反应是往content字段里塞JSON，然后各端解析JSON自己渲染。这个思路对，但要注意msgType必须单独占一个字段，而不能在content里塞一个type字段让客户端自己判。因为消息要做历史检索、做未读红点、做统计报表，都依赖msgType这一列做索引，塞在content里这些场景全部要重写SQL。

自定义消息类型一般约定在100以上的整数值，100以下留给系统内置类型。服务端分发逻辑里加一个扩展分支：

// MessageDispatcher.java 中扩展自定义消息入口 switch (packet.getMsgType()) { case 1: // 文本 textService.handle(packet); break; case 2: // 图片 mediaService.handle(packet); break; default: // 100 以上为业务自定义类型，统一走扩展网关 if (packet.getMsgType() >= 100) { customMessageGateway.handle(ctx, packet); } else { // 未知类型，记录日志并丢弃 log.warn("unknown message type: {}", packet.getMsgType()); } }

安卓端收到自定义消息后，不建议在IM客户端的主代码里堆满各种业务渲染判断。更干净的做法是定义一个消息渲染插件接口，业务模块按类型注册渲染器。这样IM源码的升级和维护跟业务代码完全解耦，以后换肤或者做白标也会顺手得多。

4.3 离线消息、已读回执和多端同步的改动顺序

这三块是IM从“能用”到“好用”的分水岭。离线消息逻辑一般在服务端的消息入库时顺带处理：消息写入MySQL后，查一下接收方是否在线，在线走长连接推送，不在线就只入库，等对方下次上线拉取。这个逻辑简单，但要注意离线消息的拉取接口要带上时间游标，不能每次全量拉，否则用户离线一天回来能拉几万条消息，直接打崩客户端。

已读回执的改动要小心。已读状态适合放在Redis里用hash结构维护，键是会话ID，值是已读到的消息ID。聊天列表的未读数可以实时从Redis里取，不用每次查MySQL。PC端和手机端同时在线时，已读状态要双向同步，这个稍有不慎就会引发“手机读了PC还显示红点”的尴尬局面。

多端同步的核心是服务端按设备维度维护消息拉取游标。每个设备都有自己的last_msg_id，哪一端上线就按自己游标往后拉。别共用同一个游标，否则先上线的设备会把新消息拉走，后上线的设备一条都收不到。

5. 集成后期最容易翻车的5个坑：鸽哒IM排查记录

5.1 现象：客户端连上两分钟就断开

跑通demo后，安卓端连接服务端，在线状态撑不过两分钟就掉线，日志里全是“channel inactive”或者空指针。排查了一圈发现，客户端心跳是30秒一次，但服务端读空闲超时设的是45秒。表面上没问题，可客户端在锁屏或切换WiFi的瞬间心跳包发不出去，服务端先判定超时把连接关了。

解决方式是把客户端心跳缩短到20秒，服务端读空闲阈值放宽到90秒，再不放心就再加一层重连退避策略：断线后第一次重连延迟1秒，之后指数递增，最大不超过30秒。这样WiFi切换造成的瞬时断网可以自动恢复。

5.2 现象：iOS退后台后收不到离线推送

iOS端退到后台后，系统很快就断开Socket连接，这时候只能靠APNs推送。很多人在这一步卡住：明明配置了推送证书，服务端也发了推送，但手机就是收不到。最常见的原因是证书环境搞混了——开发环境用了生产证书，或者反之，APNs的feedback服务就会静默丢弃。

解决方式是先在苹果开发者后台确认当前App的Bundle ID和推送证书匹配，再检查服务端推送配置里的environment字段是development还是production。调试阶段用development，TestFlight和上架版本用production，这个开关配错一次会耽误一整天。

5.3 现象：PC端挂几天内存涨到2GB

Electron客户端连续挂机两三天，内存从500MB一路涨到2GB，聊天列表滚动越来越卡。查下来发现消息列表组件把所有历史消息都渲染在DOM里，聊天一多，每个消息节点的图片、头像、气泡全占着内存不释放。

解决方式是给消息列表换虚拟滚动组件，只渲染可视区域内的消息节点。另外，图片消息的缩略图文件缓存在内存里也不能无限堆积，凡是超过三天的图片缓存统一清理掉。这套改动做完，PC端长时间挂机内存基本能稳定在600MB以内。

5.4 现象：历史消息越翻越慢，翻到100页就卡

消息记录翻得越深，响应越慢，翻到一百多页时请求直接超时。问题出在分页查询SQL上，用了传统的offset分页，每次翻页MySQL都要把前面所有行扫一遍，翻的页数越多成本越高。

解决方式是改成游标分页，查询条件不再用页号，而是传上一页最后一条消息的msg_id或msg_time：

-- 改之前（深分页性能差） SELECT * FROM im_message WHERE chat_type = 0 AND to_uid = '10001' ORDER BY msg_time DESC LIMIT 20 OFFSET 4000; -- 改之后（游标分页，走索引） SELECT * FROM im_message WHERE chat_type = 0 AND to_uid = '10001' AND msg_time < '2024-06-01 12:00:00' ORDER BY msg_time DESC LIMIT 20;

游标分页需要msg_time和to_uid的联合索引，没有索引照样慢。迁移脚本里把这条联合索引创建好，历史消息查询的响应时间能从秒级降到毫秒级。

5.5 现象：手机和PC同时在线，消息只在一边出现

同一个账号在安卓手机和PC上同时登录，PC端能收消息，手机端收不到，或者反过来。查服务端日志发现，消息推送之后立刻被标记为“已送达”，但实际上只推给了最后登录的那个设备。

问题在于在线状态管理把“用户”和“连接”当成一对一维护了。一个用户多端登录后，应该维护的是uid到多个channel的映射，推送时遍历所有channel广播，而不是只推最后一个。同时在离线消息游标上也要按设备区分，每个设备记自己的last_msg_id，这样任何一端上线都能补齐自己缺的消息。这个改动涉及在线状态表和推送逻辑，建议放在二次开发的第一优先级。

6. 上线前必做的压测与验证：让鸽哒IM扛住真实并发

6.1 先做连接压测：看服务端能撑住多少在线连接

压测不要一上来就测消息吞吐，先测连接能力和心跳保活。用一段脚本模拟几百上千个客户端同时建连，观察服务端有没有报连接数超限、内存有没有异常上涨。

# 简易连接保活压测脚本 import socket import time import threading HOST = "127.0.0.1" PORT = 8088 CONNECT_COUNT = 500 # 模拟 500 个在线设备 def connect_one(idx): s = socket.create_connection((HOST, PORT), timeout=10) login = f'{{"cmd":1,"uid":"user_{idx}","deviceType":"android"}}'.encode() s.send(login) time.sleep(30) # 持续保持连接 30 秒 s.close() threads = [] for i in range(CONNECT_COUNT): t = threading.Thread(target=connect_one, args=(i,)) t.start() threads.append(t) time.sleep(0.01) # 限流创建线程，避免触发服务端 SYN 队列保护 for t in threads: t.join() print("连接压测完成")

这个脚本里0.01秒的间隔是为了模拟真实用户逐步上线，瞬间涌入500个连接会让服务端触发保护机制，测出来的结果不真实。压测时一边跑脚本，一边在服务端看GC日志和连接数曲线，连接数稳定、GC没有频繁Full GC，才算通过。

6.2 消息可靠性验证：不丢、不重、不乱序

连接压测通过后再测消息链路。消息可靠性的验证思路很简单：客户端A给客户端B发100条消息，B端统计收到的条数和顺序，看有没有丢消息、有没有重复、有没有乱序。但要做成自动化，不然每轮发版都手工测一遍不现实。

我通常会写一个带消息号校验的测试用例，每条消息的消息体里带上递增的序号。接收端把收到的序号写入Set，最后比对Set里的元素和发送序号范围，缺的说明丢消息，重复的说明没去重干净，乱序的看时间戳。这套用例挂在CI上，每次服务端代码变更都会自动跑一遍，比上线后靠用户反馈省心得多。

6.3 上线配置核对清单与第一周的观察指标

上线前最后做一遍配置核对，我按下面的清单过，少一项都不敢上生产：

上线后第一周别只盯着在线人数，重点看三个指标：长连接掉线率、消息推送延迟P95、离线消息补拉成功率。这三项能反映IM系统最核心的健康状态。掉线率突然升高先看网络层有没有抖动，推送延迟升高先看服务端GC和Redis响应时间。我吃过一次亏，上线第一天只看在线峰值，结果某一个地区用户的掉线率已经飙到15%都没察觉，第二天用户反馈才暴露。现在我的习惯是上线后第二、第三天各拉一次全链路日志，把心跳、推送、离线补拉三个时间点拼在一起看，一段链路整体耗时超过两秒就要回去查。这个检查习惯救了我好几次，也希望能帮你在鸽哒IM的落地过程中少走这些弯路。

本文还有配套的精品资源，点击获取