企业官网建设流程全解析

Wazuh 4.x 到 5.0 迁移指南：全新安装路径与全量手动迁移清单

【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh

本文是 Wazuh 从 4.x 升级到 5.0 的迁移总纲，覆盖 Wazuh 官方迁移文档 docs/guide/migration/README.md 中列出的全部 13 篇迁移指南。读者将掌握 Wazuh 5.0 在安装路径、配置文件、内容管理模型上的破坏性变更，学会按照"备份 → 卸载 → 全新安装 → 手工迁移配置"的标准流程完成管理器配置、Agent 组、规则/解码器、SCA 策略、漏洞检测与基础设施组件的迁移，并能够应对迁移过程中的典型故障。

迁移总原则：没有就地升级路径

Wazuh 5.0 对管理器（Manager）做了深度重构：分析引擎被全新的 Wazuh Engine 取代，安装路径、系统用户、日志文件、配置文件格式全部发生变更。因此官方明确说明：

不存在从 4.x 管理器就地升级到 5.0 的路径。必须卸载 4.x 管理器，全新安装 Wazuh 5.0，再从迁移前的备份中恢复你的自定义配置。

以 manager-configuration-migration.md 中的对照表为例，5.0 的几项核心变化如下：

所有 4.x 配置、内容与模块的迁移，本质上都要围绕这套"全新目录 + 新格式 + 新内容模型"重新落位。

迁移标准流程

1. 在 4.x 管理器上备份配置：导出ossec.conf、internal_options.conf、local_internal_options.conf、api.yaml，以及自定义规则、解码器和列表（详见后文各小节）。
2. 卸载 4.x 管理器：按发行版官方文档卸载，这会移除 4.x 二进制和/var/ossec/目录。
3. 全新安装 5.0 管理器：安装到/var/wazuh-manager/，生成带默认配置的全新wazuh-manager.conf。
4. 手工应用配置变更：不要直接把 4.x 配置文件复制进 5.0 安装，而是以备份为参考，把自定义项逐条应用到 5.0 默认文件上。

迁移指南总览

下表是迁移文档集中列出的 13 篇指南及其适用范围：

管理器配置迁移：四大配置文件逐一对照

manager-configuration-migration.md 是本迁移集中最核心的实操指南，覆盖四个配置文件的变更。

1.ossec.conf→wazuh-manager.conf

主配置文件的文件名与 XML 根元素同时变更：

• 将全文的<ossec_config>替换为<wazuh_config>。
• <global>段大幅瘦身：5.0 的解析器只接受<agents_disconnection_time>与<agents_disconnection_alert_time>，其余元素会导致启动错误。必须移除<jsonout_output>、<alerts_log>、<logall>、<logall_json>、<update_check>，以及全部邮件相关选项（<email_notification>、<smtp_server>、<email_from>、<email_to>、<email_maxperhour>、<email_log_source>，邮件功能已整体移除，替代方案见 Mail forwarding and reporting）。另外，用于 Active Response 白名单的第二个<global>块（<white_list>）在 5.0 中被静默忽略，可直接删除。
• <remote>段移除<connection>元素：4.x 中<connection>secure</connection>的写法在 5.0 会导致启动错误——Agent 与管理器之间的通信默认全部走安全协议。仅保留<port>1514</port>与<protocol>tcp</protocol>。
• <auth>段保留，但需更新证书路径，例如<ssl_manager_cert>从/var/ossec/etc/sslmanager.cert改为/var/wazuh-manager/etc/sslmanager.cert（sslmanager.key同理）。
• 整段移除的配置块（部分导致启动错误，部分被静默接受）：

特别注意：4.x 的自定义规则与解码器不能通过向管理器复制 XML 文件来迁移。5.0 中内容通过引擎的内容管理系统进行管理与发布，详见 engine-introduction.md 与 engine 模块文档。

• <vulnerability-detection>保留但移除<index-status>：4.x 中的<index-status>yes</index-status>已删除，其余选项（<enabled>、<feed-update-interval>）原样保留。
• <indexer>段两处变更：一是<enabled>标志被移除，5.0 中 Indexer 连接始终激活；二是证书路径不再指向 Filebeat 证书目录，而是管理器自己的证书：

