# 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. 失败则用原文件回滚