Merge pull request #2122 from Websoft9/feature/appstore-publish-migration

fix

Author: zhaojing1987

build/library_publish.py

@@ -121,23 +121,7 @@ def v2_full_package_names(channel: str, dataset_version: str) -> tuple[str, str]
     return (f"{V2_FULL_PACKAGE_BASENAME}-{dataset_version}.zip", f"{V2_FULL_PACKAGE_BASENAME}-{channel}.zip")
 
 
-def _app_version_from_hash(app_hash: str) -> str:
-    """Derive a stable, content-addressed version identifier from an app's fingerprint hash.
-
-    Using the content hash means the same app content always produces the same
-    versioned filename, so unchanged apps never need to be rebuilt or re-uploaded.
-    """
-    return app_hash[:16]
-
-
-def v2_app_package_names(app_version: str) -> tuple[str, str]:
-    """Return (versioned_zip_name, latest_zip_name) for a single app.
-
-    ``app_version`` should be a per-app content-derived identifier, not the
-    global publish timestamp, so that only actually-changed apps get new
-    versioned packages.
-    """
-    return (f"{app_version}.zip", "latest.zip")
+APP_PACKAGE_NAME = "latest.zip"
 
 
 def sha256_file(path: Path) -> str:
@@ -197,30 +181,19 @@ def current_app_fingerprint(app_dir: Path) -> str:
     return digest.hexdigest()
 
 
-def build_app_package_entry(app_name: str, app_version: str) -> dict:
-    versioned_name, latest_name = v2_app_package_names(app_version)
-    app_base = f"apps/{app_name}"
-    return {
-        "versioned": f"{app_base}/{versioned_name}",
-        "latest": f"{app_base}/{latest_name}",
-    }
+def build_app_package_entry(app_name: str) -> dict:
+    return {"latest": f"apps/{app_name}/{APP_PACKAGE_NAME}"}
 
 
-def build_app_checksum_entry(app_name: str, app_version: str) -> dict:
-    package_entry = build_app_package_entry(app_name, app_version)
-    return {
-        "versioned": f"{package_entry['versioned']}.sha256",
-        "latest": f"{package_entry['latest']}.sha256",
-    }
+def build_app_checksum_entry(app_name: str) -> dict:
+    return {"latest": f"apps/{app_name}/{APP_PACKAGE_NAME}.sha256"}
 
 
 def build_apps_index(dataset_version: str, channel: str, generated_at: str) -> dict:
     apps = []
     for app_dir in sorted(path for path in APPS_DIR.iterdir() if path.is_dir()):
         variables = load_variables_json(app_dir)
         app_name = app_dir.name
-        app_hash = current_app_fingerprint(app_dir)
-        app_version = _app_version_from_hash(app_hash)
         apps.append(
             {
                 "app": app_name,
@@ -229,9 +202,9 @@ def build_apps_index(dataset_version: str, channel: str, generated_at: str) -> d
                 "release": variables.get("release"),
                 "versions": summarize_versions(variables.get("edition", [])),
                 "path": f"apps/{app_name}",
-                "hash": app_hash,
-                "package": build_app_package_entry(app_name, app_version),
-                "checksum": build_app_checksum_entry(app_name, app_version),
+                "hash": current_app_fingerprint(app_dir),
+                "package": build_app_package_entry(app_name),
+                "checksum": build_app_checksum_entry(app_name),
             }
         )
 
