WebSocket 连接排查

站内 私信/群聊、管理端 H5 实时能力、对外事件流（openstream） 均依赖 WebSocket。HTTP API 正常但「一直连接中 / 发不出消息 / WS 403」时，按本文从外到内排查。

连接方式（先确认路径）

灵萌 不 使用 /api/message/ws 作为升级地址，标准流程为：

1. 换取票据（须登录）：POST /api/message/ws/ticket（或 /api/v1/message/ws/ticket，取决于 API 前缀）
2. 升级连接：GET /ws?ticket=<一次性票据>（根路径 /ws，不在 /api 下）

对外事件流类似：POST /api/open/ws/ticket → GET /ws/open?ticket=...。

H5 / 管理端在 HTTPS 页面下会自动使用 wss://你的域名/ws?ticket=...。

现象与对应原因

现象	常见原因
票据接口 502 / Connection refused	Go 进程未启动或反代 upstream 端口错误（默认 127.0.0.1:8080）
GET /ws 返回 403，body 含「Origin 不在白名单内」	CORS allowed_origins 未包含当前页面的 HTTPS Origin（见下文）
GET /ws 返回 401	票据无效或过期（属正常鉴权，说明 Origin 已通过）
仅 H5 失败、小程序正常	Nginx 未转发 Upgrade / Connection 头，或 CDN 未开 WebSocket
间歇性断开	CDN/负载均衡空闲超时过短；可加大 proxy_read_timeout

1. CORS 白名单须与访问协议一致（高频）

WebSocket 升级握手会带浏览器 Origin 头，后端与 HTTP CORS 共用 config.yaml 中的 cors.allowed_origins 白名单。

站点已启用 HTTPS 时，若白名单只写了 HTTP，连接会被拒绝：

# ❌ 仅 HTTP：浏览器从 https://goqiang.b0518.top 打开时 Origin 为 https，不在名单内 → /ws 403
cors:
  allowed_origins:
    - http://goqiang.b0518.top

# ✅ 同时列入 HTTPS（建议正式环境以 HTTPS 为准）
cors:
  allowed_origins:
    - https://goqiang.b0518.top
    - http://goqiang.b0518.top

修改 config.yaml 后 须重启 Go 进程后生效。

自检（在服务器上）：

# 应返回 401（票据无效），而不是 403
curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'Origin: https://你的域名' \
  -H 'Connection: Upgrade' \
  -H 'Upgrade: websocket' \
  -H 'Sec-WebSocket-Version: 13' \
  -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
  'http://127.0.0.1:8080/ws?ticket=invalid'

• 403 → 继续检查 allowed_origins
• 401 → Origin 已通过，再查票据、Redis、进程是否在线

初始化向导里填写的 CORS 白名单 同样须写完整协议（https://）。管理端、独立 H5 域名若与主站不同，需 每行一个 Origin 全部列入。

2. Nginx / 宝塔反代

站点 location / 反代到 Go 时，需支持协议升级（宝塔 Go 项目模板通常已包含）：

location / {
    proxy_pass http://127.0.0.1:8080;
    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_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_read_timeout 86400s;
}

/ws 与 /api 走同一 location / 即可，无需单独再配 /api/ws。

3. CDN（EdgeOne 等）

域名接入 CDN 时，须在控制台 开启 WebSocket 转发。未开启时表现为外网连不上、源站直连正常。详见 快速部署 中的 CDN 提示。

4. 服务与依赖

• 系统监控 → 系统状态：Redis、WebSocket 相关项应为正常
• 系统监控 → 在线用户：有连接时能看到在线规模
• Nginx error.log 若出现 connect() failed (111: Connection refused) while connecting to upstream，说明当时 Go 未监听 8080（部署/重启中或进程退出）

5. 日志快速对照

日志	含义
POST .../message/ws/ticket 200，GET /ws?ticket=... 403	多为 Origin 白名单 问题
GET /ws 401	票据问题或已消费；Origin 已通过
upstream 502 / Connection refused	Go 未运行或端口不对

相关文档

文档	说明
私信与群聊	私信开关、区域配置
对外事件流	/ws/open 与 Pull/回调
快速部署	宝塔部署与 CDN WebSocket
初始化向导	CORS 白名单填写
常见问题	其他运维问题索引