Docker容器内FFmpeg无法捕获UDP视频流帧的问题排查

云原生阿岚

2026-8-31

问题背景

需要通过以太网捕获视频帧，选用FFmpeg实现相关功能。迁移至Docker容器环境部署前，已在宿主机上完成功能验证，可正常捕获视频帧。

宿主机运行验证

宿主机执行以下命令可正常完成帧捕获：

ffmpeg -y -i udp://@:15004 -r 10 -frames:v 1 frame.png

正常运行输出如下：

ffmpeg version 4.2.4-1ubuntu0.1 Copyright (c) 2000-2020 the FFmpeg developers
  built with gcc 9 (Ubuntu 9.3.0-10ubuntu2)
  configuration: --prefix=/usr --extra-version=1ubuntu0.1 --toolchain=hardened --libdir=/usr/lib/x86_64-linux-gnu --incdir=/usr/include/x86_64-linux-gnu --arch=amd64 --enable-gpl --disable-stripping --enable-avresample --disable-filter=resample --enable-avisynth --enable-gnutls --enable-ladspa --enable-libaom --enable-libass --enable-libbluray --enable-libbs2b --enable-libcaca --enable-libcdio --enable-libcodec2 --enable-libflite --enable-libfontconfig --enable-libfreetype --enable-libfribidi --enable-libgme --enable-libgsm --enable-libjack --enable-libmp3lame --enable-libmysofa --enable-libopenjpeg --enable-libopenmpt --enable-libopus --enable-libpulse --enable-librsvg --enable-librubberband --enable-libshine --enable-libsnappy --enable-libsoxr --enable-libspeex --enable-libssh --enable-libtheora --enable-libtwolame --enable-libvidstab --enable-libvorbis --enable-libvpx --enable-libwavpack --enable-libwebp --enable-libx265 --enable-libxml2 --enable-libxvid --enable-libzmq --enable-libzvbi --enable-lv2 --enable-omx --enable-openal --enable-opencl --enable-opengl --enable-sdl2 --enable-libdc1394 --enable-libdrm --enable-libiec61883 --enable-nvenc --enable-chromaprint --enable-frei0r --enable-libx264 --enable-shared
  libavutil      56. 31.100 / 56. 31.100
  libavcodec     58. 54.100 / 58. 54.100
  libavformat    58. 29.100 / 58. 29.100
  libavdevice    58.  8.100 / 58.  8.100
  libavfilter     7. 57.100 /  7. 57.100
  libavresample   4.  0.  0 /  4.  0.  0
  libswscale      5.  5.100 /  5.  5.100
  libswresample   3.  5.100 /  3.  5.100
  libpostproc    55.  5.100 / 55.  5.100
[h264 @ 0x55ba0869d440] non-existing PPS 0 referenced
    Last message repeated 1 times
[h264 @ 0x55ba0869d440] decode_slice_header error
[h264 @ 0x55ba0869d440] no frame!
[h264 @ 0x55ba0869d440] non-existing PPS 0 referenced
    Last message repeated 1 times
[h264 @ 0x55ba0869d440] decode_slice_header error
[h264 @ 0x55ba0869d440] no frame!
[h264 @ 0x55ba0869d440] non-existing PPS 0 referenced
    Last message repeated 1 times
[h264 @ 0x55ba0869d440] decode_slice_header error
[h264 @ 0x55ba0869d440] no frame!
Input #0, mpegts, from 'udp://@:15004':
  Duration: N/A, start: 905.464878, bitrate: N/A
  Program 1 
    Stream #0:0[0x11]: Video: h264 (High) ([27][0][0][0] / 0x001B), yuv420p(progressive), 640x512, 60 fps, 60 tbr, 90k tbn, 120 tbc
    Stream #0:1[0x21]: Data: klv (KLVA / 0x41564C4B)
Stream mapping:
  Stream #0:0 -> #0:0 (h264 (native) -> png (native))
Press [q] to stop, [?] for help
Output #0, image2, to 'frame.png':
  Metadata:
    encoder         : Lavf58.29.100
    Stream #0:0: Video: png, rgb24, 640x512, q=2-31, 200 kb/s, 10 fps, 10 tbn, 10 tbc
    Metadata:
      encoder         : Lavc58.54.100 png
frame=    1 fps=0.0 q=-0.0 Lsize=N/A time=00:00:00.10 bitrate=N/A speed=1.23x    
video:399kB audio:0kB subtitle:0kB other streams:0kB global headers:0kB muxing overhead: unknown

Docker容器内异常表现

容器内执行完全相同的命令时，FFmpeg仅输出版本与编译配置信息后就停滞，始终无法进入帧捕获环节，运行输出如下：

