Wazuh 源码构建完全指南：Server / UNIX Agent / Windows Agent 的编译、定制与清理-迪斯科星球

Wazuh 源码构建完全指南：Server / UNIX Agent / Windows Agent 的编译、定制与清理

【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh

本指南以 docs/dev/build-sources.md 为骨架，系统讲解如何从源码构建 Wazuh 安全平台的核心组件（Server 管理端、UNIX 系 Agent、Windows Agent），涵盖依赖下载、Makefile 构建选项、CMake 底层原理、构建产物位置与多种清理策略。读者完成阅读后，将能够独立搭建 Wazuh 的编译环境、按需定制构建参数，并对构建失败进行快速定位与修复。

环境准备：工具链是成功构建的前提

在开始任何构建之前，需要先完成开发环境的搭建。推荐平台为Ubuntu 24.04，最低工具链要求如下（详见 docs/dev/setup.md）：

依赖	最低版本 / 说明
GNU C/C++ Compiler	GCC 13+
GNU Make	构建驱动工具
CMake	3.18+
SELinux Policy Core Utils	`policycoreutils`（提供`checkmodule`、`semodule_package`）
procps	进程管理工具
curl	下载外部依赖
CMocka	仅运行单元测试时需要（`libcmocka-dev`）

Ubuntu 24.04 安装命令：

apt install gcc g++ make cmake curl procps policycoreutils apt install libcmocka-dev

Rocky Linux 9 需要额外启用 GCC 工具集：

dnf install make cmake gcc-toolset-13-gcc-c++ gcc-toolset-13-gcc procps policycoreutils scl enable gcc-toolset-13 bash dnf install dnf-plugins-core dnf config-manager --enable crb dnf install libcmocka-devel

版本提示：当前仓库 VERSION.json 标识的版本为5.1.0（stagealpha0）。构建过程中，src/CMakeLists.txt 会解析该文件并注入VERSION/REVISION宏到编译单元中，因此版本号与源码保持一致。

Windows Agent 构建的特殊要求

构建 Windows 版 Agent（winagent）需要三样东西：MinGW 交叉编译器、Wine（用于在 Linux 上运行 Windows 测试二进制）和CMocka（必须用 MinGW 从源码交叉编译）。

Ubuntu 24.04 安装 MinGW 与 Wine：

apt install gcc-mingw-w64-i686 g++-mingw-w64-i686 wine32

CMocka 交叉编译（stable-1.1 分支，关闭共享库）：

git clone -b stable-1.1 https://git.cryptomilk.org/projects/cmocka.git sed -Ei 's/(BUILD_SHARED_LIBS .+) ON/\1 OFF/' cmocka/DefineOptions.cmake mkdir cmocka/build cd cmocka/build cmake -DCMAKE_C_COMPILER=i686-w64-mingw32-gcc \ -DCMAKE_C_LINK_EXECUTABLE=i686-w64-mingw32-ld \ -DCMAKE_INSTALL_PREFIX=/usr/i686-w64-mingw32/ \ -DCMAKE_SYSTEM_NAME=Windows \ -DCMAKE_BUILD_TYPE=Release .. make make install cd ../.. rm -r cmocka

理解构建系统：Makefile 驱动，CMake 落地

Wazuh 的构建入口位于 src/Makefile，它承担两层职责：

依赖管理（deps目标）：按目标平台（TARGET）挑选所需的外部库清单（cJSON、OpenSSL、zlib、sqlite、libyaml、curl、libpcre2、flatbuffers 等），从packages.wazuh.com/deps/预编译库或源码包下载并解压到src/external/（见 src/Makefile 的RESOURCES_URL与DEPS_VERSION定义）。
CMake 工程调用：最终通过build_wazuh_cmake目标在src/build/目录执行cmake .. -DTARGET=${TARGET} ...并调用make完成真正的编译（见 src/Makefile）。

编译单元的组织方式也随TARGET不同而分化（见 src/CMakeLists.txt）：

Agent（agent/winagent）：编译active-response、addagent、client-agent、logcollector、os_execd、rootcheck、syscheckd等组件；winagent还会追加win32子目录；
Server（manager）：编译engine、monitord、os_auth、remoted、wazuh_db以及content_manager、indexer_connector、keystore、router等共享模块。

值得注意的是，TARGET=server与TARGET=manager是等价的——src/Makefile 中显式将server重写为manager。如果不指定TARGET，Make 会输出提示并要求你显式选择manager、agent或winagent（见failtarget目标，src/Makefile）。

