企业官网建设流程全解析

Wazuh 5.x 升级指南：Manager 与 Agent 版本升级的完整操作、文件保留机制与回滚策略

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

本文基于 Wazuh 仓库的升级参考文档（docs/ref/upgrade.md），系统讲解 Wazuh 5.x 版本中 Manager（服务端）与 Agent（代理端）的升级流程：从升级前备份、5.x 版本间的 preserve/restore 文件保留机制、集群滚动升级顺序，到升级失败后的回滚与排障方法。读完后，你可以独立完成单节点与集群环境下的 Wazuh 升级，并理解升级脚本底层如何保证配置文件不被新包覆盖。

需要特别强调的是版本支持范围：Wazuh Manager 从 4.x 升级到 5.x 不受支持，跨主版本升级 Manager 必须全新安装；而Wazuh Agent 支持从 4.x 升级到 5.x，并且 5.x Agent 可以连接到 5.x Manager。这一限制不只是文档约定，在仓库中有源码级的硬性拦截（见下文 升级入口的版本硬拦截）。

升级前准备：要求、备份与适用前提

升级前检查清单

按照升级文档的要求，在执行任何升级操作之前，应完成以下准备工作：

1. 查阅 release notes，确认新版本的 breaking changes（破坏性变更）与新特性；
2. 确认目标系统满足新版本的要求；
3. 按照 备份与恢复指南 创建备份；
4. 规划升级维护窗口；
5. 通知相关干系人。

当前仓库的版本状态可由 VERSION.json 确认（当前为 5.1.0 阶段版本），因此本文描述的流程适用于5.x 到 5.x的升级路径。

升级前备份

升级前必须先创建备份。文档给出的标准备份脚本如下：

# Create backup directory BACKUP_DIR="/backup/wazuh-manager-$(date +%Y%m%d-%H%M%S)" sudo mkdir -p $BACKUP_DIR/db # Backup configuration and database sudo tar -czf $BACKUP_DIR/wazuh-etc.tar.gz -C /var/wazuh-manager etc/ sudo sqlite3 /var/wazuh-manager/var/db/global.db ".backup '$BACKUP_DIR/db/global.db'" # Verify backup integrity tar -tzf $BACKUP_DIR/wazuh-etc.tar.gz > /dev/null && echo "Backup successful" sudo sqlite3 $BACKUP_DIR/db/global.db "PRAGMA integrity_check"

要点说明：

• 备份对象是/var/wazuh-manager/etc/（完整配置目录，包含client.keys、证书等）与global.db（SQLite 全局数据库，存放 Agent 注册与分组信息）；
• 使用sqlite3 .backup而非直接cp，保证数据库文件在写状态下的一致性；
• 两条验证命令分别确认 tar 包可正常解包、数据库integrity_check通过。更完整的备份范围（如 SSL 证书、共享文件目录）参见 备份与恢复指南。

Manager（Server）升级流程

下载与安装新包

下载对应平台与版本的 Wazuh Manager 包（可参考 Package Download 一节获取仓库与下载说明），然后安装：

Debian 系平台：

sudo dpkg -i wazuh-manager_*.deb

Red Hat 系平台：

sudo rpm -Uvh wazuh-manager-*.rpm

包管理器在安装过程中会自动完成四件事：停止当前服务、保留原有配置与运行时数据（机制见下文）、安装新二进制文件、重新拉起服务。

文件保留机制（preserve / restore）

在 5.x 到 5.x 的升级中，.deb、.rpm与源码升级脚本都会应用一套preserve / restore机制，升级后的路径行为如下：

文件内容、权限与属主在上述路径上均被保留，升级过程不会归一化或重置管理员自行设置的任何权限与属主。

新默认值如何生效。由于etc/被完整保留，新包携带的新默认值不会自动应用到已有文件：DEB Manager 升级会在生效配置旁边写出一个wazuh-manager.conf.new侧文件供人工对比；RPM 则为保留路径生成等价侧文件，需要时请手动与包内默认值对比。

升级失败时的保留目录。源码升级在 preserve 步骤之后失败或被打断时，会自动尝试恢复保留的文件；若自动恢复失败，或包升级在恢复完成前失败，保留目录会被原样留在系统中供手动恢复：

