如果你正在尝试装 Wazuh十有八九会被它那套“一个安装包里藏了四个组件”的架构折腾得够呛。我把话放在这里Wazuh 本身的安装流程并不复杂真正会劝退人的是那些文档里不会明说的版本坑、内存坑、证书坑还有一套装完以为成功了、结果 Agent 死活连不上的连接玄学。我上周刚用一台干净的 Ubuntu 22.04 虚拟机把 Wazuh 4.7 单机快速部署整个走了一遍。中途前后跑了三遍才算把每一步的报错都理清楚也顺势整理出一份自认为“越早看越少踩坑”的实战记录。这篇指南不适合那些只想无脑复制命令的人它更适合打算在生产环境或者认真评估 Wazuh 的朋友——我会把安装过程里最容易犯的错、最容易被误解的逻辑以及最容易被忽略的参数全部摊开讲明白。如果你正准备在 Linux 上部署一套开源 SIEM或者已经装了但在 Dashboard、Indexer、Agent 之间来回试错那这篇内容你多半用得上。1. 部署前必须想清楚的几个选择安装 Wazuh 之前我建议你先别急着敲命令先花十分钟回答三个问题你装的是测试环境还是生产环境打算一台机器扛全部还是组件分开部署准备用官方安装助手还是自己手动装这些问题看起来像废话但我在实测中发现很多人后面遇到的大部分故障根源都在最初“没想清楚就动手”。1.1 单机版还是分布式别一拍脑袋就上集群Wazuh 的核心组件其实可以拆成四部分Wazuh Indexer、Wazuh Server、Wazuh Dashboard以及跑在被监控机器上的 Agent。官方给的快速安装方式里大部分组件都可以装在同一台服务器上也就是所谓的 All-in-One 单机部署。我的建议很直接第一次部署别碰多节点先用单机把全链路跑通。原因很简单Wazuh 的分布式部署需要自己处理节点证书、网络分片、副本分配还要保证每个组件节点名和证书 CN 一致。只要你有一条对不上集群就会以各种你意想不到的方式拒绝启动。而单机部署只靠官方安装脚本自动生成配置文件基本没有额外配置成本。等单机版真的用明白了再考虑把 Indexer 拆出来做三节点高可用也不迟。如果你执意要上集群请务必将每个节点的 IP、节点名、证书信息统一规划并在生成配置文件的阶段就把它们写进配置文件。我见过太多人安装文档里写了node-1实际机器却叫prod-wazuh-indexer然后证书解析失败白白多查好几个小时。1.2 操作系统与硬件规格最少要多少才不会半路崩Wazuh 组件的硬件胃口不算小尤其是 Indexer本质上是基于 OpenSearch 的搜索分析引擎内存和磁盘都吃得很凶。官方给出的最低配置是 4GB 内存、2核 CPU但我实操下来的结论是4GB 真的只是“能装上”不是“能跑好”。我这次测试用的是 4核 8GB 内存的虚拟机磁盘分配了 80GB。实际运行起来Indexer 默认的堆内存就占了 4GBServer 组件也有 1GB 左右的占用Dashboard 又要吃掉一部分8GB 内存的单机部署负载大概在 70% 左右。如果你还需要在同一台机器上做后续的规则测试、数据写入建议直接把内存拉到 16GB磁盘 100GB 起。操作系统方面官方支持 Ubuntu 20.04、22.04Debian 11、12RHEL/CentOS 8、9 等。我更推荐用 Ubuntu 22.04 LTS因为 Wazuh 安装脚本对 APT 体系的适配度最高CentOS 7 这类旧系统就不要挣扎了依赖库版本老装到一半很容易出现诡异的 Python 或者 OpenSSL 报错。还有一个系统参数特别容易被忽略vm.max_map_count。OpenSearch 的索引写入依赖内存映射默认值往往只有 65530直接跑 Indexer 会报“max virtual memory areas vm.max_map_count [65530] is too low”之类的错误。安装脚本在部分环境下会自动调整但在 Docker 或某些精简版内核上不会生效手工加一行sysctl -w vm.max_map_count262144总是没有坏处的。1.3 版本选择与升级策略别追新稳定压倒一切Wazuh 的版本迭代速度相当快我在测试时用的是当时最新的 4.7 系列。如果你是在公司环境里规划部署我建议你优先选用 v4.5 之后的稳定版因为 4.5 开始官方把原来的wazuh-certs-tool.sh、config.yml等一堆零散工具整合进了wazuh-install.sh这一个脚本安装流程简化了不少。虽然 4.8、4.9 等新版本往往带来新功能和新防护规则但改动越大踩到新坑的概率也越高。尤其是 Agent 和 Manager 的版本匹配问题我遇到过 Manager 升级到 4.8 后旧版 Agent 的日志解析格式不兼容导致事件数据在 Dashboard 里显示不全。合理的安全基线是Server 和 Dashboard 保持同版本Agent 版本尽量不低于 Server 大版本太多。还有一个很现实的建议安装前先看一眼官方文档里的“安装前提”和“兼容性矩阵”别拿生产环境试错。实在想尝鲜先放虚拟机里跑一两个星期再说。2. 核心组件关系与安装逻辑拆解很多人一看到 Wazuh 的安装界面就开始敲命令结果根本分不清自己到底在装什么。这不能怪你因为 Wazuh 的组件命名和普通软件不太一样你必须先看懂架构再谈安装。2.1 四个核心组件到底在干什么我用一个餐厅的比喻来解释。Wazuh Server 相当于餐厅的前厅经理和收银台它负责接收各个餐桌也就是被监控的机器传来的点单信息做初步的校验、归类和分发。Wazuh Indexer 则是后厨仓库把所有经过预处理的日志存起来并提供搜索能力。Wazuh Dashboard 是装修豪华的中央监控屏让你能看到全局运营状况、规则命中情况和告警列表。Agent 就是那位潜伏在后厨的“试吃员”它安装在每台被监控设备上采集文件变更、系统日志、进程行为等数据然后实时上报给 Server。放到技术上Agent 采集日志后通过 1514 端口发给 Wazuh Server 的wazuh-agentlessd或wazuh-remoted组件Server 对日志进行标准化、解码、匹配规则然后写入 Indexer。Indexer 基于 OpenSearch 和它的安全插件做了用户认证和权限控制Dashboard 通过 HTTPS 连接 Indexer提供可视化和搜索操作。所以这四个组件是一个完整的数据流水线任何一个断了整条链路都会出问题。明白了这个逻辑你就知道为什么安装顺序是 Indexer 在先、Server 次之、Dashboard 最后了——因为 Dashboard 要连接 Indexer 的存储和认证 APIServer 也要把处理完的告警事件主动推给 Indexer所以必须先有“仓库”才能开工。2.2 为什么标准化安装脚本适合大多数人Wazuh 官方从 4.5 开始主推安装助手wazuh-install.sh这是我最推荐给普通用户的方式。这个脚本的厉害之处在于它会帮你自动完成三件事生成内部 CA 和节点证书安装配置对应组件最后输出所有初始密码。默认情况下只要一台干净的机器、一个正常的网络和一串参数跑完就能进入 Dashboard。为什么推荐它因为手动安装的最大难点不是“下载包”而是证书生成。Wazuh 所有组件之间都默认启用 TLS 加密通信证书里包含的节点名和 IP 必须与配置文件一一对应。手动写config.yml时候一旦格式缩进写错、节点名写错后面所有组件都连不上。安装脚本则用一套自动生成工具按固定模板生成证书最不容易出错。脚本也有不适合的场景。比如你要对接企业内部的私有 CA 签发的证书或者完全离线的内网环境那就得走手动安装和离线包部署路线。离线部署又是一套完全不同的玩法下载离线安装包、手动分发证书、一个个安装依赖复杂度会上一个台阶。如果你没有明确的合规要求优先用官方脚本来降低排错难度。2.3 手动安装时最容易忽略的依赖关系虽然我建议大多数人用脚本安装但知道手动安装的依赖逻辑对排查故障很有帮助。安装 Wazuh Indexer 时OpenSearch 自带了一套 JDK它依赖的是opensearch这个包但如果你系统里装了其他版本的 Java可能会导致JAVA_HOME环境变量冲突。实际上 OpenSearch 会优先读取自己内置的 JVM版本冲突一般不会有致命影响但如果你在/etc/environment里强制设置了 Java反而可能影响 Indexer 启动。Wazuh Server 的 Manager 包是wazuh-manager安装时对 Python 版本、curl 版本有一定要求Ubuntu 22.04 自带的 Python 3.10 够用但不要让系统里有多个 Python 版本并存否则wazuh-remoted在调用分析脚本时可能指向错误的解释器。Wazuh Dashboard 则是 Node.js 应用虽然安装包内置了 Node 运行时但 Dashboard 首次启动时连接 Indexer 的节点名必须是证书里的 CN如果你手动写配置时用了 IP 而不是节点名就会一直报证书校验失败。我见过有人在/etc/wazuh-dashboard/opensearch_dashboards.yml里把 host 写成localhost而证书 CN 是wazuh-dashboard结果怎么都登不进去。这些细节在脚本安装时都被自动处理了但如果你非要手动拆装就必须时刻记住节点名、证书、配置文件三者要一一对应缺一不可。3. 实际安装全流程实录含参数调整有了前面的准备下面开始实际的安装过程。我演示的环境是 Ubuntu 22.044核8G内存预先配好了静态 IP。默认情况下所有操作都是root用户或sudo权限执行。3.1 存储库配置与安装器执行第一步是准备好依赖和软件源。先更新系统然后安装curl和gnupg等基础工具apt update apt install -y curl gnupg apt-transport-https建议先确认curl能访问 Wazuh 官方源再把 GPG key 导入系统curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | gpg --no-default-keyring --keyring gnupg-ring:/usr/share/keyrings/wazuh.gpg --import chmod 644 /usr/share/keyrings/wazuh.gpg然后添加 Wazuh APT 源echo deb [signed-by/usr/share/keyrings/wazuh.gpg] https://packages.wazuh.com/4.x/apt/ stable main /etc/apt/sources.list.d/wazuh.list apt update这里有一个坑如果你执行完apt update后提示源文件有 “Key is stored in legacy trusted.gpg” 警告说明你的 GPG key 没有加到 keyring 路径里。我的做法是严格走上面那两步把 keyring 指向/usr/share/keyrings/wazuh.gpg不会出现警告。接下来下载安装助手curl -sO https://packages.wazuh.com/4.x/wazuh-install.sh bash wazuh-install.sh --generate-config-files这一步会在当前目录生成wazuh-install-files.tar.gz里面包含了证书、配置文件等关键文件。请把这个压缩包的密码和位置记好后续安装组件时需要它。如果报错说tar解压失败多半是之前下载的脚本不完整可以重新下载覆盖再执行。3.2 索引器安装与内存参数调整生成配置文件之后先装第一个组件。bash wazuh-install.sh --wazuh-indexer node-1这里node-1必须和之前生成配置时指定的节点名一致。如果你自定义了节点名请同步修改不要随意改名。安装脚本会自动安装 OpenSearch、配置安全插件和证书然后启动服务。但如果你用的环境内存偏小很可能会在这一步遇到 Indexer 启动失败。常见的报错是Error: Could not open file /etc/wazuh-indexer/opensearch.log: Permission denied或者直接提示服务没有起来。此时我先检查了free -h发现可用内存不到 2GB再看/etc/wazuh-indexer/jvm.options默认-Xms4g -Xmx4g。4GB 堆内存在小内存机器上根本起不来。我的处理方式是临时把 JVM 堆降到 2GBsed -i s/-Xms4g/-Xms2g/; s/-Xmx4g/-Xmx2g/ /etc/wazuh-indexer/jvm.options systemctl daemon-reload systemctl restart wazuh-indexer同时确认系统参数sysctl -w vm.max_map_count262144 echo vm.max_map_count262144 /etc/sysctl.conf这一步必须做否则后续 Indexer 写入索引时还可能报 mmap 错误。将堆内存设成 2G 后Indexer 可以正常启动但如果你有 8G 以上内存还是建议保持默认的 4G因为过小的堆会影响搜索性能。验证 Indexer 是否起来可以用curl -k https://localhost:9200如果返回了带tagline : The OpenSearch Project的 JSON 信息说明 Indexer 服务正常。如果提示无法连接先看/var/log/wazuh-indexer/下的日志别急着重启很多启动失败的原因已经写在日志里了。3.3 安装 Manager 与 DashboardIndexer 稳定后安装 Wazuh Server也就是 Managerbash wazuh-install.sh --wazuh-server wazuh-1由于我们之前已经生成了配置文件这一步主要安装wazuh-manager、filebeat并自动导入 Dashboard 所需的模板和索引策略。Manager 默认监听 1514 和 1515 端口收到 Agent 日志后写入 Indexer。安装完成后你可以在/var/ossec/etc/ossec.conf中看到 Manager 的配置不用手动修改。不过要注意环境里的主机名如果改了最好同步确认 Filebeat 连接 Indexer 的配置没写错。然后是最后一个组件bash wazuh-install.sh --wazuh-dashboard dashboard安装脚本在最后会输出一堆提示包括 Dashboard 的访问地址和初始用户名密码。特别注意初始密码不是admin/admin而是一个随机生成的密码脚本会显示在输出信息里请立马复制保存。后续如果你想自己改密码可以用bash /usr/share/wazuh-indexer/bin/wazuh-passwords-tool -a -u admin -p 你希望设置的新密码这一步跑完理论上访问https://服务器IP就能打开 Dashboard 登录页面。但先别高兴太早很多人的坑正从这一刻开始。3.4 初始配置验证与 Agent 接入进入 Dashboard 之前先做一次基础验证。在浏览器打开https://IP跳过证书警告后用刚才的密码登录。如果页面显示正常说明 Indexer、Dashboard 的连通性没问题。接下来需要接入一台测试用的 Agent。在 Dashboard 页面点击 “Add agent”选择操作系统页面会生成一串部署指令大致是curl -s https://packages.wazuh.com/4.x/wazuh-agent.sh | bash -s -- -a -m MANAGER_IP -p 1515 -A agent-name这里有几个容易出错的地方。agent-name不要带空格和特殊符号MANAGER_IP必须填 Agent 能访问到的 Manager 地址不要填localhost。如果你把 Agent 装在同一台 Manager 机器上IP 填127.0.0.1也能通但我更建议用内网 IP 测试避免后续客户端连接时混淆。安装 Agent 后稍等几秒在 Dashboard 的 Agents 界面应该能看到新 Agent 上线。如果状态是 “Never connected”去 Agent 的/var/ossec/logs/ossec.log里看连接日志。最常见的错误是 1514/1515 端口被防火墙拦截或者 Manager 端没有开启对应端口的监听。可以用ss -lntup | grep -E 1514|1515检查监听状态。这个我在下一节详细展开。4. 常见问题与排查技巧实录这一节是大家最关心的部分。我把整个安装过程和后续试用里遇到的典型故障整理成了一套速查手册每个问题都附带原因分析和解决办法建议收藏备用。4.1 内存不足导致的安装失败现象在安装 Indexer 时systemctl status wazuh-indexer显示服务启动失败日志里出现java.lang.OutOfMemoryError或进程直接被 kill。原因大部分测试机或低配 VPS 只有 2~4GB 内存Indexer 默认 JVM 堆占 4GB再加上系统本身的内存开销进程直接爆内存被 OOM Kill。处理按我前面说的修改/etc/wazuh-indexer/jvm.options把-Xms4g和-Xmx4g改小。注意一点两个值最好保持一致避免运行期堆动态扩容带来的性能抖动。改完重启systemctl daemon-reload systemctl restart wazuh-indexer同时确认系统剩余内存足够如果连 2GB 腾不出来就不要在机器上开太多服务。这种方案只适合测试环境生产环境还是把内存至少加到 8GB 更稳妥。4.2 证书与节点名称不匹配现象安装或后期启动组件时出现类似SSL exception、PKIX path building failed、CNnode-1 does not match的错误。Dashboard 打开后一片空白或者搜索数据时显示无法连接。原因Wazuh 组件之间的 TLS 证书是安装助手根据你生成配置文件时的节点名签发的。如果你在安装 Indexer 时使用了node-1但证书实际签给my-node就会校验失败。最常见的情况是没有先执行过--generate-config-files或者中途手动改过/etc/wazuh-install-files.tar.gz里的配置。处理不要试图手动改证书文件直接重新生成一套干净的配置bash wazuh-install.sh --generate-config-files然后重新按顺序安装组件。如果你只是需要重装某个组件可以用--overwrite参数覆盖旧证书但最好先备份旧配置文件。还有一个容易忽略的问题Dashboard 访问 Indexer 时默认会验证 Indexer 证书的节点名。在/etc/wazuh-dashboard/opensearch_dashboards.yml中host必须与证书 CN 一致。用脚本安装时脚本会把它自动设为https://node-1:9200所以不要自己改成localhost。4.3 Dashboard 首次登录白屏、账号密码报错现象登录https://IP后一直白屏浏览器 F12 控制台报大量 502/503 错误或者输入初始密码提示认证失败。原因白屏大概率是 Dashboard 进程没有成功连接 Indexer导致后端 API 全部请求超时。密码错误则可能是你用了默认的admin/admin但脚本实际生成的是随机密码。处理先确认 Dashboard 服务状态systemctl status wazuh-dashboard tail -50 /var/log/wazuh-dashboard/dashboard.log如果日志里有 “connect ECONNREFUSED 127.0.0.1:9200”首先查 Indexer 是否活着再查 Dashboard 配置文件里的 host 是否指向正确。如果 Indexer 也没起来回到 4.1 处理内存问题。密码问题简单重置密码即可bash /usr/share/wazuh-indexer/bin/wazuh-passwords-tool -a -u admin -p NewPassword123!改完密码记得去 Dashboard 配置里把elasticsearch.username改成 admin否则 Dashboard 鉴权依然会失败。4.4 防火墙与端口放行清单现象Agent 安装后状态永远是 “Never connected”或者外部机器访问 Dashboard 超时。原因很可能是防火墙没放行。Wazuh 的通信端口非常明确但不同组件和不同 Linux 发行版的管理方式可能不同导致你明明在安全组放行了却漏了系统内部防火墙。处理单机部署时必须放行以下端口用途端口协议说明Wazuh Manager 接收 Agent 事件1514TCPAgent 日志上传Wazuh Manager 接受 Agent 注册1515TCPAgent 初次注册使用Wazuh Indexer REST API9200TCPDashboard 和 Filebeat 访问Wazuh Dashboard HTTPS443TCP浏览器访问以 Ubuntu 的ufw为例ufw allow 1514/tcp ufw allow 1515/tcp ufw allow 9200/tcp ufw allow 443/tcp ufw reload如果是 CentOS/RHEL 的firewalldfirewall-cmd --permanent --add-port1514/tcp firewall-cmd --permanent --add-port1515/tcp firewall-cmd --permanent --add-port9200/tcp firewall-cmd --permanent --add-port443/tcp firewall-cmd --reload还要注意9200 端口如果暴露到公网等于把索引器的数据接口直接开放了哪怕有 TLS 和认证也可能被扫描到。生产环境建议只允许内网或 Dashboard 服务器所在网段访问。4.5 Agent 注册与连接常见幺蛾子现象Agent 安装成功但 Dashboard 里看不到设备或者看到了但状态一直 “Pending” / “Never connected”。原因除了端口问题多半是 Agent 名称和 Manager 端注册信息对不上。Agent 名称是安装时传入的-A参数Manager 端不会自动帮你改名。如果 Agent 改了主机名但注册名没同步Manager 会识别为不同设备。处理建议所有 Agent 安装时统一命名规则比如server-name-01。安装完成后检查 Agent 端通信日志tail -50 /var/ossec/logs/ossec.log如果看到ERROR: 1011通常代表 Agent 无法与 Manager 建立连接。先pingManager IP再用telnet ManagerIP 1514测端口。如果通检查/var/ossec/etc/ossec.conf里的address是否是 Manager IP。Manager 端同时也要看认证日志tail -50 /var/ossec/logs/auth.log确认是否收到了 Agent 的注册请求。如果出现Unauthorized user大概率是因为 Agent 端传的用户名密码不对。默认情况下脚本安装的 Manager 使用自动认证一般不会出问题但如果之前在 Dashboard 里启用了手动认证就要为每个 Agent 单独创建认证条目。4.6 时间同步与时钟偏移现象Agent 上报的事件时间比当前时间差了几个小时或者告警排序错乱。原因Wazuh 对时间非常敏感尤其是分布式环境中组件之间的时间同步直接影响日志事件的时间戳。Agent 和 Manager 在跨区域部署时如果时区不同或者 NTP 没有同步会因为时间跳变导致部分规则误报。处理在所有 Wazuh 相关机器上统一启用 NTP 服务apt install -y ntp systemctl enable --now ntp如果只有少量机器也可以使用timedatectl set-ntp true。重点看/etc/ossec/ossec.conf里的timezone配置Manager 和 Agent 的时区建议保持一致便于告警时间统一。最后留个实操彩蛋这个彩蛋是我自己踩坑最多的地方——wazuh-install.sh安装完成后输出的控制台日志尤其是最后几行务必先截图或者复制到单独的文件里。里面不仅包含 Dashboard 登录密码还有 Indexer 的一些内部账号信息。很多人装完顺手关了终端过了两天再登录时才发现自己把密码弄丢了。如果你真的忘了密码也别慌用下面的命令之一就能重置bash /usr/share/wazuh-indexer/bin/wazuh-passwords-tool -u admin -p NewPassword123!这玩意儿比重新安装整个 Wazuh 强多了。最后再说句实在话Wazuh 的安装过程其实是在帮你建立一套安全运营思维。只要理解了组件如何协作、端口如何通信、证书如何互信后面无论你对它做高可用还是横向扩展都会有清晰的思路。我建议你在测试环境里大胆玩先把安装时踩过的坑挨个记下来等真的要生产部署时你的这些笔记就是最值钱的经验。