static-ffmpeg 镜像文档

镜像概述和主要用途

static-ffmpeg 是一个多架构 Docker 镜像，包含构建为强化静态 PIE 二进制文件的 ffmpeg 和 ffprobe，无外部依赖，可与任何基础镜像一起使用。

核心功能和特性

• 静态编译的 ffmpeg 和 ffprobe 二进制文件，无需外部依赖
• 包含丰富的编解码器和过滤器支持
• 支持多种架构（amd64 和 arm64）
• 二进制文件启用了多种安全强化特性
• 内置字体支持，可直接用于文本渲染等功能
• 支持 TLS 加密连接

使用场景和适用范围

• 作为基础镜像中的工具集成
• 视频/音频处理自动化工作流
• 开发环境中的多媒体处理工具
• 容器化应用中的媒体处理组件
• 需要在多种架构上运行的媒体处理任务

详细使用方法和配置说明

获取镜像

可使用 Docker Hub 上的 mwader/static-ffmpeg 镜像，或自行构建：

docker pull mwader/static-ffmpeg:7.1.1

在 Dockerfile 中使用

COPY --from=mwader/static-ffmpeg:7.1.1 /ffmpeg /usr/local/bin/
COPY --from=mwader/static-ffmpeg:7.1.1 /ffprobe /usr/local/bin/

直接运行

# 使用 ffmpeg 转换文件格式
docker run -i --rm -u $UID:$GROUPS -v "$PWD:$PWD" -w "$PWD" mwader/static-ffmpeg:7.1.1 -i file.wav file.mp3

# 使用 ffprobe 分析媒体文件
docker run -i --rm -u $UID:$GROUPS -v "$PWD:$PWD" -w "$PWD" --entrypoint=/ffprobe mwader/static-ffmpeg:7.1.1 -i file.wav

作为 Shell 别名

alias ffmpeg='docker run -i --rm -u $UID:$GROUPS -v "$PWD:$PWD" -w "$PWD" mwader/static-ffmpeg:7.1.1'
alias ffprobe='docker run -i --rm -u $UID:$GROUPS -v "$PWD:$PWD" -w "$PWD" --entrypoint=/ffprobe mwader/static-ffmpeg:7.1.1'

支持的库

• fontconfig
• gray (完整灰度支持)
• iconv (来自 musl)
• lcms2
• libaom
• libaribb24
• libass
• libbluray
• libdav1d
• libdavs2
• libfdk-aac (仅在构建时显式启用，见下文)
• libfreetype
• libfribidi
• libgme
• libgsm
• libharfbuzz
• libjxl
• libkvazaar
• libmodplug
• libmp3lame
• libmysofa
• libopencore
• libopenjpeg
• libopus
• librabbitmq
• librav1e
• librsvg
• librtmp
• librubberband
• libshine
• libsnappy
• libsoxr
• libspeex
• libsrt
• libssh
• libsvtav1
• libtheora
• libtwolame
• libuavs3d
• libva
• libvidstab
• libvmaf
• libvo-amrwbenc
• libvorbis
• libvpl
• libvpx
• libvvenc
• libwebp
• libx264
• libx265 (支持 10 位和 12 位的多库版本)
• libxavs2
• libxevd
• libxeve
• libxml2
• libxvid
• libzimg
• libzmq
• openssl
• 以及所有原生 ffmpeg 编解码器、格式和过滤器等

镜像中的文件

• /ffmpeg - ffmpeg 二进制文件
• /ffprobe - ffprobe 二进制文件
• /doc - 文档
• /versions.json - 包含 ffmpeg 和库构建版本的 JSON 文件
• /etc/ssl/cert.pem - CA 证书，用于直接运行镜像时的 -tls_verify 1 -ca_file /etc/ssl/cert.pem
• 字体、fontconfig 配置和预填充缓存:
  • /etc/fonts
  • /usr/share/fonts
  • /usr/share/consolefonts
  • /var/cache/fontconfig

镜像标签

• latest - 最新的主分支构建
• MAJOR.MINOR.PATCH[-BUILD] - 特定版本的 FFmpeg，其中 -BUILD 表示该版本的附加构建，用于添加或修复功能

安全性

二进制文件启用了多种强化特性，但即使在容器内使用，仍建议以非 root 用户身份运行，特别是处理不受信任的输入文件时。

libfdk-aac

由于许可证问题，默认情况下 Docker 镜像不包含 libfdk-aac。可通过向构建参数 ENABLE_FDKAAC 传递非空值来构建包含 libfdk-aac 的 Docker 镜像，示例如下：

docker build --build-arg ENABLE_FDKAAC=1 . -t my-ffmpeg-static:latest

字体使用（SVG 或绘制文本过滤器等）

