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

mDNS 主机名访问设计文档

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

一、设计目标

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

二、适用范围与约束

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

三、总体架构设计

3.1 架构组成

系统由三部分组成：

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

3.2 逻辑结构图（文字版）

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

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

4.1 mDNS 广播服务模块设计

功能职责：

实现思路（Go）：

广播内容：

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

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

功能目标：

支持：

而不仅是：

实现思路：

技术要点：

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

功能职责：

冲突检测机制：

持久化内容：

项目 存储
主机名 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+

十、总结

该设计方案实现了：