简介面向具备一定开发基础、希望自建即时通讯系统的技术人员这份资料围绕视酷酷信 IM 源码展开覆盖安卓、苹果、PC 与 Web 四端互通场景并涉及 Java、OC、C#、Vue 等技术栈。内容强调可部署到自有服务器、支持二次开发与功能扩展对数据隐私和后续维护有需求的团队更具参考价值。资源包共 9 个文件以 6 个 txt 解析文本、1 份 doc 说明、1 个 html 页面和 1 张 jpg 配图为主压缩包约 99KB便于先梳理系统结构、通信方案与部署要点。已有 501 人学习适合在正式搭建前了解四端架构、tio 通信技术、MongoDB 数据存储及 CentOS 7.6 环境要求也可作为二开与排错思路的入门参考。1. 拿到视酷酷信 IM 源码先别急着解压四端互通这套环境最容易翻车在哪视酷酷信这套 IM 即时通讯源码很多人第一反应是丢到一台装了宝塔的机器上解压、访问 install、一路下一步然后登录 PC 端发现能进安卓端能进H5 打开就是白屏iOS 上登录成功但消息一条都发不出去——四个端共用一个消息网关任何一处端口、协议、跨域没对齐表现出来的都是「能登录、不能聊」这种半死不活的状态。这不是源码坏了是环境没列清楚就开装。这套东西本质上是 PHP 后端 MySQL Redis 一个常驻的 WebSocket 网关再挂 PC、安卓、iOS、H5 四个前端壳。装它的门槛不在敲命令在于你得先知道每个部件吃什么版本、占哪个端口、谁先起谁后起。适合有 LNMP 底子、打算自己二开加商城或者改业务逻辑的人只想点两下就有人陪你聊天的这套会让你在 Supervisor 日志里熬一晚上。2. 环境清点PHP、MySQL、Redis 与 9502 端口的版本取舍装这类 IM 源码我习惯先把版本和端口写成一张纸贴在屏幕上再动手。原因是它的失败模式特别隐蔽PHP 版本高一个小号某个加密函数行为变了登录接口返回 200 但 token 是空的Redis 没设密码又能被外网访问跑两天被人写进脏数据聊天记录乱序你回头查代码查三天都查不出来。所以第 2 章不装东西只做清点和取舍。2.1 PHP 版本怎么选7.4 稳、8.0 快、8.1 以上先别碰源码包里的说明一般会给一个推荐区间我通常按 PHP 7.4 起步试第一遍跑通了再考虑升 8.0。原因很实在这类带即时通讯、带支付/商城二开能力的源码历史包袱多半在 7.x 时代留下一些老扩展和加密库在 8.1 之后会有废弃警告虽然不致命但会把错误日志刷满真出问题时你的黑匣子被噪音淹了。选 8.0 的唯一理由是性能和新语法如果你确定要二开写不少新代码8.0 更舒服。8.1、8.2 不是不能上是没必要在第一遍装的时候就给自己加变量——先让它跑起来再谈升级。# 确认当前 PHP 版本与关键扩展是否齐全 php -v php -m | grep -Ei pcntl|posix|redis|fileinfo|pdo_mysql|mbstring|openssl这段不是随便敲的pcntl和posix是 Linux 下跑常驻 WebSocket 进程的前提缺了这两个网关进程起来几秒就退出日志里只留一行看不出原因的退出码redis是缓存和在线状态存续用的fileinfo管聊天里图片、语音、文件的上传类型识别缺了它上传接口直接 500pdo_mysql和mbstring属于基础项很多精简版 PHP 镜像会漏。如果pcntl、posix没输出别去网上找偏方直接重装或换一个带完整扩展的 PHP 包然后在 php.ini 里确认这两个函数没被禁用; php.ini 片段常驻进程需要的函数不能进 disable_functions ; 很多人为了安全把整段都禁了结果网关起不来 disable_functions exec,system,passthru,shell_exec ; proc_open、pcntl_* 必须保留Workerman 类网关依赖它们这里是个典型取舍disable_functions禁得越狠越安全但 IM 的常驻进程要靠proc_open拉起子进程、靠pcntl_*做信号处理。我的做法是只禁真正用不到的然后把 PHP 的 running user 降权安全性靠权限补不靠一刀切禁函数。2.2 数据库和缓存的版本与端口规划MySQL 我一般用 5.7 或 8.0两者都能跑差别在排序规则和 JSON 字段。老源码里如果有utf8mb4_general_ci的建表语句导入 8.0 默认排序规则会报警告但不报错能过。真正要盯的是sql_mode-- 装之前先把严格模式放宽否则老建表语句里的零值日期会直接失败 SET GLOBAL sql_mode STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION; -- 导入时统一字符集别让聊天内容里的表情变成问号 -- mysql -uroot -p --default-character-setutf8mb4 im_db im_db.sqlIM 场景里表情符号是高频输入字符集不对用户发的每一个 emoji 都会在入库时被截断前端显示成方块用户会认为你程序有 bug。所以库、表、连接三处都要utf8mb4连接串里也要显式声明。Redis 版本 5 以上就行关键是两件事设密码、只听内网。端口规划我一般这么排部件端口说明Nginx80 / 443站点与 HTTPSH5 端必须 443MySQL3306只对本机或内网开放Redis6379必须设 requirepass禁止 0.0.0.0WebSocket 网关9502对外经 Nginx 反代成 wss网关内部通信9503只跑 127.0.0.1不对外9502 这个数字在同类源码里出现频率很高但不要照抄先看源码配置文件里写的是哪个以包内为准再去 Nginx 和防火墙对齐。我见过最冤的一次翻车是安全组开了 9502Nginx 反代写的 9501前端连了半小时日志里全是 502。2.3 运行账号与目录权限不要用 root 跑网关进程。常见做法是建一个www或imrun账号把站点目录给它日志目录单独给写权限# 建运行账号并交接目录注意别把整个站点给 777 useradd -r -s /sbin/nologin imrun chown -R imrun:imrun /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 /www/wwwroot/im/public/uploadsruntime是框架的缓存和日志目录public/uploads是聊天文件落地的地方这两个必须可写其他目录一律只读。给整个站点 777 是最省事也最容易出事的一步——上传目录可执行脚本等于把半个服务器交出去了。装完第一件事我会去上传目录放一个测试文件试试能不能访问到能直接访问到的.php就说明有大问题。3. 服务端落地上传、伪静态与安装向导的四步走环境清点完进入真正装的部分。这一章的顺序不能乱先定站点根再配伪静态再走安装向导最后把常驻进程托管起来。颠倒顺序的典型后果是安装向导写完了数据库配置你才发现站点根指错了目录得删库重来。3.1 站点根必须指向 public不是源码根目录解压之后你会看到一堆目录其中public才是对外暴露的那一层入口文件在里面。站点根指到源码根目录等于把config、.env、vendor全摊在公网上搜索引擎爬一遍你的数据库密码就上了别人的字典。# 上传并解压解压后先看目录结构再动 Nginx cd /www/wwwroot mkdir im cd im unzip /tmp/im-source.zip -d . ls -la # 确认存在 public/index.php 这类入口再决定站点根解压完先ls一眼看清public在哪一层、有没有多套一层同名目录压缩包里套一层目录是常见现象直接解压会让站点根深一层访问全是 404。Nginx 站点配置大致是server { listen 443 ssl; server_name im.example.com; root /www/wwwroot/im/public; # 关键指向 public index index.php index.html; # 前端路由交给入口文件IM 的 H5 端是单页应用刷新不能 404 location / { try_files $uri $uri/ /index.php$is_args$args; } location ~ \.php$ { fastcgi_pass unix:/run/php/php7.4-fpm.sock; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; } # WebSocket 反代前端连 wss://im.example.com/ws location /ws { proxy_pass http://127.0.0.1:9502; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 600s; # 长连接别用默认 60s会周期性断线 } # 聊天上传的图片语音走静态别绕 PHP location /uploads { expires 7d; add_header Cache-Control public; } }几个参数值得说清楚。try_files那行是给 H5 单页路由兜底的少了它用户在聊天页按 F5 就是 404。proxy_read_timeout 600s是我踩过坑之后固定写上的——默认 60 秒用户切出去看个视频回来连接已经被 Nginx 掐了前端表现为消息不推送、刷新才好。Upgrade和Connection两个头是 WebSocket 握手的前提漏一个前端控制台就报握手失败。fastcgi_pass的 socket 路径要和你机器上实际的 PHP 版本对上写错就是 502。3.2 安装向导数据库信息写在哪、写完之后查什么站点根和伪静态都通了浏览器访问域名一般会跳到安装页。填库名、账号、密码、管理员账号走完会提示安装成功同时生成或改写配置文件。; 配置文件里这几项装完必须逐条核对别只看安装成功 [database] hostname 127.0.0.1 database im_db username im_user password 这里填强密码 hostport 3306 prefix im_ ; 表前缀二开加表时别撞名 charset utf8mb4 ; 少这一行表情全变问号 [redis] host 127.0.0.1 port 6379 password 这里填 requirepass 的值 select 0装完之后我一定做三件事一是mysql -u im_user -p im_db -e show tables;看表是不是真建全了二是访问一次首页确认不是白屏三是把install目录改名或删掉。留着安装入口任何人重新访问都能重装一遍库这是最容易被忽略的后悔药位置。3.3 常驻进程托管Supervisor 比 nohup 靠谱IM 的消息推送靠一个常驻的 WebSocket 网关它不属于 Nginx也不是 PHP-FPM 的子进程得单独起、单独守。nohup php start.php start 能跑但机器重启就没了进程崩了也不会自己回来——IM 最怕的就是看着在跑其实早挂了。; /etc/supervisor/conf.d/im-gateway.conf [program:im-gateway] command/usr/bin/php /www/wwwroot/im/start.php start directory/www/wwwroot/im userimrun autostarttrue autorestarttrue startsecs3 stdout_logfile/www/wwwroot/im/runtime/gateway.out.log stderr_logfile/www/wwwroot/im/runtime/gateway.err.logstartsecs3是给进程一个自检窗口起来三秒内退出就不算启动成功避免死循环重启。userimrun保证它不是 root。日志两个文件分开写排查时先看 err再看 out。supervisorctl reread supervisorctl update supervisorctl status im-gateway tail -f /www/wwwroot/im/runtime/gateway.err.logstatus显示 RUNNING 只是第一步还要tail一下日志确认它真的在监听端口而不是启动后立刻抛异常又被拉起——这种反复重启在 status 里有时也显示 RUNNING。4. 四端联调Safari 上的 H5 端为什么总掉登录态四端里最容易出问题的不是安卓也不是 iOS 原生壳是 Safari 打开的 H5。原因不玄学Safari 对 Cookie、自动播放、后台挂起的策略比桌面浏览器严得多而这些正好是 IM 的命门。4.1 域名与端口规划四端必须指向同一个 API 域名PC 端、安卓、iOS、H5 四个前端只是壳业务接口是同一套。如果 H5 跑在h5.example.com接口在api.example.comSafari 会把接口的 Cookie 当第三方 Cookie 处理登录态写不进去表现就是登录成功一跳转又回到登录页。// 前端配置里统一 baseUrl四端只改这一处 const CONFIG { apiBase: https://api.example.com, // 业务接口 wsUrl: wss://api.example.com/ws, // 必须 wsshttp 页面连不上 upload: https://api.example.com/uploads, timeout: 15000 }; export default CONFIG;关键点两条一是wsUrl必须wssSafari 在 https 页面下禁止连ws://控制台只给你一句含糊的报错二是接口域名尽量和页面同主域用子域而不是完全不同的域名能省掉一大半 Cookie 问题。4.2 Safari 的三处硬限制Cookie、自动播放、后台挂起第一处是 Cookie 的SameSite。后端下发登录态时如果没声明Safari 的默认策略偏保守跨站场景下直接不存。// 登录成功后写 CookieSafari 下这三个参数要一起给 setcookie(im_token, $token, [ expires time() 7 * 86400, path /, domain example.com, // 带上主域子域共享 secure true, // https 下必须 true httponly true, samesite Lax // 同主域用 Lax完全跨站才用 None Secure ]);samesiteNone必须配securetrue否则浏览器直接丢弃这条 Cookie而且不报错——这是最典型的代码看着对、就是登不上。第二处是提示音的自动播放限制。IM 收到新消息要响一声Safari 要求音频必须由用户手势触发过一次才能播。解决办法是在用户点进入聊天时先播一个静音音频解锁// 用一次用户点击解锁音频通道之后才允许自动播放提示音 document.addEventListener(click, function unlock() { const a new Audio(/static/notify.mp3); a.volume 0; a.play().catch(() {}); document.removeEventListener(click, unlock); }, { once: true });第三处是后台挂起。iOS 上的 Safari 切到后台几分钟页面会被冻结WebSocket 连接名义上还在实际已经死了。心跳间隔别超过 25 秒并且监听visibilitychange回到前台立刻重连document.addEventListener(visibilitychange, () { if (!document.hidden) { reconnect(); // 回到前台先重连别等心跳超时 syncOfflineMsgs(); // 拉一次离线消息补齐挂起期间漏掉的 } });syncOfflineMsgs这一步不能省。只重连不补拉用户会看到消息从中间断了一截然后来问你服务器是不是丢数据了。4.3 安卓和 iOS 壳里要改的三个常量原生壳一般是把 H5 打进 WebView或者直连 API。不管哪种打包前有三个地方必须改接口域名、WebSocket 地址、上传地址。改漏一个的典型现象是 App 能登录但发不出图因为上传还指着测试环境的内网 IP。另外 Android 9 以上默认禁止明文 HTTP接口如果还是 http请求直接失败iOS 的 ATS 同理。这不是源码问题是壳的配置问题在打包配置里放开对应域名就行但更正确的做法是接口全上 HTTPS。4.4 PC 端与 H5 端的静态资源缓存PC 和 H5 是同一套前端资源改完代码上线用户说还是老界面八成是浏览器缓存了旧的 JS。做法是给静态资源加版本号或 hashNginx 侧对index.html不缓存location /index.html { add_header Cache-Control no-store; } location ~* \.(js|css|png|jpg|woff2)$ { expires 30d; add_header Cache-Control public, immutable; }入口不缓存、带 hash 的资源长缓存这样每次发版用户拿到的都是新入口老资源自然淘汰不用教用户清缓存。5. 排查装完连不上、消息不发、图片 404 的五种典型现场这一章是我自己攒的排错清单按发生频率排。每条都是现象 → 原因 → 解决的顺序遇到问题从第一条往下对基本能定位。第一条登录成功一刷新就退回登录页。现象是接口返回 200token 也有但页面一跳转登录态就没了。原因九成在 Cookie 没写进去要么domain写成了带 www 的具体子域而前端跑在另一个子域要么samesiteNone却没开secure要么 PHP 的 session 存到了另一个进程读不到的位置。解决方式是打开浏览器开发者工具的 Application 面板看 Cookie 到底存没存、Domain 和 SameSite 是什么值再回头对setcookie的参数。别在代码里猜看实际落地的值。第二条能登录、能拉历史消息新消息一条不推。现象是刷新页面能看到记录但两个人同时在线发出去对方不弹。原因基本是 WebSocket 网关没真正跑起来或者 Nginx 的/ws反代没配对。先ss -lntp | grep 9502看端口在不在听再curl -i -N -H Connection: Upgrade -H Upgrade: websocket https://你的域名/ws看握手返回是不是 101。返回 502 就是反代目标端口写错返回 400 一般是Host头没传。还有一种情况是网关在跑但被防火墙挡了前端连的是公网域名反代走的本机 127.0.0.1这条链路本身不经过防火墙所以要分清是前端连不上还是反代连不上。第三条图片、语音上传成功但显示 404。现象是接口返回上传成功返回的 URL 打开是 404。原因通常是上传目录不在public下或者 Nginx 的location /uploads和实际落盘路径不一致。查法很简单ls -l /www/wwwroot/im/public/uploads看文件到底落在哪再对一下 Nginx 的 root。还有一种少见情况是上传目录权限不对PHP 以www用户跑但目录属主是 root文件建不出来接口却因为没检查返回值而返回成功——这类假成功最坑日志里必须把上传失败的原因打出来。第四条网关进程反复重启日志里只有一行退出码。现象是supervisorctl status一会儿 RUNNING 一会儿 FATAL。原因通常是 PHP 缺pcntl/posix或者disable_functions把proc_open禁了或者启动脚本里写死的端口被别的进程占了。用php -m先确认扩展再ss -lntp | grep 9502确认端口最后用php start.php start前台跑一次错误会直接打在终端上比翻日志快得多。第五条跑一段时间后聊天记录乱序、在线状态全错。现象是刚装好一切正常跑两三天开始出怪事。原因多半是 Redis 没设密码又对公网开放被外部写了脏数据或者 Redis 和业务共用一个库缓存 key 没有前缀二开时和其他模块撞了。解决是立刻给 Redis 设requirepass、绑定 127.0.0.1在配置里指定select到独立库并且给所有 key 加统一前缀。上生产前我还会把源码里的高危函数扫一遍# 装完先自查一遍包内说明标注无后门但自己的环境自己负责 grep -rn --include*.php -E eval\(|base64_decode\(|assert\( /www/wwwroot/im \ | grep -v vendor | head -50grep -v vendor是排除第三方依赖只看业务代码。扫出来的结果不一定有问题但每一处都该能解释清楚它在干什么。6. 验证跑通三个动作确认四端真的通了装完不等于通了。我判断一套 IM 是不是真跑起来只看三个动作缺一个都不算完。第一个动作两个账号互发。开两个浏览器无痕窗口或者一个 PC 一个手机A 发 B 收B 回 A 收文字、图片、语音各来一遍。这一步验的是网关和推送链路。只看发送成功的提示不算数必须看对端真的弹出来。图片和语音要单独验因为它们走的是上传接口和文字消息不是同一条路。第二个动作刷新重连。在聊天页按 F5看历史消息是否完整、新消息是否还能推过来。这一步验的是登录态持久化和前端重连逻辑。很多人装完第一步就以为成了结果用户一刷新就掉线投诉堆到你这。第三个动作模拟断网。把手机切飞行模式十秒再切回来看是否自动重连、是否补拉了这十秒的离线消息。这一步验的是心跳和离线补偿也是最容易在 Safari 上翻车的地方——我在 iOS 上见过太多次网络恢复了但消息停在断网那一刻。# 服务端侧同步确认三件事进程、端口、日志无异常 supervisorctl status im-gateway ss -lntp | grep -E 9502|9503|6379|3306 tail -n 100 /www/wwwroot/im/runtime/gateway.err.log | grep -iE error|exception三条都干净再去看数据库里消息表有没有新记录、Redis 里的在线集合是不是两个账号。四个端的验证顺序我一般是 PC → H5Safari→ 安卓 → iOS因为 PC 最好调试问题能最早暴露Safari 放第二个是因为它最容易出 Cookie 和自动播放的幺蛾子早发现早改。还有一个小技巧给网关加一个健康检查接口返回当前在线连接数。上线之后隔几天 curl 一次数字对得上就说明没人偷偷挂掉。这套源码本身带教程装的时候对着走一遍比纯看代码猜要快得多二开加商城那块等你把上面三步验完再去动别在环境没稳的时候改业务出了事分不清是新代码还是环境。从那以后我每次装这类四端 IM都会先把「两账号互发、刷新重连、断网恢复」跑一遍再交付不管需求方多急。省下的那二十分钟往往要用两个晚上还。希望帮到你。本文还有配套的精品资源点击获取