🚀 使用 Docker Compose 部署 HandBrake 视频转码工具

本文档将指导你如何使用 Docker Compose 部署 jlesage/handbrake 容器，这是一个功能强大的开源视频转码工具，通过 Web 界面提供便捷的视频转换体验。

📖 项目简介

HandBrake 是一款适用于 Linux、Mac 和 Windows 的开源视频转码器。它可以处理大多数常见的视频文件和格式，包括消费者和专业摄像机创建的文件、手机和平板电脑等移动设备的文件、游戏和计算机屏幕录制的文件，以及 DVD 和蓝光光盘的文件。

docker-handbrake 特点： - Web 图形界面：通过现代 Web 浏览器访问 GUI（端口 5800），无需安装客户端 - 自动化转换：支持监视文件夹功能，自动处理放入的文件 - 硬件加速：支持 Intel Quick Sync Video (QSV) 等硬件编解码技术 - 多格式支持：利用 FFmpeg、x264 和 x265 等工具创建新的 MP4 或 MKV 视频文件

⚙️ 部署前准备

环境要求
- 已安装 Docker 和 Docker Compose
- 至少 2GB 内存（硬件加速可降低 CPU 占用）
- 足够的磁盘空间存储输入/输出文件
硬件加速检查（可选）对于 Intel 核显用户，检查是否支持 QSV：

ls /dev/dri

如果输出包含 renderD128 等设备，则支持硬件加速。

若需启用 Intel QSV/AMD 核显加速，需宿主机 CPU 支持（如 Intel 第 6 代及以上），并安装对应驱动：

# Ubuntu 安装 Intel 核显驱动示例 
sudo apt install -y intel-media-va-driver-non-free vainfo

mkdir -p ./config
mkdir -p /mnt/10t/videos/{watch,watch2,output}

🔧 配置 Docker Compose

创建 docker-compose.yml 文件，使用以下配置：

#version: '3.9'
services:
  handbrake:
    image: jlesage/handbrake:latest  # 官方镜像，自动更新最新版
    container_name: handbrake  # 容器名称，便于管理
    cap_add:
      - SYS_NICE  # 允许调整进程优先级，优化转码效率
    devices:  
      #- /dev/dri 
      - /dev/dri:/dev/dri   # 挂载核显设备（启用硬件加速，如 Intel QSV/AMD 核显）
    environment:
        TZ: Asia/Shanghai   # 时区（确保日志、时间显示正确）
        USER_ID: 0  # 运行用户 ID（0=root，避免权限问题，新手推荐）
        GROUP_ID: 0 # 运行用户组 ID（与 USER_ID 一致）
        #有网时设置↓
        LANG: zh_CN.UTF-8    # Web 界面语言（中文，避免乱码）
        PACKAGES_MIRROR: https://mirrors.aliyun.com/alpine/  # 国内软件源（加速依赖安装）

        KEEP_APP_RUNNING: 1   # 程序异常退出后自动重启（1=启用）
        #VNC_PASSWORD: 111   # 可选：设置 VNC 密码，不支持符号（需取消注释，建议修改）


        #CONTAINER_DEBUG: 1 # 是否开启Debug日志，1=是
        #WEB_AUDIO: 1 # 是否在GUI中启用声音，1=是
        #HANDBRAKE_DEBUG: 1   # 是否启用GUI和调试日志，1=是
        AUTOMATED_CONVERSION: 0  # 关闭自动转码（0=关闭，1=开启，新手建议先手动测试）
        #有网时设置↓  # 安装中文字体（1=启用，避免 Web 界面中文乱码）
        ENABLE_CJK_FONT: 1 # 是否安装WenQuanYi Zen Hei字体，如果不想GUI乱码就安装，1=是
        AUTOMATED_CONVERSION_OUTPUT_SUBDIR: SAME_AS_SRC    # 自动转码输出目录与源文件同目录
        ## 输出文件夹的子目录，可以填具体目录，填SAME_AS_SRC表示与源视频所在目录相同

        # 自动转码预设（H.265 编码，质量 22） 这是自建好的预设，在目录1下面，预设名'c_h265_22'
        AUTOMATED_CONVERSION_PRESET: "1/c_h265_22" #没问题，fps5个位数徘徊,10bit默认
        #AUTOMATED_CONVERSION_PRESET: "1/qsv_h265_22" #偶尔压出几倍于原视频的体积来，压制后体积符合预设。
        #AUTOMATED_CONVERSION_PRESET: "1/qsv22" #为了兼容性和体积与速度，用这个合适。压制后体积符合预设
        #UTOMATED_CONVERSION_PRESET: "1/c_22" #最低rf24不听使唤啊，怎么调都不行
        #AUTOMATED_CONVERSION_PRESET: "1/av1_30" #速度快，兼容性不好，不想用它啊终端硬解慢。
        #AUTOMATED_CONVERSION_PRESET: 'Hardware/H.265 QSV 1080p'  # Intel QSV 预设 #应该是自带的预设
        AUTOMATED_CONVERSION_KEEP_SOURCE: 1    # 自动转码后保留源文件（1=保留）
        #AUTOMATED_CONVERSION: 1
        AUTOMATED_CONVERSION_OUTPUT_DIR: '/output' # 自动转码输出根目录
        AUTOMATED_CONVERSION_CHECK_INTERVAL: 60    # 自动检查目录间隔（60秒）
      #- PERMS=true        # 是否重设/media权限
      #- UMASK=022         # 权限掩码
    ports:
      - '5800:5800'  # Web 界面端口：主机 5800 → 容器 5800
    volumes:
      - ./config:/config   # 配置持久化：保存设置、预设等
      - /mnt/10t/videos/watch:/watch  # 自动监控转码目录
      - /mnt/10t/videos/watch2:/watch2  # 手动转码源目录
      - /mnt/10t/videos/output:/output # 转码输出目录
      # 额外挂载（便于 Web 界面访问）
      - /mnt/10t/videos/watch:/storage/watch # 监控自动转码的目录
      - /mnt/10t/videos/watch2:/storage/watch2 # 待转码的目录
      - /mnt/10t/videos/output:/storage/output # 输出目录
      - /mnt/10t/videos/Anime_R18:/storage/media    # 额外视频源目录
    restart: always  # 容器退出后自动重启（确保服务稳定）
    #restart: unless-stopped
    logging:
        options:
            max-size: "5m"   # 单日志文件最大 5MB
            max-file: "5"    # 最多保留 5 个日志文件
    deploy:
     resources:
       limits:
        cpus: '12'  # 最多使用 12 个 CPU 核心
        memory: 5G  # 最多使用 5GB 内存


    #privileged: true
    #特权:真

