环境说明这次记录 2026-05-07 节后恢复 NAS Docker 服务时的一套排查流程。环境可以对应群晖 Container Manager、绿联 Docker、飞牛 OS、Unraid 或普通 Linux 小主机。示例服务Jellyfin影音库默认端口8096PhotoPrism照片入库和索引默认端口按 compose 配置Home Assistant智能家居默认端口8123Nginx/Caddy内网域名和反向代理Redis/MariaDB/Postgres部分服务的后台依赖问题现象dockercompose up-ddockercomposeps# 页面能打开但媒体库为空、照片不索引、Home Assistant 设备状态异常# 或者 docker compose pull 长时间停在 Pulling本文重点不只看镜像拉取而是按“镜像入口 - 挂载卷 - 权限 - 端口 - 反代 - 索引任务”的顺序排查。1. 先确认 Docker 和存储状态NAS 上跑 Docker最怕的不是某个服务报错而是底层存储已经满了。先检查磁盘、Docker 目录和容器状态。df-hdockersystemdfdockercomposeps如果docker system df显示镜像层、build cache 或 stopped container 占用很大先清理无用对象。生产或长期使用的 NAS 不要直接清理 volume先确认数据归属。dockerimagelsdockercontainerls-adockerbuilder prune2. 镜像拉取失败先拆服务预检节后恢复时很多 compose 文件会同时拉多个镜像。不要一上来就docker compose pull后等结果建议先拆核心服务。dockerpull docker.1ms.run/jellyfin/jellyfin:latestdockerpull docker.1ms.run/photoprism/photoprism:latestdockerpull ghcr.1ms.run/home-assistant/home-assistant:stabledockerpull docker.1ms.run/nginx:stable-alpinedockerpull docker.1ms.run/redis:7-alpine如果这些基础镜像可以单独拉取再执行dockercompose pulldockercompose up-d毫秒镜像1ms.run在这里适合作为多源镜像入口Docker Hub 用docker.1ms.runGHCR 用ghcr.1ms.run。它解决的是镜像层的可达性问题不替代后面的配置和权限排查。3. 用 compose 明确镜像和挂载路径下面是一个简化示例重点是镜像入口、端口、配置目录和媒体目录。真实环境要按自己的 NAS 路径调整。services:jellyfin:image:docker.1ms.run/jellyfin/jellyfin:latestcontainer_name:jellyfinrestart:unless-stoppedports:-8096:8096volumes:-/volume1/docker/jellyfin/config:/config-/volume1/media:/media:rophotoprism:image:docker.1ms.run/photoprism/photoprism:latestcontainer_name:photoprismrestart:unless-stoppedports:-2342:2342volumes:-/volume1/photos:/photoprism/originals-/volume1/docker/photoprism/storage:/photoprism/storagehomeassistant:image:ghcr.1ms.run/home-assistant/home-assistant:stablecontainer_name:homeassistantrestart:unless-stoppednetwork_mode:hostprivileged:truevolumes:-/volume1/docker/homeassistant:/config-/etc/localtime:/etc/localtime:ro注意两点Jellyfin 的媒体目录通常可以只读挂载避免服务误改原始媒体文件。PhotoPrism 的 originals、storage 目录要按官方文档区分尤其不要把 import 目录放到 originals 里面形成循环。4. 排查 bind mount 路径和权限Docker bind mount 依赖宿主机路径。NAS UI 里显示的共享文件夹不等于容器用户一定能读写。先看容器实际挂载dockerinspect jellyfin--format{{json .Mounts}}dockerinspect photoprism--format{{json .Mounts}}dockerinspect homeassistant--format{{json .Mounts}}再看宿主机目录ls-lah/volume1/dockerls-lah/volume1/medials-lah/volume1/photos如果日志里出现 permission denied、database is locked、cannot write、failed to scan directory就重点查这几项现象可能原因处理方向Jellyfin 媒体库为空/media挂载错层级或无读权限修正 compose 路径和目录权限PhotoPrism 不索引originals 无权限或存储目录不可写分开检查 originals 和 storageHome Assistant 配置丢失/config指向新目录修正配置挂载路径数据库启动失败DB 目录权限变更或磁盘满查磁盘、权限和日志5. 排查端口占用和反向代理先查 NAS 是否监听端口ss-lntpdockercomposeps典型端口Jellyfin8096PhotoPrism2342Home Assistant8123Nginx/Caddy80、443如果内网IP:端口可访问但域名访问 502先查反代容器dockerlogs--tail120nginxdockerlogs--tail120caddy不要把端口问题和证书问题混在一起排。顺序建议是容器端口 - NAS 防火墙 - 反代 upstream - 证书 - 路由器端口映射。6. PhotoPrism 索引和 Jellyfin 扫描不要急着判失败节后导入大量照片和视频时PhotoPrism 的索引任务会消耗 CPU、内存和磁盘 IO。Jellyfin 重新扫描媒体库时也可能先出现封面空白或元数据不完整。检查资源占用dockerstatsdockercompose logs--tail200photoprismdockercompose logs--tail200jellyfin如果日志没有持续报错只是 CPU 和 IO 较高可以先等索引任务结束。对性能一般的 NASRAW 照片、高码率视频和大量缩略图生成都会拖慢恢复速度。7. 一套可复用的排查顺序# 1. 看磁盘和 Docker 占用df-hdockersystemdf# 2. 拆核心镜像预检dockerpull docker.1ms.run/jellyfin/jellyfin:latestdockerpull docker.1ms.run/photoprism/photoprism:latestdockerpull ghcr.1ms.run/home-assistant/home-assistant:stable# 3. 启动并看状态dockercompose pulldockercompose up-ddockercomposeps# 4. 看日志和挂载dockercompose logs--tail120dockerinspect jellyfin--format{{json .Mounts}}# 5. 看端口和反代ss-lntpdockerlogs--tail120nginx常见问题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 拉取不稳定带来的干扰后续再看卷权限、端口和应用日志定位会快很多。