产品文档

• 1: CheeseWAF
  • 1.1: 架构与工作原理
  • 1.2: 部署 & 安装
    • 1.2.1: Linux 部署（systemd）
    • 1.2.2: Docker Compose 部署
    • 1.2.3: Windows 部署
    • 1.2.4: macOS 部署
  • 1.3: 快速上手
    • 1.3.1: 系统初始化向导
    • 1.3.2: 接入首个业务站点
    • 1.3.3: 接入大语言模型
  • 1.4: 核心概念
    • 1.4.1: 流量处理路径与两阶段流水线
    • 1.4.2: 防护等级机制
    • 1.4.3: 独立特征与夹杂特征
    • 1.4.4: 统一管理入口与权限模型
  • 1.5: 站点管理与反向代理
  • 1.6: 网关适配器 (Adapters)
  • 1.7: 安全防护策略
    • 1.7.1: AST 语义分析引擎
    • 1.7.2: 自定义正则规则
    • 1.7.3: IP、地理位置与客户端指纹
    • 1.7.4: Bot 挑战与人机验证码
    • 1.7.5: 流量限流
    • 1.7.6: 访问控制列表（ACL）
    • 1.7.7: 拦截响应页与 HTML 安全清洗
  • 1.8: API 接口安全
  • 1.9: 边缘优化：响应头、静态缓存与内容压缩
  • 1.10: TLS 与证书管理
  • 1.11: ALAP 异步审查与自学习机制
  • 1.12: 插件体系与 CRP 规范
  • 1.13: 监控、日志与攻击态势大屏
  • 1.14: 集群高可用与节点协同
  • 1.15: 存储与调度管理
  • 1.16: 商业化平台架构
  • 1.17: 独立控制面运行时
  • 1.18: Web 管理控制台
  • 1.19: 命令行与 TUI 交互
  • 1.20: RESTful 管理接口
  • 1.21: 配置文件参考
  • 1.22: 系统运维与安全加固
  • 1.23: 从源码构建与开发指南
  • 1.24: 开源许可与生态仓库
  • 1.25: 问题反馈与安全报告
  • 1.26: 开发者想说
    • 1.26.1: 开发者想说

1 - CheeseWAF

CheeseWAF 是基于 Go 语言构建的商用级自托管 Web 应用防火墙（WAF）。系统采用数据平面与管理平面解耦的双平面架构，运行时内置轻量级持久化存储保存管理状态，并支持扩展 PostgreSQL 作为高性能异步访问日志存储。

在架构设计上，CheeseWAF 将**数据平面（Data Plane）请求路径与管理平面（Management Plane）**及异步 ALAP 审查流程彻底解耦。同一个 cheesewaf 进程内启动两个监听平面：数据平面负责有界、低延迟的同步检测与反向代理；管理平面承载管理 API、控制台界面与后台威胁审查队列，实时请求路径绝不阻塞等待远程大模型分析。

为什么选择 CheeseWAF

市面上常见的 Web 安全防护方案通常面临几个痛点：

1. 传统正则 WAF（如 ModSecurity / CRS 规则集）：靠维护成千上万条正则表达式防守。攻击者通过大小写变异、畸形 URL 编码或特殊注释很容易绕过；同时误报率高，日常运维需要大量写白名单，改一条规则要反复调试。
2. 直接调大模型的实验性 WAF：每个 HTTP 请求都同步等待大模型返回，网页延迟直接飙升 500 ms 到 2 s，不仅拖慢业务，还极易刷爆 API 费用；一旦外部大模型网络抖动或超时，业务直接瘫痪。
3. 重型容器全家桶（如雷池 SafeLine 等）：通常需要启动 5 到 10 个 Docker 容器（Tengine、Postgres、Redis 等），常驻内存 1～2 GB 起步，低配轻量云主机或 VPS 难以承受。
4. 商业云 WAF（如 Cloudflare / 云厂商高防）：所有业务流量必须穿透第三方公网云节点，存在数据合规与隐私出境风险；按流量计费成本不可控，无法在纯离线内网部署。

CheeseWAF 的思路是：用自研 AST 语法树做毫秒级即时拦截，大模型只在后台异步值守存疑流量，既没有正则的误报和绕过，也不增加线上任何延迟，极简轻量开箱即用。

方案对比

核心机制

1. 高性能数据平面检测：入站请求经多层解码后进入抽象语法树（AST）语义分析引擎，对请求中可能存在的 SQL 注入、跨站脚本（XSS）、命令执行（RCE）等攻击和恶意请求实施毫秒乃至微秒级的阻断。
2. 异步 ALAP 智能研判：在响应返回客户端后，对于判定边界模糊或嵌入在大段正常文本中的可疑样本，系统将其投递至后台异步审查队列，由配置的大语言模型（兼容 OpenAI Response / Chat Completions 协议与 Anthropic Messages 协议）进行深度语义研判。
3. 闭环规则采纳与防御加固：对模型判定为高危（high）或严重（critical）的威胁样本，系统支持人工确认或自动采纳。站点级自动采纳会沉淀为该站点的自定义载荷规则；全局 IP 黑名单与客户端软指纹处置仍需操作者明确执行。

默认监听平面

CheeseWAF 默认在以下端口提供网络服务：

文档导航

1.1 - 架构与工作原理

传统的 Web 应用防火墙多依赖庞大的正则表达式特征库。这类方案不仅规则维护成本高昂，且极易被多重编码、语法嵌套与字符混淆手法绕过；而若在实时请求链路中同步调用大语言模型（LLM），又会引入不可控的网络时延与单点可用性风险。

针对上述挑战，CheeseWAF 采用了双平面解耦与异步智能旁路的设计理念，将毫秒级的确定性拦截与深度语义分析有效结合。

系统架构与平面分工

数据平面（Data Plane）

数据平面负责接收 HTTP/1.1、HTTPS 及 HTTP/3 业务流量，并在毫秒级时延内按序执行流水线检测：

1. 网络与指纹检测：执行 IP 黑白名单、GeoIP 地理位置封禁及客户端软指纹校验。
2. 访问控制与防刷：执行 Bot 挑战验证、滑动窗口限流及排队室调度。
3. AST 语义分析：对多层解码后的请求参数进行抽象语法树语法分析与攻击识别。
4. 反向代理转发：检测通过的合法流量直接代理转发至配置的上游源站。

数据平面处于业务核心链路，坚持极简与确定性原则，绝不产生对外部大模型调用的同步等待。

管理平面（Management Plane）

管理平面通过独立的监听端口提供系统管理与运维能力：

• /setup 初始化向导：首次部署引导与管理员账号凭据初始化。
• Web 管理控制台：基于 React 构建的可视化管理界面。
• RESTful 管理接口：承载自动化脚本与第三方运维集成的 /api 端点。
• 监控与指标导出：提供 Prometheus Metrics 采集端点与健康检查接口。

ALAP 异步审查机制

在数据平面向客户端完成响应交付后，CheeseWAF 可将特定样本投递至后台异步审查队列（ALAP，AI Large-Language-Model Auto Pilot）：

• 高等级拦截样本：防护等级 5 下被阻断的独立攻击命中。
• 夹杂命中样本：防护等级 2～4 下被放行但包含可疑特征的复合长文本。
• 边界与待审样本：被语义引擎标记为置信度较低或处于边界状态的流量。

后台 Worker 会异步调用配置的大语言模型进行深度研判。安全运维人员可通过控制台确认研判结果，或开启自动采纳机制，将高危威胁自动沉淀为长期防护规则。详见 ALAP 与审查队列。

交付组件与单二进制分发

CheeseWAF 采用单一二进制（BusyBox 模式）交付，包含核心引擎、管理控制台及交互工具：

相关阅读

• 流量处理路径与流水线
• 防护等级与降误报机制
• 独立控制面运行时
• 系统安装与部署指引

1.2 - 部署 & 安装

CheeseWAF 支持以系统服务、容器编排或单二进制运行于各类主流操作系统。根据生产或测试环境的实际架构，选择对应的安装方式：

发行包列表与发布策略

从正式稳定版（v0.3.9+）起，CheeseWAF 遵循**服务器优先（Server-First）**发布策略：稳定 Release 默认优先分发经 Sigstore 签名校验与 SBOM 物料清单认证的 Linux 服务器架构发行包；Windows 与 macOS 桌面版作为可选的操作端构建产物提供。

可前往 GitHub Releases 下载官方发布的预编译包：

安装完成后，请继续参考 快速上手 完成系统初始化与站点接入。

小型主机建议使用轻量档：逻辑核数不超过 2 或内存不超过 2 GB 时，初始化向导会推荐 low。探测超时、取消或请求失败也会回退到 low。程序配置的安全默认值仍是 127.0.0.1:9443；官方 Linux 一键安装器会明确启用公网 HTTPS 引导，并要求管理员保管一次性 Token 与安全入口。storage.profile: production 在完整生产接线完成前会拒绝启动，不会静默回退到 SQLite。

1.2.1 - Linux 部署（systemd）

本指南适用于 Linux 物理机、云服务器和虚拟机。在线安装会自动选择语言、识别 CPU 架构、拉取最新稳定版发行包、校验校验和文件、在可用时安装 systemd 服务并输出初始化地址；无法访问 GitHub 时，请使用文末的离线流程。

1. 一键安装（推荐）

只需复制并粘贴以下命令。脚本会在交互终端中询问语言，随后自动完成下载、校验和安装：

curl -fsSL https://github.com/LaokeQwQ/CheeseWAF/releases/latest/download/install-linux.sh | sudo bash

如果当前用户已经是 root，可以省略 sudo：

curl -fsSL https://github.com/LaokeQwQ/CheeseWAF/releases/latest/download/install-linux.sh | bash

脚本需要从 /dev/tty 读取语言、安装根目录和安全入口输入，因此即使脚本内容通过标准输入传入，也不会把交互输入误当作脚本内容。无人值守环境请设置文档列出的 CHEESEWAF_* 环境变量后运行已下载的脚本；不要把密码或安装 Token 写入命令行历史。

如需安装指定的稳定版或 Beta 版本，可设置 CHEESEWAF_RELEASE（v 前缀可省略）：

curl -fsSL https://github.com/LaokeQwQ/CheeseWAF/releases/latest/download/install-linux.sh \
  | sudo env CHEESEWAF_RELEASE=v0.4.2-beta bash

选择语言后，交互流程会询问应用安装根目录。例如输入 /opt/cheesewaf，二进制、Web 资源、运行时配置、数据和日志会分别放在该目录下的 bin/、web/、config/、data/、logs/ 子目录。直接回车则保留下面列出的分散式 FHS 默认布局。除非显式设置 CHEESEWAF_UNIT_DIR，systemd 单元仍安装在 /etc/systemd/system。

自动化部署时，可在调用安装器前设置 CHEESEWAF_INSTALL_DIR。如果同时设置 CHEESEWAF_PREFIX、CHEESEWAF_WEB_DIR、CHEESEWAF_CONFIG_DIR、CHEESEWAF_DATA_DIR 或 CHEESEWAF_LOG_DIR，对应的单独目录覆盖根目录派生值：

curl -fsSL https://github.com/LaokeQwQ/CheeseWAF/releases/latest/download/install-linux.sh \
  | sudo env CHEESEWAF_INSTALL_DIR=/opt/cheesewaf bash

安装根目录必须是绝对路径，并且每个路径段只能使用 ASCII 字母、数字、.、_ 或 -；共享系统目录以及含 Shell 元字符的路径会被拒绝。

安装过程会依次完成：

1. 选择中文或 English，并检测 Linux、架构、磁盘空间、curl、tar、sha256sum、awk 和 od 等前置条件。
2. 从 GitHub Releases 拉取指定服务器发行包，校验对应的唯一 SHA256SUMS 条目；校验失败会立即停止，不会启动旧或未知来源的程序。
3. 将二进制、Web 控制台、运行时配置和 systemd 单元安装到标准路径，并创建无登录权限的 cheesewaf 系统用户。
4. 生成 HTTPS 管理监听、一次性初始化 Token 和安全入口。入口路径只允许 ASCII 字母和数字；脚本会默认生成随机值，也允许你输入自定义值，不符合规则时会拒绝继续。
5. 在可用时启动 systemd 服务，检查端口和健康状态，并打印版本、架构、安装路径、配置/数据/日志路径、服务状态、公网管理地址、检测到的内网管理地址、Token 有效期和后续操作。没有 systemd 时只安装文件，并明确报告服务未启动。

安装结束时请保存终端输出中的完整初始化地址。交互终端会打印公网初始化地址和安全入口，也会打印每个检测到的内网地址；非交互运行默认不向标准输出回显敏感信息，而是写入仅 root 可读的 install-secrets.txt 回执，只有在输出环境受保护时才设置 CHEESEWAF_SHOW_SECRETS=1。Token 只在首次初始化阶段有效，默认短期有效且完成初始化后立即撤销；不要把完整地址提交到工单、截图、Shell 历史或日志。

2. 首次初始化与公网入口

初始化期间，使用安装器输出的 https:// 地址打开向导。初始化地址固定使用 /setup 路径：

https://PUBLIC_IP:9443/setup#setup_token=ONE_TIME_TOKEN

其中 ONE_TIME_TOKEN 是一次性初始化 Token。浏览器会从 URL fragment 读取 Token，随后清理地址栏，并通过 X-CheeseWAF-Setup-Token 请求头提交；Token 不会放在查询参数、Cookie 或 localStorage 中。

初始化完成后，访问 https://PUBLIC_IP:9443/SECURITY_ENTRY。安全入口只包含 ASCII 字母和数字，由安装器默认生成，也可以使用通过校验的自定义值。入口会签发访问 Cookie 并跳转到登录页；初始化路由与完成后的安全入口是两个独立路径。

该安装路径默认使用 HTTPS 并公开绑定管理面。安装器会将检测到的公网主机写入 admin.env；如果服务器位于 NAT 或反向代理之后且没有直接公网地址，请设置 CHEESEWAF_ADMIN_PUBLIC_HOST。生产环境应进一步限制安全组、防火墙和反向代理来源，只允许受信管理网络访问 9443；不要把初始化地址分享给其他人。若证书由本机临时生成，浏览器首次访问会显示证书警告，生产环境请替换为受信证书。

向导完成后，初始化 Token 立即失效。遗失地址时，可在服务器上查看权限为 0600 的运行时文件，或在管理员尚未创建前重置 Token：

sudo -u cheesewaf cheesewaf setup token reset

重置后必须使用命令输出的新地址；旧地址不可恢复。

对已有配置再次运行安装器会执行升级：现有监听地址、TLS、站点、策略和安全入口会保留。请使用同一安装根目录，或再次设置相同的 CHEESEWAF_*_DIR 覆盖项，确保升级的是预期实例。

3. 安装后检查

systemctl status cheesewaf --no-pager
ss -ltnp | grep ':9443'
sudo journalctl -u cheesewaf -n 100 --no-pager

检查输出中的版本和架构是否与目标服务器匹配，并确认管理端口只由预期进程监听。完成初始化后，再到控制台接入第一个站点和配置数据面监听。

默认 FHS 路径如下：

当设置 CHEESEWAF_INSTALL_DIR=/opt/cheesewaf 时，对应的应用路径为 /opt/cheesewaf/bin/cheesewaf、/opt/cheesewaf/web、/opt/cheesewaf/config/cheesewaf.yaml、/opt/cheesewaf/data 和 /opt/cheesewaf/logs。

4. 离线或手动安装

在可联网机器上，从 GitHub Releases 下载与服务器架构匹配的完整 .tar.gz、SHA256SUMS 和（发布时提供的）签名文件，再将它们传到目标服务器。在下载目录先校验并解压，然后进入解压目录执行安装器：

sha256sum --check SHA256SUMS --ignore-missing
tar -xzf cheesewaf-*-linux-*.tar.gz
cd cheesewaf-*-linux-*
sudo ./install-linux.sh

离线脚本仍会在本地交互选择语言、生成安全入口并启动服务，但不会尝试重新下载发行包。若系统没有 systemd，请改用手动方式复制二进制和 web/dist，并由现有进程管理器启动；必须保留运行时配置副本与数据目录，不能直接修改仓库中的 configs/cheesewaf.yaml 模板。

不要使用未经校验的二进制、第三方镜像或旧版安装脚本。完整安装包包含 cheesewaf、Web 资源、配置模板、systemd 单元和本安装脚本；缺少其中任一项时应停止并重新下载。

1.2.2 - Docker Compose 部署

本方案适用于容器化云原生基础设施。仓库提供经过加固的 Dockerfile 与 Compose 示例，示例会在本地构建镜像；除非另行核对镜像来源，否则不要把 cheesewaf:dev 当作厂商签名或已发布到可信仓库的镜像。运行时默认使用专用非 root 用户（UID 10001）并启用只读根文件系统。

容器资源由宿主机和容器限制共同决定。逻辑核数不超过 2 或内存不超过 2 GB 时，初始化向导会推荐 low；探测失败或超时也会回退到 low。Compose 示例只把管理端口绑定到宿主机回环地址 127.0.0.1:9443。storage.profile: production 当前仍会因生产接线不完整而拒绝启动，不会回退到 SQLite。

编排配置（Compose 文件）

参考项目仓库中的 deploy/docker/docker-compose.yml：

