WebSocket 端口转发配置指南

目标: 为公网域名 test888.iepose.cn 配置 WebSocket 端口（8765）转发，以启用完整的实时功能

为什么需要配置？

当前状态： - ✅ HTTP 服务（8080端口）已配置端口转发，公网可访问 - ⚠️ WebSocket 服务（8765端口）未配置端口转发 - ❌ 移动设备无法使用实时功能（实时会话输出、自动刷新等）

配置后效果： - ✅ 公网域名支持完整的 WebSocket 实时功能 - ✅ 移动设备可以实时查看会话输出 - ✅ 所有设备均可使用完整功能

配置步骤

步骤1: 登录路由器/防火墙管理界面

打开浏览器，访问路由器管理页面
常见地址：
- http://192.168.1.1 （光猫）
- http://192.168.31.1 （小米路由）
- http://192.168.2.1 （千兆网关）
输入管理员账号密码登录
如忘记密码，请查阅路由器说明书或联系网络管理员

步骤2: 找到端口转发设置

不同品牌路由器界面略有差异，通常在以下位置：

小米路由器: - 进入"高级设置" → "端口转发"

华为/中兴光猫: - 进入"应用" → "端口映射"

TP-Link路由器: - 进入"转发规则" → "虚拟服务器"

其他品牌: - 查找类似"端口转发"、"端口映射"、"虚拟服务器"、"NAT"等设置

步骤3: 添加端口转发规则

需要添加 2条端口转发规则（对应两个内网IP）：

规则1: 内部网（小米路由）

配置项	值
规则名称	zhineng-bridge-ws-internal
外部端口	8765
内部端口	8765
内部IP	192.168.31.99
协议	TCP
状态	启用/生效

规则2: 千兆互联网（直连）

配置项	值
规则名称	zhineng-bridge-ws-direct
外部端口	8765
内部端口	8765
内部IP	192.168.2.1
协议	TCP
状态	启用/生效

重要说明: - 外部端口和内部端口都设置为 8765 - 内部IP需要根据实际网络配置调整（见下方"如何确认内网IP"） - 协议选择 TCP（WebSocket 是基于 TCP 的） - 如果只有一条规则可用，优先选择 192.168.31.99

步骤4: 保存并重启

保存端口转发规则
根据需要重启路由器或重新加载规则
等待约 30-60 秒让规则生效

如何确认内网IP？

ZhinengAI 服务器有两个内网IP：

方法1: 查看本机网络配置

在 ZhinengAI 服务器上执行：

hostname -I

输出类似：

192.168.2.1 192.168.31.99 10.113.22.99 100.66.1.8 ...

其中： - 192.168.31.99 = 内部网（小米路由） - 192.168.2.1 = 千兆互联网（直连）

方法2: 通过 Web UI 查看

访问 http://test888.iepose.cn/web/ui/network-connectivity.html

查看"网络访问状态"部分，可以看到各个网络的IP地址。

方法3: Ping 测试

# 测试内部网IP是否可达
ping 192.168.31.99

# 测试千兆网IP是否可达
ping 192.168.2.1

配置验证

验证1: 端口连通性测试

从外网测试（使用手机或其他外网设备）:

# Linux/Mac
nc -zv test888.iepose.cn 8765

# Windows (PowerShell)
Test-NetConnection -ComputerName test888.iepose.cn -Port 8765

# 或者使用在线工具
# 访问: https://www.yougetsignal.com/tools/open-ports/
# 输入: test888.iepose.cn
# 端口: 8765

预期结果:

