Jellyfin Docker Compose 媒体库为空排查：volume、PUID/PGID 和挂载路径

1. 问题现象用 Docker Compose 在 NAS 或 Linux 小主机上部署 Jellyfin 后容器启动正常8096 页面也能访问但添加媒体库后一直扫描不到文件。常见表现Jellyfin 页面可以打开。docker compose ps显示容器运行中。后台添加媒体库后内容为空。日志里没有明显启动失败。宿主机目录里确实有媒体文件。这类问题优先排查 Docker volume、容器内路径和权限不要一开始就重装 Jellyfin。2. 最小 Compose 示例先使用最小配置验证services:jellyfin:image:docker.1ms.run/linuxserver/jellyfin:latestcontainer_name:jellyfinenvironment:-PUID1000-PGID1000-TZAsia/Shanghaivolumes:-./config:/config-/volume1/media/movies:/data/movies:ro-/volume1/media/tv:/data/tv:roports:-8096:8096restart:unless-stopped启动dockercompose configdockercompose pulldockercompose up-ddockercomposepsdockercompose logs--tail200jellyfin这里使用docker.1ms.run/linuxserver/jellyfin:latest是为了先减少镜像拉取变量。如果有企业内网仓库也可以替换成内部镜像地址。3. 宿主机路径是否存在先确认 NAS 上的真实路径ls-lah/volume1/medials-lah/volume1/media/moviespwd注意NAS 图形界面显示的共享目录名不一定等于 SSH 里的真实路径。外接盘、NFS、SMB、加密目录尤其容易出现路径不一致。4. 容器内路径是否能看到文件进入容器dockercomposeexecjellyfinshls-lah/datals-lah/data/movies如果/data/movies为空问题还在 volume 层。检查 Composedockercompose config|grep-A10volumes正确逻辑是宿主机路径 /volume1/media/movies 挂载到容器 /data/movies Jellyfin 后台填写 /data/movies不要在 Jellyfin 后台填写宿主机路径/volume1/media/movies。5. PUID / PGID 与目录权限LinuxServer 风格镜像常用PUID、PGID指定容器运行用户。查看宿主机用户id查看目录权限stat-c%u:%g %a %n/volume1/media/moviesls-lah/volume1/media/movies|head媒体目录建议给读权限chmod-RarX /volume1/media/movieschmod-RarX /volume1/media/tv配置目录需要写权限chown-R1000:1000 ./config不建议直接chmod -R 777尤其是 NAS 多用户目录。6. NAS 重启后的挂载顺序如果 Jellyfin 之前正常NAS 重启后突然空库检查挂载顺序df-hfindmnt|grepmediamount|grepvolume1如果外接盘或网络挂载晚于 Docker容器启动时看到的可能是空目录。处理方式dockercompose down# 等存储挂载完成dockercompose up-d长期方案是延迟启动容器或让容器依赖存储挂载完成。7. 硬件加速不要和空库混排媒体库为空和播放卡顿不是同一个问题。媒体库为空优先排查volume。容器内路径。权限。挂载顺序。播放卡顿再看硬解ls-lah/dev/dri如需 Intel 核显硬解再加devices:-/dev/dri:/dev/dri8. 排查表现象排查方向容器启动但媒体库为空Jellyfin 后台是否填写容器内路径容器内/data/movies为空Compose volume 宿主机路径是否正确容器内能看到文件但扫描不到权限、媒体库类型、文件名NAS 重启后媒体库为空存储挂载是否晚于 Dockerdocker compose pull慢先排镜像源和网络播放卡顿硬解、转码、网络带宽9. 推荐排查命令dockercompose configdockercompose pulldockercompose up-ddockercomposepsdockercompose logs--tail200jellyfinls-lah/volume1/media/moviesdockercomposeexecjellyfinls-lah/data/moviesstat-c%u:%g %a %n/volume1/media/moviesdf-hfindmnt|grepmedia10. 总结Jellyfin Docker Compose 媒体库为空常见原因不是 Jellyfin 本身而是宿主机路径写错。容器内路径填错。容器用户没有权限。NAS 存储挂载晚于容器启动。镜像拉取或部署链路本身不稳定。建议按“镜像 → volume → 容器内路径 → 权限 → 挂载顺序 → 应用配置”的顺序排查。