WebSocket连接未建立成功是群消息响应延迟、指令无反馈或机器人不在线的主因，需检查Nginx是否启用HTTP/1.1并透传Upgrade头、location路径是否与WorkBuddy监听路径严格一致、Nginx是否将WSS解密为明文WS转发、WorkBuddy是否启用force-identify重连机制，以及防火墙/SELinux是否拦截端口。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已完成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;
启用该技能，可以在WorkBuddy对话页的右边栏添加一个日历，提供月历视图、日程增删改查、分类标签（开庭/会议/截止日期/个人/研究/其他），支持从对话中提取事件并自动同步到日历。当用户提到"日历""日程""打开日历""添加日程""我的日程""calendar""安排"或询问已记录的日程信息时使用。
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
