Wazuh Agent Upgrade 模块配置完全指南：WPK 远程升级的 Manager 与 Agent 双向调优-酒店常州论坛

Wazuh Agent Upgrade 模块配置完全指南：WPK 远程升级的 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 的 Agent Upgrade（代理升级）模块负责通过现有的 Manager–Agent 连接通道，向端点远程下发 WPK（Wazuh Package Kit）升级包、校验校验和、执行安装脚本，并通过任务管理器（Task Manager）跟踪升级结果。本文以仓库中的官方配置参考文档 docs/ref/modules/agent_upgrade/configuration.md 为主体，结合模块架构文档与src/wazuh_modules/src/agent_upgrade/下的 C 源码实现，系统讲解 Manager 端与 Agent 端全部配置项、完整升级流程、性能调优、监控与排障方法。读完本文，你将能够根据网络条件与集群规模为 Wazuh 部署定制远程升级策略，并能在升级失败时快速定位问题。

模块定位：Manager 与 Agent 的职责划分

Agent Upgrade 模块的配置分为**管理端（Manager）与代理端（Agent）**两个互不相同的层面：

Manager 端：控制 WPK 包的下载、分块传输（chunked transfer）与升级编排（orchestration），决定"如何把包发给哪些代理、同时并发几路"；
Agent 端：控制该代理是否接受来自 Manager 的远程升级指令，以及升级结果通知（notification）的重试行为，决定"收不收、装之前验不验证签名、结果怎么汇报"。

这种职责划分在源码中体现得非常清晰：wm_agent_upgrade.h 将配置拆成了wm_agent_configs（agent 端：upgrade_wait_start、upgrade_wait_max、upgrade_wait_factor_increase、enable_ca_verification）与wm_manager_configs（manager 端：max_threads、chunk_size、wpk_repository）两个结构体；wm_agent_upgrade.c 中则通过#ifdef CLIENT编译分支，在同一份模块代码里分别启动wm_agent_upgrade_start_agent_module（Agent 侧）或wm_agent_upgrade_start_manager_module（Manager 侧）。

Manager 端配置

配置文件：/var/wazuh-manager/etc/wazuh-manager.conf

XML 段：<agent-upgrade>

内部选项（Internal Options）：无

Manager 端配置项全部作用于 WPK 包的分发策略。模块启动后，wm_agent_upgrade_dump会把当前生效配置输出到模块信息中（见 wm_agent_upgrade.c），可用于核对配置是否真正生效。

enabled

启用或停用整个 Agent Upgrade 模块。

属性	值
默认值	`yes`
允许值	`yes`、`no`
说明	设置为`no`后，所有代理升级操作（API 触发、CLI 触发）都会被阻止

该开关同时作用于 Manager 与 Agent 两侧的模块主循环：源码中wm_agent_upgrade_main会把upgrade_config->enabled一并传给启动函数（wm_agent_upgrade.c），停用后模块不监听升级任务队列。

wpk_repository

WPK 升级包的下载基础 URL。

属性	值
默认值	无（运行时根据 Manager 版本自动推导为`packages.wazuh.com/<major>.x/wpk/`）
允许值	任意合法 URL
说明	若 URL 末尾缺少`/`，运行时会被自动补全

源码层面，wm_agent_upgrade.h 定义了默认仓库模板WM_UPGRADE_WPK_REPO_URL "packages.wazuh.com/%d.x/wpk/"，并保留了 3.x 时代的旧仓库常量WM_UPGRADE_WPK_REPO_URL_3_X。在 wm_agent_upgrade_validate.c 中可以看到其解析逻辑：若任务未显式指定仓库，则优先使用模块配置中的wpk_repository，否则回退到按版本自动推导的默认仓库；解析时还会校验 URL 是否包含http://或https://前缀，并保证以/结尾后再拼接 WPK 文件名。

chunk_size

每次向 Agent 传输 WPK 包时单个数据块（chunk）的大小（字节）。

属性	值
默认值	`32768`（32 KB）
允许值	`64`～`60000`的整数
说明	块越小内存占用越低，但传输开销（消息往返次数）越大

源码常量与此完全对应：wm_agent_upgrade.h 定义了WM_UPGRADE_CHUNK_SIZE 32768、WM_UPGRADE_CHUNK_SIZE_MIN 64与WM_UPGRADE_CHUNK_SIZE_MAX 60000。传输时 Manager 会按该大小逐块读取 WPK 文件并循环调用write命令下发，见 wm_agent_upgrade_upgrades.c 中char buffer[chunk_size]的块缓冲实现。

