> 域名迁移（0.16.108）：旧版无法在线检查更新时，下载本页完整 ZIP，在“设置 → 本应用更新 → 手动上传升级包”上传一次，无需解压、删除项目或重建数据卷。

# 扩展商店 · 快速安装

版本 **0.16.108**，适用于已开启 Docker 的铁牛 NAS（x86_64 / AMD64，不支持 ARM）。准备一台电脑，与 NAS 连接同一局域网；全程不用命令行。

**首次安装：电脑解压 → 上传文件 → Compose 新增项目 → 打开使用。**

已安装本应用请看文末「升级」；上次安装报错或中断，请先看「遇到问题」，不要再次新增项目。

## 首次安装：5 步完成

1. **电脑解压。** 下载 `NAS-App-Center-Share-0.16.108-amd64.zip`。Windows 右键「全部解压」，macOS 双击 ZIP。里面的 `runtime.tar.gz` 保持原样，不要再解压。
2. **上传文件。** 在铁牛「文件管理」新建 `nas-app-center` 文件夹，把解压出的全部文件上传进去。不能上传文件夹时，多选里面的文件上传。确认 `Dockerfile`、`docker-compose.yml`、`runtime.tar.gz` 在同一层。
3. **新增项目。** 打开「Docker → Compose → 新增项目」，名称填 `nas-app-center`，「路径」选择刚才包含这三个文件的文件夹。提示已有配置文件时，点击「确定」使用它。
4. **启动安装。** 返回创建页，勾选「创立项目后立即启动」，点击该页的「确定」一次，等待完成。确认 `web` 和 `agent` 两个服务均已启动。
5. **打开使用。** 登录铁牛管理员桌面，刷新桌面后从「扩展商店」入口进入，再到「应用商店」安装应用。直接访问 `http://NAS的局域网IP:8790` 若提示登录，请回铁牛桌面重新进入；扩展商店需要验证当前铁牛管理员身份。选择文件夹沿用同一会话，与铁牛文件管理中的文件空间对应，不需要另设目录账号。

**请使用 Compose 新增项目，不要使用「导入镜像」功能。** NAS 上不用解压，也不能只上传 ZIP 或 YAML 文件。

商店自动连接，无需邀请码。中心默认使用铁牛管理员身份，不需要另设中心密码。分享包不预设信任网段。设备所有者已配置受信任内网时，管理和目录选择可按该配置直接使用；其余入口使用当前铁牛管理员身份。包内不预装应用，商店下载需要联网。

安装完成后，桌面入口会自动同步；应用安装后也会注册独立入口。若没有显示，先刷新铁牛桌面，再到扩展商店「设置 → 铁牛桌面入口」查看状态或点击「重新同步桌面图标」。保留同步结果中的具体报错供排查，无需反复重装。

## 遇到问题

| 提示或现象 | 怎么做 |
| --- | --- |
| 找不到 `Dockerfile` | 检查项目路径，必须选中直接包含上述三个文件的文件夹 |
| `container name ... is already in use` | 已有同名容器，不代表你装了两次。先保留日志，截图 Compose 和全部容器列表给维护者；不要直接删除数据卷或改项目名 |
| 安装中断、显示 `DONE` 但打不开 | 查看原项目和两个服务的状态及日志；`DONE` 可能只表示镜像构建完成，不要再次新增项目 |

## 升级

已有 0.16.5 及以上版本：打开「设置 → 本应用更新 → 检查更新」（旧版入口名为“中心升级”），有新版时点击「下载并升级」，不需要解压或重新创建项目。

0.5.0–0.16.4：在「设置 → 中心升级」上传**更高版本的完整 ZIP，不解压、不删除项目或数据卷**。已是 0.16.108 无需重装。0.14.0 需先联系维护者取得 0.14.1 过渡包。

更新商店里的应用使用「更新」页，不用重装中心。

本分享入口仅分发扩展商店及其安装说明、校验文件。影库等应用在安装后的“应用商店”中获取；商店管理端属于维护工具，不在此页提供下载入口。

## 旧版更新故障恢复（0.16.90 修复说明）

0.16.86、0.16.89 的网页上传升级存在分片回调错误，可能显示 `path is not defined` 并停止上传。修复版 ZIP 不会自动修正仍在运行的旧版网页。恢复访问后优先使用“在线升级”；无法恢复访问时，先核对旧部署与数据卷，再按原项目进行离线更新，不能删除应用、另建项目或清理旧卷来绕过问题。

“暂时无法验证铁牛身份”可能是网页到控制服务或控制服务到铁牛接口的连接故障，不等于账号过期。0.16.90 区分登录失效和服务故障；公网仍需管理员身份，可信内网仍沿用设备原有显式授权，不自动扩大范围。

