企业官网建设流程全解析

装 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 Dashboard：

• Wazuh Indexer：数据存储与检索层，底层是 OpenSearch，负责保存告警和事件数据，同时维护索引模板。
• Wazuh Server：核心管理节点，里面又包含 Manager（进程叫 wazuh-manager，监听 Agent 通信）和 Filebeat（负责把分析后的事件转发到 Indexer）。
• Wazuh Dashboard：可视化层，底层是 OpenSearch Dashboards 的定制版，提供 Web 界面和 API。

这三者之间的联动是：Agent 把日志推给 Server 的 1514 端口，Server 里 wazuh-analysisd 分析后写入本地 socket，Filebeat 再从 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: 1g

swap 的作用是兜底不是万能的，频繁换页会让查询变慢，但总比进程直接被 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_count=262144 echo 'vm.max_map_count=262144' >> /etc/sysctl.conf sysctl -p

文件描述符在 systemd 服务里配更可靠。直接编辑服务单元或者用 systemctl edit wazuh-indexer，添加 LimitNOFILE=65535 和 LimitMEMLOCK=infinity，然后 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 couldn't 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/*.key

Server 端要装 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 服务起不来：先查内核参数和证书

4.2 Agent 注册不上：九成是网络和名字问题

Agent 安装完成后，需要执行注册命令，类似这样：

sudo WAZUH_MANAGER='192.168.1.100' WAZUH_AGENT_NAME='ubuntu-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 打不开或者登录报 401

Dashboard 默认监听 443，如果机器上以前装过 Nginx 或别的 Web 服务占用了 443，Dashboard 会启动失败，日志里能看到 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_MANAGER='192.168.1.100' WAZUH_AGENT_NAME='app-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 自带的 ISM（Index 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 侧的配置和管理也一直在简化，多动手试几遍，比反复看理论文档管用得多。