max_threads

同时进行的升级操作（升级任务线程）最大数量。

属性	值
默认值	`8`
允许值	`0`（使用 CPU 核数）或`1`～`256`的整数
说明	设为`0`时自动使用可用 CPU 核数

默认值8对应源码常量WM_UPGRADE_MAX_THREADS 8（wm_agent_upgrade.h）。Manager 启动时通过 wm_agent_upgrade_upgrades.c 的wm_agent_upgrade_init_upgrade_queue用信号量sem_init(&upgrade_semaphore, 0, max_threads)构建并发闸门，将同时执行的升级任务严格限制在该数值以内。

Manager 端配置示例

默认配置

适用于大多数部署场景的标准升级设置：

<agent-upgrade> <enabled>yes</enabled> <chunk_size>32768</chunk_size> <max_threads>8</max_threads> </agent-upgrade>

自定义 WPK 仓库

使用内部或自定义 WPK 仓库替代官方 Wazuh 仓库（例如内网镜像或企业私有源）：

<agent-upgrade> <enabled>yes</enabled> <wpk_repository>https://packages.internal.company.com/wazuh/wpk/</wpk_repository> </agent-upgrade>

大规模部署

面向同时升级大量 Agent 的高性能配置（把块放大到接近上限，并放开线程数以吃满 CPU）：

<agent-upgrade> <enabled>yes</enabled> <chunk_size>60000</chunk_size> <max_threads>0</max_threads> <!-- Use all CPU cores --> </agent-upgrade>

低带宽网络

针对带宽受限或不稳定网络进行优化（更小的块降低单次传输失败重传的代价，减少并发线程避免拥塞）：

<agent-upgrade> <enabled>yes</enabled> <chunk_size>8192</chunk_size> <max_threads>2</max_threads> </agent-upgrade>

禁用远程升级

在 Manager 端彻底阻止所有远程代理升级：

<agent-upgrade> <enabled>no</enabled> </agent-upgrade>

Agent 端配置

配置文件：/var/ossec/etc/ossec.conf（Linux/Unix）或C:\Program Files (x86)\ossec-agent\ossec.conf（Windows）

XML 段：<agent-upgrade>

内部选项（Internal Options）：无

Agent 端配置决定单个代理是否接受 Manager 的远程升级指令，以及升级结果通知的重试策略。

enabled

允许或禁止该代理被远程升级。

属性	值
默认值	`yes`
允许值	`yes`、`no`
说明	设为`no`后，代理会拒绝来自 Manager 的所有升级命令

ca_verification

安装前是否校验 WPK 包的数字签名。

属性	值
默认值	`yes`
允许值	`yes`、`no`
说明	不建议关闭；关闭后允许安装未签名包，存在被投毒的风险

在 Agent 侧源码中，该选项对应wm_agent_configs.enable_ca_verification（wm_agent_upgrade.h）。实际验签发生在解包安装之前：wm_agent_upgrade_com.c 通过w_wpk_unsign(source_j, dest, wcom_ca_store)使用 CA 证书库对 WPK 进行解签验证。

ca_store（子选项）

用于 WPK 签名校验的自定义 CA 证书文件路径。

属性	值
默认值	内置 CA 证书
允许值	合法文件路径（标签可重复，用于指定多个证书）
说明	仅在`ca_verification`为`yes`时生效；允许使用自定义 CA 为 WPK 签名

ca_store以字符串数组形式保存在全局变量wcom_ca_store中（wm_agent_upgrade_agent.c），模块状态输出时会以 JSON 数组形式回显（wm_agent_upgrade.c）。

多证书格式：

<ca_verification> <ca_store>/etc/ssl/certs/ca1.pem</ca_store> <ca_store>/etc/ssl/certs/ca2.pem</ca_store> </ca_verification>

notification_wait_start

升级完成后，Agent 首次向 Manager 汇报升级结果前的初始等待时间（秒）。

属性	值
默认值	`60`
允许值	正整数
说明	用于 Manager 不可达时的指数退避（exponential backoff）起点

值得说明的是：仓库源码 wm_agent_upgrade.h 中定义的编译期默认常量为WM_UPGRADE_WAIT_START 30，文档记录的默认值为60，配置未显式给出时以你所用版本实际生效值为准。其运行时行为可以在 wm_agent_upgrade_agent.c 中看到：Agent 重启后不断尝试把结果文件发送给 Manager，每次失败就按wait_time *= upgrade_wait_factor_increase放大等待时间，直到 Manager 确认收到结果。

notification_wait_max