镜像预装了一些基本字体 (font-terminus font-inconsolata font-dejavu font-awesome)，可直接运行镜像时使用。如果将二进制文件复制到其他镜像中，则需要自行安装字体。具体方法因发行版而异，通常需要查找字体包以及如何让 fontconfig 识别它们：

• Alpine Linux 参见 [***]
• Debian/Ubuntu 参见 [***]

自定义字体目录

假设要构建一个需要 ffmpeg 和 ffprobe 二进制文件的应用 Docker 镜像，并希望有一个专用目录存储字体，例如 /app/fonts。可按以下步骤操作：

1. 添加包含自定义字体目录的配置文件到镜像中。将文件 50-custom.conf 添加到 /etc/fonts/conf.d 目录，包含供 Fontconfig 使用的附加 /app/fonts 目录：

COPY <<EOF /etc/fonts/conf.d/50-custom.conf
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
<fontconfig>
        <dir>/app/fonts</dir>
</fontconfig>
EOF

2. 复制 ffmpeg（和 ffprobe）二进制文件：

COPY --from=mwader/static-ffmpeg:7.1.1 /ffmpeg /usr/bin/
COPY --from=mwader/static-ffmpeg:7.1.1 /ffprobe /usr/bin/

3. 确保镜像中存在 /app/fonts 目录：

WORKDIR /app

RUN <<EOT bash
  set -ex
  mkdir -p ./fonts
EOT

完整示例：

FROM python:3.11-slim-bookworm AS base

COPY <<EOF /etc/fonts/conf.d/50-custom.conf
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
<fontconfig>
        <dir>/app/fonts</dir>
</fontconfig>
EOF

FROM base as ffmpeg

COPY --from=mwader/static-ffmpeg:7.1.1 /ffmpeg /usr/bin/
COPY --from=mwader/static-ffmpeg:7.1.1 /ffprobe /usr/bin/

FROM ffmpeg AS app

WORKDIR /app

RUN <<EOT bash
  set -ex
  mkdir -p ./fonts
EOT

构建并运行容器，将卷挂载到 /app/fonts：

docker build -t ffmpeg-fonts-image .
docker run -i --rm \
  -u "$UID:$GROUPS" \
  -v "$PWD:$PWD" \
  -v "$PWD/fonts:/app/fonts" \
  -v "$PWD/cache:/var/cache/fontconfig" \
  -w "$PWD" \
  ffmpeg-fonts-image \
  ffmpeg -v debug -y -f lavfi -i 'color=white,drawtext=text=Test:fontfile=Arial' -t 1s /app/output.mp4

TLS 支持

二进制文件内置 TLS 支持，但默认情况下 ffmpeg 当前不进行证书验证。要启用验证，需要使用 -tls_verify 1 和 -ca_file /path/to/cert.pem 运行 ffmpeg：

• Alpine Linux 证书路径：/etc/ssl/cert.pem
• Debian/Ubuntu：安装 ca-certificates 包后，证书路径为 /etc/ssl/certs/ca-certificates.crt

已知问题和解决方法

多架构和 arm64 支持

从版本 5.0.1-3 开始，Docker Hub 镜像为多架构镜像，支持 amd64 和 arm64。

从镜像中复制二进制文件

将 ffmpeg 和 ffprobe 复制到当前目录：

docker run --rm -v "$PWD:/out" $(echo -e 'FROM alpine\nCOPY --from=mwader/static-ffmpeg:7.1 /ff* /\nENTRYPOINT cp /ff* /out' | docker build -q -)

查看镜像构建版本信息

docker run --rm mwader/static-ffmpeg -v quiet -f data -i versions.json -map 0 -c copy -f data -

DNS 解析错误

可能会遇到 "Name does not resolve" 错误，这可能是因为主机名解析为过多 IP 地址，无法放入 DNS UDP 数据包（通常为 512 字节），导致响应被截断。通常客户端应切换到 TCP 并重做查询。这应该只在该镜像的 6.0-1 或更早版本中出现，这些版本使用 musl libc 1.2.3 或更早版本。

TLS 数字信封例程错误

可能会看到 "[tls @ 0x7f80c8ec3800] error:030000A9:digital envelope routines::unknown option" 错误。这可能是因为 static-ffmpeg 二进制文件中静态链接的 openssl 版本与文件系统中的（可能是发行版修改的 openssl）配置文件不兼容。该错误是关于 openssl 遇到未知选项。

可能的解决方法：

• 向 openssl 配置添加 config_diagnostics = 0 以忽略未知选项，但有忽略实际问题的风险
• 使用 ffmpeg 选项 -reconnect_on_network_error true 忽略错误，但仍会警告

版本控制

版本信息可在 Dockerfile 中查看。通常，master 分支应该包含最新稳定版本的 ffmpeg 和相关库。版本通过 bump 自动保持最新。