WebSocket 无法连接
依次检查 Workerman 进程、监听端口、云服务器安全组、防火墙、Nginx 反向代理、SSL 证书和客户端 WSS 地址。HTTPS 页面不能连接明文 ws://。
消息必须刷新页面才出现
说明页面列表只依赖 HTTP 拉取，没有正确消费 WebSocket 事件。检查连接是否绑定当前用户、事件名称是否一致、前端状态仓库是否更新，以及消息到达后是否合并进当前会话。
新好友没有红点
创建好友申请后，服务端应同时保存申请记录并推送 friend.request.created 事件。客户端收到后更新新好友未读数量；进入新好友页面后再调用已读接口。
发送了一条却出现两条
检查断线重试和按钮重复点击。客户端为每次发送生成 client_message_id，数据库建立唯一约束，重复请求返回原消息，不再次插入。
已读状态不更新
确认进入会话时已上报最后读取的服务端消息 ID，并把 read receipt 推送给会话其他在线设备。多端场景取各设备已读位置的最大值。
离线推送收不到
确认正式 App 包已经获取 push_clientid，服务端保存设备标识，用户未退出登录，推送任务已创建，push-worker 正常运行，厂商参数与应用签名一致。
图片或文件发送失败
检查 PHP 上传限制、Nginx client_max_body_size、磁盘权限、MIME 白名单、对象存储跨域和临时凭证有效期。
群消息部分成员收不到
检查群成员缓存是否及时更新、用户是否被禁言或移除、WebSocket 节点间是否共享在线路由，以及离线任务是否按所有有效成员创建。
手机锁屏后连接断开
移动系统会限制后台网络，这是正常现象。前台恢复时重新连接并同步离线消息；后台期间依赖厂商推送提醒。
PC 和手机消息不同步
所有端必须使用同一用户身份和服务端消息历史，不能只保存本地消息。新设备登录后按最后同步位置拉取会话与消息。
授权正常但程序提示未授权
检查产品代码、授权码、绑定域名、程序版本、服务器时间和 RSA 公钥。API、WebSocket 和任务进程应使用同一套授权配置。
授权中心暂时不可访问
客户端可以在已成功在线验证后使用签名离线凭证，但只允许在配置的离线期限内运行。网络恢复后必须重新在线验证。
接口返回数据库结构尚未升级
说明代码版本高于数据库结构版本。先备份数据库，再访问升级入口执行当前版本迁移；不要把完整安装 SQL 导入旧库。
WebSocket 提示 auth timeout
连接建立后客户端没有在规定时间内发送有效认证事件。检查登录令牌、连接票据、设备 ID、事件名称和客户端连接后发送认证的时机。
消息发送成功但对方没有实时收到
检查消息是否进入派发任务、WebSocket 服务是否持续读取实时事件、对方连接是否绑定正确用户，以及多节点环境是否共享事件来源。对方重新连接后应能通过增量同步补回消息。
push-worker 队列持续增加
检查进程是否运行、第三方推送接口是否超时、失败任务是否不断重试、设备标识是否大量失效。应对失败原因分类处理，永久错误不要无限重试。
后台支付显示成功但业务没有到账
检查异步通知是否到达、渠道签名验证、订单金额、商户号、幂等记录和钱包流水。禁止仅凭前端支付成功页面直接给用户增加余额。
音视频能呼叫但没有声音或画面
检查 RTC 是否启用、房间令牌是否过期、双方麦克风和摄像头权限、浏览器安全上下文、网络 NAT 情况和第三方控制台日志。
升级后 App 提示协议不兼容
服务端会根据客户端版本和协议头判断兼容性。确认 App 不是旧缓存包，检查 X-Client-Version、X-Client-Protocol 和服务端当前协议版本，必要时发布强制升级。