企业官网建设流程全解析

Wazuh Database Sync 模块配置指南：内部选项详解与同步机制原理解析

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

导读

本文聚焦 Wazuh 管理端（Manager）中负责代理（Agent）数据库同步的 Database Sync 模块，完整讲解其全部内部选项（wazuh_database.*）、三种典型部署配置模板、实时/定时两种同步模式的取舍，以及队列容量调优与故障排查方法。本文以 Database Sync 配置参考 为主体，并结合仓库内wm_database模块源码（wm_database.c）与全局库表结构（schema_global.sql）展开底层原理，读者阅读后即可独立完成该模块的配置、调优与问题诊断。

1. 模块定位：Manager 侧代理数据同步的"胶水层"

Database Sync 模块是wazuh-db守护进程的一个组成部分（Manager 专属组件），负责在管理器与全局数据库（global.db）之间同步与代理相关的数据，具体包括：

• 代理状态同步：跟踪并更新代理的连接状态（connection_status）与同步状态（sync_status）；
• 代理组同步：维护代理与组（group）的归属关系，并在组共享配置变更后重新计算组哈希（group hash）；
• 实时更新：支持实时（inotify 事件驱动）与定时（interval 轮询）两种同步模式；
• 事件队列管理：通过内部队列缓冲文件系统变更事件，实现批量处理。

模块概况可参考 Database Sync 模块总览。需要强调的是，该模块完全通过内部选项配置，在ossec.conf/wazuh-manager.conf中不存在对应的 XML 或 YAML 配置节。

2. 配置入口：内部选项文件

配置文件路径：/var/wazuh-manager/etc/wazuh-manager-internal-options.conf

XML 节：无

YAML 节：无

内部选项前缀：wazuh_database.*

仓库自带的模板文件 wazuh-manager-internal-options.conf 头部注释说明了该文件的语义：

该文件允许对 Wazuh manager 内部选项进行运行时覆盖；默认值已被编译进 manager 二进制文件，仅在需要覆盖特定值时添加条目。格式为module.option=value，且升级时不会覆盖此文件。

也就是说，所有 Database Sync 参数在源码中都有编译期默认值（见下文源码解析），该文件只需在需要调优时填写差异项。

3. 内部选项完整参考

以下四个选项均以wazuh_database.为前缀，写入内部选项文件后需要重启wazuh-manager（或wazuh-db相关服务）生效。

3.1wazuh_database.sync_agents

启用或禁用代理数据库同步。

wazuh_database.sync_agents=1

• 默认值：1（启用）
• 允许值：0（禁用）、1（启用）

启用后，管理器会将代理的状态、组归属与连接状态同步到全局数据库。从源码看，该选项同时是模块的"总开关"：在 wm_database_read() 中，如果sync_agents为 0，模块直接返回NULL（不加载、不运行）；只有启用时才会分配wm_database结构并注册到模块上下文。此外，sync_agents还决定是否对client.keys所在目录和共享组目录（SHAREDCFG_DIR）注册 inotify 监视（见 wm_inotify_setup()）。

3.2wazuh_database.real_time

启用实时同步模式。

wazuh_database.real_time=1

• 默认值：1（启用）
• 允许值：0（禁用）、1（启用）

启用时，代理相关更新被立即同步；禁用时，更新被批量累积，并按照wazuh_database.interval定义的间隔周期性地同步。

源码视角的实时模式：real_time=1时，wm_database_main()走 inotify 分支（wm_database.c）——建立内部事件队列，用inotify_add_watch()监视client.keys所在目录（IN_CLOSE_WRITE | IN_MOVED_TO）与共享组目录（额外含IN_MOVED_FROM | IN_CREATE | IN_DELETE），一旦文件系统事件到达即触发wm_sync_agents()或wm_sync_file()。注意client.keys变更引起的整表同步只在worker 节点上执行，master 上的代理增删由authd负责。

3.3wazuh_database.interval

同步间隔（秒），仅在实时模式关闭时生效。

wazuh_database.interval=60

• 默认值：60秒
• 允许值：正整数（1–86400）
• 注意：仅当wazuh_database.real_time=0时适用

