Wazuh这套东西，说好装也好装，一条官方脚本跑完就能看到仪表板；说难装也难装，生产环境里拆成三个组件部署时，每个环节都能把你卡上半天。群里天天有人问“为什么dashboard打不开”“为什么agent一直显示Disconnected”，十有八九都是安装和初始配置阶段埋下的雷。这篇文章是我自己从测试机到生产环境反复装了多次之后整理出来的踩坑记录，不吹不黑，全是实际操作中验证过的经验。
整个指南会覆盖这么几条线：装之前怎么规划部署形态和资源，软件包的获取和安装细节，三个组件（manager、indexer、dashboard）之间的配置联动，以及agent接入时最容易出错的地方。配了排查表和重装清理建议，直接把能避开的坑全部提前标记出来。
1. 装之前先想明白三件事
1.1 Wazuh到底是由什么组成的
很多人第一次接触Wazuh，上来就想“装一个”。但它不是一个单体软件，而是一套由多个组件拼起来的系统。想象一下你在一栋大楼里做安保：门口的闸机是agent，保安监控室是manager（负责收数据、分析、下发策略），监控录像存储和检索系统是indexer（专门存日志和做全文搜索），而保安面前的那块大屏幕就是dashboard（可视化界面）。
具体到进程层面：agent装在被监控的服务器上，负责采集系统日志、文件完整性信息、漏洞数据，然后通过加密通道推给manager。manager干的是重活，事件关联分析、告警规则匹配都在这台机器上完成。indexer组件的角色是把处理好后的数据做索引和存储，对外暴露9200端口供检索使用。最后dashboard是面向人的入口，浏览器访问443端口，登录进去看各种告警大屏和安全分析报表。
有不少教程为了省事，会把indexer和dashboard装在同一台机器上，甚至和manager叠在一起。这种All-in-One形态适合测试环境，但生产环境我强烈建议分开部署。原因很简单：分开之后，升级manager不会影响检索服务，某个组件崩了也不会全盘跪掉。而且indexer本身就是个吃资源的大户，如果和manager挤一台小内存机器上，两个进程会互相抢内存，直接导致OOM（内存耗尽）甚至服务反复重启。
1.2 部署形态怎么选
选择部署形态之前，先明确你的场景是什么。
如果是个人学习、在家里的虚拟机里面跑一跑，或者公司内部搭个试用环境验证功能，那All-in-One脚本安装是最高效的选择。官方一行命令就能装完，默认配置即可跑起来。注意，这里说的“跑起来”是指功能基本可用，但性能和稳定性是打了折扣的。
如果是要监控二三十台生产服务器，建议把Wazuh拆成两条线：一条是manager独立部署，另一条是indexer和dashboard合在一起。这样agent数据进来时，manager的负载和indexer的存储压力不会互相影响，即使数据量突然增加导致indexer变慢，也不会拖垮agent的数据上报。
如果规模更大，比如要管上百台机器、每天日志量以GB甚至TB级别增长，那就老老实实把indexer做成三节点集群，manager按区域或业务拆多个，前面再架一层负载均衡。这个级别的部署已经有专门的架构师在操盘了，这里不多展开。
关于All-in-One的误区我也得说一句：很多新手以为All-in-One就是“官方推荐的正式形态”，其实恰好相反，它只是官方为了降低体验门槛推出的快捷方式。换句话说，它照顾的是“先跑起来看看是什么东西”的需求，而不是“长期稳定承载业务”的需求。
1.3 硬件配额别拍脑袋，按官方基线来
Wazuh官方给过一份硬件配置建议表，上面写得很清楚：All-in-One部署最低要求是4GB内存、2核CPU，但实际上如果你真的只用4GB跑，装完之后内存占用率就已经冲到80%以上，稍微查几个索引页面就会卡顿，如果数据量上来，OOM几乎是必然的。
我个人的建议是，测试环境All-in-One至少给8GB内存、4核CPU，磁盘预留50GB以上。如果indexer和manager分开部署，manager建议4GB内存起步，indexer则建议8GB起步。别心疼那几百GB的磁盘，Wazuh存储的是日志和安全事件，这类数据涨得飞快，你甚至可以按“每天产生日志量 x 30天 x 1.5倍膨胀系数”来粗算磁盘需求。
另外有个特别容易被忽略的参数：vm.max_map_count。Elasticsearch系的组件（Wazuh indexer基于Opensearch）对这个值有硬性要求，低于262144时启动会直接报错或者运行中崩溃。有的系统默认值只有65530，装完indexer之后一切正常，但过一段时间你会发现进程莫名其妙死了，去看日志才发现是map count耗尽。所以不管是哪台机器要跑indexer，都建议先把下面这段写进/etc/sysctl.conf，再执行sysctl -p让它生效：
vm.max_map_count=262144这个坑我栽过一次，后来养成了习惯，装之前先执行sysctl vm.max_map_count看一眼当前值。你可以直接用下面的命令临时修改，重启后依然有效需要写配置文件：
sudo sysctl -w vm.max_map_count=262144 echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf2. 安装过程和三种常用方式
2.1 在线安装：来自官方仓库的包
Wazuh的安装方式最常见的就是软件包安装。官方维护了YUM和APT仓库，安装过程非常直观。以RHEL系为例，先导入GPG密钥，再添加仓库文件，最后安装。CentOS系的命令我放在下面：
sudo rpm --import https://packages.wazuh.com/key/GPG-KEY-WAZUH cat <<EOF | sudo tee /etc/yum.repos.d/wazuh.repo [wazuh] gpgcheck=1 gpgkey=https://packages.wazuh.com/key/GPG-KEY-WAZUH enabled=1 name=EL-\$releasever - Wazuh baseurl=https://packages.wazuh.com/4.x/yum/ protect=1 EOFDebian系则用add-apt-repository的方式操作。仓库配好之后，manager、indexer、dashboard三个组件是各自独立的包，分别叫wazuh-manager、wazuh-indexer、wazuh-dashboard，想装哪个就装哪个。
这种方式的优势是很灵活，你可以自己决定哪些组件装在哪台机器上。而且后续升级只需要yum update wazuh-manager这种粒度精确的命令，不会把整个依赖树搅乱。但劣势也很明显：装完一个组件不等于装完整个系统，你还要手动配置证书、把filebeat的对接信息配上，任何一步出错，dashboard和indexer之间就连不通。
2.2 快速安装：官方脚本的便利与局限
官方提供了一套快速安装脚本，也就是wazuh-install.sh，可以一鼓作气把全部组件装好。官方文档里的命令大致是：
curl -sO https://packages.wazuh.com/4.7/wazuh-install.sh sudo bash wazuh-install.sh --generate-config-files sudo bash wazuh-install.sh --install这里有个值得注意的点：脚本执行完成后，终端会输出一个随机生成的dashboard管理员密码，这个密码只显示一次，记得第一时间保存。如果没有保存，后面想找回是比较麻烦的，得去wazuh-dashboard的包目录下翻配置文件，或者直接重置密码。
快速脚本本质上是在调用系统包管理器安装上述几个包，然后自动生成证书、自动启动服务、自动配置filebeat，半小时内就能看到一个可以访问的dashboard。看起来是美滋滋，但它有两个局限：
一是对系统的假设比较固定。它假设你的系统是干净的、没有残留的旧配置，而且端口没有被占用。如果之前装过失败的Wazuh或者残留了Opensearch的进程，脚本执行到一半确实可能卡住，我在后面“重装”那部分会详细讲怎么清理。
二是All-in-One模式下，它默认把每个组件都装在同一台机器上。如果你本来想组件分离部署，就不能用默认的--install参数一路走到底。不过官方脚本其实也支持先生成配置文件，再在各自机器上执行安装，只不过这一步需要你提前在config.yml里定义好每台机器的角色，操作难度比默认模式高一个档次。
2.3 离线安装：内网环境的备选方案
很多企业的生产环境是不允许直接访问外网的，这时候在线仓库方案失效。离线安装的核心思路就是先在有外网的机器上把需要的rpm或deb包全部下载下来，再拷贝到内网机器上。以RHEL系为例：
# 在外网机器上，将wazuh仓库相关包下载到本地目录 sudo yum install --downloadonly --downloaddir=/tmp/wazuh-packages wazuh-manager wazuh-indexer wazuh-dashboard filebeat然后把这些rpm包拷到目标机器的/tmp/wazuh-packages目录，执行yum localinstall *.rpm或者rpm -ivh *.rpm完成安装。需要注意的是，依赖包也得一并下载，最简单的办法是先用yum deplist查看依赖关系，把依赖包一并downloadonly下来。
离线安装最大的坑在于证书生成和配置文件分发。因为官方脚本会自动化处理证书流程，而手动离线安装时，你必须自己用wazuh-certs-tool.sh生成所有节点的证书，再手工分发到对应服务器的/etc/wazuh-indexer/certs、/etc/filebeat/certs、/etc/wazuh-dashboard/certs目录。证书的主机名如果和实际节点名对不上，启动服务时会有极其隐蔽的报错，这一块我在第3部分专门展开说。
3. 最容易翻车的六个环节
3.1 内存不足导致服务反复重启或进程消失
系统日志里大量出现Killed process，或者wazuh-manager.service运行几分钟后自动退出，最直接的原因就是内存不足。
Wazuh manager有一个比较关键的配置在/var/ossec/etc/ossec.conf里，其中<memory>标签控制agent事件队列使用的内存大小。默认配置在某些场景下偏保守，但也不建议盲目调大。如果你发现自己机器内存只有2GB，那正确操作不是去调配置，而是升级实例规格。Wazuh的agent事件默认会走内存队列，宁可丢弃一些非关键日志，也不要让系统进入OOM循环。
在部署之前用下面这条命令筛查一下当前机器的内存和加载情况是个好习惯：
free -h cat /proc/meminfo | grep CommitLimitCommitLimit如果明显低于实际物理内存，说明系统配置了overcommit限制，大内存申请会被拒绝，这种情况就算代码层面没bug，也会被系统“礼貌地”杀掉。
3.2 dashboard打不开或者502/503
装完dashboard之后，浏览器访问https://服务器IP，结果页面一直转圈或者直接报连接被拒绝，这是新手最常见的困惑之一。
第一件事，确认dashboard服务本身起来了没有：
sudo systemctl status wazuh-dashboard如果显示active (running)但页面还是打不开，检查端口监听：
sudo ss -tlnp | grep 443443端口没监听起来，大概率是启动时报错了。去日志文件/var/log/wazuh-dashboard/wazuh-dashboard.log翻一翻。常见报错是connect ECONNREFUSED 127.0.0.1:9200，意思很明确：dashboard连不上indexer的9200端口。
那为什么indexer起了却连不上？通常有两个原因。一是indexer的监听地址写死了localhost，外部连不进来；二是证书校验失败，也就是dashboard和indexer之间没有互相信任。后者最常见，后面我会单独讲。
3.3 证书问题：这套系统里最折磨人的点
Wazuh的组件之间全部用TLS双向认证通信，证书体系的复杂度高于一般Web应用。很多安装问题表面上看是“服务起不来”，根因全是证书不对。
Wazuh的证书工具会生成一套节点证书，里面包含node name标记。比如你的manager节点名字叫wazuh-manager，证书里也会带有这个标记。如果你在配置indexer的opensearch.yml时，node.name没有和证书里的主机名完全一致，indexer启动时会报：
ERROR: OpenSearch did not exit normally这个报错非常笼统，第一次遇到完全不知道问题在哪。我的排查方法是打开/var/log/wazuh-indexer/wazuh-indexer-cluster.log，看里面有没有unable to load certificate或者CertificateForOtherNameExtension字样。有的话，去/etc/wazuh-indexer/certs目录检查证书文件和目录权限。证书文件必须是640权限，属主必须和运行indexer的用户一致，否则进程在读取证书这一步就直接退出。
还有filebeat侧的证书问题。filebeat进程自己连不上indexer的9200时，dashboard页面会提示无法获取数据，但你不一定第一时间想到是filebeat的问题。排查路径是看/var/log/filebeat/filebeat日志，如果出现x509: certificate is valid for wazuh-indexer, not filebeat这类报错，说明filebeat拿着自己的客户端证书去当服务端证书验证，被indexer拒了。解决办法是检查filebeat配置中输出的host是否是indexer的IP，同时检查/etc/filebeat/certs里是否存在两个证书：一个是filebeat自身的证书，一个是对应CA证书，缺一不可。
3.4 端口占用劫持安装进程
Wazuh全家桶占用的端口大致是这样的：
| 组件 | 端口 | 用途 |
|---|---|---|
| wazuh-manager | 1514/TCP | agent上报日志 |
| wazuh-manager | 1515/TCP | agent注册 |
| wazuh-manager | 55000/TCP | API管理接口 |
| wazuh-indexer | 9200/TCP | 数据检索入口 |
| wazuh-dashboard | 443/TCP | Web访问 |
如果你机器上已经跑着其他Elasticsearch服务、Nginx或者Prometheus，这些端口很可能被占用。尤其是443和9200，这两个是运维日常高频使用端口。
排查端口占用很简单：
sudo ss -tulnp | grep -E '443|9200|1514|1515|55000'如果看到占用，要么把占用进程停掉，要么修改Wazuh配置改端口。改端口的复杂度会连锁反应到所有下游组件，比如manager改了端口，所有agent都要跟着改上报端口；dashboard改了端口，浏览器访问时就要带端口号，证书里的Common Name和IP对应关系也要调整。所以我的建议是：如果端口冲突，优先工程上解决端口占用问题，而不是修改Wazuh默认端口集。
3.5 SELinux和防火墙的流量拦截
在RHEL系上安装Wazuh，如果SELinux是Enforcing模式，默认策略可能拦截Wazuh的进程访问网络或者读写文件。观察到的现象是服务看着在跑，agent数据就是发不进来，调试了很久可能都没怀疑到SELinux头上。
一条缓解思路是把SELinux置为Permissive模式，先确认是不是它的锅：
sudo setenforce 0如果置为Permissive后一切正常，那基本可以断定是SELinux策略问题。这时候不要急着永久关闭SELinux，生产环境关SELinux是需要论证的。更好的方案是让Wazuh的二进制和库文件加载正确的策略，或者用ausearch去查具体的AVC denial记录，按记录去调整策略。当然，如果你这是一个内网测试环境，机器上不跑其他敏感服务，临时Permissive也不是不行，但记得至少把日志记录开着，方便回溯问题。
防火墙方面，云服务器额外要注意安全组层面的配置。有些云平台默认安全组只开放少数端口，你在机器上用iptables开了1514/1515，但云平台安全组没放行，agent数据依然进不来。这一层是最隐蔽的，因为iptables -L看着没问题，但你忘了上面的云平台控制面板。
3.6 agent注册后一直是Disconnected
agent装好之后，在dashboard里看到的连接状态如果始终是Disconnected，大概率是注册流程没走通。Wazuh agent注册是独立于日志上报的，它通过1515端口发起注册请求，然后manager返回一个钥匙，之后agent用这个钥匙走1514端口建立加密通道。
检查agent日志（通常在/var/ossec/logs/ossec.log）是一个切入步骤。常见的报错有两种：一种是ERROR: Invalid key，说明注册后密钥没正确写入agent配置，或者在manager上重复注册导致密钥不一致。另一种是ERROR: Cannot connect to server，说明1514端口网络不通，拿telnet或者nc直接测一下：
nc -vz 服务器IP 1514 nc -vz 服务器IP 1515如果端口通但仍Disconnected，建议在manager端跑：
sudo /var/ossec/bin/manage_agents -l查看agent列表和状态。只要密钥对得上，agent和manager之间的连接一般能起来。这里有个小细节：agent的配置文件ossec.conf里<server><address>指向的IP，必须和agent实际能访问的manager IP一致。很多时候你填的是内网IP，但agent在另一网段过不来，它就会一直循环重试，界面看就是永远连不上。
4. 常见问题排查表与实操心得
4.1 快速筛查问题定位表
我把安装过程中最常碰到的现象、排查路径和对应解法整理成了表格，你在遇到问题时按图索骥即可：
| 现象 | 排查范围 | 常见根因 | 解决思路 |
|---|---|---|---|
| wazuh-manager启动失败 | systemctl status、/var/ossec/logs/ossec.log | 内存不足、端口被占用 | 加大内存、释放端口 |
| dashboard连接拒绝 | ss -tlnp查443端口 | dashboard服务未启动、证书错误 | 看dashboard日志、重置证书 |
| dashboard能开但加载不了数据 | filebeat日志、indexer日志 | 证书不匹配、filebeat无数据接入 | 检查filebeat输出端和证书 |
| indexer启动退出 | /var/log/wazuh-indexer日志 | vm.max_map_count过小、证书错误 | 调整sysctl参数、重发证书 |
| agent连接不上 | /var/ossec/logs/ossec.log | 防火墙、密钥不对、IP填错 | 放行端口、重新注册agent |
| 仪表盘登录后一直loading | filebeat进程状态 | filebeat配置的indexer地址不通 | 检查connectivity和证书 |
| 系统高负载/卡顿 | top看进程 | 组件抢内存 | 拆分部署、加内存 |
这个表不是万能的，但能覆盖实验环境里90%以上启动问题。按照从上到下的顺序做排除，大部分安装问题会在前三个环节就水落石出。
4.2 重装和清理的正确姿势
Wazuh安装过程中如果某个环节失败了，很多人第一反应是“卸载重来”。但Java系的软件最大的特点就是卸载不干净，Wazuh也不例外。
如果你想彻底清掉一个失败的Wazuh安装，建议按下面顺序操作：
# 停止所有相关服务 sudo systemctl stop wazuh-manager wazuh-indexer wazuh-dashboard filebeat # 卸载软件包 sudo yum remove wazuh-manager wazuh-indexer wazuh-dashboard filebeat # 删除残留的配置和数据目录 sudo rm -rf /var/ossec /var/lib/wazuh-indexer /etc/wazuh-indexer /etc/filebeat /var/lib/filebeat /etc/wazuh-dashboard注意：/var/ossec目录下可能有你手工修改过的配置文件和密钥，如果只是重装测试环境，完全可以删；但如果是生产环境，请务必备份后再操作。另外，数据目录一旦删除就再也找不回历史日志了，操作前确认你确实不需要保留这些数据。
重装的时候还有个容易踩坑的点：如果之前的证书目录没有删干净，新装后的证书配置可能会读到旧的、无效的证书。所以别跳过rm -rf那一步，它治标也治本。
4.3 升级时先备份再动手
生产环境升级千万不要直接yum update wazuh-*一把梭。正确的做法是：
- 先备份manager的配置和密钥：
sudo tar czf wazuh-backup-$(date +%F).tar.gz /var/ossec/etc /var/ossec/queue/agents-keyindexer如果存有重要告警数据，做一份快照备份。云平台的话直接打磁盘快照，速度快副作用小。
逐个升级，顺序是indexer -> manager -> dashboard。升级完一个，看一眼对应服务状态，确认没问题再动下一个。
升级后如果dashboard显示版本不匹配，检查filebeat的版本是否和manager对齐。filebeat和manager之间是有严格版本匹配要求的，跨大版本升级时特别容易踩这个雷。
Wazuh每年的小版本更新很频繁，但并不是每个版本都必须追。如果你当前的版本用的是稳定的，没有CVE告警和重大bug影响你，完全可以等一两个小版本再跳升。每次升级前，去官方changelog里看一眼破坏性变更，比盲目更版本稳妥得多。
4.4 运维日常的几个小习惯
装好之后的日常运维，有几个小习惯能帮你省掉很多大坑。
定期检查磁盘使用率。Wazuh体系的日志增长是粗暴的，/var/ossec/logs下面会积累大量archives和警报日志，indexer的数据目录也会持续膨胀。建议至少每周执行一次df -h看磁盘水位。真等到磁盘满了，indexer会自动拒绝写入，然后告警链路全断。
日志轮转要提前配置。manager默认配置文件里有<logall>开关，如果要开启，建议同时开启日志轮转。轮转配置在/var/ossec/etc/ossec.conf里面，设置<daily_rolling>和<size_limit>，否则日志文件会单文件无限增长。
API连接信息要保存好。Dashboard的登录账号密码、API连接信息建议存到密码管理工具里。忘了密码虽然可以重置，但重置流程会涉及到重新生成各类安全配置，平白给自己找事。
5. 写在最后的几个实在建议
装Wazuh这套系统，心态上要对它有个预判：它不像装个Nginx那么手起刀落，更像是在玩一套需要各个零件互相咬合的积木。config、证书、端口、防火墙、内核参数，哪一环没对上，后面就会以具体问题的方式当场“回报”你。
如果你是我文章里提到的第一类场景（纯测试、学习），那All-in-One脚本跑起来先用着，边用边理解组件之间的关系，这是上手最快的方式。等需要进生产了，再参考第2部分的方案做拆分部署也不迟。
根据我个人经验，还有一件事值得单独说：Wazuh的社区文档其实写得挺全，但很多问题是文档没覆盖的，偏偏这些又是实战里最容易出现的。比如证书权限、比如实例规格过小导致的OOM、比如云平台安全组忘开端口。这些细节，官方文档默认“你已经会了”，而新手刚好死在“你默认我已经会了”这句话上。所以遇到问题时，不要只盯着软件层面的报错，也从系统层面、网络层面多想一层。
最后分享一个小技巧给已经在用的人：agent部署阶段，大批量接入时，先在manager上确认代理密钥有没有正常下发，再去挨个看agent的ossec.log。这样能让你从“一台台排查”变成“先看发行端再看接收端”，省下来的时间够你多喝一杯咖啡了。
