企业官网建设流程全解析

Wazuh 开发环境搭建与 VS Code 调试配置实战指南（基于 docs/dev/setup.md）

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

导读

本文基于 Wazuh 官方开发文档 docs/dev/setup.md 编写，完整介绍在 Ubuntu 24.04 / Rocky Linux 9 上从零搭建 Wazuh（开源统一 XDR 与 SIEM 安全平台）C/C++ 开发环境、为 Windows Agent 准备 MinGW 交叉编译工具链，以及如何在 Visual Studio Code 中配置构建任务（Build Tasks）、GDB 调试配置与部署流水线的全流程。读完本文，你将能够独立复现 Wazuh 的源码编译、调试与迭代环境，并结合仓库源码理解make TARGET=... DEBUG=1等关键构建参数在底层是如何生效的。

一、工具链准备：最低版本要求

Wazuh 官方推荐的开发平台为Ubuntu 24.04，其核心源码位于仓库 src/ 目录（C/C++ 实现），同时包含 framework/（Python 框架层）与 api/（REST API 层）。编译源码的最低工具链要求如下：

从仓库 src/Makefile 可以看到，构建系统在运行时探测checkmodule与semodule_package是否存在，以此决定是否启用USE_SELINUX编译选项，这正是工具链清单中 SELinux Policy Core Utils 的用途。

版本说明：当前仓库 VERSION.json 标识的版本为5.1.0 (alpha0)；构建系统会从该文件提取version与stage并注入预处理器宏（见 src/CMakeLists.txt）。

二、按发行版安装工具链

2.1 Ubuntu 24.04（推荐）

使用 apt 安装基础编译工具与依赖：

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

第二条命令安装的是 CMocka 的二进制开发包（libcmocka-dev），仅对 Linux 目标（server / agent）的单元测试编译足够；Windows Agent 目标的 CMocka 必须从源码用 MinGW 交叉编译（见下文）。

2.2 Rocky Linux 9

Rocky 9 默认仓库的 GCC 版本较旧，因此需要启用GCC Toolset 13并通过scl（Software Collections）激活：

dnf install make cmake gcc-toolset-13-gcc-c++ gcc-toolset-13-gcc procps policycoreutils scl enable gcc-toolset-13 bash # 安装 CMocka（需先启用 CRB 仓库） dnf install dnf-plugins-core dnf config-manager --enable crb dnf install libcmocka-devel

libcmocka-devel位于 CRB（CodeReady Builder）仓库中，这正是需要config-manager --enable crb的原因。

三、Windows Agent 构建要求（Linux 上交叉编译）

Wazuh 的 Windows Agent 可以在 Ubuntu 24.04 上通过MinGW 交叉编译生成，前提是安装 MinGW、CMocka 与 Wine 三件套。

3.1 安装 MinGW 与 Wine

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

注意此处是i686（32 位）工具链。仓库 src/CMakeLists.txt 为 Windows 交叉编译强制指定了i686-w64-mingw32-ranlib与i686-w64-mingw32-windres；而 src/Makefile 在TARGET=winagent时会自动探测i686-w64-mingw32-gcc并设置MING_BASE前缀，找不到时直接报错No windows cross-compiler found!。

Wine 的作用是作为Windows 可执行文件的运行模拟器：当CMAKE_SYSTEM_NAME=Windows且开启UNIT_TEST时，CMake 会把wine设置为交叉编译测试的模拟器（见 src/CMakeLists.txt），否则 Windows 单元测试在 Linux 上无法执行。

3.2 从源码编译 MinGW 版 CMocka

发行版自带的libcmocka-dev是 Linux 原生库，无法链接到 Windows 目标，因此必须从源码为 MinGW 构建静态版本：

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

关键点说明：

• sed命令将DefineOptions.cmake中的BUILD_SHARED_LIBS改为OFF，强制生成静态库（交叉环境下运行时加载 DLL 不便）；
• 安装前缀/usr/i686-w64-mingw32/与 src/CMakeLists.txt 中查找winpthread库的搜索路径一致，保证链接阶段能找到库；
• 该流程与仓库 docs/dev/test-execution.md 中 Windows 单元测试的 CMocka 构建步骤完全吻合（src/unit_tests/Toolchain-win32.cmake 是配套的交叉编译工具链文件）。

安装完成后，即可按 docs/dev/build-sources.md 构建 Windows Agent：

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

构建产物位于 src/win32/ 目录；顶层 Makefile 的winagent目标还会用 src/win32/unix2dos.pl 把ossec.conf、internal_options.conf、LICENSE等文本转换为 Windows 换行格式（见 src/Makefile）。

四、Visual Studio Code 开发环境

官方推荐使用VS Code进行 Wazuh 开发，配合 C/C++ 插件实现 IntelliSense、调试与代码浏览。

4.1 推荐扩展

仓库中已提供一份贴近真实开发的 VS Code 配置示例，位于 src/engine/tools/devContainer/.vscode/，可作为参考（包含settings.json、launch.json、tasks.json、c_cpp_properties.json）。