关键配置说明：

硬件加速：devices 部分将 /dev/dri 设备暴露给容器，这是 Intel QSV 硬件加速的关键
中文支持：LANG: zh_CN.UTF-8 和 ENABLE_CJK_FONT: 1 确保界面正确显示中文
资源限制：deploy.resources.limits 控制容器使用的 CPU 和内存资源
存储映射：
./config：保存 HandBrake 配置和状态
/watch：监控自动转换的源文件目录
/output：存储转换后的视频文件
/storage/media：访问其他视频源的目录

配置项关键说明（新手必看）

配置项	作用与注意事项
`devices: /dev/dri:/dev/dri`	硬件加速核心配置：若宿主机无核显或驱动未安装，可注释此行（仅用 CPU 转码，速度较慢）。
`USER_ID: 0`/`GROUP_ID: 0`	root 权限可避免 90% 的权限问题（如无法读写视频文件），新手不建议修改。
`AUTOMATED_CONVERSION: 0`	默认关闭自动转码，建议先手动测试成功后再开启（改为 1），避免配置错误导致批量失败。
`AUTOMATED_CONVERSION_PRESET`	转码预设：`1/c_h265_22` 为 H.265 编码（高压缩率），`1/qsv_h265_22` 为 Intel 硬件加速（需核显支持），可根据需求选择。
`volumes` 目录挂载	所有目录需与宿主机实际路径一致，否则 Web 界面无法看到视频文件（常见问题！）。
`deploy.resources`	资源限制：根据宿主机配置调整，如 8 核 CPU 建议设 `cpus: '6'`，避免占满资源。

🚀 启动与验证

启动服务 bash docker compose up -d
验证状态

docker compose logs handbrake
#docker compose logs -f handbrake # 实时查看日志，按 Ctrl+C 退出

查看容器日志，确认无错误信息。

访问 Web 界面 打开浏览器，访问 http://你的服务器IP:5800，应该能看到 HandBrake 的 Web 界面。

🛠️ 基础配置与使用

界面中文化

如果界面仍显示乱码，可手动安装中文字体：

# 下载中文字体（如 Songti.ttc）
docker cp ./Songti.ttc handbrake:/usr/share/fonts/
docker exec -it --user root handbrake fc-cache -vf
docker compose restart handbrake

硬件加速配置

确保 Intel QSV 正常工作： 1. 确认 /dev/dri 设备正确映射 2. 在 HandBrake 的音频/视频编码器中选择 QSV 相关选项 3. 可使用预设 "Hardware/H.265 QSV 1080p"

转码预设选择

软件编码："1/c_h265_22" - 通用 H.265 编码
硬件编码："1/qsv_h265_22" - Intel QSV H.265 编码
平衡设置："1/qsv22" - 兼容性、体积与速度的平衡

🛠️ 基础配置与使用2

1. 界面基本操作（手动转码）

