UUSEC WAF 7.2.6 配置参数详解

目标：按配置面逐组讲清 UUSEC WAF（南墙）v7.2.6 的全部配置入口：管理面 config.json 字段、数据面 nginx 配置组、站点与防护参数、规则与规则集参数、元数据库与资源参数，并给出三档生产配置模板。 全部字段取值与行为均在 7.2.6 实测环境取证（部署过程见 《UUSEC WAF Docker Compose 部署指南》），敏感值（密钥/令牌/密码）按规范以 ${VAR} 占位并同时给出读取方式。

一、环境信息

• 实验主机：Ubuntu 22.04.4 LTS，x86_64；UUSEC WAF 7.2.6（官方 compose 发行形态，安装目录以 /opt/waf/ 为准）；元数据库 mysql:5.7
• 配置面版本：管理面 config.json 与系统设置接口版本号字段实测回显 "version": "7.2.6"
• 本篇实测环境差异：数据面 HTTP 监听改为 8133（默认 80；宿主 80 被其他服务占用），443/4443/777/4447/6612 为默认值——涉及端口示例时同时标注默认值与实测值
• 演示站点：wafdemo.example.com → 源站 127.0.0.1:8139（部署篇建立）
• 修改生效验证基准：每次修改后以「正常请求 200 + SQLi 请求 403 + 管理台接口 200」三连验证服务可用性（本篇所有修改点实测通过）

二、前置条件

1. 已按部署篇完成 compose 部署并能访问管理台（默认 https://<IP>:4443，实测账号 admin）；
2. REST API 认证可用（管理台"系统设置"中获取 api_token，或从 config.json 读取，JWT/Token 两种认证头的用法见 《UUSEC WAF 7.2.6 管理 API 使用详解》）；
3. 数据面配置目录已挂载到宿主（官方 compose 默认不挂载 /uuwaf/conf/，改数据面配置前先按部署篇第八章补挂载，否则重建后丢失）；
4. 修改前备份：cp -a /opt/waf/waf_config /opt/waf/waf_config.bak（管理面）与 cp -a /opt/waf/waf_conf /opt/waf/waf_conf.bak（数据面）。

三、参数查看与修改方式

UUSEC WAF 的参数分布在四个层面，查看与修改方式不同（实测归纳）：

⚠️ 注意：config.json 与 PUT /api/v1/setting 是同一份数据的两个入口。直改文件绕过了管理面的参数校验，生产优先走管理台；仅当管理台不可用时才手改文件并重启。

四、参数总览（配置面地图）

五、管理面参数详解（config.json）

GET /api/v1/setting 实测全量回显（密钥类字段以 ${VAR} 占位）：

{
    "id": "1",
    "addr": ":4443",
    "dsn": "root:${MYSQL_PASSWORD}@tcp(127.0.0.1:6612)/uuwaf?charset=utf8mb4&parseTime=true&loc=Local",
    "jwt_key": "${JWT_KEY}",
    "jwt_expiration": 43200,
    "waf_nodes": ["127.0.0.1:4447"],
    "ml_server": "http://127.0.0.1:4445",
    "ml_token": "${ML_TOKEN}",
    "api_token": "${API_TOKEN}",
    "log_db": true,
    "log_level": "error",
    "language": "zh",
    "version": "7.2.6"
}

敏感值读取方式（执行下述命令即得到真实值，避免文档落盘密钥）：

# CONFIG=/opt/waf/waf_config/config.json
# API_TOKEN=$(python3 -c "import json;print(json.load(open('$CONFIG'))['api_token'])")
# JWT_KEY=$(python3 -c "import json;print(json.load(open('$CONFIG'))['jwt_key'])")
# ML_TOKEN=$(python3 -c "import json;print(json.load(open('$CONFIG'))['ml_token'])")

逐字段详解（实测值与行为）：

管理台修改实测（等价于系统设置页提交；本篇用原值回写验证接口可用，"OK" 回显）：

# curl -sk -X PUT 'https://127.0.0.1:4443/api/v1/setting' \
      -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
      -d '{"addr":":4443","dsn":"root:'"$MYSQL_PASSWORD"'@tcp(127.0.0.1:6612)/uuwaf?charset=utf8mb4&parseTime=true&loc=Local", ... }'
"OK"

💡 说明：api_token 与 JWT 是并存的两种管理 API 认证方式——JWT 由登录接口签发（12 小时有效，适合交互/自动化脚本），Api-Token 为长效令牌（适合监控采集类长任务）；生产建议日常用 JWT、只给采集器发 Api-Token。

