基于GatewayWorker的WebSocket与HTTP双链路即时通讯

如果你一路跟着这个系列走到第五章，说明前面 GatewayWorker 服务端、Laravel 集成、事件解析这些门槛已经迈过去了。这一章是大家最想看的"能跑起来的东西"——前后端代码写完、浏览器打开、两个窗口互相发消息、发文件，把 IM 的样子真正做出来。

先说结论：这一章的核心不是疯狂堆代码，而是把"WebSocket 长连接"和"HTTP 请求"这两条路子理顺。很多人项目死在联调阶段，不是因为不会写代码，而是没想清楚消息从 A 浏览器到 B 浏览器到底走哪条链路。文本消息走 GatewayWorker 实时通道，文件互传走 HTTP 上传再推送通知，两条链路配合好，整个 IM 就活了。

下面我会把后端接口、前端 JS、演示步骤、踩坑记录全部拆开讲，代码可以直接抄，但更建议你把每一步"为什么这么写"也看了，后面自己扩展功能才不会被绊住。

1. 先把数据通路想清楚：谁负责推送，谁负责存储

动手写代码前，我建议你先画一张"数据走向图"在脑子里。不用多复杂，就弄清三个问题：客户端连到哪、消息往哪发、文件往哪放。

先说整体架构。Laravel 负责提供 HTTP 接口，包括登录鉴权、好友列表、文件上传这些常规业务；GatewayWorker 负责维护 WebSocket 长连接，所有客户端连上之后，GatewayWorker 就变成一个实时中转站。文本消息由客户端直接通过 WebSocket 发给 GatewayWorker，GatewayWorker 再转发给接收方。这个流程实时性最高，一条消息发出去到对方收到，正常在几十毫秒级别。

文件互传则是另一条链路。我见过有人把文件用 base64 编码之后塞进 WebSocket 消息里直接发，早期小文件能跑，但一传 2MB 以上的图片，消息体膨胀 33%，GatewayWorker 转发会明显卡顿，而且数据库或内存压力直接翻倍。所以生产环境更稳妥的做法是：发送方先把文件通过 HTTP 上传到 Laravel 服务器，拿到一个访问 URL，再通过 WebSocket 把"包含 URL 的消息"推送给对方。接收方点击消息里的文件卡片，就能从服务器加载文件。

这两条链路的分工可以用一张表概括：

数据形式	传输通道	存储位置	实时性
文本消息	WebSocket 直传	可存数据库/Redis	毫秒级
小图片/音频	base64 走 WebSocket	不存储，转发即焚	毫秒级，仅限调试
正式文件/图片	HTTP 上传 + WebSocket 推送 URL	Laravel 服务器磁盘	秒级，推荐

这个模式想清楚之后，后端的接口设计就变得特别自然：只是"上传文件"和"推送消息"这两件事，彼此不纠缠。我在项目里最怕的就是有人硬把文件塞进 WebSocket 里，后面调试都不知道从哪下手。

2. 后端接口设计：绑定关系是 IM 的命脉

2.1 为什么必须做 uid 与 client_id 绑定

GatewayWorker 的机制里，每个连接都会被分配一个 client_id，它是一个随机字符串，每次连接都会变。问题在于：业务层知道的是用户的 uid（比如用户 ID），GatewayWorker 知道的是 client_id，两边得建立映射关系，否则没法把消息推送给指定用户。

这个绑定关系是整个 IM 的命脉。我在 2.1 章节里的职责就是把 onConnect 或者登录成功后的首次通信里拿到的 client_id 和用户 ID 关联起来，存到 GatewayWorker 的全局变量或者 Redis 里。

实际开发中，我推荐在 Laravel 里做一个绑定接口，由前端登录成功后调用：

// routes/api.php Route::post('/im/bind', [ImController::class, 'bindClient']); // app/Http/Controllers/ImController.php public function bindClient(Request $request) { $uid = auth('api')->id(); // 假设走接口登录 $clientId = $request->input('client_id'); // 调用 GatewayWorker 的 Gateway 类，把 uid 与 client_id 绑定 Gateway::bindUid($clientId, (string)$uid); // 同时存一份映射到 Redis 备用（比如后期多端登录检查） Redis::set('im:uid:' . $uid, $clientId); return ['code' => 0, 'msg' => '绑定成功']; }