添加源文件：点击「源」→ 选择文件或目录（来自挂载的 /watch2、/media 等）。
选择转码预设：右侧「预设」列表提供多种方案（如 “Fast 1080p30” 适合快速压缩，“H.265 2160p” 适合 4K 视频），新手建议直接使用预设。
自定义参数（进阶）：
- 「视频」标签：调整编码（H.264/H.265）、质量（数值越小质量越高，建议 20-25）、帧率；
- 「音频」标签：选择音频轨、编码（AAC/MP3）、比特率；
- 「输出」标签：设置输出格式（MP4/MKV）、文件名和保存路径（默认 /output）。
开始转码：点击底部「开始编码」，在「队列」标签查看进度。

2. 启用自动转码（监控目录）

自动转码适合批量处理视频，配置步骤：

编辑 docker-compose.yml，将 AUTOMATED_CONVERSION: 0 改为 1；
（可选）调整预设：AUTOMATED_CONVERSION_PRESET 改为适合的方案（如 1/qsv22 适合 Intel 硬件加速）；
重启容器生效：docker compose restart；
测试：将视频放入 /mnt/10t/videos/watch 目录，1 分钟内（CHECK_INTERVAL=60）会自动触发转码，完成后输出到 /output 或源文件同目录（取决于 OUTPUT_SUBDIR 配置）。

3. 启用硬件加速（提升速度）

若宿主机有 Intel 核显（支持 QSV）或 AMD 核显，需确认：

devices: /dev/dri:/dev/dri 配置未被注释；
宿主机驱动已安装（如 Intel 驱动 intel-media-va-driver-non-free）；
转码时选择硬件加速预设（如 1/qsv_h265_22），或在「视频」标签中选择「编码器」为「H.265 (QSV)」。

🔄 维护与管理

监控转换进度

# 查看容器实时日志
docker compose logs -f handbrake

# 查看资源使用情况
docker stats handbrake

更新容器

# 拉取最新镜像
docker compose pull

# 重启服务
docker compose up -d

备份配置

# 备份 config 目录
tar -czf handbrake-config-backup.tar.gz ./config

❓ 常见问题排查

1. Web 界面无法访问

检查端口冲突：netstat -tunlp | grep 5800
验证防火墙设置
查看容器状态：docker compose ps

2. 中文显示乱码

确认 ENABLE_CJK_FONT: 1 已设置
手动安装中文字体（见"基础配置与使用"部分）
重启容器生效

3. 硬件加速不工作

确认宿主机支持 Intel QSV：ls /dev/dri
检查设备映射：docker exec handbrake ls /dev/dri
验证 HandBrake 日志中是否有 QSV 初始化信息

4. 转换速度慢

检查 CPU 和内存使用情况
确认硬件加速已启用
调整 AUTOMATED_CONVERSION_PRESET 使用硬件编码预设
增加资源限制（CPU/内存）

5. 权限问题

设置 USER_ID: 0 和 GROUP_ID: 0 使用 root 权限避免权限问题
确保挂载的目录有读写权限

通过以上配置和指南，你应该能够成功部署并使用 HandBrake Docker 容器进行高效的视频转码工作。

❓ 常见问题排查2

1. Web 界面中文乱码

原因：未启用 CJK 字体（ENABLE_CJK_FONT=0）或镜像源问题。
解决：确认 ENABLE_CJK_FONT=1 和 PACKAGES_MIRROR=https://mirrors.aliyun.com/alpine/ 配置正确，重启容器（会自动安装字体）。

2. 转码时提示 “无法打开源文件”

原因：源文件目录权限不足或挂载路径错误。
解决：
1. 执行 sudo chmod -R 777 /mnt/10t/videos 确保权限；
2. 确认 volumes 中挂载路径正确（如 /mnt/10t/videos/watch2:/watch2），重启容器。

3. 硬件加速不工作（转码速度慢）

原因：核显驱动未安装、/dev/dri 未挂载或未选择硬件编码器。
解决：
1. 安装驱动（如 Intel 驱动 sudo apt install intel-media-va-driver-non-free）；
2. 确认 devices: /dev/dri:/dev/dri 配置未被注释；
3. 转码时选择硬件加速预设（如 1/qsv_h265_22）。

4. 自动转码不触发（放入 /watch 的视频无反应）

原因：AUTOMATED_CONVERSION=0 未开启，或目录挂载错误、检查间隔未到。
解决：
1. 改为 AUTOMATED_CONVERSION=1，重启容器；
2. 确认 /mnt/10t/videos/watch 正确挂载（Web 界面可访问 /watch 目录）；
3. 等待 60 秒（CHECK_INTERVAL=60）或重启容器立即触发检查。

5. 转码后视频体积异常（过大 / 过小）

原因：转码预设参数不合适（如质量值设置过高 / 过低）。
解决：
- 降低质量值（如从 25 改为 22，数值越小质量越高、体积越大）；
- 更换预设（如 1/c_22 适合平衡体积和质量）。

通过以上步骤，新手可快速搭建 HandBrake 转码服务，实现视频格式转换和压缩。如需更复杂的转码需求（如批量添加水印、字幕），可探索 Web 界面的高级设置，或参考 jlesage/handbrake 官方文档。