4.x：

<indexer> <enabled>yes</enabled> <hosts> <host>https://127.0.0.1:9200</host> </hosts> <ssl> <certificate_authorities> <ca>/etc/filebeat/certs/root-ca.pem</ca> </certificate_authorities> <certificate>/etc/filebeat/certs/wazuh-server.pem</certificate> <key>/etc/filebeat/certs/wazuh-server-key.pem</key> </ssl> </indexer>

5.0：

<indexer> <hosts> <host>https://127.0.0.1:9200</host> </hosts> <ssl> <certificate_authorities> <ca>/var/wazuh-manager/etc/certs/root-ca.pem</ca> </certificate_authorities> <certificate>/var/wazuh-manager/etc/certs/manager.pem</certificate> <key>/var/wazuh-manager/etc/certs/manager-key.pem</key> </ssl> </indexer>

5.0 安装器会自动生成带正确证书路径的<indexer>段；若手工应用配置，请确保路径与/var/wazuh-manager/etc/certs/下的实际证书一致。

2.internal_options.conf→wazuh-manager-internal-options.conf

4.x 中内部选项采用"双文件 + 优先级"机制：local_internal_options.conf（用户可编辑，优先级最高，升级时保留）在前，internal_options.conf（随包发布的系统默认值，每次升级覆盖）兜底。5.0 中管理器的双文件机制被废除：只有一个wazuh-manager-internal-options.conf，它继承了旧local_internal_options.conf的角色（用户自定义覆盖的唯一位置），系统默认值被硬编码进引擎，不再有回退文件。Agent 侧仍沿用 4.x 的双文件系统。

迁移时只保留在 5.0 中仍然有效的选项，大量选项已随引擎重写被移除，带入会引发启动错误。典型被移除项包括：

• analysisd.*全部选项（analysisd.default_timeframe、analysisd.stats_maxdiff、analysisd.rule_matching_threads、analysisd.alerts_queue_size、analysisd.debug等）——analysisd 已被 Wazuh Engine 取代；
• remoted.guess_agent_group——基于merged.mg校验和的组猜测机制在 5.0 中彻底移除，替代流程见 Agent groups migration；
• maild.strict_checking、maild.grouping、maild.full_subject、maild.geoip、monitord.sign、wazuh_download.enabled、dbd.reconnect_attempts、integrator.debug、wazuh_clusterd.debug等。

3.api.yaml

REST API 配置文件仍位于相对路径api/configuration/api.yaml（仓库中见 api/api/configuration/api.yaml），但 5.0 默认文件删除了若干选项：

• SSL 证书默认文件名变更：https.key从server.key改为manager.key，https.cert从server.crt改为manager.crt（与更名的系统用户保持一致）。使用自定义证书名的无需改动；依赖默认名的需要重命名证书或改配置。
• 移除https.ssl_protocol：管理器自动协商最佳协议。
• 移除experimental_features开关。
• upload_configuration简化：remote_commands（localfile/wodle_command）、limits.eps、integrations.virustotal等子段在 5.0 中不再有效，必须删除；仅保留agents.allow_higher_versions与indexer.allow。

4.cluster.json

cluster.json是控制集群行为的内部文件（仓库路径 framework/wazuh/core/cluster/cluster.json），不建议直接编辑，但如果你在 4.x 上改过它，需要知道以下变更。安装时会替换该文件，不要复制 4.x 版本，应以 5.0 默认文件为基准，只重新应用你改过的 interval 值。

• 集群同步文件列表变化：etc/rules/、etc/decoders/、etc/lists/不再通过集群文件同步机制从主节点向工作节点传播（自定义内容改由引擎内容系统分发）；excluded_files从ar.conf、ossec.conf变为wazuh-manager.conf。
• 新增 master intervals：sync_disconnected_agent_groups（默认 300 秒）、sync_disconnected_agent_groups_batch_size（默认 100）、sync_disconnected_agent_groups_min_offline（默认 600 秒）、sync_disconnected_agent_cluster_name_delay（默认 300 秒）、metrics_frequency（默认 600 秒）、metrics_bulk_size（默认 100）。
• 新增intervals.common块："common": { "active_response_polling": 30 }，控制 Active Response 状态检查的轮询间隔（秒），主、工作节点共用。

