wjz304/kodi

Kodi Docker 镜像

概述

基于Ubuntu系统构建，集成Kodi媒体中心（KMS/DRM终端模式）及可选音频支持（PulseAudio/PipeWire）。适用于具备独立显卡的Linux服务器，可直接通过DRM（直接渲染管理）接口输出视频，实现硬件加速播放。

核心功能与特性

• 硬件加速：支持通过DRM直接访问显卡，实现高效视频渲染
• 音频支持：兼容ALSA、PulseAudio和PipeWire多种音频后端
• 灵活配置：通过环境变量自定义时区、语言、渲染模式等
• 软件渲染回退：当硬件驱动不可用时，可切换至软件渲染模式
• 持久化存储：支持Kodi配置文件持久化，保留用户设置和媒体库

使用场景

• Linux服务器作为家庭媒体中心，直接连接显示设备
• 需要硬件加速的高清视频播放场景
• 支持远程控制（Web/JSON-RPC）和投屏（UPnP/DLNA、AirPlay）的媒体播放环境

环境变量配置

构建镜像

bash
docker build -t kodi:local kodi

运行示例

需确保宿主机已配置显卡驱动和音频后端（ALSA/PulseAudio/PipeWire），根据实际环境调整参数。

ALSA音频后端

bash
docker run --rm \
  -e TZ=Asia/Shanghai -e LANG=zh_CN.UTF-8 \
  --device /dev/dri --device /dev/snd --device /dev/input --cap-add SYS_ADMIN --cap-add SYS_RAWIO \
  -v /run/udev:/run/udev:ro \
  -v /tmp/kodi:/root/.kodi \
  -p 8080:8080 -p 9090:9090 -p 7000:7000 -p 9777:9777/udp \
  kodi:local

PulseAudio音频后端

bash
docker run --rm \
  -e TZ=Asia/Shanghai -e LANG=zh_CN.UTF-8 \
  --device /dev/dri --device /dev/input --cap-add SYS_ADMIN --cap-add SYS_RAWIO \
  -v /run/udev:/run/udev:ro \
  -e XDG_RUNTIME_DIR=/run/user/0 \
  -e PULSE_SERVER=unix:/run/user/0/pulse/native \
  -v /run/user/0/pulse/native:/run/user/0/pulse/native \
  -v /tmp/kodi:/root/.kodi \
  -p 8080:8080 -p 9090:9090 -p 9777:9777/udp \
  kodi:local

PipeWire音频后端

bash
docker run --rm -it \
  -e TZ=Asia/Shanghai -e LANG=zh_CN.UTF-8 \
  --device /dev/dri --device /dev/input --cap-add SYS_ADMIN --cap-add SYS_RAWIO \
  -v /run/udev:/run/udev:ro \
  -e XDG_RUNTIME_DIR=/run/user/0 \
  -v /run/user/0/pipewire-0:/run/user/0/pipewire-0 \
  -v /run/user/0/pulse/native:/run/user/0/pulse/native \
  -v /tmp/kodi:/root/.kodi \
  -p 8080:8080 -p 9090:9090 -p 9777:9777/udp \
  kodi:local

root用户下PulseAudio配置（如需）

仅在需要以root用户运行PulseAudio时执行：

bash
sudo -i
usermod -a -G pulse-access root
gpasswd -a root pulse
gpasswd -a root pulse-access
sed -i 's/^ConditionUser=!root/#ConditionUser=!root/' /usr/lib/systemd/user/pulseaudio.* 2>/dev/null
sed -i 's/^ConditionUser=!root/#ConditionUser=!root/' /usr/lib/systemd/user/pipewire.* /usr/lib/systemd/user/pipewire-pulse.* 2>/dev/null
systemctl --user enable pulseaudio
systemctl --user start pulseaudio

UPnP/DLNA与AirPlay投屏

Docker默认NAT/bridge模式不转发组播包，而AirPlay依赖mDNS/SSDP（UDP 5353/1900）及局域网广播，需使用--network host模式以支持投屏功能。

软件渲染回退方案

当硬件驱动不可用或VA-API初始化失败时，可通过以下环境变量启用软件渲染（性能会显著下降）：

• 设置LIBGL_ALWAYS_SOFTWARE=1强制软件渲染
• 配合MESA_LOADER_DRIVER_OVERRIDE=swrast指定swrast驱动

docker-compose配置示例

yaml
version: "3.8"

services:
  kodi:
    build: .
    image: wjz304/kodi:latest
    container_name: kodi
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
      - LANG=zh_CN.UTF-8
      # - LIBGL_ALWAYS_SOFTWARE=1            # 可选：强制软件渲染
      # - MESA_LOADER_DRIVER_OVERRIDE=swrast # 可选：指定软件驱动
      # - XDG_RUNTIME_DIR=/run/user/1000     # 可选：PulseAudio/PipeWire支持
    devices:
      - /dev/dri:/dev/dri          # 显卡直通（必须）
      - /dev/snd:/dev/snd          # 声卡直通
      - /dev/input:/dev/input      # 输入设备直通（键盘、鼠标等）
    volumes:
      - /run/udev:/run/udev:ro     # 设备信息读取
      - ./kodi:/root/.kodi         # Kodi配置持久化
      # - /run/user/1000/pulse/native:/run/user/1000/pulse/native # 可选：PulseAudio支持
      # - /run/user/1000/pipewire-0:/run/user/1000/pipewire-0     # 可选：PipeWire支持
    cap_add:
      - SYS_ADMIN                  # DRM设备操作权限
      - SYS_RAWIO                  # 硬件设备访问权限
    # network_mode: host           # 可选：UPnP/DLNA及AirPlay需启用
    ports:
      - 8080:8080                  # Web远程控制端口
      - 9090:9090                  # JSON-RPC远程控制端口
      - 9777:9777/udp              # Zeroconf服务发现端口
    shm_size: "1gb"
    security_opt:
      - seccomp=unconfined

注意事项

• 确保XDG_RUNTIME_DIR与音频socket路径与宿主机一致，且容器有访问权限
• 根据硬件配置选择是否启用软件渲染，避免不必要的性能损耗
• 使用UPnP/DLNA或AirPlay功能时需启用--network host网络模式
• 持久化配置目录权限需正确设置，避免数据丢失