若workbuddy私有化部署后客户端或集成端无法通信，主因是网络链路被防火墙或云安全组阻断；需依次排查端口开放、配置系统防火墙、调整云安全组、排除代理与dns干扰，并启用claw协议端口穿透。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已完成WorkBuddy私有化部署，但客户端或集成端（如企业微信、飞书）无法与本地服务通信，则极可能是网络链路被防火墙或云平台安全组策略阻断。以下是针对性的排查与配置步骤：
一、确认关键端口是否开放
WorkBuddy私有化部署依赖多个固定端口进行内部组件通信与外部接入，任一端口被拦截均会导致连接中断。需逐项验证以下端口在本机及网络边界处的可达性。
1、检查本地服务监听状态：Windows用户在命令提示符中执行 netstat -ano | findstr :3000，macOS/Linux用户执行 lsof -i :3000，确认WorkBuddy主服务（默认3000端口）处于LISTEN状态。
2、验证API服务端口5001：使用curl命令测试本地连通性——curl -I http://localhost:5001/health，返回HTTP 200且含{"status": "ok"}即表示API子系统正常运行。
3、检查Redis缓存端口6379：执行 redis-cli -h 127.0.0.1 -p 6379 ping，若返回PONG则Redis已就绪；否则需启动Redis服务并确保其绑定地址为0.0.0.0（非仅127.0.0.1）。
4、验证RabbitMQ消息队列端口5672：运行 telnet localhost 5672，成功建立连接表明AMQP服务可用；若失败，需检查RabbitMQ是否启用guest用户远程登录权限。
二、配置操作系统防火墙规则
系统级防火墙默认阻止入站连接，必须显式放行WorkBuddy相关端口，否则即使服务运行也无法被外部访问。
1、Windows Defender防火墙：打开“高级安全Windows Defender防火墙”，点击“入站规则”→“新建规则”，选择“端口”，输入TCP端口3000,5001,6379,5672，操作设为“允许连接”，配置文件勾选“域”“专用”“公用”全部选项。
2、macOS防火墙：进入“系统设置 → 隐私与安全性 → 防火墙 → 防火墙选项”，点击左下角锁图标解锁后，点击“+”号添加WorkBuddy.app，并确保其状态为“允许传入连接”；同时手动添加/usr/local/bin/redis-server与/opt/homebrew/opt/rabbitmq/sbin/rabbitmq-server两个可执行文件。
3、Ubuntu/CentOS防火墙：执行 sudo ufw allow 3000/tcp && sudo ufw allow 5001/tcp && sudo ufw allow 6379/tcp && sudo ufw allow 5672/tcp，随后运行 sudo ufw reload 生效；若使用firewalld，替换为 sudo firewall-cmd --permanent --add-port={3000,5001,6379,5672}/tcp && sudo firewall-cmd --reload。
三、调整云服务器安全组策略
若WorkBuddy部署于阿里云、腾讯云或AWS等云平台，安全组作为虚拟防火墙将独立于操作系统生效，必须同步放行对应端口，否则公网IP虽可达，实际请求仍被丢弃。
1、登录云服务商控制台，定位至目标ECS实例所绑定的安全组。
2、编辑入方向规则，新增四条授权策略：协议类型均为TCP，端口范围分别填入3000/3000、5001/5001、6379/6379、5672/5672，源IP地址设置为0.0.0.0/0（若仅限内网调用，改为办公网段如192.168.10.0/24）。
3、确保每条规则的“策略”为“允许”，“优先级”高于任何拒绝规则；部分平台要求单独配置出方向规则，此时亦需对相同端口设置出方向放行。
4、保存后等待1–2分钟策略同步，再通过另一台机器执行 nc -zv [服务器公网IP] 3000 验证端口对外可达性。
四、绕过代理与DNS干扰
企业网络常部署透明代理或自定义DNS，可能劫持WorkBuddy的Claw协议通信或证书校验请求，导致WebSocket握手失败或auth.codebuddy.cn域名解析异常。
1、临时关闭所有代理软件（如Clash、Surge、企业级SSL解密网关），并在终端执行 unset HTTP_PROXY HTTPS_PROXY（Linux/macOS）或 set HTTP_PROXY= && set HTTPS_PROXY=（Windows）清除环境变量。
2、强制刷新DNS缓存：Windows执行 ipconfig /flushdns，macOS执行 sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder，Linux执行 sudo systemd-resolve --flush-caches。
3、验证域名解析准确性：运行 nslookup auth.codebuddy.cn，确认返回IP属于腾讯云CVM集群（如10x.x.x.x或18x.x.x.x段）；若返回私有IP（如10.0.0.x），说明DNS被篡改，需切换至公共DNS（如8.8.8.8）。
五、启用Claw协议专用端口穿透
WorkBuddy通过Claw协议实现企业微信、飞书等IM工具的反向长连接，该协议默认使用443端口复用机制，但在严格防火墙环境下需额外声明端口映射与TLS直通策略。
1、确认WorkBuddy配置文件中claw.listen_port字段未被注释，且值为443或8443（若443已被占用）。
2、在防火墙及安全组中单独放行该Claw端口，并确保其协议类型为TCP而非UDP。
3、若使用Nginx做前置反代，需在server块中添加 proxy_set_header Upgrade $http_upgrade; 与 proxy_set_header Connection "upgrade"; 两行，否则WebSocket升级请求将被降级为普通HTTP。
4、重启WorkBuddy服务：Windows执行 net stop workbuddy && net start workbuddy，Linux/macOS执行 sudo systemctl restart workbuddy 或 brew services restart workbuddy。
