通信与 HTTP API

1. 发现与控制协议

1.1 UDP 发现

用途：

Windows 客户端在指定网卡上广播发现设备
Linux Server 响应自身信息

建议端口：50000

发现请求

{
  "protocol_version": 1,
  "message_type": "discover",
  "request_id": "6f7d2f6a-1111-2222-3333-444455556666",
  "client_name": "WIN-PC-01"
}

发现响应

{
  "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

启动参数：

--ip：指定维护地址，默认 169.254.100.2
--port：指定 HTTP 端口，默认 48888
--password：指定管理密码，默认 Dieteng2026

请求头：

Content-Type: application/json
X-Admin-Password: Dieteng2026

当前实现说明：

默认管理密码为 Dieteng2026
也可通过 --password 启动参数覆盖

2. 通用约定

2.1 通用响应格式

{
  "code": 0,
  "message": "成功",
  "data": {}
}

2.2 通用错误码

0：成功
1001：缺少密码
1002：密码错误
2001：参数错误
2002：资源不存在
3001：配置校验失败
3002：配置应用失败
3003：配置失败，已回滚
3004：回滚失败
4001：系统执行失败

3. HTTP API

3.1 健康检查

GET /api/health

响应：

{
  "code": 0,
  "message": "成功",
  "data": {
    "status": "运行中",
    "server_version": "1.0.0"
  }
}

3.2 获取设备信息

GET /api/device/info

响应：

{
  "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

响应：

{
  "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"]
      }
    ]
  }
}

说明：

management_interface 为当前管理连接所在真实接口名
suggested_target_interface 为当前建议操作的真实接口名
requires_target_selection 为 true 时，客户端应要求用户选择目标接口
name 为逻辑展示标识，实际配置应使用 system_name

3.4 获取全部接口当前配置

GET /api/network/configs

响应：

{
  "code": 0,
  "message": "成功",
  "data": {
    "configs": [
      {
        "interface": "enp1s0",
        "dhcp4": false,
        "addresses": [
          {
            "ip": "192.168.10.20",
            "prefix": 24
          }
        ],
        "routes": [],
        "dns": []
      }
    ],
    "errors": []
  }
}

部分失败响应：

{
  "code": 0,
  "message": "部分接口配置读取失败",
  "data": {
    "configs": [],
    "errors": [
      {
        "interface": "enp1s0",
        "message": "读取 netplan 配置失败。"
      }
    ]
  }
}

说明：客户端应以 configs[].interface 匹配接口列表中的 system_name。errors 仅表示对应接口配置读取失败，不表示 HTTP 请求失败。

3.5 校验指定接口配置

POST /api/network/validate

请求：

{
  "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": []
}

正常响应：

{
  "code": 0,
  "message": "校验通过",
  "data": {
    "valid": true,
    "warnings": []
  }
}

带警告响应：

{
  "code": 0,
  "message": "校验通过",
  "data": {
    "valid": true,
    "warnings": [
      "目标接口使用的是链路本地地址，通常仅适合同链路通信。"
    ]
  }
}

失败响应：

{
  "code": 3001,
  "message": "配置校验失败",
  "data": {
    "valid": false,
    "errors": [
      "网关与目标接口 IP 不在同一子网。"
    ]
  }
}

校验规则：

dhcp4=false 时，addresses 至少需要 1 项
addresses[].ip 必填
addresses[].prefix 必填
dns 选填
interface 必填，必须是有效的真实接口名
routes[].to 必须为 default 或 IPv4 CIDR
routes[].via 必须为 IPv4 地址，且必须与任一 addresses 在同一子网
若任一 addresses[].ip 为 169.254.x.x，返回中文警告，不直接报错
单个接口最多只能配置 1 条 default 路由
批量配置中最多只能有 1 个网口配置默认网关；多个网口同时配置默认网关时校验失败

3.6 应用指定接口配置

POST /api/network/apply

请求：

{
  "interface": "enp1s0",
  "dhcp4": false,
  "addresses": [
    {
      "ip": "192.168.10.20",
      "prefix": 24
    }
  ],
  "routes": [
    {
      "to": "default",
      "via": "192.168.10.1"
    }
  ],
  "dns": []
}

响应：

{
  "code": 0,
  "message": "配置任务已提交",
  "data": {
    "interface": "enp1s0",
    "task_id": "task-20260507-0001"
  }
}

说明：

当前 apply 返回的是“任务创建结果”
返回数据只包含 interface 和 task_id
任务详细状态需再调用 GET /api/tasks/{task_id} 获取

执行流程：

校验参数
备份当前稳定配置
写入新的 netplan
执行 netplan apply
验证配置是否生效
成功则保存
失败则回滚

3.7 手动回滚指定接口配置

POST /api/network/rollback

请求：

{
  "interface": "enp1s0"
}

响应：

{
  "code": 0,
  "message": "回滚成功",
  "data": {
    "interface": "enp1s0",
    "rolled_back": true
  }
}

3.8 查询任务状态

GET /api/tasks/{task_id}

进行中响应：

{
  "code": 0,
  "message": "任务执行中",
  "data": {
    "task_id": "task-20260507-0001",
    "status": "running",
    "step": "applying",
    "detail": "正在应用 netplan 配置。",
    "rollback": false
  }
}

成功响应：

{
  "code": 0,
  "message": "配置成功",
  "data": {
    "task_id": "task-20260507-0001",
    "status": "success",
    "step": "completed",
    "detail": "目标接口配置已成功应用。",
    "rollback": false
  }
}

失败并回滚响应：

{
  "code": 3003,
  "message": "配置失败，已自动回滚",
  "data": {
    "task_id": "task-20260507-0001",
    "status": "rolled_back",
    "step": "rolling_back",
    "detail": "网关不可达，已恢复到上一次稳定配置。",
    "rollback": true
  }
}

状态建议：

pending
running
success
failed
rolled_back

步骤建议：

validating
writing_netplan
applying
verifying
rolling_back
completed

3.9 重启系统

POST /api/system/reboot

请求：

{}

响应：

{
  "code": 0,
  "message": "重启命令已接受",
  "data": {
    "accepted": true
  }
}

3.10 关机系统

POST /api/system/shutdown

请求：

{}

响应：

{
  "code": 0,
  "message": "关机命令已接受",
  "data": {
    "accepted": true
  }
}

4. Server 请求处理顺序

每个 HTTP 请求统一按以下顺序处理：

检查请求是否发送到 169.254.100.2
读取 X-Admin-Password
校验密码是否正确
通过后进入业务逻辑
返回统一 JSON 响应

当前实现补充：

已增加 HTTP 访问日志
日志会记录方法、路径、查询参数、状态码和耗时

03-通信与HTTP_API.md 8.8 KB Historia Raaka