@@ -450,7 +423,7 @@ def validate_library_artifacts(output_dir: Path, manifest: dict, changed_app_nam
             continue
         package = entry.get("package") or {}
         checksum = entry.get("checksum") or {}
-        for path in (package.get("versioned"), package.get("latest"), checksum.get("versioned"), checksum.get("latest")):
+        for path in (package.get("latest"), checksum.get("latest")):
             if not path or not (output_dir / path).exists():
                 raise SystemExit(f"missing app package artifact: {entry.get('app')} -> {path}")
 
@@ -610,25 +583,16 @@ def build_v2_appstore_artifacts(
         if app_name not in changed_app_names:
             continue
 
-        # Look up the app's content-derived version identifier from the index.
-        app_entry = next((e for e in apps_index["apps"] if e["app"] == app_name), None)
-        if app_entry is None:
-            continue
-        app_version = _app_version_from_hash(app_entry["hash"])
-        app_versioned_name, app_latest_name = v2_app_package_names(app_version)
-
         app_output_dir = apps_packages_dir / app_name
         app_output_dir.mkdir(parents=True, exist_ok=True)
 
         with tempfile.TemporaryDirectory() as tmp_dir_name:
             tmp_dir = Path(tmp_dir_name)
             app_package_root = tmp_dir / app_name
             shutil.copytree(app_dir, app_package_root)
-            create_zip_from_directory(app_package_root, app_output_dir / app_versioned_name)
+            create_zip_from_directory(app_package_root, app_output_dir / APP_PACKAGE_NAME)
 
-        shutil.copy2(app_output_dir / app_versioned_name, app_output_dir / app_latest_name)
-        write_checksum_file(app_output_dir / app_versioned_name)
-        write_checksum_file(app_output_dir / app_latest_name)
+        write_checksum_file(app_output_dir / APP_PACKAGE_NAME)
 
     # ── library – write index, delta, manifest ───────────────
     write_json(library_dir / apps_index_name, apps_index)

docs/devops.md

@@ -388,48 +388,34 @@ v2 workflow 的职责应为：
 3. `artifact/websoft9/v2/<channel>/appstore/library/apps-delta-<fromVersion>-to-<toVersion>.json`
 4. `artifact/websoft9/v2/<channel>/appstore/library/full/library-<datasetVersion>.zip`
 5. `artifact/websoft9/v2/<channel>/appstore/library/full/library-<channel>.zip`
-6. `artifact/websoft9/v2/<channel>/appstore/library/apps/<app>/<appVersion>.zip`
-7. `artifact/websoft9/v2/<channel>/appstore/library/apps/<app>/latest.zip`
+6. `artifact/websoft9/v2/<channel>/appstore/library/apps/<app>/latest.zip`
+7. `artifact/websoft9/v2/<channel>/appstore/library/apps/<app>/latest.zip.sha256`
 
 说明：
 
 1. `full/library-<datasetVersion>.zip` 是不可变的全量快照包，`<datasetVersion>` 使用全局发布时间戳
 2. `full/library-<channel>.zip` 是该通道下的全量最新别名，可被覆盖
-3. `apps/<app>/<appVersion>.zip` 是不可变的单 app 快照包，**`<appVersion>` 使用该 app 内容指纹哈希的前 16 位十六进制字符，而非全局发布时间戳**
-4. `apps/<app>/latest.zip` 是该 app 在该通道下的最新别名，可被覆盖
-5. `latest` 类对象只承担最新指针语义，不承担审计与回滚语义
-6. 真正的审计、回滚与复现必须依赖版本化对象
-
-**`<appVersion>` 设计说明：**
-
-单 app 包的版本标识采用内容寻址（content-addressed）策略：
-
-- `<appVersion>` = SHA-256(`apps/<app>/` 下所有文件的内容 + 相对路径) 的前 16 位十六进制字符
-- 同一 app、同一内容 → 同一 `<appVersion>` → 文件名不变
-- 这确保了 **只有内容实际变更的 app 才产生新的版本化包**，未变更的 app 的已有版本化包无需重建、无需重新上传
-
-此字段在 `apps-index` 的 `hash` 字段中以完整 SHA-256 形式存储，`<appVersion>` 是其截断派生值。
+3. `apps/<app>/latest.zip` 是该 app 在该通道下的唯一安装包，每次 app 内容变更时覆盖更新
+4. R2 上的历史审计与回滚能力由 git 仓库保证，R2 仅作为分发缓存
+5. 客户端通过 `apps-index` 中的 `hash` 字段判断 app 是否变更，无需版本化文件名
 
 ### 10.2 单 App 包构建优化
 
-为避免每次发布都重建全部 300+ 个 app 的单 app 包，构建流程采用按需构建策略：
-
-1. **首次发布**（无历史 `from_ref`）：为所有 app 构建单 app 包（全量冷启动）
-2. **增量发布**（存在历史 `from_ref`）：**仅**为 `apps-delta` 中的 `addedApps` 与 `changedApps` 构建单 app 包
-3. 未变更 app 的单 app 包不重新构建、不重新上传——R2 上已有文件保持不变
+每个 app 只保留一个 `latest.zip`，构建流程采用按需覆盖策略：
 
-此优化依赖两个前提：
+1. **首次发布**（R2 上 `apps/` 为空）：为所有 app 构建 `latest.zip`（全量冷启动）
+2. **增量发布**（R2 已播种）：**仅**为 `apps-delta` 中的 `addedApps` 与 `changedApps` 构建/覆盖 `latest.zip`
+3. 未变更 app 的 `latest.zip` 不重新构建、不触碰——R2 上已有文件保持不变
 
-1. `<appVersion>` 使用内容哈希（内容不变 → 文件名不变 → 无需重建）
-2. R2 上传步骤采用**追加/覆盖模式**，而非同步删除模式（sync-with-delete），避免覆盖掉未变更 app 的已有包
+此优化依赖 R2 上传步骤采用 `aws s3 sync` 默认行为（追加/覆盖，不删除），配合 `check_seed` 步骤检测首次发布。
 
 优化效果（以 300 个 app、每次变更 2 个为例）：
 
-| 指标 | 优化前 | 优化后 |
-|------|--------|--------|
+| 指标 | 全量构建 | 增量构建 |
+|------|---------|---------|
 | 单 app zip 打包次数 | 300 | 2 |
 | R2 PUT 请求数（单 app 部分） | ~600 | ~4 |
-| 10 次发布后 R2 版本化包存量 | ~3000 | ~320 |
+| R2 上单 app 文件数 | 600 | 600（无孤儿堆积） |
 
 注意：全量包 `full/library-<datasetVersion>.zip` 仍然每次发布都重建（包含所有 app），作为首装与灾备的兜底路径。
 
@@ -632,21 +618,18 @@ v2 workflow 的职责应为：
 
 ### 11.4 apps-index 扩展要求
 
-为支持单 app 下载，`apps-index` 中每个 app 条目建议最少包含：
+每个 app 条目最少包含：
 
 1. `app`
 2. `hash`
-3. `package.versioned`
-4. `package.latest`
-5. `checksum.versioned`
-6. `checksum.latest`
+3. `package.latest`
+4. `checksum.latest`
 
 说明：
 
-1. `package.versioned` 指向不可变单 app 包
-2. `package.latest` 指向该 app 的最新别名
-3. 新客户端优先读取 `package.versioned`，以获得更强一致性
-4. 只关心当前通道最新值的轻量客户端可读取 `package.latest`
+1. `package.latest` 指向该 app 的唯一安装包（`latest.zip`）
+2. `hash` 是该 app 目录内容的完整 SHA-256 指纹，客户端通过对比此字段判断 app 是否变更
+3. 当 `hash` 与本地记录不同时，客户端下载 `latest.zip` 覆盖本地
 
 ## 14. 校验门禁