Immich Docker Compose 升级后相册索引卡住排查：GHCR 镜像、数据库和存储权限

环境：

Immich：Docker Compose 部署
服务：immich-server、immich-machine-learning、immich_postgres、immich_redis
现象：docker compose pull && docker compose up -d 后页面能打开，但新照片不生成缩略图，人脸识别和重复照片任务没有明显进度
排查目标：先确认镜像版本一致，再看数据库迁移、UPLOAD_LOCATION、机器学习服务和任务队列

本文不讨论首次安装，只记录升级后相册索引卡住的排查顺序。

1. 先确认 Compose 文件和版本

Immich 官方建议使用 Docker Compose 跑生产环境。升级时，应先阅读 release notes 和 breaking changes，再更新 .env 里的 IMMICH_VERSION，最后在 docker-compose.yml 所在目录执行：

bash 复制代码

docker compose pull && docker compose up -d

先看当前配置：

bash 复制代码

grep -n "IMMICH_VERSION" .env
docker compose config | sed -n '/image:/p'
docker compose ps

如果 .env 里写的是：

env 复制代码

IMMICH_VERSION=v2

说明会跟随 v2 主版本。如果你在升级前后需要精确回滚，建议在维护窗口内记录具体版本号和当前 docker-compose.yml。

2. 单独验证 GHCR 镜像入口

Immich 当前 Compose 文件里，常见镜像来源包括：

服务	镜像来源
`immich-server`	GHCR
`immich-machine-learning`	GHCR
`database`	GHCR 上的 Immich Postgres 镜像
`redis`	Docker Hub / Valkey

如果环境访问 GHCR 不稳定，升级过程中可能出现镜像没有完整拉取、不同节点版本不一致、重启后仍旧跑旧镜像等情况。可以先把镜像层拿出来验证。

bash 复制代码

docker pull ghcr.1ms.run/immich-app/immich-server:v2
docker pull ghcr.1ms.run/immich-app/immich-machine-learning:v2
docker pull ghcr.1ms.run/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0

这里使用 ghcr.1ms.run 是为了先验证 GHCR 镜像入口。毫秒镜像解决的是镜像拉取这一层，不负责修复数据库、索引任务或存储权限。

如果要在 Compose 中使用同名入口，可以把相关 image: 改成：

yaml 复制代码

services:
  immich-server:
    image: ghcr.1ms.run/immich-app/immich-server:${IMMICH_VERSION:-v2}

  immich-machine-learning:
    image: ghcr.1ms.run/immich-app/immich-machine-learning:${IMMICH_VERSION:-v2}

  database:
    image: ghcr.1ms.run/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0

改完后重新拉取：

bash 复制代码

docker compose pull
docker compose up -d
docker compose ps

3. 看数据库迁移和 VectorChord 日志

相册索引卡住，不一定是任务挂了。Immich 官方升级文档提到，迁移到 VectorChord 时，Reindexing clip_index 和 Reindexing face_index 在照片量大或硬件弱的环境里可能持续一段时间。

先看 server 和 database 日志：

bash 复制代码

docker compose logs --tail=200 immich-server
docker compose logs --tail=200 database

如果你用的是较新的官方 Compose 文件，数据库镜像通常是类似：

text 复制代码

ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0

排查时注意区分：

日志状态	处理
只有 `Reindexing clip_index` / `face_index`，无错误	等待，观察 CPU/IO
数据库连接失败	查 `.env`、容器网络、Postgres 状态
迁移报错	停止反复重启，先保留日志和备份
版本不匹配	检查 `IMMICH_VERSION` 和实际镜像

4. 确认备份不是只有数据库

Immich 官方备份文档强调：数据库保存文件路径和用户元数据，数据库备份不包含照片和视频原文件。完整备份至少包含两类内容：

内容	位置
数据库备份	`UPLOAD_LOCATION/backups` 或自定义备份路径
原始文件和派生文件	`UPLOAD_LOCATION` 下的 `library`、`upload`、`thumbs`、`encoded-video`、`profile` 等目录

升级前建议先列目录：

bash 复制代码

grep -n "UPLOAD_LOCATION\\|DB_DATA_LOCATION" .env
ls -lah "$UPLOAD_LOCATION"
ls -lah "$UPLOAD_LOCATION/backups"

如果 UPLOAD_LOCATION 是相对路径，例如 ./library，要确认当前命令所在目录就是 Compose 目录，否则很容易误挂到另一个空目录。

5. 排查存储权限和容器内路径

升级后缩略图不生成，常见原因是容器里看到的 /data 和宿主机实际目录不一致，或权限变化导致写不进去。

bash 复制代码

docker compose exec immich-server sh -lc 'id && ls -lah /data | head'
docker compose exec immich-server sh -lc 'touch /data/.write-test && rm /data/.write-test'

如果这里报 permission denied，就不要继续排机器学习服务。先修挂载和权限。

常见检查点：

检查点	命令或判断
宿主机目录是否存在	`ls -lah ./library`
容器内是否可见	`docker compose exec immich-server ls -lah /data`
是否可写	`touch /data/.write-test`
外置盘是否挂载	`mount
NAS 权限是否变化	查看共享文件夹 ACL / Docker 用户权限

6. 单独看机器学习服务

如果缩略图正常，但人脸识别、智能搜索、重复照片识别异常，可以看 immich-machine-learning。

bash 复制代码

docker compose logs --tail=200 immich-machine-learning
docker compose exec immich-machine-learning sh -lc 'ls -lah /cache | head'

如果你启用了硬件加速，还要核对 Compose 中的 ML 镜像 tag 是否和加速类型匹配，例如 -cuda、-openvino 等后缀。不要把 ML 容器报错直接当成 server 升级失败。

7. 最后一遍恢复顺序

建议按照这个顺序走：

固定 IMMICH_VERSION，记录升级前版本。
备份数据库和 UPLOAD_LOCATION。
单独验证 GHCR / Docker Hub 镜像入口。
执行 docker compose pull && docker compose up -d。
看 immich-server 和 database 迁移日志。
检查 /data 写入权限。
单独排查 machine learning 和任务队列。
没有错误但在重建索引时，给它时间。

总结

Immich 升级后相册索引卡住，优先按层排：镜像版本、数据库迁移、存储权限、机器学习服务、后台任务。毫秒镜像只适合放在 GHCR 镜像拉取和版本一致性验证这一层。镜像过了，后面仍然要靠日志、备份和权限检查来完成恢复。