# 33 个应用迁移与官方套件安装方案

本轮采用 **SPKG 1.1 官方平台模块**：33 个应用都有独立套件 ID、版本、架构、签名、UI 入口和生命周期合同，默认安装与可选安装采用同一个引擎。Vue 公共依赖、账户认证、Rust API、Linux 身份与受限 broker 由宿主提供；模块不是可脱离 ApuOS 独立启动的原生进程。

## 用户确认的安装策略

新装默认 18 个：系统概览、存储空间、文件管理、应用中心、套件中心、下载中心、回收站、容器管理、控制面板、浏览器、媒体中心、服务管理、数据库中心、虚拟机管理、任务中心、日志中心、备份中心（现有云备份）、网络中心。其余 15 个可在套件中心单选、多选或全部安装。

已有设备首次升级时为全部 33 个现有应用登记已安装状态，保留账户和业务数据；之后升级保留用户的已安装/未安装选择，不会自动把已卸载的应用重新装上。系统概览、存储空间、文件管理、应用中心、套件中心、回收站、控制面板是受保护的恢复入口，可以随宿主更新和修复，不能从 UI 卸载。其他默认应用也可卸载其管理模块，独立容器、数据库、虚拟磁盘及服务工作负载不会随管理页面删除。

## 全量迁移清单

| 应用 | 新装策略 | 套件 ID | API 能力 |
| --- | --- | --- | --- |
| 回收站 | 默认安装 / 受保护 | `com.apuos.app.recycle` | `files.read`, `knowledge.read`, `echo.read`, `health.read`, `ai.chat` |
| 岁月留声 | 可选安装 | `com.apuos.app.echo` | `echo.read` |
| 文件互传 | 可选安装 | `com.apuos.app.transfer` | `transfer.read` |
| 健康中心 | 可选安装 | `com.apuos.app.health` | `health.read` |
| 终端 | 可选安装 | `com.apuos.app.terminal` | `terminal.admin` |
| 算法商城 | 可选安装 | `com.apuos.app.algorithms` | `algorithms.read` |
| AI 大模型 | 可选安装 | `com.apuos.app.models` | `ai.models.read`, `ai.chat`, `ai.gateway.read` |
| AI Agent | 可选安装 | `com.apuos.app.agents` | `ai.local-agents.read`, `ai.agents.read` |
| AI 硬件 | 可选安装 | `com.apuos.app.hardware` | `ai.hardware.read` |
| 自动化 | 可选安装 | `com.apuos.app.automations` | `automation.read` |
| 媒体中心 | 默认安装 | `com.apuos.app.media` | `library.read` |
| 相册 | 可选安装 | `com.apuos.app.photos` | `library.read` |
| openraw | 可选安装 | `com.apuos.app.openraw` | `openraw.read` |
| 知识库 | 可选安装 | `com.apuos.app.knowledge` | `knowledge.read` |
| Office | 可选安装 | `com.apuos.app.office` | `files.read` |
| 文件管理 | 默认安装 / 受保护 | `com.apuos.app.files` | `files.read` |
| 任务中心 | 默认安装 | `com.apuos.app.tasks` | `tasks.read` |
| 系统概览 | 默认安装 / 受保护 | `com.apuos.app.overview` | `system.read` |
| 存储空间 | 默认安装 / 受保护 | `com.apuos.app.storage` | `storage.read` |
| 日志中心 | 默认安装 | `com.apuos.app.logs` | `logs.read` |
| 投屏 | 可选安装 | `com.apuos.app.casting` | `desktop.read` |
| 下载中心 | 默认安装 | `com.apuos.app.downloads` | `downloads.read` |
| 虚拟机管理 | 默认安装 | `com.apuos.app.zvm` | `virtualization.read` |
| 数据库中心 | 默认安装 | `com.apuos.app.databases` | `native.read` |
| 套件中心 | 默认安装 / 受保护 | `com.apuos.app.native-apps` | `native.read` |
| 浏览器 | 默认安装 | `com.apuos.app.browser` | `desktop.manage` |
| 容器管理 | 默认安装 | `com.apuos.app.containers` | `containers.read` |
| 应用中心 | 默认安装 / 受保护 | `com.apuos.app.apps` | `apps.read` |
| 文件共享 | 可选安装 | `com.apuos.app.shares` | `shares.read` |
| 云备份 | 默认安装 | `com.apuos.app.backups` | `backup.read` |
| 网络中心 | 默认安装 | `com.apuos.app.network` | `network.read` |
| 服务管理 | 默认安装 | `com.apuos.app.services` | `services.read` |
| 控制面板 | 默认安装 / 受保护 | `com.apuos.app.settings` |  |