services:
  cheesewaf:
    image: cheesewaf:dev
    build:
      context: ../..
      dockerfile: deploy/docker/Dockerfile
    user: "10001:10001"
    restart: unless-stopped
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp:size=32m,mode=1777,noexec,nosuid,nodev
    ports:
      - "8080:8080"
      - "127.0.0.1:9443:9443"
    volumes:
      - cheesewaf-data:/var/lib/cheesewaf
      - cheesewaf-logs:/var/log/cheesewaf
    healthcheck:
      test: ["CMD", "/usr/local/bin/cheesewaf-entrypoint", "healthcheck"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  cheesewaf-data:
  cheesewaf-logs:

启动与初始化

执行以下命令在后台启动容器并观察日志：

docker compose -f deploy/docker/docker-compose.yml up -d
docker compose -f deploy/docker/docker-compose.yml logs -f cheesewaf

容器首次启动时会自动在持久化目录生成初始管理员配置，并为管理平面签发自签名证书。本 Compose 文件将管理端口仅绑定到 Docker 宿主机回环地址（127.0.0.1:9443），请在宿主机浏览器中打开 https://127.0.0.1:9443/setup。从其他机器访问时，请先将 CHEESEWAF_SSH_TARGET 设置为 SSH 目标，再执行 ssh -N -L 9443:127.0.0.1:9443 "$CHEESEWAF_SSH_TARGET" 建立隧道，之后仍使用同一回环地址；如需直接暴露端口，请显式修改绑定并配置相应的访问控制。亦可执行以下命令通过容器终端进行 CLI 初始化：

首次初始化尚未完成时，容器日志不会打印初始化 Token 或完整地址，只显示基础 /setup 地址、受保护的 /var/lib/cheesewaf/setup.url 路径和不含秘密的随机回执。请在 10 分钟有效期内从权限为 0600 的文件读取完整地址。初始化完成后，Token 会被撤销；过期的 setup.url 文件会被清理。

docker compose -f deploy/docker/docker-compose.yml exec -it cheesewaf \
  cheesewaf --config /var/lib/cheesewaf/config/cheesewaf.yaml \
  --data-dir /var/lib/cheesewaf setup

停止容器（docker compose -f deploy/docker/docker-compose.yml down）时，SQLite 数据、证书、自定义规则和日志会保存在命名卷 cheesewaf-data 与 cheesewaf-logs 中。配置 storage.postgresql 时，它接收外部访问日志；默认 storage.profile: temporary 下，Docker 卷仍保存管理数据库。预留的 production 配置当前会在启动时拒绝。

1.2.3 - Windows 部署

在 Windows 操作系统中，CheeseWAF 提供三种运行分发形态，底层核心功能与防护引擎完全一致：

初始化向导会根据本机资源推荐档位。逻辑核数不超过 2 或内存不超过 2 GB 时使用 low；探测失败或超时也会回退到 low。管理面默认只监听 127.0.0.1:9443，本地辅助控制器另监听 127.0.0.1:17943。

1. 单文件 CLI 与原生 Windows 服务

适用于快速调试、脚本调用或注册为 Windows 系统服务：

# 前台交互式启动 WAF 转发与管理服务
.\cheesewaf.exe serve --config .\data\config\cheesewaf.yaml --data-dir .\data

# 查询服务运行状态与 PID 租约
.\cheesewaf.exe status

# 安全终止运行中的服务
.\cheesewaf.exe stop

原生 Windows 系统服务感知

cheesewaf serve 内置了原生 Windows 服务状态机（基于 golang.org/x/sys/windows/svc）：

• 当被 Windows 服务控制管理器（SCM）拉起时，程序会自动识别为服务运行模式，无缝响应 SCM 的停止（Stop）与关机（Shutdown）信号并执行优雅退出。
• 服务名称默认注册为 CheeseWAF，无需借助第三方包装工具（如 NSSM 或 WinSW）。

2. 便携 Zip 压缩包

便携包内包含预设的配置文件模板与编译好的 Web 控制台静态资源：

1. 将 cheesewaf-amd64-windows-*.zip 解压至指定目录（如 D:\CheeseWAF）。
2. 在该目录下通过 PowerShell 执行初始化与启动：

# 首次运行推荐通过交互式向导配置凭证
.\cheesewaf.exe setup

# 启动 WAF 守护进程
.\cheesewaf.exe serve --config .\data\config\cheesewaf.yaml --data-dir .\data

首次初始化尚未完成时，进程日志只显示基础 /setup 地址、受保护的 data\setup.url 路径和不含秘密的随机回执。请在 10 分钟有效期内从权限为 0600 的文件读取完整地址。初始化完成后，Token 会被撤销；过期的 setup.url 文件会被清理。

3. NSIS 图形安装向导 (推荐)

适用于需要图形化引导、注册 Windows 服务与创建系统快捷方式的生产或办公桌面环境：

1. 下载并运行 cheesewaf-amd64-windows-*-setup.exe 安装包（Windows ARM64 请使用 arm64 版本）。
2. 按照向导提示选择安装路径。安装程序会注册 CheeseWAF Windows 服务，并设置为手动启动（start= demand）；需要时可通过服务管理器或 sc.exe 显式启动/停止。
3. 卸载程序时，系统将默认保留 data\ 目录中的业务数据库与配置文件，防止误删历史数据。

本地辅助控制器（GUI）

cheesewaf-gui 是面向桌面环境的轻量级浏览器本地控制器，用于便捷管理主服务进程的生命周期：

• 网络边界：严格限制仅监听本地回环地址 127.0.0.1:17943，杜绝局域网未授权探测。
• 核心功能：启动/停止/重启服务、显示运行状态与 PID、直达 Web 管理控制台及快捷打开配置目录。
• 运行模型：按需调用本地 cheesewaf serve 进程，不是第二套管理后台；控制器仅监听本机回环地址。

.\cheesewaf-gui.exe --config .\data\config\cheesewaf.yaml --data-dir .\data

启动后可在浏览器中直接打开 http://127.0.0.1:17943/ 进入桌面控制器界面。

1.2.4 - macOS 部署

在 macOS 系统下，CheeseWAF 支持桌面图形包与命令行压缩包两种运行方式：

初始化向导会根据本机资源推荐档位。逻辑核数不超过 2 或内存不超过 2 GB 时使用 low；探测失败或超时也会回退到 low。管理面默认只监听 127.0.0.1:9443。

1. DMG 桌面安装包

适用于本地开发调试与桌面工作站环境：

1. 根据芯片架构下载安装包：Apple Silicon（M 系列芯片）选择 cheesewaf-arm64-darwin-*.dmg，Intel 芯片选择 cheesewaf-amd64-darwin-*.dmg。
2. 双击打开 DMG 镜像，将 CheeseWAF 拖拽至 Applications（应用程序） 文件夹。
3. 从启动台或应用程序文件夹中启动 CheeseWAF。

程序启动后将拉起基于浏览器的本地控制器服务（监听回环地址 http://127.0.0.1:17943/），支持一键启动/停止主服务、查看运行状态及快速直达 Web 管理控制台。默认运行时数据目录为 ~/Library/Application Support/CheeseWAF。

2. 命令行压缩包（tar.gz）

适用于纯终端操作或无图形界面环境：

# 解压对应架构的压缩包
tar -xzf cheesewaf-arm64-darwin-*.tar.gz
cd cheesewaf-*

# 运行终端初始化向导
./cheesewaf setup

# 启动 WAF 守护服务
./cheesewaf serve --config ./data/config/cheesewaf.yaml --data-dir ./data

如果首次 Web 初始化尚未完成，进程输出只显示基础 /setup 地址、受保护的 data/setup.url 路径和不含秘密的随机回执。请在 10 分钟有效期内从权限为 0600 的文件读取完整地址。初始化完成后，Token 会被撤销；过期的 setup.url 文件会被清理。

服务启动后，使用浏览器访问 http://127.0.0.1:9443/ 进入 Web 管理控制台登录页。

1.3 - 快速上手

先执行 Linux 一键安装。脚本会询问语言、拉取并校验最新稳定版、生成公网 HTTPS 管理入口并输出短期初始化地址，然后按照以下三个核心步骤完成防护：

curl -fsSL https://github.com/LaokeQwQ/CheeseWAF/releases/latest/download/install-linux.sh | sudo bash

语言选择后，安装器会询问应用安装根目录。输入 /opt/cheesewaf 可将二进制、Web 资源、配置、数据和日志集中在同一目录；直接回车则使用标准 FHS 布局。安装完成后会输出公网和检测到的内网初始化地址；需要指定版本时设置 CHEESEWAF_RELEASE=vX.Y.Z[-beta]。自动化变量、升级行为和安全入口说明请参考 Linux 安装指南。

1.3.1 - 系统初始化向导

首次安装 CheeseWAF 后，系统尚未生成管理员凭证与业务站点配置。CheeseWAF 提供 Web 图形向导 与 终端 CLI 向导 两种初始化方式，用户可根据部署场景自由选择。

方式一：终端命令行初始化向导（推荐运维使用）

在终端中执行以下命令即可启动轻量级交互式向导：

cheesewaf setup

1. 自动化硬件探测与画像适配

向导启动时会自动探测主机的计算与存储资源（CPU 核心数、物理可用内存及磁盘挂载容量），并智能推荐最适配的运行画像（Hardware Profile）：

• low（轻量模式）：适合 1～2 核 CPU / 1～2 GB 内存的轻量云服务器或小内存 VPS；请求检测超时自动降级到此档。
• smart（智能模式，默认）：推荐 2～4 核 CPU / 4～8 GB 内存的普通云服务器使用；根据请求风险动态分配检测深度。
• medium（均衡模式）：手动指定，固定检测深度 2，单请求耗时上限 50 ms。
• high（强力模式）：适合 4 核以上 CPU / 8 GB 以上内存的核心业务网关，执行全量深度语义分析。
• custom（自定义模式）：手动精确调优各项检测深度与超时预算。

探测最长运行 30 秒。探测超时或失败时，向导会自动回退推荐 low 档，后续也可在管理后台随时调整。

2. 交互式凭据录入与安全事务保障

• 用户名：输入 3–32 个 ASCII 字符的用户名。用户名必须以 ASCII 字母开头、以 ASCII 字母或数字结尾，只能包含 ASCII 字母、数字、.、_ 和 -。非 ASCII 字符、Unicode 空白字符、控制字符（Cc）和格式/不可见字符（Cf）都会被拒绝；服务端保留原始值，不会自动去除空格或转小写。
• 密码：新密码至少需要 10 个字符，并满足大写字母、小写字母、不重复数字、特殊字符 4 类中的至少 3 类。常见密码和简单模式会被拒绝，密码也不能等于或包含用户名。Web 向导的确认步骤只显示密码已设置，不显示密码、密码哈希、系统主加密密钥或管理员凭证摘要。
• 可选集成：交互式终端向导在提交配置时可以应用 GeoIP、Prometheus /metrics 和 VictoriaLogs 设置。Web 向导只会把集成选择记录在初始化草稿中供核对，不会直接应用到运行配置；完成初始化后，还要到对应的系统设置、存储或监控页面配置支持的集成。PostgreSQL 选项只是异步访问日志 Sink，不是管理数据库。
• 事务性安全承诺：配置、数据库、证书和管理员状态在最终步骤前只保存在内存中，只有最终提交才会写入。中断不会留下部分初始化状态。CLI 语言选择是单独的用户偏好，可能写入 data/cli.lang；这个文件不是运行时配置，也不是管理数据库。

3. 脚本无交互自动化（Headless Mode）

在 CI/CD 自动化流水线或云主机批量装机时，可传入命令行标志实现全自动无人值守初始化：

cheesewaf setup --yes \
  --username admin \
  --password-stdin < /etc/cheesewaf/secrets/admin_pass.txt \
  --admin-listen 0.0.0.0:9443 \
  --skip-probe

注意：无人值守模式下 --yes 必须与 --password-stdin 联合使用，确保初始密码满足安全策略要求；向导执行完成后会根据管理端 TLS 状态自动输出正确的 http:// 或 https:// 访问面板链接。

方式二：Web 浏览器图形向导

完成初始化向导后，访问管理地址将自动重定向至 Web 控制台登录页。后续可通过终端交互工具 waf-cli 或命令行 cheesewaf user 随时重置管理员密码。

1.3.2 - 接入首个业务站点

登录 Web 控制台后，进入 站点管理 → 新建站点，按以下步骤配置业务反向代理：

配置完成后，修改本地 hosts 文件或调整 DNS 解析，将域名指向 CheeseWAF 数据平面的监听地址（默认 http://127.0.0.1:8080），验证业务流量能否正常回源代理。

关于健康检查、SSL 证书自动申请及路径重写等高级配置，请参考 站点与反向代理配置。

1.3.3 - 接入大语言模型

CheeseWAF 的 ALAP（AI Large-Language-Model Auto Pilot）支持接入主流大语言模型服务，对边界可疑流量进行异步深度语义研判。

在 Web 管理控制台中进入 AI 配置 模块，填写以下参数：

旧配置迁移： 当前版本不会读取旧的 ai.base_url 与 ai.auto_agree。请将 ai.base_url 手动迁移为 ai.api_base，并将审批开关分别迁移到各站点的 sites[].waf.semantic_policy.auto_agree；保存后按需 reload/restart 服务。

运行与安全建议

• 坚持异步模式：确保配置中 ai.async: true 保持开启状态，严禁在同步实时转发路径中同步等待外部模型返回。
• 连通性校验：保存配置前，建议点击控制台中的 测试连接 按钮，验证网络连通性与 API 密钥有效性。
• 渐进式启用自动采纳：在接入初期建议保持 sites[].waf.semantic_policy.auto_agree 关闭，在人工观察审查队列研判质量稳定后，再评估是否开启自动规则沉淀。

关于 ALAP 的工具调用权限、自动化研判流程及定时自学习机制，请参考 ALAP 与审查队列。

1.4 - 核心概念

本章详细介绍 CheeseWAF 的核心架构设计与检测判定原理。在调整生产环境防护等级或定制安全策略之前，建议深入了解以下机制：

1.4.1 - 流量处理路径与两阶段流水线

CheeseWAF 的流量处理链路分为同步检测链路与异步旁路研判链路两大部分。系统在同步链路中采用了独特的**两阶段流水线（Two-Phase Pipeline）**架构，兼顾极端高并发下的微秒级快速阻断与复杂语法树解析的高吞吐：

flowchart TB
  Client[客户端请求] --> Ingress[网络接入层 HTTP / HTTPS / HTTP3]
  subgraph Phase1 [Phase 1: 预筛选器链 Pre-Filters (顺序执行 / 短路阻断 / 优先级 < 290)]
    IP{IP / 地理位置 / 软指纹} -->|放行| Bot{Bot 挑战 / 限流 / 排队室}
    Bot -->|放行| Rules{自定义规则引擎 Priority 250}
  end
  Ingress --> IP
  IP -->|命中黑名单| Block[返回拦截页]
  Bot -->|触发挑战| Challenge[验证码校验 / 排队等待]
  Challenge -->|挑战通过| Rules
  Rules -->|命中阻断规则| Block

  subgraph Phase2 [Phase 2: 语义分析组 Semantic Group (Worker 线程池并发 / 确定性合并 / 优先级 >= 290)]
    Sem[AST 语义分析引擎: SQL / XSS / RCE / LFI / NoSQL / SSTI 等]
  end
  Rules -->|无阻断| Sem

  Sem --> Shape{特征形态判断}
  Shape -->|独立特征 2~5 级| Block
  Shape -->|夹杂特征 5 级| Block
  Shape -->|夹杂特征 2~4 级| Pass[放行并投递异步队列]
  Shape -->|无异常| Origin[转发至上游源站]
  Pass --> Origin
  Pass -.-> Queue[ALAP 异步审查队列]
  Sem -.->|5 级阻断样本| Queue
  Queue --> LLM[调用配置的大语言模型]
  LLM --> Review{研判判定}
  Review -->|高危 / 严重| Rule[沉淀为长期规则]
  Review -->|低危 / 误报| Dismiss[归档忽略 / 加入白名单]
  Rule -.-> IP

两阶段流水线设计（Phase 1 与 Phase 2）

为了在生产高流量下保障服务时延确定性，CheeseWAF 的请求检测流水线在内存中将所有注册的检测器按 Priority 分离为两个截然不同的执行阶段：

1. Phase 1：Pre-Filters 顺序预筛选器（优先级 < 290）

• 涵盖范围：IP 黑白名单与地理围栏、Bot 挑战与防刷识别、分片滑动窗口限流，以及 自定义正则规则引擎（Priority 250）。
• 执行特性：单线程顺序执行，对执行顺序极度敏感。
• 快速短路机制：任意前置检测器判定为 ActionBlock 时，请求将立即被短路拦截并终止流水线，绝对不进入昂贵的 AST 语法树解析阶段。这使得针对已知敏感路径、特定扫描特征的大规模扫描流量在毫秒级内被拦截丢弃。

2. Phase 2：Semantic Group 并发语义分析组（优先级 >= 290）

• 涵盖范围：SQL 注入、XSS 跨站脚本、RCE 命令注入、LFI 文件遍历、NoSQL 注入、SSTI 模板注入、SSRF 以及 XXE 等深层语法分析器。
• 执行特性：
  • Worker 协程池并发调度：系统维护全局共享的 Worker 协程池（上限为 8 协程），入站请求将各项语义分析任务并发推入任务队列并行分析。
  • 请求上下文隔离（Forked Context）：每个检测器在独立的 Fork 上下文中运行，向元数据和检测结果写入数据时互不干扰，在架构上杜绝并发数据竞争（Data Race）。
  • 确定性优先级合并：所有并发检测器执行完成（或超时）后，系统严格按照既定的优先级序号执行稳定合并，确保威胁评估结果与日志记录在任何并发环境下均保持 100% 幂等。

流水线超时与预算控制（Budget Protection）

• 100ms 硬超时防线：整个流水线设有全局 100ms 硬超时时钟，防止复杂畸形载荷将 WAF 进程长时间卡死。
• 分析预算耗尽策略（budget_exhausted_policy）：当请求体异常巨大或语法树分析在超时窗口内未能完整结束时，系统将触发安全兜底策略：
  • auto：遵循全局 web_attack 防护策略等级映射兜底动作。
  • open：以业务可用性为先予以放行（记录指标）。
  • observe：仅记录观察日志，不执行硬阻断。
  • closed：安全优先，触发人机挑战或严格拦截。
• 过载保护（Guard Overload）：底层内置基于协程管程与信号量的过载防护，当极端并发导致分析队列溢出时主动触发 ErrDetectionOverload，保障主服务进程的高可用与自愈。

异步旁路研判链路（ALAP Loop）

异步链路完全独立于实时转发流程，在客户端完成响应接收后于后台触发：

• 样本投递：在防护等级 2～4 下被放行的夹杂特征样本，以及在等级 5 下被阻断的高危样本，均会被投递至 ALAP 审查队列。
• 模型智能分析：后台 Worker 异步调用大模型提取攻击意图并输出置信度评估。
• 闭环规则沉淀：人工审核可将确认样本转换为所选的载荷、URI、IP 或指纹规则；站点级自动采纳范围更窄，仅写入该站点的自定义载荷规则。

1.4.2 - 防护等级机制

CheeseWAF 支持为每个站点独立配置防护等级（sites[].waf.paranoia_level）。取值范围为 0 至 5，系统默认推荐值为 3。

防护等级机制的核心目标是在保证高检出率的同时最大程度降低误报率。语义分析引擎在对单个解码后的参数值进行检测时，会根据特征形态（独立特征 vs 夹杂特征）与当前防护等级执行分级处置。

防护等级对照表

动态临时升档机制

在 防护等级 4 下，当系统检测到业务流量中出现疑似攻击的夹杂特征时，为防止攻击者正处于探测阶段，系统会自动将该站点的防护等级临时上调至 5 级（严格模式），持续时间由 promote_seconds（例如 300 秒）指定。

• 状态持久化：升档截止时间戳保存在本地管理存储中，重启后依然生效；访问日志可异步投递至 PostgreSQL 存储。
• 自动衰减：当升档时间窗口结束且无新的可疑特征触发时，站点将自动恢复至原本的 4 级状态。

严格等级（5 级）审查说明

在防护等级 5 下被阻断的请求样本仍会被投递至 ALAP 审查队列，并附带 blocked 标记：

• 不可追溯放行：由于该请求已被物理拦截，管理员无法在审查控制台中将其变更为“已放行”状态。
• 规则沉淀转换：审查通过后，可将样本一键转化为长期的全局防护规则（包括特征规则、URL 路径规则、IP 黑名单或客户端软指纹封禁）。

1.4.3 - 独立特征与夹杂特征

在 Web 业务场景中，用户提交的内容形态各异。例如在论坛发帖、博客评论或技术社区中，正常用户经常会引用代码片段或 SQL 查询语句；若简单使用纯特征匹配，极易导致大面积误报。

为了解决这一问题，CheeseWAF 的 AST 语义分析引擎在完成参数多层解码后，会根据载荷的上下文占比与包裹形态，将判定命中标记为独立特征（Isolated Payload）或夹杂特征（Embedded Payload）。

特征形态定义

1. 独立特征（Isolated Payload）

独立特征指参数值的绝大部分内容直接构成了攻击载荷本身，且缺乏合法的业务文本上下文。

• 典型场景：在登录框或搜索框参数中直接输入 UNION SELECT 1,2,3、' OR 1=1 -- 等。
• 包裹判定：即使攻击者添加了 @、结尾分号、/{${...}} 或简单前后缀等轻微包装，只要有效载荷占据主要结构，引擎依然将其判定为独立特征。
• 处置策略：在防护等级 2～5 下，独立特征命中将触发立即阻断。

2. 夹杂特征（Embedded Payload）

夹杂特征指疑似攻击语法的片段嵌入在较长的正常自然语言、技术文章或商品描述等大段文本中。

• 典型场景：技术论坛帖子中讨论数据库优化并包含了一条示例 SQL，或者文章中讨论 Log4j 漏洞时引用了相关 payload 字符串。
• 处置策略：在标准防护等级（2～4 级）下，系统采取放行请求并异步投递 ALAP 队列的策略，避免中断正常业务交互；在严格模式（5 级）下，则执行严格拦截。

引擎隔离覆盖范围与工程实现事实

为确保策略的严密性与透明度，以下为当前版本语义引擎针对特征隔离的具体实现边界：

• 已覆盖 Gadget：隔离分析器专门覆盖了 PHP/JSP 动态 WebShell、Log4j JNDI 注入 以及 短引号/谓词 SQL 注入（针对长度不超过 96 个字符/rune 的短片段）。
• 形态守卫机制：针对 XSS、系统命令执行（RCE）、服务端模板注入（SSTI）、服务端请求伪造（SSRF） 及 XML 外部实体注入（XXE） 等攻击类型，引擎采用专门的文档形态守卫（Document Shape Guards），独立于短 Gadget 隔离分析器运行。
• 兜底证据链：被标记为 embedded 的命中在低于 5 级时免除阻断；对于未明确归类的边界命中，系统依然严格遵从 blockableHit 证据判定逻辑，不会默认降级为夹杂特征。
• 最佳实践建议：特征隔离机制用于降低已知 Gadget 在富文本业务下的误报率，若业务系统完全面向 API 或固定表单交互，建议在关键接口上开启更高的防护等级或针对性 Schema 校验。

1.4.4 - 统一管理入口与权限模型

CheeseWAF 提供了三种各司其职的管理入口，满足可视化运维、无图形终端交互及 CI/CD 自动化集成等多种场景：

三端统一鉴权机制

当配置文件中启用 setup.three_end_unified: true 时，CheeseWAF 实现了三大管理入口的用户体系与权限闭环：

• 用户身份通用：在 Web 控制台创建的管理员或普通用户账号，可直接用于 TUI 命令行登录与 API 鉴权。
• 统一 RBAC 授权：在控制台“系统管理”中生成的 API Token，遵从与用户角色相同的 RBAC 权限矩阵（定义于 apisec.permissions）。
• 细粒度角色划分：系统默认预设 admin（拥有 ["*"] 全量权限）与 readonly（拥有 ["read:*", "read:cluster"] 等只读权限）等角色。
• 身份字段精确校验：用户名遵循 CLI 手册中的 3–32 个 ASCII 字符规范。角色必须精确匹配 apisec.permissions 中的已配置键；首尾或嵌入 Unicode 空白、控制字符（Cc）、格式/不可见字符（Cf）以及 *、: 等权限表达式都会被拒绝。服务端不会自动去空格或改大小写。

操作审计链路

当开启 apisec.audit.enabled: true 时，所有通过 Web 控制台、TUI 终端以及 REST API 执行的配置变更、策略启停及用户管理操作，均会结构化写入 apisec.audit.path 指定的审计日志文件中，确保生产环境运维操作的可追溯性。

相关模块参考

• Web 控制台使用指南
• 命令行与 TUI 交互手册
• REST API 接口与权限对照表

1.5 - 站点管理与反向代理

在 CheeseWAF 中，站点（Site） 是业务反向代理与安全策略的基本组织单元。一个站点由一组对外绑定的域名（Host）与一个或多个后端上游源站（Upstream）构成。

管理与导入方式

• Web 控制台：进入 站点管理 模块进行可视化新增、编辑与策略调试。
• RESTful API：支持通过 GET/POST /api/sites 与 GET/PUT/DELETE /api/sites/{id} 接口进行自动化管理。
• Nginx 配置导入：支持调用 POST /api/nginx/import 解析并导入现有的 Nginx server 块配置。

站点配置字段说明

负载均衡算法详解

针对配置了多个后端上游源站的站点，sites[].loadbalance 支持以下 4 种负载均衡策略：

1. round_robin（轮询，默认）：请求依次循环分发给各健康上游节点，适合各源站规格性能一致的标准集群。
2. weighted（加权轮询）：根据各节点在 upstreams[].weight 中配置的权重比例分配请求（例如权重 3:1 时，每 4 个请求分配 3 个至主节点），适合异构服务器部署。
3. ip_hash（客户端源 IP 哈希）：基于真实客户端源 IP 进行一致性哈希计算，将同一客户端的请求稳定分发至同一后端节点，用于维持服务端本地会话（Session Sticky）。
4. least_conn（最小活跃连接数）：实时追踪分配至各源站的在途未完成请求数，将新请求动态分发至当前处理中连接数最少的健康节点，有效平抑长耗时请求导致的请求堆积。

上游健康检查探测

当开启 health_check.enabled: true 时，CheeseWAF 会定期向各后端源站发起 HTTP 探测请求（路径由 health_check.path 指定）：

• 当源站连续探测失败次数达到 unhealthy_threshold 时，该节点将被暂时标记为不健康并移出负载均衡池。
• 当节点恢复正常且连续成功达到阈值后，系统将自动恢复其流量分发。
• 若所有源站均标记为不健康，Fail-Open 仅可对安全重试的空 GET 或 HEAD 请求回退尝试配置的上游。非幂等方法（如 POST、PUT）或携带请求体的请求不会被重放。

路径重写与重定向

路径改写规则支持配置 pattern（匹配正则）、replacement（替换目标）以及 redirect_code：

• 内部静默改写：当 redirect_code: 0 时，系统在转发给源站前在内存中改写 URI 路径，客户端对此无感知。
• 外部重定向：当 redirect_code 设为 301 或 302 时，直接向客户端返回 HTTP 重定向响应。

站点专属自定义规则

每个站点均独立维护专属的 custom_rules 列表：

• 支持通过 Web 控制台「规则管理」直接编辑或导入导出。
• 支持使用 CLI 工具进行 CI/CD 流水线自动化同步，例如 export CHEESEWAF_SITE_ID='site-demo'; export CHEESEWAF_RULES_FILE='rules.yaml'; cheesewaf rules import --site "$CHEESEWAF_SITE_ID" --file "$CHEESEWAF_RULES_FILE"。
• 规则在请求进入 AST 语义分析前（Phase 1 Priority 250）进行评估，可精准阻断特定站点的探测流量。

1.6 - 网关适配器 (Adapters)

CheeseWAF-Adapters 是面向 CheeseWAF 的 Go-first、自托管网关适配组件。它将特定网关的胶水代码与 WAF 核心检测引擎彻底解耦，通过轻量级守护进程 adapterd 部署于网关或业务旁边，负责将外部网关协议转换为标准化的版本化检查契约，并将决策结果转换回网关原生响应。

架构与核心原则

    NGINX / Envoy / Kubernetes 网关
                  |
                  | auth_request / ext_authz / ext_proc
                  v
    CheeseWAF-Adapters (Go, adapterd)
                  |
                  | 版本化 HTTP 检查契约 (/api/v1/adapter/inspect)
                  v
    CheeseWAF 核心服务 (自托管, Go)
                  |
                  +-- Inline 同步安全决策 (allow / block / challenge)
                  +-- 异步 Telemetry / Postanalytics (/api/v1/adapter/telemetry)

• 自托管与 Sidecar 优先：不依赖任何 SaaS 控制面或外部厂商服务；默认以网关或工作负载旁边的本地独立进程（127.0.0.1:9080）运行。
• 适配器保持极薄：仅处理网关协议解析与响应语义适配，不复制任何检测器、规则解析、签名计算或管理状态；所有安全决策完全交由 CheeseWAF 核心处理。
• 默认 Fail-Closed（安全熔断）：当 CheeseWAF 核心不可用或超时时，适配器默认返回 503 Service Unavailable，严禁在未显式配置时静默放行流量。
• 有界请求体（Bounded Body）机制：默认不向核心转发请求体；仅在策略明确开启时以受控上限（默认 64 KB）转发。超过上限时标记 BodyTruncated=true；若核心返回 allow 或超时，适配器严格返回 HTTP 413 Request Entity Too Large。
• 安全认证与网络边界：网关调用适配器时使用专用的 X-CheeseWAF-Adapter-Token 请求头进行校验（严禁通过 Authorization: Bearer 传递），并严格校验 CHEESEWAF_ADAPTER_TRUSTED_PROXY_CIDRS。

契约边界 (Inspection Contract v1)

适配器基于 contracts/inspection/v1 契约与 CheeseWAF 核心通信：

• Inline 检查接口：默认路径为 /api/v1/adapter/inspect，接收标准化请求元数据、客户端上下文、TLS 指纹和有界请求体，在设定的时间预算（默认 100ms）内返回决策。
• 核心决策动作：
  • allow：放行请求并转发至上游业务。
  • block：阻断请求并返回安全拦截页面或特定状态码。
  • challenge：触发人机验证（如 JavaScript 挑战或 CAPTCHA）。
  • log：放行请求并记录告警（归一化为观察模式）。
• 异步 Telemetry 接口：默认路径为 /api/v1/adapter/telemetry，限速且尽力而为（Best-Effort）接收事件，不阻塞实时流量链路。

网关接入配置示例

1. NGINX auth_request 接入

在 NGINX 中利用 ngx_http_auth_request_module 模块将子请求交由 adapterd 授权：

# 业务站点配置
location / {
    auth_request /cheesewaf_auth;
    auth_request_set $waf_status $upstream_status;

    # 授权通过后正常转发上游
    proxy_pass http://backend_cluster;
}

# 适配器授权内部端点
location = /cheesewaf_auth {
    internal;
    proxy_pass http://127.0.0.1:9080/v1/inspect;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-CheeseWAF-Adapter-Token "YOUR_SECURE_ADAPTER_TOKEN";
    proxy_set_header X-Original-URI $request_uri;
    proxy_set_header X-Original-Method $request_method;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

2. Envoy ext_authz 接入

在 Envoy 过滤器链中配置 HTTP 外部鉴权过滤器：

http_filters:
  - name: envoy.filters.http.ext_authz
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
      http_service:
        server_uri:
          uri: 127.0.0.1:9080
          cluster: cheesewaf_adapter_cluster
          timeout: 0.100s
        authorization_request:
          allowed_headers:
            patterns:
              - exact: cookie
              - exact: user-agent
              - prefix: x-
          headers_to_add:
            - key: x-cheesewaf-adapter-token
              value: "YOUR_SECURE_ADAPTER_TOKEN"
      failure_mode_allow: false
      with_request_body:
        max_request_bytes: 65536
        pack_as_bytes: true

适配器运行与环境变量参考

# 启动本地适配器守护进程
adapterd --listen 127.0.0.1:9080 --core-url http://127.0.0.1:8080

演进规划

1. 协议完善：扩展流式 Envoy ext_proc 适配器，支持大容量请求体流式检测与响应修改。
2. Kubernetes 集成：推出轻量级 Kubernetes Sidecar Controller，基于 Pod Annotation 自动完成适配器注入与流量路由。
3. 生态兼容：完成与 Kong、Apache APISIX、Traefik 等主流云原生 API 网关的官方适配。

1.7 - 安全防护策略

CheeseWAF 构建了从网络接入层到应用语义层的多维度防御体系。全局防护基线由主配置文件中的 protection 与 protection.policy 定义，同时支持在各业务站点（sites[].waf.protection_policy）中按需覆盖。

1.7.1 - AST 语义分析引擎

CheeseWAF 的核心检测器采用抽象语法树（AST）语法分析架构，而非传统的静态正则表达式堆叠。入站请求首先经过 URL 编码、Unicode、十六进制及嵌套 Base64 等多层递归解码，随后构建特定语言的语法树，精准识别载荷的语义意图。

经过基于 多套权威工业级实网语料库与独立标注保真度分类器（Corpus Fidelity Classifier）的大规模评测与缺口修复，语义引擎的标注可信检出率（TPR）已提升至 97.08%。

语义引擎开关配置

在站点配置项 sites[].waf.semantic_engines 中，可按业务技术栈独立启用或关闭专项分析引擎：

性能保障与低时延设计

为了在具备深层语法分析能力的同时保持微秒级的极低延迟，引擎实现了以下优化机制：

• 廉价子串门限前置（Substring Pre-Filters）：在执行复杂的语法树解析或高成本正则前，先通过常数时间（O(1) 或 O(n)）的廉价特征子串门限进行初筛，无潜在风险的正常业务参数在微秒级直接跳过。
• 并发 Worker 池与请求上下文隔离：多个语义分析器在 Phase 2 阶段通过并发 Worker 协程池执行，检测上下文互不干扰，并在结束时按照优先级确定性合并结果。
• 100ms 硬超时防线：若遭遇超大畸形请求体导致计算耗尽，流水线将根据 budget_exhausted_policy 触发安全兜底，绝不拖垮宿主机。

分析预算与白名单控制

通过 sites[].waf.semantic_policy 可对分析耗时与特殊业务路径进行细粒度调控：

• budget_exhausted_policy：单次请求语法解析预算耗尽时的兜底策略。可选 auto（默认，遵循 web_attack 策略等级）、open（放行可用优先）、observe（仅记录观察）或 closed（挑战/严格拦截）。
• path_allowlist：路径白名单列表，匹配到的 URI 路径将直接跳过语义检测。
• param_allowlist：参数白名单列表，匹配到的特定参数名不执行语法分析。

迁移说明： 规范配置路径为 sites[].waf.semantic_policy.budget_exhausted_policy。旧版本若将该字段放在其他非规范路径，当前版本不会读取，请手动移动到每个站点的 waf.semantic_policy 下。迁移旧枚举时，将 pass 映射为 open，将 block 或 challenge 映射为 closed（当前 closed 在分析无法完成时优先挑战）。留空或设置为 auto 时，实际策略会根据站点 web_attack 等级推导。

在 sites[].waf.performance 中可进一步限制 max_body_bytes（请求体最大分析字节数，默认 8MB）、max_header_bytes 及 proxy_timeout。

出站响应检测（敏感数据防泄露）

sites[].waf.response 支持对后端源站返回的响应体进行出站扫描，防止敏感凭据泄漏：

• 检测范围：支持识别 AWS Access Key、常见账号密码泄露模式及站点自定义敏感模式（注意：站点自定义 sensitive_patterns 将覆盖系统默认规则，默认配置下 PEM 私钥扫描未激活，可在 sensitive_patterns 中按需配置启用）。
• 性能建议：对于大文件下载或视频流业务，建议结合路径规则将响应检测限制在 JSON/HTML 接口范围，并合理设置 max_body_bytes。

关于独立攻击与嵌入长文本攻击的判定逻辑，请参考 独立特征与夹杂特征。

1.7.2 - 自定义正则规则

自定义规则引擎（Custom Rule Engine）在检测流水线中作为 Phase 1 预筛选器 运行（引擎优先级为 250）。它先于 AST 语义分析引擎（优先级 290+）执行，主要用于拦截已知的敏感管理路径探测、扫描器指纹特征以及针对特定业务接口的定制化阻断。自定义规则代表管理员显式强意图规则，不受全局 web_attack: smart 策略置信度门限抑制。一旦命中带有 block 动作的规则，请求将立即短路 403 阻断，避免产生高昂的语法树解析开销。

在 Web 管理控制台中可进入 规则管理 模块进行可视化配置与导入导出，底层对应配置项为 sites[].waf.custom_rules，亦可通过 CLI 命令 cheesewaf rules 或 REST API 进行运维管理。

规则配置示例

custom_rules:
  - id: "block-admin-probe"
    name: "Admin path probe"
    pattern: "(?i)/(wp-admin|phpmyadmin|\\.git)"
    location: "uri"
    action: "block"
    severity: "medium"
    enabled: true
    priority: 180
  - id: "challenge-bot-header"
    name: "Challenge suspicious scraper header"
    pattern: "(?i)(headlesschrome|phantomjs)"
    location: "header"
    action: "challenge"
    severity: "high"
    enabled: true
    priority: 200

字段属性与合法枚举

确定性意图与免策略过滤（Deterministic Enforcement）

自定义规则代表管理员的确定性处置意志，而非引擎的概率性弱信号。在数据平面两阶段流水线中：

• 动作直接兑现：当请求命中自定义规则时，系统无条件立即执行所配置的处置动作（block 阻断、challenge 挑战、log 仅记录）。
• 免除门槛过滤：该动作直接生效，不受 protection_policy.web_attack 策略（如最低严重度门槛、模型置信度要求或聚合风险分阈值）的拦截过滤约束，确保管理员配置的规则所见即所行。

安全校验与约束规范

为防止恶意或低效规则对数据平面造成性能衰竭，CheeseWAF 引擎在加载自定义规则时实施以下严格校验：

• 容量配额限制：单站点最多配置 256 条自定义规则；单次导入文档总大小不得超过 1MB；单站点所有规则正则字符串总长度不得超过 256KB。导入 YAML 文档必须显式包含 custom_rules 根节点，严禁空缺文档。
• 复杂度与抗 ReDoS 保证：底层依赖 Go 标准库 regexp（RE2 保证线性时间复杂度，根除灾难性回溯 ReDoS 隐患）。编译后程序指令数超过 4096 的复杂正则将被拒绝。
• 重复性校验：系统强制要求单站点内不得存在重复的规则 ID；同时严格禁止存在相同匹配位置与相同正则的规则（即重复的 location + pattern）。
• 导出文件名安全净化：在导出规则包（API GET /api/rules/export）时，系统对目标文件名强制执行字符白名单清洗（仅允许 [A-Za-z0-9._-]），彻底杜绝 Content-Disposition 响应头注入与路径穿越风险。

批量导入、导出与模板生成

从最新版本开始，CheeseWAF 原生支持通过命令行和 Web 控制台以 YAML 或 JSON 格式全量导入或导出站点规则：

1. 命令行管理（CLI）

# 生成标准自定义规则 YAML 模板
cheesewaf rules example --format yaml --file template.yaml

# 验证并全量替换指定站点的自定义规则（自动触发平滑热载）
cheesewaf rules import --site site-prod-01 --file new-rules.yaml

# 导出指定站点的自定义规则为 JSON
cheesewaf rules export --site site-prod-01 --format json --file rules-backup.json

2. Web 控制台交互

在 Web 管理控制台的 规则管理 页面中，点击右上角「导入/导出」按钮：

• 支持拖拽或选择本地 .yaml / .json 文件上传。
• 支持实时校验规则语法并在提交前预览变更差异。
• 支持一键导出当前站点的全量规则备份。

编写与运维最佳实践

• 特征精准收敛：自定义规则适用于高频已知的路径探测（如后台管理路径、漏洞探测扫描器特征 Header）。复杂的跨站脚本（XSS）与 SQL 注入注入语义，建议直接交给后置的 AST 语义分析引擎处理。
• 合理利用短路阻断：将确定的恶意特征以较小的 priority 数值排在靠前位置，利用短路机制直接丢弃攻击请求，从而降低整体 CPU 计算开销。

1.7.3 - IP、地理位置与客户端指纹

CheeseWAF 在请求接入的最外层提供了网络层与客户端维度的快速访问控制能力。在 Web 控制台中进入 IP 管理 模块，或通过配置文件中的 protection.ip 进行设置。

静态名单与基础配置

protection:
  ip:
    whitelist: ["127.0.0.1", "::1"]
    blacklist: []
    access_rules: []
    reputation_overrides: {}
    tags: {}
    threat_intel: []
    geoip:
      enabled: false
      database: "./data/GeoLite2-Country.mmdb"
      blocked_countries: []

• IP 白名单（whitelist）：命中白名单的客户端将跳过 IP 拦截、GeoIP 限制、威胁情报、Bot 挑战与全局速率限制（注：WAF 语义检测流水线仍会执行，以保障业务内容安全）。
• IP 黑名单（blacklist）：命中黑名单的请求将被当场拒绝并返回拦截页，不会进一步消耗语义引擎分析算力。

GeoIP 地理位置封禁

支持基于 MaxMind MMDB 格式的离线 IP 地理数据库实现国家与地区级流量阻断：

1. 将 geoip.enabled 设置为 true。
2. 将 geoip.database 指向有效的 Country MMDB 文件路径（如 ./data/GeoLite2-Country.mmdb）。
3. 在 blocked_countries 列表中填入需要封禁的 ISO 3166-1 alpha-2 两位国家代码（如 ["US", "RU"]）。

威胁情报源集成

支持导入第三方威胁情报 IP 库，并在控制台中支持情报源的自动化定时同步、手动更新与连通性测试。通过 REST API 端点 POST /api/ip/threat-intel/lookup 可查询特定 IP 的情报命中详情与置信度评分。

客户端软指纹与前置代理穿透

• 客户端软指纹：数据平面基于客户端 User-Agent 与 Accept-Language 特征计算轻量级软指纹（sha256 前 8 字节摘要）。ALAP 异步分析在识别高危威胁后，支持将恶意指纹沉淀为封禁规则，作为辅助防御维度。
• 前置代理真实 IP 获取：若 CheeseWAF 部署于 CDN、云负载均衡器或 Nginx 之后，必须在站点配置中声明 sites[].waf.access_control.trusted_cidrs 或 trusted_proxy_providers，以便正确从 X-Forwarded-For 等头部提取真实的客户端源 IP。

1.7.4 - Bot 挑战与人机验证码

现代网络中的复杂请求中，往往可能伴随着AI爬虫、撞库攻击及自动化扫描工具等恶意流量，CheeseWAF 提供了多层次的人机识别与流量挑战机制。可通过 Web 控制台的 Bot 挑战 与 验证码实验室 进行可视化调试，或通过 protection.bot 与 console.login.captcha 进行配置。

业务流量挑战配置

protection:
  bot:
    enabled: false
    js_challenge: true
    captcha: true
    captcha_type: "slider"
    cookie_name: "cheesewaf_js_clearance"
    path_prefixes: ["/login", "/register", "/api/order"]
    exempt_path_prefixes: ["/health", "/static"]
    suspicious_user_agents: ["curl", "sqlmap", "nuclei"]

验证码类型与交互形式

• 工作量证明（PoW / Altcha）：客户端后台在浏览器中执行哈希碰撞计算并通过请求头 X-CheeseWAF-Altcha 提交结果，对合法用户完全无感且大幅增加攻击者并发成本。
• 滑动拼图（Slider）：包含几何轨迹分析与最短拖动时间校验（由 slider_captcha_* 参数定义），有效防御机械脚本。
• 图形验证码（Image）：支持自定义字符长度、图片尺寸及语音辅助验证次数限制。
• 实验性行为验证：包括轨迹绘制、刮刮卡与图标点选等实验室题型，建议在控制台 验证码实验室 中验证业务适配性后再推向生产。

通过 /api/captcha/assets 端点支持上传企业定制背景图与图标素材。

管理端登录防护

配置项 console.login.captcha 专用于保护 Web 管理控制台登录入口（与数据平面业务隔离），支持滑块验证码与二次 PoW 校验。

源码模板默认开启管理端登录滑块验证码（console.login.captcha.enabled: true）。因此初始化完成后首次登录时，除用户名和密码外还必须完成浏览器中的人机验证。测试环境如需关闭，可在运行时配置副本中设置 console.login.captcha.enabled: false 并重启；生产环境不建议为了绕过验收而关闭该保护。

此外，可启用 console.login.security_entry 为管理登录配置隐藏的混淆路径与前置 Cookie 密钥，防止管理端被公网自动化探测。

排队室机制（Waiting Room）

通过配置 waiting_room: true 并设定 waiting_room_max_active 活跃用户上限，可在突发秒杀或流量激增时将超出承载能力的客户端优雅调度至排队等待页面。排队室只有在全局 protection.policy.bot_cc 未设为 off 且其 action 为 challenge 时才会生效；仅打开站点级排队室开关并不足够。详见 流量限流。

1.7.5 - 流量限流

CheeseWAF 在数据平面内置了高性能的分片滑动窗口计数器限流算法（Sharded Sliding Window Counter），用于平抑瞬时流量高峰并防范 CC 攻击。配置位于 protection.ratelimit，支持通过 REST API PUT /api/protection/ratelimit 进行热更新。

基础配置示例

protection:
  ratelimit:
    enabled: true
    default:
      requests: 100
      window: 60s
      burst: 20

超额处置策略

当客户端的请求速率超出设定配额时，系统支持以下处置动作：

1. 直接返回 429 拦截页：向客户端响应 HTTP 429 Too Many Requests 状态码及定制的拦截提示。
2. 调度至排队室：若同时启用了 排队室机制 且全局 protection.policy.bot_cc 策略未关闭并映射为 challenge，超出限流配额的客户端将被引导至排队等待页面。

建议在上线初期采用较宽松的配额阈值，在观察 1～2 周的正常业务流量基线后，再逐步收紧 requests 与 burst 参数。

1.7.6 - 访问控制列表（ACL）

访问控制列表（ACL）位于流量处理流水线的前端，用于以极低的计算开销快速拦截已知无用的调试路由、探测路径或强制校验指定请求头。配置位于 protection.acl，支持通过 REST API PUT /api/protection/acl 进行热更新。

配置示例

protection:
  acl:
    enabled: true
    rules:
      - id: "deny-debug"
        name: "Deny debug endpoints"
        method: ""
        path_prefix: "/debug"
        header: ""
        header_value: ""
        action: "block"
        severity: "high"
        enabled: true

匹配字段说明

1.7.7 - 拦截响应页与 HTML 安全清洗

当客户端请求被 IP 黑名单、ACL 访问控制、Bot 挑战或 AST 语义引擎阻断时，CheeseWAF 将向客户端返回结构化的拦截响应页面。配置位于 block_page，可在 Web 控制台的 拦截页 模块进行可视化预览、模板切换与源码定制。

基础配置示例

block_page:
  template_id: "minimal"
  custom_enabled: false
  custom_html: ""

模板管理与实时预览

• 内置现代模板：通过 API GET /api/block-pages/templates 可查询系统预设的现代拦截模板。
• 沙箱安全预览：在控制台中可调用 POST /api/block-pages/preview 在沙箱窗口中实时渲染拦截效果，确认无误后再执行全局发布。
• 自定义 HTML 替换：支持调用 POST /api/block-pages/upload 上传企业品牌定制的 HTML 源码，或通过 DELETE /api/block-pages/custom 清除并恢复默认模板。

自定义 HTML 安全清洗规范（SanitizeBlockPageHTML）

为了防止管理员误上传或遭受供应链投毒导致自定义拦截页引入存储型 XSS（Stored XSS）与恶意跳转风险，CheeseWAF 在保存与渲染自定义 HTML 时，强制经过内置的 SanitizeBlockPageHTML 净化引擎处理：

1. 标签与结构白名单

仅允许安全的语义排版与布局标签：

• 容器与结构：html、head、body、title、main、section、header、footer、div、span
• 排版与文本：h1~h6、p、strong、em、b、i、small、pre、code、br、hr
• 列表与表格：ul、ol、li、table、thead、tbody、tfoot、tr、th、td
• 媒体与链接：a、img、style、meta

2. 主动脚本与事件剥离

• 杜绝内联脚本：所有 <script> 标签与注释节点会被完全剔除。
• 剥离 DOM 事件处理器：所有以 on 开头的属性（如 onclick、onload、onerror 等）一律强制清除。
• 禁用表单劫持：严格过滤 formaction、action 与 method 属性，防止伪造表单收集受害者凭据。
• 防恶意重定向：<meta> 标签仅允许安全的 charset 属性，严格过滤 http-equiv="refresh" 等强制跳转指令。

3. CSS 样式净化与外部引用拦截

• <style> 标签及内联 style 属性中，严格过滤 @import 外部样式加载。
• 自动屏蔽包含 javascript:、vbscript:、expression(、behavior: 及 -moz-binding 等危险 CSS 表达式。

4. URL 协议安全限制

• 对于 href 与 src 属性，仅允许 http、https、mailto、tel 协议。
• 对于 <img> 标签，额外允许安全的 Base64 图片数据（data:image/*;base64,...），严禁非图片类型的数据 URI。

请求追踪与安全规范

• 全局追踪编号（Trace ID）：拦截页面中会自动嵌入唯一的请求追踪标识符。终端用户遇到误报反馈时，运维人员可直接在 监控与日志 中根据该编号精准定位原始请求上下文与命中规则链。
• 敏感信息保护：在编写自定义 HTML 拦截模板时，请勿泄露真实源站名称、内网 IP 地址或内部技术栈拓扑等敏感信息。

1.8 - API 接口安全

随着前后端分离与微服务架构的普及，API 接口已成为主要的攻击暴露面。CheeseWAF 的 API 安全模块提供接口自动发现、输入 Schema 强校验、JWT 身份认证及路由级精准限流能力。

在 Web 管理控制台中可进入 API 安全 模块进行可视化配置，底层对应配置文件中的 apisec 块。

1. 自动 API 资产发现

启用 apisec.discovery.enabled: true 后，系统会在流量转发过程中根据 window（时间窗口）与 sample_limit（采样上限）自动对入站请求进行路径聚类，绘制 API 资产拓扑：

• 静态路径过滤：配置 ignore_prefixes 可自动跳过静态文件路径（如 /static、*.css）。
• 资产查询接口：调用 GET /api/apisec/endpoints 获取当前已识别的 API 接口清单与请求统计。
• 结构测试：调用 POST /api/apisec/validate 可对单条测试请求进行 Schema 契约校验。

2. 请求 Schema 校验

Schema 校验模块用于强制校验入站请求的结构完整性，防范参数注入与未预期字段传递：

apisec:
  validation:
    enabled: true
    schemas:
      - id: "api-search"
        method: "GET"
        path_pattern: "^/api/search$"
        required_params: ["q"]
        required_headers: []
        max_body_bytes: 0
        enabled: true

支持校验请求方法、路径正则、必填 Query/Body 参数、必填 HTTP 请求头及允许的最大请求体长度（max_body_bytes）。

3. JWT 与 JWKS 身份认证

通过 apisec.auth 可在前置代理层实现无状态的 JWT 令牌鉴权校验：

• 验证维度：支持校验 Token 签名有效性、签发方（iss）、受众（aud）、有效时间戳（exp/nbf）及指定的加密算法。
• 密钥来源：支持对称共享密钥、本地 PEM 证书文件、内联 PEM 文本、本地 JWKS 文件或远程 jwks_url。
• 自动缓存与刷新：配置远程 JWKS 时，系统将公钥集缓存于 jwks_cache_file，并按 jwks_refresh_interval 周期自动刷新。

4. 路由级精准限流

与 数据平面全局分片滑动窗口计数器限流 不同，API 接口限流专门针对已识别的具体业务路由进行配额控制（例如高频敏感的登录与发送验证码接口）：

apisec:
  rate_limits:
    - id: "login-api"
      method: "POST"
      path_pattern: "^/api/auth/login$"
      requests: 10
      window: 1m
      enabled: true

5. RBAC 权限矩阵定义

apisec.permissions 用于定义管理平面各角色的权限范围：

apisec:
  permissions:
    admin: ["*"]
    readonly: ["read:*", "read:cluster"]

关于具体权限标识符（如 read:sites、write:protection、manage:api_tokens）与 REST API 端点的对应关系，请参考 REST API 接口参考。

1.9 - 边缘优化：响应头、静态缓存与内容压缩

CheeseWAF 在反向代理链路上提供了边缘优化能力，支持自定义响应头注入与剥离、静态内容缓存加速以及动态内容压缩传输。

在 Web 管理控制台中进入 边缘优化 模块，底层配置对应 edge 块，支持通过 REST API GET/PUT /api/edge 进行热配置。

1. 响应头注入与剥离规则

edge:
  headers:
    enabled: true
    rules:
      - id: "set-edge-marker"
        operation: "set"
        header: "X-CheeseWAF"
        value: "edge"
        enabled: true
      - id: "remove-origin-leak"
        operation: "delete"
        header: "X-Origin-Secret"
        enabled: true

• operation: "set"：向客户端响应中注入自定义响应头（如安全标识、Trace ID 或跨域头）。
• operation: "delete"：在响应返回给客户端前，安全剥离源站返回的内部敏感响应头（如 X-Origin-Secret、Server 内部版本等），防止技术栈信息泄露。

2. 静态内容缓存策略

edge:
  cache:
    enabled: true
    mode: "public"
    ttl: 5m
    status_codes: [200, 304]
    path_prefixes: ["/assets/", "/static/"]
    max_body_bytes: 2097152

• 路径前缀过滤：通过 path_prefixes 限制仅缓存确定为公开静态资源的路径（如 /assets/、/static/），严禁对涉及用户会话或动态鉴权的 HTML/API 接口开启全局缓存。
• 缓存控制：支持限定缓存的 HTTP 状态码（如 200 与 304）、缓存有效期（ttl）及允许缓存的最大单体体积（max_body_bytes）。

3. Brotli 与 Gzip 压缩

edge:
  compression:
    enabled: true
    algorithms: ["br", "gzip"]
    level: 5
    min_bytes: 1024

• 多算法支持：同时支持现代高压缩比的 Brotli（br）与通用的 Gzip 算法。
• 触发阈值：通过 min_bytes 设定触发压缩的最小响应体积（如 1024 字节），避免对极短文本压缩反而增加开销。
• 内容类型：预设规则支持覆盖 text/*、application/json、application/javascript、application/xml 及 image/svg+xml。

1.10 - TLS 与证书管理

CheeseWAF 提供了完善的 TLS/HTTPS 安全加密支持，涵盖管理平面的访问加固以及业务数据平面的证书挂载、自动续期与 HTTP/3 协议支持。

在 Web 管理控制台中进入 SSL 证书 模块，底层对应配置文件中的 server.admin_tls 与 tls 块。

1. 管理平面 TLS 配置

server:
  admin_tls:
    enabled: false
    cert_file: "./data/certs/admin.crt"
    key_file: "./data/certs/admin.key"
    self_signed: true

• 容器环境默认行为：Docker 部署环境下默认启用管理端 TLS，并自动生成自签名证书。
• 生产安全要求：若管理平面需要对外部公网开放，建议替换为权威机构签发的正式证书，避免使用浏览器自签名警告证书。

2. 业务站点 TLS 与 HTTP/3 配置

tls:
  auto_cert: false
  cert_file: "./data/certs/site.crt"
  key_file: "./data/certs/site.key"
  min_version: "1.3"
  hsts: true

• 数据平面监听：配置 server.listen_tls 才会启用 HTTPS 监听；该字段没有默认值，未显式设置时保持关闭。将 server.http3.enabled: true 才会启用 HTTP/3；可显式设置 server.listen_http3，否则会回退到 TLS 监听地址（两者都未设置时使用 :443）。
• TLS 版本约束：支持通过 min_version 强制限制最低加密协议版本（如 1.2 或 1.3）。
• HSTS 响应头：开启 hsts: true 将在出站响应中自动注入 Strict-Transport-Security 响应头。
• HTTP/3 (QUIC) 支持：启用 server.http3.enabled: true 可开启基于 UDP 的 HTTP/3 协议支持（需前置已开启 TLS 监听）。

3. ACME 自动化证书签发与续期

CheeseWAF 内置了对 Let’s Encrypt 等 ACME 协议证书颁发机构的支持：

1. 查询 DNS 提供商：调用 GET /api/acme/providers 获取当前配置驱动已启用的 DNS API 插件列表。
2. 发起证书签发：调用 POST /api/sites/{id}/acme/issue 为指定站点申请证书，系统将自动完成 DNS 挑战验证与证书绑定。
3. 安全存储：ACME 账户私钥与申请的证书持久化存储在运行时数据目录下，请勿提交至 Git 版本控制系统。

1.11 - ALAP 异步审查与自学习机制

ALAP（AI Large-Language-Model Auto Pilot）是 CheeseWAF 的智能旁路分析大脑。它通过与数据平面完全解耦的异步队列机制，将大语言模型的泛化语义理解能力引入威胁检测流程，同时保障核心转发链路的零延迟开销。

在 Web 管理控制台中对应 AI 配置 与 威胁审查 模块，底层配置块为 ai。

1. 异步审查队列与并发索赔机制

在数据平面向客户端完成响应交付后，命中特定防护策略的边界样本与夹杂特征请求会被推入后台异步审查队列：

• 模型适配层：后台 Worker 会根据 ai.provider 适配 OpenAI Chat Completions 或 Anthropic Messages 协议格式发起外部推理请求。
• 异步安全原则：始终保持配置中 ai.async: true，数据平面不产生任何针对模型返回的同步阻塞等待。
• 并发索赔与队列保护（Decision Claims）：多管理员协作时，底层存储引擎通过原子索赔机制（review_decisions 锁）锁定待审样本，防止多人并发重复判定，并设定最大保留周期自动清理陈旧样本。

2. 威胁研判与处置流程

安全运维人员可通过控制台或 REST API 审查分析结果：

• 查询待审队列：调用 GET /api/review 获取待研判样本列表与模型评分。
• 人工决策提交：调用 POST /api/review/{id}/decide 记录处置决定（确认为攻击、误报放行或沉淀为防护规则）。
• 严格模式约束：在防护等级 5 下已被数据平面当场拦截的样本，由于请求已物理终止，无法在事后逆向变更为放行状态。操作者仍可提交独立的人工研判决定（载荷、URI、IP 或指纹）来创建所选规则。

3. 自动化规则采纳（Auto-Agree 与 Fail-Closed）

当开启站点级 sites[].waf.semantic_policy.auto_agree: true 时，系统会将模型判定为高危（high）或严重（critical）的高置信度样本自动沉淀为该站点的自定义载荷规则。自动采纳本身不会创建全局 IP 黑名单或客户端软指纹封禁；这些仍需操作者单独明确执行。

4. AI 运维助手与工具审批流防篡改

CheeseWAF 提供了基于大模型的智能交互助手（接口 POST /api/ai/assistant，支持 Server-Sent Events 流式响应）：

• 操作者与状态强绑定（Actor & Preview Binding）：当助手生成修改网络监听、删除站点或重载规则等高风险工具调用时，必须通过 /api/ai/tools/approvals 提交人工审批确认。审批令牌由系统在内存中与当前经过身份认证的操作者（Actor）、工具预览指纹及状态进行不可篡改的加密绑定，从根源上杜绝审批回放与越权提权。
• 权限角色隔离：
  • use:ai：仅允许发起分析与查询对话。
  • write:ai：允许修改 AI 配置并触发自学习任务。
  • approve:ai：具备批准高危工具调用的核心权限。

5. 定时自学习分析（Self-Learning）

系统内置了自动化威胁自学习任务调度，配置参数如下：

ai:
  self_learning:
    enabled: false
    auto_apply: false
    dry_run: true
    interval: 24h
    at: "03:30"
    min_confidence: 0.995
    min_events: 5
    max_events: 200
    max_rules_per_run: 3
    action: "block"

• 参数约束：
  • min_confidence：自动沉淀规则的最低模型置信度阈值（默认 0.995）。
  • min_events / max_events：聚类分析所需的最少与最多关联攻击事件样本数。
  • max_rules_per_run：单次自学习运行允许生成的最大规则配额（默认 3 条），防止规则库膨胀。
  • dry_run：演练模式开关，开启时仅生成分析报告而不实际应用规则。
• 手动触发：调用 POST /api/ai/self-learning/run 可立即触发一轮针对近期访问日志的深度关联聚类分析。

1.12 - 插件体系与 CRP 规范

CheeseWAF 用 CRP (CheeseWAF Resources Package) 定义签名资源包格式，并提供本地离线校验与暂存命令。发布政策与开发者规范由 CheeseSec_Plugin 和 CheeseSec_Plugin_Docs 维护。

CRP v1 归档结构规范

当前 CheeseWAF CRP v1 解析器要求资源包必须为标准 ZIP 归档，且内部必须且仅允许包含以下三类条目，包含任何多余文件或未知目录均会被硬阻断（Hard Reject）：

my-plugin-v1.0.0.crp (ZIP 归档)
├── manifest.json              # 核心元数据清单
├── artifact/                  # 单一有效载荷文件
│   └── payload.bin            # 插件实体产物
└── signatures/
    └── manifest.json          # 离线 Ed25519 签名集合

Manifest 元数据清单字段

manifest.json 采用严格白名单校验，拒绝未知字段。核心字段包括：

签名验证与离线准入机制

CRP 资源包采用离线多方阈值签名（Ed25519）：

• 信任根与来源注册：准入引擎依据 policy/trust-roots.json 与 policy/source-registry.json 校验公钥指纹与签名有效期，不向公网发起证书吊销列表（CRL）或 OCSP 请求。
• 签名阈值判定：根据 policy/trust-levels.json 要求官方包具备法定阈值签名（如 2-of-3 密钥多签）。
• 零网络准入：在纯离线隔离环境中，只要信任根配置就绪，WAF 即可完成全套完整性与合法性校验。

命令行运维与本地操作

CheeseWAF 命令行工具提供了原子化的离线检验与安全暂存命令：

1. 离线验签 (crp verify)

校验本地 .crp 资源包的格式、哈希一致性及签名有效性（不安装、不执行、不联网）：

cheesewaf crp verify \
  --package ./plugin.crp \
  --trust-roots ./trust-roots.json \
  --sources ./sources.json \
  --now 2026-09-08T12:00:00Z

2. 离线暂存 (crp stage)

将通过校验的合规产物保存至本地受保护的内容寻址暂存槽位中（权限收紧为仅属主可读写，不自动激活）：

cheesewaf crp stage \
  --package ./plugin.crp \
  --trust-roots ./trust-roots.json \
  --sources ./sources.json \
  --runtime-dir /var/lib/cheesewaf/crp-runtime \
  --now 2026-09-08T12:00:00Z

3. 显式临时出站探测 (temporary-online probe)

针对必须进行远端联调的受限场景，CheeseWAF 提供唯一挂载的临时 HTTPS 探测通道。该命令要求管理员交互式输入密码，并绑定精确的 TLS 叶证书 Pin，所有网络进出均以结构化审计日志落盘：

cheesewaf temporary-online probe \
  --administrator admin \
  --password-stdin \
  --plugin-id my-plugin \
  --plugin-version 1.0.0 \
  --host updates.cheesesec.com \
  --leaf-pin sha256:abcd... \
  --ttl 60s

官方发布渠道与生态端点

• 插件目录服务：https://store.cheesesec.com (只读元数据拉取)
• OTA 索引端点：https://ota.cheesesec.com (只读增量版本引索)
• 不可变对象存储：https://res.cheesesec.com (基于 SHA-256 内容寻址的只读资源)

扩展分析边界（DuckDB）

DuckDB 作为可选的日志分析扩展，采用异步一次性任务（One-shot Job）模式运行，而非请求拦截热路径上的常驻进程。该作业仅以只读方式处理脱敏后的 Parquet 审计快照，并生成标准结构化分析记录（analysis-record/v1），确保分析工作不影响 WAF 核心转发性能与系统稳定性。

1.13 - 监控、日志与攻击态势大屏

CheeseWAF 提供了全链路的可观测性支持，包括结构化访问日志、Prometheus 标准指标输出、多渠道告警推送及可视化攻击态势大屏。

在 Web 管理控制台中对应 仪表盘、日志检索、监控告警 与 攻击态势大屏 模块，底层配置项对应 logging 与 monitor。

1. 结构化访问日志

logging:
  level: "info"
  format: "json"
  output:
    type: "file"
    file:
      path: "./logs/access.log"
      max_size: "100MB"
      max_backups: 10

• 日志轮转与切割：支持按文件大小（max_size）与保留备份数量（max_backups）自动执行安全轮转。
• Trace ID 全链路定位：每条日志均包含全局唯一的 traceId。在控制台访问 /logs/{traceId} 可直达该请求的完整命中断言详情。
• 日志支持包一键导出：可直接在终端执行 cheesewaf logs pack 一键生成包含所有运行日志的 ZIP 支持包。
• 日志外发：支持将日志异步外发至 ClickHouse、PostgreSQL、VictoriaLogs 或 Elasticsearch，详见 存储与调度管理。

2. Prometheus 指标与 Remote Write

monitor:
  prometheus:
    enabled: true
    path: "/metrics"
    public: false
  remote_write:
    enabled: false
    endpoint: "https://prometheus-push.internal/api/v1/write"
    interval: 1m
    timeout: 10s

• 指标采集端点：当 public: false 时，需携带管理员权限令牌访问 /api/metrics 抓取指标；若设为 public: true，端点直接挂载于路由根路径。
• Prometheus Remote Write（Protobuf 支持）：支持将 WAF 运行指标通过标准的 Prometheus Remote Write 协议（Protobuf 编码）定时主动推送到统一监控中心。

3. 告警规则与通知渠道

系统支持配置拦截率突增（high-block-rate）与磁盘空间预警（disk-usage）等规则：

• 通知渠道（Notifiers）：在 monitor.notifiers 中可配置标准 Webhook 通知器（钉钉、企业微信、飞书等企业即时通讯通过配置其自定义机器人 Webhook URL 即可接入）。
• 站内消息中心：所有告警事件同时写入站内通知系统，可通过 /api/notifications 端点拉取。

4. 实时攻击态势大屏（100% 纯离线与合规支持）

访问控制台的 /attack-map 或全屏模式 /attack-map/screen，可实时渲染全球威胁攻击来源、拦截频次与攻击类型分布。

最新版本对大屏进行了全面的离线化与合规重构：

• 规范国界线与十段线：内置规范审图标准的中国国界线与完整的南海十段线地理矢量数据。
• 授权高德世界边界：采用合规授权的高德全球国家与地区多边形边界资产。
• 3D 纯离线地球渲染：放弃传统依赖公网 OpenStreetMap（OSM）光栅瓦片图的方案，采用轻量级 3D 离线地球矢量渲染，彻底杜绝外网瓦片加载慢与请求外泄隐患，确保在完全隔离的涉密内网或离线专网环境中 100% 正常显示。

1.14 - 集群高可用与节点协同

在大规模多节点部署场景下，CheeseWAF 提供用于节点 mTLS 身份认证、健康/心跳上报、拓扑状态与编排钩子的集群互联。该互联不是站点策略复制通道。当前可运行路径是单节点 builtin 协调器；选择 etcd 只能记录共享集群要求，当前二进制没有 etcd 后端协调器，因此会 fail-closed，不会从共享部署静默回退到心跳选主。商业化目标是由 native-raft 负责期望状态顺序、epoch fencing 与回滚引用，由 PostgreSQL 保存持久管理真相。在迁移完成前，本页的 etcd 命令只描述 contract，不能据此宣称 native-raft 已交付。

在 Web 管理控制台中可进入 集群管理 模块，或通过命令行 cheesewaf cluster 与 REST API /api/cluster/* 进行管理。

1. 基础配置与模式定义

单机默认配置如下：

deployment:
  mode: "standalone"
cluster:
  enabled: false
  ha_mode: "single-node"
  interconnect:
    listen: "127.0.0.1:9444"
    mtls_required: true

下面的配置描述当前节点互联和准入 contract；它不会让当前二进制直接变成可用于生产的多节点 HA：

1. 将 deployment.mode 设置为 cluster、cluster.enabled 设置为 true，并指定全局统一的 cluster_id。
2. 为每个物理机/虚拟机节点分配唯一的 node_id。
3. 配置 interconnect.advertise_addr 为该节点可被集群内其他节点访问的通信地址。
4. 保持 mtls_required: true，并在各节点配置受信的 ca_file、cert_file 与 key_file 证书文件。

内置共识提供方只支持单节点，并且只保留内存中的配置版本日志。设置 cluster.consensus.provider: etcd 并填写 etcd_endpoints 只能记录共享集群所需的 contract；当前二进制没有 etcd 后端协调器，因此会保持写保护/保护模式，不会把心跳状态冒充为共识。native-raft contract 见商业化架构基线，独立命令的当前启动和 join 限制见独立控制面运行时。这两份文档都不会通过当前配置键启用 native-raft。

脑裂与写保护机制

• cluster.protection.freeze_writes_without_majority：当发生网络分区导致无法形成多数派仲裁时，系统将自动冻结配置写操作，防止数据冲突与脑裂。
• allow_traffic_in_protection_mode：在写保护模式下，数据平面继续为现有业务提供反向代理与安全检测服务。

2. 集群 CLI 命令行运维工具链

CheeseWAF 提供用于集群初始化、令牌/证书操作和心跳检查的 CLI 入口：

1. 主控节点初始化与令牌签发

# 初始化本地单节点集群（互联地址默认只绑定回环）
cheesewaf cluster init

# 签发新的工作节点临时加入令牌（有效期由 --ttl 控制，默认 15m）
cheesewaf cluster token create --ttl 15m

# 查看或吊销现有的加入令牌
cheesewaf cluster token list
export CHEESEWAF_TOKEN_ID='token-id-to-revoke'
cheesewaf cluster token revoke "$CHEESEWAF_TOKEN_ID"

cluster init 初始化节点集群身份与通信配置。接入远程节点前，应将两个地址都改成可路由值（例如使用 --force --advertise-addr 10.0.0.1:9444 --listen 0.0.0.0:9444 重新执行），并配置统一的集群发现与协调后端。

2. 工作节点加入与证书轮换

export CHEESEWAF_CONTROLLER='https://10.0.0.1:9443'
export CHEESEWAF_JOIN_TOKEN='one-time-join-token'
export CHEESEWAF_NODE_ID='node-worker-02'
export CHEESEWAF_ADVERTISE_ADDR='10.0.0.2:9444'
export CHEESEWAF_CONTROLLER_CA='/var/lib/cheesewaf/certs/admin-ca.crt'

# 在工作节点使用一次性令牌与本地 CSR 执行加入
cheesewaf cluster join \
  --controller "$CHEESEWAF_CONTROLLER" \
  --token "$CHEESEWAF_JOIN_TOKEN" \
  --node-id "$CHEESEWAF_NODE_ID" \
  --advertise-addr "$CHEESEWAF_ADVERTISE_ADDR" \
  --ca-file "$CHEESEWAF_CONTROLLER_CA"

export CHEESEWAF_API_TOKEN='management-token-with-write-cluster'

# 请求签发新的节点证书（需已有证书路径；写入后按服务语义 reload/restart）
cheesewaf cluster cert rotate \
  --controller "$CHEESEWAF_CONTROLLER" \
  --ca-file "$CHEESEWAF_CONTROLLER_CA" \
  --api-token-env CHEESEWAF_API_TOKEN
# 检查当前节点的集群健康状态与多数派仲裁
cheesewaf cluster status

--ca-file 用于校验控制器 HTTPS 管理端证书，并不是加入响应返回的集群 CA。若控制器证书链已受系统信任可省略；使用私有 CA 时，应预先准备控制器 CA（例如 admin-ca.crt）。加入命令会在本地生成节点密钥与 CSR，接收集群 CA 和签发证书，并写入配置的数据目录；私钥不会发送给控制器。

证书轮换同样要求节点已有配置的身份/证书路径，并且 API 令牌来源必须三选一（--api-token、--api-token-file 或 --api-token-env）。命令只负责写入替换文件，需按服务的 reload/restart 流程后新证书才会生效。

3. Ansible 批量自动化部署

当前 POST /api/cluster/deploy/ansible 导出器只生成 CheeseWAF 主服务引导包（inventory、变量、playbook、role、配置模板和 README）。它不包含 CWEDP 代理，也不是拿来就能执行的生产包：运行前必须补充经过校验的二进制 URL 和 SHA-256、服务路径；多节点场景还必须填写生成 role 所需的外部 etcd 地址。可选的 deploy/ansible/full.yml 只有在明确设置 provision_only=true、补齐外部控制面预检参数以及 CWEDP 代理 URL 和 SHA-256 时，才能执行只拉取代理的主机交接；这仍不会让 CheeseWAF 的 production 存储变为可运行。插件 CRP 的安装、升级、回滚、签名、晋级及认证分发都不会由 Ansible 执行，这些生命周期操作属于 CWEDP：

• Playbook 导出接口：调用 POST /api/cluster/deploy/ansible，传入目标节点的主机清单、角色（waf / monitor）、SSH 端口与地域标签。响应为 JSON，files 对象将相对文件名（如 inventory.ini、playbook.yml 及角色文件）映射到文本内容；保存后先填写经过校验的二进制变量和 etcd 设置，人工复核命令，再执行 playbook。
• Web 控制台导出：在 Web 管理控制台的 集群管理 模块中，可录入节点拓扑并点击「导出 Ansible 部署包」；下载内容仍需人工补全和复核，不是拿来就能执行的生产包。

4. 集群核心 REST API 参考

单节点部署默认采用 builtin 模式并将状态保存在本地；多节点高可用集群必须配置外部 etcd 端点（etcd_endpoints）以协调分布式状态与选主。

1.15 - 存储与调度管理

CheeseWAF 使用轻量化内置存储，并支持可选的外部日志 Sink。当前管理主存储是 SQLite，外部 Sink 不会替代它。

在 Web 管理控制台中可进入 运维调度 与 系统管理 模块，底层配置项对应 storage、setup.data_dir 与 scheduler。

1. 存储配置分层

setup:
  data_dir: "./data"
storage:
  profile: temporary
  management_postgresql:
    dsn: ""
    timeout: 10s
  sqlite:
    path: "./data/cheesewaf.db"

系统默认采用 storage.profile: temporary 运行。内置 SQLite 表保存用户、管理端 Session、站点、站点规则、审查队列、通知、临时升档截止时间、TOTP 防重放标记与审计记录。运行时配置保存在 YAML 文件中。

storage.profile: production 用于生产持久化存储模式，必须独立配置 storage.management_postgresql.dsn，且不能复用访问日志用的 storage.postgresql.dsn。若未正确配置外部存储，服务启动时将执行安全检查并触发 ErrProductionStorageUnavailable 拒绝启动，防止生产数据被误写入临时文件。

storage.postgresql 用于可选的外部异步访问日志写入，不承担管理状态存储。

配置迁移说明

旧配置若未显式指定 storage.profile，系统默认按 temporary 处理。配置生产模式时，必须确保外部生产存储端点已就绪且可正常连接。

自动化版本迁移（Versioned Schema Migrations）

CheeseWAF 内置了自动事务迁移器。当前支持的 SQLite Schema 版本为 5：

• v1 (Initial Schema)：初始化站点、用户、凭证与审查队列基础表结构。
• v2 (Review Decision Claims)：引入威胁审查处置决策索赔与操作者元数据追踪，防并发重复处置。
• v3 (Legacy Rules to Site Custom Rules)：将早期版本的旧式全局规则表平滑迁移并转换为标准化的站点专属自定义规则结构。
• v4 (Historical Username Repair Audit)：新增只追加的 user_username_repairs 表，供按不可变用户 ID 执行的历史用户名修复命令记录；不会自动改写现有用户名。
• v5 (User Credential Epochs)：为 users 和 admin_sessions 增加 credential_epoch。账号安全信息变化时会递增用户 epoch；Session 只有在 epoch 与当前用户一致时才有效，因此旧 Session 不会在凭据变化后继续使用。

数据库性能与完整性保障

• WAL 模式（Write-Ahead Logging）：数据库连接建立时自动执行 PRAGMA journal_mode = WAL。写入期间读操作可以继续，但写操作仍由单一 SQLite 连接串行执行，并受有界 busy timeout 限制。
• 外键约束（Foreign Keys）：强制开启 PRAGMA foreign_keys = ON，保障多表关联的引用完整性。
• 向前兼容安全锁（ErrSQLiteSchemaTooNew）：当数据库文件曾被更高版本的 CheeseWAF 写入时，低版本二进制将主动拒绝打开并报错退出，防止老程序破坏新版数据库架构。

2. Redis 临时协调

Redis 配置为后续集成预留。当前运行时不会用 Redis 保存 Bot 挑战、会话、租约或重放状态。单独启用 storage.redis 不会改变当前管理主存储。

当前挑战功能使用内存安全状态后端。高可用集群与集中式数据持久化可外接 PostgreSQL 与 native-raft。

3. 外部日志外发与存储 Sink

针对大规模高并发访问日志，CheeseWAF 支持将日志异步外发至外部存储引擎：

4. 定时任务调度器（Scheduler）

内置调度器可以执行日志清理、配置快照和安全日报任务。配置快照不是完整数据库导出，而且源码模板默认关闭该任务：

scheduler:
  enabled: true
  tasks:
    - id: "log-cleanup"
      type: "cleanup"
      every: 24h
      target: "./logs"
      keep: 14
      enabled: true
    - id: "config-backup"
      type: "backup"
      every: 24h
      target: "./data/backups"
      keep: 7
      enabled: false
    - id: "security-daily-report"
      type: "security_report"
      frequency: "daily"
      at: "08:00"
      enabled: false

• 任务管理：调用 GET /api/scheduler/tasks 与 PUT /api/scheduler/tasks 查询和修改调度任务列表。
• 执行历史：调用 GET /api/scheduler/history 查看历史任务执行耗时与执行状态。

5. 数据备份与空间回收

• 备份 API 状态：POST /api/backup/export 和 POST /api/backup/restore 已注册路由，但当前处理器固定返回 HTTP 501（BACKUP_EXPORT_NOT_IMPLEMENTED / BACKUP_RESTORE_NOT_IMPLEMENTED），不能当作可恢复备份流程。正式归档/恢复格式交付前，请使用系统运维与安全加固中的 SQLite 在线备份步骤，或使用调度器的配置快照任务。
• 磁盘回收：回收操作按当前存储模式执行；SQLite VACUUM 仅适用于临时模式。

6. 加密诊断队列

诊断数据严格采用有界本地队列与应用侧信封加密，具备严格的 TTL 与脱敏机制，确保敏感业务数据不出内网。

1.16 - 商业化平台架构

本文档定义 CheeseWAF 商业化平台架构设计，涵盖控制面、数据面、插件安全规范及受限网络运维边界。

数据面和控制面

系统采用控制平面与数据平面分离的架构设计：

• WAF 数据面：负责高并发流量检测、反向代理转发与本地生效策略快照评估，保证业务转发的连续性与低延迟。
• 独立控制面（cheesewaf-control）：负责集群协同、配置管理与期望状态分发，提供本地绑定的健康探测、就绪检查及管理接口。运行与配置细节见独立控制面运行时。
• 状态存储与集群：生产模式支持外接 PostgreSQL 持久化管理数据，结合 native-raft 维护集群拓扑与状态同步，通过 Redis 支撑短期租约与安全辅助缓存；生产配置遵循 fail-closed 原则，保障状态一致性。

插件与 CRP 规范

CRP（CheeseWAF Resources Package）是平台定义的标准化资源扩展包：

• 信任根与签名校验：支持官方 Vendor Root 与企业私有根，采用 Ed25519 阈值签名（如 2-of-3 签名）防篡改。
• 本地校验与暂存：CLI 提供 crp verify 与 crp stage 命令，在显式指定信任根与来源的前提下进行离线解包、摘要校验与受控目录暂存。
• 安全生命周期：支持基于策略快照的安全激活与回滚机制，严格校验扩展包完整性与授权状态。
• 发布与更新：通过只读 HTTPS 索引保障包引索的一致性，遵循本地安全留观与确定性交付原则。

DuckDB 作为面向日志审计的离线分析扩展，采用异步一次性作业模式读取脱敏 Parquet 快照，只输出标准 analysis-record/v1 记录，完全独立于请求热路径运行，不影响 WAF 在线转发性能。

离线模式与临时出站

在物理隔离或内网环境中，离线模式切断管理扩展的所有外部主动出站连接，同时保障数据面至后端源站（Origin）的正常转发：

• 本地 cheesewaf temporary-online probe 提供一次性受限 HTTPS 代理，需管理员二次授权，具备 IP 与 TLS 固定绑定及审计能力。
• 只有经过管理员明确审批的操作方可获得临时网络租约。

诊断与审计

• 诊断数据严格遵循最小化与脱敏原则，避免将敏感业务数据写入诊断日志。
• 高风险运维操作遵循首次明确确认、同一授权窗口内避免重复打扰、环境参数变动重新确认的安全原则。

1.17 - 独立控制面运行时

代码仓库包含独立的 cheesewaf-control 控制面进程。它会打开控制面 PostgreSQL 适配器和 native-raft 运行时，再提供本地状态服务。它不处理 WAF 请求，不托管 Web 控制台，也不替代主 cheesewaf serve 进程。

命令边界

进程只接受命令行参数，不接受位置参数。

cheesewaf-control --help
cheesewaf-control \
  --profile production \
  --cluster-id cluster-a \
  --node-id node-a \
  --data-dir /var/lib/cheesewaf/control \
  --listen 127.0.0.1:9450 \
  --raft-listen 127.0.0.1:9451 \
  --mode join \
  --ca-file /etc/cheesewaf/control/ca.pem \
  --cert-file /etc/cheesewaf/control/node.pem \
  --key-file /etc/cheesewaf/control/node-key.pem \
  --postgres-dsn '<由受保护的密钥来源提供>' \
  --timeout 15s

两个监听地址都会校验为回环地址。当前命令不提供远程管理监听。若要远程部署，需要单独设计 TLS、mTLS、ACL、审计和回滚控制。

--postgres-dsn 是独立的管理状态连接，不能与 storage.postgresql.dsn 混淆。后者仍是 cheesewaf 使用的可选异步访问日志 Sink。回环地址和 Unix Socket 的 PostgreSQL 连接可以使用；远程 PostgreSQL 主机必须启用并校验证书的 TLS。这个进程不会打开 Redis 连接。

CA、节点证书和私钥必须由受保护的配置流程提前生成并放置。没有真实 PostgreSQL、Raft TLS 和一致快照时，这个示例仍会 fail-closed；它不是可以直接成功创建 HA 集群的安装步骤。

启动顺序与 fail-closed 行为

只有完整的生产启动流程成功后，cheesewaf-control 才会绑定 HTTP 监听器：

1. 打开管理 PostgreSQL 适配器。
2. 执行 PostgreSQL 控制面表迁移并检查健康状态。
3. 读取 PostgreSQL 控制状态快照。
4. 打开、准备并检查 native-raft。
5. 读取 native-raft 快照。
6. 比较两份快照，包括 cluster、leader、term、epoch、revision、期望版本、摘要、载荷、冻结状态和 nonce ledger。
7. 校验快照，确认它没有覆盖本机已经保存的 last-known-good 状态。
8. 建立 fencing token，并确认它绑定同一个 cluster、leader、epoch、revision、摘要和 nonce。
9. 再次读取 native-raft。fencing 后如果 leader、term、epoch、revision 或摘要发生变化，启动失败。
10. 安装一致的快照，恢复控制面写入，并报告 ready。

迁移、健康检查、快照比较、校验或 fencing 任一步失败，命令都会返回错误。命令输出 control-plane startup failed closed，并在启动状态服务前退出。未验证的快照不会进入 ready 状态，系统也不会接受 proposal。若上层 supervisor 特意使用运行时提供的冻结诊断模式，可以暴露存活状态和冻结原因；这种模式不会报告 ready，也不会恢复写入。

当 PostgreSQL 没有状态行、native-raft 也没有状态时，两边都会得到空的冻结状态。要进入 ready，仍必须有已提交的 desired state revision、非零 term 和 epoch、已建立的 leader，以及匹配的 fencing nonce。因此，仅设置 --mode bootstrap 不能初始化空的生产集群，也不能凭空生成第一份期望状态。

本地状态接口

状态服务供本机 supervisor 和探针使用。它监听 --listen，该地址会被校验为仅限回环。

状态响应不会包含凭据、PostgreSQL DSN、文件路径或后端原始错误。这个接口只用于本地诊断，不是集群 API。

Bootstrap 与 join 模式

bootstrap 和 join 是 native-raft 的启动模式，不是完整的集群管理流程。

• bootstrap 只有在数据目录没有既有 Raft 状态时，才会调用 native-raft 的一次性 BootstrapCluster。进程仍然需要一致的 PostgreSQL 与 native-raft 快照，以及有效的已提交 fencing，才能进入 ready。
• join 不会调用 BootstrapCluster。全新的 join 节点不会自行成为 leader，也不能把空状态变成集群。当前 CLI 没有 controller 地址、join token 或远程注册参数。
• native-raft 包提供 leader 侧的 Join 操作，用于添加 voter。这个操作是内部运行时 API，不是 HTTP 接口，也不是 cheesewaf-control 子命令。在完整、经过测试的 follower 注册流程发布前，应把 join 视为只读注册模式。

因此，当前独立命令不能创建空集群、自动加入对等节点，也不能宣称已经提供生产级多节点 HA。仓库中的 native-raft 和 PostgreSQL 代码定义了一致性边界，但不会让现有 cheesewaf serve 自动切换到 PostgreSQL 或 native-raft 存储路径。

与主服务的关系

cheesewaf serve 仍是主 WAF 入口。它负责数据平面监听和现有管理平面；当前可运行的管理存储配置仍是 storage.profile: temporary。在主服务中添加管理 PostgreSQL DSN，或设置 storage.profile: production，都不会把它迁移到这个独立进程。主服务仍会等待完整的 PostgreSQL、Coordinator、native-raft、审批、审计和数据面接线完成后，才可能解除 fail-closed。

更大的目标架构见商业化平台架构。本文说明独立命令的可执行边界，应与仓库中的控制面启动契约一起阅读。

1.18 - Web 管理控制台

CheeseWAF 内置了基于 React 构建的单页可视化管理控制台，由 cheesewaf 进程的管理监听器直接托管。完成 系统初始化 后，请访问配置的管理地址。独立部署可按配置使用 HTTP/HTTPS；官方 Docker Compose 将管理端以 HTTPS 绑定在 Docker 宿主机回环地址，因此应在宿主机打开 https://127.0.0.1:9443/（或使用 SSH 隧道），除非明确修改绑定，否则不要使用远程主机地址。

控制台采用基于 Session Cookie 的状态保持与严格的 CSRF 双重防御机制（HTTP 环境自动自适应，HTTPS 下强制启用 Secure 属性），并支持在登录页启用 人机验证码防护。

控制台路由与手册对照表

控制台内置了浅色、深色及多套主题色系，个性化配置仅在浏览器本地生效，不会对数据平面的请求转发造成任何影响。

1.19 - 命令行与 TUI 交互

CheeseWAF 采用单一二进制（BusyBox 模式）设计，通过调用文件名自动识别运行模式：

全局命令行参数

-c, --config string     指定配置文件路径（默认 ./data/config/cheesewaf.yaml）
    --data-dir string   指定运行数据目录（默认 ./data）
    --lang string       界面语言偏好（en 或 zh-CN）

界面多语言匹配优先级为：命令行 --lang 参数 > 环境变量 CHEESEWAF_LANG > 数据目录已保存配置 > 操作系统系统区域设置。

用户名和密码规则

初始化向导、Web 控制台、REST API、CLI、存储层、人类用户 JWT claims 和登录 CAPTCHA receipt 使用同一套用户名规则。用户名长度为 3–32 个 ASCII 字符，必须以 ASCII 字母开头、以 ASCII 字母或数字结尾，只能包含 ASCII 字母、数字、.、_ 和 -。非 ASCII 字符、Unicode 空白字符、控制字符（Cc）和格式/不可见字符（Cf）都会被拒绝。服务端保留原始输入，不会自动去除空格，也不会自动转小写，因此 admin 和 admin 是两个不同的字符串，后者无效。

role 字段同样必须精确匹配 apisec.permissions 中的已配置角色键（通常为 admin 或 readonly）。空值、未知角色、*/: 权限表达式，以及包含首尾或嵌入 Unicode 空白、控制字符（Cc）或格式/不可见字符（Cf）的角色都会被拒绝；服务端不会自动去空格或改大小写。

新密码至少需要 10 个字符，并满足以下 4 类中的至少 3 类：大写字母、小写字母、不重复数字、特殊字符。系统还会拒绝常见密码和简单模式，包括连续数字或键盘序列。密码不能等于用户名，也不能包含用户名。上述命令不会输出密码哈希。

子命令参考列表

核心子命令与参数详解

1. 系统初始化向导（setup）

支持交互式向导与适合脚本自动化的无人值守模式：

# 交互式向导（包含硬件探测、硬件画像评定与密码设置）
cheesewaf setup

# 无人值守自动化初始化
cheesewaf setup --yes \
  --username admin \
  --password-stdin < /path/to/password.txt \
  --profile smart \
  --admin-listen 127.0.0.1:9443 \
  --skip-probe

常用参数包括：

• -y, --yes：跳过所有交互式确认提示直接提交（无人值守时必须同时指定 --password-stdin 以保障初始凭据满足复杂度策略）。
• --username / --password-stdin：初始超级管理员账号与从标准输入读取的强密码。
• --profile：硬件适配画像（可选 smart、low、medium、high、custom，支持官方别名 minimal、balanced、performance）。
• --admin-listen：指定管理平面监听地址（默认 127.0.0.1:9443，向导提交时会自动依据 admin_tls 状态打印 http:// 或 https:// 面板 URL）。
• --skip-probe / --skip-external：跳过 CPU/内存/磁盘自动探测或跳过外部遥测（GeoIP/Prometheus/VictoriaLogs）配置。

--username 必须符合上面的用户名规则。自动化脚本应优先使用 --password-stdin；密码从标准输入读取，不会出现在初始化摘要中。

2. 自定义规则导入与导出（rules）

支持以 YAML 或 JSON 格式全量替换或导出指定站点的 custom_rules，规则导入成功后会自动向本地运行中服务发送信号以触发平滑热重载：

# 生成标准自定义规则 YAML 模板
cheesewaf rules example --format yaml --file rules-template.yaml

# 验证并全量导入自定义规则至指定站点
cheesewaf rules import --site site-demo --file my-rules.yaml

# 导出指定站点的自定义规则为 JSON
cheesewaf rules export --site site-demo --format json --file exported-rules.json

3. 本地用户管理（user）

# 为指定用户重置密码（推荐从标准输入读取，避免密码出现在 shell 历史、环境变量或进程参数中）
cheesewaf user password admin --password-stdin < secret.txt
# 直接使用 --password 安全性较低，密码可能出现在 shell 历史、环境变量或进程参数中
cheesewaf user password admin --password 'replace-with-new-password'

# 自动生成高强度临时密码并禁用 TOTP 2FA（常用于应急恢复）
cheesewaf user password admin --generate --reset-2fa

# 确保管理员账号存在（不存在则自动创建，存在则更新密码）
cheesewaf user ensure-admin admin --password-stdin < secret.txt

# 重命名本地用户名
cheesewaf user rename old_admin new_admin

# 修复历史上包含空格或其他非法字符的用户名
cheesewaf user repair-username USER_ID recovered_admin --reason 'Historical whitespace in imported account'

当前用户名已经符合规则时，应使用 user rename，旧用户名和新用户名都必须通过同一套校验。命令会更新账号并撤销该账号全部未撤销的 Session，但不会写入历史用户名修复审计记录；它不能按用户名选中历史非法账号。只有 repair-username 会把用户名更新、撤销 Session 和写入审计记录放在同一个事务中。两个命令都不会自动去除空格或转小写。

只有历史用户名不符合当前规则时，才能使用 user repair-username。该命令按不可变用户 ID 操作，而不是按用户名查找。目标用户不存在、当前用户名已经合法，或目标用户名已被其他账号占用时，命令都会拒绝执行，也不会合并账号。用户名更新、撤销该用户全部未撤销的管理端 Session 和追加审计记录在同一个 SQLite 事务中提交。用户 ID、密码哈希、角色、TOTP 启用状态和 TOTP 密钥都会保留。审计记录包含当前操作系统用户 ID、填写的原因、旧用户名、新用户名、撤销的 Session 数量和时间。

如需查找不可变用户 ID，请使用 SQLite CLI 的只读模式，并且只选择 ID 和带引号的用户名。将路径替换为配置中的 storage.sqlite.path 或当前数据目录：

DB=/var/lib/cheesewaf/cheesewaf.db
sqlite3 -readonly "$DB" \
  'SELECT id, quote(username) AS username FROM users ORDER BY username;'

quote(username) 会让用户名前后的空格在结果中可见。不要使用 SELECT *，也不要把数据库输出粘贴到工单或日志中。

管理 API Token 的显示备注属于元数据，不是账号用户名，不套用账号用户名规则。不要把 Token 备注当作用户身份。管理 API Token 默认有效期为 90 天，最长可设为 365 天；过期或连续 180 天无活动的 Token 会由单个合并清理 worker 处理，并尝试写入审计和管理员通知。

user 命令用于操作本地管理存储中的用户账号、角色与凭据数据。对于 CRP 插件包，crp verify 提供本地离线验签能力，crp stage 则可将校验通过的本地包写入指定 staged 槽位。

CRP 本地暂存

cheesewaf crp stage \
  --package ./plugin.crp \
  --trust-roots ./trust-roots.json \
  --sources ./sources.json \
  --runtime-dir ./data/crp-runtime \
  --now 2026-09-08T12:00:00Z

该命令必须显式提供信任根、来源注册、运行时目录和确定性的 --now。它会验证归档，并只把本地 staged 元数据和 artifact 写入指定目录；不会晋级包、启动插件、绕过确认要求，也不会访问网络来源。--high-risk 只选择高风险签名阈值，不会自动授予确认。

# 显式执行一次性临时 HTTPS 出站网络探测（要求管理员从标准输入提供密码并绑定 TLS 叶证书 Pin）
cheesewaf temporary-online probe \
  --administrator admin \
  --password-stdin \
  --plugin-id my-plugin \
  --plugin-version 1.0.0 \
  --host updates.cheesesec.com \
  --leaf-pin sha256:0123456789abcdef... \
  --ttl 60s

该探测命令只执行受限的 HEAD/GET 握手，将仅含结构化元数据的只读审计记录写入 <data-dir>/audit/netlease.jsonl，不启动后台常驻下载器，亦不参与主服务数据转发。

4. 集群节点管理（cluster）

# 将当前节点初始化为集群主控节点（该命令仅写入配置，不生成 CA）
cheesewaf cluster init

# 签发新的工作节点加入令牌（有效期默认 15 分钟）
cheesewaf cluster token create --ttl 15m

# 查看或吊销加入令牌
cheesewaf cluster token list
export CHEESEWAF_TOKEN_ID='token-id-to-revoke'
cheesewaf cluster token revoke "$CHEESEWAF_TOKEN_ID"

export CHEESEWAF_CONTROLLER='https://10.0.0.1:9443'
export CHEESEWAF_JOIN_TOKEN='one-time-join-token'
export CHEESEWAF_NODE_ID='node-worker-02'
export CHEESEWAF_ADVERTISE_ADDR='10.0.0.2:9444'
export CHEESEWAF_CONTROLLER_CA='/var/lib/cheesewaf/certs/admin-ca.crt'

# 工作节点使用一次性令牌加入，CLI 会在本地生成密钥与 CSR
cheesewaf cluster join \
  --controller "$CHEESEWAF_CONTROLLER" \
  --token "$CHEESEWAF_JOIN_TOKEN" \
  --node-id "$CHEESEWAF_NODE_ID" \
  --advertise-addr "$CHEESEWAF_ADVERTISE_ADDR" \
  --ca-file "$CHEESEWAF_CONTROLLER_CA" # 亦可使用别名 --ca-cert

export CHEESEWAF_API_TOKEN='management-token-with-write-cluster'

# 请求替换集群 mTLS 文件（需已有本地证书路径；写入后按需 reload/restart）
cheesewaf cluster cert rotate \
  --controller "$CHEESEWAF_CONTROLLER" \
  --ca-file "$CHEESEWAF_CONTROLLER_CA" \
  --api-token-env CHEESEWAF_API_TOKEN

# 查询集群拓扑与仲裁健康状态
cheesewaf cluster status

# 导出集群声明式对象（命令输出 YAML，可重定向保存）
cheesewaf cluster export > cluster-export.yaml

# 启动当前节点的心跳监控循环（目标为 HTTPS/mTLS 集群互联端口）
export CHEESEWAF_CLUSTER_CONTROLLER='https://10.0.0.1:9444'
cheesewaf cluster monitor-node --controller "$CHEESEWAF_CLUSTER_CONTROLLER" --interval 10s

cluster join 与 cert rotate 的 --ca-file 用于校验控制器 9443 HTTPS 管理端，不是加入响应返回的集群 CA。若控制器证书链已受系统信任可省略；私有 CA 场景请预置管理端 CA。加入时 CLI 会在本地生成密钥/CSR，接收集群 CA 与节点证书并写入数据目录。证书轮换要求节点已有配置的证书路径，且令牌来源必须三选一（--api-token、--api-token-file 或 --api-token-env）；写入文件后需按服务流程 reload/restart 才会生效。

cluster monitor-node 通常向 HTTPS :9444 集群互联端点发送心跳，并使用本地配置的集群 CA/证书/私钥。回退使用的环境变量是 CHEESEWAF_CLUSTER_CONTROLLER；自定义 --controller 也必须是 HTTPS 互联地址。--insecure-skip-verify 仅限隔离实验室使用。

5. 日志支持包打包（logs）

# 将当前数据目录下的全部服务日志打包为带时间戳的 ZIP 归档
cheesewaf logs pack

# 指定输出目录与归档文件名
cheesewaf logs pack --dir /tmp --name support-bundle.zip

6. 多语言设置（lang）

# 查询当前生效语言与支持的语言列表
cheesewaf lang show

# 持久化设置 CLI 语言为简体中文或英文
cheesewaf lang set zh-CN
cheesewaf lang set en

常用操作示例

# 指定自定义配置文件与数据目录启动
cheesewaf serve --config /etc/cheesewaf/cheesewaf.yaml --data-dir /var/lib/cheesewaf

# 检查运行状态与 PID 租约
cheesewaf status

# 启动交互式 TUI 终端面板
waf-cli

# 容器探针与网络就绪性诊断
cheesewaf healthcheck

1.20 - RESTful 管理接口

CheeseWAF 的管理 API 由同一进程的管理平面监听器（默认端口 9443）承载，路径统一为 /api；它与承载业务流量的数据平面使用不同监听器。这里的管理平面不是未来独立的商业化控制面服务。

认证与鉴权方式

系统支持两种鉴权模式：

1. Session 会话认证：调用 POST /api/auth/login 完成登录后，客户端携带返回的 Session Cookie 进行后续请求。所有引发状态变更的非幂等请求（POST/PUT/DELETE/PATCH）均须通过 CSRF 中间件防御校验。
2. Bearer 管理令牌：先启用 apisec.management_api.enabled，再调用 POST /api/system/api-tokens（需要具备 manage:api_tokens 权限）创建具有指定范围的 API Token。在 HTTP 请求头中以 Authorization: Bearer <TOKEN> 发起调用。创建响应只返回一次明文；列表/查询接口只返回元数据，不返回密钥。

用户名与角色校验

人类账号端点（POST /api/users、PUT /api/users/{id}）、初始化、登录、存储层、人类用户 JWT claims 和 CAPTCHA receipt 使用同一套精确用户名规则：3–32 个 ASCII 字符，以 ASCII 字母开头、以 ASCII 字母或数字结尾，只允许 ASCII 字母、数字、.、_ 和 -。非 ASCII 字符、Unicode 空白字符、控制字符（Cc）和格式/不可见字符（Cf）都会被拒绝。服务端不会去空格、转小写或以其他方式静默改写输入。

创建或更新用户时，role 必须精确匹配 apisec.permissions 中的已配置角色键（通常为 admin 或 readonly）。空值、未知角色、*/: 权限表达式，以及包含首尾或嵌入 Unicode 空白、控制字符（Cc）或格式/不可见字符（Cf）的角色都会被拒绝。字段不合法时分别返回 USERNAME_INVALID 或 ROLE_INVALID。历史上已经存在的非法用户名不能通过普通 API 更新悄悄修复；请先查询不可变用户 ID，再在本机执行 cheesewaf user repair-username USER_ID NEW_USERNAME --reason '...'。

公开免密端点清单

以下只读、登录或挑战接口无需已有会话或 Bearer 令牌即可访问。若配置 monitor.prometheus.public: true，对应的 Prometheus 路径也会免密开放（路径由部署配置决定）。

引导流程与节点鉴权接口

这些路由虽然不经过常规管理令牌中间件，但并非匿名操作：

• POST /api/setup 与 POST /api/setup/probe 必须在请求头 X-CheeseWAF-Setup-Token 中提供初始化令牌，且仅在系统尚未完成初始化时接受。
• GET /api/setup/draft 必须携带探测阶段下发的初始化会话 Cookie；PATCH /api/setup/draft 同时需要该 Cookie 与初始化令牌。
• POST /api/cluster/join 必须提供一次性加入令牌与节点 CSR；控制器会校验令牌并完成节点注册，并非公开的集群成员接口。
• POST /api/cluster/nodes/{id}/heartbeat 仅接受已注册且未吊销节点的已验证 mTLS 客户端证书（证书身份/序列号必须与注册信息一致）。

首次初始化地址的安全传递

服务启动日志不会打印初始化 Token 或完整初始化地址。日志只显示基础初始化 URL（例如 http://127.0.0.1:9443/setup）、受保护的运行时文件路径（setup.url）和不含秘密的随机回执。

完整 URL 保存在 setup.url 中。文件权限为 0600，有效期为 10 分钟。初始化完成后，Token 会被撤销；过期的 setup.url 文件会被清理。正常安装流程不会向用户提供 ReadURLOnce 命令。

初始化完成前，API 仍要求在 X-CheeseWAF-Setup-Token Header 中提供 Token；初始化完成后，Token 会失效。浏览器从 URL fragment 读取 Token，清除地址栏中的 fragment，并且只通过该 Header 发送。启动前通过 CHEESEWAF_SETUP_TOKEN 提供的 Token 也遵循相同的 API 校验规则，不得写入日志或 Shell 历史。

GET /api/setup/status 只返回是否仍需初始化，不会返回初始化地址或初始化 Token。

RBAC 细粒度权限对照表

后端路由中间件通过权限标识符对 API 调用进行细粒度鉴权：

拥有 admin: ["*"] 权限的角色具备全量接口调用权限。

当前管理 API Token 支持按权限范围授权、备注、可选 TTL/失效时间、吊销、最近使用时间和一次性明文展示。平台默认有效期为 90 天，显式有效期最长 365 天。服务使用单个合并清理 worker：新建 Token 会把清理截止时间推迟 10 分钟，但不会超过本批首次创建时间加 60 分钟；已过期或连续 180 天无活动的 Token 会被删除，提交配置后会尝试写入审计记录并通知管理员。

Web 控制台提供管理员 Session 下的永久 Token 二次确认流程。系统严格遵循最小特权原则，创建永久 Token 需完成强身份核验（如当前密码/TOTP 双因子校验）与风险确认流程，在校验未满足时安全拒绝并返回 API_TOKEN_CONFIRMATION_UNAVAILABLE。

备份路由当前不是可恢复的完整流程：POST /api/backup/export 与 POST /api/backup/restore 会返回 HTTP 501（BACKUP_EXPORT_NOT_IMPLEMENTED / BACKUP_RESTORE_NOT_IMPLEMENTED）。

错误响应规范

API 调用失败时，将返回对应的 HTTP 状态码与标准 JSON 错误响应体：

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request parameter",
    "trace_id": "1a2b3c4d5e6f",
    "event_id": "1a2b3c4d5e6f"
  }
}

在遇到登录验证码校验失败（401/403）时，请先调用 /api/auth/captcha 刷新挑战上下文，再重新提交登录凭据。

1.21 - 配置文件参考

CheeseWAF 在首次启动时会在运行数据目录的 config/ 目录下自动生成 cheesewaf.yaml 主配置文件（默认 ./data/config/cheesewaf.yaml）。预设配置模板可参考源码库中的 configs/cheesewaf.yaml。

configs/cheesewaf.yaml 是源码模板，不是运行时状态文件。初始化、站点管理和控制台保存操作会写入运行时配置；源码构建时请先复制到 ./data/config/cheesewaf.yaml 或其他明确的数据目录，避免把数据库路径、证书、密钥和站点变更写回 Git 工作区中的模板。

顶层配置块索引

超时机制配置

• 接入层超时：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 上限时，数据平面直接向客户端响应 HTTP 413 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 服务管理器）。

1.22 - 系统运维与安全加固

本章介绍 CheeseWAF 在生产环境下的日常运维操作与安全加固规范。在 Web 控制台中对应 用户管理、系统管理 与 检查更新 模块。

CheeseWAF 默认使用 storage.profile: temporary 运行，用户、Session 和管理状态保存在内置 SQLite 中。若显式指定生产模式 storage.profile: production，系统执行严格的环境校验并遵循 fail-closed 原则，在外部生产持久化数据库不可用时抛出 ErrProductionStorageUnavailable。

storage.postgresql 用于集中归档访问日志；storage.redis 端点可用于辅助缓存验证。CLI 提供 cheesewaf crp verify 与 cheesewaf crp stage 用于安全包离线校验与受保护槽位暂存；生产模式下结合策略快照与鉴权环境支持安全激活与回滚。

当前 CWEDP/NetLease 包已经包含 broker-bound HTTP/file transport、一次性租约校验、直接 IP 拨号、TLS/mTLS/NodeID/leaf pin、Range 续传和来源隔离，但尚未挂载到主 serve、节点注册或完整的插件安装/OTA 生命周期。本地 cheesewaf temporary-online probe 是独立的一次性运维工具，不是生产插件出站 API。

1. 用户管理与 CLI 凭据运维

• 统一用户名规则：初始化向导、Web 控制台、REST API、CLI、存储层、人类用户 JWT claims 和登录 CAPTCHA receipt 使用同一套用户名格式。用户名长度为 3–32 个 ASCII 字符，必须以 ASCII 字母开头、以 ASCII 字母或数字结尾，只能包含 ASCII 字母、数字、.、_ 和 -。非 ASCII 字符、Unicode 空白字符、控制字符（Cc）和格式/不可见字符（Cf）都会被拒绝。服务端保留原始输入，不会自动去除空格或转小写，因此 admin 和 admin 是两个不同的字符串，后者无效。
• 角色输入规则：用户 role 必须精确匹配当前 apisec.permissions 中已配置的角色键（通常为 admin 或 readonly）。空角色、未知角色、*/: 权限表达式，以及包含首尾或嵌入 Unicode 空白、控制字符（Cc）或格式/不可见字符（Cf）的角色都会被拒绝。服务端不会自动去空格或改大小写；账号字段不合法时分别返回 USERNAME_INVALID 或 ROLE_INVALID。
• Web 控制台与 REST API：调用 GET/POST /api/users 与 PUT /api/users/{id} 管理账号。Web 用户管理、初始化向导和登录使用同一套校验规则。
• 命令行运维工具（cheesewaf user）：
  BASH

  # 推荐脚本方式：从标准输入读取密码，避免写入 shell 历史或进程列表
  cheesewaf user password admin --password-stdin < secret.txt
  
  # 仅适合一次性人工操作：显式密码（必须三选一）
  read -r -s -p 'New password: ' CHEESEWAF_NEW_PASSWORD; printf '\n'
  cheesewaf user password admin --password "$CHEESEWAF_NEW_PASSWORD"
  
  # 自动生成随机高强度密码并重置/禁用 TOTP 2FA（应急恢复）
  cheesewaf user password admin --generate --reset-2fa
  
  # 确保初始管理员存在并从标准输入注入密码（适合自动化部署脚本）
  cheesewaf user ensure-admin admin --password-stdin < secret.txt
  
  # 重命名本地管理员账号
  cheesewaf user rename old_admin new_admin
  
  # 按不可变用户 ID 修复历史非法用户名
  cheesewaf user repair-username USER_ID recovered_admin --reason 'Historical whitespace in imported account'

• 当前用户名已经符合规则时，应使用 user rename，旧用户名和新用户名都必须通过同一套校验。命令会更新账号并撤销该账号全部未撤销的 Session，但不会写入历史用户名修复审计记录；它不能按用户名选中历史非法账号。只有 repair-username 会把用户名更新、撤销 Session 和写入审计记录放在同一个事务中。
• 只有历史用户名不符合当前规则时，才能使用 user repair-username，例如 admin。该命令必须提供 --reason 和准确的不可变用户 ID。用户不存在、当前用户名已经合法，或目标用户名已被其他账号占用时，命令都会拒绝执行，也不会合并账号。用户名更新、撤销该用户全部未撤销的管理端 Session 和追加审计记录在同一个 SQLite 事务中提交。用户 ID、密码哈希、角色、TOTP 启用状态和 TOTP 密钥都会保留。审计记录包含当前操作系统用户 ID、填写的原因、旧用户名、新用户名、撤销的 Session 数量和时间。两个路径都不会自动去除空格或转小写。
• 请使用拥有 CheeseWAF 数据目录权限的操作系统账号运行修复命令。审计中的操作者来自当前操作系统用户 ID；换用其他账号运行会改变这条证据。
• 密码策略：新密码至少需要 10 个字符，并满足大写字母、小写字母、不重复数字、特殊字符 4 类中的至少 3 类。常见密码和简单模式（包括连续数字、键盘序列）会被拒绝。密码不能等于用户名，也不能包含用户名。优先使用 --password-stdin；直接使用 --password 可能把密码写入 shell 历史或进程列表。
• 最小权限原则：建议为日常审计监控人员创建 readonly 只读角色，避免共享超级管理员账号。
• TOTP 双因素认证（2FA）：支持标准 TOTP 认证。调用 /api/users/{id}/2fa/setup 生成密钥与绑定二维码，并调用 enable、disable 或 recover 进行生命周期管理。
• 管理 API Token 的显示备注属于元数据，不是账号用户名，不套用账号用户名规则。不要把 Token 备注当作人类用户身份。管理 API Token 默认有效期为 90 天，最长 365 天；运行中的服务通过合并清理 worker 删除过期或连续 180 天无活动的 Token，并尝试写入审计和管理员通知。
• Web 控制台支持永久 Token 的二次确认与强核验，创建永久 Token 需完成强身份校验，未满足安全条件时返回 API_TOKEN_CONFIRMATION_UNAVAILABLE。

如需查找用户 ID，请使用 SQLite CLI 的只读模式，并且只选择 ID 和带引号的用户名，不读取密码哈希或 TOTP 密钥：

DB=/var/lib/cheesewaf/cheesewaf.db
sqlite3 -readonly "$DB" \
  'SELECT id, quote(username) AS username FROM users ORDER BY username;'

quote(username) 会让用户名前后的空格在结果中可见。不要使用 SELECT *，也不要把这段输出粘贴到工单或日志中。

2. 备份和迁移 SQLite 管理存储

执行用户名修复或升级二进制前，先根据 storage.sqlite.path 确认当前数据库和父目录。常见默认路径是本地运行时的 ./data/cheesewaf.db，以及 Linux 服务的 /var/lib/cheesewaf/cheesewaf.db。不要把这些命令指向版本库中的 configs/cheesewaf.yaml 模板。

运行中的 SQLite 通常使用 WAL 模式。CheeseWAF 运行时不要只复制主 .db 文件；最新提交可能仍在 -wal 文件中，这样得到的副本可能无法恢复。在线备份可以在服务继续运行时读取一致性快照：

DB=/var/lib/cheesewaf/cheesewaf.db
BACKUP_DIR=/var/backups/cheesewaf
test -f "$DB" || { echo "database not found: $DB" >&2; exit 1; }
install -d -m 700 "$BACKUP_DIR"
df -h "$BACKUP_DIR"
du -h "$DB"
BACKUP="$BACKUP_DIR/cheesewaf-before-maintenance-$(date -u +%Y%m%dT%H%M%SZ).db"
test ! -e "$BACKUP" || { echo "backup path already exists: $BACKUP" >&2; exit 1; }
sqlite3 -readonly "$DB" ".backup '$BACKUP'"
chmod 600 "$BACKUP"
test -s "$BACKUP" || { echo "backup is empty: $BACKUP" >&2; exit 1; }
integrity=$(sqlite3 -readonly "$BACKUP" 'PRAGMA integrity_check;')
test "$integrity" = ok || { echo "backup integrity check failed: $integrity" >&2; exit 1; }
sha256sum "$BACKUP" > "$BACKUP.sha256"
sha256sum -c "$BACKUP.sha256"

完整性检查必须返回 ok，最后的校验和命令必须报告 OK；任一检查失败都应立即停止。请把备份放在受保护的位置，并按保留策略复制到异机。备份包含敏感的管理数据，不能上传到工单或粘贴到聊天中。开始前检查磁盘空间；备份期间关注 WAF 健康状态和磁盘延迟。CheeseWAF 的单一二进制同时提供数据平面和管理平面，停止它可能中断防护和业务流量。

如果无法在线备份，只能通过服务管理器停止确切的 CheeseWAF 写入进程，并确认没有其他 CheeseWAF 进程继续写入，再复制包含相邻 -wal 和 -shm 文件的一致数据库集合。重启服务前，用 PRAGMA integrity_check; 验证副本。不要使用会停止大量无关进程的命令。

当前二进制会按顺序执行 SQLite 迁移，当前 Schema 版本为 5。3 到 4 的迁移会创建只追加的 user_username_repairs 审计表，4 到 5 的迁移会为 users 和 admin_sessions 增加 credential_epoch。账号安全信息变化时会递增用户 epoch，活动 Session 必须匹配当前 epoch。这些迁移不会自动去除空格、转小写、合并或改写现有账号。只支持旧 Schema 的二进制打开新数据库时，会因 newer SQLite schema version 拒绝运行。

如果需要降级，请恢复升级前的备份，并在核对服务路径和数据路径后再启动旧二进制。不要手工修改 PRAGMA user_version。如果用户名修复成功后必须撤销，请在计划维护窗口恢复修复前备份；repair-username 会刻意拒绝把合法用户名改回非法格式。

3. 日志支持包与 CLI 语言管理

• 一键打包服务日志（Support Bundle）：在遇到难以定位的异常时，执行以下命令即可一键将全部运行时日志导出为规范命名的 ZIP 支持包，便于快速交接或提交安全工单：
  BASH

  cheesewaf logs pack --dir /tmp --name cheesewaf-support.zip

• CLI 界面语言配置：
  BASH

  # 查询当前语言与支持列表
  cheesewaf lang show
  
  # 持久化设置默认 CLI 语言（支持 en 与 zh-CN）
  cheesewaf lang set zh-CN

4. NTP 时钟同步与状态校准

JWT 签名校验、TOTP 动态验证码计算以及集群节点共识均强依赖系统时钟的准确性：

• 查询时钟源：调用 GET /api/system/time-sync 查询当前 NTP 时钟源与偏差。
• 强制同步：调用 POST /api/system/time-sync/sync 触发即时时钟对齐。
• 重新优选：调用 POST /api/system/time-sync/reselect 重新探测并选择延迟最低的 NTP 节点。

5. OTA 能力状态

update:
  ota:
    enabled: false
    server: ""
    channel: "stable"
    check_interval: 6h
    auto_update_rules: true
    auto_update_binary: false
    verify_signature: true

• 当前运行边界：这些配置键为 OTA 更新器预留，但当前二进制没有更新 Worker。控制台的「检查更新」页面会报告 NOT_IMPLEMENTED；通过系统 API 开启 OTA 会被 OTA_UPDATES_UNAVAILABLE 拒绝。
• 配置安全：在更新 Worker 交付前，请保持 enabled: false。启用时，配置校验仍会检查服务器地址、通道、间隔和签名设置。
• 未来行为：auto_update_rules、auto_update_binary 和 verify_signature 描述计划中的签名更新策略，不表示当前会下载或安装规则、二进制。

6. 软件供应链安全与发布完整性校验

只使用实际发布版本提供的元数据。运行时不会自动生成或验证发行签名：

• SBOM：如果发行版本提供 CycloneDX 或 SPDX SBOM，请将它与部署记录一起保存，并核对其中的版本和摘要是否与收到的文件一致。
• 容器签名：如果发行版本提供 Cosign 签名，请在部署前针对确切的镜像引用进行验证。
• Windows 签名：如果 Windows 安装包带有 Authenticode 元数据，请在实际安装机器上核对签名者和证书链。
• 校验和：如果发行版本提供校验和文件，请使用 sha256sum -c checksums.txt 或对应平台的工具校验确切文件。

1.23 - 从源码构建与开发指南

本指南适用于参与 CheeseWAF 核心引擎开发、前端定制或需要从源代码独立构建二进制的场景。生产环境部署推荐直接使用官方发布的 预编译发行包。

开发环境工具链要求

• Go 编译器：Go 1.26 或更高版本
• Node.js 运行时：Node.js 24.x 及匹配的 npm 包管理器

源码拉取与编译流程

CheeseWAF 采用单二进制打包架构，编译时会将前端 React 产物嵌入 Go 二进制中：

# 克隆仓库
git clone https://github.com/LaokeQwQ/CheeseWAF.git
cd CheeseWAF

# 1. 编译 Web 控制台前端静态资源，并同步到 Go 嵌入目录
bash scripts/ci/build-web.sh

# 2. 编译 Go 主程序二进制
go build -o bin/cheesewaf ./cmd/cheesewaf

# 3. 使用运行时配置副本启动本地服务，避免污染模板
mkdir -p ./data/config
cp ./configs/cheesewaf.yaml ./data/config/cheesewaf.yaml
./bin/cheesewaf serve --config ./data/config/cheesewaf.yaml --data-dir ./data

自动化测试与质量校验

在提交代码前，请执行以下完整的单元测试、静态检查与攻击语料评测：

# 后端 Go 单元测试与代码静态检查
go test -v ./cmd/... ./internal/...
go vet ./cmd/... ./internal/...

# 前端 TypeScript 类型检查与单元测试
cd web && npm ci --no-audit --no-fund --ignore-scripts && npm run typecheck && npm test && cd ..

# 运行内置攻击语料库压测与 AST 语义分析器评测
go run ./cmd/cheesewaf-corpus --mode analyzer

1.24 - 开源许可与生态仓库

CheeseWAF 项目源代码采用 Apache License 2.0 协议开源分发。

关于 CheeseSec 与 CheeseWAF 的品牌标识、名称及产品 Logo，不属于开源代码授权范畴。如需二次分发或在商业品牌中引用，请参阅 CheeseSec_pages 仓库中的 NOTICE 说明。

生态项目仓库索引

若在使用中发现软件缺陷或有功能建议，欢迎在各项目 Issue Tracker 中反馈。详细的问题反馈渠道、邮件沟通方式及严重安全漏洞报告规范，请参阅 问题反馈与安全报告。

1.25 - 问题反馈与安全报告

CheeseSec 鼓励社区参与和技术反馈。根据问题性质的不同，请选用相应的沟通渠道：

常规交流与缺陷反馈

1. GitHub Issues

对于软件运行缺陷（Bug）、异常报错、功能改进建议或技术文档错漏，推荐直接在对应的 GitHub 项目仓库中提交 Issue：

2. 邮件交流

对于不便通过公开 Issue 讨论的一般性问题、技术交流或部署咨询，可通过电子邮件直接沟通：

• 联系邮箱：[email protected]

严重缺陷与安全漏洞报告

CheeseSec 高度重视软件安全。若在 CheeseWAF 核心系统或其生态组件中发现安全漏洞、防护绕过或严重稳定性缺陷，请遵循负责任的漏洞披露原则（Responsible Disclosure），避免在公开公共渠道（如 GitHub Issues、社交网络或公开群聊）中直接发布漏洞细节。

专有安全邮箱

• 漏洞报告专用邮箱：[email protected]

适用报告范围

包括但不限于以下威胁场景：

• 远程代码执行（RCE）或任意命令执行缺陷
• 管理平面鉴权绕过、权限越权或 JWT/Session 校验失效
• AST 语义检测引擎或核心防护规则的通用绕过（Bypass）手段
• 内存溢出、死锁或非预期资源耗尽引发的高危拒绝服务（DoS）
• 敏感配置、凭据或未脱敏数据的泄露隐患

安全报告建议包含的信息

为协助安全团队快速复核并定位问题，发送报告时建议包含以下要素：

1. 漏洞简述与影响面：漏洞类型、影响的模块或接口，以及评估危害等级。
2. 受影响版本：受影响的 Release 版本号或 Git Commit 哈希。
3. 概念验证（PoC）：清晰、完整的重现步骤，包括请求报文、测试脚本或关键配置。
4. 利用条件与前置要求：触发漏洞所需的前置配置项、权限要求或网络拓扑。
5. 修复建议（可选）：如有可行的缓解规避措施或补丁思路，欢迎一同提供。

响应与处置流程

1. 报告确认：安全团队在收到 [email protected] 来信后，将及时给予确认并建立专门跟踪通道。
2. 复现与定级：技术团队在独立安全环境中验证 PoC，确认威胁影响并确定修复优先级。
3. 补丁发布与披露：完成代码修复并经过充分测试后，团队将发布安全补丁版本及相应安全公告（Security Advisory）。在此之前，请协助保持漏洞信息的保密性。

1.26 - 开发者想说

在严谨、客观且标准化的技术文档之外，我们开辟了这个专属版块，留给项目的创造者与核心开发者，用以记录技术之外的思考、初衷与愿景。

1.26.1 - 开发者想说

“安全不应该是昂贵、封闭或让运维疲惫不堪的黑盒，而应该是一套透明、优雅且让人感到踏实的工程基础设施。”

写在前面的话

如果你正在阅读这篇文档，或许你正准备在自己的服务器上部署 CheeseWAF，或许你是在排查某个棘手的安全问题，又或许你只是一名对 Web 安全与应用架构感兴趣的同行或爱好者。

无论是哪一种，我都由衷地欢迎你。

这里没有冰冷的命令行参数、也没有晦涩的正则表达式语法，我想用自己简朴的话，和你聊聊为什么会有 CheeseWAF，以及在这个过程中我所坚持与思考的一切。

为什么要做 CheeseWAF

在确认立项并动手写下 CheeseWAF 的第一行代码前，我和许多网站运维与安全工程师一样，面对日益复杂的网络请求，在高价的商业 WAF 授权报价与传统开源项目的繁杂规则维护、误报漏报率高的困境中难以抉择。

我们常常陷入两个极端：

• 过度依赖传统正则特征：规则越堆越多，不仅维护成本成倍攀升，稍微遇到多层编码或字符嵌套就会被绕过；
• 盲目将大模型塞进实时路径：为了所谓的“智能化”，在同步反向代理链路中强行等待远程 LLM 返回，把一次简单的 HTTP 交互变成几百毫秒甚至数秒的等待，最终拖垮了整个业务系统。

我们坚信，精准性、低延迟和可维护性是数据平面的生命线，而深度的语义理解应当交给能自己解耦和自我成长学习的异步旁路。 这便是 CheeseWAF 诞生的起点——我们希望打造一款真正商用级、自包含、开箱即用的自托管 WAF，让每一位开发者和运维团队都能掌握自己的应用安全防护权，不受云端和高价商业授权束缚。

我们的设计执念

在 CheeseWAF 的演进历程中，有一些工程原则被我们视作底线：

1. 坚持单一二进制与自包含：把复杂的组件、Web 控制台和安全引擎凝聚在单一可执行文件中，无需先折腾半天数据库、中间件或外部依赖，主项目由 100% Go 语言编写，这使得 CheeseWAF 拥有先天的鲁棒性和极好的可移植性，可以在主流的 Linux、Windows、macOS 平台上直接运行。不仅如此，我们还兼容了龙芯架构（LoongArch），原生支持搭载国产龙芯芯片的设备上正常运行。
2. 请求路径绝不妥协：最快微秒级处理的请求检测管线源于清晰的抽象语法树（AST）语义解析，根据设备性能参数实时调优的检测管线，经过无数次打磨的 GC 调优和硬件加速，只在追求极致的性能与并发。
3. 把选择权交还给操作者：从防护等级（Paranoia Level）的逐级推进，到大模型研判结果的自动采纳，你可以在 AI 自动操作和告警人工审批中自主选择，最终防线的掌控和话语权永远在你手中。

给使用者的一封信

做一款严肃的 Web 应用安全产品并不容易，它需要面对瞬息万变的网络攻击手法、复杂的现代 Web 协议演进，以及现实部署环境中的种种严苛挑战。

CheeseWAF 作为一个初来乍到、涉世未深的个人维护开源项目，仍在不断成长中。如果它在某个深夜帮你挡住了一次突如其来的恶意攻击，帮助你的网站初创团队或小公司减轻了商业化 WAF 授权或云上防护的费用，亦或者只是让你的运维工作变得轻松了一点，觉得用起来还算顺手，那便已是我最大的荣幸。

欢迎有任何想法、批评或者建议的用户们通过 GitHub Issues 或 邮箱（[email protected]） 与我交流。

最后，由衷感谢您对 CheeseWAF 的认可和信赖，也致敬每一个热爱开源与安全技术的你。