NetworkTool/docs/05-Server模块设计.md

Server 模块设计

1. 目标

定义 Linux Server 的内部模块划分、职责边界和建议实现顺序，作为后续编码的实现基线。

2. 设计原则

1. 保持模块职责单一
2. 先保证主链路可用，再补充增强能力
3. 配置写入与任务执行分离
4. 接口识别、协议处理、系统配置解耦
5. 回滚能力必须独立存在，不能散落在各业务处理函数中
6. 首版以新机器初始化为主，复杂历史配置兼容不是重点

3. 模块划分

3.1 配置模块

建议名称：config

职责：

1. 保存 Server 固定参数
2. 提供统一配置读取入口
3. 输出运行时使用的配置对象

当前阶段建议包含：

1. HTTP 监听端口
2. UDP 发现端口
3. 固定维护地址 169.254.100.2/16
4. 固定初始化密码
5. 日志级别
6. 默认 HTTP 端口为 48888
7. 支持通过启动参数覆盖维护 IP 和 HTTP 端口
8. 支持通过 --password 启动参数覆盖默认密码

说明：

1. 当前阶段密码虽然写死在代码中，但仍建议通过该模块集中输出
2. 这样后续改为配置文件时，不需要改动上层业务逻辑

3.2 日志模块

建议名称：logger

职责：

1. 输出统一格式日志
2. 区分信息日志、警告日志、错误日志
3. 对敏感字段做过滤

约束：

1. 不记录 X-Admin-Password
2. 不明文输出完整敏感请求头
3. 网络配置变更要写审计日志

3.3 接口枚举与识别模块

建议名称：network/interfaces

职责：

1. 枚举系统物理有线接口
2. 过滤虚拟接口
3. 输出真实接口信息
4. 判断当前管理接口
5. 生成目标接口候选列表
6. 在首版启动前为管理接口注入维护地址

建议输出字段：

1. 真实接口名
2. MAC 地址
3. 链路状态
4. 当前 IPv4 列表
5. 是否为当前管理接口
6. 是否为建议目标接口
7. 逻辑展示标识

3.4 UDP 发现模块

建议名称：discovery

职责：

1. 监听 UDP 广播请求
2. 解析发现报文
3. 优先按收到广播的本地网卡生成发现响应
4. 返回设备基础信息

边界：

1. 仅负责发现，不做网络配置
2. 不负责密码校验
3. 只依赖设备信息与接口识别模块

3.5 HTTP 服务模块

建议名称：httpserver

职责：

1. 暴露 HTTP API
2. 路由请求到业务处理器
3. 返回统一 JSON 响应

边界：

1. 不直接写系统配置
2. 不直接处理 netplan 文件
3. 只做协议层编排

3.6 HTTP 认证与访问控制模块

建议名称：auth

职责：

1. 校验来源 IP 是否属于 169.254.0.0/16
2. 校验请求目标是否为维护地址
3. 校验 X-Admin-Password
4. 拒绝未授权请求

当前阶段调整：

1. 暂时取消来源 IP 限制
2. 仅保留密码校验
3. 当前默认密码为 hvAC2026#%

边界：

1. 该模块只返回通过/失败结果
2. 不处理具体业务逻辑

3.7 设备信息模块

建议名称：deviceinfo

职责：

1. 提供设备 ID
2. 提供主机名
3. 提供 Ubuntu 版本
4. 提供 Server 版本
5. 提供运行时长等基础信息

3.8 网络配置读取模块

建议名称：network/configreader

职责：

1. 读取指定真实接口的当前网络配置
2. 输出统一配置结构
3. 提供给接口状态页和配置页回填使用

建议输出字段：

1. 接口名
2. IP
3. 前缀长度
4. 网关
5. DNS

3.9 配置校验模块

建议名称：network/validator

职责：

1. 校验目标接口是否存在
2. 校验 IP 格式
3. 校验前缀长度
4. 校验静态 IP 不能是所在网段的网络地址或广播地址
5. 校验网关格式和同网段关系
6. 校验 DNS 格式
7. 返回警告信息和错误信息

说明：

1. 该模块只做校验，不写配置
2. 允许对 169.254.x.x 返回警告而非错误

3.10 netplan 渲染模块

建议名称：network/netplan

职责：

1. 根据目标接口和参数生成 netplan 内容
2. 保存 netplan 备份
3. 写入新的 netplan 文件
4. 提供回滚需要的备份信息