4.2 Workspace 设置（.vscode/settings.json）

在仓库根目录创建或更新.vscode/settings.json，以对齐 Wazuh 编码规范：

{ "files.autoSave": "afterDelay", "files.trimTrailingWhitespace": true, "files.insertFinalNewline": true, "files.trimFinalNewlines": true, "files.simpleDialog.enable": true, "editor.acceptSuggestionOnEnter": "off", "workbench.editor.enablePreview": false, "files.associations": { "wazuh-manager.conf": "xml", "ossec.conf": "xml", "agent.conf": "xml" }, "terminal.integrated.allowChords": false, "terminal.integrated.scrollback": 100000, "editor.rulers": [80] }

关键项解析：

• files.trimTrailingWhitespace：保存时删除行尾空白；
• files.insertFinalNewline：确保文件以换行符结尾（C 源码规范要求）；
• editor.rulers: [80]：在 80 列处显示辅助线，约束行长。仓库引擎模块的配置还额外标注了 90/120 列参考线（见 src/engine/tools/devContainer/.vscode/settings.json）；
• files.associations：把wazuh-manager.conf、ossec.conf、agent.conf识别为 XML 语法（这些是真实的 Wazuh 配置格式，仓库中的模板见 etc/wazuh-manager.conf、etc/ossec-agent.conf 与 etc/agent.conf）；
• terminal.integrated.scrollback: 100000：把终端回滚缓冲提高到 10 万行，便于回溯长编译输出。

4.3 构建任务（.vscode/tasks.json）

把编译动作封装为 VS Code 任务，避免手工敲命令。创建或更新.vscode/tasks.json：

{ "version": "2.0.0", "tasks": [ { "label": "build server", "type": "shell", "command": "make", "args": ["TARGET=server", "DEBUG=1", "-j4"], "options": { "cwd": "${workspaceFolder}/src" }, "group": "build", "problemMatcher": ["$gcc"] }, { "label": "build agent", "type": "shell", "command": "make", "args": ["TARGET=agent", "DEBUG=1", "-j4"], "options": { "cwd": "${workspaceFolder}/src" }, "group": "build", "problemMatcher": ["$gcc"] }, { "label": "build windows agent", "type": "shell", "command": "make", "args": ["TARGET=winagent", "-j4"], "options": { "cwd": "${workspaceFolder}/src" }, "group": "build", "problemMatcher": ["$gcc"] } ] }

运行方式：

• Ctrl+Shift+P（macOS 为Cmd+Shift+P）→ 输入 “Tasks: Run Task” → 选择任务；
• 或直接按Ctrl+Shift+B展示全部构建任务。

配置项说明：

• DEBUG=1：编译带调试符号（-g）且不优化。在 src/Makefile 中，DEBUG=1会向 CMake 传递-DCMAKE_BUILD_TYPE=Debug；src/CMakeLists.txt 进一步设置CMAKE_CXX_FLAGS_DEBUG "-g"；
• -j4：4 个并行编译作业，可结合 CPU 核数调整；
• problemMatcher: ["$gcc"]：解析编译器输出，把错误/警告显示到 Problems 面板。

TARGET 参数在 Makefile 中的语义：TARGET=server会被归一化为manager（src/Makefile），与agent、winagent一起决定编译哪些模块。从 src/CMakeLists.txt 可见，agent 专属模块（active-response、logcollector、rootcheck、syscheckd、data_provider等）仅在IS_AGENT时编译；server 专属模块（engine、monitord、os_auth、remoted、wazuh_db等）仅在非 agent 时编译。构建入口是build_wazuh_cmake目标（src/Makefile）：cd build && cmake .. -DTARGET=... && make。

4.4 调试配置（.vscode/launch.json）

创建或更新.vscode/launch.json，以 GDB 交互式调试 Wazuh 守护进程：

{ "version": "0.2.0", "configurations": [ { "name": "Debug wazuh-manager-analysisd", "type": "cppdbg", "request": "launch", "program": "/var/wazuh-manager/bin/wazuh-manager-analysisd", "args": ["-f"], "stopAtEntry": false, "cwd": "${workspaceFolder}", "environment": [], "externalConsole": false, "MIMode": "gdb", "setupCommands": [ { "description": "Enable pretty-printing for gdb", "text": "-enable-pretty-printing", "ignoreFailures": true } ], "preLaunchTask": "build server", "miDebuggerPath": "/usr/bin/gdb" } ] }

开始调试：

1. 打开要调试的源文件；
2. 在行号左侧点击设置断点；
3. 按F5，或进入 Run → Start Debugging；
4. 也可以打开调试面板（Ctrl+Shift+D）点击播放按钮。

配置项说明：