六、数据面 nginx 配置详解（waf_conf/）

数据面主配置 uuwaf.conf（实测 173 行）按 nginx 风格组织，处理链为：init_by_lua（加载 waf 引擎）→ 请求进入 server（include listen.conf/gzip.conf/ssl.conf）→ rewrite_by_lua（waf.req_filter()，规则/语义/黑名单检测）→ 回源（balancer_by_lua 动态选源站）→ header_filter_by_lua/body_filter_by_lua（响应过滤）→ log_by_lua（访问与攻击日志）。以下按参数组讲解。

6.1 全局性能组（uuwaf.conf 顶部）

user  root;
worker_processes auto;
worker_cpu_affinity auto;
worker_rlimit_nofile 102400;
events {
    use epoll;
    accept_mutex off;
    worker_connections 102400;
}
pcre_jit on;
worker_shutdown_timeout 240s;

• worker_processes auto + worker_cpu_affinity auto：按 CPU 核数自动起 worker 并绑核（实测 8 核机器起 8 个 worker）；
• worker_connections 102400 / worker_rlimit_nofile 102400：单 worker 连接与句柄上限，与 compose 的 ulimits.nofile=102400 呼应；
• keepalive_timeout 65s、client_max_body_size 0（不限制请求体大小，上传场景友好）、server_tokens off（隐藏版本指纹）。

共享内存区（lua_shared_dict，实测 9 个，总量约 106 MB）：ipCache 16m、ipBlock 8m、stats 2m、db 32m（站点/规则配置缓存）、robot 16m（人机验证）、purge 4m（缓存清理）、lock 2m、live 2m（实时统计）、search_engines 8m（搜索引擎识别）。站点与白名单规模很大时优先调大 db。

缓存路径：proxy_cache_path /tmp/disk_cache_uuwaf ... keys_zone=cache_zone:32m max_size=8g inactive=60m——磁盘缓存上限 8 GB，位于容器 tmpfs/临时层，站点开启 is_cache 后生效。

6.2 监听组（listen.conf，实测全文）

listen 8133 default_server reuseport;      # 默认值 listen 80 default_server reuseport;
listen 443 ssl default_server reuseport;
### For HTTP2
#listen 443 ssl http2 default_server reuseport;
### For IPv6
#listen [::]:80 default_server reuseport;
#listen [::]:443 ssl default_server reuseport;

• HTTP 监听默认 80（本环境实测改为 8133，宿主 80 被占用；改法与持久化见部署篇第八章，重启后实测 8133 正常监听、回源 200）；
• HTTPS 默认 443 开启 ssl；HTTP2 与 IPv6 监听为注释可选项，按需放开。

6.3 回源转发组（proxy.conf，实测全文）

proxy_http_version      1.1;
proxy_buffer_size       16k;
proxy_buffers           8 16k;
proxy_busy_buffers_size 32k;
proxy_read_timeout      600s;
proxy_set_header        Upgrade            $upstream_upgrade;
proxy_set_header        Connection         $upstream_connection;
proxy_set_header        X-Real-IP          $remote_addr;
proxy_set_header        X-Forwarded-For    $proxy_add_x_forwarded_for;
proxy_set_header        X-Forwarded-Proto  $scheme;
proxy_set_header        X-Forwarded-Host   $host;
proxy_set_header        X-Forwarded-Port   $server_port;
proxy_set_header        Host               $upstream_host;
proxy_hide_header       X-Powered-By;
proxy_ssl_server_name   on;
proxy_ssl_name          $upstream_host;
proxy_next_upstream     error timeout http_500 http_502 http_503 http_504;
proxy_pass              $upstream_scheme://waf_backend;

要点：回源统一走 waf_backend upstream（balancer_by_lua 按站点配置动态选择真实源站，配合 keepalive 320 连接复用）；向源站透传 X-Real-IP、X-Forwarded-For 等真实客户端信息；proxy_next_upstream 覆盖 error/timeout/5xx 自动重试下一源站（多源站负载均衡的容错基础）；proxy_hide_header X-Powered-By 隐藏源站技术栈指纹。

6.4 TLS 组（ssl.conf，实测全文）

ssl_certificate      cert/ssl_PLACE_HOLDER.crt;
ssl_certificate_key  cert/ssl_PLACE_HOLDER.key;
ssl_session_cache    shared:SSL:20m;
ssl_session_timeout  10m;
ssl_session_tickets  off;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:...(现代套件列表，实测原文);
ssl_prefer_server_ciphers off;