通知重试之间的最大等待时间（秒）。

属性	值
默认值	`3600`（1 小时）
允许值	正整数
说明	防止重试延迟无限增大

对应源码常量WM_UPGRADE_WAIT_MAX 3600（wm_agent_upgrade.h），在退避循环中充当上限封顶：if (wait_time > upgrade_wait_max) wait_time = upgrade_wait_max;。

notification_wait_factor

通知重试的指数退避乘数。

属性	值
默认值	`2`
允许值	正整数
说明	每次重试等待`previous_wait * factor`，并以`notification_wait_max`为上限

对应源码常量WM_UPGRADE_WAIT_FACTOR_INCREASE 2.0（wm_agent_upgrade.h），注意源码中该字段类型为float，即允许小数乘数。

Agent 端配置示例

默认配置

标准的 Agent 升级设置：

<agent-upgrade> <enabled>yes</enabled> <ca_verification>yes</ca_verification> </agent-upgrade>

在单个 Agent 上禁用远程升级

阻止这一特定代理被远程升级（例如生产关键节点希望完全人工介入）：

<agent-upgrade> <enabled>no</enabled> </agent-upgrade>

自定义通知时序

针对不稳定网络调整通知重试行为（更短的起始等待、更大的退避因子、更早封顶）：

<agent-upgrade> <enabled>yes</enabled> <ca_verification>yes</ca_verification> <notification_wait_start>30</notification_wait_start> <notification_wait_max>1800</notification_wait_max> <notification_wait_factor>3</notification_wait_factor> </agent-upgrade>

升级流程与任务状态机

Manager 侧完整流程

一次远程升级在 Manager 侧遵循如下链路（与模块架构文档中的流程图一致）：

API 请求：通过 Wazuh API 或 CLI 发起升级；
任务创建：Task Manager 创建升级任务（初始状态Pending）；
WPK 下载：Manager 从仓库下载 WPK（若未命中缓存）；
WPK 传输：Manager 以分块方式把 WPK 传给 Agent；
执行触发：Manager 向 Agent 发送升级执行指令；
状态监控：Manager 持续监控升级任务状态；
完成：任务标记为完成或失败。

从源码看，第 3～5 步的实现细节集中在 wm_agent_upgrade_upgrades.c：Manager 会依次向 Agent 发送lock_restart（冻结 Agent 重启）、open wb <file>（在 Agent 端以写二进制模式创建文件）、多轮write <chunk>（按chunk_size分块写入）、sha1 <file> <sha1>（Agent 计算本地 SHA-1 与 Manager 侧比对），最后触发upgrade（Agent 运行 WPK 内置的pkg_install.sh安装脚本）。其中open命令还内置了WM_UPGRADE_WPK_OPEN_ATTEMPTS次重试机制（wm_agent_upgrade_upgrades.c），以应对传输期间的瞬时故障。

版本约束

条件	行为
Agent < v3.0.0	拒绝 —— 最低支持版本
从 < v4.14.0 升级到 v5.0.0	必须先做中间升级到 v4.14.0
Agent 版本 ≥ Manager 版本	拒绝，除非设置`force_upgrade`

从框架层看，framework/wazuh/agent.py 的upgrade_agents函数会通过WazuhDBQueryAgents过滤出活跃、存在且满足条件（filters、q）的候选代理，将不存在（错误码 1701）、非活跃（1707）、不满足条件（1731）的代理列入failed_items，其余代理才会真正创建升级任务。

任务状态

状态	含义
`Pending`	任务已创建，等待分发
`In progress`	WPK 传输与安装进行中
`Done`	Agent 上报成功
`Failed`	Agent 上报错误
`Timeout`	在`task_timeout`（默认 15 分钟）内未收到结果
`Cancelled`	任务在完成前被取消

WPK 缓存

已下载的 WPK 会缓存在/var/wazuh-manager/var/upgrade/：

ls -lh /var/wazuh-manager/var/upgrade/

升级任务的发起方式

通过 API 发起

官方 API 规范 api/api/spec/spec.yaml 定义了三个与升级相关的端点：

PUT /agents/upgrade：使用在线仓库的 WPK 升级 Agent（参数支持wpk_repo、upgrade_version、use_http、force、package_type以及按 OS、组、节点等维度过滤的q查询）；
PUT /agents/upgrade_custom：使用本地 WPK 文件升级 Agent（参数为file_path、installer）；
GET /agents/upgrade_result：查询升级结果。