源码视角的定时模式：real_time=0时，wm_database_main()走轮询分支（wm_database.c）：先等待一个interval，然后循环执行wm_check_agents()（通过stat()比对client.keys的 mtime/inode 判断是否变化，变化时在 worker 上触发wm_sync_agents()）与wdb_update_groups()（同步共享组目录与数据库中的组记录）。循环末尾会精确补偿休眠时间，若上一轮执行超时，则记录Time interval exceeded by %lld seconds警告。因此该选项直接决定定时模式下的数据库写入节奏。

3.4wazuh_database.max_queued_events

队列中允许累积的最大代理事件数，达到该上限会强制触发一次同步（即使间隔尚未到达）。

wazuh_database.max_queued_events=10000

• 默认值：10000个事件
• 允许值：正整数（100–1000000）

源码视角的队列机制：在实时模式下，该值用于初始化内部事件队列。wm_inotify_setup()中queue_init(data->max_queued_events > 0 ?>wazuh_database.sync_agents=1 wazuh_database.real_time=1 wazuh_database.interval=60 wazuh_database.max_queued_events=10000

4.2 定时同步（降低数据库压力）

适合大规模部署，减少数据库写入频率：

wazuh_database.sync_agents=1 wazuh_database.real_time=0 wazuh_database.interval=300 wazuh_database.max_queued_events=50000

该配置的效果：

• 关闭实时同步；
• 每 5 分钟同步一次；
• 允许更大的事件队列，减少强制同步触发次数。

4.3 高频更新（低延迟）

适合对状态实时性要求极高的环境：

wazuh_database.sync_agents=1 wazuh_database.real_time=1 wazuh_database.interval=30 wazuh_database.max_queued_events=5000

4.4 禁用同步（测试场景）

wazuh_database.sync_agents=0 wazuh_database.real_time=0 wazuh_database.interval=60 wazuh_database.max_queued_events=10000

警告：禁用同步可能导致代理状态与组信息过期失真（stale），只建议在测试或特定部署场景下使用。

5. 底层同步流程：从client.keys到全局库

理解上述选项后，可以从源码看清完整同步链路。核心函数wm_sync_agents()（wm_database.c）调用OS_ReadKeys()读取client.keys，再交给sync_keys_with_wdb()（wm_database.c）执行双向校准：

1. 插入新代理：遍历密钥库，若某代理 ID 存在于client.keys但不在全局库，则通过wdb_insert_agent()写入 agent 表；
2. 删除失效代理：反向遍历全局库中的代理，若某代理没有对应密钥，则调用wdb_remove_agent()删除记录及其工件（diff 文件、计数器、时间戳），并通过 router 向inventory-sync发布{"command": "delete_agent", "agent_id": ...}消息，通知索引器侧清理数据（见 send_agent_delete_to_inventory_sync()）。

组同步侧，wdb_update_groups()与wm_sync_shared_group()（wm_database.c）负责将共享组目录（SHAREDCFG_DIR）中的组与全局库对齐：目录被删除则移除组记录，目录存在但库中无记录则插入。

全局库中与同步状态相关的字段定义在 schema_global.sql，是理解"同步状态"语义的直接依据：

• sync_status：'synced' | 'syncreq' | 'syncreq_status' | 'syncreq_keepalive'，默认'synced'；
• group_sync_status：'synced' | 'syncreq'，默认'synced'；
• connection_status：'pending' | 'never_connected' | 'active' | 'disconnected'，默认'never_connected'。

对应的同步操作封装在 wdb.h 中，例如wdb_global_sync_agent_info_get/set（按syncreq标记批量获取/回写代理同步状态）、wdb_global_sync_agent_groups_get（按同步条件获取代理组并可选置为 synced）、wdb_global_update_agent_connection_status（更新连接状态与同步状态）以及wdb_global_recalculate_agent_groups_hash（重算组哈希）。集群同步场景正是通过"读syncreq→ 推送 → 写回synced"的标记位机制，配合last_id游标分页（见wdb_global_sync_agent_info_get的 last_agent_id 参数）实现的。

6. 性能考量

6.1 实时模式 vs 定时模式

从源码看，"批量写入"在实时模式下主要由 inotify 事件队列与共享组目录扫描实现批量处理；定时模式下则由interval控制写入节奏，二者对应文档给出的代理规模建议是经验分界，实际取舍应结合数据库所在磁盘 IOPS 与代理变更频率。

6.2 队列容量规划

max_queued_events同时影响内存占用与同步触发频率，建议按代理规模设置：

• 小规模（<1000 代理）：5000–10000 个事件
• 中规模（1000–5000 代理）：10000–25000 个事件
• 大规模（>5000 代理）：25000–100000 个事件

需要注意的是，max_queued_events在源码中同时作用于内核 inotify 队列上限（写入/proc/sys/fs/inotify/max_queued_events）与模块内部队列（不足时回退 16384），过小的值在突发大量文件变更时可能触发IN_Q_OVERFLOW（模块记录Inotify event queue overflowed）或内部队列满的错误。

6.3 数据库影响

代理同步涉及的数据库操作包括：

• agent 表上的 INSERT/UPDATE；
• 代理组哈希重算（wdb_global_recalculate_agent_groups_hash）；
• 连接状态更新；
• SQLite 事务提交。

高频同步可能加剧数据库文件碎片化，可结合 Wazuh DB 的wazuh_db.fragmentation_threshold相关设置监控与处理（见 Wazuh DB 配置参考）。

7. 监控与验证

7.1 查看同步状态

通过wazuh-db的 socket 接口直接查询全局库中代理的同步状态（连接状态、同步标记）：

echo 'global sql SELECT id,name,connection_status,sync_status FROM agent' | \ /var/wazuh-manager/bin/wazuh-db

输出中的sync_status列即对应 schema 中'synced'/'syncreq'/...的取值，可用于判断是否有代理处于待同步（syncreq）状态。

7.2 查看队列统计

在 manager 日志中检索队列相关告警：

grep "queued_events" /var/wazuh-manager/logs/wazuh-manager.log

实时模式下还会出现Internal queue is full、Inotify event queue overflowed等关键日志，它们直接对应队列容量不足。

7.3 数据库活动监控

持续跟踪 wazuh-db 的写入行为：

tail -f /var/wazuh-manager/logs/wazuh-manager.log | grep "wazuh-db"

模块自身的运行信息（同步耗时、周期完成时间）由WM_DATABASE_LOGTAG（wazuh-manager:database，见 wm_database.h）输出，例如wm_sync_agents(): %.3f ms与Cycle completed: %.3lf ms，可在调试级别日志中观察同步开销。

8. 故障排查

8.1 代理显示为已断开（Disconnected）

• 可能原因：数据库同步被禁用或同步失败。
• 排查步骤：
  1. 确认wazuh_database.sync_agents=1；
  2. 检查 wazuh-db 进程是否运行：ps aux | grep wazuh-db；
  3. 查看日志中的数据库错误。

8.2 数据库 CPU 占用过高

• 可能原因：代理数量多时同步过于频繁。
• 解决步骤：
  1. 切换为定时模式：wazuh_database.real_time=0；
  2. 增大间隔：wazuh_database.interval=300；
  3. 增大队列：wazuh_database.max_queued_events=50000。

8.3 代理组不更新

• 可能原因：同步队列已满或同步被禁用。
• 解决步骤：
  1. 检查队列大小是否与代理数量匹配；
  2. 确认wazuh_database.sync_agents=1；
  3. 检查日志中是否出现max_queued_events exceeded类警告（对应内部队列满错误）。

9. 关联文档导航

• Database Sync 模块总览 —— 模块功能清单与定位；
• Wazuh DB 配置参考 —— 数据库备份与调优（<wdb>节、wazuh_db.*选项）；
• Agent 管理模块 —— 代理生命周期管理；
• Manager 配置参考 —— 管理端全部配置选项索引。

配套源码速查：本文所有底层结论均可追溯至 wm_database.c（模块主循环、inotify 事件处理、密钥库双向同步）、wm_database.h（wm_database结构体定义）、schema_global.sql（同步状态字段约束）与 wdb.h（同步查询/更新接口）。建议在调整内部选项前先结合上述源码确认参数语义与默认值边界。

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