WorkBuddy通讯异常？WebSocket反向代理解析

当WorkBuddy出现群消息延迟、指令无响应或机器人“失联”时，问题根源往往并非程序崩溃或配置错误，而是WebSocket实时通信通道未能成功建立——这通常源于Nginx反向代理配置中HTTP/1.1支持缺失、Upgrade头未透传、location路径不匹配、WSS未正确解密为WS转发、WorkBuddy未启用强制重鉴权（force-identify），或系统防火墙/SELinux拦截了关键端口；本文直击五大高频故障点，提供可立即执行的逐项排查与修复方案，助你5分钟内恢复稳定、低延迟的机器人通讯能力。

如果您已完成WorkBuddy安装，但群消息响应延迟、指令无反馈或机器人完全不在线，则很可能是WebSocket连接未建立成功。Nginx反向代理配置缺失或错误是导致实时通讯失效的最常见原因。以下是针对性排查与修复步骤：

一、确认Nginx已启用HTTP/1.1并透传WebSocket关键头

Nginx必须显式支持HTTP/1.1协议，并将客户端发起的升级请求头完整转发给后端WorkBuddy服务，否则WebSocket握手在第一步即失败。

1、打开Nginx配置文件（通常为/etc/nginx/conf.d/default.conf或/etc/nginx/nginx.conf）。

2、在对应server块的location配置中，检查是否包含以下三行且无注释：

proxy_http_version 1.1;

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection "upgrade";

3、若任意一行缺失或被注释，取消注释并保存文件。

4、执行sudo nginx -t验证语法正确性，再运行sudo systemctl reload nginx重载配置。

二、校验Nginx location路径与WorkBuddy监听路径严格一致

WebSocket请求能否进入代理逻辑，完全取决于Nginx的location匹配规则。路径不一致将导致请求被路由至静态资源或其他后端，而非WorkBuddy的WebSocket服务。

1、确认WorkBuddy实际监听的WebSocket路径（默认为/ws/或/websocket），可通过其启动日志或配置文件中的websocket.path字段查得。

2、在Nginx配置中定位到对应server块，检查location指令是否与该路径完全相同，包括末尾斜杠：

location /ws/ { ... }

3、若WorkBuddy监听/ws/而Nginx配置为location /websocket，则必须修改Nginx配置使其一致。

4、修改后再次执行sudo nginx -t && sudo systemctl reload nginx。

三、验证Nginx是否终止TLS并将明文WS转发至本地WorkBuddy

WorkBuddy自身不支持SSL/TLS，所有WSS请求必须由Nginx解密后以明文WS协议转发至127.0.0.1上的指定端口；若让WorkBuddy直接监听HTTPS端口或尝试加载证书，必然导致握手失败。

1、检查Nginx server块中是否同时配置了SSL证书与监听443端口：

listen 443 ssl;

ssl_certificate /path/to/fullchain.pem;

ssl_certificate_key /path/to/privkey.pem;

2、确认proxy_pass目标为http://127.0.0.1:2346（或WorkBuddy实际监听的明文端口），而非https://或wss://。

3、运行netstat -tuln | grep :2346，确保WorkBuddy进程正在监听该端口且绑定地址为127.0.0.1:2346而非0.0.0.0:2346（后者存在安全风险且非标准部署方式）。

四、检查WorkBuddy服务是否启用强制IDENTIFY而非resume重连

当WebSocket连接中断后，若WorkBuddy尝试使用过期session_id进行resume，QQ频道网关将返回4006错误并拒绝重建连接；此时必须触发全新IDENTIFY流程才能恢复通讯。

1、查看WorkBuddy最新日志，搜索4006或invalid session id关键词。

2、若存在该错误，说明当前配置未启用强制重鉴权机制。

3、编辑WorkBuddy启动命令或配置文件，在参数中添加：

--force-identify

或在YAML配置中设置：

connection.force_identify: true

4、保存后彻底终止WorkBuddy进程（如pkill -f workbuddy），再重新启动。

五、排查本地防火墙或SELinux对WebSocket端口的拦截

即使Nginx与WorkBuddy配置全部正确，系统级网络策略仍可能丢弃WebSocket流量，尤其在CentOS/RHEL系服务器上SELinux默认阻止非标准端口通信。

1、临时关闭防火墙测试连通性：

sudo systemctl stop firewalld

2、若通讯立即恢复，说明firewalld规则阻断了WorkBuddy监听端口（如2346）。

3、永久放行该端口：

sudo firewall-cmd --permanent --add-port=2346/tcp

sudo firewall-cmd --reload

4、若使用SELinux，执行：

sudo setsebool -P httpd_can_network_connect 1

今天关于《WorkBuddy通讯异常？WebSocket反向代理解析》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！