配置文件参考
cheesewaf.yaml 主配置文件结构导航、顶层键解析、超时控制与热重载范围说明。
CheeseWAF 在首次启动时会在运行数据目录的 config/ 目录下自动生成 cheesewaf.yaml 主配置文件（默认 ./data/config/cheesewaf.yaml）。预设配置模板可参考源码库中的 configs/cheesewaf.yaml。
configs/cheesewaf.yaml 是源码模板，不是运行时状态文件。初始化、站点管理和控制台保存操作会写入运行时配置；源码构建时请先复制到 ./data/config/cheesewaf.yaml 或其他明确的数据目录，避免把数据库路径、证书、密钥和站点变更写回 Git 工作区中的模板。
顶层配置块索引
| 顶层配置键 | 功能模块与定位 | 详细参考章节 |
|---|---|---|
server | 基础网络监听、管理端口与网络层超时 | 架构介绍 · TLS 与证书 |
tls | 数据平面 TLS/HTTPS 证书与 HSTS 配置 | TLS 与证书 |
setup | 初始化状态与运行时数据目录定义 | 系统初始化 · 存储与调度 |
deployment / cluster | 部署形态（单机/集群）与高可用协同参数 | 集群高可用 |
console | Web 控制台个性化与管理端登录安全 | Bot 与验证码 · 监控与日志 |
sites | 业务反向代理站点、域名与上游配置 | 站点管理 |
protection | 全局安全基线（语义引擎、IP、Bot、限流等） | 安全防护策略 |
block_page | 阻断拦截页模板与自定义响应 HTML 清洗 | 拦截响应页 |
storage | temporary SQLite 管理存储；预留但当前会拒绝的 production 配置；可选外部日志 Sink | 存储与调度 |
logging | 访问日志输出级别、格式与文件轮转 | 监控与日志 |
ai | ALAP 大语言模型连接与异步研判参数 | ALAP 异步审查 |
update | OTA 预留配置；当前运行时尚未实现更新 Worker | 系统运维 |
scheduler | 自动化清理、配置快照与定时报表任务调度器；配置快照不是完整数据库导出 | 存储与调度 |
edge | 边缘响应头注入、静态缓存与 Gzip/Brotli 压缩 | 边缘特性 |
monitor | Prometheus 指标导出、Remote Write 与告警通知器 | 监控与日志 |
apisec | API 资产发现、Schema 校验与 RBAC 权限矩阵 | API 接口安全 |
performance | Go 运行时垃圾回收（GC）自适应调优（memory_limit_ratio / min_gogc） | 架构介绍 |
time_sync | NTP 时间同步服务器与时钟偏差共识算法配置 | 监控与日志 |
captcha_assets | 验证码自定义背景图与点选图标静态资源目录 | Bot 与验证码 |
acme | ACME 自动化证书签发与 DNS 认证提供商配置 | TLS 与证书 |
vulnerability | 漏洞预警情报源订阅配置 | 系统运维 |
超时机制配置
- 接入层超时：
server.read_timeout、server.write_timeout与server.idle_timeout控制客户端与 WAF 之间的 HTTP 连接生命周期。 - 反向代理超时：
sites[].waf.performance.proxy_timeout控制 WAF 向后端上游源站发起请求与等待响应的最大超时时间。
防护模式与请求体限制
- WAF 防护模式 (
waf.mode)：支持block（阻断恶意请求）、monitor（仅记录告警不拦截）以及off（完全关闭防护）。历史配置别名log会被系统自动识别并归一化为monitor。 - 请求体截断保护 (
max_body_bytes)：当入站请求体大小超出配置的max_body_bytes上限时，数据平面直接向客户端响应 HTTP413 Request Entity Too Large，避免大请求体绕过或耗尽内存。
网关适配器认证与代理穿透
- 专用适配器令牌 (
CHEESEWAF_ADAPTER_TOKEN)：使用外部网关适配器（CheeseWAF-Adapters）时，调用方必须通过独立的X-CheeseWAF-Adapter-Token请求头传递密钥；它不是 Bearer Token，严禁放入Authorization头部。 - 可信代理网段 (
trusted_cidrs)：默认可信 CIDR 列表为空。若 CheeseWAF 部署在可信前置代理（如 CDN 或云负载均衡器）之后，需显式配置sites[].waf.access_control.trusted_cidrs（例如127.0.0.1/32或::1/128），才能安全解析X-Forwarded-For中的真实客户端 IP。
动态热重载范围
- 即时热生效：在 Web 控制台或通过 REST API 保存站点配置、自定义规则、IP 黑白名单、Bot 挑战策略及 ACL 规则时，系统会在内存中实时原子热重载，无需重启服务进程。
- 需重启生效：修改
server.listen、server.admin_listen等底层物理监听端口或网络驱动层参数后，须重启服务进程（通过cheesewaf restart或 systemd 服务管理器）。