下面是mDNS 主机名访问设计文档（嵌入式局域网版），包含完整开发思路 + 技术架构 + 页面设计要点 + 验收标准，可直接作为 PRD / 技术设计 / 测试验收依据使用。

mDNS 主机名访问设计文档

（兼容 Avahi 行为，支持裸主机名访问，Go 实现）

一、设计目标

在无公网、局域网、嵌入式 Linux环境下，实现：

通过以下方式访问设备管理页面：
- http://device-name
- https://device-name
- http://device-name.local（兼容标准 mDNS）
不依赖 avahi-daemon，使用 Go 原生实现
支持多网口、多 IP、多实例广播
自动冲突检测与处理
可用于生产环境、稳定、低资源占用

二、适用范围与约束

项目	说明
网络环境	局域网（无互联网）
操作系统	Embedded Linux / Debian / Ubuntu / Yocto
存储	bbolt ymal(默认)
实现语言	Go
协议支持	mDNS、DNS（本地代理）、HTTP、HTTPS

三、总体架构设计

3.1 架构组成

系统由三部分组成：

mDNS 广播服务模块
裸主机名 DNS 代理模块
主机名管理与冲突处理模块

3.2 逻辑结构图（文字版）

浏览器 / 客户端
     |
     | DNS 查询 device-name
     |
局域网广播
     |
+----------------------------+
|   本设备 mDNS / DNS 服务   |
+----------------------------+
     |
     |---- mDNS 响应：device-name.local
     |---- DNS 代理响应：device-name
     |
HTTP/HTTPS 服务监听

四、开发思路与技术实现方案

4.1 mDNS 广播服务模块设计

功能职责：

周期性广播设备主机名
提供服务发现信息（HTTP/HTTPS 服务）
兼容 Avahi 行为

实现思路（Go）：

使用 UDP 224.0.0.251:5353
实现标准 mDNS 报文格式（RFC 6762）
注册以下服务：
- _http._tcp.local
- _https._tcp.local
- _gateway._tcp.local

广播内容：

字段	示例
主机名	device-name.local
IP 地址	192.168.1.100
端口	8082 / 443
TXT 记录	model, version, sn

4.2 裸主机名 DNS 代理模块设计

功能目标：

支持：

http://device-name
https://device-name

而不仅是：

http://device-name.local

实现思路：

在设备本地监听 DNS 端口（UDP/TCP 53）
拦截对 device-name 的解析请求
返回本设备 IP 地址（A/AAAA 记录）
对非本设备主机名请求：
- 可转发到系统默认 DNS（可配置）
- 或直接拒绝（安全模式）

技术要点：

支持多网口返回多个 IP
支持 DNS 请求并发处理
支持缓存与 TTL 控制

4.3 主机名管理与冲突处理模块

功能职责：

管理设备主机名
检测主机名冲突
自动解决冲突

冲突检测机制：

在启动时发送 mDNS probe 查询
若发现同名主机存在：
- 自动追加后缀：device-name-2
- 写入持久存储（bbolt）

持久化内容：

项目	存储
主机名	hostname
冲突历史	hostname_conflicts
用户设置	hostname_user_defined

4.4 HTTPS 支持与证书策略

支持导入证书
支持自动生成自签证书
证书与主机名绑定
支持证书轮换提醒

五、前端页面设计要点（系统设置 → 主机名访问）

5.1 页面字段

字段	描述
主机名	device-name
启用 mDNS 广播	开关
启用裸主机名访问	开关
HTTP 端口	默认 8082
HTTPS 端口	默认 443
HTTPS 证书	上传 / 自动生成
绑定网口	eth0 / eth1 / wlan0
广播状态	正常 / 冲突 / 异常

5.2 状态展示区

显示：

当前访问地址：
当前广播状态
最近一次冲突检测结果

六、安全与资源控制设计

项目	设计策略
网络范围	仅监听局域网接口
权限控制	非 root 进程运行
防滥用	请求频率限制
内存控制	固定大小缓存
CPU 控制	事件驱动、非轮询

七、异常处理与降级机制

异常场景	处理策略
DNS 53 端口被占用	自动降级为 mDNS-only
mDNS 广播失败	重试 + 告警
主机名冲突	自动重命名
网络接口变化	自动重广播
证书过期	提前告警

八、开发阶段划分建议

阶段	内容
阶段 1	实现 mDNS 广播（.local）
阶段 2	实现裸主机名 DNS 代理
阶段 3	冲突检测与自动修复
阶段 4	HTTPS 与证书管理
阶段 5	UI 配置与状态可视化

九、验收标准（测试与验收指标）

9.1 功能验收

项目	验收标准
mDNS 发现	avahi-browse 可发现设备
`.local` 访问	http://device-name.local 可访问
裸主机名访问	http://device-name 可访问
HTTPS 支持	https://device-name 可访问
多网口广播	每个接口均广播
主机名冲突处理	自动更名且可访问
配置持久化	重启后主机名不变

9.2 性能与稳定性验收

项目	标准
DNS 响应时间	≤ 10 ms
mDNS 广播周期	≤ 60 秒
CPU 占用	≤ 1%（空闲状态）
内存占用	≤ 10 MB
长时间运行	7×24 小时无异常

9.3 兼容性验收

客户端	期望结果
Windows 浏览器	可直接访问
macOS Safari / Chrome	可访问
Linux 浏览器	可访问
Android	可访问
iOS	可访问

9.4 安全验收

项目	标准
外网不可访问	仅局域网有效
非授权解析	不响应非本机主机名
HTTPS 安全	支持 TLS1.2+

十、总结

该设计方案实现了：

标准 mDNS 服务发现能力
裸主机名直连访问能力（非 .local）
与 Avahi 行为兼容但更轻量
适配嵌入式设备、离线局域网场景
高可用、低资源、可配置、可运维