Connection to test888.iepose.cn 8765 port [tcp/*] succeeded!

验证2: WebSocket 连接测试

方法A: 使用 wscat 工具

# 安装 wscat（如果未安装）
npm install -g wscat

# 测试 WebSocket 连接
wscat -c ws://test888.iepose.cn:8765

# 发送测试消息
> {"type":"ping"}

# 应该收到响应
< {"type":"pong","timestamp":"..."}

方法B: 使用浏览器开发者工具

打开浏览器，访问 http://test888.iepose.cn/web/ui/index.html
按 F12 打开开发者工具
切换到"Console"（控制台）标签
查看是否有 WebSocket 连接成功的日志

预期结果:

✅ WebSocket connected successfully

验证3: 功能测试

访问 http://test888.iepose.cn/web/ui/index.html
检查页面顶部状态，应该显示"已连接"
创建一个新的会话
观察会话输出是否实时更新（无需手动刷新）
检查浏览器控制台是否有 WebSocket 错误

预期结果: - ✅ 页面状态显示"已连接" - ✅ 会话输出实时更新 - ✅ 浏览器控制台无 WebSocket 错误

常见问题

Q1: 端口转发配置后仍然无法连接

可能原因及解决方案:

防火墙阻止
检查服务器防火墙规则

确保 8765 端口允许入站流量

# 检查防火墙状态
sudo ufw status

# 允许 8765 端口
sudo ufw allow 8765/tcp

服务未监听在所有网络接口
检查 WebSocket 服务是否绑定到 0.0.0.0
而不是只绑定到 127.0.0.1
DNS 缓存问题
清除本地 DNS 缓存
等待 DNS 传播（通常 5-30 分钟）
路由器规则冲突
检查是否有其他规则占用了 8765 端口
确保规则优先级正确

Q2: 可以连接但无法建立 WebSocket 握手

可能原因: - HTTP 代理或反向代理未正确配置 - WebSocket Upgrade 头被过滤

解决方案: - 检查反向代理配置（如使用 Nginx） - 确保支持 WebSocket 协议升级

Q3: 连接不稳定，频繁断开

可能原因: - NAT 超时设置过短 - 网络质量不稳定

解决方案: - 调整路由器 NAT 超时时间 - 检查网络连接质量 - 使用心跳包保持连接（前端已实现）

Q4: 配置后内网无法访问

原因: 可能是路由器 NAT 环回功能未启用

解决方案: - 启用路由器的 NAT 环回（NAT Loopback）功能 - 或继续使用内网IP访问

安全建议

配置端口转发后，建议采取以下安全措施：

1. 启用认证

WebSocket 服务已启用认证机制，确保： - 使用强密码 - 定期更换密码 - 启用速率限制

2. 配置访问控制

限制特定 IP 地址访问（如可能）
定期审查访问日志

3. 启用 HTTPS/WSS

# 生产环境建议启用
# 需要配置 SSL 证书
# 使用 WSS (WebSocket Secure) 替代 WS

4. 监控异常访问

定期检查访问日志
设置异常访问告警
及时封禁恶意IP

网络拓扑参考

Internet (公网)
    │
    ▼
公网域名: test888.iepose.cn (103.215.36.110)
    │
    │ 端口转发 (8080, 8765)
    ▼
路由器/防火墙
    │
    ├──▶ 192.168.31.99 (内部网 - 小米路由)
    │       │
    │       └──▶ ZhinengAI Server (HTTP: 8080, WS: 8765)
    │
    └──▶ 192.168.2.1 (千兆网 - 直连)
            │
            └──▶ ZhinengAI Server (HTTP: 8080, WS: 8765)

配置清单

完成配置后，请确认以下项目：

[ ] 已登录路由器/防火墙管理界面
[ ] 已找到端口转发设置
[ ] 已添加端口转发规则（192.168.31.99:8765）
[ ] 已添加端口转发规则（192.168.2.1:8765）
[ ] 已保存并应用规则
[ ] 已从外网验证端口 8765 可访问
[ ] 已验证 WebSocket 连接成功
[ ] 已测试实时会话输出功能
[ ] 已检查服务器防火墙规则
[ ] 已考虑安全加固措施

需要帮助？

如果配置过程中遇到问题：

查看日志

# 查看WebSocket服务器日志
tail -f /tmp/relay_server.log

检查服务状态

# 检查WebSocket服务是否运行
ps aux | grep relay-server

测试本地连接

# 从服务器内部测试
curl -I http://localhost:8765

联系支持
查看网络设备文档
联系网络管理员
参考路由器官方配置指南

配置完成后，请返回"网络连通性检测"页面重新测试 http://test888.iepose.cn/web/ui/network-connectivity.html