构建 Wazuh Server（管理端）

Server 组件（manager）的构建分为两步：先安装依赖，再编译：

make -C src TARGET=server deps make -C src TARGET=server

-C src表示在src/目录下执行 Make；deps目标会依据TARGET=server拉取 Server 专属依赖，例如 CPython（内嵌 Python 解释器）、jemalloc、rocksdb、simdjson、abseil-cpp、spdlog、yaml-cpp、protobuf 等（见 src/Makefile 的 Server-only 依赖清单）。若仓库根目录存在external/cpython源码，Server 构建还会触发build_python，将 CPython 与 Wazuh 内部库链接并安装到INSTALLDIR/framework/python（见 src/Makefile 与 src/Makefile）。

Server 构建选项

make -C src TARGET=server DEBUG=1 # 带调试符号构建（-g，关闭优化） make -C src TARGET=server TEST=1 # 测试模式构建（开启 UNIT_TEST） make -C src TARGET=server -j4 # 4 个并行编译任务 make -C src TARGET=server INSTALLDIR=/custom # 安装到自定义目录

DEBUG=1：在 src/Makefile 中映射为CMAKE_BUILD_TYPE=Debug，对应编译标志-g（见 src/CMakeLists.txt）。
TEST=1：映射为-DUNIT_TEST=ON（见 src/Makefile），此时 CMake 会为各目标附加--coverage覆盖率编译与 gcov 链接选项（见 src/CMakeLists.txt）。
-jN：GNU Make 的并行任务数，多核机器上可显著缩短编译时间。
INSTALLDIR=/custom：指定安装前缀。当使用PYTHON_SOURCE从源码编译 Python 解释器时该参数为必填（未定义会直接报错，见 src/Makefile）。

此外，src/Makefile 的help目标还列出了更多可选开关，例如：

选项	说明
`V=yes`	显示完整编译输出（默认安静模式）
`USE_INOTIFY=yes`	启用 inotify 支持（Linux 下默认自动启用）
`USE_BIG_ENDIAN=yes`	大端序平台支持
`USE_SELINUX=yes`	生成 SELinux 策略模块（仅 Agent）
`USE_AUDIT=yes`	审计服务支持（Linux Agent 默认启用）
`DISABLE_JEMALLOC=yes`	不构建 jemalloc 内存分配库
`OPTIMIZE_CPYTHON=yes`	构建 Python 解释器时启用优化
`PYTHON_SOURCE=yes`	与`deps`配合，下载 CPython 源码用于本地编译
`IMAGE_TRUST_CHECKS=0/1/2`	DLL/EXE 签名校验（0 禁用，1 仅告警，2 强制），默认 1
`CA_NAME="..."`	签名校验所用 CA 名称，默认`DigiCert Assured ID Root CA`
`WAZUH_USER`/`WAZUH_GROUP`	覆盖默认运行用户/组（Server 为`wazuh-manager`，Agent 为`wazuh`）

构建 UNIX 系 Agent

UNIX 系（Linux、macOS、BSD 等）Agent 的构建流程与 Server 完全对称：

make -C src TARGET=agent deps make -C src TARGET=agent

Agent 构建选项

make -C src TARGET=agent DEBUG=1 # 带调试符号构建 make -C src TARGET=agent TEST=1 # 测试模式构建 make -C src TARGET=agent -j4 # 4 并行任务 make -C src TARGET=agent INSTALLDIR=/custom # 安装到自定义目录

与 Server 相比，Agent 的依赖集更精简：Linux Agent 额外引入libdb、popt、lua、rpm、dbus、libbpf-bootstrap（用于 eBPF 系统调用监控），macOS Agent 则引入libplist（见 src/Makefile）。Linux 平台下 Agent 还会自动启用 audit（ENABLE_AUDIT=ON）以支撑 FIM/whodata 实时监控，而 Server 不需要该代码路径（见 src/Makefile）。

构建 Windows Agent（交叉编译）

Windows Agent 是典型的 Linux 主机上的交叉编译流程。同样先装依赖再编译：

make -C src TARGET=winagent deps make -C src TARGET=winagent

构建过程中 src/Makefile 会：

使用i686-w64-mingw32-g++-posix定位并拷贝运行时 DLL（libstdc++-6.dll、libgcc_s_dw2-1.dll）到src/build/lib/；
通过unix2dos.pl将ossec.conf、internal_options.conf、LICENSE、VERSION.json等转换为 Windows 换行符版本，输出到src/win32/（见 src/Makefile）；
在 src/CMakeLists.txt 中设置CMAKE_SYSTEM_NAME=Windows、MinGW 编译器与EVENTCHANNEL_SUPPORT=ON，并将 Wine 配置为单元测试的交叉运行模拟器。

