升级管理

2026-04-07 09:45:27 +08:00
parent 738c2d4ae6
commit 93539ccd97
43 changed files with 1647 additions and 483 deletions
@@ -1,49 +1,51 @@
-# 标准收发器离线升级包最小样例
+# RECEIVER 离线升级包最小样例

-本目录提供 `STANDARD_APP` 离线升级包的最小示例骨架，用于对齐打包方、后端和联调流程。
+本目录保留原有 `standard-app` 路径，便于继续联调，但样例内容已经切换到当前第一版 `RECEIVER` 升级包契约。

 目录结构：

 ```text
 standard-app/
 ├── manifest.json
+├── build-package.sh
 └── payload/
    └── scripts/
-        └── orchestrator.sh
+        ├── execute.sh
+        ├── precheck.sh
+        ├── verify.sh
+        └── rollback.sh
 ```

 说明：

- 本目录中的 `manifest.json` 使用了占位符 `__PAYLOAD_SHA256__`
- 真正打包前，需要先对 `payload.zip` 计算 `SHA-256`，再替换该字段
- `signature.sig` 不放在仓库示例里，必须由打包方使用“固件完整性密钥”私钥在打包阶段生成
+- `execute.sh` 必填
+- `precheck.sh`、`verify.sh`、`rollback.sh` 可选
+- 本样例里四个脚本都给出，方便联调
+- `signature.sig` 不放在仓库示例里，必须由打包方在打包阶段生成
+- `build-package.sh` 会把 `manifest.json`、`signature.sig` 和 `payload/` 打成最终 `upgrade-package.zip`

 推荐打包步骤：

 1. 进入当前示例目录
-2. 将 `payload/` 压缩为 `payload.zip`
-3. 计算 `payload.zip` 的 `SHA-256`
-4. 用实际摘要替换 `manifest.json` 中的 `__PAYLOAD_SHA256__`
-5. 对 `manifest.json` 原始字节生成 `signature.sig`
-6. 将 `manifest.json`、`signature.sig`、`payload.zip` 压缩成最终 `upgrade-package.zip`
+2. 根据实际设备修改 `manifest.json` 中的 `productType`、`version`、`minCompatibleVersion`
+3. 对 `manifest.json` 原始字节生成真实的 `signature.sig`
+4. 执行 `./build-package.sh`

 参考命令：

 ```bash
 cd docs/examples/upgrade-package/standard-app

-zip -rq payload.zip payload
-PAYLOAD_SHA256="$(shasum -a 256 payload.zip | awk '{print $1}')"
-sed "s/__PAYLOAD_SHA256__/${PAYLOAD_SHA256}/g" manifest.json > manifest.generated.json
+# 这里替换为正式签名工具，生成 manifest.json 对应的 signature.sig
+# sign-manifest manifest.json > signature.sig

-# 这里改为公司正式签名工具，生成 manifest.generated.json 对应的 signature.sig
-# sign-manifest manifest.generated.json > signature.sig
-
-zip -j upgrade-package.zip manifest.generated.json signature.sig payload.zip
+chmod +x build-package.sh
+./build-package.sh
 ```

 联调时建议：

- 先用这个目录骨架做一个 `STANDARD_APP` 预检样包
- `orchestrator.sh` 可以先只输出日志并返回 `0`
- 等预检、建任务、执行链路跑通后，再替换成真实升级脚本
+- 先用这个目录骨架做一个 `RECEIVER` 预检样包
+- 脚本可以先只输出日志并返回 `0`
+- 等预检、建任务、执行、回滚链路跑通后，再替换成真实升级脚本
+- 如果当前环境启用了真实密码卡验签，占位 `signature.sig` 无法通过预检
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OUTPUT_PATH="${1:-${SCRIPT_DIR}/upgrade-package.zip}"
+SIGNATURE_PATH="${SCRIPT_DIR}/signature.sig"
+
+if [[ ! -f "${SIGNATURE_PATH}" ]]; then
+  echo "missing signature file: ${SIGNATURE_PATH}" >&2
+  echo "generate a real signature.sig for manifest.json before building the package" >&2
+  exit 1
+fi
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "${tmpdir}"' EXIT
+
+cp "${SCRIPT_DIR}/manifest.json" "${tmpdir}/manifest.json"
+cp "${SIGNATURE_PATH}" "${tmpdir}/signature.sig"
+cp -R "${SCRIPT_DIR}/payload" "${tmpdir}/payload"
+
+rm -f "${OUTPUT_PATH}"
+(
+  cd "${tmpdir}"
+  zip -rq "${OUTPUT_PATH}" manifest.json signature.sig payload
+)
+
+echo "package built: ${OUTPUT_PATH}"
@@ -1,13 +1,14 @@
 {
-  "packageFormatVersion": 1,
-  "packageId": "PKG-20260319-STANDARD-001",
-  "targetComponent": "STANDARD_APP",
-  "targetVersion": "V1.3.2",
+  "packageId": "PKG-20260403-RECEIVER-001",
+  "taskType": "RECEIVER",
+  "productType": "DIRECT",
+  "version": "V1.4.0",
  "minCompatibleVersion": "V1.3.0",
-  "description": "标准收发器企业版离线升级包最小样例",
-  "createdAt": "2026-03-19T16:30:00+08:00",
-  "orchestrator": "scripts/orchestrator.sh",
-  "fileChecksums": {
-    "payloadZip": "__PAYLOAD_SHA256__"
+  "description": "receiver upgrade package",
+  "entrypoints": {
+    "execute": "payload/scripts/execute.sh",
+    "precheck": "payload/scripts/precheck.sh",
+    "verify": "payload/scripts/verify.sh",
+    "rollback": "payload/scripts/rollback.sh"
  }
 }
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+TASK_ID="${1:-UNKNOWN}"
+
+echo "[upgrade] task=${TASK_ID} phase=execute message=execute placeholder"
@@ -1,11 +0,0 @@
-#!/usr/bin/env bash
-
-set -euo pipefail
-
-TASK_ID="${1:-UNKNOWN}"
-
-echo "[upgrade] task=${TASK_ID} phase=backup message=start backup placeholder"
-echo "[upgrade] task=${TASK_ID} phase=stop-service message=stop service placeholder"
-echo "[upgrade] task=${TASK_ID} phase=deploy message=deploy placeholder"
-echo "[upgrade] task=${TASK_ID} phase=health-check message=health check placeholder"
-echo "[upgrade] task=${TASK_ID} phase=done message=upgrade completed"
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+TASK_ID="${1:-UNKNOWN}"
+
+echo "[upgrade] task=${TASK_ID} phase=precheck message=precheck placeholder"
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+TASK_ID="${1:-UNKNOWN}"
+
+echo "[upgrade] task=${TASK_ID} phase=rollback message=rollback placeholder"
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+TASK_ID="${1:-UNKNOWN}"
+
+echo "[upgrade] task=${TASK_ID} phase=verify message=verify placeholder"