系统设置模块设计文档（嵌入式局域网边缘计算系统）
版本信息
- 文档版本：v1.0
- 适用阶段：第一～第三阶段统一
- 适用环境：嵌入式 Linux / 局域网 / 离线部署
- 存储：bbolt（go.etcd.io/bbolt）以及本地 yaml 配置文件
- 实现语言：Go
一、模块定位与目标
系统设置模块是边缘计算设备的基础运行平台管理中心，用于管理设备的时间、网络、路由、高可用、主机名访问等底层能力，确保设备在无公网、复杂局域网拓扑、多设备协同环境下稳定运行。
目标：
- 零配置接入局域网
- 多网口、多 IP、多路由支持
- 主备双机高可用保障
- 主机名直接访问（无
.local） - 完全脱离互联网依赖
- 与 Avahi 行为兼容，但 Go 原生实现
二、一级页面结构
系统设置一级页面包含以下模块：
- 时间设置
- 网络接口配置
- 静态路由管理
- 双主机备份（主备热备）
- 主机名访问（mDNS + 裸主机名）
- 系统状态与配置生效管理
三、时间设置模块设计
3.1 功能目标
- 支持手动时间设置与 NTP 自动同步
- 兼容 systemd / 非 systemd / busybox 系统
- 同步系统时间与硬件 RTC
3.2 页面设计
时间模式选择
- ⭕ 手动设置时间
- ⭕ 自动同步（NTP）
手动设置时间
字段：
| 字段 | 描述 |
|---|---|
| 日期时间 | YYYY-MM-DD HH:MM:SS |
| 时区 | Asia/Shanghai 等 |
| 写入硬件时间 | 开关 |
操作逻辑：
- 设置系统时间 → 写入 RTC → 通知业务模块刷新时间缓存
NTP 自动同步
字段：
| 字段 | 描述 |
|---|---|
| NTP 服务器 | 支持多个 IP/主机名 |
| 同步周期 | 默认 1 小时 |
| 启用状态 | 开启 / 停止 |
系统自动识别并适配：
- systemd-timesyncd
- chronyd
- ntpd
- busybox ntpd
3.3 验收指标
| 项目 | 标准 |
|---|---|
| 手动设置生效 | 时间立即更新，RTC 写入成功 |
| NTP 同步成功 | 时间误差 ≤ 1 秒 |
| 服务兼容性 | 多 Linux 系统可用 |
| 重启保持 | 重启后时间正确 |
四、网络接口配置模块设计
4.1 功能目标
- 自动加载全部网口
- 支持每个网口配置多个 IP
- 支持 DHCP / 静态 / 混合模式
- 兼容多种 Linux 网络管理机制
4.2 页面设计
网口列表视图
字段：
| 字段 | 描述 |
|---|---|
| 接口名 | eth0 / eth1 / wlan0 |
| MAC 地址 | 硬件标识 |
| 链路状态 | UP / DOWN |
| IP 列表 | 支持多个 |
| 默认网关 | 可选 |
IP 配置能力
- 添加 / 编辑 / 删除 IP
-
每个 IP 支持：
- IPv4 / IPv6
- 子网掩码 / 前缀
- 是否主 IP
支持模式：
- DHCP
- 静态 IP
- DHCP + 静态 IP 混合
4.3 验收指标
| 项目 | 标准 |
|---|---|
| 网口识别 | 所有网口可见 |
| 多 IP 生效 | 多 IP 可访问 |
| 模式切换 | 无冲突 |
| 重启保持 | 配置持久化 |
五、静态路由管理模块设计
5.1 功能目标
- 支持多个静态路由
- 支持不同接口、不同网关
- 支持优先级控制
5.2 页面设计
字段：
| 字段 | 描述 |
|---|---|
| 目标网段 | 192.168.10.0/24 |
| 网关 | 192.168.1.1 |
| 出接口 | eth0 / eth1 |
| 优先级 | Metric |
| 启用状态 | 开关 |
支持批量导入/导出（JSON/YAML）。
5.3 验收指标
| 项目 | 标准 |
|---|---|
| 路由生效 | ip route 可见 |
| 多规则支持 | 多路由并存 |
| 优先级正确 | 路由选择正确 |
| 重启保持 | 重启后仍生效 |
六、双主机备份模块设计（主备热备）
6.1 功能目标
- 主机采集，备机热备
- 自动心跳检测与切换
- 配置与数据一致性保障
- 切换无数据丢失
6.2 页面设计
模式配置
| 角色 | 描述 |
|---|---|
| 主机 | 负责采集、计算、上报 |
| 备机 | 监听心跳、接管业务 |
心跳与保活
配置项：
| 字段 | 描述 |
|---|---|
| 心跳方式 | TCP / UDP / HTTP |
| 心跳周期 | 默认 2 秒 |
| 超时阈值 | 默认 5 秒 |
| 连续失败次数 | 默认 3 次 |
切换策略
- 自动切换
- 手动切换
- 自动回切（可选）
数据同步范围
- 设备配置
- 通道配置（南向/北向）
- 规则与动作
- bbolt 本地缓存数据
同步方式：
- 定时增量同步
- 变更事件实时同步
6.3 验收指标
| 项目 | 标准 |
|---|---|
| 心跳检测 | 丢失可准确识别 |
| 自动切换 | ≤ 5 秒完成 |
| 数据一致性 | 切换后无差异 |
| 回切机制 | 可配置可验证 |
| 零数据丢失 | 不中断业务 |
七、主机名访问模块设计（mDNS + 裸主机名，Go 实现）
7.1 功能目标
-
通过以下方式访问设备：
http://device-namehttps://device-name
-
同时兼容：
http://device-name.local
- 不依赖 avahi-daemon，Go 原生实现
- 支持多网口广播
7.2 技术实现策略（核心）
标准 mDNS 仅支持
.local域名，裸主机名访问通过组合方案实现：
| 机制 | 用途 |
|---|---|
| mDNS 广播 | 兼容 Avahi 行为 |
| 内置 DNS 代理（Go 实现） | 拦截裸主机名解析 |
| DHCP 名称下发（可选） | 网络侧增强支持 |
最终实现：
- mDNS 负责服务发现与
.local解析 - 内置 DNS 代理负责裸主机名解析
7.3 页面设计
主机名配置区
| 字段 | 描述 |
|---|---|
| 主机名 | device-name |
| 启用 mDNS | 开关 |
| 启用裸主机名访问 | 开关 |
| HTTP 端口 | 默认 8082 |
| HTTPS 端口 | 默认 443 |
| HTTPS 证书 | 上传 / 自动生成 |
| 绑定网口 | eth0 / eth1 / wlan0 |
状态显示区
- 当前广播状态：正常 / 冲突 / 停止
-
当前访问地址：
7.4 mDNS 广播服务清单
| 服务 | 协议 |
|---|---|
| _http._tcp | Web 管理 |
| _https._tcp | 安全 Web 管理 |
| _gateway._tcp | 设备专用服务 |
TXT 记录包含：
- 设备型号
- 固件版本
- 序列号
- 管理端口
7.5 内置 DNS 代理能力
功能：
- 监听 UDP/TCP 53 端口
- 拦截对
device-name的解析请求 - 返回设备当前 IP
- 其他请求可转发系统默认 DNS（可选）
特性：
- 仅监听局域网接口
- 支持 A / AAAA 记录
- 支持多网口多 IP 返回
7.6 异常处理
| 场景 | 处理策略 |
|---|---|
| 主机名冲突 | 自动加后缀 device-name-2 |
| DNS 端口被占用 | 自动降级为 mDNS-only |
| 网络变化 | 自动重广播 |
| 证书过期 | 提前告警 |
7.7 验收指标
| 项目 | 标准 |
|---|---|
| 裸主机名访问 | http://device-name 可访问 |
| HTTPS 支持 | https://device-name 可访问 |
| Avahi 兼容 | avahi-browse 可发现服务 |
| 多系统兼容 | Windows/macOS/Linux 可用 |
| 多网口支持 | 各接口均广播 |
| 冲突处理 | 自动重命名 |
八、系统状态与配置生效管理
功能设计
-
所有配置支持：
- 保存但不立即生效
- 保存并立即生效
- 回滚到上一个版本
-
显示配置状态：
- 已生效
- 待重启
- 生效失败（含错误原因）
九、整体验收指标汇总
| 模块 | 验收标准 |
|---|---|
| 时间设置 | 手动/NTP 均稳定 |
| 网络接口 | 多网口、多 IP 正常 |
| 静态路由 | 多路由可控 |
| 双主机备份 | 切换 ≤ 5 秒，无丢数据 |
| 主机名访问 | 裸主机名与 mDNS 可用 |
| 配置管理 | 支持生效、回滚、持久化 |