vinden75lr           | ffmpeg version 4.3.4-0+deb11u1 Copyright (c) 2000-2021 the FFmpeg developers
vinden75lr           |   built with gcc 10 (Debian 10.2.1-6)
vinden75lr           |   configuration: --prefix=/usr --extra-version=0+deb11u1 --toolchain=hardened --libdir=/usr/lib/x86_64-linux-gnu --incdir=/usr/include/x86_64-linux-gnu --arch=amd64 --enable-gpl --disable-stripping --enable-avresample --disable-filter=resample --enable-gnutls --enable-ladspa --enable-libaom --enable-libass --enable-libbluray --enable-libbs2b --enable-libcaca --enable-libcdio --enable-libcodec2 --enable-libdav1d --enable-libflite --enable-libfontconfig --enable-libfreetype --enable-libfribidi --enable-libgme --enable-libgsm --enable-libjack --enable-libmp3lame --enable-libmysofa --enable-libopenjpeg --enable-libopenmpt --enable-libopus --enable-libpulse --enable-librabbitmq --enable-librsvg --enable-librubberband --enable-libshine --enable-libsnappy --enable-libsoxr --enable-libspeex --enable-libsrt --enable-libssh --enable-libtheora --enable-libtwolame --enable-libvidstab --enable-libvorbis --enable-libvpx --enable-libwavpack --enable-libwebp --enable-libx265 --enable-libxml2 --enable-libxvid --enable-libzmq --enable-libzvbi --enable-lv2 --enable-omx --enable-openal --enable-opencl --enable-opengl --enable-sdl2 --enable-pocketsphinx --enable-libmfx --enable-libdc1394 --enable-libdrm --enable-libiec61883 --enable-chromaprint --enable-frei0r --enable-libx264 --enable-shared
vinden75lr           |   libavutil      56. 51.100 / 56. 51.100
vinden75lr           |   libavcodec     58. 91.100 / 58. 91.100
vinden75lr           |   libavformat    58. 45.100 / 58. 45.100
vinden75lr           |   libavdevice    58. 10.100 / 58. 10.100
vinden75lr           |   libavfilter     7. 85.100 /  7. 85.100
vinden75lr           |   libavresample   4.  0.  0 /  4.  0.  0
vinden75lr           |   libswscale      5.  7.100 /  5.  7.100
vinden75lr           |   libswresample   3.  7.100 /  3.  7.100
vinden75lr           |   libpostproc    55.  7.100 / 55.  7.100

当前调用实现

目前通过如下C++代码调用FFmpeg命令，为快速验证版本，未做额外容错处理：

void VindenCamera::save_image_to_file(){
    std::string filename;

    SPDLOG_INFO("Creating image filename {}", filename);
    create_filename(filename);

    std::string ffmpeg_still_frame_command("ffmpeg -y -i udp://@:15004 -r 10 -frames:v 1 " + filename);

    system(ffmpeg_still_frame_command.c_str());
}

故障原因定位

核心原因是Docker默认网络隔离导致UDP流量无法进入容器：Docker默认使用bridge网络模式，不会自动转发UDP端口流量，FFmpeg打开UDP输入后一直等待流数据，因此卡在输入初始化阶段，不会继续输出流解析、帧捕获相关日志。
FFmpeg版本与参数兼容性问题：宿主机FFmpeg版本为4.2.4，容器内为4.3.4，不同版本对udp://@:port格式的地址解析、UDP接收缓冲区默认值存在差异，在容器网络环境下更容易出现收流失败、无限等待的问题。
调用逻辑缺少容错：直接使用system()执行命令没有捕获错误输出、没有设置超时，进程卡住时没有任何错误提示，提升了排查难度。

解决方案

优先调整Docker网络配置：启动容器时添加--network host参数，让容器共享宿主机网络栈，无需额外端口映射即可直接接收UDP流量，是UDP视频流场景下最稳定的配置，可避开bridge模式下UDP组播、端口转发的各类兼容问题。
若无法使用host网络，需显式映射UDP端口：启动容器时添加-p 15004:15004/udp参数，注意必须显式指定/udp，Docker默认仅映射TCP端口，不指定则UDP 15004的流量不会转发到容器内。
排查阶段先验证网络连通性：在容器内安装netcat或tcpdump，执行nc -ul 0.0.0.0 15004验证是否能收到UDP流量，先确认网络通畅再调试FFmpeg参数。
优化FFmpeg命令参数，避免无限等待：将原命令调整为ffmpeg -y -timeout 5000000 -i udp://0.0.0.0:15004?buffer_size=262144 -r 10 -frames:v 1 [输出文件名]，其中-timeout 5000000设置5秒接收超时，收不到流直接报错退出不会卡死；buffer_size=262144调大UDP接收缓冲区避免丢包；明确指定绑定地址0.0.0.0代替@，避开不同版本的地址解析差异。
优化C++调用逻辑，增加错误处理：

void VindenCamera::save_image_to_file(){
    std::string filename;
    SPDLOG_INFO("Creating image filename {}", filename);
    create_filename(filename);
    // 增加超时、缓冲区参数，重定向错误输出
    std::string ffmpeg_still_frame_command("ffmpeg -y -timeout 5000000 -i udp://0.0.0.0:15004?buffer_size=262144 -r 10 -frames:v 1 " + filename + " 2>&1");
    int ret = system(ffmpeg_still_frame_command.c_str());
    if(ret != 0){
        SPDLOG_ERROR("ffmpeg frame capture failed, return code: {}", ret);
    }
}

内容的提问来源于stack exchange，提问作者Ben Whitely