NetworkTool/docs/06-netplan修改策略.md

netplan 修改策略

1. 目标

定义首版 NetTool 在 Ubuntu 24 上修改 netplan 的具体策略，重点说明：

1. 修改哪个文件
2. 修改哪些字段
3. 保留哪些字段
4. 什么时候回滚

2. 首版场景

首版默认场景是新机器初始化。

特点：

1. 一般只有一个 netplan YAML 文件
2. 不重点处理复杂历史网络配置兼容
3. 核心目标是把选中的真实接口配置正确写入系统

3. 文件定位规则

3.1 默认规则

1. 扫描 /etc/netplan/*.yaml
2. 如果只存在一个 YAML 文件：
   • 直接将该文件作为本次修改目标文件
3. 如果不存在 YAML 文件：
   • 返回错误，由后续实现决定是否补充自动创建能力
4. 如果存在多个 YAML 文件：
   • 首版直接返回错误
   • 不自动猜测该改哪个文件

3.2 为什么这样定

原因：

1. 符合新机器初始化场景
2. 可避免误改错误文件
3. 可避免首版陷入复杂多文件兼容

4. 修改方式

4.1 总体原则

首版不建议做字符串替换或正则替换。

建议方式：

1. 先按 YAML 结构解析目标文件
2. 找到目标真实接口对应节点
3. 按结构化方式更新字段
4. 再将整个文件重新写回

说明：

1. 这是“修改现有文件”
2. 但实现方式仍然应该是结构化重写
3. 不建议做纯文本级局部替换

4.2 修改范围

首版只修改：

1. 用户选中的目标真实接口配置
2. 必要时补充当前管理接口的固定维护地址配置

不主动修改：

1. 其他无关接口
2. 与本次目标接口无关的系统网络字段

5. 目标接口字段处理规则

假设当前目标真实接口为 enp1s0。

5.1 需要写入或覆盖的字段

对于目标接口，首版建议由 NetTool 明确写入或覆盖以下字段：

1. dhcp4
   • 设为 false
2. addresses
   • 按用户输入的一个或多个 IP 和前缀长度生成
3. routes
   • 若用户填写默认网关或静态路由，则写入
   • 默认网关表达为 to: default
   • 若用户未填写路由，则删除该字段
4. nameservers.addresses
   • 若用户填写 DNS，则写入
   • 若用户未填写 DNS，则删除或置空

5.2 建议删除的旧字段

若目标接口原本存在以下字段，首版建议按新配置重置，避免旧状态残留：

1. 旧的 addresses
2. 旧的 gateway4
3. 旧的 nameservers
4. 旧的 dhcp4
5. 旧的 routes

5.3 建议保留的字段

若目标接口下已存在且与本次配置无直接冲突，首版可考虑保留：

1. optional
2. mtu
3. wakeonlan

但首版如果实现复杂，也可以先不保留这些增强字段，重点保证主配置正确。

6. 管理接口字段处理规则

当前管理接口对应逻辑标识为 LAN2，但实际操作对象仍是真实接口名。

首版目标：

1. 保证管理接口上有固定维护地址 169.254.100.2/16
2. 允许该接口继续通过 DHCP 获取外联地址

建议处理：

1. 若管理接口节点已存在：
   • 补充或更新固定维护地址
   • 保留 DHCP4 能力
2. 若管理接口节点不存在：
   • 由 NetTool 创建该接口节点

7. 备份与回滚规则

7.1 备份规则

每次应用配置前：

1. 先备份目标 netplan 文件
2. 备份文件应完整保留原始内容
3. 备份文件路径由实现决定，但应可用于立即回滚

7.2 应用规则

1. 备份完成后写回修改后的文件
2. 执行 netplan apply
3. 客户端仍可连接时，在限定时间内自动确认保留配置
4. 未自动确认或执行失败时恢复本次备份并再次执行 netplan apply

7.3 回滚规则

出现以下情况时执行回滚：

1. netplan apply 执行失败
2. 客户端未能在超时时间内自动确认保留配置
3. 其他明确判定为配置失败的情况

回滚步骤：

1. 恢复备份文件
2. 再次执行 netplan apply
3. 记录回滚结果

8. 首版不处理的情况

首版建议明确不自动处理以下情况：

1. /etc/netplan 下存在多个 YAML 文件
2. 多个文件共同描述同一接口
3. 复杂路由策略合并
4. IPv6 配置兼容
5. 复杂自定义 nameserver/search 域保留

这些情况可直接返回错误，由后续版本再扩展。

9. 建议实现顺序

1. 先完成“定位单个 netplan 文件”能力
2. 再完成“读取并解析 YAML 结构”能力
3. 再完成“修改目标真实接口字段”能力
4. 再完成“备份、写回、apply、回滚”闭环

10. 当前推荐结论

首版 netplan 修改策略建议固定为：

1. 默认认为系统只有一个 netplan YAML 文件
2. 修改该现有文件
3. 修改前先完整备份
4. 按 YAML 结构更新目标真实接口字段
5. 失败则用原文件回滚