首版建议：

1. 优先处理新机器初始化场景
2. 以目标真实接口配置成功为主目标
3. 不优先支持复杂旧 netplan 合并与跨文件重构
4. 首版默认修改系统现有 netplan 文件
5. 修改前先做完整备份，再对目标接口对应内容进行修改

边界：

1. 只负责文件层处理
2. 不负责执行 netplan apply

3.11 应用执行模块

建议名称：network/apply

职责：

1. 调用 netplan apply
2. 检查命令执行结果
3. 记录执行日志

边界：

1. 只负责执行和结果返回
2. 不负责配置渲染与业务校验

3.12 验证模块

建议名称：network/verify

职责：

1. 验证目标接口地址是否生效
2. 可选验证网关连通性
3. 输出验证成功或失败结果

说明：

1. 首版只需做最小验证
2. 可先只验证接口地址是否已成功生效
3. 网关连通性可以作为增强项或警告项

3.13 回滚模块

建议名称：network/rollback

职责：

1. 恢复最近一次稳定 netplan 配置
2. 重新执行 netplan apply
3. 记录回滚结果

首版建议：

1. 回滚目标以当前被修改的 netplan 文件为主
2. 不扩展到复杂多文件恢复编排

要求：

1. 必须可被任务执行流程调用
2. 也必须可被手动回滚接口调用

3.14 任务管理模块

建议名称：tasks

职责：

1. 创建配置任务
2. 维护任务状态
3. 记录执行步骤
4. 为客户端轮询提供状态数据

建议状态：

1. pending
2. running
3. success
4. failed
5. rolled_back

建议步骤：

1. validating
2. writing_netplan
3. applying
4. verifying
5. rolling_back
6. completed

当前实现补充：

1. POST /api/network/apply 返回的是任务创建结果，而不是完整任务详情
2. 当前返回数据只包含 interface 和 task_id
3. 任务详细状态需要再通过 GET /api/tasks/{task_id} 获取

3.15 系统控制模块

建议名称：systemctl 或 systemops

职责：

1. 执行重启
2. 执行关机
3. 返回执行接受状态

4. 请求处理链路

4.1 GET /api/network/interfaces

建议链路：

1. auth
2. network/interfaces
3. httpserver 统一组装响应

4.2 POST /api/network/validate

建议链路：

1. auth
2. network/interfaces 校验接口是否存在
3. network/validator
4. httpserver 返回结果

4.3 POST /api/network/apply

建议链路：

1. auth
2. tasks 创建任务
3. network/validator
4. network/netplan
5. network/apply
6. network/verify
7. 失败时进入 network/rollback
8. tasks 更新状态

5. 建议目录结构

建议仅作参考：

server/
  cmd/
    nettool-server/
  internal/
    config/
    logger/
    auth/
    deviceinfo/
    discovery/
    httpserver/
    tasks/
    systemops/
    network/
      interfaces/
      configreader/
      validator/
      netplan/
      apply/
      verify/
      rollback/

6. 建议实现顺序

第一阶段

先打通最小链路：

1. config
2. logger
3. deviceinfo
4. network/interfaces
5. discovery
6. httpserver
7. auth
8. GET /api/health
9. GET /api/device/info
10. GET /api/network/interfaces

第二阶段

补齐读取与校验：

1. network/configreader
2. network/validator
3. GET /api/network/config
4. POST /api/network/validate

第三阶段

补齐配置与回滚主链路：

1. tasks
2. network/netplan
3. network/apply
4. network/verify
5. network/rollback
6. POST /api/network/apply
7. POST /api/network/rollback
8. GET /api/tasks/{task_id}

第四阶段

补齐系统操作：

1. systemops
2. POST /api/system/reboot
3. POST /api/system/shutdown

7. MVP 阶段建议收口

为了尽快落地，Server 首版建议遵循以下约束：

1. 只支持 Ubuntu 24
2. 只支持 netplan
3. 只处理 IPv4
4. 只处理单目标接口配置
5. 只提供固定密码鉴权
6. 只做最小必要校验与回滚

8. 当前最重要的实现判断

如果现在进入编码，我建议先做下面 3 件事：

1. 先验证 Ubuntu 24 上 LAN2 的固定 169.254.100.2/16 与 DHCP 共存是否稳定
2. 先实现 network/interfaces，把真实接口识别做稳
3. 先完成只读接口，再进入 netplan 写入和回滚