• program：要调试的二进制路径。此例为 Manager 的分析引擎wazuh-manager-analysisd（对应 src/wazuh_modules 与 src/engine 编译出的分析组件）；
• args: ["-f"]：-f（foreground）让进程前台运行，便于 GDB 接管；
• preLaunchTask: "build server"：调试前先执行上文的构建任务，确保二进制最新；
• stopAtEntry: true：若想停在程序入口，可改为true；
• 重要前提：二进制必须用DEBUG=1编译（带调试符号），否则断点与变量查看不可用。

为其他组件添加调试配置（例如 remoted）：

{ "name": "Debug wazuh-manager-remoted", "type": "cppdbg", "request": "launch", "program": "/var/wazuh-manager/bin/wazuh-manager-remoted", "args": ["-f"], "preLaunchTask": "build server", "MIMode": "gdb" }

安装后的可执行文件统一位于/var/wazuh-manager/bin/（Manager）与/var/ossec/bin/（Agent），与 docs/dev/run-sources.md 中描述的安装目录一致。

4.5 构建后的部署

编译产物默认位于src/目录，而调试配置指向安装目录/var/wazuh-manager/bin/，因此需要把二进制拷贝过去。可新增部署任务：

{ "label": "deploy wazuh-manager-analysisd", "type": "shell", "command": "sudo", "args": ["cp", "wazuh-manager-analysisd", "/var/wazuh-manager/bin/"], "options": { "cwd": "${workspaceFolder}/src" }, "dependsOn": ["build server"] }

dependsOn保证先构建、后部署。更省事的做法是：在调试配置的preLaunchTask中链式引用该部署任务，实现“每次调试前自动重新编译并部署”。Wazuh 各组件通常以 root 权限运行，拷贝到系统目录需要sudo，这一点在调试时同样适用（见下文故障排除）。

五、故障排除（Troubleshooting）

5.1 调试时提示权限拒绝（Permission Denied）

Wazuh 组件普遍需要 root 权限。两种解决方式：

• 以 root 运行 VS Code（使用独立配置目录避免污染普通用户配置）：

  sudo code --user-data-dir=/root/.vscode-root --no-sandbox

• 或配置 sudo 免密，避免调试会话中反复输入密码。

5.2 GDB 未找到（GDB Not Found）

apt-get install gdb # Ubuntu/Debian yum install gdb # Rocky Linux/RHEL

安装后确认launch.json中miDebuggerPath指向实际路径（默认/usr/bin/gdb）。

5.3 编译错误（Compilation Errors）

确认依赖齐全且编译器版本满足要求：

gcc --version # 应为 13 或更高

同时检查：

• 是否先执行了make -C src TARGET=... deps（外部依赖下载与构建，见 docs/dev/build-sources.md）。顶层 Makefile 维护了EXTERNAL_RES依赖清单（src/Makefile），Manager 目标额外拉取 cpython、rocksdb、protobuf 等数十个库，Agent 目标则包含 libdb、lua、rpm 等；
• 若启用单元测试模式（TEST=1），src/Makefile 会向 CMake 传递-DUNIT_TEST=ON，此时 CMocka 头文件必须存在；
• 如需内存安全检测，可以启用FSANITIZE=1，src/CMakeLists.txt 会为 Debug 构建追加-fsanitize=address,leak,undefined标志。

5.4 IntelliSense 不工作

1. 确认已安装 C/C++ 扩展（ms-vscode.cpptools）；
2. 打开命令面板（Ctrl+Shift+P）；
3. 运行 “C/C++: Edit Configurations (JSON)”；
4. 检查compilerPath与includePath是否正确。Wazuh 源码依赖的头文件目录可在 src/CMakeLists.txt 中看到（如src/shared/include、src/shared_modules/*/include），可据此配置includePath或直接使用 CMake Tools 的compile_commands.json（该项目默认开启CMAKE_EXPORT_COMPILE_COMMANDS，见 src/CMakeLists.txt）。

六、环境就绪后的下一步

工具链与 IDE 配置完成后，可以继续阅读仓库开发文档的其余部分：

• docs/dev/build-sources.md：Server、UNIX Agent、Windows Agent 的完整编译流程与clean系列清理目标；
• docs/dev/run-sources.md：从源码安装、启动、停止各组件，以及日志与常见运维操作；
• docs/dev/test-execution.md：单元测试（CMocka/CTest/覆盖率）、API 与框架测试（pytest）、集成测试的执行方式；
• docs/dev/package-generation.md：在 Docker 容器中批量生成 rpm/deb 安装包。

总结

本文完整复现并扩充了 Wazuh 开发环境搭建的全过程：从 Ubuntu 24.04 / Rocky Linux 9 的工具链安装、Windows Agent 的 MinGW + Wine + CMocka 交叉编译环境，到 VS Code 的扩展、工作区规范、构建任务与 GDB 调试配置。同时通过 src/Makefile 与 src/CMakeLists.txt 的源码证据，解释了TARGET、DEBUG、TEST、FSANITIZE等核心构建参数在底层如何驱动 CMake 与依赖管理，帮助你在遇到编译或调试问题时能够快速定位根因。

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