Docker 的镜像列表只说明镜像存在，不能证明服务已切换。升级完成应核对网页与控制服务均使用目标版本、任务完成、原数据卷保留，以及当前入口的身份验证和应用列表可用。0.16.90 新增的事务访问检查由新版升级程序执行；从旧版首次升级时，旧升级程序不会自动获得这项检查，因此仍需独立验收。

仓库提供只读工具 `tools/diagnose_center_update.py`，在受影响 NAS 的终端执行 `python3 diagnose_center_update.py`。它需要已有 Docker 访问权限，输出服务镜像、任务阶段和无凭据连接探测，不输出密码、环境变量、原始日志或完整挂载配置，也不修改容器或数据。连接探测不能替代真实管理员会话和手机入口验收。

## 最近公开版本的兼容升级入口

兼容工具面向 0.16.84、0.16.86、0.16.88、0.16.89、0.16.90 原版标准部署。工具同时核对运行版本、旧升级程序摘要、唯一的服务实例与原有数据挂载；未知或修改过的部署拒绝执行。0.16.85、0.16.87 未公开，不作为用户升级基线。**源码兼容检查不替代实机升级验收；具体支持状态以本次版本的验收记录为准。**

这些旧版本的升级程序仍读取废弃的 `/web-data/auth.json`，全新安装可能没有此文件。新包允许它缺失，但不能修改正在执行的旧升级程序。另有旧页面在分片上传后触发 JavaScript 异常；重复上传不会修复页面。

在 NAS 终端进入本包解压目录，以有本机 Docker 访问权限的账号执行以下检查。完整包 SHA-256 必须与可信下载说明核对，不从陌生聊天或未知脚本取包：

```bash
python3 legacy_center_upload.py --package NAS-App-Center-Share-<目标版本>-amd64.zip --sha256 <完整SHA256>
```

不加 `--apply` 只检查，不创建文件、不上传、不启动升级。检查通过且确认短暂中断扩展商店后，在原命令末尾加 `--apply`。执行流程是：保留已有旧文件、仅补缺失的空兼容文件，然后通过原控制服务上传分片，由原升级事务校验与切换。不会直接替换容器，不改鉴权或用户应用数据，不执行包内脚本；本机 Docker 权限是使用此工具的前提。

旧网页可能已经留下未提交的上传。此时核对任务确实处于 `uploading` 后，可明确增加 `--restart-upload` 丢弃未提交上传并重新传包；正在构建、切换、回退或等待人工处理的任务始终拒绝覆盖。升级提交只发送一次；响应丢失时保留终端显示的任务 ID，回扩展商店核对结果，不重复提交。

仅需准备旧文件、之后仍使用原网页在线升级时，可执行：

```bash
python3 prepare_legacy_center_upgrade.py
python3 prepare_legacy_center_upgrade.py --apply
```

已有文件逐字节保留；缺失时以网页服务实际 UID 排他创建空兼容文件。服务重复、异常挂载、符号链接、权限问题或未知旧程序摘要都会中止。升级后核对网页和控制服务版本、任务完成、应用列表、目录与业务数据；“已上传”或“事务已接收”不代表升级成功。


## 升级后的镜像整理

0.16.92 起，升级成功后会自动整理当次盘点中无引用的历史镜像，包括无标签镜像。运行或已停止容器、当前安装记录、备份和未完成恢复仍需要的镜像保留；不删除用户文件或数据卷。子镜像清理后重新检查父镜像。

清理分批执行，进度和结果显示在“本应用更新”。清理期间新增的镜像不加入本次范围。出现占用变化或删除结果不明时保留并提示，清理失败不会回退已经成功的升级；可在“设置 → 运行与存储”核对剩余项。


## 本轮候选补充：自动整理临时文件

本候选仅完成本地验证，实机升级与商店安装未验收。扩展商店成功升级并结束工作容器后删除当前事务快照；上传超过24小时无活动会失效并回收。失败镜像缓存保留7天供续传，空闲后台回收过期缓存及24小时以上的可识别部分文件。无引用包图标同步回收。安装日志保留7天、已完成日志总量目标64MiB；正在写入的日志与无法确认的文件保留。清理失败记录并重试，不影响已成功升级的判断。

商店管理使用同一上传实例锁，后台每轮回收超过1小时无活动的上传会话，以及超过24小时的可识别孤立上传部分文件；不删除已发布资源、草稿载荷或用户文件。商店镜像资源的引用回收继续沿用独立开关和发布引用检查，不因临时文件清理自动启用。
