3.1 privileged: true 的安全取舍#

privileged: true 等于把容器当半个 root 对待——能访问宿主机所有设备、加载内核模块、修改 sysctl。对 Kodi 这种只要用 GPU / 音频 / 输入设备的场景，属于过度授权。

推荐：先试用最小权限，实在不行再退回特权

对安全敏感时可以尝试用精确的 devices + group_add 替代 privileged：

1
# 去掉 privileged: true
2
devices:
3
  - /dev/dri:/dev/dri
4
  - /dev/snd:/dev/snd
5
  - /dev/input:/dev/input
6
group_add:
7
  - video
8
  - audio
9
  - input

如果改完 CEC、HDMI framebuffer 输出不正常，再退回 privileged: true——某些 DRM master 的场景确实需要特权才能拿到完整控制。

3.2 网络模式：bridge vs host#

Kodi 容器的网络模式是本文最值得展开的一处，两种模式各有明显的优缺点：

推荐用 host 模式，除非你的 NAS 上已经有其他服务占用了 8080 等端口。切换方式：

1
# 取消这一行的注释
2
network_mode: host
3
# 同时把 ports: 段整块删掉（host 模式下端口映射不起作用）

TIP

如果不知道宿主机 8080 有没有被占用，先 ss -lntp | grep 8080 确认一下，再决定用哪个模式。

3.3 设备挂载说明#

严格讲，设备类挂载更适合用 devices: 段声明（语义更准确），但在 privileged: true 下写在 volumes: 里也能正常工作，功能等价。

3.4 数据卷说明#

• ./data:/root：Kodi 的全部用户数据会写到容器内 /root，映射到宿主机当前目录下的 data 子文件夹（即 ~/.kodi：媒体库数据库、刮削缩略图、插件、设置都在这里）。

  CAUTION

  删除 ./data 目录等于重置 Kodi——所有媒体库、观看进度、插件配置全部丢失，需要重新扫库。建议定期备份这个目录。

• /vol1/1000/download/media:/media：FNOS 特有的存储路径约定：

  • /vol1/ 是第一个存储池的挂载点
  • 1000/ 是 UID 为 1000 的用户空间目录
  • download/media/ 是具体的媒体文件夹

  如果你不是 FNOS 用户，或者 UID 不同，替换成自己的媒体目录即可。通用写法：

  1
  - /mnt/media:/media
  2
  # 或
  3
  - /data/movies:/media

3.5 端口含义#

9777 必须加 /udp

9777 是 UDP 协议，Docker Compose 里 "9777:9777" 会默认当成 TCP 映射，结果是 Kore App 表面能连上但按键无效。务必写成 "9777:9777/udp"。

4.1 启动容器#

1
docker compose up -d
2
docker compose logs -f kodi

看到 Kodi is starting 或 Kodi 启动日志即表示容器跑起来了。

4.2 确认 HDMI 输出#

宿主机接好的电视 / 显示器上应该直接出现 Kodi 的启动画面（可能要先切到对应 HDMI 输入源）。黑屏时的排查：

• 宿主机 HDMI 线是否实际接着——FNOS 开机时如果能看到 bootloader 画面，说明硬件层 HDMI 工作正常
• docker compose logs kodi 有没有 DRM / framebuffer 相关错误
• FNOS 宿主机上有没有其他进程已经占用了显卡（部分 FNOS 版本自带桌面环境）

4.3 验证 VA-API 硬解#

第一步：容器内确认驱动可用

1
docker exec -it kodi vainfo

输出应该包含一堆 VAProfile* 条目（VAProfileH264*、VAProfileHEVCMain*、VAProfileVP9* 等）。若报 failed to initialize display 或 ERROR，说明 /dev/dri 权限或驱动没对上，检查 group_add 或退回 privileged: true。

第二步：在 Kodi 里启用 VAAPI

用电视遥控（或手机 Kore App、浏览器打开 http://<NAS IP>:8080）操作：

1. 设置 → 系统 → 设置级别 切到”专家级”
2. 设置 → 玩家 → 视频
3. 启用 “允许硬件加速 – VAAPI”

第三步：实际播放验证

1. 播放一段 4K HEVC 测试片源（Jellyfin 社区有免费测试片）
2. 播放时按 Ctrl+Shift+O 打开调试浮层
3. 看 VC:（video codec）那一行，出现 vaapi 即为硬解生效
4. 另开 SSH 终端跑 top，正常播放 4K HEVC CPU 占用应该 <30%；如果接近 100% 说明还在走软解

5.1 手机遥控（Kore，推荐）#

官方 Kore App（Android / iOS）是最顺手的方案：

1. Kodi 里 设置 → 服务 → 控制 → 启用”允许远程控制应用程序”和”允许其他设备的远程控制”
2. 手机装好 Kore，确保和 NAS 在同一局域网
3. Kore 首次启动会自动扫描（bridge 模式下可能扫不到，手动添加：IP 填 NAS 地址，端口 8080）
4. 首次连接 Kodi 在电视上弹出授权提示，确认即可

5.2 HDMI-CEC（电视遥控器）#

大多数支持 HDMI-CEC 的电视（Sony BRAVIA Sync / Samsung Anynet+ / LG SimpLink）：

1. 建议使用 network_mode: host，CEC 走底层设备通信、host 模式更稳
2. 电视设置里启用 HDMI-CEC 相关选项
3. Kodi 设置 → 系统 → 输入 → 外设 → 配置 CEC 适配器
4. 之后直接用电视遥控器的方向键 / OK / 返回键即可操作 Kodi

5.3 键盘 / 鼠标#

因为挂载了 /dev/input，插在 NAS USB 口的任意键盘、鼠标、无线遥控接收器（如飞利浦、Rii mini）都能开箱即用。