恢复数据后，重试升级前必须删除保留目录。DEB/RPM 升级一旦发现已存在的 preserve 备份会直接中止；源码升级每次尝试都会创建新的临时保留目录，旧的源码保留目录不会阻塞重试，但手动恢复后仍应清理。

升级入口的版本硬拦截

从源码结构看，文档中"4.x Manager 不可升级到 5.x"是一条硬编码约束。在 DEB 前置脚本 preinst 中，升级分支首先从 dpkg 传入的旧版本号提取主版本，若小于 5 立即输出错误并exit 1；随后还会通过wazuh-manager-control info -v或安装目录下的VERSION.json二次校验，检测不到版本（no_version）或版本过低（old_version）同样会打印如下提示并中止：

ERROR: Upgrade from Wazuh manager versions prior to 5.x is not supported. A clean installation of Wazuh manager 5.x is required.

RPM 侧在 wazuh-manager.spec 中实现了相同的保护：%pre升级段先检查UPGRADE_PRESERVE_DIR是否已存在（存在则报Existing manager upgrade preserve backup found并退出），再用cp -a将etc/与data/（跳过tzdb）完整复制到保留目录。

保留/恢复的源码实现

理解这套机制最有价值的部分是三个脚本文件：

1. DEB preinst —— 备份阶段。preinst 的backup_upgrade_preserve()逻辑为：

• 若/var/wazuh-manager/packages_files/manager_upgrade_preserve已存在，打印ERROR: Existing manager upgrade preserve backup found并exit 1（即文档中"DEB 升级遇到已有保留备份会中止"的出处）；
• 用cp -a（保留属性）复制整个etc/；
• 遍历data/下所有条目（含隐藏文件），显式跳过tzdb后逐条cp -a到保留目录。

preinst 同时负责停服务（systemd / SysV /wazuh-manager-control多重兜底）、清理旧的~api备份与 3.x 遗留的wazuh-api服务、迁移logs/ossec→logs/wazuh与queue/ossec→queue/sockets目录结构。

2. DEB postinst —— 恢复阶段。postinst 的restore_upgrade_preserve()在新包文件落盘后执行：先把保留目录中的etc/内容cp -a回/var/wazuh-manager/etc/，再恢复data/各条目，最后rm -rf删除保留目录。注释明确说明这是"对这两个目录树的最后一步内容恢复"，与 RPM 的%posttrans顺序对齐，严格满足"etc/ 绝不被覆盖"的升级契约。此外 postinst 还会：

• 将global.db从var/db/迁移到queue/db/并重新设置属主权限（660）；
• 升级场景下用新默认配置生成wazuh-manager.conf.new侧文件（postinst 第 82-84 行），属主root:wazuh-manager、权限 660——这就是文档提到的 DEB 侧文件；
• 恢复 API 的rbac.db与api.yaml（升级前已被 preinst 暂存）。

3. 源码安装 —— 失败自动恢复。仓库根目录的 install.sh 实现了源码升级路径：PrepareUpgradePreserve()用mktemp -d在${TMPDIR:-/tmp}下创建wazuh-${INSTYPE}-upgrade-preserve.XXXXXX目录并保存etc/与data/（同样跳过tzdb）；RestoreUpgradePreserve()负责回拷；AttemptUpgradePreserveRestore()在升级出错时先尝试自动恢复，失败则打印Preserved files left at ... for manual recovery保留现场。值得注意的是源码恢复使用cp -R（不带-p/-a）而非备份时的cp -a，注释说明这是为了让源码升级沿用安装器指定的属主与模式。

验证升级

# Check service status sudo systemctl status wazuh-manager # Check logs for errors sudo tail -50 /var/wazuh-manager/logs/wazuh-manager.log # Check database integrity sudo sqlite3 /var/wazuh-manager/var/db/global.db "PRAGMA integrity_check"

集群升级：Worker 优先、Master 最后

升级顺序

集群部署必须按以下顺序升级：

1. Worker 节点（一次只升一个）；
2. Master 节点（最后升级）。

这样安排是为了把服务中断降到最小：单节点升级期间，Agent 流量可以由其他 Worker 节点承接。

备份所有节点

Master 节点（完整备份）：

