环境说明

这次记录 2026-05-07 节后恢复 NAS Docker 服务时的一套排查流程。环境可以对应群晖 Container Manager、绿联 Docker、飞牛 OS、Unraid 或普通 Linux 小主机。

示例服务：

• Jellyfin：影音库，默认端口 8096
• PhotoPrism：照片入库和索引，默认端口按 compose 配置
• Home Assistant：智能家居，默认端口 8123
• Nginx/Caddy：内网域名和反向代理
• Redis/MariaDB/Postgres：部分服务的后台依赖

问题现象：

docker compose up -d
docker compose ps

# 页面能打开，但媒体库为空、照片不索引、Home Assistant 设备状态异常
# 或者 docker compose pull 长时间停在 Pulling

本文重点不只看镜像拉取，而是按“镜像入口 -> 挂载卷 -> 权限 -> 端口 -> 反代 -> 索引任务”的顺序排查。

1. 先确认 Docker 和存储状态

NAS 上跑 Docker，最怕的不是某个服务报错，而是底层存储已经满了。先检查磁盘、Docker 目录和容器状态。

df -h
docker system df
docker compose ps

如果 docker system df 显示镜像层、build cache 或 stopped container 占用很大，先清理无用对象。生产或长期使用的 NAS 不要直接清理 volume，先确认数据归属。

docker image ls
docker container ls -a
docker builder prune

2. 镜像拉取失败先拆服务预检

节后恢复时，很多 compose 文件会同时拉多个镜像。不要一上来就 docker compose pull 后等结果，建议先拆核心服务。

docker pull docker.1ms.run/jellyfin/jellyfin:latest
docker pull docker.1ms.run/photoprism/photoprism:latest
docker pull ghcr.1ms.run/home-assistant/home-assistant:stable
docker pull docker.1ms.run/nginx:stable-alpine
docker pull docker.1ms.run/redis:7-alpine

如果这些基础镜像可以单独拉取，再执行：

docker compose pull
docker compose up -d

毫秒镜像（1ms.run）在这里适合作为多源镜像入口：Docker Hub 用 docker.1ms.run，GHCR 用 ghcr.1ms.run。它解决的是镜像层的可达性问题，不替代后面的配置和权限排查。

3. 用 compose 明确镜像和挂载路径

下面是一个简化示例，重点是镜像入口、端口、配置目录和媒体目录。真实环境要按自己的 NAS 路径调整。

services:
  jellyfin:
    image: docker.1ms.run/jellyfin/jellyfin:latest
    container_name: jellyfin
    restart: unless-stopped
    ports:
      - "8096:8096"
    volumes:
      - /volume1/docker/jellyfin/config:/config
      - /volume1/media:/media:ro

  photoprism:
    image: docker.1ms.run/photoprism/photoprism:latest
    container_name: photoprism
    restart: unless-stopped
    ports:
      - "2342:2342"
    volumes:
      - /volume1/photos:/photoprism/originals
      - /volume1/docker/photoprism/storage:/photoprism/storage

  homeassistant:
    image: ghcr.1ms.run/home-assistant/home-assistant:stable
    container_name: homeassistant
    restart: unless-stopped
    network_mode: host
    privileged: true
    volumes:
      - /volume1/docker/homeassistant:/config
      - /etc/localtime:/etc/localtime:ro

注意两点：

• Jellyfin 的媒体目录通常可以只读挂载，避免服务误改原始媒体文件。
• PhotoPrism 的 originals、storage 目录要按官方文档区分，尤其不要把 import 目录放到 originals 里面形成循环。

4. 排查 bind mount 路径和权限

Docker bind mount 依赖宿主机路径。NAS UI 里显示的共享文件夹，不等于容器用户一定能读写。

先看容器实际挂载：

docker inspect jellyfin --format '{{json .Mounts}}'
docker inspect photoprism --format '{{json .Mounts}}'
docker inspect homeassistant --format '{{json .Mounts}}'