Agent 组迁移：注册即归属的新机制

agent-groups-migration.md 介绍了 5.0 中最易踩坑的变更之一。4.x 中，Agent 的组归属存储在管理器的global.db，共享组配置位于/var/ossec/etc/shared/（每个组目录含agent.conf与编译后的merged.mg）。5.0 中组配置仍位于相对路径etc/shared/（绝对路径变为/var/wazuh-manager/etc/shared/），但组归属不再由管理器推断：

1. 注册握手携带组：Agent 注册时把ossec.conf中<enrollment><groups>配置的组发给管理器，管理器的注册服务wazuh-manager-authd校验组并写入global.db。如果声明的组在管理器上不存在，注册被拒绝，Agent 无法连接。
2. 持久化：归属记录在global.db中，Agent 和管理器重启后仍保留，无需每次连接重发。
3. 重连：每次 keepalive 时管理器从global.db查组，找到则编译并推送该组共享配置；无组记录的 Agent 落入default组。

重要：4.x 中通过merged.mg校验和猜测组归属的机制（remoted.guess_agent_group）在 5.0 中已移除。没有配置组且global.db无历史记录的 Agent 会被放入default组。

迁移步骤概要：

1. 备份组配置：在 4.x 管理器上归档shared/下的组目录，排除运行时生成的merged.mg：

   cd /var/ossec/etc tar -cvzf /tmp/wazuh_groups_backup.tar.gz --exclude='*/merged.mg' shared/*/

   只迁移部分组时，把shared/*/替换为具体目录名。备份必须存放在能挺过重装的位置。

2. 在 5.x 恢复组配置（务必在连接任何 Agent 之前完成，否则组不存在的注册会被拒绝）：

   tar -xvzf /tmp/wazuh_groups_backup.tar.gz -C /var/wazuh-manager/etc/ chown -R wazuh-manager:wazuh-manager /var/wazuh-manager/etc/shared/

   恢复的agent.conf必须对 5.0 有效，任何 4.x 废弃选项都会导致共享配置编译失败。

3. 确认每个 Agent 配置了组：在 Agent 的ossec.conf中设置：

   <enrollment> <enabled>yes</enabled> <groups>group-name</groups> </enrollment>

   注意：4.x 仪表盘上显示有组并不代表组一定在ossec.conf里，请直接检查 Agent 文件。

4. 启动 Agent 并验证：5.0 起注册服务默认要求密码，先从管理器读取/var/wazuh-manager/etc/authd.pass并写入每个 Agent 的/var/ossec/etc/authd.pass（权限 640）；随后清除旧密钥重新注册：

   rm -f /var/ossec/etc/client.keys systemctl start wazuh-agent

   注册时 Agent 上报组，管理器写入global.db，下一次 keepalive 时管理器编译并推送对应组的共享配置。可用仪表盘Agents management → Summary或 API 验证：

   curl -k -X GET "https://<manager-ip>:55000/agents?agents_list=<agent-id>&select=group" \ -H "Authorization: Bearer $TOKEN"

典型故障与规避：Agent 声明了管理器上不存在的组时，日志出现ERROR: Invalid group: <group>. Unable to add agent。三种解法：① 先恢复组目录再重启 Agent 重注册；② 在仪表盘Agents management → Groups → Add new group手工建组（或POST /groups），再重启 Agent；③ 删掉 Agent 的<groups>标签使其落入default，之后再手工指派。对于落入default的 Agent，可在仪表盘Summary → Actions → Edit groups中指派，或通过 API 指派（PUT /agents/<id>/group/<name>，批量可循环调用）。注意PUT是"追加"组，若希望 Agent 只属于一个组，还需用DELETE /agents/<id>/group/default移除default。