BACKUP_DIR="/backup/wazuh-master-$(date +%Y%m%d-%H%M%S)" sudo mkdir -p $BACKUP_DIR/db # Full backup of master sudo tar -czf $BACKUP_DIR/wazuh-master-etc.tar.gz -C /var/wazuh-manager etc/ sudo sqlite3 /var/wazuh-manager/var/db/global.db ".backup '$BACKUP_DIR/db/global.db'" # Verify backup tar -tzf $BACKUP_DIR/wazuh-master-etc.tar.gz > /dev/null && echo "Master backup successful"

每个 Worker 节点（仅配置备份）：

BACKUP_DIR="/backup/wazuh-worker-$(hostname)-$(date +%Y%m%d-%H%M%S)" sudo mkdir -p $BACKUP_DIR # Configuration backup only sudo tar -czf $BACKUP_DIR/wazuh-worker-config.tar.gz -C /var/wazuh-manager/etc wazuh-manager.conf local_internal_options.conf # Verify backup tar -tzf $BACKUP_DIR/wazuh-worker-config.tar.gz > /dev/null && echo "Worker backup successful"

逐个升级 Worker 节点

在每个 Worker 节点上执行：

1. 升级前检查集群状态：

sudo /var/wazuh-manager/bin/cluster_control -l

2. 下载新包（见 Package Download）。

3. 升级包：

# Debian 系 sudo dpkg -i wazuh-manager_*.deb # Red Hat 系 sudo rpm -Uvh wazuh-manager-*.rpm

4. 验证升级：

# Check service status sudo systemctl status wazuh-manager # Check cluster connectivity sudo /var/wazuh-manager/bin/cluster_control -l # Monitor cluster synchronization sudo tail -f /var/wazuh-manager/logs/cluster.log

5. 等待同步完成后再升级下一个 Worker：

# Monitor synchronization status sudo /var/wazuh-manager/bin/cluster_control -i # Check cluster logs sudo tail -50 /var/wazuh-manager/logs/cluster.log | grep -i sync

对每个剩余 Worker 重复以上流程，确保当前节点完全同步后再动下一个。

最后升级 Master 节点

Master 节点上执行：

1. 确认所有 Worker 已升级且健康：

# Check cluster status sudo /var/wazuh-manager/bin/cluster_control -l # Verify all workers are connected sudo /var/wazuh-manager/bin/cluster_control -i

2. 下载新包。

3. 升级包（dpkg -i/rpm -Uvh，同上）。

4. 验证升级：

# Check service status sudo systemctl status wazuh-manager # Check cluster status sudo /var/wazuh-manager/bin/cluster_control -l # Verify cluster health sudo /var/wazuh-manager/bin/cluster_control -i # Check logs sudo tail -50 /var/wazuh-manager/logs/wazuh-manager.log sudo tail -50 /var/wazuh-manager/logs/cluster.log

5. 验证集群同步：

# Check that all workers are synchronized with the master sudo /var/wazuh-manager/bin/cluster_control -l # Monitor cluster logs on master sudo tail -f /var/wazuh-manager/logs/cluster.log

集群升级后的综合验证

所有节点升级完成后，在Master 节点执行：

# Check cluster status sudo /var/wazuh-manager/bin/cluster_control -l # Check cluster health sudo /var/wazuh-manager/bin/cluster_control -i # Check database integrity sudo sqlite3 /var/wazuh-manager/var/db/global.db "PRAGMA integrity_check" # Monitor logs for errors sudo tail -100 /var/wazuh-manager/logs/wazuh-manager.log | grep -i error sudo tail -100 /var/wazuh-manager/logs/cluster.log | grep -i error

在每个 Worker 节点执行：

# Check cluster connectivity sudo /var/wazuh-manager/bin/cluster_control -l # Monitor logs sudo tail -50 /var/wazuh-manager/logs/cluster.log

Agent 升级流程

升级前建议

升级 Agent 之前：

1. 预防性备份 Agent 配置（ossec.conf与client.keys虽会被自动保留，仍建议做外部备份）；
2. 分批升级，避免所有 Agent 同时升级；
3. 先在非生产 Agent 上验证；
4. 确认 Manager 与新 Agent 版本的兼容性；
5. 注册口令注意事项：Wazuh 5.0 默认启用 Agent 注册的口令保护。若升级期间或之后需要重新注册 Agent，必须使用注册口令。如果 5.0 Manager 是全新安装的，请用sudo cat /var/wazuh-manager/etc/authd.pass在 Manager 上取回新口令并配置到 Agent，或把旧authd.pass文件恢复到新 Manager。

