提交api调用相关信息

2026-06-18 18:00:17 +08:00
parent f6ae31c319
commit 2a425196e6
8 changed files with 2762 additions and 0 deletions
--- a/hawkbit-compose/CURL-API.md
+++ b/hawkbit-compose/CURL-API.md
@@ -0,0 +1,746 @@
+# Hawkbit DDI API — curl 完整操作手册
+
+基于实际验证的 Hawkbit DDI API v1 交互流程，所有命令均已跑通。
+
+## 环境信息
+
+```
+Hawkbit Server:  http://192.168.142.128:9090
+Tenant:          DEFAULT
+Auth:            GatewayToken my-gateway-key    (DDI 接口)
+                 admin:admin                    (Management 接口)
+Controller ID:   test-curl-001
+DistributionSet: id=1 (r3576test:V1.0.0.0)
+```
+
+## 目录
+
+1. [认证配置](#1-认证配置)
+2. [自动注册与轮询](#2-自动注册与轮询)
+3. [分配 Distribution Set](#3-分配-distribution-set)
+4. [拉取部署详情](#4-拉取部署详情)
+5. [上报设备属性](#5-上报设备属性)
+6. [下载 artifact](#6-下载-artifact)
+7. [SHA256 文件校验](#7-sha256-文件校验)
+8. [上报执行状态](#8-上报执行状态)
+9. [取消任务](#9-取消任务)
+10. [确认任务流程](#10-确认任务流程)
+11. [查询验证](#11-查询验证)
+12. [完整流程速查](#12-完整流程速查)
+
+---
+
+## 1. 认证配置
+
+### 1.1 开启 GatewayToken 认证（服务端，一次性）
+
+```bash
+# 设置 token key
+curl -u admin:admin -X PUT \
+  -H "Content-Type: application/json" \
+  "http://192.168.142.128:9090/rest/v1/system/configs/authentication.gatewaytoken.key" \
+  -d '{"value": "my-gateway-key"}'
+
+# 启用 gateway token 认证
+curl -u admin:admin -X PUT \
+  -H "Content-Type: application/json" \
+  "http://192.168.142.128:9090/rest/v1/system/configs/authentication.gatewaytoken.enabled" \
+  -d '{"value": true}'
+```
+
+### 1.2 开启 TargetToken 认证（服务端，一次性）
+
+```bash
+curl -u admin:admin -X PUT \
+  -H "Content-Type: application/json" \
+  "http://192.168.142.128:9090/rest/v1/system/configs/authentication.targettoken.enabled" \
+  -d '{"value": true}'
+```
+
+### 1.3 查看当前所有认证配置
+
+```bash
+curl -s -u admin:admin \
+  "http://192.168.142.128:9090/rest/v1/system/configs" \
+  | python3 -m json.tool | grep -E "authentication\.(gateway|target)"
+```
+
+### 1.4 认证方式对比
+
+```
+DDI 请求头:
+  GatewayToken → Authorization: GatewayToken my-gateway-key
+  TargetToken  → Authorization: TargetToken <设备securityToken>
+
+Management API 请求头:
+  Basic Auth    → -u admin:admin
+```
+
+---
+
+## 2. 自动注册与轮询
+
+### 2.1 首次轮询（自动注册）
+
+```
+GET /{tenant}/controller/v1/{controllerId}
+```
+
+设备 SN 在 Hawkbit 中不存在时，服务端自动调用 `findOrRegisterTargetIfItDoesNotExist()` 创建 target。
+
+```bash
+curl -v \
+  -H "Authorization: GatewayToken my-gateway-key" \
+  -H "Accept: application/json" \
+  "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001"
+```
+
+**响应（无待处理 action）：**
+
+```json
+{
+  "config": {"polling": {"sleep": "00:05:00"}},
+  "_links": {
+    "configData": {
+      "href": "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001/configData"
+    }
+  }
+}
+```
+
+**响应（有待处理 action）：**
+
+```json
+{
+  "config": {"polling": {"sleep": "00:05:00"}},
+  "_links": {
+    "deploymentBase": {
+      "href": "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001/deploymentBase/15?c=424529173"
+    },
+    "configData": {
+      "href": "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001/configData"
+    }
+  }
+}
+```
+
+### 2.2 响应中的 HAL 链接含义
+
+| 链接 rel | 含义 | 下一步动作 |
+|----------|------|----------|
+| `deploymentBase` | 有待执行的部署任务 | 拉取部署详情 → 下载 → 安装 |
+| `cancelAction` | 有取消指令 | 确认取消 |
+| `confirmationBase` | 有需要确认的任务 | 发送确认 |
+| `configData` | 服务端要求上报属性 | PUT 属性数据 |
+| `installedBase` | 有历史安装记录 | 可查询 |
+
+---
+
+## 3. 分配 Distribution Set
+
+```
+POST /rest/v1/distributionsets/{distributionSetId}/assignedTargets
+```
+
+> ⚠️ 这是 Management API，用 `-u admin:admin` 认证。
+
+```bash
+curl -u admin:admin -X POST \
+  -H "Content-Type: application/json" \
+  "http://192.168.142.128:9090/rest/v1/distributionsets/1/assignedTargets" \
+  -d '[{"id": "test-curl-001"}]'
+```
+
+**可选参数（完整请求体）**：
+
+```json
+{
+  "id": "test-curl-001",
+  "type": "forced",
+  "forcetime": 1682408575278,
+  "weight": 1000,
+  "maintenanceWindow": {
+    "schedule": "00:00-04:00",
+    "duration": "02:00:00",
+    "timezone": "+08:00"
+  },
+  "confirmationRequired": false
+}
+```
+
+**响应**：`200 OK`，返回 `MgmtTargetAssignmentResponseBody`。
+
+分配成功后，设备下次轮询就会拿到 `deploymentBase` 链接。
+
+---
+
+## 4. 拉取部署详情
+
+```
+GET /{tenant}/controller/v1/{controllerId}/deploymentBase/{actionId}
+```
+
+```bash
+curl -H "Authorization: GatewayToken my-gateway-key" \
+  -H "Accept: application/json" \
+  "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001/deploymentBase/15"
+```
+
+**响应**：
+
+```json
+{
+  "id": "15",
+  "deployment": {
+    "download": "forced",
+    "update": "forced",
+    "chunks": [
+      {
+        "part": "os",
+        "version": "V1.0.0.0",
+        "name": "r3576-OS-android",
+        "artifacts": [
+          {
+            "filename": "update.zip",
+            "hashes": {
+              "sha1": "223377ea691bd7fc47865cccfd802771ff1b3fca",
+              "md5": "28a17f5fb87d637756c0cc5d555d69b7",
+              "sha256": "438b8f9e2af3a3334dc72272d167e0deda8c6e65bb1585202151b3cb866bb530"
+            },
+            "size": 195411,
+            "_links": {
+              "download-http": {
+                "href": "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001/softwaremodules/1/artifacts/update.zip"
+              },
+              "md5sum-http": {
+                "href": "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001/softwaremodules/1/artifacts/update.zip.MD5SUM"
+              }
+            }
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 字段说明
+
+| 字段 | 说明 |
+|------|------|
+| `id` | action ID，后续反馈操作的关键参数 |
+| `deployment.download` | `forced`=强制下载 / `attempt`=尝<><E5B09D><EFBFBD>下载 / `skip`=跳过 |
+| `deployment.update` | `forced`=强制安装 / `attempt`=尝试安装 / `skip`=跳过 |
+| `chunks[].part` | 软件模块类型（os / app / …） |
+| `chunks[].version` | 软件版本号 |
+| `chunks[].artifacts[].filename` | 要下载的文件名 |
+| `chunks[].artifacts[].hashes` | SHA1 / MD5 / SHA256 校验值 |
+| `chunks[].artifacts[].size` | 文件大小（bytes） |
+| `_links.download-http.href` | **下载地址** |
+
+### download / update handlingType 组合
+
+| download | update | 含义 |
+|----------|--------|------|
+| `forced` | `forced` | 立即下载并安装 |
+| `attempt` | `attempt` | 设备自行决定是否下载/安装 |
+| `forced` | `skip` | 只下载不安装（download only） |
+| `skip` | `skip` | maintenance window 未到，等待下次轮询 |
+
+---
+
+## 5. 上报设备属性
+
+```
+PUT /{tenant}/controller/v1/{controllerId}/configData
+```
+
+> ⚠️ 必须先轮询一次让 target 自动注册，再上报属性，否则 404。
+
+```bash
+curl -H "Authorization: GatewayToken my-gateway-key" \
+  -H "Content-Type: application/json" -X PUT \
+  "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001/configData" \
+  -d '{
+    "mode": "merge",
+    "data": {
+      "osType": "linux",
+      "platform": "x86_64",
+      "kernel": "6.17.0-35-generic",
+      "hostname": "test-curl-001",
+      "hwRevision": "VMware Virtual Platform",
+      "manufacturer": "VMware, Inc.",
+      "swVersion": "V1.0.0.0"
+    }
+  }'
+```
+
+### mode 说明
+
+| mode | 行为 |
+|------|------|
+| `merge` | 合并：只更新传入的 key，保留已有属性（推荐） |
+| `replace` | 替换：完全覆盖已有属性 |
+| `remove` | 删除：移除传入的 key |
+
+**响应**：`200 OK`（空 body）
+
+### 查询设备属性
+
+```bash
+curl -u admin:admin \
+  "http://192.168.142.128:9090/rest/v1/targets/test-curl-001/attributes"
+```
+
+---
+
+## 6. 下载 artifact
+
+```
+GET /{tenant}/controller/v1/{controllerId}/softwaremodules/{softwareModuleId}/artifacts/{fileName}
+```
+
+### 6.1 完整下载
+
+```bash
+curl -H "Authorization: GatewayToken my-gateway-key" \
+  -o /tmp/test-update.zip \
+  "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001/softwaremodules/1/artifacts/update.zip"
+```
+
+**响应**：`200 OK`，二进制流。
+
+### 6.2 断点续传（Range 请求）
+
+```bash
+# 续传：从 byte 1048576 开始
+curl -H "Authorization: GatewayToken my-gateway-key" \
+  -H "Range: bytes=1048576-" \
+  -o /tmp/test-update.zip.part --append \
+  "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001/softwaremodules/1/artifacts/update.zip"
+```
+
+**响应**：`206 Partial Content`，`Content-Range: bytes 1048576-195410/195411`。
+
+### 6.3 条件请求（If-Match）
+
+```bash
+curl -H "Authorization: GatewayToken my-gateway-key" \
+  -H "If-Match: 223377ea691bd7fc47865cccfd802771ff1b3fca" \
+  -o /tmp/test-update.zip \
+  "http://..."
+# SHA1 不匹配 → 412 Precondition Failed
+```
+
+### 6.4 下载 MD5SUM
+
+```bash
+curl -H "Authorization: GatewayToken my-gateway-key" \
+  "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001/softwaremodules/1/artifacts/update.zip.MD5SUM"
+```
+
+**响应**：`28a17f5fb87d637756c0cc5d555d69b7  update.zip`
+
+### 6.5 从 HAL 链接提取下载地址
+
+artifact 的 `_links` 中有两个下载链接，优先级：
+
+```
+download        → HTTPS（如果有，首选）
+download-http   → HTTP（回退方案）
+md5sum-http     → MD5 校验文件（HTTP）
+```
+
+---
+
+## 7. SHA256 文件校验
+
+### 7.1 计算本地文件 SHA256
+
+```bash
+sha256sum /tmp/test-update.zip
+```
+
+### 7.2 对比部署详情中的哈希值
+
+```bash
+# 部署详情中的 SHA256:
+# "sha256": "438b8f9e2af3a3334dc72272d167e0deda8c6e65bb1585202151b3cb866bb530"
+
+echo "438b8f9e2af3a3334dc72272d167e0deda8c6e65bb1585202151b3cb866bb530  /tmp/test-update.zip" | sha256sum -c
+# → /tmp/test-update.zip: OK
+```
+
+---
+
+## 8. 上报执行状态
+
+```
+POST /{tenant}/controller/v1/{controllerId}/deploymentBase/{actionId}/feedback
+```
+
+### 8.1 状态上报 JSON 格式
+
+```json
+{
+  "timestamp": 1750000000000,
+  "status": {
+    "execution": "download",
+    "result": {
+      "finished": "none",
+      "progress": {"cnt": 2, "of": 5}
+    },
+    "code": 200,
+    "details": ["Starting download"]
+  }
+}
+```
+
+### 8.2 四步标准流程
+
+```bash
+# 定义变量，方便重复使用
+D="http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001/deploymentBase/15/feedback"
+A="Authorization: GatewayToken my-gateway-key"
+J="Content-Type: application/json"
+
+# ① download — 开始下载
+curl -H "$A" -H "$J" \
+  -d '{"status":{"execution":"download","result":{"finished":"none"},"details":["Starting download"]}}' \
+  "$D"
+
+# ② downloaded — 下载完成
+curl -H "$A" -H "$J" \
+  -d '{"status":{"execution":"downloaded","result":{"finished":"none"},"details":["Downloaded update.zip"]}}' \
+  "$D"
+
+# ③ proceeding — 安装中
+curl -H "$A" -H "$J" \
+  -d '{"status":{"execution":"proceeding","result":{"finished":"none"},"details":["Installing update"]}}' \
+  "$D"
+
+# ④ closed — 最终结果
+# 成功:
+curl -H "$A" -H "$J" \
+  -d '{"status":{"execution":"closed","result":{"finished":"success"},"details":["Installation complete"],"code":200}}' \
+  "$D"
+
+# 失败:
+curl -H "$A" -H "$J" \
+  -d '{"status":{"execution":"closed","result":{"finished":"failure"},"details":["Installation failed"],"code":500}}' \
+  "$D"
+```
+
+### 8.3 execution 枚举值
+
+| execution | Hawkbit Status | 说明 |
+|-----------|---------------|------|
+| `download` | `DOWNLOAD` | 开始下载 |
+| `downloaded` | `DOWNLOADED` | 下载完成 |
+| `proceeding` | `RUNNING` | 安装进行中 |
+| `closed` | `FINISHED` / `ERROR` | 最终状态（配合 result.finished） |
+| `canceled` | `CANCELED` | 已取消 |
+| `rejected` | `WARNING` | 已拒绝 |
+| `scheduled` | `RUNNING` | 已计划 |
+| `resumed` | `RUNNING` | 恢复执行 |
+
+### 8.4 result.finished 枚举值
+
+| finished | 含义 |
+|----------|------|
+| `none` | 尚未完成（中间状态） |
+| `success` | 执行成功 |
+| `failure` | 执行失败 |
+
+### 8.5 带进度的上报
+
+```bash
+# 进度: 第2个/总共5个 artifact
+curl -H "$A" -H "$J" \
+  -d '{"status":{"execution":"proceeding","result":{"finished":"none","progress":{"cnt":2,"of":5}},"details":["Downloading artifact 2/5"]}}' \
+  "$D"
+```
+
+### 8.6 取消反馈（cancelAction feedback）
+
+```bash
+curl -H "$A" -H "$J" \
+  -d '{"status":{"execution":"canceled","result":{"finished":"none"},"details":["Cancel acknowledged"]}}' \
+  "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001/cancelAction/15/feedback"
+```
+
+### 8.7 确认反馈（confirmationBase feedback）
+
+```bash
+curl -H "$A" -H "$J" \
+  -d '{"confirmation":"confirmed","code":200,"details":["Auto-confirmed"]}' \
+  "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001/confirmationBase/15/feedback"
+```
+
+### 8.8 常见错误
+
+| HTTP 状态码 | 原因 | 解决 |
+|------------|------|------|
+| `401` | 认证未通过 | 检查 Authorization header 格式 |
+| `404` | URL 路径错误或 target 不存在 | 确保 `/{tenant}/controller/v1/...` |
+| `405` | feedback URL 带了 `?c=xxx` 参数 | POST 前剥离查询参数 |
+| `410 Gone` | action 已不再活跃 | 已经 closed 或 canceled |
+| `400 Body Not Readable` | JSON 格式错误 | `"final"` 应为 `"finished"`，`"progress":{}` 应为 `null` 或省略 |
+
+---
+
+## 9. 取消任务
+
+### 9.1 服务端发起取消（Management API）
+
+```bash
+curl -u admin:admin -X DELETE \
+  "http://192.168.142.128:9090/rest/v1/targets/test-curl-001/actions/15"
+```
+
+### 9.2 设备端处理取消
+
+```bash
+# ① 轮询拿到 cancelAction
+curl -H "Authorization: GatewayToken my-gateway-key" \
+  "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001"
+# → _links.cancelAction.href
+
+# ② 确认取消
+curl -H "Authorization: GatewayToken my-gateway-key" \
+  -H "Content-Type: application/json" \
+  -d '{"status":{"execution":"canceled","result":{"finished":"none"},"details":["Acknowledged"]}}' \
+  "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001/cancelAction/15/feedback"
+```
+
+---
+
+## 10. 确认任务流程
+
+### 10.1 开启确认流程（服务端）
+
+```bash
+curl -u admin:admin -X PUT \
+  -H "Content-Type: application/json" \
+  "http://192.168.142.128:9090/rest/v1/system/configs/user.confirmation.flow.enabled" \
+  -d '{"value": true}'
+```
+
+### 10.2 分配时要求确认
+
+```bash
+curl -u admin:admin -X POST \
+  -H "Content-Type: application/json" \
+  "http://192.168.142.128:9090/rest/v1/distributionsets/1/assignedTargets" \
+  -d '[{"id":"test-curl-001","confirmationRequired":true}]'
+```
+
+### 10.3 设备端自动确认
+
+```bash
+curl -H "Authorization: GatewayToken my-gateway-key" \
+  -H "Content-Type: application/json" \
+  -d '{"confirmation":"confirmed","code":200,"details":["Auto-confirmed"]}' \
+  "http://192.168.142.128:9090/DEFAULT/controller/v1/test-curl-001/confirmationBase/15/feedback"
+```
+
+---
+
+## 11. 查询验证
+
+### 11.1 查询 target 基本信息
+
+```bash
+curl -u admin:admin \
+  "http://192.168.142.128:9090/rest/v1/targets/test-curl-001"
+```
+
+### 11.2 查询 target 所有 action
+
+```bash
+curl -u admin:admin \
+  "http://192.168.142.128:9090/rest/v1/targets/test-curl-001/actions"
+```
+
+### 11.3 查询指定 action 详情
+
+```bash
+curl -u admin:admin \
+  "http://192.168.142.128:9090/rest/v1/targets/test-curl-001/actions/15"
+```
+
+### 11.4 查询 action 状态历史
+
+```bash
+curl -u admin:admin \
+  "http://192.168.142.128:9090/rest/v1/targets/test-curl-001/actions/15/status"
+```
+
+**响应示例（完成全流程后）**：
+
+```json
+{
+  "content": [
+    {"id":58, "type": "finished",  "messages": ["Installation complete"], ...},
+    {"id":57, "type": "running",   "messages": ["Installing update"],     ...},
+    {"id":56, "type": "downloaded","messages": ["Downloaded update.zip"],  ...},
+    {"id":55, "type": "download",  "messages": ["Starting download"],      ...},
+    {"id":54, "type": "download",  "messages": ["Target downloads ..."],   ...},
+    {"id":53, "type": "retrieved", "messages": ["Target retrieved ..."],   ...},
+    {"id":52, "type": "running",   "messages": ["Assignment initiated ..."]}
+  ],
+  "total": 7, "size": 7
+}
+```
+
+### 11.5 查询 target 属性
+
+```bash
+curl -u admin:admin \
+  "http://192.168.142.128:9090/rest/v1/targets/test-curl-001/attributes"
+```
+
+### 11.6 查询所有 target
+
+```bash
+curl -u admin:admin \
+  "http://192.168.142.128:9090/rest/v1/targets"
+```
+
+### 11.7 查询所有 Distribution Set
+
+```bash
+curl -u admin:admin \
+  "http://192.168.142.128:9090/rest/v1/distributionsets"
+```
+
+---
+
+## 12. 完整流程速查
+
+### 12.1 一次完整的 OTA 生命周期（复制粘贴即用）
+
+```bash
+# ═══ 变量设置 ═══
+HOST="http://192.168.142.128:9090"
+TENANT="DEFAULT"
+CID="test-curl-001"
+AUTH="Authorization: GatewayToken my-gateway-key"
+ADMIN="admin:admin"
+
+# ═══ Step 1: 轮询（自动注册）═══════════════════════════════════════
+curl -s -H "$AUTH" -H "Accept: application/json" \
+  "$HOST/$TENANT/controller/v1/$CID" | python3 -m json.tool
+
+# ═══ Step 2: 分配 Distribution Set（Management API）═════════════════
+curl -u $ADMIN -X POST -H "Content-Type: application/json" \
+  "$HOST/rest/v1/distributionsets/1/assignedTargets" \
+  -d '[{"id": "'$CID'"}]'
+
+# ═══ Step 3: 轮询（拿到 deploymentBase）═════════════════════════════
+RESP=$(curl -s -H "$AUTH" -H "Accept: application/json" \
+  "$HOST/$TENANT/controller/v1/$CID")
+echo "$RESP" | python3 -m json.tool
+
+# 提取 actionId（假设第一次分配，取 deploymentBase URL 中的数字）
+DEPLOY_URL=$(echo "$RESP" | python3 -c "import sys,json; print(json.load(sys.stdin)['_links']['deploymentBase']['href'])")
+AID=$(echo "$DEPLOY_URL" | grep -oP 'deploymentBase/\K\d+')
+echo "Action ID: $AID"
+
+# ═══ Step 4: 拉取部署详情 ══════════════════════════════════════════
+DEPLOY=$(curl -s -H "$AUTH" -H "Accept: application/json" \
+  "$HOST/$TENANT/controller/v1/$CID/deploymentBase/$AID")
+echo "$DEPLOY" | python3 -m json.tool
+
+# 提取下载地址和 SHA256
+DL_URL=$(echo "$DEPLOY" | python3 -c "
+import sys,json
+art = json.load(sys.stdin)['deployment']['chunks'][0]['artifacts'][0]
+print(art['_links']['download-http']['href'])
+")
+SHA256=$(echo "$DEPLOY" | python3 -c "
+import sys,json
+print(json.load(sys.stdin)['deployment']['chunks'][0]['artifacts'][0]['hashes']['sha256'])
+")
+echo "Download: $DL_URL"
+echo "SHA256:   $SHA256"
+
+# ═══ Step 5: 上报属性 ══════════════════════════════════════════════
+curl -s -H "$AUTH" -H "Content-Type: application/json" -X PUT \
+  "$HOST/$TENANT/controller/v1/$CID/configData" \
+  -d '{"mode":"merge","data":{"osType":"linux","hostname":"'$CID'","swVersion":"V1.0.0.0"}}'
+
+# ═══ Step 6: 下载 ══════════════════════════════════════════════════
+curl -H "$AUTH" -o /tmp/update.zip "$DL_URL"
+
+# ═══ Step 7: 校验 ══════════════════════════════════════════════════
+echo "$SHA256  /tmp/update.zip" | sha256sum -c
+
+# ═══ Step 8: 上报四步状态 ══════════════════════════════════════════
+FB="$HOST/$TENANT/controller/v1/$CID/deploymentBase/$AID/feedback"
+
+curl -s -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"status":{"execution":"download","result":{"finished":"none"},"details":["Starting"]}}' "$FB"
+
+curl -s -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"status":{"execution":"downloaded","result":{"finished":"none"},"details":["Downloaded"]}}' "$FB"
+
+curl -s -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"status":{"execution":"proceeding","result":{"finished":"none"},"details":["Installing"]}}' "$FB"
+
+curl -s -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"status":{"execution":"closed","result":{"finished":"success"},"details":["Installation complete"],"code":200}}' "$FB"
+
+# ═══ Step 9: 验证 ══════════════════════════════════════════════════
+curl -s -u $ADMIN "$HOST/rest/v1/targets/$CID/actions/$AID/status" | python3 -m json.tool
+
+echo "Done! Action $AID is now finished."
+```
+
+### 12.2 Hawkbit 状态流转图
+
+```
+  管理员分配 DS
+       │
+       ▼
+   RUNNING                                 WAITING_FOR_CONFIRMATION
+       │                                         │
+       ▼                                         │ confirmed
+   RETRIEVED  ◄─── deploymentBase                ▼
+       │         (轮询返回)                   RUNNING
+       ▼                                         │
+   DOWNLOAD                                     ...
+       │
+       ▼
+   DOWNLOADED
+       │
+       ▼
+   PROCEEDING ──→ status: RUNNING
+       │
+   ┌───┴───┐
+   ▼       ▼
+FINISHED  ERROR        ◄─── closed + success/failure
+ (成功)    (失败)
+
+  任意阶段 ──cancel──→ CANCELING ──→ CANCELED
+```
+
+### 12.3 API 端点速查表
+
+| 操作 | 方法 | 路径 | 认证 |
+|------|------|------|------|
+| 轮询 | GET | `/{tenant}/controller/v1/{controllerId}` | DDI |
+| 部署详情 | GET | `/{tenant}/controller/v1/{controllerId}/deploymentBase/{actionId}` | DDI |
+| 上报反馈 | POST | `.../deploymentBase/{actionId}/feedback` | DDI |
+| 取消反馈 | POST | `.../cancelAction/{actionId}/feedback` | DDI |
+| 确认反馈 | POST | `.../confirmationBase/{actionId}/feedback` | DDI |
+| 上报属性 | PUT | `/{tenant}/controller/v1/{controllerId}/configData` | DDI |
+| 下载文件 | GET | `/{tenant}/controller/v1/{controllerId}/softwaremodules/{id}/artifacts/{file}` | DDI |
+| 下载MD5 | GET | `.../softwaremodules/{id}/artifacts/{file}.MD5SUM` | DDI |
+| 分配 DS | POST | `/rest/v1/distributionsets/{id}/assignedTargets` | Basic |
+| 查询 target | GET | `/rest/v1/targets/{controllerId}` | Basic |
+| 查询 action | GET | `/rest/v1/targets/{controllerId}/actions/{id}` | Basic |
+| 查询状态 | GET | `/rest/v1/targets/{controllerId}/actions/{id}/status` | Basic |
+| 查询属性 | GET | `/rest/v1/targets/{controllerId}/attributes` | Basic |
+| 取消 action | DELETE | `/rest/v1/targets/{controllerId}/actions/{id}` | Basic |
+| 配置管理 | GET/PUT/DELETE | `/rest/v1/system/configs/{key}` | Basic |