引擎内容迁移：规则、解码器与 CDB 列表

5.0 的内容模型发生根本变化：规则、解码器、列表全部从"管理器上的 XML/文本文件"迁移为"引擎中的 YAML 资产"，并按integration为单位打包，经 wazuh-indexer 分发给引擎（内容管理器 CMSync 负责同步）。本仓库 src/engine 与 docs/ref/modules/engine/README.md 是这一新模型的实现与参考。

XML 解码器 → YAML 解码器

xml-decoders-migration.md 给出完整的等价关系表：

不支持的 XML 模式包括：<plugin_decoder>（插件解码器依赖硬编码 C 处理器，5.x 改为纯 YAML 解析模型）、<json_null_field>、<type>（解码器路由层被重写）、<fts>/<ftscomment>/<accumulate/>（5.x 解码器无跨事件状态，是设计上无状态）、<use_own_name>（5.x 强制解码器名唯一：decoder/<name>/<version>）、<prematch type="pcre2">/<regex type="pcre2">（logpar 不是正则引擎）、各种offset（logpar 顺序解析器天然跟踪位置）。

迁移五步法：① 写头部，name: decoder/<your-name>/0（用户自建解码器版本恒为 0）、生成 UUIDv4 的id、enabled: true、填写metadata；②<parent>转parents列表，子解码器仅在某个父解码器匹配后运行；③<prematch>转check（布尔表达式，只过滤不提取）；④<regex>+<order>转parse|<field>（如parse|message），捕获组换成带 schema 类型的命名占位符——<source.ip>（IP）、<source.port>（number）、<@timestamp>（date）自动推断类型，可用后缀强制（<source.port/long>），可选段用(?)（connected from <source.ip>(? port <source.port>)），通配丢弃用<~>，临时变量用_前缀；⑤ 无条件赋值放进normalize的map块，每个 normalize 块可独立拥有check、parse|、map，失败块被跳过而不拖垮整个解码器。

转换示例（4.x XML → 5.x YAML）：

<decoder name="auth_decoder"> <parent>syslog</parent> <prematch>^(sshd|sudo)</prematch> <regex>(\w+): Failed password for (\w+) from ([\d.]+)</regex> <order>process.name,user.name,source.ip</order> </decoder>

name: decoder/auth-failure/0 id: <replace-with-a-new-uuidv4> enabled: true parents: - decoder/syslog/0 metadata: title: SSH/Sudo authentication failure description: Extracts failed authentication attempts author: <ORGANIZATION/AUTHOR OF DECODER> date: <YYYY-MM-DD> check: $process.name == 'sshd' OR $process.name == 'sudo' normalize: - parse|message: - "<process.name>: Failed password for <user.name> from <source.ip>" map: - event.action: authentication-failure - event.outcome: failure - event.category: array_append(authentication)

CDB 列表 → KVDB

cdb-to-kvdb-migration.md 说明：4.x 中规则通过 CDB（Constant Database）列表（/var/ossec/etc/lists/）做威胁情报查询；5.0 中引擎改用 KVDB（Key-Value Database）。CDB 列表不会自动带入，必须把每个列表转成 KVDB 并把相关规则改写成解码器的check/map阶段。

结构差异要点：4.x 的 CDB 查询出现在规则（<list>标签）与解码器中；5.x 中所有 KVDB 查询都在解码器里，规则级的 CDB 逻辑必须下移到处理该事件的解码器。CDB 无 schema，KVDB 是带显式content条目的 YAML 文档；KVDB 定义在 integration 内、存储于 wazuh-indexer、自动同步到引擎；KVDB 的值还支持嵌套字段与数组。

实现等价关系：

