NetworkTool/docs/07-Agent首阶段实现清单.md

Agent 首阶段实现清单

1. 目标

定义 Linux Agent 从零开始时，第一阶段应该优先完成的模块、接口、数据结构和验证顺序。

第一阶段目标不是立即改 IP，而是先把“发现 + 连接 + 读取状态”整条只读链路打通。

2. 第一阶段范围

第一阶段只实现以下能力：

1. Agent 启动
2. 读取固定运行配置
3. 启动前为管理接口挂载维护地址
4. UDP 广播发现
5. HTTP 服务启动
6. 固定密码鉴权
7. 设备信息读取
8. 真实接口枚举与识别
9. 返回接口列表

第一阶段暂不实现：

1. netplan 写入
2. 配置校验
3. 配置应用
4. 自动回滚
5. 重启与关机

3. 第一阶段必须完成的 HTTP 接口

3.1 GET /api/health

用途：

1. 客户端探活
2. 判断 Agent 是否运行

最低返回：

1. 运行状态
2. Agent 版本

3.2 GET /api/device/info

用途：

1. 展示设备基础信息
2. 确认设备身份

最低返回：

1. 设备 ID
2. 主机名
3. Ubuntu 版本
4. Agent 版本
5. 运行时长

3.3 GET /api/network/interfaces

用途：

1. 返回真实接口列表
2. 返回当前管理接口
3. 返回建议目标接口
4. 为设备页提供数据

最低返回：

1. management_interface
2. suggested_target_interface
3. requires_target_selection
4. interfaces[]

4. 第一阶段必须完成的 UDP 能力

4.1 UDP 广播监听

要求：

1. 监听固定发现端口
2. 能接收 Windows 广播报文
3. 能正确解析 discover 请求

4.2 UDP 发现响应

要求：

1. 回传 request_id
2. 返回设备基础信息
3. 返回维护地址 169.254.100.2
4. 返回 auth_required=true

5. 第一阶段建议模块顺序

5.1 config

先完成一个最小配置模块，至少输出：

1. HTTP 端口
2. UDP 端口
3. 固定维护地址
4. 固定密码
5. Agent 版本
6. HTTP 默认端口 48888
7. 支持 --ip 与 --port 启动参数
8. 支持 --password 启动参数，默认密码为 Dt123$

建议示例：

./quickip-agent --ip 169.254.100.2 --port 48888 --password 'Dt123$'

5.2 logger

提供统一日志入口。

最低要求：

1. 信息日志
2. 错误日志
3. 敏感头过滤

5.3 deviceinfo

负责提供：

1. 主机名
2. OS 版本
3. 设备 ID
4. 运行时长

5.4 network/interfaces

这是第一阶段最关键模块之一。

最低要求：

1. 枚举物理有线接口
2. 过滤虚拟接口
3. 返回接口名、MAC、链路状态、IPv4
4. 判断当前管理接口
5. 判断建议目标接口
6. 在维护地址不存在时，为管理接口执行运行时注入

5.5 auth

最低要求：

1. 检查来源 IP 是否在 169.254.0.0/16
2. 校验 X-Admin-Password
3. 返回统一失败结果

5.6 httpserver

最低要求：

1. 路由注册
2. 统一 JSON 输出
3. 接入 auth

5.7 discovery

最低要求：

1. 启动 UDP 监听
2. 收包后读取 deviceinfo
3. 收包后读取管理地址
4. 返回发现响应

6. 第一阶段建议数据结构

6.1 AgentConfig

建议字段：

type AgentConfig struct {
    HttpPort          int
    UdpPort           int
    MaintenanceIP     string
    MaintenanceCIDR   string
    AdminPassword     string
    Version           string
}

6.2 DeviceInfo

建议字段：

type DeviceInfo struct {
    DeviceID      string
    Hostname      string
    OSVersion     string
    AgentVersion  string
    UptimeSeconds int64
}

6.3 NetworkInterface

建议字段：

type NetworkInterface struct {
    Name                 string
    SystemName           string
    Role                 string
    LinkUp               bool
    IsManagement         bool
    IsSuggestedTarget    bool
    MAC                  string
    IPv4                 []IPv4Address
    Gateway              string
    DNS                  []string
}

6.4 IPv4Address

建议字段：

type IPv4Address struct {
    Address string
    Prefix  int
    Source  string
}

6.5 InterfacesResponse

建议字段：

type InterfacesResponse struct {
    ManagementInterface     string
    SuggestedTargetInterface string
    RequiresTargetSelection bool
    Interfaces              []NetworkInterface
}

7. 第一阶段建议目录落地

建议优先创建：

agent/
  cmd/
    quickip-agent/
  internal/
    config/
    logger/
    auth/
    deviceinfo/
    discovery/
    httpserver/
    network/
      interfaces/

8. 第一阶段联调前置条件

在 Windows 客户端开始联调前，Agent 至少应满足：

1. 能在 Ubuntu 24 上正常启动
2. 能监听 HTTP 端口
3. 能响应 UDP 发现
4. 能返回设备信息
5. 能返回真实接口列表
6. 能识别当前管理接口

9. 第一阶段验证顺序

建议按下面顺序验证：

1. 本机直接访问 GET /api/health
2. 本机直接访问 GET /api/device/info
3. 本机直接访问 GET /api/network/interfaces
4. Windows 端发送 UDP 发现
5. Windows 端通过密码访问上述 3 个接口

10. 第一阶段完成标准

满足以下条件即可认为第一阶段完成：

1. Windows 能发现设备
2. Windows 能通过固定密码连接设备
3. Windows 能看到设备信息
4. Windows 能看到真实接口列表
5. Windows 能自动识别当前管理接口
6. 当接口数为 2 时，Windows 能拿到建议目标接口

11. 第二阶段入口

第一阶段完成后，再进入第二阶段：

1. GET /api/network/config
2. POST /api/network/validate
3. POST /api/network/apply
4. POST /api/network/rollback
5. GET /api/tasks/{task_id}

也就是先把“只读链路”做稳，再开始改配置。