固件发布 API

公开端点

以下端点无需认证，供设备固件更新客户端使用。

GET /api/v1/firmware/slave/manifest.json

获取下位机固件发布清单。

响应

{
  "release": "260714000-1.26.7.r1",
  "image_version": 260714000,
  "display_version": "1.26.7",
  "system": {
    "offset": 0,
    "length": 1048576,
    "sha256": "abc123def456...",
    "crc32": "A1B2C3D4"
  },
  "product": {
    "magic": "JANPNP",
    "hw_version": 1,
    "fw_version": 260714000,
    "git_sha": "abc1234",
    "timestamp": "2026-07-14T00:00:00Z"
  }
}

GET /api/v1/firmware/slave/system.bin

下载下位机签名固件镜像。返回二进制流。

管理端点

需要管理员权限。

GET /api/v1/admin/firmware/slave/releases

获取所有已发布的固件版本列表。

POST /api/v1/admin/firmware/slave/releases

发布新的固件版本。

请求

上传固件镜像文件和清单文件（multipart/form-data）。

响应

{
  "success": true,
  "release_id": "260714000-1.26.7.r1",
  "image_version": 260714000
}

POST /api/v1/admin/firmware/slave/releases/{release_id}/activate

激活指定固件版本，设备下次检查更新时将获取该版本。

响应

{
  "success": true,
  "release_id": "260714000-1.26.7.r1",
  "activated": true
}

固件发布流程

flowchart LR
    A[构建签名镜像] --> B[上传镜像 + 清单]
    B --> C[服务端验证<br/>SHA-256 · CRC32 · 镜像头]
    C --> D{验证通过?}
    D -->|是| E[发布版本]
    D -->|否| F[拒绝]
    E --> G[激活版本]
    G --> H[设备下载更新]

安全机制

固件镜像使用 ECDSA P-256 + SHA-256 签名链保护
上传后服务端验证镜像头结构、摘要和 CRC
版本发布和激活全程记录审计日志到 audit.jsonl
发布 ID 格式校验防止路径遍历攻击