交叉编译器必须可用，否则 Make 会直接报错No windows cross-compiler found!（见 src/Makefile 的编译器探测逻辑，依次探测amd64-mingw32msvc-、i686-pc-mingw32-、i686-w64-mingw32-前缀）。

构建完成后，将src/win32/下所有文件拷贝到 Windows 机器，即可进一步用 WiX Toolset 生成 MSI 安装包（参见 docs/dev/run-sources.md 的 Windows Agent 章节，安装包构建脚本为wazuh-installer-build-msi.bat，相关工程文件见 src/win32/wazuh-installer.wxs）。

构建产物位置

构建成功后，二进制产物位于：

目标	产物目录
Server / UNIX Agent	`src/`目录（实际中间产物在`src/build/`，链接后的可执行文件与库位于`src/build/bin`与`src/build/lib`）
Windows Agent	`src/win32/`目录

后续的安装、运行与配置步骤（./install.sh、wazuh-manager-control/wazuh-control、日志路径等）请参阅 docs/dev/run-sources.md；构建完成后如何执行单元测试与集成测试，请参阅 docs/dev/test-execution.md。

清理构建产物：四种清理目标

构建系统提供了分级清理目标，按需选择：

make -C src clean # 清理全部编译产物（含外部依赖） make -C src clean-deps # 仅清理外部依赖 make -C src clean-internals # 清理编译产物，保留外部依赖 make -C src clean-windows # 清理 Windows 资源文件

各目标语义（依据 src/Makefile 的实现）：

clean：完整清理，依次调用clean-test（覆盖率报告与.gcno/.gcda文件）、clean-internals、clean-external、clean-windows、clean-framework与clean-config（../etc/wazuh.mc、Config.OS）。适合需要彻底重来的场景。
clean-deps：仅清除src/external/下除CMakeLists.txt与.gitignore之外的下载依赖（含shared_modules/http-request与 WCS flat 文件），保留已编译的二进制，方便重新拉取依赖。
clean-internals：删除build目录、单元测试构建目录、flatbuffers 生成头文件（syscollector、vulnerability_scanner的*_generated.h）、SELinux 模块（wazuh.mod、wazuh.pp），但保留外部依赖——适合快速增量重编译。
clean-windows：仅删除src/win32/下由unix2dos.pl生成的 Windows 资源文件（LICENSE.txt、help_win.txt、internal_options.conf、default-ossec.conf、VERSION.json等）。

常见问题排查

依赖缺失导致编译失败

如果编译报错指向缺少的头文件或库，最可能的原因是跳过了deps阶段。务必先执行：

make -C src deps

该目标会下载当前TARGET所需的全部外部依赖（cJSON、OpenSSL、zlib、sqlite、libyaml、curl、libpcre2、nlohmann、flatbuffers、bzip2、googletest、benchmark 等通用依赖，以及各目标专属依赖），若网络受限，可组合EXTERNAL_SRC_ONLY=yes仅拉取源码。

编译速度过慢

使用并行构建make -C src TARGET=server -j4（-j值建议不超过 CPU 物理核心数）。注意deps阶段通常耗时集中在下载与解压，也可以预先执行make -C src TARGET=server deps后再并行编译。

调试与验证构建配置

使用V=yes查看完整编译器命令行，便于定位具体编译单元的错误；
使用make -C src TARGET=server settings查看当前生效的构建设置（TARGET、DEBUG、INSTALLDIR、USE_* 开关、编译器变量等，见 src/Makefile）；
使用make -s print-EXTERNAL_RES TARGET=agent打印当前目标解析后的依赖清单（该接口同时被 packages/externals 工具链复用，见 src/Makefile）。

结语

从源码构建 Wazuh 的整体脉络可以概括为：选对 TARGET → 拉齐依赖（deps）→ 按需定制选项 → 并行编译 → 检查产物 → 分级清理。理解 src/Makefile 与 src/CMakeLists.txt 的分工，是灵活驾驭 Server、UNIX Agent 与 Windows Agent 三种构建路径的关键。结合 docs/dev/setup.md 的工具链准备、docs/dev/run-sources.md 的运行部署以及 docs/dev/test-execution.md 的测试执行，即可完成从源码到可运行安全平台的完整闭环。

【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析