# 通信与 HTTP API ## 1. 发现与控制协议 ### 1.1 UDP 发现 用途： 1. Windows 客户端在指定网卡上广播发现设备 2. Linux Server 响应自身信息 建议端口：`50000` #### 发现请求 ```json { "protocol_version": 1, "message_type": "discover", "request_id": "6f7d2f6a-1111-2222-3333-444455556666", "client_name": "WIN-PC-01" } ``` #### 发现响应 ```json { "protocol_version": 1, "message_type": "discover_response", "request_id": "6f7d2f6a-1111-2222-3333-444455556666", "device_id": "SN202605070001", "hostname": "ubuntu-server-01", "server_version": "1.0.0", "lan2_ip": "169.254.100.2", "auth_required": true } ``` ### 1.2 HTTP 控制 Base URL： `http://169.254.100.2:48888` 启动参数： 1. `--ip`：指定维护地址，默认 `169.254.100.2` 2. `--port`：指定 HTTP 端口，默认 `48888` 3. `--password`：指定管理密码，默认 `hvAC2026#%` 请求头： ```http Content-Type: application/json X-Admin-Password: hvAC2026#% ``` 当前实现说明： 1. 默认管理密码为 `hvAC2026#%` 2. 也可通过 `--password` 启动参数覆盖 ## 2. 通用约定 ### 2.1 通用响应格式 ```json { "code": 0, "message": "成功", "data": {} } ``` ### 2.2 通用错误码 1. `0`：成功 2. `1001`：缺少密码 3. `1002`：密码错误 5. `2001`：参数错误 6. `2002`：资源不存在 7. `3001`：配置校验失败 8. `3002`：配置应用失败 9. `3003`：配置失败，已回滚 10. `3004`：回滚失败 11. `4001`：系统执行失败 ## 3. HTTP API ### 3.1 健康检查 `GET /api/health` 响应： ```json { "code": 0, "message": "成功", "data": { "status": "运行中", "server_version": "1.0.0" } } ``` ### 3.2 获取设备信息 `GET /api/device/info` 响应： ```json { "code": 0, "message": "成功", "data": { "device_id": "SN202605070001", "hostname": "ubuntu-server-01", "os_version": "Ubuntu 24.04", "server_version": "1.0.0", "uptime_seconds": 86400 } } ``` ### 3.3 获取网络接口列表 `GET /api/network/interfaces` 响应： ```json { "code": 0, "message": "成功", "data": { "management_interface": "enp2s0", "suggested_target_interface": "enp1s0", "requires_target_selection": false, "interfaces": [ { "name": "LAN1", "system_name": "enp1s0", "role": "business", "link_up": true, "is_management_interface": false, "is_suggested_target": true, "mac": "00:11:22:33:44:55", "ipv4": [ { "address": "192.168.10.20", "prefix": 24, "source": "static" } ], "gateway": "", "dns": [] }, { "name": "LAN2", "system_name": "enp2s0", "role": "control", "link_up": true, "is_management_interface": true, "is_suggested_target": false, "mac": "00:11:22:33:44:66", "ipv4": [ { "address": "169.254.100.2", "prefix": 16, "source": "static" }, { "address": "192.168.8.23", "prefix": 24, "source": "dhcp" } ], "gateway": "192.168.8.1", "dns": ["192.168.8.1"] } ] } } ``` 说明： 1. `management_interface` 为当前管理连接所在真实接口名 2. `suggested_target_interface` 为当前建议操作的真实接口名 3. `requires_target_selection` 为 `true` 时，客户端应要求用户选择目标接口 4. `name` 为逻辑展示标识，实际配置应使用 `system_name` ### 3.4 获取全部接口当前配置 `GET /api/network/configs` 响应： ```json { "code": 0, "message": "成功", "data": { "configs": [ { "interface": "enp1s0", "dhcp4": false, "addresses": [ { "ip": "192.168.10.20", "prefix": 24 } ], "routes": [], "dns": [] } ], "errors": [] } } ``` 部分失败响应： ```json { "code": 0, "message": "部分接口配置读取失败", "data": { "configs": [], "errors": [ { "interface": "enp1s0", "message": "读取 netplan 配置失败。" } ] } } ``` 说明：客户端应以 `configs[].interface` 匹配接口列表中的 `system_name`。`errors` 仅表示对应接口配置读取失败，不表示 HTTP 请求失败。 ### 3.5 校验指定接口配置 `POST /api/network/validate` 请求： ```json { "interface": "enp1s0", "dhcp4": false, "addresses": [ { "ip": "192.168.10.20", "prefix": 24 }, { "ip": "192.168.20.20", "prefix": 24 } ], "routes": [ { "to": "default", "via": "192.168.10.1" }, { "to": "10.10.0.0/16", "via": "192.168.20.1" } ], "dns": [] } ``` 正常响应： ```json { "code": 0, "message": "校验通过", "data": { "valid": true, "warnings": [] } } ``` 带警告响应： ```json { "code": 0, "message": "校验通过", "data": { "valid": true, "warnings": [ "目标接口使用的是链路本地地址，通常仅适合同链路通信。" ] } } ``` 失败响应： ```json { "code": 3001, "message": "配置校验失败", "data": { "valid": false, "errors": [ "网关与目标接口 IP 不在同一子网。" ] } } ``` 校验规则： 1. `dhcp4=false` 时，`addresses` 至少需要 1 项 2. `addresses[].ip` 必填 3. `addresses[].prefix` 必填 4. `dns` 选填 5. `interface` 必填，必须是有效的真实接口名 6. `routes[].to` 必须为 `default` 或 IPv4 CIDR 7. `routes[].via` 必须为 IPv4 地址，且必须与任一 `addresses` 在同一子网 8. 若任一 `addresses[].ip` 为 `169.254.x.x`，返回中文警告，不直接报错 9. 单个接口最多只能配置 1 条 `default` 路由 10. 批量配置中最多只能有 1 个网口配置默认网关；多个网口同时配置默认网关时校验失败 ### 3.6 应用指定接口配置 `POST /api/network/apply` 请求： ```json { "interface": "enp1s0", "dhcp4": false, "addresses": [ { "ip": "192.168.10.20", "prefix": 24 } ], "routes": [ { "to": "default", "via": "192.168.10.1" } ], "dns": [] } ``` 响应： ```json { "code": 0, "message": "配置任务已提交", "data": { "interface": "enp1s0", "task_id": "task-20260507-0001" } } ``` 说明： 1. 当前 `apply` 返回的是“任务创建结果” 2. 返回数据只包含 `interface` 和 `task_id` 3. 任务详细状态需再调用 `GET /api/tasks/{task_id}` 获取 执行流程： 1. 校验参数 2. 备份当前稳定配置 3. 写入新的 `netplan` 4. 执行 `netplan apply` 5. 验证配置是否生效 6. 成功则保存 7. 失败则回滚 ### 3.7 手动回滚指定接口配置 `POST /api/network/rollback` 请求： ```json { "interface": "enp1s0" } ``` 响应： ```json { "code": 0, "message": "回滚成功", "data": { "interface": "enp1s0", "rolled_back": true } } ``` ### 3.8 查询任务状态 `GET /api/tasks/{task_id}` 进行中响应： ```json { "code": 0, "message": "任务执行中", "data": { "task_id": "task-20260507-0001", "status": "running", "step": "applying", "detail": "正在应用 netplan 配置。", "rollback": false } } ``` 成功响应： ```json { "code": 0, "message": "配置成功", "data": { "task_id": "task-20260507-0001", "status": "success", "step": "completed", "detail": "目标接口配置已成功应用。", "rollback": false } } ``` 失败并回滚响应： ```json { "code": 3003, "message": "配置失败，已自动回滚", "data": { "task_id": "task-20260507-0001", "status": "rolled_back", "step": "rolling_back", "detail": "网关不可达，已恢复到上一次稳定配置。", "rollback": true } } ``` 状态建议： 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` ### 3.9 重启系统 `POST /api/system/reboot` 请求： ```json {} ``` 响应： ```json { "code": 0, "message": "重启命令已接受", "data": { "accepted": true } } ``` ### 3.10 关机系统 `POST /api/system/shutdown` 请求： ```json {} ``` 响应： ```json { "code": 0, "message": "关机命令已接受", "data": { "accepted": true } } ``` ## 4. Server 请求处理顺序 每个 HTTP 请求统一按以下顺序处理： 1. 检查请求是否发送到 `169.254.100.2` 2. 读取 `X-Admin-Password` 3. 校验密码是否正确 4. 通过后进入业务逻辑 5. 返回统一 JSON 响应 当前实现补充： 1. 已增加 HTTP 访问日志 2. 日志会记录方法、路径、查询参数、状态码和耗时