Wazuh 4.x 开发环境 Docker Compose 快速搭建指南多节点集群、负载均衡与本地源码热挂载【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh本文以仓库中的 api/tools/env/README.md 为骨架围绕其docker-compose.yml、各组件 Dockerfile、entrypoint 脚本、NGINX 配置与证书生成脚本等真实文件系统讲解如何在本地一键拉起一套 Wazuh 4.x 多节点开发集群Master 双 Worker Indexer Dashboard Agent NGINX 负载均衡并深入说明本地源码热挂载、环境变量、常见故障排查等实战细节。读者读完可完整复现这套开发环境并理解其底层实现原理。⚠️ 警告该目录是测试/开发环境包含多种面向调试的简化配置如默认凭据、调试日志、宽松的 API 限流严禁用于生产环境。环境组件总览api/tools/env/ 目录是 Wazuh 4.x 版本的 PyServer 开发环境包含以下 6 类组件全部通过 docker-compose.yml 编排在一个名为wazuh.net的 bridge 网络中服务名角色关键端口镜像来源wazuh.managerMaster 节点55050→55000API本地构建wazuh-managerserver targetwazuh.worker1Worker 节点 #155051→55000API复用wazuh-manager镜像wazuh.worker2Worker 节点 #255052→55000API复用wazuh-manager镜像nginx.lbNGINX 负载均衡1514→1514本地构建nginx.lbwazuh.agentAgent无映射内网本地构建wazuh-agentwazuh.indexerIndexer9200quay.io/wazuh/wazuh-indexer:5.0.0-0wazuh.dashboardDashboard443→5601public.ecr.aws/wazuh-cicd/wazuh/wazuh-dashboard:5.0.0-latestwazuh.base基础编译镜像-本地构建wazuh-basecerts.generator证书生成器-本地构建wazuh-certs-generator除wazuh.indexer与wazuh.dashboard直接拉取预编译镜像外Manager、Worker、Agent 均以本地仓库代码编译而来使得这套环境天然服务于 Wazuh 4.x 的源码级二次开发。服务依赖拓扑从 compose 文件中的depends_on可以还原出完整的启动时序理解这一顺序对排查启动失败至关重要certs.generator ──成功退出──▶ wazuh.indexer ──healthy──▶ wazuh.manager ──started──▶ wazuh.worker1 / wazuh.worker2 │ ▼ nginx.lb ──started──▶ wazuh.agentwazuh.indexer依赖certs.generator成功完成condition: service_completed_successfully保证 TLS 证书先就绪wazuh.manager依赖wazuh.indexer健康service_healthycompose 中配置了针对/_cluster/health的 healthchecknginx.lb依赖三个 Manager 节点全部已启动wazuh.agent依赖nginx.lb已启动并将nginx.lb作为注册地址写入配置。快速启动一条命令拉起集群前置条件Docker Engine 与 Docker Compose v2按 .env 的模板设置 4 个环境变量变量含义示例WAZUH_BRANCH用于wazuh-base编译阶段git clone的分支/标签v4.9.0WAZUH_VERSION传给 Agent 入口脚本的版本号v4.9.0WAZUH_PYTHON_VERSION内嵌 Python 的主次版本用于拼接挂载路径3.10WAZUH_LOCAL_PATH本地 Wazuh 仓库的绝对路径用于源码热挂载/data/web/disk1/git_repo/GitHub_Trending/wa/wazuhWAZUH_LOCAL_PATH与WAZUH_PYTHON_VERSION直接决定挂载是否生效两者必须与实际环境一致否则site-packages路径拼接将指向错误位置。两条核心命令docker compose build # 1. 构建镜像 docker compose up # 2. 启动整个集群构建阶段会先编译wazuh-base拉取指定分支源码、安装编译依赖并执行make deps随后基于它构建wazuh-manager与wazuh-agent。横向扩容 Agent需要更多 Agent 时一条命令即可按需扩容docker compose up --scale wazuh-agent5扩容后的 Agent 都通过nginx.lb接入集群。需要说明的是当使用--scale时wazuh.agent服务不应设置固定container_name因此 docker-compose.yml 中该服务未声明固定容器名其他服务如 indexer、dashboard则显式指定了container_name。本地源码热挂载改代码即生效这是该开发环境最有价值的设计之一。Manager 与两个 Worker 通过 bind mount 将本地仓库的 Python 代码实时挂载进容器替代容器内安装的对应目录本地路径宿主机容器内路径挂载目标${WAZUH_LOCAL_PATH}/framework/scripts/var/wazuh-manager/framework/scripts${WAZUH_LOCAL_PATH}/api/scripts/var/wazuh-manager/api/scripts${WAZUH_LOCAL_PATH}/framework/wazuh/var/wazuh-manager/framework/python/lib/python${WAZUH_PYTHON_VERSION}/site-packages/wazuh${WAZUH_LOCAL_PATH}/api/api/var/wazuh-manager/framework/python/lib/python${WAZUH_PYTHON_VERSION}/site-packages/api以framework/wazuh与api/api两个核心 Python 包为例容器内 Manager 进程实际 import 的是宿主机上的源码。开发者修改 framework/wazuh/ 或 api/api/ 下的任何.py文件后只需重启对应容器docker compose restart wazuh.manager即可加载新逻辑无需重新 build 镜像。这套挂载同时覆盖了 API 网关与框架层意味着调试 API 控制器如 api/api/controllers/、模型api/api/models/或框架核心framework/wazuh/core/代码都非常方便。此外wazuh-manager/Dockerfile 在构建阶段还预装了pydevd-pycharm、freezegun、ipdb三个调试/测试库可直接配合 PyCharm 远程调试或断点分析。单容器独立构建与运行如果只需要单独跑一个 Manager 容器例如聚焦 API 调试README 提供了不经过 Compose 的构建路径cd wazuh-manager docker build -t wazuh-manager --target server ./wazuh-manager先按 .env 模板定义所需的环境变量然后运行docker run -d \ --name wazuh-master \ --hostname wazuh-master \ -p 55000:55000 \ -v ${WAZUH_LOCAL_PATH}/framework/scripts:/var/wazuh-manager/framework/scripts \ -v ${WAZUH_LOCAL_PATH}/api/scripts:/var/wazuh-manager/api/scripts \ -v ${WAZUH_LOCAL_PATH}/framework/wazuh:/var/wazuh-manager/framework/python/lib/python${WAZUH_PYTHON_VERSION}/site-packages/wazuh \ -v ${WAZUH_LOCAL_PATH}/api/api:/var/wazuh-manager/framework/python/lib/python${WAZUH_PYTHON_VERSION}/site-packages/api \ wazuh-manager \ /scripts/entrypoint.sh wazuh-master master-node master这里--target server选择了 wazuh-manager/Dockerfile 中的多阶段server目标跳过开发依赖得到精简运行镜像-p 55000:55000暴露 RESTful API 端口最后的三个参数分别对应 entrypoint 的NODE_NAME、cluster node_name与节点角色master。深入实现启动流程与配置注入Manager 入口角色驱动的配置生成wazuh-manager/entrypoint.sh 是理解这套环境的关键WAZUH_CERTS_DIR/var/wazuh-manager/etc/certs ROLE$3 # master / worker # 等待证书生成器产出 root-ca.pem while [ ! -f ${WAZUH_CERTS_DIR}/root-ca.pem ]; do sleep 2 done # 写入 Indexer 凭据默认 wazuh-manager / wazuh-manager echo wazuh-manager | /var/wazuh-manager/bin/wazuh-manager-keystore -f indexer -k username echo wazuh-manager | /var/wazuh-manager/bin/wazuh-manager-keystore -f indexer -k password # 依据角色写入 wazuh-manager.conf 与 api.yaml if [ $ROLE master ]; then python3 /scripts/xml_parser.py /var/wazuh-manager/etc/wazuh-manager.conf /scripts/master_wazuh-manager_conf.xml sed -i s:# access:access:g /var/wazuh-manager/api/configuration/api.yaml sed -i s:# max_request_per_minute\: 300: max_request_per_minute\: 99999:g /var/wazuh-manager/api/configuration/api.yaml else python3 /scripts/xml_parser.py /var/wazuh-manager/etc/wazuh-manager.conf /scripts/worker_wazuh-manager_conf.xml fi # 开启调试日志 echo wazuh_db.debug2 /var/wazuh-manager/etc/wazuh-manager-internal-options.conf echo authd.debug2 /var/wazuh-manager/etc/wazuh-manager-internal-options.conf echo remoted.debug2 /var/wazuh-manager/etc/wazuh-manager-internal-options.conf chmod 500 /var/wazuh-manager/etc/certs chmod 400 /var/wazuh-manager/etc/certs/* chown -R wazuh-manager:wazuh-manager /var/wazuh-manager/etc/certs /var/wazuh-manager/bin/wazuh-manager-control start while true; do sleep 10; done # 保持容器存活其中 Master 特有的两处sed直接作用于 API 配置文件 api.yaml将# access注释解除放开 API 的访问控制将max_request_per_minute从默认的300提升到99999显著放宽 API 限流便于压测与调试这是仅限测试环境的原因之一。开发环境的调试属性还体现在向wazuh-manager-internal-options.conf追加wazuh_db.debug2、authd.debug2、remoted.debug2三行将数据库、注册认证、远程通信三大模块的日志级别调到 debug。集群配置模板与动态节点名Master 与 Worker 使用不同的 XML 模板master_wazuh-manager_conf.xmlnode_typemaster、集群端口1516、共享密钥9d273b53510fef702b54a92e9cffc82e开发环境固定值、Indexer 指向https://wazuh.indexer:9200并引用容器内证书路径worker_wazuh-manager_conf.xmlnode_typeworker并额外声明nodesnodewazuh.manager/node/nodes指明 Master 地址同时追加protocoltcp/protocol。两个模板都设置了use_source_ipno/use_source_ip使 Agent 事件不受来源 IP 影响适配经 NGINX 代理转发的场景。模板替换由 xml_parser.py 完成它读取当前wazuh-manager.conf与新模板将模板中每个 section 的内容整体替换到原配置对应 section不存在则追加。特别地当宿主机 hostname 含worker时还会把clusternode_name动态改为实际 hostname如wazuh.worker1保证集群内节点名唯一。Agent 入口动态写入 Manager 地址wazuh-agent/entrypoint.sh 通过sed将ossec.conf中的address替换为入口参数即nginx.lb并把internal_options.conf的agent.debug从 0 调到 2 开启调试随后启动wazuh-control。因此 Agent 注册与上报全部经由负载均衡器进入集群。Agent 的健康检查基于日志关键字见 wazuh-agent/DockerfileHEALTHCHECK ... CMD grep INFO: (4102): Connected to the server /var/ossec/logs/ossec.log || exit 1即只有当 Agent 在日志中打出“已连接服务器”的 4102 信息时才判定为 healthy。证书体系自动生成与分发certs.generator是集群的信任根基其 Dockerfile 从 Wazuh 官方 packages 站点下载wazuh-certs-tool.sh入口脚本 generate_certs.sh 调用./wazuh-certs-tool.sh -A一次性生成全部节点证书并做两件事将全部证书拷贝到共享卷wazuh-certs挂载于/certificates供 Manager/Worker/Indexer 使用将root-ca.pem、wazuh.dashboard.pem、wazuh.dashboard-key.pem单独导出到./config/wazuh_dashboard_certs供 Dashboard 挂载见 compose 中的/export/dashboard卷映射。节点清单定义在 certs-generator/config.yml它刻画了整套集群的拓扑1 个 indexerwazuh.indexer、2 个 server workerwazuh.worker1→wazuh.worker别名、wazuh.worker2→wazuh2.worker别名、1 个 dashboard。注意 config.yml 中ip字段使用的是Docker 网络内的服务名/别名而非真实 IP这与 compose 中networks.wazuh.net.aliases的声明一一对应。Indexer 侧的 TLS 由 wazuh.indexer.yml 配置HTTP 与 transport 层的证书/私钥/CA 均指向/etc/wazuh-indexer/certs/下的同名证书allow_default_init_securityindex: true配合 compose 中OPENSEARCH_JAVA_OPTS-Xms1g -Xmx1g与默认admin:admin凭据让单节点索引器在开发环境开箱即用。负载均衡NGINX 四层代理nginx-lb/nginx.conf 用 NGINXstream模块实现 TCP 层负载均衡stream { upstream mycluster { least_conn; server wazuh.manager:1514; server wazuh.worker1:1514; server wazuh.worker2:1514; } upstream register { least_conn; server wazuh.manager:1515; server wazuh.worker1:1515; server wazuh.worker2:1515; } server { listen 1514; proxy_pass mycluster; } # Agent 事件上报 server { listen 1515; proxy_pass register; } # Agent 注册/认证 }端口1514事件上报通道与1515注册认证通道分别均衡到三个 Manager 节点负载算法为least_conn最少连接动态分散 Agent 连接Agent 只感知nginx.lb这一个地址通过入口参数写入ossec.conf因此集群对 Agent 完全透明也实现了--scale wazuh-agentN的自由扩容。一键清理与故障排查完全清理含卷docker compose down -v-v会连同wazuh-indexer-data、wazuh-certs、wazuh-dashboard-custom三个命名卷一起删除。由于证书保存在卷中若集群配置变更如修改节点名或 IP必须清理后重建避免旧证书干扰。构建失败处理构建问题优先使用无缓存构建docker compose build --no-cacheapi/tools/env/README.md 明确建议在遇到构建问题时使用--no-cache。结合 wazuh-base/Dockerfile 可以看到编译链路较长git clone指定分支 →make deps失败还会自动重试一次缓存失效或网络波动都可能导致构建中断--no-cache是最直接的规避手段。常见排障路径速查现象排查点Indexer 起不来/不健康确认certs.generator是否成功退出docker compose logs certs.generator查看证书生成日志检查admin:admin凭据与/_cluster/health可达性Manager 卡在“Waiting for certificates”共享卷wazuh-certs为空重跑certs.generator或docker compose down -v后重建Agent 反复重启docker compose logs wazuh.agent查看是否有Connected to the server4102确认nginx.lb1514/1515 端口可通本地代码改动未生效核对.env中WAZUH_LOCAL_PATH是否为绝对路径、WAZUH_PYTHON_VERSION是否与镜像内 Python 版本一致然后docker compose restart wazuh.manager端口冲突55050/55051/55052API、9200Indexer、443Dashboard、1514LB若与本机服务冲突需调整 compose 左侧宿主机端口总结api/tools/env/ 提供了一整套 Wazuh 4.x 源码开发环境的容器化方案一键集群docker compose build docker compose up即可拉起 Master 双 Worker Indexer Dashboard Agent NGINX LB 的完整拓扑源码热挂载framework/与api/目录直接 bind mount 进容器配合pydevd-pycharm/ipdb可高效调试 API 与框架代码角色化配置注入entrypoint 依据 master/worker 角色套用不同 XML 模板并自动开启 API 限流放宽与多模块 debug 日志透明横向扩容NGINX 四层代理屏蔽了集群内部结构--scale wazuh-agentN即可灵活增减 Agent 数量。再次强调这套环境为了开发便利引入了默认凭据、放宽限流与全量 debug 日志仅适用于测试与开发切勿在生产环境直接复用。【免费下载链接】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），仅供参考