Immich 版本升级与 v2 迁移 v3：改一个变量加两条命令

Immich 的升级体验在自托管软件里算一流的：常规升级两条命令，大版本迁移也主要是改一个环境变量。但「简单」不等于「可以裸奔」，这一页把动作和顺序写全。

常规小版本升级（v3.2 → v3.3 这种）

docker compose pull && docker compose up -d

第一条拉新镜像，第二条滚动重启容器。升级期间服务会短暂中断，照片库数据不受影响。升级完打开网页端，页脚或设置里能看到新版本号。

大版本迁移（v2 → v3）

第一步把 .env 里的版本线改掉：

- IMMICH_VERSION=v2
+ IMMICH_VERSION=v3

然后同样执行 docker compose pull && docker compose up -d。

v3 的破坏性变更，普通用户需要关心的其实很少：

• 大多数破坏性变更集中在 API 端点，只影响对接 Immich 接口的第三方工具——如果你只用官方网页端和手机 App，感知不到；
• 环境变量层面只移除了少数几个机器学习相关的变量，报错了就按启动日志的提示改；
• 向量扩展 pgvecto.rs 的支持被移除，还在用它的老库需要按官方迁移文档转到 VectorChord（新的部署默认就是 VectorChord，无需动作）；
• OAuth 配置更严格：默认拒绝非 HTTPS 的请求，自定义了 OAuth 的用户检查 allowInsecureRequests 配置；
• amd64 机器要求 x86-64-v2 指令集（约 2012 年后的 CPU 都满足），不满足的机器最高只能停在 v2.7.5。

升级前的三个必做动作

1. 确认数据库备份存在且是新的。自动备份的机制与位置见 数据库备份；升级恰好碰上数据库损坏的概率很低，但一旦发生，昨天的备份就是全部。
2. 看一下官方发布说明。每个版本有对应的博文，列了新特性和已知问题；迁移版说明（migration guide）单列了所有破坏性变更。
3. 挑空闲时间做。升级后首启会跑一些数据迁移任务，大库可能持续几十分钟，期间任务队列会很忙——这正是 任务队列 说的场景。

回滚与钉版本

对稳定性有洁知的用户，可以在 .env 里把 IMMICH_VERSION 钉死在具体版本号（如 v3.2.0），只在确认新版没问题后再手动前进——这是自托管相对云服务的自由所在。注意官方不支持降级数据库结构：一旦新版启动过数据库，直接换回旧镜像跑会报错，回滚意味着要 从备份恢复数据库。

想尝鲜的人

从 v3.0 起官方引入了发布候选（Release Candidate）机制：在管理后台的版本检查设置里把发布通道从「Stable」切到「Release candidate」，就能提前用上候选版并帮项目抓虫。生产库不建议，测试机随便玩。

升级顺利的话，服务器侧就齐活了——回到手机侧继续 开启自动备份。