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

1. 问题现象

用 Docker Compose 在 NAS 或 Linux 小主机上部署 Jellyfin 后，容器启动正常，8096 页面也能访问，但添加媒体库后一直扫描不到文件。

常见表现：

Jellyfin 页面可以打开。
docker compose ps 显示容器运行中。
后台添加媒体库后内容为空。
日志里没有明显启动失败。
宿主机目录里确实有媒体文件。

这类问题优先排查 Docker volume、容器内路径和权限，不要一开始就重装 Jellyfin。

2. 最小 Compose 示例

先使用最小配置验证：

yaml 复制代码

services:
  jellyfin:
    image: docker.1ms.run/linuxserver/jellyfin:latest
    container_name: jellyfin
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
    volumes:
      - ./config:/config
      - /volume1/media/movies:/data/movies:ro
      - /volume1/media/tv:/data/tv:ro
    ports:
      - "8096:8096"
    restart: unless-stopped

启动：

bash 复制代码

docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 jellyfin

这里使用 docker.1ms.run/linuxserver/jellyfin:latest 是为了先减少镜像拉取变量。如果有企业内网仓库，也可以替换成内部镜像地址。

3. 宿主机路径是否存在

先确认 NAS 上的真实路径：

bash 复制代码

ls -lah /volume1/media
ls -lah /volume1/media/movies
pwd

注意：NAS 图形界面显示的共享目录名，不一定等于 SSH 里的真实路径。

外接盘、NFS、SMB、加密目录尤其容易出现路径不一致。

4. 容器内路径是否能看到文件

进入容器：

bash 复制代码

docker compose exec jellyfin sh
ls -lah /data
ls -lah /data/movies

如果 /data/movies 为空，问题还在 volume 层。

检查 Compose：

bash 复制代码

docker compose config | grep -A 10 volumes

正确逻辑是：

text 复制代码

宿主机路径 /volume1/media/movies
挂载到容器 /data/movies
Jellyfin 后台填写 /data/movies

不要在 Jellyfin 后台填写宿主机路径 /volume1/media/movies。

5. PUID / PGID 与目录权限

LinuxServer 风格镜像常用 PUID、PGID 指定容器运行用户。

查看宿主机用户：

bash 复制代码

id

查看目录权限：

bash 复制代码

stat -c "%u:%g %a %n" /volume1/media/movies
ls -lah /volume1/media/movies | head

媒体目录建议给读权限：

bash 复制代码

chmod -R a+rX /volume1/media/movies
chmod -R a+rX /volume1/media/tv

配置目录需要写权限：

bash 复制代码

chown -R 1000:1000 ./config

不建议直接 chmod -R 777，尤其是 NAS 多用户目录。

6. NAS 重启后的挂载顺序

如果 Jellyfin 之前正常，NAS 重启后突然空库，检查挂载顺序：

bash 复制代码

df -h
findmnt | grep media
mount | grep volume1

如果外接盘或网络挂载晚于 Docker，容器启动时看到的可能是空目录。

处理方式：

bash 复制代码

docker compose down
# 等存储挂载完成
docker compose up -d

长期方案是延迟启动容器，或让容器依赖存储挂载完成。

7. 硬件加速不要和空库混排

媒体库为空和播放卡顿不是同一个问题。

媒体库为空优先排查：

volume。
容器内路径。
权限。
挂载顺序。

播放卡顿再看硬解：

bash 复制代码

ls -lah /dev/dri

如需 Intel 核显硬解，再加：

yaml 复制代码

devices:
  - /dev/dri:/dev/dri

8. 排查表

现象	排查方向
容器启动但媒体库为空	Jellyfin 后台是否填写容器内路径
容器内 `/data/movies` 为空	Compose volume 宿主机路径是否正确
容器内能看到文件但扫描不到	权限、媒体库类型、文件名
NAS 重启后媒体库为空	存储挂载是否晚于 Docker
`docker compose pull` 慢	先排镜像源和网络
播放卡顿	硬解、转码、网络带宽

9. 推荐排查命令

bash 复制代码

docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 jellyfin

ls -lah /volume1/media/movies
docker compose exec jellyfin ls -lah /data/movies
stat -c "%u:%g %a %n" /volume1/media/movies
df -h
findmnt | grep media

10. 总结

Jellyfin Docker Compose 媒体库为空，常见原因不是 Jellyfin 本身，而是：

宿主机路径写错。
容器内路径填错。
容器用户没有权限。
NAS 存储挂载晚于容器启动。
镜像拉取或部署链路本身不稳定。

建议按"镜像 → volume → 容器内路径 → 权限 → 挂载顺序 → 应用配置"的顺序排查。