机器清单：[application-inventory.json](application-inventory.json)。每个应用的源 Manifest 位于 `application-manifests/`，不是空占位安装包；构建脚本从同一前端产物取实际 JS/CSS、生成图标、封装并签名 33 个 `.spkg`。只有构建完成的包才可安装。

## 引擎与实际生命周期

1. **来源及信任。** 首批官方源随宿主发行，位于 `/opt/nas-app/official-packages`。离线可用，不接受任意远程 URL 或未经信任的用户上传。公钥固定在受审源码中；私钥必须位于仓库外，由发行环境的 `APUOS_OFFICIAL_SIGN_KEY` 指定。签名绑定整个压缩载荷及长度，沿用 SPKG 1.0 的 Ed25519 防篡改封装。
2. **预览与确认。** 后端验证签名、路径、大小、架构、官方模块 ID、宿主版本和依赖。预览绑定账户、安装状态版本和包哈希，5 分钟过期；确认时再次核验。安装可自动纳入必需依赖；卸载遇到已安装依赖者会拒绝，支持把相关模块一起选中卸载。
3. **落盘及激活。** 不执行 shell、安装脚本或原生可执行文件。UI 载荷写入私有的 `NAS_STATE_ROOT/official-packages/<app>/<version>/<package-hash>/`，读回验收后才原子提交加密安装登记。前端生产环境通过后端提供的已安装入口 URL 导入代码和样式，响应再次校验文件哈希。
4. **授权及运行边界。** 安装状态不代替账户权限。目录读取沿用 `native.read`，预览和确认要求 `native.manage`，桌面安装摘要仅需 `desktop.read`。会话与能力校验之后，模块守卫检查真实安装状态，并在文件身份代理之前执行，避免借代理绕过 Office/相册的卸载状态。独立网关、公网票据入口同样受守卫约束。
5. **活动任务与卸载。** 套件中心先要求保存并关闭目标应用窗口，避免丢失未保存编辑。活动请求、流、终端会话、算法下载以及索引/保留/自动化等后台工作持有模块活动租约，忙碌时拒绝卸载。提交卸载后不再允许新专属请求或后台处理，并用不跟随符号链接的目录描述符清理本模块代码。共同文件服务、认证、监控及其他应用不被停止。
6. **数据与恢复。** 原有数据库、文件、密钥、模型、笔记、录音、健康记录及独立工作负载不在模块载荷目录中，卸载不遍历这些数据。重新安装恢复管理能力。未提供一键清除业务数据。崩溃后未提交载荷不会被注册，正在执行的记录标记为中断；启动时修复已安装模块损坏的载荷，清理已卸载模块的残留载荷。
7. **更新。** 模块明确绑定宿主版本与共享前端 ABI。宿主发行升级时，为仍已安装的模块校验并切换对应版本；未安装项仍保持未安装。套件中心展示兼容候选更新与损坏修复。数据库破坏性迁移不允许通过包内脚本执行，必须纳入单独审核的宿主迁移。

## 实施文件和发行路径

- 引擎：`backend-rust/src/official.rs`；规范和格式校验：`manifest.schema.json`、`tools/spkg`。
- UI：套件中心“官方应用”，提供详情、安装、多选/全部安装、更新、修复、卸载及操作记录。权限与状态在服务端强制执行。
- 构建：Vite 为全部应用输出保留默认导出的独立入口；`scripts/build-official-packages.py` 收集 JS/CSS，绑定同次构建的公共资源并签名。模板不能直接当发行包安装。
- 新设备安装器默认不要求 Office 原生转换环境；`--with-office` 可显式要求已准备好的独立运行环境。浏览器 Office 编辑与原生转换的能力仍以实际运行环境检测为准。模块的资源字段是宿主预算元数据，不代表每个模块有独立 OS 进程或强制内存/CPU 配额。

## 验收与边界

验证新装 18 项、已有设备 33 项、依赖补齐与卸载阻止、批量事务、卸载再安装保留数据、活动租约、未安装 API 拒绝、签名损坏、来源/落盘符号链接、预览过期或状态变化、载荷篡改、未授权访问及进程重启恢复；使用真实生产 JS/CSS 检查安装后入口与页面加载，再在 Linux ARM64 隔离状态目录复核。

SPKG 1.0 的第三方原生程序安装执行器仍未开放；社区 SPK/FPK 与 APT 原生应用继续使用各自现有受限流程。官方模块不安装任意第三方原生程序，不改变内核、驱动、网桥或已有 NAS 工作负载。