注意：Wazuh Agent 4.x 及以后版本支持升级到 5.x。

Agent 文件保留机制

5.x 到 5.x 的 Agent 升级同样应用 preserve / restore 机制：

DEB 升级会写出ossec.conf.new侧文件（新默认配置，供对比），这一点在 wazuh-agent 的 postinst 中可以确认：它在新装/升级分支用gen_wazuh.sh生成新配置并写入ossec.conf.new、权限 640。与 Server 相同，文件内容、权限与属主均被保留，升级不会重置管理员设置的权限。

Agent 的保留目录位置：

Linux Agent

Debian 系：

sudo dpkg -i wazuh-agent_*.deb sudo systemctl status wazuh-agent

Red Hat 系与 SUSE 系：

sudo rpm -Uvh wazuh-agent-*.rpm sudo systemctl status wazuh-agent

macOS

sudo installer -pkg wazuh-agent-*.pkg -target / # 验证 sudo /Library/Ossec/bin/wazuh-control status

Windows

wazuh-agent-*.msi /q # 验证 Get-Service -Name wazuh

补充说明：仓库中还存在面向 Agent 的远端升级路径——upgrade.sh 是下发到 Agent 侧var/upgrade/目录的升级脚本，会在后台调用pkg_installer.sh完成新包的下载与安装，配合 agent_upgrade.py 脚本可发起远程批量升级。若你的部署规模较大，可评估该通道替代逐台手工dpkg/rpm操作。

回滚（Rollback）

升级失败或引发问题时，可回滚到上一版本。

Server 回滚

Step 1：停止服务

sudo systemctl stop wazuh-manager

Step 2：移除新包

# Debian 系 sudo dpkg -r wazuh-manager # Red Hat 系 sudo rpm -e wazuh-manager

Step 3：从备份恢复

# Restore configuration sudo tar -xzf $BACKUP_DIR/wazuh-etc.tar.gz -C /var/wazuh-manager # Restore database sudo cp $BACKUP_DIR/db/global.db /var/wazuh-manager/var/db/global.db # Set permissions sudo chown -R wazuh-manager:wazuh-manager /var/wazuh-manager/etc sudo chown -R wazuh-manager:wazuh-manager /var/wazuh-manager/var/db

Step 4：重装旧版本包。

Step 5：验证回滚

sudo systemctl start wazuh-manager sudo systemctl status wazuh-manager

集群回滚

集群升级失败时，按与升级相反的顺序回滚：先回滚 Master（若已升级），再按升级顺序的逆序回滚 Worker。

回滚 Worker 节点：

# Stop the service sudo systemctl stop wazuh-manager # Remove the new package (Debian) sudo dpkg -r wazuh-manager # Or remove the new package (Red Hat) sudo rpm -e wazuh-manager # Restore configuration sudo tar -xzf $BACKUP_DIR/wazuh-worker-config.tar.gz -C /var/wazuh-manager/etc # Reinstall previous version package # Start the service sudo systemctl start wazuh-manager # Verify cluster connectivity sudo /var/wazuh-manager/bin/cluster_control -l

回滚 Master 节点：

# Stop the service sudo systemctl stop wazuh-manager # Remove the new package (Debian) sudo dpkg -r wazuh-manager # Or remove the new package (Red Hat) sudo rpm -e wazuh-manager # Restore configuration and database sudo tar -xzf $BACKUP_DIR/wazuh-master-etc.tar.gz -C /var/wazuh-manager sudo cp $BACKUP_DIR/db/global.db /var/wazuh-manager/var/db/global.db # Set permissions sudo chown -R wazuh-manager:wazuh-manager /var/wazuh-manager/etc sudo chown -R wazuh-manager:wazuh-manager /var/wazuh-manager/var/db # Reinstall previous version package # Start the service sudo systemctl start wazuh-manager # Verify cluster status sudo /var/wazuh-manager/bin/cluster_control -l

故障排查

Server 问题

Manager 升级后无法启动：

