企业官网建设流程全解析

Wazuh DB（wazuh-db）配置完全指南：自动备份、内部选项与性能调优

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

本篇技术指南以 Wazuh 仓库中 Wazuh DB 模块的配置参考文档为主体，系统讲解 wazuh-db 守护进程的两类配置入口：wazuh-manager.conf中控制 global.db 自动备份与保留策略的<wdb>XML 配置块，以及wazuh-manager-internal-options.conf中控制线程池、事务提交、文件句柄与数据库碎片化治理的wazuh_db.*内部选项。读完本文，你将能够完整继承并落地文档中的所有配置示例，理解每个参数的默认值、取值范围及其在源码中的实际解析与生效位置，并掌握手动备份、恢复、完整性校验与常见故障的排查方法。

Wazuh DB 是什么：配置的对象与背景

Wazuh DB（wazuh-db）是 Wazuh Manager 的中央数据库服务，负责存储 Agent 注册信息、漏洞数据、文件完整性监控（FIM）状态以及其他模块的运行状态，并提供统一的查询接口与自动备份能力。它与模块概览、架构及数据库表结构的对应关系可参考 Wazuh DB 模块文档。

从该模块文档可以确认其运行架构：守护进程内部由四类线程协作——Dealer 线程接收 Unix socket 连接并将对端加入队列；Worker 线程池（默认 8 个）负责出队、执行查询并回发响应；Garbage collector 线程关闭过期数据库句柄；Backup 线程周期性创建global.db备份。这正是本文两个配置入口分别控制的部分：XML 配置块控制 Backup 线程，内部选项控制 Worker 线程池、事务提交与碎片化治理行为。

数据库文件的物理位置（文档明确给出）：

• 全局数据库：/var/wazuh-manager/queue/db/global.db
• Agent 数据库：/var/wazuh-manager/queue/db/agents/<agent-id>.db
• 备份目录：/var/wazuh-manager/backup/db/

入口一：wazuh-manager.conf 中的<wdb>备份配置

配置文件：/var/wazuh-manager/etc/wazuh-manager.confXML 节点：<wdb>作用：控制数据库自动备份与保留策略。

backup 块结构与子选项

<backup>是<wdb>下的备份配置块，必须通过database属性指定目标数据库（当前仅支持global），其下包含三个子选项：enabled、interval、max_files。

这些默认值可以在配置解析源码中得到逐一印证。在 wazuh_db-config.c 的wdb_init_conf()中，初始化时即写入默认值：

