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/wazuhWazuh 的 Agent Upgrade代理升级模块负责通过现有的 Manager–Agent 连接通道向端点远程下发 WPKWazuh 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_configsagent 端upgrade_wait_start、upgrade_wait_max、upgrade_wait_factor_increase、enable_ca_verification与wm_manager_configsmanager 端max_threads、chunk_size、wpk_repository两个结构体wm_agent_upgrade.c 中则通过#ifdef CLIENT编译分支在同一份模块代码里分别启动wm_agent_upgrade_start_agent_moduleAgent 侧或wm_agent_upgrade_start_manager_moduleManager 侧。Manager 端配置配置文件/var/wazuh-manager/etc/wazuh-manager.confXML 段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_repositoryWPK 升级包的下载基础 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的大小字节。属性值默认值3276832 KB允许值6460000的整数说明块越小内存占用越低但传输开销消息往返次数越大源码常量与此完全对应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 核数或1256的整数说明设为0时自动使用可用 CPU 核数默认值8对应源码常量WM_UPGRADE_MAX_THREADS 8wm_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 enabledyes/enabled chunk_size32768/chunk_size max_threads8/max_threads /agent-upgrade自定义 WPK 仓库使用内部或自定义 WPK 仓库替代官方 Wazuh 仓库例如内网镜像或企业私有源agent-upgrade enabledyes/enabled wpk_repositoryhttps://packages.internal.company.com/wazuh/wpk//wpk_repository /agent-upgrade大规模部署面向同时升级大量 Agent 的高性能配置把块放大到接近上限并放开线程数以吃满 CPUagent-upgrade enabledyes/enabled chunk_size60000/chunk_size max_threads0/max_threads !-- Use all CPU cores -- /agent-upgrade低带宽网络针对带宽受限或不稳定网络进行优化更小的块降低单次传输失败重传的代价减少并发线程避免拥塞agent-upgrade enabledyes/enabled chunk_size8192/chunk_size max_threads2/max_threads /agent-upgrade禁用远程升级在 Manager 端彻底阻止所有远程代理升级agent-upgrade enabledno/enabled /agent-upgradeAgent 端配置配置文件/var/ossec/etc/ossec.confLinux/Unix或C:\Program Files (x86)\ossec-agent\ossec.confWindowsXML 段agent-upgrade内部选项Internal Options无Agent 端配置决定单个代理是否接受 Manager 的远程升级指令以及升级结果通知的重试策略。enabled允许或禁止该代理被远程升级。属性值默认值yes允许值yes、no说明设为no后代理会拒绝来自 Manager 的所有升级命令ca_verification安装前是否校验 WPK 包的数字签名。属性值默认值yes允许值yes、no说明不建议关闭关闭后允许安装未签名包存在被投毒的风险在 Agent 侧源码中该选项对应wm_agent_configs.enable_ca_verificationwm_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_verificationnotification_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通知重试之间的最大等待时间秒。属性值默认值36001 小时允许值正整数说明防止重试延迟无限增大对应源码常量WM_UPGRADE_WAIT_MAX 3600wm_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.0wm_agent_upgrade.h注意源码中该字段类型为float即允许小数乘数。Agent 端配置示例默认配置标准的 Agent 升级设置agent-upgrade enabledyes/enabled ca_verificationyes/ca_verification /agent-upgrade在单个 Agent 上禁用远程升级阻止这一特定代理被远程升级例如生产关键节点希望完全人工介入agent-upgrade enabledno/enabled /agent-upgrade自定义通知时序针对不稳定网络调整通知重试行为更短的起始等待、更大的退避因子、更早封顶agent-upgrade enabledyes/enabled ca_verificationyes/ca_verification notification_wait_start30/notification_wait_start notification_wait_max1800/notification_wait_max notification_wait_factor3/notification_wait_factor /agent-upgrade升级流程与任务状态机Manager 侧完整流程一次远程升级在 Manager 侧遵循如下链路与 模块架构文档 中的流程图一致API 请求通过 Wazuh API 或 CLI 发起升级任务创建Task Manager 创建升级任务初始状态PendingWPK 下载Manager 从仓库下载 WPK若未命中缓存WPK 传输Manager 以分块方式把 WPK 传给 Agent执行触发Manager 向 Agent 发送升级执行指令状态监控Manager 持续监控升级任务状态完成任务标记为完成或失败。从源码看第 35 步的实现细节集中在 wm_agent_upgrade_upgrades.cManager 会依次向 Agent 发送lock_restart冻结 Agent 重启、open wb file在 Agent 端以写二进制模式创建文件、多轮write chunk按chunk_size分块写入、sha1 file sha1Agent 计算本地 SHA-1 与 Manager 侧比对最后触发upgradeAgent 运行 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.0Agent 版本 ≥ Manager 版本拒绝除非设置force_upgrade从框架层看framework/wazuh/agent.py 的upgrade_agents函数会通过WazuhDBQueryAgents过滤出活跃、存在且满足条件filters、q的候选代理将不存在错误码 1701、非活跃1707、不满足条件1731的代理列入failed_items其余代理才会真正创建升级任务。任务状态状态含义Pending任务已创建等待分发In progressWPK 传输与安装进行中DoneAgent 上报成功FailedAgent 上报错误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、installerGET /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列出所有过期outdatedAgent-f, --file自定义 WPK 文件名本地包升级-x, --executeWPK 内可执行文件名默认upgrade.sh--http使用 HTTP 协议而非 HTTPS--package_typeLinux 平台使用 rpm 或 deb 包该脚本内部复用框架层接口-l调用wazuh.agent.get_outdated_agentsframework/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 个 Agentmax_threads4/max_threads中规模部署100–1000 个 Agentmax_threads8/max_threads大规模部署1000 个 Agentmax_threads0/max_threads !-- Use all CPU cores --传输块大小chunk_size块大小是传输吞吐与内存占用之间的权衡点高带宽chunk_size60000/chunk_size低带宽或不稳定网络chunk_size8192/chunk_size均衡默认chunk_size32768/chunk_size与 Task Manager 协同调优升级任务的生命周期由 Task Manager 统一管理其配置参考见 docs/ref/modules/task_manager/configuration.md。两个关键参数与升级强相关task_timeout任务执行默认超时默认15m支持s/m/h/d后缀。升级属长耗时操作task_timeout15m/task_timeout时间不足时可适当调大cleanup_time已完成任务的清理间隔默认15m必须大于task_timeout否则任务尚未判定超时就被清理。监控升级状态查询升级状态通过 APIcurl -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/确认防火墙放行出站 HTTPSiptables -L OUTPUT -n -v | grep 443若使用自定义仓库还应回到 配置解析源码 确认 URL 带http:///https://前缀且以/结尾否则运行时补全逻辑可能拼出错误地址。升级超时升级长时间停留在In progress并在task_timeout后进入Timeout通常意味着 WPK 传输过慢或 Agent 失联。可增大 Task Manager 的任务超时默认 15 分钟task-manager task_timeout30m/task_timeout !-- Increase from 15m default -- /task-manager同时可考虑在agent-upgrade中调低chunk_size减少单块传输失败的重传代价并控制max_threads避免并发洪峰挤占带宽。修改配置后需重启wazuh-managerManager 端或对应 Agent 服务使配置生效。相关文档Agent Upgrade 模块概述与架构WPK 格式说明、升级流程图、任务状态表、套接字与关键源文件清单Task Manager 配置参考任务生命周期管理、task_timeout与cleanup_time调优Manager 全部配置参考其余 Manager 端配置项Agent 全部配置参考其余 Agent 端配置项【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/14 18:23:55 · 阅读 1.2k 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/wazuhWazuh 的 Agent Upgrade代理升级模块负责通过现有的 Manager–Agent 连接通道向端点远程下发 WPKWazuh 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_configsagent 端upgrade_wait_start、upgrade_wait_max、upgrade_wait_factor_increase、enable_ca_verification与wm_manager_configsmanager 端max_threads、chunk_size、wpk_repository两个结构体wm_agent_upgrade.c 中则通过#ifdef CLIENT编译分支在同一份模块代码里分别启动wm_agent_upgrade_start_agent_moduleAgent 侧或wm_agent_upgrade_start_manager_moduleManager 侧。Manager 端配置配置文件/var/wazuh-manager/etc/wazuh-manager.confXML 段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_repositoryWPK 升级包的下载基础 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的大小字节。属性值默认值3276832 KB允许值6460000的整数说明块越小内存占用越低但传输开销消息往返次数越大源码常量与此完全对应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 核数或1256的整数说明设为0时自动使用可用 CPU 核数默认值8对应源码常量WM_UPGRADE_MAX_THREADS 8wm_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 enabledyes/enabled chunk_size32768/chunk_size max_threads8/max_threads /agent-upgrade自定义 WPK 仓库使用内部或自定义 WPK 仓库替代官方 Wazuh 仓库例如内网镜像或企业私有源agent-upgrade enabledyes/enabled wpk_repositoryhttps://packages.internal.company.com/wazuh/wpk//wpk_repository /agent-upgrade大规模部署面向同时升级大量 Agent 的高性能配置把块放大到接近上限并放开线程数以吃满 CPUagent-upgrade enabledyes/enabled chunk_size60000/chunk_size max_threads0/max_threads !-- Use all CPU cores -- /agent-upgrade低带宽网络针对带宽受限或不稳定网络进行优化更小的块降低单次传输失败重传的代价减少并发线程避免拥塞agent-upgrade enabledyes/enabled chunk_size8192/chunk_size max_threads2/max_threads /agent-upgrade禁用远程升级在 Manager 端彻底阻止所有远程代理升级agent-upgrade enabledno/enabled /agent-upgradeAgent 端配置配置文件/var/ossec/etc/ossec.confLinux/Unix或C:\Program Files (x86)\ossec-agent\ossec.confWindowsXML 段agent-upgrade内部选项Internal Options无Agent 端配置决定单个代理是否接受 Manager 的远程升级指令以及升级结果通知的重试策略。enabled允许或禁止该代理被远程升级。属性值默认值yes允许值yes、no说明设为no后代理会拒绝来自 Manager 的所有升级命令ca_verification安装前是否校验 WPK 包的数字签名。属性值默认值yes允许值yes、no说明不建议关闭关闭后允许安装未签名包存在被投毒的风险在 Agent 侧源码中该选项对应wm_agent_configs.enable_ca_verificationwm_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_verificationnotification_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通知重试之间的最大等待时间秒。属性值默认值36001 小时允许值正整数说明防止重试延迟无限增大对应源码常量WM_UPGRADE_WAIT_MAX 3600wm_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.0wm_agent_upgrade.h注意源码中该字段类型为float即允许小数乘数。Agent 端配置示例默认配置标准的 Agent 升级设置agent-upgrade enabledyes/enabled ca_verificationyes/ca_verification /agent-upgrade在单个 Agent 上禁用远程升级阻止这一特定代理被远程升级例如生产关键节点希望完全人工介入agent-upgrade enabledno/enabled /agent-upgrade自定义通知时序针对不稳定网络调整通知重试行为更短的起始等待、更大的退避因子、更早封顶agent-upgrade enabledyes/enabled ca_verificationyes/ca_verification notification_wait_start30/notification_wait_start notification_wait_max1800/notification_wait_max notification_wait_factor3/notification_wait_factor /agent-upgrade升级流程与任务状态机Manager 侧完整流程一次远程升级在 Manager 侧遵循如下链路与 模块架构文档 中的流程图一致API 请求通过 Wazuh API 或 CLI 发起升级任务创建Task Manager 创建升级任务初始状态PendingWPK 下载Manager 从仓库下载 WPK若未命中缓存WPK 传输Manager 以分块方式把 WPK 传给 Agent执行触发Manager 向 Agent 发送升级执行指令状态监控Manager 持续监控升级任务状态完成任务标记为完成或失败。从源码看第 35 步的实现细节集中在 wm_agent_upgrade_upgrades.cManager 会依次向 Agent 发送lock_restart冻结 Agent 重启、open wb file在 Agent 端以写二进制模式创建文件、多轮write chunk按chunk_size分块写入、sha1 file sha1Agent 计算本地 SHA-1 与 Manager 侧比对最后触发upgradeAgent 运行 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.0Agent 版本 ≥ Manager 版本拒绝除非设置force_upgrade从框架层看framework/wazuh/agent.py 的upgrade_agents函数会通过WazuhDBQueryAgents过滤出活跃、存在且满足条件filters、q的候选代理将不存在错误码 1701、非活跃1707、不满足条件1731的代理列入failed_items其余代理才会真正创建升级任务。任务状态状态含义Pending任务已创建等待分发In progressWPK 传输与安装进行中DoneAgent 上报成功FailedAgent 上报错误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、installerGET /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列出所有过期outdatedAgent-f, --file自定义 WPK 文件名本地包升级-x, --executeWPK 内可执行文件名默认upgrade.sh--http使用 HTTP 协议而非 HTTPS--package_typeLinux 平台使用 rpm 或 deb 包该脚本内部复用框架层接口-l调用wazuh.agent.get_outdated_agentsframework/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 个 Agentmax_threads4/max_threads中规模部署100–1000 个 Agentmax_threads8/max_threads大规模部署1000 个 Agentmax_threads0/max_threads !-- Use all CPU cores --传输块大小chunk_size块大小是传输吞吐与内存占用之间的权衡点高带宽chunk_size60000/chunk_size低带宽或不稳定网络chunk_size8192/chunk_size均衡默认chunk_size32768/chunk_size与 Task Manager 协同调优升级任务的生命周期由 Task Manager 统一管理其配置参考见 docs/ref/modules/task_manager/configuration.md。两个关键参数与升级强相关task_timeout任务执行默认超时默认15m支持s/m/h/d后缀。升级属长耗时操作task_timeout15m/task_timeout时间不足时可适当调大cleanup_time已完成任务的清理间隔默认15m必须大于task_timeout否则任务尚未判定超时就被清理。监控升级状态查询升级状态通过 APIcurl -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/确认防火墙放行出站 HTTPSiptables -L OUTPUT -n -v | grep 443若使用自定义仓库还应回到 配置解析源码 确认 URL 带http:///https://前缀且以/结尾否则运行时补全逻辑可能拼出错误地址。升级超时升级长时间停留在In progress并在task_timeout后进入Timeout通常意味着 WPK 传输过慢或 Agent 失联。可增大 Task Manager 的任务超时默认 15 分钟task-manager task_timeout30m/task_timeout !-- Increase from 15m default -- /task-manager同时可考虑在agent-upgrade中调低chunk_size减少单块传输失败的重传代价并控制max_threads避免并发洪峰挤占带宽。修改配置后需重启wazuh-managerManager 端或对应 Agent 服务使配置生效。相关文档Agent Upgrade 模块概述与架构WPK 格式说明、升级流程图、任务状态表、套接字与关键源文件清单Task Manager 配置参考任务生命周期管理、task_timeout与cleanup_time调优Manager 全部配置参考其余 Manager 端配置项Agent 全部配置参考其余 Agent 端配置项【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考