WorkBuddy内网访问失败排查指南

当WorkBuddy在本地安装后无法被同一局域网内的手机、同事电脑等设备访问，问题往往并非服务未运行，而是虚拟网络隧道配置存在隐蔽断点——从监听地址绑定错误、系统防火墙拦截、虚拟机网络模式不匹配，到路由器UPnP干扰及Claw网关未正确暴露内网接口，五个关键环节环环相扣。本文直击这些高频故障根源，提供覆盖Windows/macOS/Linux及VMware/VirtualBox环境的实操排查路径，助你快速打通内网访问链路，让WorkBuddy真正成为团队协作中即装即用的可靠伙伴。

如果您在本地电脑上完成WorkBuddy安装后，发现其服务无法被同一局域网内的其他设备（如手机、同事电脑）访问，则可能是由于虚拟网络隧道配置缺失或错误，导致WorkBuddy监听的本地端口未正确暴露至内网。以下是排查此问题的具体步骤：

一、确认WorkBuddy服务监听地址与端口绑定模式

WorkBuddy默认仅绑定127.0.0.1（回环地址），该配置使服务仅对本机可见，拒绝来自局域网其他IP的连接请求。必须显式修改为0.0.0.0才能响应内网访问。

1、打开WorkBuddy安装目录下的配置文件config.yaml（Windows路径示例：C:\Program Files\WorkBuddy\config.yaml；macOS/Linux路径示例：~/Library/Application Support/WorkBuddy/config.yaml或/etc/workbuddy/config.yaml）。

2、查找server.host字段，将其值由127.0.0.1修改为0.0.0.0。

3、确认server.port字段值（默认为3001），并记录该端口号供后续防火墙与路由器检查使用。

4、保存文件后，必须完全退出WorkBuddy进程并重启客户端，否则新配置不会加载。

二、检查系统防火墙是否放行对应端口

操作系统防火墙可能拦截来自局域网的入站连接，即使WorkBuddy已绑定0.0.0.0且服务运行正常，外部请求仍会被静默丢弃。

1、Windows用户：打开“控制面板 → 系统和安全 → Windows Defender 防火墙 → 高级设置”，在“入站规则”中点击“新建规则”，选择“端口”，输入TCP 3001（或实际配置端口），允许连接，应用到所有配置文件。

2、macOS用户：进入“系统设置 → 隐私与安全性 → 防火墙 → 防火墙选项”，点击左下锁图标解锁，勾选“启用防火墙”，然后点击“+”号添加WorkBuddy.app，并确保其状态为“允许传入连接”。

3、Linux用户：执行sudo ufw allow 3001/tcp（若启用ufw），或检查iptables规则中是否存在ACCEPT目标端口3001的策略。

4、验证防火墙生效：在另一台局域网设备上执行telnet [本机IP] 3001，若连接成功则说明端口已开放。

三、验证宿主机与虚拟机间网络隧道连通性（适用于VMware/VirtualBox部署场景）

若WorkBuddy部署于虚拟机中，而宿主机或其他设备需通过宿主机IP访问该服务，则必须确保虚拟网络适配器处于桥接模式或NAT端口转发已正确配置，否则虚拟机IP在局域网中不可达。

1、关闭虚拟机，在VMware/VirtualBox管理界面中右键虚拟机 → “设置” → “网络适配器”，确认网络连接模式为“桥接模式”而非“NAT”或“仅主机”。

2、若必须使用NAT模式，则需进入“网络适配器 → 高级 → 端口转发”，新增规则：主机端口3001 → 虚拟机IP:3001，协议TCP。

3、启动虚拟机后，在其中执行ip a（Linux）或ipconfig（Windows），确认获取到非169.254.x.x的IPv4地址，且该地址属于当前局域网网段（如192.168.1.x或10.0.0.x）。

4、在宿主机命令行中执行ping [虚拟机IP]，确认ICMP可达；再执行telnet [虚拟机IP] 3001验证端口层连通性。

四、排查路由器UPnP或手动端口映射冲突

部分路由器开启UPnP功能后会自动劫持本地端口映射表，干扰WorkBuddy生成的内网穿透或服务发现机制，导致局域网设备解析到错误IP或连接超时。

1、登录路由器管理后台（通常为192.168.1.1或192.168.0.1），定位“高级设置 → UPnP”或“NAT转发 → UPnP设置”。

2、临时关闭UPnP功能，保存并重启路由器。

3、重启WorkBuddy服务后，在局域网另一设备浏览器中直接访问http://[宿主机IP]:3001，观察是否返回WorkBuddy欢迎页或API健康检查响应。

4、若关闭UPnP后访问恢复正常，则说明原UPnP规则存在覆盖或冲突，需清空UPnP映射表后重新配置。

五、校验WorkBuddy内置反向代理与Claw网关绑定状态

WorkBuddy依赖Claw网关组件实现跨设备指令路由，若Claw服务未运行或未监听内网接口，即使主服务端口开放，远程设备也无法建立有效通信链路。

1、在终端执行ps aux | grep claw（Linux/macOS）或任务管理器搜索claw（Windows），确认claw进程处于运行状态。

2、执行netstat -tuln | grep :3002（Claw默认端口）或lsof -i :3002，确认其绑定地址为0.0.0.0:3002而非127.0.0.1:3002。

3、若Claw未运行，前往WorkBuddy安装目录执行./claw --bind 0.0.0.0:3002 --workbuddy-url http://127.0.0.1:3001启动（Linux/macOS）或双击claw.exe并传入相同参数（Windows）。

4、Claw启动后，局域网设备需访问http://[宿主机IP]:3002而非3001，方可触发完整指令处理流程。

今天关于《WorkBuddy内网访问失败排查指南》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！