规范中还特别提示：当同时升级超过 3000 个 Agent 时，强烈建议将wait_for_complete设为true，以避免 API 超时。三个端点均要求agent:upgradeRBAC 权限（x-rbac-actions引用agent:upgrade动作）。

通过 CLI 发起

仓库提供了完整的命令行工具 framework/scripts/agent_upgrade.py，常用参数如下：

参数	作用
`-a, --agents`	要升级的 Agent ID 列表（必填，除非使用`-l`）
`-r, --repository`	指定仓库 URL（默认取框架常量`WPK_REPO_URL_4_X`）
`-v, --version`	升级到指定版本（默认最新 Wazuh 版本）
`-F, --force`	强制升级，忽略版本校验
`-s, --silent`	不输出过程信息
`-l, --list_outdated`	列出所有过期（outdated）Agent
`-f, --file`	自定义 WPK 文件名（本地包升级）
`-x, --execute`	WPK 内可执行文件名（默认`upgrade.sh`）
`--http`	使用 HTTP 协议而非 HTTPS
`--package_type`	Linux 平台使用 rpm 或 deb 包

该脚本内部复用框架层接口：-l调用wazuh.agent.get_outdated_agents（framework/wazuh/agent.py），升级调用upgrade_agents，随后通过get_upgrade_result轮询任务状态，每 3 秒检查一次（framework/scripts/agent_upgrade.py），直至所有 Agent 达到Updated、Legacy upgrade、Error、Timeout或cancelled终态。

性能调优

并发升级数（max_threads）

并发升级数直接受max_threads信号量闸门约束，官方文档给出了按规模的分级建议：

小规模部署（<100 个 Agent）：

<max_threads>4</max_threads>

中规模部署（100–1000 个 Agent）：

<max_threads>8</max_threads>

大规模部署（1000+ 个 Agent）：

<max_threads>0</max_threads> <!-- Use all CPU cores -->

传输块大小（chunk_size）

块大小是传输吞吐与内存占用之间的权衡点：

高带宽：

<chunk_size>60000</chunk_size>

低带宽或不稳定网络：

<chunk_size>8192</chunk_size>

均衡（默认）：

<chunk_size>32768</chunk_size>

与 Task Manager 协同调优

升级任务的生命周期由 Task Manager 统一管理，其配置参考见 docs/ref/modules/task_manager/configuration.md。两个关键参数与升级强相关：

task_timeout：任务执行默认超时（默认15m，支持s/m/h/d后缀）。升级属长耗时操作，<task_timeout>15m</task_timeout>时间不足时可适当调大；
cleanup_time：已完成任务的清理间隔（默认15m），必须大于task_timeout，否则任务尚未判定超时就被清理。

监控升级状态

查询升级状态

通过 API：

curl -k -X GET "https://localhost:55000/agents/upgrade" \ -H "Authorization: Bearer $TOKEN"

通过 CLI：

/var/wazuh-manager/bin/agent_upgrade -l

查看升级日志

# Manager 升级日志 tail -f /var/wazuh-manager/logs/wazuh-manager.log | grep agent-upgrade # Task Manager 日志 tail -f /var/wazuh-manager/logs/wazuh-manager.log | grep task-manager

检查 WPK 缓存

# 列出已缓存的 WPK 文件 ls -lh /var/wazuh-manager/var/upgrade/ # 检查磁盘占用 du -sh /var/wazuh-manager/var/upgrade/

故障排查

升级无法启动

检查模块是否启用：

grep -A5 "<agent-upgrade>" /var/wazuh-manager/etc/wazuh-manager.conf

验证 WPK 仓库可达：

# 测试仓库 URL curl -I https://packages.wazuh.com/4.x/wpk/

WPK 下载失败

检查网络连通性：

curl -v https://packages.wazuh.com/

确认防火墙放行出站 HTTPS：

iptables -L OUTPUT -n -v | grep 443

若使用自定义仓库，还应回到配置解析源码确认 URL 带http:///https://前缀且以/结尾，否则运行时补全逻辑可能拼出错误地址。

升级超时

升级长时间停留在In progress并在task_timeout后进入Timeout，通常意味着 WPK 传输过慢或 Agent 失联。可增大 Task Manager 的任务超时（默认 15 分钟）：

<task-manager> <task_timeout>30m</task_timeout> <!-- Increase from 15m default --> </task-manager>

同时可考虑在<agent-upgrade>中调低chunk_size（减少单块传输失败的重传代价）并控制max_threads（避免并发洪峰挤占带宽）。修改配置后需重启wazuh-manager（Manager 端）或对应 Agent 服务使配置生效。

企业官网建设流程全解析