再看宿主机目录：

ls -lah /volume1/docker
ls -lah /volume1/media
ls -lah /volume1/photos

如果日志里出现 permission denied、database is locked、cannot write、failed to scan directory，就重点查这几项：

现象	可能原因	处理方向
Jellyfin 媒体库为空	/media 挂载错层级或无读权限	修正 compose 路径和目录权限
PhotoPrism 不索引	originals 无权限或存储目录不可写	分开检查 originals 和 storage
Home Assistant 配置丢失	/config 指向新目录	修正配置挂载路径
数据库启动失败	DB 目录权限变更或磁盘满	查磁盘、权限和日志

5. 排查端口占用和反向代理

先查 NAS 是否监听端口：

ss -lntp
docker compose ps

典型端口：

• Jellyfin：8096
• PhotoPrism：2342
• Home Assistant：8123
• Nginx/Caddy：80、443

如果内网 IP:端口 可访问，但域名访问 502，先查反代容器：

docker logs --tail=120 nginx
docker logs --tail=120 caddy

不要把端口问题和证书问题混在一起排。顺序建议是：容器端口 -> NAS 防火墙 -> 反代 upstream -> 证书 -> 路由器端口映射。

6. PhotoPrism 索引和 Jellyfin 扫描不要急着判失败

节后导入大量照片和视频时，PhotoPrism 的索引任务会消耗 CPU、内存和磁盘 IO。Jellyfin 重新扫描媒体库时，也可能先出现封面空白或元数据不完整。

检查资源占用：

docker stats
docker compose logs --tail=200 photoprism
docker compose logs --tail=200 jellyfin

如果日志没有持续报错，只是 CPU 和 IO 较高，可以先等索引任务结束。对性能一般的 NAS，RAW 照片、高码率视频和大量缩略图生成都会拖慢恢复速度。

7. 一套可复用的排查顺序

# 1. 看磁盘和 Docker 占用
df -h
docker system df

# 2. 拆核心镜像预检
docker pull docker.1ms.run/jellyfin/jellyfin:latest
docker pull docker.1ms.run/photoprism/photoprism:latest
docker pull ghcr.1ms.run/home-assistant/home-assistant:stable

# 3. 启动并看状态
docker compose pull
docker compose up -d
docker compose ps

# 4. 看日志和挂载
docker compose logs --tail=120
docker inspect jellyfin --format '{{json .Mounts}}'

# 5. 看端口和反代
ss -lntp
docker logs --tail=120 nginx

常见问题

1. 为什么镜像能拉下来，服务还是异常？

镜像只解决“容器镜像能不能到本机”。Jellyfin、PhotoPrism、Home Assistant 还依赖本地目录、数据库、端口、设备映射和反代入口。

2. NAS UI 里目录能打开，容器为什么读不到？

容器看到的是 bind mount 后的路径和权限，不是 NAS UI 的用户权限视角。需要用 docker inspect 和宿主机 ls -lah 一起看。

3. Home Assistant 用 Docker 时要注意什么？

Home Assistant Container 官方文档强调要有容器运行时，Docker Engine 需要满足版本要求。常见 compose 配置会使用 /config 挂载、host 网络和必要设备映射。

4. PhotoPrism 节后导入大量照片卡住怎么办？

先看日志和 docker stats，区分“索引正在跑”和“权限/存储报错”。大量 RAW、视频和缩略图生成需要时间，磁盘空间和 swap 也要检查。

总结

NAS Docker 服务节后恢复，建议按这条链路排：

磁盘空间 -> 镜像入口 -> compose 配置 -> bind mount 权限 -> 端口监听 -> 反代入口 -> 索引任务

镜像入口用毫秒镜像先跑通，可以减少 Docker Hub、GHCR 拉取不稳定带来的干扰；后续再看卷权限、端口和应用日志，定位会快很多。