BunkerWeb 1.6.16 配置参数详解

目标：讲清 BunkerWeb 1.6.16 的配置存储与下发机制，覆盖核心参数（API 白名单、日志级别、站点与反代组）与安全插件开关（黑白名单、限速、Bot 检测、Bad behavior），每项改动均给出实测回显；并演示自定义配置注入的完整闭环。环境基于《BunkerWeb Docker Compose 部署指南》部署的 1.6.16 五容器栈；防护参数的攻防效果对照见《BunkerWeb 安全加固指南》。

一、环境信息

操作系统：Ubuntu 22.04.4 LTS（x86_64），Docker 29.8.1（Compose v5.5.1）
BunkerWeb 1.6.16（bunkerweb / bw-scheduler / bw-ui 三镜像同版本，内置 nginx/1.30.5），编排与部署过程见《BunkerWeb Docker Compose 部署指南》
配置数据库：PostgreSQL 18（bw-db 容器，库名 db，用户 bunkerweb）
受管站点：app.local（反代到后端静态站点 myapp），客户端流量入口宿主端口 8117（HTTP）
配置修改方式：本次实测统一采用 scheduler 环境变量 + 数据库直查/直改 两条路径（UI 界面修改等价于数据库 method=ui 写入，二者最终都由 scheduler 检测并重新渲染下发）
实测日期：2026-10-19；所有回显均为真实命令输出摘录

二、前置条件

已按《BunkerWeb Docker Compose 部署指南》完成部署，五个服务状态健康（docker compose ps 全部 Up，核心三服务 healthy）；
已有受管站点 app.local 可访问（curl -H 'Host: app.local' http://127.0.0.1:8117/ 返回 200）；
掌握两条查看配置的命令通道：
- 数据库通道：docker exec -i bunkerweb-1-6-16-db psql -U bunkerweb -d db（配置真源）；
- 数据面通道：docker exec bunkerweb-1-6-16-waf sh（查看渲染结果 /etc/nginx 与运行日志）；
理解一条铁律：所有配置修改都要经过 scheduler 检测 → GENERATOR 重新渲染 → 推送数据面 → NGINX reload 四步才生效，后文所有实测均以"数据库回显 + 数据面日志/行为变化"双证据闭环。

三、配置存储与参数查看方式

3.1 存储架构（实测确认）

BunkerWeb 1.6 以数据库为中心管理配置，实测 PostgreSQL 中相关表与职责：

表	职责	实测样例
bw_settings	设置定义（名称/插件归属/默认值/帮助文本），即"参数字典"	`log-level` 默认 `info`、`use-limit-req` 默认 `yes`
bw_global_values	全局设置值（GLOBAL 上下文）	`SERVER_NAME=app.local`、`MULTISITE=yes`
bw_services_settings	站点级设置值（MULTISITE 每站点一行组）	`app.local` 的 `REVERSE_PROXY_HOST=http://myapp:80`
bw_services	受管服务清单（id + 来源方法）	`app.local`（method=scheduler）
bw_custom_configs	自定义配置片段（原文 + 校验和 + 来源）	见"七、自定义配置注入"

参数命名存在两套写法，实测对应关系：环境变量/数据库中的站点设置用大写下划线（USE_BAD_BEHAVIOR），而 bw_settings 字典表用小写连字符 slug（use-bad-behavior）；环境变量 app.local_WHITELIST_IP 对应站点级设置（域名前缀 + 下划线大写设置名）。

值来源用 method 字段区分：scheduler（环境变量注入）、ui（管理界面）、api（REST API）、manual 等。实测确认合并优先级：UI/API 写入的值覆盖环境变量默认；环境变量只在 scheduler 侧生效——但注意一个实测发现：bw-ui 进程会在运行期把其内存中的配置同步回写数据库（实测在清理测试配置时出现"删了又回来"的现象，排查确认回写来源为 bw-ui 进程内存态；清库前先重启 bw-ui 或直接用 UI 界面删除，见"十一、常见问题 Q3"）。

3.2 查看方式一：数据库直查

查全局设置值：

docker exec -i bunkerweb-1-6-16-db psql -U bunkerweb -d db \
  -c "SELECT setting_id, value, method FROM bw_global_values ORDER BY setting_id LIMIT 8;"

