# 总体方案

## 1. 目标

开发一个 Windows 桌面客户端，用于通过 `LAN2` 直连 Ubuntu 24 设备，对 Linux 的网络进行发现、管理和配置。

## 2. 当前约束

1. Linux 发行版：`Ubuntu 24`
2. 网络管理方式：`netplan`
3. 通信协议：`UDP + HTTP`
4. 鉴权方式：固定初始化密码
5. `LAN1`、`LAN2` 仅作为逻辑标识，便于界面展示和硬件对应
6. 实际配置与操作对象为 Linux 本机真实接口名，例如 `eno1`、`enp1s0`
7. `LAN2` 长期保留固定维护地址，同时支持接 4G 路由器联网
8. 首版以新机器初始化为主，不重点处理复杂历史网络配置兼容

## 3. 总体架构

### 3.1 网口角色

#### LAN1

1. 角色：业务口逻辑标识
2. 用途：接客户业务网络
3. 地址模式：仅静态 IP
4. 网关按用户填写内容正常写入

#### LAN2

1. 角色：控制口 + 外联网口逻辑标识
2. 用途：
   - Windows 直连维护
   - 接 4G 路由器联网
3. 固定维护地址：`169.254.100.2/16`
4. 可叠加 DHCP 地址
5. 可通过 DHCP 获取网关等网络参数

### 3.2 组件划分

#### Windows 客户端

建议技术：`C# + WPF`

负责：

1. 选择本机网卡
2. 将本机网卡切换到 `169.254/16`
3. 通过 UDP 发现设备
4. 调用 HTTP API
5. 展示设备状态
6. 配置选中的目标网络接口
7. 执行关机、重启等操作

#### Linux Server

建议技术：`Go + systemd service`

负责：

1. 监听当前被识别为 `LAN2` 的真实接口上的固定维护地址
2. 响应 UDP 发现请求
3. 提供 HTTP 管理接口
4. 读取当前网络状态
5. 写入和应用 `netplan`
6. 验证配置结果
7. 失败后自动回滚
8. 执行关机、重启

首版边界：

1. 以新机器初始化为主
2. 核心目标是把选中的真实接口配置好
3. 默认修改系统现有 netplan 文件，并在修改前完整备份
4. 不重点处理复杂旧 netplan 文件接管和多文件冲突兼容

## 4. 地址与路由策略

### 4.1 LAN2 地址策略

`LAN2` 同时允许存在两个 IPv4 地址：

1. 固定维护地址：`169.254.100.2/16`
2. DHCP 地址：由 4G 路由器分配，例如 `192.168.8.x/24`

规则：

1. `169.254.100.2` 不配置网关
2. DHCP 地址可带默认网关
3. DHCP 地址可带网关等网络参数
4. Server 只通过 `169.254.100.2` 提供服务

### 4.2 LAN1 地址策略

`LAN1` 仅支持静态配置。

可配置字段：

1. IP：必填
2. 前缀长度：必填
3. 网关：选填，填写后正常写入
4. 首选 DNS：选填
5. 备用 DNS：选填

### 4.3 LAN1 特殊规则

1. `LAN1` 允许配置 `169.254.x.x`
2. 当 `LAN1` 配置为 `169.254.x.x` 时：
   - 应提示这是链路本地地址
   - 建议网关留空
   - 建议 DNS 留空
   - 一般只适合同链路通信
3. `LAN1` 的 IP、网关、DNS 按用户填写内容正常写入，具体路由优先级由系统实际路由表决定

## 5. 安全边界

### 5.1 网络访问限制

1. Server 仅监听 `169.254.100.2`
2. 当前阶段暂不限制来源 IP，仅通过密码校验控制访问
3. `LAN2` 接入 4G 路由器后，4G 网络侧理论上可达 Server，因此当前阶段要依赖密码保护

### 5.2 鉴权方式

当前采用固定初始化密码，暂时直接写死在 Server 代码中。

规则：

1. 不使用 Token
2. 不使用 Session
3. 不单独设计登录接口
4. 所有 HTTP 接口都必须校验密码
5. 密码通过 HTTP Header 传递

建议 Header：

`X-Admin-Password: <固定密码>`

注意事项：

1. 不要通过 URL 传递密码
2. 不要在日志中记录密码 Header
3. 当前阶段密码写死在代码中，后续再升级为配置文件或每机唯一密码
4. 可增加简单的密码错误次数限制