迁移三步：① 备份cp -r /var/ossec/etc/lists /tmp/cdb-migration与规则目录；② 写 KVDB 骨架（kvdbs:列表，含id/metadata/enabled/content），把 CDB 条目key:value转成标准 YAML 映射key: value（注意 CDB 分隔符:后无空格）；③ 把 KVDB 与使用它的解码器打包进 integration，上传到 wazuh-indexer 的 Custom 空间，由 CMSync 在下一同步周期分发。典型模式：黑名单精确 IP 用check: source.ip: kvdb_match('list_one')；子网条目拆成显式ip_cidr_match/192.168.0.0/16/$source.ip；allowlist（not_match_key）用kvdb_not_match('authorized_users')；match_key_value用map中的kvdb_get('threat_types', $source.ip)取值再过滤；跨两个列表的 AND 条件通过"父解码器 + 子解码器"的父子关系保持。

规则迁移与 SCA 策略

规则内容同样迁移到引擎体系（见 rules-4x-to-5x.md 与 engine-introduction.md）。SCA 策略的格式变更在 sca-policies-4x-to-5x.md 中有完整说明（详见下节）。

模块替代与功能移除

CIS-CAT / OpenSCAP → 原生 SCA

4.x 的open-scapwodle 与 CIS-CAT 集成在 5.0 中被移除，统一由原生 SCA 模块取代，详见 ciscat-openscap-to-sca.md。管理器wazuh-manager.conf中残留的<wodle name="open-scap">块应删除。

SCA 策略格式变更（4.x → 5.x）

sca-policies-4x-to-5x.md 总结了自定义 SCA 策略的破坏性变更，且没有自动迁移工具：

正则表达式迁移的关键示例（4.x → 5.x PCRE2）：r:*→r:\*（裸*是空量词，PCRE2 编译失败）；n:audit_backlog_limit=(d+)→(\d+)；compare => 5→compare >= 5；compare \!= 1→compare != 1；需要匹配字面量点时转义（r:pam_unix\.so）；OSRegex 通配\p换成显式字符类（如[*!+-]）。迁移完成后在非生产 5.x Agent 上验证扫描，重点看Failed to parse policy、Invalid compliance key、PCRE2 compilation failed等日志，再按组增量推广。当前策略 schema 参见 docs/ref/modules/sca/custom-policies.md，仓库内置策略示例位于 ruleset/sca。

邮件转发与报告

4.x 基于<global>邮件配置和 maild 的报告功能在 5.0 中被移除，替代方案见 mail-forwarding-reporting.md（邮件通知改用新的通知渠道/触发器机制，相关概念在 integratord-notifications.md 与 remote-syslog-output.md 中有对应说明）。同时记得删除maild.*内部选项。

osQuery → IT Hygiene

osQuery 模块由 IT Hygiene 取代，见 osquery-to-it-hygiene.md。

Agentless → Agent 化与 SSH relay

Agentless 模块在 5.0 中移除，改用基于 Agent 的方案或 SSH relay 方式，见 agentless-4x-to-5x.md。

VirusTotal 集成

VirusTotal 集成被移除（api.yaml中upload_configuration.integrations.virustotal也随之失效），迁移方案见 virustotal-migration.md。

漏洞检测：CTI 数据源模型

vulnerability-detection-cti-feeds.md 说明 4.x 的离线/自定义漏洞 feed（按厂商的 feed 文件或镜像 URL，配置在遗留的<vulnerability-detector>块下）在 5.x 中整体移除。CVE 内容改由 Wazuh CTI 发布，经 Wazuh Indexer 自动到达管理器，无需任何 feed 配置。

新内容流固定为：

Wazuh CTI -> Wazuh Indexer (.wazuh-threatintel-vulnerabilities) -> Vulnerability Detection (/var/wazuh-manager/queue/vd/feed) -> wazuh-states-vulnerabilities

CTI 消费者（cti:catalog:consumer:vulnerabilities）把 CVE 文档装入.wazuh-threatintel-vulnerabilities索引，消费者状态记录在.wazuh-cti-consumers；管理器从 Indexer（而非直接连cti.wazuh.com）下载 feed，在queue/vd/feed/构建本地 RocksDB 数据库。更新时内容先暂存于queue/vd/vd_updater/rocksdb/再提交。漏洞检测现在依赖可用的<indexer>连接，耦合度远高于 4.x。