站点证书不在本文件写死——ssl_certificate_by_lua 阶段按 SNI 动态加载站点证书（cert/ 目录存放各站点证书文件，默认仅 ssl_PLACE_HOLDER 占位对，站点未配证书时由管理面下发的内置通配证书兜底，实测 CN=*）。协议与套件为现代安全基线（TLSv1.2/1.3），一般无需调整。

6.5 缓存组（cache.conf，实测全文）

proxy_cache            cache_zone;
proxy_set_header       Range              $http_range;
proxy_set_header       If-Range           $http_if_range;
proxy_cache_key        $scheme$host$request_uri$http_range;
proxy_cache_use_stale  error timeout invalid_header updating http_500 http_502 http_503 http_504;
proxy_cache_bypass     $skip_cache;
proxy_no_cache         $skip_cache;
proxy_cache_valid      200 206 0;
add_header             X-Waf-Cache $upstream_cache_status;
### Force cache
#proxy_ignore_headers   X-Accel-Expires Expires Cache-Control Set-Cookie Vary;

X-Waf-Cache 响应头由最后一行注入（实测正常请求回显 X-Waf-Cache: BYPASS——动态请求跳过缓存；静态命中时为 HIT）。proxy_cache_valid 200 206 0 的 0 表示有效期由源站 Cache-Control 决定；proxy_cache_use_stale 允许源站故障时返回过期缓存。站点级开关对应站点参数 is_cache。

6.6 内部端口与状态端点（uuwaf.conf 末尾 server 块）

server {
    listen 4447 default_server reuseport;
    location /uuwaf/admin { allow 127.0.0.0/8; deny all; content_by_lua_block { waf.http_admin() } }
    location /uuwaf/live  { allow 127.0.0.0/8; deny all; content_by_lua_block { waf.http_live() } }
}

4447 是数据面 Lua 与管理面（Go）之间的节点通道（对应 config.json 的 waf_nodes），仅允许 127.0.0.0/8 访问——这就是管理台配置"发布即生效"的链路：管理面写入库 → 调用 4447 /uuwaf/admin 下发 → 数据面 Lua 更新共享内存。另有 /uuwaf/status（nginx 原生状态页，仅本机）与验证码组件 777（@robot location 代理至 127.0.0.1:777）。缓存清理与 ACME 验证也各有专用 location（/.well-known/acme-challenge/ 指向 /uuwaf/html/）。

6.7 其他辅助文件

七、站点与防护参数组

站点参数经管理台"站点管理"维护（库表化存储，管理面下发生效）。实测对象结构（GET /api/v1/sites）与逐项说明：

⚠️ 注意：ip_source/ip_order/ip_header 决定 WAF 认定的攻击来源 IP。WAF 前面还有 CDN/负载均衡时必须正确设置，否则 CC 防护与 IP 封禁会对准代理 IP 误伤全量用户。另外主配置中有注释掉的 set_real_ip_from/real_ip_header/real_ip_recursive 段，多级代理场景需要一并放开。

八、规则与规则集参数组

内置规则集实测状态（GET /api/v1/rules 与 /api/v1/ruleset）：

• 规则共 50 条，全部 type: 1（Lua 脚本规则），如 React2Shell（React Server Components RCE）、SSTI 服务器端模板注入、Tomcat RCE(CVE-2025-24813) 等，按漏洞类型持续随版本更新；
• level 为威胁等级（实测值 3-4，配合拦截策略）；
• phase 为生效阶段：实测 44 条为 0（请求检测）、1 条为 1、5 条为 2（含响应阶段检测），官方未公开逐级语义，理解为"请求/响应处理阶段"即可；
• 规则 content 即 Lua 脚本，基于官方 waf.* API 编写（如 waf.reqHeaders、waf.form、waf.rgxMatch、waf.endWith 等），在管理台规则编辑器修改后发布即生效、无需重启；
• 规则集 Default（id 1）的 content 是启用的规则 ID 列表（实测 [75,74,73,72,70,69,65,64,62,61,60,59,58,56,55,54,53,52,51,50,49,48,47,46,45,44,43,41,29,28,27,25,24,22,21,20,19,18,17,16,15,14,13,12,11]），站点通过 ruleset_id 绑定；拦截页展示的「规则ID：45」即规则对象的 id（45 = 常规sql注入检测，实测拦截统计一致）。