void wdb_init_conf() { os_calloc(WDB_LAST_BACKUP, sizeof(wdb_backup_settings_node*), wconfig.wdb_backup_settings); for (int i = 0; i < WDB_LAST_BACKUP; i++) { os_calloc(1, sizeof(wdb_backup_settings_node), wconfig.wdb_backup_settings[i]); wconfig.wdb_backup_settings[i]->enabled = true; // 默认 yes wconfig.wdb_backup_settings[i]->interval = 86400; // 默认 1 天 wconfig.wdb_backup_settings[i]->max_files = 3; // 默认 3 份 } }

同文件的Read_WazuhDB()还展示了严格的 XML 校验逻辑：<wdb>的直接子节点必须是backup，database属性必须且只能取global，否则会报XML_INVELEM/XML_INVATTR/XML_VALUEERR错误；enabled的值由eval_bool()解析，仅接受yes或no；interval由w_parse_time()解析为秒数，必须为正；max_files必须是纯数字且大于 0。任何一个子节点取值非法，整个配置块都会被拒绝——这意味着部署前务必用wazuh-control check-config之类的配置校验手段（或观察 Manager 日志）确认 XML 无误。

配置示例（完整继承原文档四种典型场景）

默认配置（标准备份策略）：

<wdb> <backup database="global"> <enabled>yes</enabled> <interval>1d</interval> <max_files>3</max_files> </backup> </wdb>

备份文件写入/var/wazuh-manager/backup/db/。

高频备份（关键业务环境）：

<wdb> <backup database="global"> <enabled>yes</enabled> <interval>6h</interval> <max_files>8</max_files> </backup> </wdb>

延长保留期（保留更多备份历史）：

<wdb> <backup database="global"> <enabled>yes</enabled> <interval>1d</interval> <max_files>30</max_files> </backup> </wdb>

禁用备份（测试或存储受限环境）：

<wdb> <backup database="global"> <enabled>no</enabled> </backup> </wdb>

注意：禁用后不会再生成自动备份，但手动备份（下一节）始终可用。

自动备份的底层实现：VACUUM INTO 加 Gzip 压缩

文档在“性能考量”一节指出备份使用 SQLite 的备份 API 创建快照，对性能影响极小，仅在快照创建瞬间对数据库产生短暂锁。从源码看，实际实现位于 wdb_global.c 的wdb_global_create_backup()中，其流程比“调用备份 API”更具体：

1. 以当前时间戳生成备份文件名（global-<timestamp>格式），写入WDB_BACKUP_FOLDER指定的备份目录；
2. 先提交未决事务（wdb_commit2）并清空全部预编译语句缓存（wdb_finalize_all_statements），为执行VACUUM INTO做准备；
3. 执行SQLITE的VACUUM INTO语句，生成一个压缩整理后的完整数据库副本；
4. 将该副本用 gzip 压缩为global-<timestamp>.db.gz并删除未压缩的中间文件；
5. 调用wdb_global_remove_old_backups()按max_files清理超出保留上限的旧备份。

也就是说，最终落盘的备份是gzip 压缩过的 SQLite 全量副本，这也解释了为什么文档估算的磁盘占用（小部署约 50–200 MB、中型部署 200 MB–2 GB、大型部署 2 GB 以上）是“数据库大小 × max_files”量级——每个备份都是全量拷贝。

备份线程的调度逻辑位于 main.c 的run_backup()：它读取最近一次备份时间（wdb_global_get_most_recent_backup），之后每隔interval秒判断是否到达备份时刻，到达则调用wdb_global_create_backup()。该线程仅在配置enabled=yes时才会被创建，与 XML 中<enabled>no</enabled>的行为完全对应。

入口二：wazuh-manager-internal-options.conf 中的 wazuh_db.* 内部选项

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

文档明确提示：应使用wazuh-manager-internal-options.conf而非直接修改默认的internal_options.conf，以便在升级时保留自定义设置。这一点与仓库中 wazuh-manager-internal-options.conf 的注释一致：该文件用于运行时覆盖 Manager 内部选项，默认值编译在二进制中，仅在需要覆盖时添加条目，格式为module.option=value，且升级过程不会覆盖此文件。

完整选项清单如下（注释中的取值范围与默认值均已与 main.c 中getDefine_Int_default()的调用逐一核对）：

# Wazuh DB debug level (0-2) wazuh_db.debug=0 # Worker thread pool size (1-32, default: 8) wazuh_db.worker_pool_size=8 # Minimum commit interval for transactions (seconds, 1-3600, default: 10) wazuh_db.commit_time_min=10 # Maximum commit interval for transactions (seconds, 1-3600, default: 60) wazuh_db.commit_time_max=60 # Maximum number of open database connections (1-4096, default: 64) wazuh_db.open_db_limit=64 # Maximum file descriptors (1024-1048576, default: 458752) wazuh_db.rlimit_nofile=458752 # Database fragmentation threshold percentage (0-100, default: 75) wazuh_db.fragmentation_threshold=75 # Fragmentation delta for triggering vacuum (0-100, default: 5) wazuh_db.fragmentation_delta=5 # Free pages percentage to maintain (0-99, default: 0) wazuh_db.free_pages_percentage=0 # Maximum allowed fragmentation percentage (0-100, default: 90) wazuh_db.max_fragmentation=90 # Interval to check database fragmentation in seconds (1-30758400, default: 7200 = 2 hours) wazuh_db.check_fragmentation_interval=7200

各选项在源码中的读取位置（main.c 启动阶段）：

wconfig.worker_pool_size = getDefine_Int_default("wazuh_db", "worker_pool_size", 1, 32, 8); wconfig.commit_time_min = getDefine_Int_default("wazuh_db", "commit_time_min", 1, 3600, 10); wconfig.commit_time_max = getDefine_Int_default("wazuh_db", "commit_time_max", 1, 3600, 60); wconfig.open_db_limit = getDefine_Int_default("wazuh_db", "open_db_limit", 1, 4096, 64); nofile = getDefine_Int_default("wazuh_db", "rlimit_nofile", 1024, 1048576, 458752); wconfig.fragmentation_threshold = getDefine_Int_default("wazuh_db", "fragmentation_threshold", 0, 100, 75); wconfig.fragmentation_delta = getDefine_Int_default("wazuh_db", "fragmentation_delta", 0, 100, 5); wconfig.free_pages_percentage = getDefine_Int_default("wazuh_db", "free_pages_percentage", 0, 99, 0); wconfig.max_fragmentation = getDefine_Int_default("wazuh_db", "max_fragmentation", 0, 100, 90); wconfig.check_fragmentation_interval = getDefine_Int_default("wazuh_db", "check_fragmentation_interval", 1, 30758400, 7200);

逐项解读

wazuh_db.debug（0–2，默认 0）：调试日志级别。源码中通过循环调用nowDebug()逐级提升调试输出，排查 wazuh-db 行为问题时可临时调高。

wazuh_db.worker_pool_size（1–32，默认 8）：Worker 线程池大小，直接决定同时处理 socket 查询的线程数。文档的故障排查建议指出：当 wazuh-db CPU 占用偏高时可增大该值。

wazuh_db.commit_time_min/wazuh_db.commit_time_max（1–3600 秒，默认 10 / 60）：控制 SQLite 事务的批量提交时机。从 wdb.c 的提交条件可以确认其精确语义：

当距离上一次查询已超过commit_time_min秒，或者距离事务开始已超过commit_time_max秒时，触发提交。

这是一种“高频写入不拖延、长事务有上限”的折中策略：既通过批量提交降低 commit 开销，又保证任何事务最长运行不超过commit_time_max。文档建议出现数据库锁错误时检查长查询并增大 commit 时间参数。

wazuh_db.open_db_limit（1–4096，默认 64）：同时打开的数据库连接数上限。wdb.c中的池回收逻辑会在连接数超过该值时关闭多余句柄，与 Garbage collector 线程配合，防止 Agent 数量增长导致句柄泄漏。

wazuh_db.rlimit_nofile（1024–1048576，默认 458752）：进程可打开的最大文件描述符数。默认值很高，是为了容纳大规模部署下众多 SQLite 连接与日志文件的并发打开。

碎片化治理四参数（fragmentation_threshold/fragmentation_delta/free_pages_percentage/max_fragmentation）加检查间隔check_fragmentation_interval（1–30758400 秒，默认 7200，即 2 小时）：这组参数控制 wazuh-db 的自动 VACUUM 决策。从 wdb.c 的碎片化检查逻辑看，只有同时满足“空闲页比例不低于free_pages_percentage”且命中下列任一条件时才会触发 VACUUM：

• 碎片率超过max_fragmentation（强制线，默认 90%）；
• 碎片率超过fragmentation_threshold（默认 75%）且此前从未执行过 VACUUM；
• 碎片率超过fragmentation_threshold，且比上次 VACUUM 时的碎片率还高出fragmentation_delta（默认 5 个百分点）。

换言之，这组参数让 wazuh-db 在“数据库文件无限膨胀”和“频繁 VACUUM 消耗 IO”之间取得平衡：正常情况下只在碎片较上次明显恶化时才整理，碎片率达到 90% 则无条件整理。

通过 socket 查询当前生效配置

这些内部选项并非不可观测。wdb.c中处理getconfig命令时会将commit_time_max、commit_time_min、open_db_limit、worker_pool_size及各碎片化参数打包进wazuh_db节点返回给调用方，因此可以通过 wazuh-db socket 查询当前实际生效的内部选项值，作为验证配置是否被正确加载的手段。

手动备份与恢复

手动备份

创建 global 数据库的手动备份（确保一致性的做法是先停服务）：

# 停止 wazuh-manager 以确保一致性 systemctl stop wazuh-manager # 如不存在则创建备份目录 mkdir -p /var/wazuh-manager/backup/db/manual # 复制 global 数据库 cp /var/wazuh-manager/queue/db/global.db \ /var/wazuh-manager/backup/db/manual/global-$(date +%Y%m%d-%H%M%S).db # 重新启动 wazuh-manager systemctl start wazuh-manager

从备份恢复

# 停止 wazuh-manager systemctl stop wazuh-manager # 恢复备份（将 TIMESTAMP 替换为实际备份文件名） cp /var/wazuh-manager/backup/db/global-TIMESTAMP.db \ /var/wazuh-manager/queue/db/global.db # 恢复属主与权限 chown wazuh:wazuh /var/wazuh-manager/queue/db/global.db chmod 660 /var/wazuh-manager/queue/db/global.db # 启动 wazuh-manager systemctl start wazuh-manager

查看备份文件

ls -lh /var/wazuh-manager/backup/db/

注意：自动备份由 wazuh-db 生成时为.db.gz压缩格式且带时间戳，手动备份为普通.db副本；恢复前请先用gunzip解开压缩备份，并确认文件属主与权限。

性能考量与大型部署调优

• 备份影响：快照式备份（源码确认为VACUUM INTO+ gzip）期间对数据库产生短暂锁，整体性能影响极小；
• 存储需求：每个备份都是全量副本，可用以下命令监控磁盘占用：

du -sh /var/wazuh-manager/backup/db/ du -sh /var/wazuh-manager/queue/db/

文档给出的典型体积参考：<100 个 Agent 约 50–200 MB；100–1000 个 Agent 约 200 MB–2 GB；1000+ 个 Agent 通常 2 GB 以上。

• 大型部署调优建议：降低备份频率、减少保留份数以控制磁盘增量：

<wdb> <backup database="global"> <enabled>yes</enabled> <interval>12h</interval> <!-- 更低频 --> <max_files>5</max_files> <!-- 保留更少备份 --> </backup> </wdb>

故障排查手册

检查 wazuh-db 状态

# 确认 wazuh-db 是否运行 systemctl status wazuh-manager | grep wazuh-db # 检查 wazuh-db socket ls -l /var/wazuh-manager/queue/db/wdb # 测试数据库连接 echo 'agent 000 sql SELECT name FROM sqlite_master' | \ /var/wazuh-manager/bin/wazuh-db

查看 wazuh-db 日志

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

数据库完整性校验

sqlite3 /var/wazuh-manager/queue/db/global.db "PRAGMA integrity_check;"

预期输出：ok。

常见问题速查

延伸阅读

• Wazuh DB 模块文档 —— 模块概览、线程架构、socket 协议与数据库表结构
• Manager 配置参考 —— Manager 全部配置项
• Vulnerability Scanner 配置 —— 使用 wazuh-db 存储漏洞数据的模块
• Task Manager 配置 —— 使用 wazuh-db 存储任务状态的模块

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