2026/9/15 6:33:36
FEATURED · 精选文章 
装 Wazuh 这种事属于“文档写得挺好但照着抄还是会翻车”的典型。我前前后后在生产环境和小规模测试环境里装过不下十次从 4.3 一路装到 4.7踩过的坑五花八门端口被占、证书权限不对导致服务起不来、Agent 死活注册不上、一升级就全校报错全都遇到过。这篇指南把 Wazuh 安装全流程拆开专门讲哪些地方容易出事、出事之后怎么定位。Wazuh 是什么一句话开源的统一安全监控平台整合了 HIDS主机入侵检测、SIEM 事件收集以及基础的 XDR 能力。装好之后它能在 Linux/Windows 主机上收集日志、做文件完整性监控FIM、检测 rootkit、跑漏洞扫描把所有数据汇总到一个看板里统一展示。适合什么人看刚接触安全基础设施的运维、准备用 Wazuh 替代商业 SIEM 的团队以及已经被安装报错折磨了一两天还没装成的新手。下面这些内容全部来自真实环境不是照着官方文档念一遍。1. 动手之前先搞清楚 Wazuh 的架构和版本脾气1.1 三个组件的分工决定了你的排错方向Wazuh 不像 Nginx 那样一个包装完就结束。它由三大部分组成官方命名分别是 Wazuh Indexer、Wazuh Server、Wazuh DashboardWazuh Indexer数据存储与检索层底层是 OpenSearch负责保存告警和事件数据同时维护索引模板。Wazuh Server核心管理节点里面又包含 Manager进程叫 wazuh-manager监听 Agent 通信和 Filebeat负责把分析后的事件转发到 Indexer。Wazuh Dashboard可视化层底层是 OpenSearch Dashboards 的定制版提供 Web 界面和 API。这三者之间的联动是Agent 把日志推给 Server 的 1514 端口Server 里 wazuh-analysisd 分析后写入本地 socketFilebeat 再从 socket 读取数据发送到 Indexer 的安全索引里Dashboard 负责查询展示。所以一旦你遇到“Agent 在线但看板没数据”问题十有八九出在 Filebeat 到 Indexer 这一段而不是 Agent 本身。把这些组件在脑子里串成一条链路后面排错会快非常多。我第一次装的时候不知道这个关系Agent 明明显示 active可看板里一条告警都没有硬是查了一下午才发现是 Filebeat 的证书路径写错了。1.2 版本必须对齐这是最容易忽略的硬性约束官方文档里写得很明确所有组件必须使用相同的主版本并且在安装脚本和仓库配置里必须绑定准确的版本号不能只写一个 4.x 就完事。举例来说2024 年之后很多教程还停留在 4.5、4.6 的命令如果照抄用 4.7 的方式生成了证书却去装 4.5 的索引器包大概率出现证书校验失败或者索引模板版本不兼容。我的做法是安装前先到官方 release 页面确认当前最新稳定版本然后把安装命令里的版本号写死比如curl -sO https://packages.wazuh.com/4.7/wazuh-install.sh这样至少保证脚本、工具、仓库用的是同一套版本逻辑。等你确认这套版本组合跑通了再考虑锁仓或升级别在安装阶段给自己埋不稳定的种子。1.3 部署形态先问自己“我到底要装什么”有三种常见装法单机一体化Indexer、Server、Dashboard 装在同一台机器上官方 quickstart 就是干这个的。适合测试环境、学习环境、小规模生产环境。分布式Indexer 集群三个节点Server 和 Dashboard 分开部署。适合更大规模或者高可用需求。只装 Server 和 Agent 做纯日志收集不装 Dashboard纯命令行管理这个场景比较少见一般是有已有可视化平台的团队才会这么干。如果你只是自己体验我强烈建议先走单机一体化。原因很实在组件越多排错变量越多一次只引入一个变量才是合理的排查策略。等单机跑通了再拆分布式也不迟。2. 环境准备资源、系统与网络这三样别省2.1 硬件资源官方最低配置是能跑不是能好好跑官方对单机部署的建议是 4GB 内存、2 核 CPU、30GB 硬盘。我实测下来4GB 内存真的只是“能装起来”一旦 Agent 开始持续上报事件OpenSearch 的 JVM 堆我一般给 1GB加上系统本身内存很快吃满然后出现各种莫名其妙的 OOM。我现在的小规模生产环境用的是 8GB 内存、4 核、100GB 硬盘稳定多了。如果你只有 4GB可以加 2GB swap 兜底装好后把 Indexer 的堆内存调小一点在 /etc/wazuh-indexer/opensearch.yml 里加一行opensearch.heap.size: 1gswap 的作用是兜底不是万能的频繁换页会让查询变慢但总比进程直接被 OOM killer 杀掉强。内存不足时还会伴随另一个现象Indexer 启动到一半就退出journalctl 里能看到 killed process 的提示。2.2 系统版本Ubuntu 22.04 是最省心的选择官方支持很多发行版但我的建议非常朴素能上 Ubuntu 22.04 就上 Ubuntu 22.04。它的系统包版本比较新OpenSearch 和依赖基本不会出现 libc 版本太老这类问题。CentOS 7 已经 EOL别再用了RHEL 8 和 9 官方支持但 Red Hat 系在安装 OpenSearch 时经常遇到 SELinux 权限问题虽然能解但没必要给自己加难度。还有一个经常被忽略的点装之前把系统时间校准一下。时钟漂移会导致 TLS 证书验证失败表现是浏览器访问 Dashboard 时提示证书无效组件之间通信也不正常。用 chrony 或 NTP 同步一下一劳永逸。2.3 主机名解析这一步不做quickstart 大概率失败这是我在多台机器上验证过的最常见的“卡死点”。Wazuh 的安装脚本和默认配置使用三个固定主机名去解析节点地址wazuh-indexer、wazuh-server、wazuh-dashboard。如果你的 DNS 里没有这三个 A 记录或者没写进 /etc/hosts脚本会在“Searching for the indexer...”这一步卡住很久然后报错退出。单机部署最简单的方式是在 /etc/hosts 里加三行192.168.1.100 wazuh-indexer 192.168.1.100 wazuh-server 192.168.1.100 wazuh-dashboard把 IP 换成这台机器自己的局域网 IP 即可。很多教程不强调这一点导致读者卡在安装流程的最早阶段。就算你用 quickstart 脚本执行前也必须先加好这些解析别跳过去。2.4 内核参数和文件描述符OpenSearch 的“体检项”OpenSearch 启动时有三个硬性前置条件不满足会直接拒绝启动vm.max_map_count 至少 262144。大部分系统默认值是 65530必须调大。文件描述符限制至少要 65535。如果有 systemd 管理的服务还要处理 memory lock 限制。调 vm.max_map_count 用sysctl -w vm.max_map_count262144 echo vm.max_map_count262144 /etc/sysctl.conf sysctl -p文件描述符在 systemd 服务里配更可靠。直接编辑服务单元或者用 systemctl edit wazuh-indexer添加 LimitNOFILE65535 和 LimitMEMLOCKinfinity然后 systemctl daemon-reload。这里有个经验不要在终端里只跑 ulimit -n 改了就说 OK服务是 systemd 拉起的终端里的 ulimit 只对当前 shell 生效跟服务无关。3. 完整安装流程一步步来顺便把坑踩一遍3.1 方式一Quickstart 一键脚本适合体验官方一键脚本确实快但它有个前提机器必须是干净的没有装过任何 Wazuh 组件也不能残留旧的证书目录。命令很简单curl -sO https://packages.wazuh.com/4.7/wazuh-install.sh bash wazuh-install.sh脚本会自己生成证书、装全部组件、最后打印管理员密码。看起来非常美好但实际执行时最可能碰到的第一个报错是“The certificates were not generated”或类似提示。原因一般是主机名没解析好或者磁盘空间不足按 2.3 先补 hosts清掉无用文件再重跑。quickstart 还有个隐藏的坑它不擅长升级。之后如果你想升级版本官方文档明确要求把旧版本彻底卸载再跑新版脚本这意味着数据得提前备份。所以如果是有明确生产计划的项目我更推荐手动装。3.2 方式二手动分组件安装推荐手动装听起来麻烦其实只是多打几条命令但对每一层的控制力完全不一样。先添加 Wazuh 仓库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这一步在 Ubuntu 20.04 和 22.04 上我踩过一次坑如果没有先创建 /usr/share/keyrings 目录后面 apt update 会一直报“The following signatures couldnt be verified”。解决方式就是先建目录再把权限改成 644最后在 /etc/apt/sources.list.d/wazuh.list 里用 signed-by 指过去deb [signed-by/usr/share/keyrings/wazuh.gpg] https://packages.wazuh.com/4.x/apt/ stable main接下来安装 Indexer。先装包再改配置 /etc/wazuh-indexer/opensearch.yml单节点场景至少要保证这几行正确network.host: 0.0.0.0 node.name: node-1 cluster.initial_master_nodes: node-1 discovery.type: single-node plugins.security.disabled: false plugins.security.ssl.transport.pemcert_filepath: /etc/wazuh-indexer/certs/wazuh-indexer.pem plugins.security.ssl.transport.pemkey_filepath: /etc/wazuh-indexer/certs/wazuh-indexer-key.pem plugins.security.ssl.transport.pemtrustedcas_filepath: /etc/wazuh-indexer/certs/root-ca.pem plugins.security.ssl.http.pemcert_filepath: /etc/wazuh-indexer/certs/wazuh-indexer.pem plugins.security.ssl.http.pemkey_filepath: /etc/wazuh-indexer/certs/wazuh-indexer-key.pem plugins.security.ssl.http.pemtrustedcas_filepath: /etc/wazuh-indexer/certs/root-ca.pem这里最容易犯的错是漏掉 plugins.security.disabled: false或者把证书路径写成了相对路径。OpenSearch 安全插件加载的是绝对路径写错了它不会立刻报错而是初始化安全配置的时候才暴露。3.3 证书生成与分发最考验耐心的一步Wazuh 组件之间全部走 TLS 加密通信证书必须包含节点的主机名和 IP。生成方法官方提供了脚本curl -sO https://packages.wazuh.com/4.7/wazuh-certs-tool.sh bash wazuh-certs-tool.sh -A-A 参数表示生成所有节点的证书。执行完会在当前目录生成一个 wazuh-certificates 文件夹里面有 root-ca.pem、root-ca.key以及每个节点对应的 .pem 和 -key.pem。分发证书时最常见的坑是权限。比如 Indexer 要求证书所有者是 wazuh-indexer 用户否则启动直接报 Permission denied。我的标准动作是mkdir -p /etc/wazuh-indexer/certs cp /path/to/wazuh-certificates/*.pem /etc/wazuh-indexer/certs/ cp /path/to/wazuh-certificates/wazuh-indexer-key.pem /etc/wazuh-indexer/certs/ chown -R wazuh-indexer:wazuh-indexer /etc/wazuh-indexer/certs chmod 500 /etc/wazuh-indexer/certs chmod 400 /etc/wazuh-indexer/certs/*.keyServer 端要装 Filebeat证书目录是 /etc/filebeat/certs文件至少是 644运行用户是 root 没问题。Dashboard 同理certs 目录要 chown 给 wazuh-dashboard 用户。网上很多帖子看到 Permission denied 就以为是系统权限问题其实真相就是证书文件的所有者没配对。服务是 systemd 管理的运行用户不是 root读不到 root 的 600 文件就这么简单。3.4 启动顺序和初始化顺序错了会连环报错手动装完以后启动顺序有讲究先 Indexer确认验证通过再 Server再 Filebeat最后 Dashboard。如果先启动 Dashboard它只会一直重试连接 Indexer日志刷屏意义不大。Indexer 起来之后还有一步初始化安全配置很多人会漏掉cd /usr/share/wazuh-indexer/bin/ bash ./wazuh-indexer-security-init.sh这个脚本会创建内置用户和默认密码 admin/admin。如果没有执行这一步Dashboard 无论如何都连不上 Indexer日志里全是 authentication 相关的报错。执行成功后用这条命令验证集群状态curl -k -u admin:admin https://localhost:9200/_cluster/health?pretty看到 status 为 green 或者至少 yellow说明 Indexer 就绪。如果返回 red去看日志 journalctl -u wazuh-indexer -n 50 --no-pager基本都是 2.4 提到的内核参数问题或者堆内存不够。4. 我把高频报错整理成了速查表这一节是全文的核心我把反复遇见的报错、现象、原因和解决办法整理成一个速查表建议直接收藏以后装 Wazuh 时对照。4.1 服务起不来先查内核参数和证书报错现象常见原因解决办法Indexer 启动失败日志有 bootstrap checks failedvm.max_map_count 不够sysctl -w vm.max_map_count262144并写入 sysctl.confIndexer 报 memory locking requested for mlockall but is not allowedLimitMEMLOCK 未放开systemctl edit wazuh-indexer加 LimitMEMLOCKinfinity然后 daemon-reloadDashboard 起不来日志是 Permission denied证书目录权限或 owner 不对按 3.3 重新 chownkey 文件设为 400目录至少 500一键脚本跑到一半失败主机名没解析、磁盘满、已有旧组件补 /etc/hosts清磁盘卸载旧组件后再重跑4.2 Agent 注册不上九成是网络和名字问题Agent 安装完成后需要执行注册命令类似这样sudo WAZUH_MANAGER192.168.1.100 WAZUH_AGENT_NAMEubuntu-node-01 apt install wazuh-agent注册不上通常表现在 /var/ossec/logs/ossec.log 里反复出现 Unable to connect to server 或 Invalid agent name。排查顺序是先确认 Server 的 1514、1515 端口能从 Agent 这台机器访问。用 nc -zv 192.168.1.100 1514 试一下。防火墙不开端口是我见过最多的问题ufw 默认只放行 OpenSSH 的更是一抓一大把。单机测试图省事可以直接 ufw allow 1514/tcp 和 1515/tcp生产环境记得用安全组规则精确放行。再看 Agent 名字。Wazuh 要求 Agent 名不能带空格和特殊符号下划线可以用但像 node 01 这种带空格的绝对不行。最后看 Server 端 /var/ossec/etc/client.keys 里有没有生成对应条目。如果没有先重启 wazuh-manager 再看。4.3 Filebeat 连不上 Indexer查证书和地址Filebeat 的作用是转发事件连不上 Indexer 时最典型的现象是 Dashboard 里 Security events 模块一片空白但 Agent 显示在线。排查主要看journalctl -u filebeat -n 50 --no-pager常见错误是 x509: certificate signed by unknown authority说明 Filebeat 用的 CA 和 Indexer 的 CA 不是同一个。解决方法是保证 /etc/filebeat/certs/root-ca.pem 与 /etc/wazuh-indexer/certs/root-ca.pem 内容一致重新拷贝后重启 filebeat。另一种是 output 地址错误。检查 /etc/filebeat/filebeat.yml 里 hosts 是否写成了 https://localhost:9200而你单独改过主机名解析。建议直接用 https://wazuh-indexer:9200保持和证书 CN 一致避免本机跟远程解析对不上。4.4 Dashboard 打不开或者登录报 401Dashboard 默认监听 443如果机器上以前装过 Nginx 或别的 Web 服务占用了 443Dashboard 会启动失败日志里能看到 address already in use。这种情况先把旧服务停掉或者改 Wazuh Dashboard 的端口配置文件在 /etc/wazuh-dashboard/opensearch_dashboards.yml 里的 server.port。登录报 401 或者 Invalid credentials最常见原因是默认密码被人改过了或者快速安装脚本在最后一步自动换了密码。如果密码忘了用官方工具重置bash /usr/share/wazuh-indexer/plugins/opensearch-security/tools/wazuh-passwords-tool.sh -u admin -p 你的新密码改了之后要同步改 /etc/filebeat/filebeat.yml 和 Dashboard 配置里的密码否则 Filebeat 会拒绝访问索引Dashboard 登录也会不稳定。5. Agent 部署与验证装完不代表能用5.1 客户端安装的正确姿势Agent 和被监控主机之间是 C/S 模式Agent 需要装在每台被监控的机器上。用环境变量传 Server 地址和 Agent 名是官方推荐而且最少出错的方式curl -s https://packages.wazuh.com/4.x/apt/wazuh.gpg | sudo apt-key add - echo deb https://packages.wazuh.com/4.x/apt/ stable main | sudo tee /etc/apt/sources.list.d/wazuh.list sudo apt update sudo WAZUH_MANAGER192.168.1.100 WAZUH_AGENT_NAMEapp-server-01 apt install wazuh-agent注意 Ubuntu 20.04 以上不要再直接用 apt-key add会报 deprecated 警告按 3.2 的方式用 keyrings 目录导入。Agent 安装完成后会自动注册并启动不用手动 exec 密钥这一代版本比 3.x 时代用 manage_agents 一条条敲密钥方便太多了。5.2 验证三步走从系统层面看 Agent 是否真正“通”了验证不能只看 Dashboard 上的绿色点。我有一套标准三步第一步系统层面看进程。systemctl status wazuh-agent 必须显示 active (running)。第二步看日志。tail -f /var/ossec/logs/ossec.log出现 Connected to the server 字样才算注册成功。如果一直出现 Unable to connect to server多半是 Server 端的 1514/1515 端口没开或者 Server 的防火墙拦了。第三步功能层面验证。在 Dashboard 的 Agents 页面看到该 Agent 状态为 Active并且点进去能看到至少一条最近事件。三步都过才能说这台 Agent“真正通了”。只看 Dashboard 的绿点容易被缓存状态骗过去。5.3 触发一条测试告警这里分享一个特别实用的验证小技巧装好 Agent 后往系统日志里写一条明显的内容然后在 Dashboard 里搜索确认。logger wazuh test alert - FIM and log collection check这条命令会往 syslog 或 journal 里写一条日志Wazuh 的日志收集器会把它转发到 Indexer。几分钟后去 Dashboard 的 Discover 页面搜索 wazuh test alert如果能搜到端到端链路就完全打通。如果没有按顺序排查Agent 有没有收日志看 ossec.log、Filebeat 有没有转发看 filebeat 日志、Indexer 有没有入索引用 curl 查索引列表。这样一条链走下来问题一定定位到具体环节。6. 装完还有几件容易忽略的小事6.1 默认密码和密钥一定要改测试环境无所谓但如果你要把 Wazuh 用在任何真实场景第一件事就是改默认凭据Dashboard 的 admin/admin 必须改。内部用户 wazuh-wui 是 API 调用用户也要改。Filebeat 配置文件里埋着索引器用户名密码改的时候别漏。用官方 wazuh-passwords-tool.sh 可以一次性把所有内部用户密码改掉但前提是知道当前密码。最稳妥的顺序是先用 admin/admin 登录 Indexer 安全插件重置 admin 密码再同步其他服务里的密码配置。6.2 磁盘增长是个隐形杀手事件数据会持续写入 Indexer如果不管很快会占满磁盘。Wazuh 4.x 自带的 ISMIndex State Management策略默认会做索引轮转和删除但默认保留天数不一定符合你的合规要求。我建议装完立刻检查索引策略路径在 Dashboard 的 Indexer Management 里的 State management policies。如果数据量特别大可以按天创建索引并设置生命周期比如保留 30 天。删除过期索引用curl -k -u admin:密码 https://localhost:9200/.wazuh-alerts-* -X DELETE注意只删你自己确认过、确定过期不用的业务索引系统索引一定别动。6.3 升级前必须做的事Wazuh 的版本升级体验谈不上好每次升级我都要做三件事备份证书目录和 /var/ossec/etc/client.keys。备份 Filebeat 和 Dashboard 的配置文件。记下当前版本 Indexer 数据目录大小评估是否需要清理旧索引。官方推荐用升级脚本但我更习惯手动升级先升级 Indexer确认集群 health 正常再升 Server再升 Filebeat最后 Dashboard。永远不要在 Indexer 还没起来的时候就升级 Dashboard否则可能出现版本号不兼容的问题Dashboard 一直报版本不匹配。7. 最后分享几点个人体会装 Wazuh 这件事认真说起来不复杂但每一步都有隐藏的地雷。很多人失败不是因为官方文档写得差而是因为跳过了环境准备直接跑脚本。主机名的三个解析、内核参数、证书权限、端口放行这四样东西检查到位后续基本不会有大问题。我在实际踩坑过程中还有一个习惯每次安装前都先把系统状态打一个快照。不管是虚拟机快照还是云平台镜像多花两分钟备份就能在排错失败后一键还原。尤其是证书生成和分发阶段反复重试会导致目录里的文件混合新旧证书相互覆盖这种状态比干干净净的失败更让人头疼。如果你正在被某个报错卡住建议先对照第 4 节的速查表过一遍大多数问题都能在里面找到影子。装完过后也别忘了 6.2 里的索引保留策略这是很多人装完之后第一个踩的长效坑。Wazuh 这几年功能迭代很快Agent 侧的配置和管理也一直在简化多动手试几遍比反复看理论文档管用得多。
Wazuh 安装实战指南：从架构解析到高频报错排查
装 Wazuh 这种事属于“文档写得挺好但照着抄还是会翻车”的典型。我前前后后在生产环境和小规模测试环境里装过不下十次从 4.3 一路装到 4.7踩过的坑五花八门端口被占、证书权限不对导致服务起不来、Agent 死活注册不上、一升级就全校报错全都遇到过。这篇指南把 Wazuh 安装全流程拆开专门讲哪些地方容易出事、出事之后怎么定位。Wazuh 是什么一句话开源的统一安全监控平台整合了 HIDS主机入侵检测、SIEM 事件收集以及基础的 XDR 能力。装好之后它能在 Linux/Windows 主机上收集日志、做文件完整性监控FIM、检测 rootkit、跑漏洞扫描把所有数据汇总到一个看板里统一展示。适合什么人看刚接触安全基础设施的运维、准备用 Wazuh 替代商业 SIEM 的团队以及已经被安装报错折磨了一两天还没装成的新手。下面这些内容全部来自真实环境不是照着官方文档念一遍。1. 动手之前先搞清楚 Wazuh 的架构和版本脾气1.1 三个组件的分工决定了你的排错方向Wazuh 不像 Nginx 那样一个包装完就结束。它由三大部分组成官方命名分别是 Wazuh Indexer、Wazuh Server、Wazuh DashboardWazuh Indexer数据存储与检索层底层是 OpenSearch负责保存告警和事件数据同时维护索引模板。Wazuh Server核心管理节点里面又包含 Manager进程叫 wazuh-manager监听 Agent 通信和 Filebeat负责把分析后的事件转发到 Indexer。Wazuh Dashboard可视化层底层是 OpenSearch Dashboards 的定制版提供 Web 界面和 API。这三者之间的联动是Agent 把日志推给 Server 的 1514 端口Server 里 wazuh-analysisd 分析后写入本地 socketFilebeat 再从 socket 读取数据发送到 Indexer 的安全索引里Dashboard 负责查询展示。所以一旦你遇到“Agent 在线但看板没数据”问题十有八九出在 Filebeat 到 Indexer 这一段而不是 Agent 本身。把这些组件在脑子里串成一条链路后面排错会快非常多。我第一次装的时候不知道这个关系Agent 明明显示 active可看板里一条告警都没有硬是查了一下午才发现是 Filebeat 的证书路径写错了。1.2 版本必须对齐这是最容易忽略的硬性约束官方文档里写得很明确所有组件必须使用相同的主版本并且在安装脚本和仓库配置里必须绑定准确的版本号不能只写一个 4.x 就完事。举例来说2024 年之后很多教程还停留在 4.5、4.6 的命令如果照抄用 4.7 的方式生成了证书却去装 4.5 的索引器包大概率出现证书校验失败或者索引模板版本不兼容。我的做法是安装前先到官方 release 页面确认当前最新稳定版本然后把安装命令里的版本号写死比如curl -sO https://packages.wazuh.com/4.7/wazuh-install.sh这样至少保证脚本、工具、仓库用的是同一套版本逻辑。等你确认这套版本组合跑通了再考虑锁仓或升级别在安装阶段给自己埋不稳定的种子。1.3 部署形态先问自己“我到底要装什么”有三种常见装法单机一体化Indexer、Server、Dashboard 装在同一台机器上官方 quickstart 就是干这个的。适合测试环境、学习环境、小规模生产环境。分布式Indexer 集群三个节点Server 和 Dashboard 分开部署。适合更大规模或者高可用需求。只装 Server 和 Agent 做纯日志收集不装 Dashboard纯命令行管理这个场景比较少见一般是有已有可视化平台的团队才会这么干。如果你只是自己体验我强烈建议先走单机一体化。原因很实在组件越多排错变量越多一次只引入一个变量才是合理的排查策略。等单机跑通了再拆分布式也不迟。2. 环境准备资源、系统与网络这三样别省2.1 硬件资源官方最低配置是能跑不是能好好跑官方对单机部署的建议是 4GB 内存、2 核 CPU、30GB 硬盘。我实测下来4GB 内存真的只是“能装起来”一旦 Agent 开始持续上报事件OpenSearch 的 JVM 堆我一般给 1GB加上系统本身内存很快吃满然后出现各种莫名其妙的 OOM。我现在的小规模生产环境用的是 8GB 内存、4 核、100GB 硬盘稳定多了。如果你只有 4GB可以加 2GB swap 兜底装好后把 Indexer 的堆内存调小一点在 /etc/wazuh-indexer/opensearch.yml 里加一行opensearch.heap.size: 1gswap 的作用是兜底不是万能的频繁换页会让查询变慢但总比进程直接被 OOM killer 杀掉强。内存不足时还会伴随另一个现象Indexer 启动到一半就退出journalctl 里能看到 killed process 的提示。2.2 系统版本Ubuntu 22.04 是最省心的选择官方支持很多发行版但我的建议非常朴素能上 Ubuntu 22.04 就上 Ubuntu 22.04。它的系统包版本比较新OpenSearch 和依赖基本不会出现 libc 版本太老这类问题。CentOS 7 已经 EOL别再用了RHEL 8 和 9 官方支持但 Red Hat 系在安装 OpenSearch 时经常遇到 SELinux 权限问题虽然能解但没必要给自己加难度。还有一个经常被忽略的点装之前把系统时间校准一下。时钟漂移会导致 TLS 证书验证失败表现是浏览器访问 Dashboard 时提示证书无效组件之间通信也不正常。用 chrony 或 NTP 同步一下一劳永逸。2.3 主机名解析这一步不做quickstart 大概率失败这是我在多台机器上验证过的最常见的“卡死点”。Wazuh 的安装脚本和默认配置使用三个固定主机名去解析节点地址wazuh-indexer、wazuh-server、wazuh-dashboard。如果你的 DNS 里没有这三个 A 记录或者没写进 /etc/hosts脚本会在“Searching for the indexer...”这一步卡住很久然后报错退出。单机部署最简单的方式是在 /etc/hosts 里加三行192.168.1.100 wazuh-indexer 192.168.1.100 wazuh-server 192.168.1.100 wazuh-dashboard把 IP 换成这台机器自己的局域网 IP 即可。很多教程不强调这一点导致读者卡在安装流程的最早阶段。就算你用 quickstart 脚本执行前也必须先加好这些解析别跳过去。2.4 内核参数和文件描述符OpenSearch 的“体检项”OpenSearch 启动时有三个硬性前置条件不满足会直接拒绝启动vm.max_map_count 至少 262144。大部分系统默认值是 65530必须调大。文件描述符限制至少要 65535。如果有 systemd 管理的服务还要处理 memory lock 限制。调 vm.max_map_count 用sysctl -w vm.max_map_count262144 echo vm.max_map_count262144 /etc/sysctl.conf sysctl -p文件描述符在 systemd 服务里配更可靠。直接编辑服务单元或者用 systemctl edit wazuh-indexer添加 LimitNOFILE65535 和 LimitMEMLOCKinfinity然后 systemctl daemon-reload。这里有个经验不要在终端里只跑 ulimit -n 改了就说 OK服务是 systemd 拉起的终端里的 ulimit 只对当前 shell 生效跟服务无关。3. 完整安装流程一步步来顺便把坑踩一遍3.1 方式一Quickstart 一键脚本适合体验官方一键脚本确实快但它有个前提机器必须是干净的没有装过任何 Wazuh 组件也不能残留旧的证书目录。命令很简单curl -sO https://packages.wazuh.com/4.7/wazuh-install.sh bash wazuh-install.sh脚本会自己生成证书、装全部组件、最后打印管理员密码。看起来非常美好但实际执行时最可能碰到的第一个报错是“The certificates were not generated”或类似提示。原因一般是主机名没解析好或者磁盘空间不足按 2.3 先补 hosts清掉无用文件再重跑。quickstart 还有个隐藏的坑它不擅长升级。之后如果你想升级版本官方文档明确要求把旧版本彻底卸载再跑新版脚本这意味着数据得提前备份。所以如果是有明确生产计划的项目我更推荐手动装。3.2 方式二手动分组件安装推荐手动装听起来麻烦其实只是多打几条命令但对每一层的控制力完全不一样。先添加 Wazuh 仓库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这一步在 Ubuntu 20.04 和 22.04 上我踩过一次坑如果没有先创建 /usr/share/keyrings 目录后面 apt update 会一直报“The following signatures couldnt be verified”。解决方式就是先建目录再把权限改成 644最后在 /etc/apt/sources.list.d/wazuh.list 里用 signed-by 指过去deb [signed-by/usr/share/keyrings/wazuh.gpg] https://packages.wazuh.com/4.x/apt/ stable main接下来安装 Indexer。先装包再改配置 /etc/wazuh-indexer/opensearch.yml单节点场景至少要保证这几行正确network.host: 0.0.0.0 node.name: node-1 cluster.initial_master_nodes: node-1 discovery.type: single-node plugins.security.disabled: false plugins.security.ssl.transport.pemcert_filepath: /etc/wazuh-indexer/certs/wazuh-indexer.pem plugins.security.ssl.transport.pemkey_filepath: /etc/wazuh-indexer/certs/wazuh-indexer-key.pem plugins.security.ssl.transport.pemtrustedcas_filepath: /etc/wazuh-indexer/certs/root-ca.pem plugins.security.ssl.http.pemcert_filepath: /etc/wazuh-indexer/certs/wazuh-indexer.pem plugins.security.ssl.http.pemkey_filepath: /etc/wazuh-indexer/certs/wazuh-indexer-key.pem plugins.security.ssl.http.pemtrustedcas_filepath: /etc/wazuh-indexer/certs/root-ca.pem这里最容易犯的错是漏掉 plugins.security.disabled: false或者把证书路径写成了相对路径。OpenSearch 安全插件加载的是绝对路径写错了它不会立刻报错而是初始化安全配置的时候才暴露。3.3 证书生成与分发最考验耐心的一步Wazuh 组件之间全部走 TLS 加密通信证书必须包含节点的主机名和 IP。生成方法官方提供了脚本curl -sO https://packages.wazuh.com/4.7/wazuh-certs-tool.sh bash wazuh-certs-tool.sh -A-A 参数表示生成所有节点的证书。执行完会在当前目录生成一个 wazuh-certificates 文件夹里面有 root-ca.pem、root-ca.key以及每个节点对应的 .pem 和 -key.pem。分发证书时最常见的坑是权限。比如 Indexer 要求证书所有者是 wazuh-indexer 用户否则启动直接报 Permission denied。我的标准动作是mkdir -p /etc/wazuh-indexer/certs cp /path/to/wazuh-certificates/*.pem /etc/wazuh-indexer/certs/ cp /path/to/wazuh-certificates/wazuh-indexer-key.pem /etc/wazuh-indexer/certs/ chown -R wazuh-indexer:wazuh-indexer /etc/wazuh-indexer/certs chmod 500 /etc/wazuh-indexer/certs chmod 400 /etc/wazuh-indexer/certs/*.keyServer 端要装 Filebeat证书目录是 /etc/filebeat/certs文件至少是 644运行用户是 root 没问题。Dashboard 同理certs 目录要 chown 给 wazuh-dashboard 用户。网上很多帖子看到 Permission denied 就以为是系统权限问题其实真相就是证书文件的所有者没配对。服务是 systemd 管理的运行用户不是 root读不到 root 的 600 文件就这么简单。3.4 启动顺序和初始化顺序错了会连环报错手动装完以后启动顺序有讲究先 Indexer确认验证通过再 Server再 Filebeat最后 Dashboard。如果先启动 Dashboard它只会一直重试连接 Indexer日志刷屏意义不大。Indexer 起来之后还有一步初始化安全配置很多人会漏掉cd /usr/share/wazuh-indexer/bin/ bash ./wazuh-indexer-security-init.sh这个脚本会创建内置用户和默认密码 admin/admin。如果没有执行这一步Dashboard 无论如何都连不上 Indexer日志里全是 authentication 相关的报错。执行成功后用这条命令验证集群状态curl -k -u admin:admin https://localhost:9200/_cluster/health?pretty看到 status 为 green 或者至少 yellow说明 Indexer 就绪。如果返回 red去看日志 journalctl -u wazuh-indexer -n 50 --no-pager基本都是 2.4 提到的内核参数问题或者堆内存不够。4. 我把高频报错整理成了速查表这一节是全文的核心我把反复遇见的报错、现象、原因和解决办法整理成一个速查表建议直接收藏以后装 Wazuh 时对照。4.1 服务起不来先查内核参数和证书报错现象常见原因解决办法Indexer 启动失败日志有 bootstrap checks failedvm.max_map_count 不够sysctl -w vm.max_map_count262144并写入 sysctl.confIndexer 报 memory locking requested for mlockall but is not allowedLimitMEMLOCK 未放开systemctl edit wazuh-indexer加 LimitMEMLOCKinfinity然后 daemon-reloadDashboard 起不来日志是 Permission denied证书目录权限或 owner 不对按 3.3 重新 chownkey 文件设为 400目录至少 500一键脚本跑到一半失败主机名没解析、磁盘满、已有旧组件补 /etc/hosts清磁盘卸载旧组件后再重跑4.2 Agent 注册不上九成是网络和名字问题Agent 安装完成后需要执行注册命令类似这样sudo WAZUH_MANAGER192.168.1.100 WAZUH_AGENT_NAMEubuntu-node-01 apt install wazuh-agent注册不上通常表现在 /var/ossec/logs/ossec.log 里反复出现 Unable to connect to server 或 Invalid agent name。排查顺序是先确认 Server 的 1514、1515 端口能从 Agent 这台机器访问。用 nc -zv 192.168.1.100 1514 试一下。防火墙不开端口是我见过最多的问题ufw 默认只放行 OpenSSH 的更是一抓一大把。单机测试图省事可以直接 ufw allow 1514/tcp 和 1515/tcp生产环境记得用安全组规则精确放行。再看 Agent 名字。Wazuh 要求 Agent 名不能带空格和特殊符号下划线可以用但像 node 01 这种带空格的绝对不行。最后看 Server 端 /var/ossec/etc/client.keys 里有没有生成对应条目。如果没有先重启 wazuh-manager 再看。4.3 Filebeat 连不上 Indexer查证书和地址Filebeat 的作用是转发事件连不上 Indexer 时最典型的现象是 Dashboard 里 Security events 模块一片空白但 Agent 显示在线。排查主要看journalctl -u filebeat -n 50 --no-pager常见错误是 x509: certificate signed by unknown authority说明 Filebeat 用的 CA 和 Indexer 的 CA 不是同一个。解决方法是保证 /etc/filebeat/certs/root-ca.pem 与 /etc/wazuh-indexer/certs/root-ca.pem 内容一致重新拷贝后重启 filebeat。另一种是 output 地址错误。检查 /etc/filebeat/filebeat.yml 里 hosts 是否写成了 https://localhost:9200而你单独改过主机名解析。建议直接用 https://wazuh-indexer:9200保持和证书 CN 一致避免本机跟远程解析对不上。4.4 Dashboard 打不开或者登录报 401Dashboard 默认监听 443如果机器上以前装过 Nginx 或别的 Web 服务占用了 443Dashboard 会启动失败日志里能看到 address already in use。这种情况先把旧服务停掉或者改 Wazuh Dashboard 的端口配置文件在 /etc/wazuh-dashboard/opensearch_dashboards.yml 里的 server.port。登录报 401 或者 Invalid credentials最常见原因是默认密码被人改过了或者快速安装脚本在最后一步自动换了密码。如果密码忘了用官方工具重置bash /usr/share/wazuh-indexer/plugins/opensearch-security/tools/wazuh-passwords-tool.sh -u admin -p 你的新密码改了之后要同步改 /etc/filebeat/filebeat.yml 和 Dashboard 配置里的密码否则 Filebeat 会拒绝访问索引Dashboard 登录也会不稳定。5. Agent 部署与验证装完不代表能用5.1 客户端安装的正确姿势Agent 和被监控主机之间是 C/S 模式Agent 需要装在每台被监控的机器上。用环境变量传 Server 地址和 Agent 名是官方推荐而且最少出错的方式curl -s https://packages.wazuh.com/4.x/apt/wazuh.gpg | sudo apt-key add - echo deb https://packages.wazuh.com/4.x/apt/ stable main | sudo tee /etc/apt/sources.list.d/wazuh.list sudo apt update sudo WAZUH_MANAGER192.168.1.100 WAZUH_AGENT_NAMEapp-server-01 apt install wazuh-agent注意 Ubuntu 20.04 以上不要再直接用 apt-key add会报 deprecated 警告按 3.2 的方式用 keyrings 目录导入。Agent 安装完成后会自动注册并启动不用手动 exec 密钥这一代版本比 3.x 时代用 manage_agents 一条条敲密钥方便太多了。5.2 验证三步走从系统层面看 Agent 是否真正“通”了验证不能只看 Dashboard 上的绿色点。我有一套标准三步第一步系统层面看进程。systemctl status wazuh-agent 必须显示 active (running)。第二步看日志。tail -f /var/ossec/logs/ossec.log出现 Connected to the server 字样才算注册成功。如果一直出现 Unable to connect to server多半是 Server 端的 1514/1515 端口没开或者 Server 的防火墙拦了。第三步功能层面验证。在 Dashboard 的 Agents 页面看到该 Agent 状态为 Active并且点进去能看到至少一条最近事件。三步都过才能说这台 Agent“真正通了”。只看 Dashboard 的绿点容易被缓存状态骗过去。5.3 触发一条测试告警这里分享一个特别实用的验证小技巧装好 Agent 后往系统日志里写一条明显的内容然后在 Dashboard 里搜索确认。logger wazuh test alert - FIM and log collection check这条命令会往 syslog 或 journal 里写一条日志Wazuh 的日志收集器会把它转发到 Indexer。几分钟后去 Dashboard 的 Discover 页面搜索 wazuh test alert如果能搜到端到端链路就完全打通。如果没有按顺序排查Agent 有没有收日志看 ossec.log、Filebeat 有没有转发看 filebeat 日志、Indexer 有没有入索引用 curl 查索引列表。这样一条链走下来问题一定定位到具体环节。6. 装完还有几件容易忽略的小事6.1 默认密码和密钥一定要改测试环境无所谓但如果你要把 Wazuh 用在任何真实场景第一件事就是改默认凭据Dashboard 的 admin/admin 必须改。内部用户 wazuh-wui 是 API 调用用户也要改。Filebeat 配置文件里埋着索引器用户名密码改的时候别漏。用官方 wazuh-passwords-tool.sh 可以一次性把所有内部用户密码改掉但前提是知道当前密码。最稳妥的顺序是先用 admin/admin 登录 Indexer 安全插件重置 admin 密码再同步其他服务里的密码配置。6.2 磁盘增长是个隐形杀手事件数据会持续写入 Indexer如果不管很快会占满磁盘。Wazuh 4.x 自带的 ISMIndex State Management策略默认会做索引轮转和删除但默认保留天数不一定符合你的合规要求。我建议装完立刻检查索引策略路径在 Dashboard 的 Indexer Management 里的 State management policies。如果数据量特别大可以按天创建索引并设置生命周期比如保留 30 天。删除过期索引用curl -k -u admin:密码 https://localhost:9200/.wazuh-alerts-* -X DELETE注意只删你自己确认过、确定过期不用的业务索引系统索引一定别动。6.3 升级前必须做的事Wazuh 的版本升级体验谈不上好每次升级我都要做三件事备份证书目录和 /var/ossec/etc/client.keys。备份 Filebeat 和 Dashboard 的配置文件。记下当前版本 Indexer 数据目录大小评估是否需要清理旧索引。官方推荐用升级脚本但我更习惯手动升级先升级 Indexer确认集群 health 正常再升 Server再升 Filebeat最后 Dashboard。永远不要在 Indexer 还没起来的时候就升级 Dashboard否则可能出现版本号不兼容的问题Dashboard 一直报版本不匹配。7. 最后分享几点个人体会装 Wazuh 这件事认真说起来不复杂但每一步都有隐藏的地雷。很多人失败不是因为官方文档写得差而是因为跳过了环境准备直接跑脚本。主机名的三个解析、内核参数、证书权限、端口放行这四样东西检查到位后续基本不会有大问题。我在实际踩坑过程中还有一个习惯每次安装前都先把系统状态打一个快照。不管是虚拟机快照还是云平台镜像多花两分钟备份就能在排错失败后一键还原。尤其是证书生成和分发阶段反复重试会导致目录里的文件混合新旧证书相互覆盖这种状态比干干净净的失败更让人头疼。如果你正在被某个报错卡住建议先对照第 4 节的速查表过一遍大多数问题都能在里面找到影子。装完过后也别忘了 6.2 里的索引保留策略这是很多人装完之后第一个踩的长效坑。Wazuh 这几年功能迭代很快Agent 侧的配置和管理也一直在简化多动手试几遍比反复看理论文档管用得多。 