GatewayWorker 自带的 Gateway::bindUid 方法会把分组信息和绑定关系写进 GatewayWorker 的内部存储里，后期用 Gateway::sendToUid 就能直接向指定用户推送消息。这个设计很关键，它让你在业务逻辑里不需要关心这个用户用的是哪个 client_id，也不用管用户是电脑还是手机上登录，发消息只要带上 uid 就行。

2.2 单聊消息推送接口：文本与文件 URL 的两种处理

接口层面，聊天记录可以实时入库，也可以先入库再推送，看你的业务需求。我在项目里为了演示简单，就做成"前端直接把消息通过 WebSocket 发出去"，服务端事件里去保存。不过有些场景下需要"先落库再广播"，比如官方消息、系统通知，这种就要走 HTTP 接口。

我建议文本消息也保留一个 HTTP 推送接口作为兜底通道。一旦前端 WebSocket 断开了（比如浏览器切后台被系统杀掉），发送方可以把消息提交到这个接口，由 Laravel 调用 Gateway::sendToUid 推送给接收方。这个兜底方案能减少"消息丢了"的投诉。

public function pushMessage(Request $request) { $toUid = $request->input('to_uid'); $content = $request->input('content'); // 保存聊天记录 ChatMessage::create([ 'from_uid' => auth('api')->id(), 'to_uid' => $toUid, 'type' => 'text', 'content' => $content, ]); // 向目标用户实时推送 Gateway::sendToUid($toUid, json_encode([ 'type' => 'new_message', 'from_uid' => auth('api')->id(), 'content' => $content, 'time' => time(), ])); return ['code' => 0]; }

文件上传接口就更直白了，就是 Laravel 常规的上传处理，加一个访问权限判断。文件本身不通过 GatewayWorker 传输，所以这个接口甚至可以在另一台服务器上，和长连接服务分离。

3. GatewayWorker 事件处理：一个文件一支队伍

GatewayWorker 的 events.php 是整个实时通信的大脑。我说它是"大脑"不是夸张，因为你所有的业务逻辑分发都在这里做。

3.1 onMessage 的消息分发设计

先定义消息统一格式。我习惯用 JSON，至少包含 type、data、from_uid、to_uid 四个字段。type 决定这条消息到底执行什么动作。

public static function onMessage($client_id, $message) { $data = json_decode($message, true); if (!is_array($data)) { return; } switch ($data['type']) { case 'chat': self::handleChat($client_id, $data); break; case 'file': self::handleFile($client_id, $data); break; case 'ping': Gateway::sendToClient($client_id, json_encode(['type' => 'pong'])); break; } }

一个文件一支队伍，说的是每个 type 都要有独立的处理方法，不要全堆在一个分支里。chat 就是纯文本聊天，file 就是文件卡片消息。这样后期加"已读回执""正在输入"这些功能时，只需要新增 case，已有的逻辑不用动。

3.2 转发时的几个细节

一旦进入 chat 或者 file 处理，最核心的动作就是转发。

private static function handleChat($client_id, $data) { $fromUid = $data['from_uid'] ?? ''; $toUid = $data['to_uid'] ?? ''; $content = $data['content'] ?? ''; // 历史记录落库 \Illuminate\Support\Facades\DB::table('chat_messages')->insert([ 'from_uid' => $fromUid, 'to_uid' => $toUid, 'type' => 'text', 'content' => $content, 'created_at' => date('Y-m-d H:i:s'), ]); // 推送给目标用户 Gateway::sendToUid($toUid, json_encode([ 'type' => 'new_message', 'from_uid' => $fromUid, 'content' => $content, 'time' => time(), ])); // 给发送方一个回执，前端可以据此把"发送中"改成"已送达" Gateway::sendToUid($fromUid, json_encode([ 'type' => 'message_delivered', 'to_uid' => $toUid, ])); }

注意一个关键点：在 GatewayWorker 的回调里直接操作数据库是可以的，但需要引入 Laravel 的数据库组件。因为 GatewayWorker 是独立进程，和 Laravel 应用不在同一个容器里，如果只是在 GatewayWorker 进程里 use 一个 Model，需要先通过 think/illuminate 之类的桥接来加载 Laravel 的数据库配置。我自己的做法是：GatewayWorker 只做转发，聊天记录直接调用一个轻量的 HTTP 接口让 Laravel 写入，这样 GatewayWorker 进程保持轻量化，数据库连接也不容易因为长生命周期进程而出问题。当然，如果你用的是 workerman 的 Laravel 集成，直接在 events.php 里使用 Eloquent 也是可行的，只是要注意进程生命周期里的连接管理。

3.3 文件消息的转发：只推元数据

文件消息和文本消息的区别只有一个：消息内容不是自定义字符串，而是一个 JSON 数组，包含文件名、大小、URL、类型等信息。转发逻辑和文本一样，只是数据体换一下：

private static function handleFile($client_id, $data) { $fromUid = $data['from_uid'] ?? ''; $toUid = $data['to_uid'] ?? ''; $fileInfo = $data['file_info'] ?? []; // 推送文件卡片消息 Gateway::sendToUid($toUid, json_encode([ 'type' => 'new_file', 'from_uid' => $fromUid, 'file_info' => $fileInfo, 'time' => time(), ])); }

这里犯不着再走一遍 HTTP 去保存记录，因为文件元数据已经在上传接口里落库了，这里只是通知。"只推元数据、不推文件内容"这个原则会贯穿整个文件互传功能。

4. 前端核心代码：从建立连接到聊天气泡渲染

后端准备好之后，前端才是真正把功能串起来的角色。我把前端拆成几个模块：连接模块、心跳模块、渲染模块、发送模块、文件模块。下面按模块展开。

4.1 WebSocket 连接与心跳保活

前端第一步是建立连接。这里有个常见的坑：GatewayWorker 默认端口是 8282，但它返回的是"握手已完成"和 websocket 协议数据。一定要确认你的服务器开放了这个端口，并且前端的 ws 地址写对。我常用的是 nginx 反向代理 ws 协议的方案，后面踩坑章节里细说。

连接 JS 我习惯写成一个 class：

class IMClient { constructor(options) { this.url = options.url; this.user = options.user; this.ws = null; this.heartbeatTimer = null; this.reconnectTimer = null; this.reconnectAttempts = 0; } connect() { const that = this; this.ws = new WebSocket(this.url); this.ws.onopen = function() { console.log('连接已建立'); that.reconnectAttempts = 0; that.startHeartbeat(); that.doBind(); }; this.ws.onmessage = function(e) { that.handleMessage(e.data); }; this.ws.onclose = function() { console.log('连接断开'); that.stopHeartbeat(); that.reconnect(); }; this.ws.onerror = function(e) { console.error('连接出错', e); }; } startHeartbeat() { const that = this; this.heartbeatTimer = setInterval(() => { that.send({ type: 'ping' }); }, 30000); } stopHeartbeat() { if (this.heartbeatTimer) { clearInterval(this.heartbeatTimer); this.heartbeatTimer = null; } } reconnect() { if (this.reconnectAttempts >= 10) { console.error('重连次数过多，停止重连'); return; } this.reconnectAttempts++; const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30000); console.log('延迟重连:' + delay + 'ms'); setTimeout(() => this.connect(), delay); } doBind() { // 调用后端绑定接口 fetch('/api/im/bind', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ client_id: this.ws.client_id // 注意：前端拿不到client_id，需要等待GatewayWorker返回 }) }); } }

等一下，上面这段有个细节要修正：前端在 WebSocket 握手之后，并不直接知道自己的 client_id。GatewayWorker 在 onWebSocketConnect 或者 onConnect 时会拿到 client_id，但它不会主动告诉前端。所以绑定接口的 client_id 需要由服务端反馈。我推荐的做法是：GatewayWorker 在 onConnect 之后主动下发一个 system_connected 消息，把这个 client_id 带给前端。

public static function onConnect($client_id) { Gateway::sendToClient($client_id, json_encode([ 'type' => 'system_connected', 'client_id' => $client_id, ])); }

前端收到 system_connected 之后，再带上 client_id 去调用绑定接口。这是很多人联调时最容易卡住的地方——前端拿不到 client_id，就绑不上 uid，消息自然推不过去。

4.2 消息渲染与发送

前端渲染聊天记录，我的经验是"以接收为主，发送为辅"这两个函数足够：renderMessage 用于渲染气泡，sendMessage 用于发送文本。

handleMessage(data) { const msg = JSON.parse(data); switch (msg.type) { case 'system_connected': this.bindClient(msg.client_id); break; case 'new_message': this.renderMessage({ from_uid: msg.from_uid, content: msg.content, time: msg.time, direction: msg.from_uid === this.user.id ? 'out' : 'in' }); break; case 'new_file': this.renderFileCard(msg.file_info); break; case 'message_delivered': // 更新发送状态 break; } } sendMessage(content) { const msg = { type: 'chat', from_uid: this.user.id, to_uid: this.targetUser.id, content: content, time: Math.floor(Date.now() / 1000) }; this.send(msg); this.renderMessage({ from_uid: this.user.id, content: content, time: msg.time, direction: 'out' }); }

渲染气泡其实就是一个简单的 DOM 操作，唯一要注意的是防止 XSS。聊天内容是用户可控的，直接 innerHTML 会有安全风险。我推荐用 textContent 设置文字内容，或者前端框架自动转义。

4.3 文件互传的前端流程

文件互传前端有两个方案，前面说过生产环境推荐先传后发。前端流程是：

• 用户选择文件
• 调用上传接口，带上文件内容，拿回 URL、文件名、大小
• 渲染一个"文件卡片"气泡
• 把文件元数据通过 WebSocket 发出去

基类逻辑如下（我会做封装）：

function uploadFile(file, callback) { const formData = new FormData(); formData.append('file', file); fetch('/api/im/upload', { method: 'POST', body: formData }).then(res => res.json()).then(data => { if (data.code === 0) { callback(null, data.data); } else { callback(data.msg, null); } }).catch(err => { callback(err, null); }); } function sendFile(file) { uploadFile(file, (err, fileInfo) => { if (err) { console.error('上传失败', err); return; } const msg = { type: 'file', from_uid: currentUser.id, to_uid: targetUser.id, file_info: { file_name: fileInfo.file_name, file_url: fileInfo.file_url, file_size: fileInfo.file_size, file_type: fileInfo.file_type }, time: Math.floor(Date.now() / 1000) }; imClient.send(msg); renderFileCard(fileInfo, 'out'); }); }

前端处理文件消息时，接收方收到的就是一个带 file_url 的卡片，点击下载即可。这里要注意一点：上传接口要校验文件类型和大小，不能全盘接受。我项目里限制单文件 20MB，扩展名白名单校验，避免服务器被当免费图床刷。

5. 完整演示：两个浏览器窗口模拟双端互聊与文件互传

代码写完之后，终于到了最激动人心的演示环节。我用两个浏览器标签页分别登录两个账号（可以是一台电脑上的不同浏览器窗口，也可以直接用隐身模式开一个窗口），模拟两个用户互发消息和文件。

5.1 启动服务

先启动 GatewayWorker。我用的命令是在项目根目录运行：

php start.php start

稍等几秒，看到 start 成功且监听 8282 端口，说明 worker 状态正常。如果用的是守护模式，用php start.php start -d。

接着启动 Laravel 开发服务：

php artisan serve

Laravel 服务默认监听 8000 端口。如果你本机做演示，前端页面直接访问 Laravel 的路由就可以。为了演示效果，我通常把前端页面放在 Laravel 的一个视图里，这样不用处理跨域问题，演示最顺。

5.2 双端登录与绑定

在标签页 A 用"用户A"登录，标签页 B 用"用户B"登录（模拟数据可以用 Seeder 提前造两个测试账号）。各自进入聊天页面后，注意浏览器的 Network 面板里应能看到：

• WebSocket 已经连接成功（状态是 open）
• 系统下发了一条 type 为 system_connected 的消息
• 前端自动调用 /api/im/bind，完成 client_id 绑定

如果 Network 里没有 system_connected 消息，大概率是 onConnect 的回调没写，或者你在 onConnect 里调用 Gateway::sendToClient 的时机不对。把这些问题先解决，后面演示才顺。

5.3 文本消息互发演示

在标签页 A 的输入框里敲一句话，点击发送。你会看到：

• 用户 A 的聊天窗口立刻出现右侧气泡，显示"已送达"
• 用户 B 的聊天窗口几乎同时出现左侧气泡，显示文本内容
• Network 面板里能看到 WebSocket 151（或者类似）有一条 chat 类型消息发出

最能说明实时性的一点是：故意把标签页 B 切到后台，再在 A 发送，B 切回来时气泡已经在等着了，不需要刷新页面。这就是 WebSocket 推送和普通轮询的本质区别。

5.4 文件互传演示

在标签页 A 点击文件选择按钮，选一个 5MB 左右的图片（太小看不出效果，太大可能超限制）：

• A 的文件卡片先显示上传中的状态，接口返回 URL 之后，卡片变成可点击下载的样式
• B 立刻收到文件卡片，展示文件名、大小、类型图标
• 点击 B 的文件卡片，浏览器打开文件预览或者触发下载

验证文件确实传过去了，可以看一眼服务器上 storage 目录里多出来的文件，或者直接在浏览器地址栏手动访问 file_url，能打开就说明整个链路是通的。

5.5 模拟断线重连

为了验证心跳和重连逻辑，我特意做了一次断网演示：

• 把网线/代理断开，模拟弱网环境
• 浏览器 WebSocket 约 30 秒后自动检测断开，触发 onclose
• 前端指数退避重连，1 秒、2 秒、4 秒……逐步拉开间隔
• 重新连上之后，自动补绑 client_id
• 再次发送消息，恢复正常

这个测试非常值得做，不做的话，线上用户 WiFi 一换就永久掉线，你的 IM 会变成"一次性聊天工具"。

6. 这一章做完之后，我踩过的坑和优化建议

代码跑通之后，趁热打铁把容易踩到的坑记下来。这些都是我连续调试几天后总结的，照着避开能省你几个晚上。

6.1 前端拿不到 client_id 的尴尬

这是我第一次做 GatewayWorker 犯的错误：前端想着"我连上了，服务端应该给我一个标志"，结果 onopen 之后直接发消息，服务端根本不知道你是谁。后来才搞明白，client_id 是服务端给每个连接分配的内部标识，它不会自动推给前端。需要服务端在 onConnect 里主动下发一次，前端收到后再进行绑定流程。机制就是这样，写代码前先理解这一点，少走弯路。

6.2 Nginx 反向代理 WebSocket 的配置

如果你跟线上环境一样前面有 Nginx，注意必须加 WebSocket 升级头。我见过太多把 8282 端口暴露在防火墙之外、后端代码没问题但浏览器连接却一直失败的情况。

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 60s; }

如果配置缺少 Upgrade 头，浏览器收到的就是 400 或 502，根本进不了 onConnect。还有 proxy_read_timeout 别设太短，我一开始设 30s，正好在一个长心跳间隔内，导致服务端主动断开连接。设 60s 以上，配合前端 30s 心跳，正好稳定。

6.3 上传大小限制拦住了文件互传

Laravel 默认文件上传限制是 2MB 还是多少来着，反正我第一次传一张手机拍的照片就失败了。要改的地方有：

# php.ini upload_max_filesize = 20M post_max_size = 21M

同时 Laravel 的 validation 规则里也要放行。我建议在 FormRequest 里统一管理，不要只改 php.ini，否则换环境就忘。

6.4 历史消息的加载策略

演示中最容易露怯的就是刷新页面后聊天记录全没了。我后来把聊天记录落库了，前端在页面初始化时调用一个 history 接口，按分页加载最近 50 条消息。渲染顺序按时间正序，同时把 last_msg_id 存下来用于增量同步。这个功能如果没做，"IM"更像是一个"阅后即焚"Demo。

6.5 消息确认与离线消息

GatewayWorker 有 Gateway::isUidOnline($uid) 方法可以判断用户在线状态。我实际项目里的做法是：

• 如果用户在线，实时推送
• 如果离线，把消息标记为未读，用户下次上线时通过 HTTP 拉取未读列表

基础版可以直接把未读消息存在 MySQL 的 messages 表里，加一个 read_at 字段。升级版可以用 Redis 的 List 暂存离线消息，上线后 LPOP 批量拉取。门槛不高，但体验提升巨大。

6.6 文件互传的安全控制

文件上传我一开始没做权限校验，任何登录用户可以直接访问上传后的 URL。后来发现只要别人拿到你上传文件的 URL 就能下载，这在一个私密聊天工具里是不能接受的。至少做两层：

• 上传时校验登录状态
• 访问时校验是否与消息相关联

我用的方式是生成临时 token，把 token 拼在文件 URL 后面，过期时间 10 分钟。这样即使链接被转发，也很快就失效。这个细节如果你做到，项目面试时能讲出东西来。

---

整个第五章做完之后，我的体会是：即时通信最难的地方从来不是写一个 WebSocket 出来，而是把 HTTP 业务和实时通道之间的边界划清楚。文本走实时、文件走 HTTP、绑定靠接口、推送靠 Gateway，每一块责任单一，整体才不会乱。按这套代码跑通演示之后，你可以继续加"正在输入""已读回执""聊天记录多端同步"这类功能，框架不会因为加功能而散架。下一章我打算讲消息可靠性保障，重点处理消息丢失、重复投递、离线缓冲这三个问题，有兴趣的可以继续跟。