Nextcloud 迁移实录：跳过四个大版本与一次上游事故考古

本文最后更新于：2026年11月14日上午

NAS 架构升级的收官阶段，自建网盘是数据面最重的一块。本文记录这次迁移的完整决策与实施：从"为什么敢跳过四个大版本直接新装"，到密码哈希回填让家人无感切换，再到追新版时撞上的一场上游发布事故——用 registry API 做的取证过程也一并记录。

同一 registry API 查询下的两个 tag：空清单 vs 八平台

背景：一个带病服役的旧网盘

旧网盘自 2023 年部署后一直运行在旧 NAS 的虚拟机上：Nextcloud 31 版、三容器（应用 + Redis + MariaDB），两个家人账号，存的都是文档和软件安装包这类小文件。它有两个长期问题：一是版本落后——官方已发布 35 版，中间隔着四个大版本；二是带病——半年前开始页面持续 503，根因是配置文件属主不对导致容器进程读不到配置，一直没修。

这次架构升级把全部服务迁往新虚拟机，网盘跟着搬。迁移前先盘点数据形态，这决定了后面所有方案选择：两个账号合计一百余个文件、共八十余 MB；日历零条、联系人一条（自建）、分享链接零个；数据库全量导出仅六 MB。一句话：一个纯文件库，没有日历/协作/应用生态。

目的

三条：数据零丢失搬进新栈；服务恢复健康（503 根治）；版本升到最新。外加一条软目标——家人无感：账号不换、密码不改，客户端不用重新折腾。

方案选择：为什么放弃逐版本升级

Nextcloud 官方只支持相邻大版本升级，31 到 35 要走四步，每步换镜像跑升级、涉及目录结构调整，预计一小时起步且每步都可能撞应用不兼容。这是"标准答案"。

但回到数据形态盘点：逐版本升级保的是数据库里的日历、协作、应用数据——而这些我一条都没有。我有的只是文件本体和密码哈希，这两样都可以脱离数据库迁移。于是备选方案浮现：全新安装 35 + 文件导入 + 密码哈希回填，十分钟确定性流程换一小时的不确定性。

判断标准就一条：升级保护的东西你是不是真的有。没有，就不必为它付升级的成本。选全新安装。

实施：三步搬完

第一步，全新起栈。 新虚拟机上 compose 拉起 Nextcloud 35 官方镜像加 MariaDB 新库，初始化建管理员。旧库先做全量导出，三份留档（旧机、工作站，新机各一）——这是整个迁移的后悔药。

第二步，文件直传。 旧实例的文件树打包走局域网管道直传新机，落盘后修正属主（503 的根因正是属主问题，这一步在新栈从机制上根治），再触发全量扫描入缓存。文件数逐一对账，一百零四对一百零四。

第三步，密码哈希回填——"密码不用改"的关键。 新装实例建用户只能设新密码，直接违背"家人无感"目标。查用户表结构：密码以 argon2id 哈希存在 oc_users 的 password 字段，而新旧版本算法一致——意味着哈希可以直接搬运：

1 2	`-- 把旧实例导出的哈希写回新实例同名账号 UPDATE oc_users SET password = '<旧实例导出的哈希>' WHERE uid = '<账号>';`

执行后旧密码原样可登，两个家人账号全部无感。这一步的通用启示：看起来必须重置的东西，先看底层存的是什么再下结论——存的是哈希且算法没变，就能搬。

结果：目标逐条对账

数据零丢失：文件逐一对账一致，回收站/版本历史这类 ephemeral 数据明确不迁（旧实例本就没启用几年，提前盘过损失面）
503 根治：新栈属主正确，服务健康检查全绿
版本最新：35 版，官方当前大版本
家人无感：旧密码直登，App 连新域名即用 ✓

全部达标。唯一主动放弃的是设备访问令牌——安全起见不迁，各设备重新登录一次。

意外收获：一次上游发布事故的考古

迁移完成后追 35.0.3 补丁版，结果所有镜像源一致报"找不到 amd64 清单"。这个现象值得较真，因为"镜像拉不到"至少有三种可能：镜像站拒答（换源可解）、缓存残缺（等同步可解）、上游发布事故（只能等修复）——处置完全不同。

定性手段是绕过 docker 客户端直接问 registry API：拿匿名 token、带 Accept 头拉 manifest list、数 platforms。结果两个独立镜像源给出同一个答案——35.0.3 的清单是空的（{"manifests":[]}，一个平台都没有），而 35.0.2 是完整的八平台清单。两个独立源同见空清单即为上游实锤：官方把版本号推了、镜像没推上来，全球任何机器此刻都拉不到，不是我方问题。

再验证一层：latest 标签的摘要和本地不同，把新摘要拉下来读容器里的版本声明——35.0.2、构建时间早于 35.0.3 发布日，证明 latest 只是重建、没有藏新版。结论：35.0.2 就是当前真实存在的最新版，我的实例已在最新上。

顺手处理一个隐患：compose 原来写 nextcloud:latest——Nextcloud 不支持跨大版本升级，latest 意味着上游哪天发 36，一次 pull 就把实例推进不支持的场景。改为钉大版本 tag（nextcloud:35），35 代内的补丁自动跟、跨代升级必须显式决策。上游修复 35.0.3 后，一条 docker compose pull && up -d 完成，其余零改动。