实测回显：

    setting_id    |                   value                   |  method
------------------+--------------------------------------------+-----------
 API_WHITELIST_IP | 127.0.0.0/8 10.89.45.0/24                  | scheduler
 BUNKERWEB_INSTANCES | bunkerweb                               | scheduler
 DISABLE_DEFAULT_SERVER | yes                                  | scheduler
 MULTISITE        | yes                                       | scheduler
 SERVER_NAME      | app.local                                 | scheduler
 SERVE_FILES      | no                                        | scheduler
 USE_CLIENT_CACHE | yes                                       | scheduler
 USE_GZIP         | yes                                       | scheduler

查站点级设置值：

docker exec -i bunkerweb-1-6-16-db psql -U bunkerweb -d db \
  -c "SELECT service_id, setting_id, value FROM bw_services_settings WHERE service_id='app.local' ORDER BY setting_id;"

实测回显（节选）：

 service_id |     setting_id      |      value
------------+---------------------+------------------
 app.local  | REVERSE_PROXY_HOST  | http://myapp:80
 app.local  | REVERSE_PROXY_URL   | /
 app.local  | USE_REVERSE_PROXY   | yes
 app.local  | WHITELIST_IP        | 10.89.47.1

3.3 查看方式二：数据面渲染结果

环境变量最终被渲染进数据面容器的 /etc/nginx/variables.env 与站点配置目录，可逐字核对下发结果：

docker exec bunkerweb-1-6-16-waf grep -E 'WHITELIST' /etc/nginx/variables.env

实测回显：

app.local_WHITELIST_IP=10.89.47.1
app.local_USE_WHITELIST=yes

3.4 修改方式与生效链路

方式	操作	适用
环境变量（本篇主用）	改 docker-compose.yml 中 scheduler 的 environment → `docker compose up -d`	全局/站点基础设置，配置即代码
UI 界面	登录 `http://<IP>:7000` → Services → 站点 → 设置表单修改	日常运维，method=ui，优先级高于环境变量
数据库直改	psql UPDATE/INSERT（需自行触发重渲染）	自动化脚本、旁路注入（见第七节）

环境变量方式修改后，scheduler 容器重建并自动完成渲染下发，实测日志（docker logs bunkerweb-1-6-16-scheduler）：

[2026-10-19 06:03:45 +0000] [GENERATOR] [75] [ℹ️ ] - Generator successfully executed !
[2026-10-19 06:03:45 +0000] [SCHEDULER] [36] [ℹ️ ] - Sending /etc/nginx to all reachable BunkerWeb instances ...
[2026-10-19 06:03:45 +0000] [SCHEDULER] [36] [ℹ️ ] - Successfully sent /etc/nginx folder to reachable BunkerWeb instances
[2026-10-19 06:03:45 +0000] [SCHEDULER] [36] [ℹ️ ] - Successfully reloaded bunkerweb

旁路注意：直接往数据库 INSERT 设置/自定义配置不会触发 scheduler 的事件检测（实测插入后 60 秒内 GENERATOR 未重跑），需要 docker restart bunkerweb-1-6-16-scheduler 强制全量重新渲染；正常运维请走 UI 或环境变量路径。

四、参数总览

按功能域分组的核心参数速查（默认值取自 bw_settings 字典表实测）：

分组	参数（env 写法）	默认值	作用
API 安全组	API_HTTP_PORT / API_LISTEN_IP / API_SERVER_NAME	5000 / 0.0.0.0 / bwapi	数据面内部 API 监听
API 安全组	API_WHITELIST_IP	—（建议必设）	允许调用内部 API 的源网段
日志组	LOG_LEVEL	info	scheduler 日志级别
日志组	LOG_TYPES / LOG_FILE_PATH / LOG_SYSLOG_ADDRESS	stderr	日志输出形态
站点组	SERVER_NAME / MULTISITE	— / no	受管域名 / 多站点模式
站点组	<域名>_USE_REVERSE_PROXY 等	no	站点级反代
Bad behavior	USE_BAD_BEHAVIOR	yes	异常行为计分封禁
Bad behavior	BAD_BEHAVIOR_THRESHOLD / BAN_TIME	10 / 1d	触发阈值与封禁时长
黑名单	USE_BLACKLIST / BLACKLIST_IP	yes / —	IP/ASN/RDNS 黑名单
白名单	USE_WHITELIST / WHITELIST_IP	yes / —	IP/ASN/RDNS 白名单
限速	USE_LIMIT_REQ / LIMIT_REQ_RATE / LIMIT_REQ_URL	yes / 2r/s / /	每 URL 请求速率限制
限速	USE_LIMIT_REQ_GLOBAL / LIMIT_REQ_GLOBAL_RATE	no / 1000r/s	全局聚合限速
Bot 检测	USE_ANTIBOT	no	挑战模式：cookie/javascript/captcha 等
反代/缓存	USE_REVERSE_PROXY / USE_CLIENT_CACHE / USE_GZIP	no / no / no	基础流量能力

五、核心参数详解

5.1 API 白名单（API_WHITELIST_IP）

内部 API（数据面 5000 端口，虚拟主机 bwapi）是配置下发唯一通道，官方明确要求该设置在数据面与 scheduler 两侧镜像一致。本环境取值 127.0.0.0/8 10.89.45.0/24（回环 + bw-universe 网段）。

隔离效果实测——白名单源（bw-ui，位于 bw-universe）与非白名单源（myapp，位于 bw-services）对照访问：

docker exec bunkerweb-1-6-16-ui python3 -c "
import urllib.request
req = urllib.request.Request('http://bunkerweb:5000/', headers={'Host': 'bwapi'})
try:
    r = urllib.request.urlopen(req, timeout=5); print('HTTP', r.status)
except urllib.error.HTTPError as e: print('HTTP', e.code)
except Exception as e: print('ERR:', e)
"

实测回显（白名单源，TCP 可达进入 HTTP 层，404 为路径级响应）：

HTTP 404

docker exec bunkerweb-1-6-16-myapp wget -S --header 'Host: bwapi' -O /dev/null http://bunkerweb:5000/ 2>&1 | head -4

实测回显（非白名单源，TCP 层直接被拒绝，无 HTTP 响应）：

Connecting to bunkerweb:5000 (10.89.47.3:5000)
wget: error getting response: Connection reset by peer

结论：API 白名单在网络层完成隔离，非白名单源连请求都进不来。加固建议：生产环境务必把 API_WHITELIST_IP 收敛到管理网段，不要使用 0.0.0.0/0。

5.2 日志级别（LOG_LEVEL）

LOG_LEVEL 控制 scheduler 日志级别。实测将全局 LOG_LEVEL 由 info 改为 warning 后重建 scheduler：运行期原本每分钟出现的 info 级周期行（如 [SCHEDULER] [36] [ℹ️ ] - Executing job scheduler ...）全部消失，仅剩 warning 及以上级别（实测观测到 [JOBS.MMDB-COUNTRY] [⚠️ ] - Transient DB-IP download error, retrying (1/3) 仍正常输出）；恢复 info 后周期行重新出现。

取值建议：生产常态 info 便于审计配置变更；排障期临时调 debug 观察插件链路；warning 仅适合长期稳定运行后的降噪。数据面 NGINX 访问/错误日志由 LOG_LEVEL 与 LOG_TYPES 共同决定，输出到 stderr 可直接被 docker logs 采集。

5.3 站点与反代组（SERVER_NAME/MULTISITE/REVERSE_PROXY_*）

部署篇已实测定型，本篇补充参数语义：

SERVER_NAME：受管域名列表（空格分隔）。与请求 Host 头匹配，未匹配且 DISABLE_DEFAULT_SERVER=yes 时直接拒绝；
MULTISITE=yes 后，站点级设置以 域名_设置名 为完整键名（如 app.local_LIMIT_REQ_RATE），在 bw_services_settings 中按 service_id 分行存储（3.2 回显）；
反代三件套 <域名>_USE_REVERSE_PROXY=yes + <域名>_REVERSE_PROXY_URL=/ + <域名>_REVERSE_PROXY_HOST=http://myapp:80，实测请求链路 200（部署篇 4.7 回显）。

六、安全插件开关实测

以下每项实测均为"改配置 → 数据库回显 → 数据面日志/请求行为变化"三步闭环，客户端统一为宿主（数据面观测到的源 IP 为 10.89.47.1，bw-services 网桥网关）。

6.1 白名单（USE_WHITELIST / WHITELIST_IP）

为站点配置白名单（把测试客户端 IP 放行）：

# docker-compose.yml scheduler 段追加
app.local_USE_WHITELIST: "yes"
app.local_WHITELIST_IP: "10.89.47.1"

数据库回显（SELECT service_id, setting_id, value FROM bw_services_settings WHERE setting_id LIKE '%WHITELIST%'）：

 app.local  | WHITELIST_IP | 10.89.47.1

数据面日志回显（docker logs bunkerweb-1-6-16-waf | grep -i whitelist）：

[2026-10-19 06:05:26 +0000] [ACCESS] [30] [ℹ️ ] - ACCESS app.local /?id=1%20UNION%20SELECT%201,2,3: whitelist returned status 0 : IP is whitelisted (info : ip), client: 10.89.47.1

实测发现（重要）：白名单生效后，BunkerWeb 自身插件链（bad behavior 计分、blacklist 等）对该 IP 全部放行（status 0，后续插件不再执行，403 异常计数停止增长）；但 ModSecurity CRS 引擎的 anomaly score 拦截仍独立触发（同请求依旧 403）——因 CRS 的白名单短路规则（SecRule ENV:is_whitelisted "yes"）在 phase:1 执行时 nginx 变量尚未置位。若需对可信 IP 同时关闭 CRS，应另用站点级 ModSecurity 设置或 CRS 白名单规则处理，不要依赖 IP 白名单。

6.2 黑名单（USE_BLACKLIST / BLACKLIST_IP）

移除白名单后配置黑名单（把同一测试 IP 封禁）：

app.local_USE_BLACKLIST: "yes"
app.local_BLACKLIST_IP: "10.89.47.1"

实测请求行为：

curl -s -o /dev/null -w 'HTTP %{http_code}\n' -H 'Host: app.local' http://127.0.0.1:8117/

HTTP 403

数据面日志回显：

[2026-10-19 06:06:41 +0000] [ACCESS] [30] [ℹ️ ] - ACCESS app.local /: denied access from blacklist : IP is blacklisted (info : ip), client: 10.89.47.1

对照结论：同一 IP 在黑名单模式下所有请求（含正常请求）直接 403 拒绝，与白名单模式"放行插件链"形成互补闭环。黑名单插件另支持 BLACKLIST_RDNS_GLOBAL（反向 DNS 恶意主机名匹配）、BLACKLIST_ASN、社区黑名单订阅（数据面缓存 /var/cache/bunkerweb/blacklist/app.local/IP.list 实测含社区源列表）。

6.3 限速（USE_LIMIT_REQ / LIMIT_REQ_RATE / LIMIT_REQ_URL）

站点级限速配置（每秒 1 个请求）：

app.local_LIMIT_REQ_RATE: "1r/s"
app.local_LIMIT_REQ_URL: "/"

实测连续 4 次请求：

for i in 1 2 3 4; do curl -s -o /dev/null -w "req$i: %{http_code}\n" -H 'Host: app.local' http://127.0.0.1:8117/; done

req1: 200
req2: 429
req3: 429
req4: 429

结论：首请求放行，超速率请求一律 429。注意 1.6 的限速插件默认即启用（use-limit-req 默认 yes、默认速率 2r/s），低流量场景如果出现"偶发 429"，先检查该默认值。全局聚合限速用 USE_LIMIT_REQ_GLOBAL=yes + LIMIT_REQ_GLOBAL_RATE（默认 1000r/s）配合。

6.4 Bot 检测（USE_ANTIBOT）

启用 cookie 挑战模式：

app.local_USE_ANTIBOT: "cookie"

实测无 cookie 首次访问：

curl -si -H 'Host: app.local' http://127.0.0.1:8117/ | head -12

HTTP/1.1 302 FOUND
Content-Type: text/html; charset=utf-8
Set-Cookie: antibot_rand=<随机值>; Expires=<+10min>; Max-Age=600; Path=/; SameSite=Lax
Location: /challenge
...

完成挑战（携带挑战 cookie 访问 /challenge 完成人机验证）后再访问，数据面日志回显：

[2026-10-19 06:08:56 +0000] [ACCESS] [30] [ℹ️ ] - ACCESS app.local /: antibot redirect to / : client already resolved the challenge, client: 10.89.47.1

正常请求返回 200。实测结论：antibot 的三档强度（cookie/javascript/captcha）都走"挑战 → 发放凭证 → 放行"模型；curl 等无浏览器 UA/脚本能力自动被挡在挑战层，非常适合拦截脚本化爬虫与扫描器。Challenge 页面有效期 600 秒（Set-Cookie Max-Age=600 实测）。

6.5 Bad behavior（USE_BAD_BEHAVIOR）

bad behavior 插件默认开启（use-bad-behavior 默认 yes，阈值 10 次/分钟、封禁 1 天）。实测在 403/429 高频异常请求下数据面日志出现计数器动作：

[2026-10-19 05:56:51 +0000] [ACCESS] [30] [ℹ️ ] - BADBEHAVIOR increase counter (details: request path: /, status code: 403, ...), client: 10.89.47.1
[2026-10-19 05:57:09 +0000] [ACCESS] [30] [ℹ️ ] - BADBEHAVIOR decrease counter (details: badbehavior rand: <token>), client: 10.89.47.1

实测结论：403/429 等异常响应会累计计数（threshold=10），正常交互会衰减计数（decrease）；累计到阈值即触发封禁，且与 6.3 限速的"单 URL 速率"维度互补——它拦的是"行为模式异常"而非"瞬时高频"。

七、自定义配置注入

1.6 的自定义配置（Custom Configs）允许向 NGINX 配置树的 9 个上下文注入原始片段：http、stream、server_http、server_stream、default_server_http、modsec、modsec_crs、crs_plugins_before、crs_plugins_after（实测枚举自数据库 custom_configs_types_enum）。UI 中在 Services → 站点 → Custom configs 页面操作；本实测演示数据库旁路注入 + scheduler 重渲染的完整闭环。

第一步：注入一条 server_http 自定义配置（给 app.local 的 server 块追加自定义响应头）：

docker exec -i bunkerweb-1-6-16-db psql -U bunkerweb -d db -c "
INSERT INTO bw_custom_configs (service_id, type, name, data, checksum, method, is_draft)
VALUES ('app.local', 'server_http', 'add-custom-header.conf',
        convert_to('add_header X-Custom-Config \"injected-by-custom-config\" always;', 'UTF8'),
        'manual-insert-01', 'ui', false);"

实测回显：

INSERT 0 1

第二步：触发重渲染（旁路插入不触发事件检测，重启 scheduler）：

docker restart bunkerweb-1-6-16-scheduler

第三步：验证响应头出现：

curl -sI -H 'Host: app.local' http://127.0.0.1:8117/ | grep -iE 'HTTP/|X-Custom'

实测回显：

HTTP/1.1 200 OK
X-Custom-Config: injected-by-custom-config

清理同样要走三处（实测踩坑：只删数据库行会被回写）：① 数据库 DELETE FROM bw_custom_configs WHERE name='add-custom-header';；② scheduler 卷内镜像 /data/configs/server-http/app.local/add-custom-header.conf（实测它会在 scheduler 重启时恢复数据库）；③ 先重启 bw-ui 清空其内存态（实测 bw-ui 会把内存中的配置回写数据库）。完整清理顺序实测有效：

docker stop bunkerweb-1-6-16-scheduler
docker exec -i bunkerweb-1-6-16-db psql -U bunkerweb -d db -c "DELETE FROM bw_custom_configs;"
docker exec bunkerweb-1-6-16-scheduler sh -c 'rm -f /data/configs/server-http/app.local/add-custom-header.conf'
docker restart bunkerweb-1-6-16-ui
docker start bunkerweb-1-6-16-scheduler

清理后实测：响应头消失、正常请求 200。运维建议：生产环境统一用 UI 界面增删自定义配置（含草稿/发布流），避免旁路操作引入上述多源一致性问题。

八、生产配置模板

综合本篇实测，给出一份可直接复用的 scheduler 环境变量基线（在部署篇 compose 基础上追加/修改）：

    environment:
      <<: *env
      BUNKERWEB_INSTANCES: "bunkerweb"
      SERVER_NAME: "www.example.com app.example.com"
      API_WHITELIST_IP: "127.0.0.0/8 10.89.45.0/24"   # 收敛到管理网段，两侧镜像一致
      MULTISITE: "yes"
      SERVE_FILES: "no"
      DISABLE_DEFAULT_SERVER: "yes"
      LOG_LEVEL: "info"                                # 审计期保持 info，稳定后可降 warning
      USE_CLIENT_CACHE: "yes"
      USE_GZIP: "yes"
      # —— 安全基线（默认已开，显式声明便于审计）——
      USE_BAD_BEHAVIOR: "yes"                          # 行为封禁 10 次/1min → ban 1d
      USE_BLACKLIST: "yes"                             # IP/ASN/RDNS 黑名单
      USE_WHITELIST: "yes"                             # 白名单（运维网段专用）
      USE_LIMIT_REQ: "yes"                             # 每 URL 限速
      LIMIT_REQ_RATE: "2r/s"                           # 按业务流量调
      USE_ANTIBOT: "cookie"                            # 公网表单/登录站点可升 javascript/captcha
      # —— 站点级示例 ——
      www.example.com_USE_REVERSE_PROXY: "yes"
      www.example.com_REVERSE_PROXY_URL: "/"
      www.example.com_REVERSE_PROXY_HOST: "http://webapp:80"
      www.example.com_USE_ANTIBOT: "no"                # API 类站点关闭挑战避免误伤客户端

模板要点：① 安全插件默认全开，公网站点按需对 API 路径单独关闭 antibot；② 所有环境变量修改后 docker compose up -d 生效，观察 scheduler 日志出现 Generator successfully executed ! 与 Successfully reloaded bunkerweb 即完成下发；③ 站点级参数永远带 域名_ 前缀，全局参数不带。

九、常见问题

Q1：改了 compose 环境变量但不生效？

先确认容器真的重建了（docker compose up -d 只重建环境变化的服务）；再看数据库是否有值（bw_global_values/bw_services_settings，method=scheduler）；再看 scheduler 日志是否出现 Generator successfully executed !；最后核对数据面 variables.env。四步定位（本篇 3.2/3.4 的通道）。

Q2：UI 修改的值和环境变量不一致时以谁为准？

实测合并规则：UI 写入的值（method=ui）覆盖环境变量值；bw_services_settings 同一 setting_id 只保留一行（method 标记来源）。因此"改了 compose 但没效果"常见原因是 UI 里该参数被改过。需要环境变量接管时，先在 UI 中删除该自定义值。

Q3：手工清理数据库配置行出现"删了又回来"？

实测确认 bw-ui 进程会把内存中的配置态回写数据库（本篇第七节清理踩坑）。正确顺序：先 docker restart bunkerweb-1-6-16-ui（清内存），再清数据库行与 scheduler 的 /data/configs 镜像，最后重启 scheduler。日常运维直接用 UI 删除则无此问题。

Q4：低流量站点偶发 429？

检查限速插件默认值：use-limit-req 默认开启且 limit-req-rate 默认 2r/s（实测 bw_settings 回显）。内网监控类低流量请求可以调高速率或站点级 USE_LIMIT_REQ=no。

Q5：白名单 IP 仍被 403？

IP 白名单只放行 BunkerWeb 插件链，ModSecurity CRS 引擎独立执行（6.1 实测发现）。可信 IP 需要完全绕过 CRS 时，使用站点级 ModSecurity 设置（如 USE_MODSECURITY=no）或通过 crs_plugins_before 自定义配置添加 SecRuleRemoveById 白名单规则。

十、参考链接

官方文档 Settings（参数字典）：https://docs.bunkerweb.io/latest/settings/
官方文档 Advanced usages（Custom configurations 上下文与注入）：https://docs.bunkerweb.io/latest/advanced-usages/
官方文档 Integrations（API 安全组镜像配置要求）：https://docs.bunkerweb.io/latest/integrations/
GitHub Releases（v1.6.16）：https://github.com/bunkerity/bunkerweb/releases/tag/v1.6.16
系列文档：《BunkerWeb 1.6.16 介绍与选型指南》《BunkerWeb Docker Compose 部署指南》《BunkerWeb 安全加固指南》