mDNS 网络
概述: FastBee 设备通过 mDNS（Multicast DNS，RFC 6762）实现局域网内的零配置域名访问，无需记忆 IP 地址即可登录设备 Web 管理界面。多台设备接入同一网络时，固件自动分配唯一域名，确保每台设备均可独立访问。
mDNS 为独立开关，启停不受 AP/STA 网络模式约束（任意模式下均可手动启用或停用），由功能配置页或外设执行规则的动作 31（启用功能）/ 32（禁用功能）控制，状态变更重启后生效，出厂默认启用。
1. mDNS 工作原理
1.1. 服务注册
设备启动 mDNS 后，在网络中广播以下服务：
| 服务类型 | 协议 | 端口 | 用途 |
|---|---|---|---|
_http | TCP | 80 | Web 管理界面 |
_fastbee | TCP | 80 | FastBee 设备发现 |
_ws | TCP | 81 | WebSocket 通信 |
1.2. 访问格式
http://<hostname>.local默认 hostname 为 fastbee，因此默认访问地址为 http://fastbee.local。
2. 多设备同网络域名分配
同一局域网内多台 FastBee 设备推荐全部使用默认命名（customDomain = fastbee），无需逐台改名：
- 固件启动时枚举
_http._tcp预探测已占用的 hostname，自动分配唯一后缀（fastbee、fastbee-2…fastbee-8） - 运行期每 30 秒做一次同名收敛（IP 大者让名），新设备即插即用
- 设备实际注册的域名以当前构建、串口日志和
/api/network/status（需登录）返回为准，不要根据设备标签或上电顺序推断自动后缀 - 需要稳定名称时，在网络配置页设置
customDomain，并用上述接口或串口日志核对结果
多设备舰队实测与验证方法见设备测试的「多设备 mDNS 域名」小节。
3. 各联网模式的访问方式
3.1. WiFi STA 模式（连接路由器）
| 访问方式 | 地址 | 条件 |
|---|---|---|
| 局域网 IP | http://<路由器分配的IP> | 始终可用（推荐） |
| mDNS 域名 | http://<hostname>.local | mDNS 启用且客户端支持 |
- mDNS 域名和 IP 均可从同一局域网内任意设备访问
- Windows 用户建议直接使用 IP 访问：Windows 默认不自带完整的 mDNS 解析（依赖 Bonjour/iTunes 等组件），
fastbee.local可能间歇性无法解析或首次解析耗时数秒，造成"页面打开慢"的假象。IP 可在设备串口启动日志、路由器后台 DHCP 列表中查看
3.2. WiFi AP 模式（设备自建热点）
| 访问方式 | 地址 | 条件 |
|---|---|---|
| AP IP | http://192.168.4.1 | 始终可用 |
| mDNS 域名 | http://<hostname>.local | mDNS 启用 |
- 用户需先连接设备 WiFi 热点才能访问
- AP IP 固定为
192.168.4.1
3.3. 4G 模式（4G + WiFi AP 混合）
4G 联网采用混合模式设计：4G 提供外网连接，同时启动 WiFi AP 热点供本地配置访问。
4G 连接成功 → 启动 WiFi AP（192.168.4.1）→ 启动 mDNS| 访问方式 | 地址 | 条件 | 访问来源 |
|---|---|---|---|
| AP 热点 IP | http://192.168.4.1 | 始终可用 | 连接设备 AP 热点 |
| mDNS 域名 | http://<hostname>.local | mDNS 启用 | 连接设备 AP 热点 |
| 4G 公网 IP | http://<运营商分配的IP> | 需真实公网 IP | 公网（受运营商限制） |
公网 IP 访问的限制：
- 多数物联网 SIM 卡分配 NAT 后的内网 IP（如
10.x.x.x、100.x.x.x），非真实公网 IP - 即使获取到公网 IP，运营商通常封禁 80/443 端口入站访问
- 判断方法：对比设备获取的 IP 与 ip.cn 查到的出口 IP，一致则为真实公网 IP
4G 失败回退：4G 连接失败时自动回退到纯 AP 模式（192.168.4.1），用户可通过热点重新配置。
3.4. 以太网模式（以太网 + WiFi AP 混合）
与 4G 类似，以太网也采用混合模式：以太网提供有线网络连接，同时启动 WiFi AP 热点。
| 访问方式 | 地址 | 条件 | 访问来源 |
|---|---|---|---|
| 以太网 IP | http://<以太网DHCP分配的IP> | 始终可用 | 以太网 LAN 内设备 |
| AP 热点 IP | http://192.168.4.1 | 始终可用 | 连接设备 AP 热点 |
| mDNS 域名 | http://<hostname>.local | mDNS 启用 | 任一接口 |
4. Web 服务器网络绑定
Web 服务器（AsyncWebServer）监听地址为 0.0.0.0:80，即所有网络接口：
0.0.0.0:80
├── WiFi STA 接口（路由器分配的 IP）
├── WiFi AP 接口（192.168.4.1）
├── 以太网接口（W5500 DHCP 分配的 IP）
└── 4G 蜂窝接口（运营商分配的 IP）因此，设备在任何联网模式下，所有活跃接口的 IP 均可访问 Web 管理界面。
5. Web 访问性能与加载机制
设备内置 Web 服务器面向资源受限的 ESP32 做了并发与内存保护，了解以下机制有助于判断"页面慢"是正常行为还是故障：
- 首屏串行加载：登录页的核心 JS 被拆分为 5 个 boot chunk 并按顺序串行加载（ESP32 的 socket 池有限，并发请求易被拒），首屏完整加载通常 2-5 秒，属正常现象
- 静态资源并发限流：同时进行的静态文件传输有上限（默认 2 路），超出时请求短暂等待后返回 503，前端自动以 300/1200/2700ms 递增退避重试；请勿同时打开多个标签页访问同一设备，会互相挤占连接
- 内存门控：可用内存（DRAM）低于阈值时新请求会被拒绝，此时优先等待 MQTT 重连等后台任务结束；MQTT 与 Web 大流量操作不建议同时进行
- 失败自动重试：弱网下个别 chunk 加载失败会自动重试（最多 4 次），无需手动刷新
排障建议：
- 优先用 IP 直连（见上文 Windows 说明）
- 关闭多余的浏览器标签页与开发者工具的网络节流
- 观察串口日志：若 Web 请求期间设备重启，属于异常
6. 自定义域名配置
自定义域名（customDomain）在网络配置页的「高级配置 → 自定义本地域名」中设置，保存后 mDNS 立即重启，新域名即时生效，无需等待网络重启。
| 场景 | 行为 |
|---|---|
| mDNS 启用 + 修改域名 | 立即重启 mDNS，新域名即时生效 |
| mDNS 禁用 | 不启动 mDNS，页面提示使用 IP 访问并显示当前 IP |
| 4G 模式 | 域名配置区域在 UI 中隐藏，mDNS 不启动 |
多设备场景推荐保持默认命名，由固件自动分配唯一后缀（见第 2 节），不建议逐台手工改名。
7. 设备发现
除直接输入域名外，还可通过 mDNS 服务发现工具扫描局域网内的 FastBee 设备：
macOS / Linux：
# 扫描 FastBee 设备
dns-sd -B _fastbee._tcp local.Windows：使用 Bonjour Browser 或 mDNS 查看工具扫描 _fastbee._tcp 服务。
编程方式：任何支持 mDNS/Bonjour 的库均可通过查询 _fastbee._tcp 服务类型发现网络中的所有 FastBee 设备，返回结果包含设备 hostname 和 IP 地址。
8. 故障排查
| 问题 | 排查方向 |
|---|---|
无法通过 .local 域名访问 | 1. 确认 mDNS 已启用 2. 确认客户端支持 mDNS（Windows 需安装 Bonjour）3. 检查串口日志中的实际域名 4. 改用 IP 直连（最可靠） |
.local 解析慢/间歇失败（Windows） | Windows mDNS 解析不稳定属已知现象，非设备故障；直接用 IP 访问即可消除 |
| 多台设备域名冲突 | 查看串口日志或 /api/network/status（需登录），确认各设备实际注册的域名 |
| 4G 模式无法远程访问 | 检查 SIM 卡是否分配公网 IP，运营商是否封禁端口 |
| mDNS 间歇性不可用 | 检查网络是否有大量 mDNS 设备造成广播风暴 |
9. 常见问题
mDNS 域名访问和 IP 直连该用哪个？
现场优先使用 IP 直连，尤其 Windows 客户端（其 mDNS 解析依赖 Bonjour 组件，可能间歇失败）。mDNS 域名适合同一局域网内的免配置访问和多设备发现，不作为唯一的可靠入口。
多台设备需要逐台设置不同的自定义域名吗？
不需要。推荐全部保持默认命名（customDomain = fastbee），固件启动时会预探测已占用的 hostname 并自动分配唯一后缀，运行期每 30 秒做同名收敛。仅当某台设备需要固定不变的域名时才单独设置 customDomain。
修改自定义域名后需要重启设备吗？
不需要。保存自定义域名后 mDNS 立即重启，新域名即时生效；但 mDNS 开关本身的启停变更需要重启后生效。
4G 模式下为什么访问不到设备的 .local 域名？
4G 模式下域名配置区域在 UI 中隐藏、mDNS 不启动，且多数物联网 SIM 卡分配的是 NAT 内网 IP，公网无法直接访问。请连接设备的 WiFi AP 热点后通过 http://192.168.4.1 访问。
10. 相关文件
| 文件 | 说明 |
|---|---|
include/network/DNSManager.h | DNS 管理器头文件，定义 mDNS 管理接口 |
src/network/DNSManager.cpp | mDNS 启停、域名分配、自定义域名实现 |
src/network/NetworkManager.cpp | 各联网模式初始化及混合模式 AP 启动 |
web-src/modules/runtime/network.js | 前端网络配置页面，域名配置 UI |