# Check logs for specific errors sudo tail -100 /var/wazuh-manager/logs/wazuh-manager.log # Verify permissions sudo chown -R wazuh-manager:wazuh-manager /var/wazuh-manager # Check database integrity sudo sqlite3 /var/wazuh-manager/var/db/global.db "PRAGMA integrity_check"

Manager 升级后 Agent 无法重连：

# Verify manager is listening on agent ports sudo netstat -tulpn | grep wazuh-manager # Check remoted process ps aux | grep wazuh-manager-remoted # Review remoted logs sudo tail -f /var/wazuh-manager/logs/wazuh-manager.log | grep remoted # Verify client.keys integrity sudo ls -l /var/wazuh-manager/etc/client.keys

集群节点升级后不同步：

# Check cluster configuration sudo grep -A10 "<cluster>" /var/wazuh-manager/etc/wazuh-manager.conf # Verify network connectivity ping <master_node_ip> telnet <master_node_ip> 1516 # Check cluster daemon ps aux | grep wazuh-manager-clusterd # Review cluster logs sudo tail -100 /var/wazuh-manager/logs/cluster.log # Restart cluster service sudo systemctl restart wazuh-manager

数据库迁移错误：

# Check database file permissions sudo ls -l /var/wazuh-manager/var/db/ # Review wazuh-manager.log for migration messages sudo grep -i "database\|migration" /var/wazuh-manager/logs/wazuh-manager.log # If migration fails, restore from backup sudo systemctl stop wazuh-manager sudo cp $BACKUP_DIR/db/global.db /var/wazuh-manager/var/db/global.db sudo chown wazuh-manager:wazuh-manager /var/wazuh-manager/var/db/global.db sudo systemctl start wazuh-manager

升级中止：已存在的保留目录

若前一次包升级被中断，保留目录可能仍留在系统中。DEB/RPM 升级遇到它会报Existing upgrade preserve backup found并中止；源码升级每次尝试都使用新的临时保留目录，旧目录不阻塞重试。恢复步骤：

1. 检查保留目录内容；
2. 将所需文件拷回etc/（Manager 升级场景还包括data/）；
3. 删除保留目录后重试升级。

# Example for manager DEB ls /var/wazuh-manager/packages_files/manager_upgrade_preserve/ # Recover if needed, then: sudo rm -rf /var/wazuh-manager/packages_files/manager_upgrade_preserve

Agent 问题

Agent 升级后无法启动：

# Check logs sudo tail -50 /var/ossec/logs/ossec.log # Verify client.keys exists sudo ls -l /var/ossec/etc/client.keys # Check permissions sudo chown -R root:wazuh /var/ossec/etc

Agent 升级后无法连接 Manager：

# Verify manager address in configuration sudo grep "<address>" /var/ossec/etc/ossec.conf # Check network connectivity to manager ping <manager_ip> telnet <manager_ip> 1514 # Verify client.keys matches manager # Compare key on agent with manager's client.keys entry # Check for enrollment password verification issues: # If you see "ERROR: Invalid password (from manager)" in /var/ossec/logs/ossec.log, # verify that the password in the agent's `/var/ossec/etc/authd.pass` matches # the manager's `/var/wazuh-manager/etc/authd.pass`. # Restart agent sudo systemctl restart wazuh-agent

Windows Agent 升级失败：

# Check Windows event logs Get-EventLog -LogName Application -Source "Wazuh" -Newest 50 # Verify service status Get-Service -Name wazuh # Check installation logs Get-Content "C:\Windows\Temp\wazuh-agent-install.log" # Restart service Restart-Service -Name wazuh

最佳实践

1. 升级前必须备份：遵循 备份与恢复指南；
2. 阅读 release notes：了解破坏性变更与新特性；
3. 非生产环境先行验证；
4. 在维护窗口内升级：选择低活动时段；
5. 增量升级：大规模部署分批执行；
6. 升级期间持续监控：盯紧日志与指标；
7. 保持回滚就绪：保留旧版本包与备份；
8. 记录变更：记录配置变更与遇到的问题；
9. 集群中先升 Worker 后升 Master；
10. 验证兼容性：确保 Manager 与 Agent 版本互相兼容。

相关资源

• 备份与恢复指南
• 安装指南
• 配置参考
• 集群文档
• 升级脚本实现：install.sh（源码升级的 preserve/restore）、DEB preinst/postinst、RPM spec

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