✨ feat(update): 为原生安装增加备份与托管更新

[xyzxiaoma]

Summary

为符合条件的 CPA Manager Plus 原生发布包增加一套显式启用的托管更新流程。用户可以在 Dashboard 中准备经过验证的官方 Release，再由独立更新器重启服务、创建离线回滚快照、切换受管文件并验证目标版本；启动或健康检查失败时会自动恢复旧版本。

该功能有意采用严格的支持边界：只有使用发布包自带控制脚本启动的固定目录原生安装可以启用。Docker、CPA 托管面板、自定义服务、第三方进程管理器以及带额外启动参数的实例仍使用手动更新流程。

社区与维护类 PR 必须提交到 dev。仓库自动化会把其他目标分支改为
dev，这可能改变 diff 并使已有审查评论过时。main 只接受来自本仓库
dev 分支的发布晋级 PR。

Scope

• Frontend panel
• Manager Server
• CPA panel mode
• Full Docker mode
• Native packages / release
• Docs / Wiki
• CI / build / tooling

Changes

• 增加独立原生更新器，以及需要管理员鉴权的能力检测、Release 检查、更新准备、状态轮询和应用接口。
• 在暂存前同时验证官方 GitHub Release URL、GitHub 资产摘要、checksums.txt 和 update-manifest.json，并拒绝不安全压缩包、路径、链接、事务元数据和不受支持的安装布局。
• 切换程序文件前创建程序与数据的离线回滚快照；通过连续稳定健康窗口、目标运行版本和控制脚本状态验证新版本；下一次受控启动时可恢复被中断的事务。
• 为 Windows 和 Unix 官方控制脚本增加显式 enable-updates 注册流程，并限制为默认启动方式和私有更新元数据。
• 原生 Release 现在包含平台更新器和托管更新清单，Immutable Release 校验也会检查这些资产。
• 在 Dashboard 原有版本卡片和 Modal 风格内增加准备、应用和监控更新的交互；对于不支持的 Release 或安装方式，继续显示原有手动下载入口。
• 中英文文档补充启用方法、兼容边界、备份保留、失败恢复和 Windows ACL 行为。

User Impact

符合条件的原生包用户只需显式启用一次，后续即可在 Dashboard 中准备并应用兼容 Release，无需手工复制数据或替换二进制文件。下载和校验阶段服务保持在线，仅在创建离线备份和切换程序文件时短暂重启。

不支持的安装方式仍会收到原有 Release 版本提示和手动下载链接。用户未执行 enable-updates 前，托管更新始终保持关闭。

Compatibility / Runtime Notes

• CPA 面板模式：行为不变。CPA :8317 托管的轻量面板不会显示托管更新功能。
• Manager Server 模式：仅当嵌入式 Manager Server 是可比较的正式版本，并且安装清单描述了安全的固定目录原生包时可用。
• Full Docker / 原生发布包：Docker 仍只支持手动更新。原生包新增平台更新器和更新清单。用户仍需手动安装第一个兼容版本，然后显式启用该能力。
• 控制脚本：托管更新仅支持官方控制脚本的默认启动方式。端口、数据路径等配置应写入 config.json 或环境变量，不支持额外的 start [args...] 参数。
• 平台：实现了 Windows 和 Unix 的 amd64/arm64 原生包路径；Windows 注册流程覆盖 PowerShell 5.1 和 PowerShell 7。

Data / Security Notes

• 更新器只接受官方 seakee/CPA-Manager-Plus GitHub Release 下载前缀中的资产。
• 原生压缩包必须同时通过 GitHub 资产摘要、checksums.txt 和 update-manifest.json 校验；未知或尾随 JSON、路径穿越、重复条目、链接、超限压缩包和不安全事务布局均会被拒绝。
• 停止主进程前，会严格绑定安装 ID、事务 ID、规范化 manifest/status 路径、所属 staging 根目录、当前/目标版本和本地健康检查端点。
• 备份范围包括受管程序文件、可选的 config.json、配置的数据目录和 secrets/。备份清单记录每个文件的大小和 SHA-256，并在恢复前重新验证。
• Windows 更新元数据和备份使用受保护 DACL，仅允许当前用户、SYSTEM 和本机 Administrators；Unix 私有文件与目录使用限制权限。无法建立私有存储时会安全失败。
• API 错误不会向前端泄露本机备份或暂存目录的绝对路径。备份快照不会自动删除，由管理员决定保留策略。

Risk / Rollback

风险等级：高

该功能会替换运行中的原生程序文件并重启 Manager Server，因此风险等级标记为高。不过它默认关闭、失败时安全终止，并且只允许已知的发布包布局。应用更新前必须创建并验证离线回滚快照；新版本启动失败、版本验证失败或文件切换中断时，会尽可能恢复旧程序和旧数据。无法自动恢复的情况会进入 manual_recovery_required，并阻止启动下一笔更新事务。

发布前如需整体移除，可回退本 PR 的四个提交。发布后管理员仍可继续使用原有手动更新方式；保留的备份目录包含旧程序、配置和数据快照，可用于恢复。

Verification

• 类型检查
• Lint
• 测试
• 构建
• 手动 UI 检查
• 文档 / 链接检查
• 不适用，仅文档改动

命令与证据：

npm run type-check
  PASS

npm run lint
  PASS，仅保留 AccountHealthBadge.tsx 既有的 react-refresh warning

npm run build
  PASS

npm run docs:build
  PASS

cd apps/manager-server && go vet ./...
  PASS

cd apps/manager-server && go test \
  ./internal/update \
  ./internal/service/update \
  ./internal/http/controller/update \
  ./internal/http/response \
  ./internal/httpapi
  PASS

node node_modules/vitest/vitest.mjs run \
  tests/nativeControlScripts.test.mjs \
  tests/updateManifest.test.mjs \
  tests/releasePublishedState.test.mjs \
  tests/ciWorkflowIntegrity.test.mjs \
  --testTimeout=45000
  PASS：4 个测试文件，41 条测试

Windows ARM64 交叉编译：
  Manager Server、更新器和 update 测试程序均 PASS

Linux AMD64 交叉编译：
  Manager Server、更新器和 update 测试程序均 PASS

Windows 隔离 UI 验证：
  使用 29317/29318 验证，未影响现有 8317/18317 服务
  桌面宽度与 390x844 窄屏均 PASS，无横向溢出

另外执行了 npm run manager-server:test。所有托管更新相关包均通过；全量命令仍报告仓库既有的 Windows 环境失败：Unix 0600 权限断言在 Windows 上读取为 0666，以及两条 usage-import 符号链接测试因当前 Windows 用户没有创建链接的权限而失败。Linux go test -race ./... 应由远端 CI 提供证据，本地 Windows 环境不声明 race 通过。

此前也在该 Windows 工作区执行过完整前端测试：2221/2223 通过，两个失败均为既有的五秒并行超时，位于 demoPersistIsolation.test.ts 和 useAuthStore.test.ts。本次新增的前端更新专项测试全部通过。

Screenshots / Recordings

桌面端 Dashboard 版本卡片与更新准备弹窗：

另外已在 390x844 窄屏环境检查弹窗布局，无横向溢出。

Docs

• README / README_CN 已更新用户可见能力
• 中英文操作手册和导航已同步
• Demo fixtures、截图和深链接已审查
• 需要 Release Notes
• 不需要，原因如下

文档决定：原生控制指南和更新操作手册已经说明注册方式、支持布局、两阶段流程、备份内容、自动恢复、ACL、清理策略和手动回退。Release Notes 应特别说明：第一个兼容原生版本仍需手动安装，并且用户必须显式执行注册命令。

Related

N/A