1. 项目概述与背景最近在折腾一个基于RK3568的嵌入式视频网关项目核心需求是在这个ARM平台上实现一个稳定、高效的流媒体服务。选型时我第一时间就想到了ZLMediaKit。这个由国内开发者维护的开源项目在流媒体服务领域口碑相当不错支持RTSP、RTMP、HTTP-FLV、HLS等多种协议性能强悍代码结构也清晰。但官方文档和社区讨论大多集中在x86_64的服务器环境关于如何完整地将其移植到ARM平台尤其是资源受限的嵌入式环境系统性的分享并不多。这恰恰是很多嵌入式音视频开发者会遇到的真实痛点手里有块性能不错的ARM板子想跑个流媒体服务却发现从依赖库编译到主工程构建每一步都可能踩坑。所以我决定把这次完整的ARM平台ZLMediaKit移植过程记录下来。这不仅仅是一个“编译通过”的教程更是一次针对嵌入式环境特点如交叉编译工具链、依赖库管理、系统资源优化的深度实践。无论你用的是树莓派、RK系列、全志还是其他ARM开发板只要你想在上面部署ZLMediaKit这篇内容都能提供一条清晰的路径和一堆“踩坑”后总结的经验。整个过程会涉及CMake交叉编译配置、第三方库如OpenSSL、libsrtp的ARM版本编译、以及针对ZLMediaKit本身的一些编译选项调优。我会尽量把“为什么这么做”讲清楚而不仅仅是罗列命令。2. 移植环境准备与核心思路2.1 开发环境搭建我的实验环境分为两部分宿主机Ubuntu 20.04 LTS x86_64和目标板RK3568运行基于ARM64的Linux系统。所有编译工作都在宿主机上完成通过交叉编译工具链生成ARM平台的可执行文件再拷贝到目标板上运行。这是嵌入式开发的常规操作。首先需要在宿主机上安装交叉编译工具链。不同的ARM芯片厂商可能提供不同的工具链常见的有Linaro的gcc-linaro、Arm官方arm-gnu-toolchain或者芯片厂商定制的工具链如瑞芯微提供的。我使用的是RK3568 SDK中提供的aarch64-linux-gnu-gcc。# 假设工具链已解压到 /opt/toolchain/ export TOOLCHAIN_PATH/opt/toolchain/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu export PATH$TOOLCHAIN_PATH/bin:$PATH export CCaarch64-linux-gnu-gcc export CXXaarch64-linux-gnu-g验证工具链是否安装成功aarch64-linux-gnu-gcc --version如果正确输出了版本信息且目标架构是aarch64说明工具链就绪。接下来是CMake。ZLMediaKit使用CMake作为构建系统我们需要确保宿主机上的CMake版本足够新建议3.10以上。Ubuntu自带的版本可能较旧可以通过官方仓库或源码升级。# 卸载旧版本如果需要 sudo apt remove cmake # 安装新版以3.22为例 wget https://github.com/Kitware/CMake/releases/download/v3.22.1/cmake-3.22.1-linux-x86_64.sh chmod x cmake-3.22.1-linux-x86_64.sh sudo ./cmake-3.22.1-linux-x86_64.sh --prefix/usr/local --skip-license cmake --version # 验证注意交叉编译的核心在于让CMake知道我们要为另一个架构ARM生成代码而不是为当前宿主机x86编译。这需要通过-DCMAKE_TOOLCHAIN_FILE指定工具链文件或者在CMake命令行中显式设置一系列以CMAKE_开头的变量。2.2 依赖库分析与获取ZLMediaKit并非完全独立它依赖一些第三方库来实现特定功能。在移植前我们必须理清这些依赖并为ARM平台准备好它们。主要依赖包括OpenSSL用于TLS/DTLS加密如HTTPS、WSS、SRTP加密传输。必须。libsrtp用于SRTP协议支持WebRTC流加密。如果不需要WebRTC功能可以不编译。ffmpeg用于转码、复用/解复用。ZLMediaKit本身不强制依赖ffmpeg其内置的代码解析器已支持常见格式H.264/H.265/AAC等。但如果你需要处理非常规编码或进行转码则需要集成ffmpeg。对于嵌入式场景为了节省资源我建议先不启用ffmpeg确保基础流媒体功能稳定后再考虑。其他如libuuid生成UUID、libssl已包含在OpenSSL中。我们的策略是先确保最小化系统能运行。因此第一阶段只编译必须的OpenSSL可选编译libsrtp为后续WebRTC留可能暂时排除ffmpeg。这些库都需要用相同的交叉编译工具链进行编译生成ARM平台的静态库.a或动态库.so。我倾向于使用静态链接这样生成的可执行文件是独立的部署到目标板时不需要额外拷贝一堆.so文件避免库版本冲突。缺点是文件体积会稍大。2.3 交叉编译通用流程与CMake工具链文件交叉编译第三方库的通用步骤可以归纳为configure-make-make install。但每个库的configure脚本参数不同。一个更规范、更CMake友好的方式是编写一个工具链文件Toolchain File。创建一个文件例如arm_toolchain.cmake内容如下# arm_toolchain.cmake set(CMAKE_SYSTEM_NAME Linux) set(CMAKE_SYSTEM_PROCESSOR aarch64) # 指定交叉编译器 set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc) set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g) # 指定目标环境根目录sysroot这里假设你的目标板根文件系统已提取到 /opt/sysroot/ # 如果没有精确的sysroot可以先不设置但编译某些库时可能会报找不到头文件。 # set(CMAKE_SYSROOT /opt/sysroot) # set(CMAKE_FIND_ROOT_PATH ${CMAKE_SYSROOT}) # 告诉CMake在sysroot中查找库和头文件 set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)这个文件定义了目标系统、编译器以及查找路径的规则。之后在编译任何库或ZLMediaKit本身时都可以通过-DCMAKE_TOOLCHAIN_FILE/path/to/arm_toolchain.cmake来启用交叉编译配置。3. 关键依赖库的交叉编译实战3.1 编译OpenSSL for ARMOpenSSL的编译相对标准但需要注意版本兼容性和配置参数。下载源码从官网或GitHub下载稳定版本如 openssl-1.1.1w。不建议使用太旧的版本。wget https://www.openssl.org/source/openssl-1.1.1w.tar.gz tar -xzf openssl-1.1.1w.tar.gz cd openssl-1.1.1w配置OpenSSL使用其自带的Configure脚本。关键是指定交叉编译器前缀、目标平台和安装路径。./Configure linux-aarch64 \ no-asm \ no-shared \ no-async \ --prefix/opt/arm_libs/openssl \ --cross-compile-prefixaarch64-linux-gnu-linux-aarch64目标平台。可以通过./Configure list查看所有支持平台。no-asm禁用汇编优化。某些ARM平台的汇编代码可能需要特定调整为求稳妥可以先禁用。如果后续性能测试成为瓶颈可以尝试开启并针对具体CPU型号优化。no-shared只生成静态库.a。简化部署。no-async禁用异步IO。在嵌入式Linux上这个特性可能依赖特定的系统调用先禁用避免潜在问题。--prefix指定安装目录。所有编译出的头文件和库文件将安装到此路径下。我习惯统一放在/opt/arm_libs/下管理。--cross-compile-prefix指定交叉编译器前缀。编译与安装make -j$(nproc) make install完成后检查/opt/arm_libs/openssl目录应该包含include和lib子目录lib下有libcrypto.a和libssl.a。实操心得OpenSSL的Configure脚本对交叉编译支持很好但参数一定要写对。no-asm和no-async是我在多次嵌入式移植中总结的“保平安”选项能极大减少因平台特定指令或系统调用缺失导致的运行时崩溃。性能损失在初期可以接受。3.2 编译libsrtp for ARMlibsrtp的编译更简单一些它支持CMake。下载源码git clone https://github.com/cisco/libsrtp.git cd libsrtp git checkout v2.5.0 # 选择一个稳定版本 mkdir build_arm cd build_armCMake配置与编译cmake .. -DCMAKE_TOOLCHAIN_FILE/path/to/arm_toolchain.cmake \ -DCMAKE_INSTALL_PREFIX/opt/arm_libs/libsrtp \ -DENABLE_OPENSSLON \ -DOPENSSL_ROOT_DIR/opt/arm_libs/openssl-DENABLE_OPENSSLON启用OpenSSL支持用于加密。-DOPENSSL_ROOT_DIR指向我们刚刚编译好的ARM版OpenSSL。CMake会从这里查找OpenSSL的头文件和库。编译与安装make -j$(nproc) make install安装后在/opt/arm_libs/libsrtp/lib下会生成libsrtp2.a。3.3 处理其他系统库像libuuid这类基础库通常目标板的根文件系统里已经存在。我们不需要在宿主机上交叉编译它只需要确保在交叉编译ZLMediaKit时链接器能找到它。这通常通过正确设置CMAKE_SYSROOT来实现链接器会自动到sysroot里的/usr/lib/aarch64-linux-gnu/等目录下去找。如果你目标板的根文件系统比较精简确实缺少某个库那就需要找到该库的源码用同样的交叉编译工具链编译并安装到sysroot或自定义的库目录中。4. ZLMediaKit工程交叉编译详解4.1 获取源码与初步配置克隆代码git clone https://github.com/ZLMediaKit/ZLMediaKit.git cd ZLMediaKit git submodule update --init # 重要更新第三方子模块如zltoolkit创建构建目录mkdir build_arm cd build_arm4.2 CMake配置参数解析这是最核心的一步所有依赖路径和编译选项都在这里指定。cmake .. -DCMAKE_TOOLCHAIN_FILE/path/to/arm_toolchain.cmake \ -DCMAKE_INSTALL_PREFIX/opt/arm_libs/zlm \ -DCMAKE_BUILD_TYPERelease \ -DENABLE_WEBRTCON \ -DOPENSSL_ROOT_DIR/opt/arm_libs/openssl \ -DOPENSSL_LIBRARIES/opt/arm_libs/openssl/lib \ -DOPENSSL_INCLUDE_DIR/opt/arm_libs/openssl/include \ -DSRTP_LIBRARY/opt/arm_libs/libsrtp/lib/libsrtp2.a \ -DSRTP_INCLUDE_DIR/opt/arm_libs/libsrtp/include \ -DENABLE_FFMPEGOFF逐条解释-DCMAKE_TOOLCHAIN_FILE指定交叉编译工具链文件这是告诉CMake进行交叉编译的“钥匙”。-DCMAKE_INSTALL_PREFIX指定ZLMediaKit的安装路径。-DCMAKE_BUILD_TYPERelease生成Release版本开启编译器优化去掉调试信息体积更小速度更快。-DENABLE_WEBRTCON启用WebRTC功能。这需要libsrtp。如果你确定不需要可以设为OFF以简化依赖。-DOPENSSL_XXX明确指定OpenSSL的库路径和头文件路径。即使设置了OPENSSL_ROOT_DIR有时CMake的查找逻辑也会出问题显式指定更保险。-DSRTP_LIBRARY和-DSRTP_INCLUDE_DIR指定libsrtp的静态库和头文件路径。注意这里直接指定了静态库文件.a的绝对路径。-DENABLE_FFMPEGOFF禁用ffmpeg。如前所述先保证核心功能。4.3 编译与问题排查执行cmake命令后仔细观察终端输出。成功的标志是看到类似这样的总结-- Configuring done -- Generating done -- Build files have been written to: /path/to/ZLMediaKit/build_arm并且没有红色的错误信息。如果出现错误最常见的是找不到依赖库。错误信息通常类似CMake Error at CMakeLists.txt:xxx (find_package): Could not find a package configuration file provided by OpenSSL...或者-- Could NOT find OpenSSL (missing: OPENSSL_LIBRARIES OPENSSL_INCLUDE_DIR)排查思路检查路径确认-DOPENSSL_ROOT_DIR等参数指向的路径是否正确该路径下是否有lib和include目录。检查库文件进入/opt/arm_libs/openssl/lib用file命令检查库文件架构。file libssl.a输出应为current ar archive并且ar t libssl.a | head -1查看第一个.o文件用file查看它应该是ARM架构。如果显示是x86-64说明你编译错了用的是宿主机编译器。手动指定变量就像我上面做的那样不使用find_package的自动查找而是直接通过-DOPENSSL_LIBRARIES和-DOPENSSL_INCLUDE_DIR强制指定。查看CMakeCachebuild_arm目录下会生成CMakeCache.txt文件搜索OPENSSL可以查看CMake最终找到和设置的变量值是很好的调试依据。配置成功后开始编译make -j$(nproc)编译过程会比较长耐心等待。最终在build_arm/release/linux/目录下这是ZLMediaKit默认的输出目录会生成可执行文件MediaServer。4.4 编译产物处理与优化编译完成后我们可以先检查一下生成的可执行文件是否为ARM架构file release/linux/MediaServer期望的输出应包含ELF 64-bit LSB executable, ARM aarch64。为了部署方便我们可以将可执行文件、配置文件以及可能需要的其他资源文件打包。# 创建发布目录 mkdir -p release/arm_package cp release/linux/MediaServer release/arm_package/ cp ../conf/config.ini.default release/arm_package/config.ini # 可以按需拷贝其他脚本或默认证书注意事项默认的config.ini配置文件是为高性能服务器设计的直接用于嵌入式板子可能不合适。需要重点关注以下配置项[api]部分考虑是否关闭或修改API接口的端口和权限。[ffmpeg]部分因为我们禁用了ffmpeg所以相关命令路径是无效的确保没有流触发转码逻辑。[hls]和[record]硬盘读写频繁如果板子使用SD卡或eMMC需谨慎开启避免影响寿命。[thread]线程池数量。嵌入式CPU核心数少如4核需要调低threads数量例如设置为2或3避免过度切换。[log]日志级别和文件大小。生产环境建议设为3WARN或4ERROR并合理设置文件大小和数量防止日志占满存储。5. 目标板部署、运行与性能调优5.1 文件传输与基础运行将打包好的arm_package目录拷贝到目标板RK3568上可以使用scp、nfs或U盘。# 在宿主机上操作 scp -r release/arm_package user192.168.1.xxx:/home/user/在目标板上进入该目录先尝试运行cd /home/user/arm_package ./MediaServer -c config.ini -d -c指定配置文件-d表示以守护进程模式运行。查看日志文件默认在./logs/目录下确认服务是否正常启动有无报错。常见的启动错误找不到动态库如果编译时链接了动态库我们没有因为用了静态链接会报error while loading shared libraries: libxxx.so.x: cannot open shared object file。静态链接可以避免此问题。权限问题MediaServer默认需要绑定1024以下的端口如80、443、554需要root权限。可以用sudo运行或者修改配置文件使用1024以上的端口。配置文件语法错误仔细检查config.ini特别是如果有修改确保格式正确。5.2 功能测试与验证服务启动后可以进行基础功能测试HTTP API测试ZLMediaKit提供了丰富的HTTP API。首先确认API端口默认是80。curl http://127.0.0.1/index/api/getStatistic如果返回JSON格式的服务器统计信息说明HTTP服务正常。推流测试使用OBS或ffmpeg向服务器推一个RTMP流。# 在另一台PC或目标板本机如果装了ffmpeg ffmpeg -re -i test.mp4 -c copy -f flv rtmp://目标板IP/live/stream1拉流测试用VLC或播放器播放以下地址RTMP:rtmp://目标板IP/live/stream1HTTP-FLV:http://目标板IP/live/stream1.flvHLS:http://目标板IP/live/stream1/hls.m3u8如果能正常播放说明整个流媒体通路是通的。5.3 性能调优与稳定性保障在资源受限的ARM平台上调优至关重要。内存优化连接数限制在config.ini的[general]部分设置maxStreamWaitMS流等待超时和streamNoneReaderDelayMS无观众流延迟关闭为较低值如5000ms及时释放无效连接占用的资源。缓冲区调整[protocol]部分下的modifyStamp、lowLatency等参数根据网络状况调整。嵌入式环境内网稳定可以适当减小缓冲区。CPU优化线程池如前所述根据CPU核心数设置[thread]下的threads。RK3568是4核A55我设置为3。禁用非必要功能再次确认ENABLE_WEBRTC、ENABLE_FFMPEG等编译开关只开启需要的。运行时通过配置文件关闭不用的协议如RTSP over TCP/UDP的选择。网络优化绑定特定网卡如果板子有多个网卡可以在config.ini中指定local_ip让服务只绑定在内部或指定的网卡上避免不必要的网络暴露和干扰。调整Socket缓冲区对于高并发场景可以适当增大[protocol]中的socketBufSize但需要平衡内存占用。存储优化日志轮转确保[log]中的logFileSize和logFileCount设置合理避免日志文件无限增长塞满存储。录制与截图除非必要否则关闭[record]和[snap]功能。开机自启为了产品化需要配置系统服务。创建一个systemd服务文件/etc/systemd/system/zlm.service[Unit] DescriptionZLMediaKit Stream Server Afternetwork.target [Service] Typesimple Userroot WorkingDirectory/opt/zlm ExecStart/opt/zlm/MediaServer -c /opt/zlm/config.ini Restarton-failure RestartSec5s [Install] WantedBymulti-user.target然后systemctl enable zlm启用即可。6. 常见问题排查与解决实录在实际移植和部署过程中我遇到了不少问题这里把典型问题和解决方案记录下来。6.1 编译阶段问题问题1CMake配置时提示找不到OpenSSL即使路径正确。排查这通常是CMake的FindOpenSSL模块在交叉编译环境下工作不正常。它可能找到了宿主机系统的OpenSSL。解决最直接有效的方法不使用find_package。在ZLMediaKit的CMakeLists.txt中如果你熟悉CMake可以修改或者更简单的通过命令行覆盖相关变量。正如我之前做的直接设置-DOPENSSL_LIBRARIES和-DOPENSSL_INCLUDE_DIR。有时还需要设置-DOPENSSL_CRYPTO_LIBRARY。在工具链文件arm_toolchain.cmake中设置set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)强制只在sysroot中查找包。问题2编译链接时报undefined reference touuid_generate‘等错误。排查缺少libuuid库。这是一个系统基础库。解决确保目标板sysroot中有这个库。可以到/opt/sysroot/usr/lib/aarch64-linux-gnu/下查找libuuid.so或libuuid.a。在CMake配置时显式指定uuid库的路径-DUUID_LIBRARIES/opt/sysroot/usr/lib/aarch64-linux-gnu/libuuid.a。如果sysroot里确实没有需要交叉编译libuuid通常来自util-linux源码包并安装到sysroot或自定义库目录。6.2 运行阶段问题问题3在目标板运行./MediaServer立即段错误Segmentation fault。排查这是最令人头疼的问题。原因可能很多编译出的二进制文件架构不对不是ARM。动态链接库不匹配虽然我们静态链接了主要库但glibc等系统库仍是动态链接。代码中存在平台相关的未定义行为如内存对齐、字节序。解决第一步用file命令确认二进制是ARM架构。第二步用ldd命令查看动态依赖即使静态链接了部分库。aarch64-linux-gnu-ldd MediaServer检查列出的.so文件是否都存在于目标板的/lib或/usr/lib目录下版本是否兼容。重点看libc.so.6,libpthread.so.0,libm.so.6,libdl.so.2,librt.so.1,libstdc.so.6等。如果目标板是精简系统可能缺少libstdc.so.6。解决方法是将交叉工具链里的对应库位于toolchain/lib/或toolchain/aarch64-linux-gnu/libc/lib/拷贝到目标板的/lib目录下。第三步使用GDB调试如果目标板有GDB。在编译ZLMediaKit时使用-DCMAKE_BUILD_TYPEDebug生成带调试信息的版本拷贝到板子上用GDB运行并bt查看崩溃时的堆栈能精确定位问题代码。第四步检查ZLMediaKit代码中是否有明显的平台相关代码。可以搜索#ifdef __x86_64__或#ifdef __aarch64__看是否有针对ARM平台的适配被遗漏。通常开源项目对ARM支持较好但特定功能如某些汇编优化可能没有。问题4推流正常但拉流延迟非常大超过10秒。排查这通常是协议配置或缓冲区设置问题。解决检查config.ini中[protocol]下的lowLatency是否开启。对于RTMP/HTTP-FLV开启低延迟模式。检查[hls]配置。HLS本身有切片延迟如果测试的是HLS流延迟大是正常的。测试时应以HTTP-FLV或RTMP为准。调整[rtp]下的lowLatency、videoMtuSize、audioMtuSize。在局域网内可以将MTU设大一些如1400减少包数量。检查网络状况是否存在丢包或带宽瓶颈。问题5服务运行一段时间后内存占用持续增长内存泄漏。排查可能是连接没有正确释放或者ZLMediaKit本身在特定场景下的bug。解决首先确保你的config.ini中streamNoneReaderDelayMS等参数设置合理确保无观众的流会被及时关闭。使用curl http://127.0.0.1/index/api/getThreadsLoad和getStatistic等API监控服务器状态观察连接数、流数量是否在正常范围内波动。如果怀疑是代码问题可以尝试更新到ZLMediaKit的最新版本或者查看项目的Issue列表看是否有类似问题及修复。在嵌入式平台也可以使用top或htop观察MediaServer进程的RES内存占用。一个稳定的服务内存占用应该在达到一个峰值后趋于稳定而不是无限增长。移植工作到这一步一个基本功能的ZLMediaKit就已经在你的ARM板上跑起来了。整个过程从工具链准备、依赖库交叉编译、主工程配置编译到部署调优和问题排查涵盖了嵌入式移植的核心环节。每个项目、每块板子的情况可能略有不同但解决问题的思路是相通的明确错误信息、定位问题层次环境、依赖、配置、代码、利用工具分析、针对性解决。希望这份详细的记录能帮你绕过我踩过的那些坑更顺利地在ARM平台上搭建起强大的流媒体服务。