自定义规则的 Lua 扩展语法（waf.* API 全集）官方在管理台规则编辑器与文档站有专门说明，深度定制场景（如业务漏洞应急规则）是 UUSEC WAF 相对正则引擎 WAF 的核心优势之一。

九、元数据库与资源参数组

⚠️ 注意：waf_data/ 内是 MySQL 数据目录（站点/规则/攻击日志全在此），低内存模板把 InnoDB 缓冲池压到 5M，仅适合站点少、流量小的场景；数据量大时日志表增长很快，建议至少给元数据库预留 4 GB 以上磁盘并监控 waf_data 目录占用。

十、生产配置模板

模板 A：小内存入门（2 GB 内存 / 20 GB 磁盘 / 站点 ≤ 5 个、日均十万级请求）

• 启用 low-memory-my.cnf（compose 中取消挂载注释）；
• 其余保持官方默认（worker auto、8 GB 缓存路径不启用缓存时无实际占用：站点不开 is_cache 即不落盘缓存）；
• config.json 保持默认；管理台 addr 建议改 127.0.0.1:4443 经堡垒机/SSH 隧道访问。

模板 B：常规生产（4-8 GB 内存 / 100 GB 磁盘 / 站点 ≤ 16 个、日均百万级请求）

• 官方默认全量可用（本篇实测基线即此档：默认 worker/连接数、MySQL max_connections=512）；
• 站点按需开 is_cache（缓存磁盘 max_size=8g 内）与 force_ssl；
• jwt_expiration 可收紧到 3600（1 小时）提高管理台安全性；
• 备份策略：每日备份 waf_config/ 与 waf_data/。

模板 C：高流量缓存型（16 GB+ 内存 / NVMe SSD 500 GB+ / CDN 回源场景）

• 数据面共享内存调大：db 32m→128m、ipCache 16m→64m（站点/白名单规模大时）；
• proxy_cache_path 的 max_size=8g 按磁盘上调（如 100g），inactive 按业务热度调整；
• worker_connections 与 ulimits 同步上调（如 204800），并确认宿主 fs.file-max 足够；
• 多节点集群管理为商业版权益，社区版单节点建议在外围用 DNS 轮询或负载均衡做高可用。

十一、常见问题

Q1：改了 config.json / listen.conf 不生效？ 管理台（PUT /setting）提交的管理面参数立即生效；直接编辑 config.json 的修改需重启 uuwaf 服务加载（实测重启后管理台登录、回源、拦截均正常）。数据面配置（listen.conf 等）一律需要重启 uuwaf 服务生效，且该目录必须已挂载到宿主，否则重建后改动丢失（实测踩坑见部署篇）。

Q2：如何确认站点/规则修改已同步到数据面？ 看 waf_logs/error.log：无新增 failed to update sites 类报错即同步成功；再用攻击特征请求验证拦截（本篇基准三连验证）。

Q3：api_token 泄露了怎么办？ 管理台"系统设置"中更换 api_token（或 PUT /api/v1/setting 更新该字段）即可，旧令牌立即失效；JWT 密钥（jwt_key）同理，更换后所有已签发会话失效，需重新登录。

Q4：WAF 前面还有 CDN/代理，CC 防护封的是代理 IP？ 是默认行为。需要把 ip_source/ip_order/ip_header（站点参数）与 uuwaf.conf 中注释的 set_real_ip_from/real_ip_header 段按真实链路配置，让 WAF 认定真实客户端 IP（官方约定透传 X-Waf-Ip/X-Forwarded-For）。

Q5：元数据库密码能改吗？ 能，且必须三处同步：MySQL 侧 root 密码 → config.json 的 dsn（或管理台系统设置）→ compose 的 MYSQL_PASSWORD/UUWAF_DB_DSN。漏改任何一处都会导致管理面或数据面读库失败。

十二、参考链接

• 官方仓库：https://github.com/Safe3/uusec-waf
• 官方 FAQ（config.json / 端口修改 / REST API 约定）：https://waf.uusec.com/#/guide/problems
• 官方文档站：https://waf.uusec.com/
• 本专栏关联篇目：《UUSEC WAF 7.2.6 介绍与选型指南》（版本与能力边界）、《UUSEC WAF Docker Compose 部署指南》（部署与挂载操作）、《UUSEC WAF 7.2.6 管理 API 使用详解》（本篇 API 调用的完整说明）