📘 系统设置功能下的网络模块技术设计说明
（嵌入式设备 · 局域网环境 · Linux 内核 · Windows 行为兼容版）
1. 文档目的
本技术设计说明用于指导嵌入式边缘计算设备中网络配置与静态路由模块的系统设计、架构实现、功能边界与验证策略，重点解决以下问题：
- 在 Linux 系统上实现与 Windows 网络行为一致的配置模型；
- 支持多网口、多 IP、多网关、多路由的复杂局域网部署；
- 确保网络配置的持久化、安全性、稳定性与可运维性；
- 为前端页面设计、后端服务接口、系统服务管理提供统一技术规范。
2. 设计目标
| 目标项 |
技术要求 |
| 行为一致性 |
网络行为与 Windows 网络管理模型一致 |
| 跨平台兼容 |
支持多 Linux 网络管理机制 |
| 稳定可靠 |
网络变更不影响系统长期运行 |
| 可回滚 |
错误配置可自动恢复 |
| 可持久化 |
重启后配置自动恢复 |
| 易运维 |
运维人员无需掌握 Linux 命令 |
3. 设计范围
本模块包含以下子系统：
- 网络接口管理模块
- IP 地址配置模块
- 网关与默认路由管理模块
- 静态路由管理模块
- 配置持久化与恢复模块
- 网络变更事务与回滚模块
- 系统服务协同模块（NTP、mDNS、HA、时间同步等接口协作）
4. 架构设计
4.1 系统分层架构
┌────────────────────────────┐
│ 前端管理界面 │
└──────────────┬─────────────┘
│ REST / RPC
┌──────────────▼─────────────┐
│ 网络管理服务层 │
│ - 接口管理服务 │
│ - IP配置服务 │
│ - 网关管理服务 │
│ - 路由管理服务 │
│ - 事务与回滚服务 │
│ - 持久化服务 │
└──────────────┬─────────────┘
│ 适配器层
┌──────────────▼─────────────┐
│ 网络系统适配层（Adapter） │
│ - systemd-networkd │
│ - NetworkManager │
│ - netplan │
│ - ifupdown │
│ - 原生 netlink │
└──────────────┬─────────────┘
│
┌──────────────▼─────────────┐
│ Linux 内核网络栈 │
└────────────────────────────┘
4.2 组件职责划分
| 组件 |
职责 |
| 网络管理服务 |
接收前端配置请求，统一调度网络变更 |
| 接口管理服务 |
管理网卡状态、接口 Metric、多 IP |
| 路由管理服务 |
管理静态路由、默认路由、Metric |
| 事务管理服务 |
保证配置变更原子性与可回滚 |
| 持久化服务 |
将配置写入 bbolt 并生成系统配置文件 |
| 适配器层 |
屏蔽不同 Linux 网络管理机制差异 |
5. 数据模型设计
5.1 网络接口模型（NetworkInterface）
| 字段 |
类型 |
说明 |
| Name |
string |
接口名（eth0 / wlan0） |
| MAC |
string |
MAC 地址 |
| Status |
enum |
UP / DOWN |
| InterfaceMetric |
int |
接口优先级（Windows Interface Metric 语义） |
| IPConfigs |
[]IPConfig |
IP 配置列表 |
| Gateways |
[]GatewayConfig |
网关配置列表 |
| Enabled |
bool |
接口启用状态 |
5.2 IP 配置模型（IPConfig）
| 字段 |
类型 |
说明 |
| Address |
string |
IP 地址 |
| Prefix |
int |
前缀长度 |
| Version |
enum |
IPv4 / IPv6 |
| Source |
enum |
DHCP / Static |
| Enabled |
bool |
是否启用 |
5.3 网关模型（GatewayConfig）
| 字段 |
类型 |
说明 |
| Gateway |
string |
网关地址 |
| Metric |
int |
网关优先级 |
| Interface |
string |
所属接口 |
| Scope |
enum |
Default / Specific |
| Enabled |
bool |
是否启用 |
5.4 静态路由模型（StaticRoute）
| 字段 |
类型 |
说明 |
| Destination |
string |
目标网络 |
| Prefix |
int |
前缀长度 |
| Gateway |
string |
网关地址 |
| Interface |
string |
出接口 |
| Metric |
int |
路由优先级 |
| Enabled |
bool |
是否启用 |
5.5 配置事务模型（NetworkTransaction）
| 字段 |
类型 |
说明 |
| ID |
string |
事务ID |
| Changes |
[]ChangeSet |
变更集合 |
| Status |
enum |
Pending / Applied / RolledBack |
| Timestamp |
time |
创建时间 |
| RollbackPoint |
string |
回滚点 |
6. 行为逻辑设计（Windows 语义对齐）
6.1 默认路由选择逻辑
优先级计算顺序：
- 路由最长前缀匹配
- Route Metric 最小
- Interface Metric 最小
- Gateway Metric 最小
行为与 Windows 路由选择逻辑一致。
6.2 多 IP 行为
- 单接口可绑定多个 IPv4/IPv6 地址；
- DHCP 地址与多个静态地址可共存；
- 不强制设置主 IP；
- 所有启用 IP 参与监听与响应。
6.3 多网关行为
- 每接口支持多个网关；
- 支持多个默认网关；
- 使用 Metric 控制默认流量走向；
- 网关失效时自动切换至下一个可用网关。
7. 网络配置执行流程
7.1 标准变更流程
- 前端提交网络配置变更请求；
- 后端生成 NetworkTransaction；
- 校验配置合法性与冲突；
- 持久化配置至 bbolt；
- 调用适配器层生成系统配置文件；
- 热更新网络配置（不中断系统服务）；
- 验证网络连通性；
- 标记事务完成或触发回滚。
7.2 回滚机制
触发条件：
- 网络连通性校验失败；
- 网关不可达；
- 默认路由不可用；
- 接口无法激活。
回滚策略：
- 恢复上一次稳定配置；
- 恢复默认路由与管理 IP；
- 记录回滚事件并上报系统日志。
8. 适配器层设计（多 Linux 网络机制兼容）
8.1 支持机制
| 网络管理机制 |
支持方式 |
| systemd-networkd |
原生配置生成 |
| NetworkManager |
nmcli 接口适配 |
| netplan |
YAML 文件生成 |
| ifupdown |
/etc/network/interfaces 生成 |
| BusyBox / 嵌入式 |
netlink + iproute2 |
8.2 适配器接口规范
所有适配器需实现统一接口：
- ApplyInterfaceConfig()
- ApplyIPConfig()
- ApplyGatewayConfig()
- ApplyRouteConfig()
- ReloadNetwork()
- ValidateNetwork()
9. 持久化与恢复设计
9.1 存储方案
- 使用 bbolt 数据库存储网络配置；
- 每次配置变更生成版本快照；
- 支持历史版本回滚。
9.2 启动恢复流程
- 系统启动；
- 从 bbolt 加载最新有效配置；
- 调用适配器层生成系统配置；
- 应用网络配置；
- 验证网络状态；
- 标记系统网络为“已就绪”。
10. 安全设计
| 风险点 |
对策 |
| 错误配置导致失联 |
事务机制 + 自动回滚 |
| 非授权修改 |
配置接口鉴权 |
| 路由冲突 |
冲突检测与阻断 |
| DHCP 伪造 |
可选 DHCP 白名单 |
11. 性能与资源约束设计
| 项目 |
设计约束 |
| 内存占用 |
网络服务常驻 ≤ 20MB |
| CPU 占用 |
配置变更时峰值 ≤ 10% |
| 配置写入 |
bbolt 写入 ≤ 5ms |
| 热更新 |
网络变更 ≤ 2s 内完成 |
12. 验证与验收标准（技术层面）
12.1 功能验证项
| 模块 |
验证点 |
| 多 IP |
多 IP 并存且可通信 |
| 多网关 |
Metric 控制正确 |
| 默认路由 |
路由选择符合 Windows 行为 |
| 静态路由 |
路由生效且持久化 |
| 回滚机制 |
错误配置自动回滚 |
| 重启恢复 |
网络配置重启保持 |
12.2 可靠性验证
- 连续网络配置变更 ≥ 1000 次无异常；
- 模拟断网、网关失效、接口 DOWN，系统自动恢复；
- 电源异常断电后，网络配置完整恢复。
13. 与其他系统模块协作关系
| 模块 |
协作方式 |
| 时间同步模块 |
依赖网络稳定性 |
| mDNS 模块 |
依赖接口 IP 正确配置 |
| 双主机备份 |
依赖多接口与路由优先级 |
| 南向采集模块 |
依赖网络连通性 |
| 北向上报模块 |
依赖默认路由选择 |