迁移动作极简：5.x 默认配置已带好<vulnerability-detection>块（enabled: yes、feed-update-interval: 60m，另有可选pageSize默认 100、numSlices默认 2）；不要把旧的<vulnerability-detector>、<provider>、离线路径、自定义 URL、<index-status>带过来（只会产生弃用与invalid element1230 告警）。离线/气隙环境是唯一的真破坏性变更：5.x 没有离线或替代 feed 源（contentSource: indexer固定），管理器必须能访问 CTI 消费者已填充的 Indexer，否则queue/vd/feed/保持为空、所有 Agent 扫描无限期推迟，且没有 seed/快照/导入机制。

验证 feed 是否加载，可按依赖顺序检查四层：①.wazuh-cti-consumers文档status为"idle"（updating表示消费者仍在索引，管理器每分钟轮询并阻塞下载）；②.wazuh-threatintel-vulnerabilities*索引docs.count非零；③/var/wazuh-manager/queue/vd/feed/出现 RocksDB 文件（只有LOCK/LOG说明还没收到 feed），管理器日志可见CVE feed not yet available — per-agent scans deferred until initial load completes.与加载完成日志；④wazuh-states-vulnerabilities索引有数据说明端到端扫描生效。

基础设施组件迁移

远程 Agent 升级

remote-agent-upgrade.md 说明远程把 Agent 升级到 5.x 所需的 TCP 连通性与版本路径要求，请按该指南核对网络放通与升级路径。

Filebeat → Indexer Connector

4.x 中管理器经 Filebeat 向索引器发送数据；5.0 起由 Indexer Connector 直连，见 filebeat-to-indexer-connector.md。这也解释了<indexer>段证书从 Filebeat 目录改为管理器自身证书的原因。

协调器（HAProxy）迁移

manager-coordinator-migration.md 介绍集群协调器 HAProxy 从 4.x 到 5.x 的迁移步骤。

迁移检查清单

综合上述指南，一次完整的 4.x → 5.0 迁移应核对：

• 4.x 上完成ossec.conf、内部选项、api.yaml、组目录与自定义规则/解码器/列表的全量备份，并存放在可存活于重装的位置；
• 全新安装 5.0 后，wazuh-manager.conf根元素为<wazuh_config>，已移除<alerts>、<command>、<ruleset>、<localfile>及全部邮件选项；
• <global>、<remote>、<indexer>、<vulnerability-detection>符合 5.0 新格式，证书路径指向/var/wazuh-manager/etc/certs/；
• wazuh-manager-internal-options.conf只保留有效选项，无analysisd.*、remoted.guess_agent_group等已移除项；
• api.yaml证书名与精简后的upload_configuration正确，无ssl_protocol与experimental_features；
• 组目录恢复至/var/wazuh-manager/etc/shared/且属主为wazuh-manager，每个 Agent 的ossec.conf已配置<groups>，authd.pass已下发，Agent 重新注册后归属正确；
• 自定义解码器已迁移为 YAML（decoder/<name>/0+ UUIDv4），CDB 列表已转 KVDB 并随 integration 发布，规则逻辑下移到解码器check/map；
• SCA 策略使用name、PCRE2 表达式、对象式compliance与独立mitre，<skip_nfs>已移除，非生产环境验证通过；
• 漏洞检测依赖的 Indexer 连接可用，CTI 消费者idle、feed 已加载、扫描正常产出；
• 集群cluster.json采用 5.0 默认值，仅重放自定义 interval；移除的邮件/osQuery/Agentless/VirusTotal 模块已由对应替代方案承接。

迁移相关的一手参考包括：manager-configuration-migration.md、agent-groups-migration.md、vulnerability-detection-cti-feeds.md、xml-decoders-migration.md、cdb-to-kvdb-migration.md、sca-policies-4x-to-5x.md，以及仓库中的实际配置与实现：etc/wazuh-manager.conf、etc/wazuh-manager-internal-options.conf、api/api/configuration/api.yaml、framework/wazuh/core/cluster/cluster.json、src/engine、docs/ref/modules/engine/README.md。

【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh