四端IM即时通讯源码部署实战：环境配置、长连接与联调排错

简介面向具备一定开发经验、希望自建即时通讯系统的技术人员这份视酷酷信IM源码提供安卓、苹果、PC与Web四端互通方案采用国产tio通信技术可用于搭建私域聊天平台或作为二次开发底稿。包内共9个文件以6个txt解析文本为主辅以1个doc、1个html和1个jpg压缩包约99KB文本侧重系统架构、四端互通与双空间切换代码实现等说明html和doc便于整理阅读图片可作界面或结构示意参考。已有500人学习适合对照教程理解部署流程、服务端与客户端通信逻辑以及Java、OC、C#、Vue多语言端的组织方式。源码支持修改与扩展可参考MongoDB数据存储、CentOS 7.6部署环境及单机万人并发、集群扩展等描述用于评估自身业务落地和二次开发加商城等需求同时强调无后门与私有服务器部署的数据安全考量。1. 从白屏到跑通视酷酷信 IM 即时通讯源码四端部署的第一道坎去年帮一个小团队部署视酷酷信即时通讯这套 IM 即时通讯源码四端互通的那种服务端加 Android、iOS、PC、H5。文档给得不算敷衍结果第一晚就翻车——服务端起来了H5 用 Safari 打开一片白屏iOS 装完包登录一直转圈PC 端能登进去但发不出消息。三个现象看着是三件事查下去发现是同一个根源环境版本和配置项没对齐。这类全端源码最容易出问题的地方往往就在于你以为装完 PHP 就结束了。它适合手上有点动手能力、打算自己部署一套即时通讯做二次开发的人照着这条线往下走能少熬几个晚上。2. 环境清单钉死Nginx、PHP、MySQL、Redis 与四端编译环境各装哪版装这套东西最忌讳边装边改版本。源码包的部署文档一般只写一个区间比如“PHP 7.x”“MySQL 5.7 以上”真到机器上必须自己收窄到具体分支。我的做法是在动手前把整张清单写在纸上装一台记一台后面哪一步报错能立刻定位到是不是版本背锅。2.1 服务端四件套的版本取舍和扩展清单服务端是典型的 Nginx PHP MySQL Redis 组合长连接另起一个常驻进程。PHP 我一般锁 7.4 或 8.0 这两个分支8.1 往上要慎重很多带年份的老源码里in_array、strpos、strlen(null)这类隐式转换会直接抛 deprecated 甚至中断流程。MySQL 走 5.7 或 8.0 都行字符集必须是utf8mb4——聊天消息里有表情utf8三字节存不下写进去就是问号或者直接报错。Redis 5 以上用来放 token、在线状态和消息队列缓存。Nginx 1.18 往上随便挑。装完 PHP 第一件事不是跑站点是数扩展。这套系统至少要求fileinfo、redis、sockets、pcntl、posix、mbstring、pdo_mysql、openssl、curl、gd、bcmath十一个。少一个都可能是致命的那种。# 先看 PHP 版本再逐个确认扩展有没有真的加载 php -v php -m | grep -E fileinfo|redis|sockets|pcntl|posix|mbstring|pdo_mysql|openssl|curl|gd|bcmathphp -m列出来的是实际加载的模块不是 php.ini 里写了就算数。这里面sockets、pcntl、posix三个最容易被漏掉因为它们跟普通的 Web 请求没关系只有长连接进程启动时才用到。缺sockets的表现是进程启动后直接退出日志里就一行干巴巴的启动失败没有堆栈属于典型的问题现场。补装扩展的写法按系统源不同CentOS 系常见是# 扩展名以源里的包名为准装完记得重启 php-fpm yum install -y php74-php-redis php74-php-sockets php74-php-pcntl \ php74-php-posix php74-php-bcmath php74-php-gd systemctl restart php74-php-fpmMySQL 8.0 有个绕不开的坑默认认证插件是caching_sha2_password一些老版本 PHP 的pdo_mysql根本握手不上报的是“Authentication plugin cannot be loaded”这类看起来跟密码无关的错误。解决办法是建完业务账号后单独把它切回mysql_native_password这个放到下一章建库时一起做。Redis 别裸奔。至少设requirepassbind只留127.0.0.1protected-mode yes。装完用一条命令验# 返回 PONG 才算通返回 NOAUTH 说明密码没带上 redis-cli -h 127.0.0.1 -a 你的密码 ping2.2 四端各自的编译环境别想着用一台机器全搞定四端互通听着完整落地时是四套截然不同的环境。H5 端最轻不需要编译改完配置扔到站点目录就能跑。但对环境最挑必须是 httpsWebSocket 必须走 wss否则在 Safari 和各类内嵌浏览器里直接被拦。证书可以是正式的也可以内网自签自签的话 Safari 会先弹一次警告接受之后才继续。Android 端要 Android Studio具体版本跟工程里的 Gradle 插件版本绑定。判断方法很简单打开工程先看build.gradle里的classpath com.android.tools.build:gradle:x.x.x插件版本决定 JDK比较老的一套工程一般配 JDK 8 或 11新一点的配 17。JDK 装错版本症状是同步阶段就红一片根本走不到编译。iOS 端要 Xcode而且必须在 macOS 上做。这里有个硬性约束要提前想清楚如果应用要上架接口就必须是 httpsiOS 的 ATSApp Transport Security默认会拦掉所有明文请求。有人图省事在Info.plist里开NSAllowsArbitraryLoads本地调试确实通了审核时大概率被退回。我的习惯是调试期单独配NSExceptionDomains白名单只放测试域名上线前删干净。PC 端看源码包里给的是什么形态。给的是工程源码就要对应的打包环境给的是现成安装包那 PC 端的工作就只剩改服务地址和清缓存两件事。2.3 端口和目录一次规划定死后面不再改这套东西涉及端口不少装到一半改端口是自找麻烦因为改一处要连带改配置文件、Nginx 反代、四端的接口地址。开头就定好端口用途是否对外备注80HTTP仅用于跳转 https是全站强制跳转443HTTPS 站点是H5 与全部接口入口9000php-fpm否只监听 127.0.0.13306MySQL否只监听 127.0.0.16379Redis否必须设密码8282长连接服务否由 Nginx 的 wss 反代出去目录也顺手定死。我一般放/www/wwwroot/imroot指向里面的public目录而不是项目根目录理由是.env、runtime、日志这些不该被公网直接下载到。这个习惯看起来多余但少一次目录穿越就少一次事故。3. 服务端落地从建库到长连接进程守护的六个配置项服务端这步是整个部署的重心四端能不能连上全看这里。我把这一步拆成四个动作建库导数据、配站点、改配置、起进程每步都有验证点走完一步验一步别攒到最后一起查。3.1 建库、导 SQL 与 MySQL 8.0 的认证插件回退先建库。字符集和排序规则在这里就必须定对后面改要导数据重来。-- 建库时锁定 utf8mb4表情和生僻字都能存 CREATE DATABASE im_core DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; -- 业务账号只允许本机连别开 % 通配 CREATE USER im_user127.0.0.1 IDENTIFIED BY 替换成十六位以上的强密码; -- MySQL 8.0 特有把认证插件切回 mysql_native_password否则老 PDO 连不上 ALTER USER im_user127.0.0.1 IDENTIFIED WITH mysql_native_password BY 替换成十六位以上的强密码; GRANT ALL PRIVILEGES ON im_core.* TO im_user127.0.0.1; FLUSH PRIVILEGES;127.0.0.1这个主机位不要图省事写成%。IM 的库里有全部聊天记录暴露面越小越好。最后一句FLUSH PRIVILEGES是刷新权限缓存改完账号权限不执行这句新权限可能不生效排错时容易误判。导数据时带上字符集参数否则中文表名或注释可能乱码# --default-character-set 必须显式指定默认值在部分客户端上是 latin1 mysql -h 127.0.0.1 -u im_user -p --default-character-setutf8mb4 im_core install.sql导入完成后核对一遍三个值都应该是utf8mb4SHOW VARIABLES LIKE character_set%; -- 重点看 character_set_client / character_set_connection / character_set_database如果导完发现中文是问号别急着重新导先看这三个变量。多数情况是客户端字符集问题数据本身没坏重导一遍就行但如果表结构建的时候就用了utf8那必须重建表改不了。3.2 站点配置root 指向、伪静态和那行必须给足的超时Nginx 的配置决定了这个站点能不能正常访问、长连接会不会掉。下面这份是我压过的版本server { listen 443 ssl http2; server_name im.example.com; # 换成自己的域名 root /www/wwwroot/im/public; # 指到 public不是项目根 index index.php index.html; ssl_certificate /etc/nginx/ssl/im.pem; ssl_certificate_key /etc/nginx/ssl/im.key; # 上传大小三处联动中的 Nginx 这一处语音和图片都要过 client_max_body_size 24m; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { fastcgi_pass 127.0.0.1:9000; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } # 长连接的 wss 反代路径以源码里的配置为准 location /ws { proxy_pass http://127.0.0.1:8282; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_read_timeout 3600s; # 这个值给不够连接会被周期性掐断 } }proxy_read_timeout是这份配置里最容易被忽略的一行。默认 60 秒意味着长连接每分钟被断一次客户端要不停重连。表现出来不是报错而是“消息延迟一会儿才收到”“在线状态一会儿绿一会儿灰”查起来非常费劲。给到 3600 秒配合客户端心跳链路才稳。try_files那行是伪静态少了它除了首页之外的路由全部 404。目录权限单独说一下很多人的 500 错误就是这里来的# 目录 755、文件 644只给 runtime 和上传目录写权限 chown -R www:www /www/wwwroot/im find /www/wwwroot/im -type d -exec chmod 755 {} \; find /www/wwwroot/im -type f -exec chmod 644 {} \; chmod -R 775 /www/wwwroot/im/runtime chmod -R 775 /www/wwwroot/im/public/uploadschmod -R 777是省事但别用。整套源码之后还要做二次开发权限放太开后面接手的人排查问题会更痛苦。3.3 配置文件里必须逐项确认的六处源码的配置一般在项目根目录的.env或者config目录下字段名各家不同但需要改的东西就这六类配置项典型值不填会怎样数据库地址/库名/账号127.0.0.1 / im_core首页直接 500数据库密码上一步设的强密码连接失败报驱动异常Redis 地址/密码127.0.0.1:6379 密码登录能过但发消息无响应站点域名https://im.example.com图片、语音地址拼成内网 IP四端都显示不出来长连接地址wss://im.example.com/wsH5 端连不上原生端走 TCP 可能正常时区Asia/Shanghai消息时间差八小时群里会吵时区这项特别值得单说。PHP 的date.timezone和 MySQL 的time_zone是两套东西只改一个还是错。我的做法是两边都写死并且在代码入口统一调用date_default_timezone_set三处一致才不出问题。这套系统涉及聊天记录时间戳、消息排序差八小时不是显示问题是消息顺序可能整体错乱。顺便把上传限制三处一起改掉只改一处等于没改; php.ini upload_max_filesize 20M post_max_size 24M date.timezone Asia/ShanghaiNginx 那处client_max_body_size前面已经写了。三处的关系是层层设限最小的那个决定实际能传多大。3.4 长连接进程与守护别用 nohup 了长连接服务是常驻进程不是 fpm 那种来一个请求起一个的模式。启动命令以源码包内自带的启动脚本为准常见形态是根目录下的start.php带start / stop / restart / status参数。开发期直接前台跑看日志跑通后必须交给系统守护。nohup ... 能用但机器重启就没了进程挂了还得人工发现。我现在一律写 systemd[Unit] Descriptionim long-connection worker Afternetwork.target mysql.service redis.service [Service] Typesimple Userwww Groupwww WorkingDirectory/www/wwwroot/im ExecStart/usr/bin/php /www/wwwroot/im/start.php start ExecStop/usr/bin/php /www/wwwroot/im/start.php stop Restartalways RestartSec5 StandardOutputappend:/var/log/im-worker.log StandardErrorappend:/var/log/im-worker.err [Install] WantedBymulti-user.target几个参数值得说Restartalways加RestartSec5是自动恢复的关键进程崩了 5 秒后拉起来避免疯狂重启打满 CPU。After里带上 mysql 和 redis是为了避免开机时进程比数据库先起连不上就退出然后一直循环。日志单独指到文件跟站点日志分开出问题的时候能直接tail -f。启用并验证systemctl daemon-reload systemctl enable --now im-worker # 状态是 active (running) 才算起restart 计数一直在涨说明在反复崩 systemctl status im-worker4. 四端联调H5 在 Safari 上的兼容项与 Android、iOS、PC 的接口改造服务端跑通只是开始四端联调才是真正花时间的地方。四端里 H5 最麻烦因为它跑在别人家的浏览器里而 Safari 的脾气跟 Chrome 差得不是一点半点。4.1 H5 端域名、wss 和 Safari 上必查的五处H5 部署本身没有编译步骤把构建产物放到站点目录就能访问难点全在配置和兼容。第一件事是把接口地址全部改成 https 域名包括 WebSocket 地址必须是wss://。在 Safari 里https 页面去连ws://会被静默拦截控制台可能只留一行不痛不痒的警告表现就是“登录成功但消息永远发不出去”。第二件事是时间解析。这是 Safari 上最经典的一个问题后端返回2024-05-01 10:20:30这种带短横线的格式Safari 的new Date()解析结果是Invalid DateChrome 却正常。聊天列表的时间显示全变 NaN看起来像后端问题其实是浏览器差异。// Safari 不认 2024-05-01 10:20:30 这种带短横线的时间串 // 统一换成斜杠再交给 Date 解析四端表现才一致 function parseServerTime(str) { if (!str) return null; // iOS 上还可能是带 T 的 ISO 格式一并归一化 const normalized String(str).replace(/-/g, /).replace(T, ); const d new Date(normalized); // 解析失败时兜底为当前时间避免列表整片显示 NaN return isNaN(d.getTime()) ? new Date() : d; }第三件事是语音消息播放。Safari 禁止没有用户手势的自动播放audio.play()在没有用户交互的情况下会返回一个 rejected 的 Promise。解决办法是把播放绑到点击事件里并且先load()再play()同时把 Promise 的 catch 接住失败时给个“再点一次”的提示别让用户以为没反应。// 语音播放必须由用户手势触发先在 click 里 load 再 play playBtn.addEventListener(click, () { audio.load(); const p audio.play(); if (p ! undefined) { // Safari 会拒绝无手势的播放这里必须接住否则控制台报未捕获异常 p.catch(() { showToast(请再点一次播放); }); } });第四件事是登录态。Safari 的隐私策略对第三方 Cookie 卡得很严如果 H5 和接口不同域登录后用不了多久就掉线刷新一次要重登一次。我的做法是尽量让 H5 和接口同主域跨域时把 Cookie 的SameSite和Secure显式写清楚别指望默认值。第五件事是输入框。iOS 上键盘弹起会把整个页面顶上去聊天气泡错位键盘收起后不回落。处理方式是监听resize和focus/blur在键盘弹出时把消息列表容器高度改成window.innerHeight算出来的实际值而不是写死100vh——Safari 的100vh包含地址栏高度这是老问题了。4.2 Android 端包名、签名和接口地址三处联动Android 端要改的地方不多但每处都不能漏。包名applicationId一旦改掉推送、第三方登录的回调配置都要跟着改所以建议在正式打包之前就定死别等到上架前再动。接口地址一般集中在某个常量类或者build.gradle的buildConfigField里。用buildConfigField的好处是能按 debug / release 分环境不用手工改// 按构建类型区分接口地址避免测试包连到生产 android { buildTypes { debug { buildConfigField String, API_BASE, \https://im-test.example.com\ } release { buildConfigField String, API_BASE, \https://im.example.com\ } } }带 WebSocket 的还要单独配一个WS_BASE值是wss://开头。有人只改了API_BASE登录通了但消息不走就是漏了这一项。签名这块release 包必须用正式 keystoredebug 签名打出来的包在某些机型上装都装不上。keystore 文件和密码单独保管不要跟着源码一起传这是血泪经验——换一次签名等于所有已装用户必须卸载重装。4.3 iOS 与 PC 端ATS 配置和缓存清理iOS 端除了前面提到的 ATS还要注意最低支持版本。工程里的IPHONEOS_DEPLOYMENT_TARGET如果设得太高老设备装不上设得太低某些新 API 又要加一堆available判断。按目标用户群的设备情况定别照抄别人的配置。ATS 的写法前面说过用NSExceptionDomains白名单而不是全放开!-- 只对测试域名开例外上线前整段删掉 -- keyNSAppTransportSecurity/key dict keyNSExceptionDomains/key dict keyim-test.example.com/key dict keyNSIncludesSubdomains/key true/ keyNSTemporaryExceptionAllowsInsecureHTTPLoads/key true/ /dict /dict /dictPC 端最容易出问题的不是代码是缓存。改完服务地址重新打开还是连旧服务器通常是本地缓存或者配置文件没跟着更新。我一般让测试的同学在改地址后清一次应用数据目录确认配置文件里写的是新地址再启动。5. 排错现场装完打不开的五个典型现象与处置顺序这类四端系统出错时报错信息往往指向错误的地方。按下面这五条对号入座能省掉大量瞎猜的时间。现象一首页 502或者浏览器提示“No input file specified”。原因基本锁定在三处root指到了项目根目录而不是publicfastcgi_param SCRIPT_FILENAME那一行漏了或者写错再就是 php-fpm 根本没起来。解决顺序是先systemctl status php-fpm看进程再nginx -t看配置语法最后看 Nginx 的error.log那里会明确写“connect() failed”还是“Primary script unknown”。前者是 fpm 没起后者是路径不对。现象二登录一直转圈Network 面板里 socket 请求失败或者返回 400。这是长连接没通。检查顺序先用curl -i -H Upgrade: websocket -H Connection: Upgrade https://域名/ws看返回是不是 101不是 101 就是 Nginx 反代没配对再看长连接进程是不是活着最后确认客户端连的是wss://不是ws://。Safari 这类浏览器对混合内容卡得很死https 页面连明文 ws 会被直接拦掉控制台那行警告很容易被忽略。现象三消息发出去对方刷新后才看得到实时收不到。典型的常驻进程问题。systemctl status im-worker看Active和重启计数如果计数一直在涨说明进程起来就崩。多半是缺sockets或pcntl扩展或者 Redis 连不上。看/var/log/im-worker.err前面几行通常就有答案。还有一种情况是进程活着但业务逻辑崩在某个回调里这时候看它自己的业务日志别只看系统日志。现象四图片、语音上传失败接口返回 413 或 500。三处大小限制没对齐php.ini的upload_max_filesize、post_max_size还有 Nginx 的client_max_body_size。改完必须重启 php-fpm 和 reload nginx只改文件不重启等于没改。另外确认上传目录有写权限且用户是 wwwroot跑的应用写出来的文件后面会各种权限报错。现象五Safari 上登录态反复丢失Chrome 却一切正常。前面提过Cookie 的SameSite和Secure没配好跨域场景下 Safari 直接不存。排查方式是打开开发者工具的资源面板看 Cookie 有没有落下来没落下来就是策略问题跟后端逻辑无关。顺带确认时间戳解析有没有问题登录返回的过期时间如果被解析成Invalid Date前端会立刻判定过期表现也是“登录完马上掉线”。还有一种情况不在这五条里但很常见改完配置不生效。九成是没重启对应服务或者改错了配置文件——同一台机器上装过多个 PHP 版本php.ini有好几份改的是不用那份。php --ini能看到实际加载的是哪个文件。6. 验收跑通用一条消息走完全链路来判定安装成功装完不等于跑通。四端系统最怕的情况是“看起来能用”实际上某个环节已经断了但没人发现上线后用户量一上来就暴露。我验收只做一件事让 A 端发一条消息给 B 端然后沿途每一站都验一遍。具体是这么走的。先在服务端盯四个窗口tail -f /var/log/im-worker.log看长连接日志、tail -f /var/log/nginx/access.log看请求有没有打到反代、redis-cli -a 密码 monitor看有没有 key 写入、mysql -u im_user -p im_core -e select id,from_id,to_id,content,create_time from im_message order by id desc limit 5;看消息落库。然后 A 端发一条带文字、再发一条语音。判定的标准按顺序卡检查点通过标准不通过的定位方向Nginx 日志出现/ws且状态 101反代配置、Upgrade 头worker 日志有连接建立和消息投递记录进程没起或扩展缺失Redis能看到 token 和在线 keyRedis 密码或库号配错数据库新消息 id 递增content有值字符集或写入逻辑B 端无刷新即收到时间显示正确长连接地址、Safari 时间解析语音回流B 端点开能播Safari 上同样能播上传目录权限、播放手势绑定这一步最值钱的地方是它把“谁的问题”切开了。消息进了 Redis 但没进库是消费端的事进了库但 B 端没收到是推送链路的事B 端收到但时间是 NaN是前端解析的事。一路卡一遍问题基本跑不掉。再补两个收尾动作。一是重启机器等所有服务自动起来后再发一条消息验证 systemd 的After依赖配对了没有二是把四端各退出登录再登一次确认退出逻辑清了 Redis 里的在线状态否则会留下“永远在线”的假数据时间长了内存一直涨。从那以后我每次部署这类多端系统不管文档写得多完整上线前都强制走一遍这条发消息的链路哪怕只是改了一个配置项。四端互通的好处是所有端体验一致坏处是任何一处配置错了症状都可能跑到另一个端上表现出来。这套源码本身支持二次开发后面加商城、加功能都要在这个基础上动基线没验干净后面的问题会越堆越难查。希望帮到你。本文还有配套的精品资源点击获取