这次我们来看一个能直接落地到生产的开源 WAF/WAAP 项目BunkerWeb。它不只是一个简单的防火墙规则引擎而是把 Nginx、ModSecurity、OWASP CRS、IP 封禁、限流、反爬、可视化 UI 和 API 都整合到了一个 Docker 服务里。换句话说你的 Web 服务前面加一层 BunkerWeb等于在入口处多了一道比较完整的应用安全防线。BunkerWeb 的核心卖点可以概括为五条基于 Nginx 构建兼容常见反向代理场景默认集成 ModSecurity 和 OWASP Core Rule SetCRS开箱能拦截大部分常见 Web 攻击支持通过环境变量、UI 控制台和 API 三种方式配置可以单机部署也可以组成集群统一管理对硬件要求不高不需要 GPU普通 2GB 内存的服务器就能跑起来。这意味着它很适合中小团队、个人站长、开发自测环境以及需要满足日志留存和访问控制要求的业务系统。这篇文章我会按“部署 - 启动 - 功能验证 - API 集成 - 问题排查”的路径带大家完整跑通 BunkerWeb。你会看到如何用 Docker Compose 快速拉起服务如何登录内置 UI如何用 curl 验证 WAF 规则是否生效如何通过 API 做自动化配置以及遇到误伤、端口冲突、API 鉴权失败时该怎么处理。如果你正在评估自建 WAF 还是商用 WAF这篇文章也能给你一份很具体的参考。1. 核心能力速览在动手部署之前先看一张规格表把 BunkerWeb 的能力边界说清楚。能力项说明项目类型开源 Web 应用防火墙WAF与 API 保护平台WAAP技术底座Nginx ModSecurity OWASP Core Rule SetCRS开源情况开源项目代码托管在 GitHub具体协议以仓库 LICENSE 为准主要功能SQL 注入与 XSS 拦截、路径访问控制、IP 黑白名单、限流、反爬虫、HTTP 安全头、基础认证、多站点管理部署方式Docker / Docker Compose支持单机与集群模式管理界面内置 Web UI浏览器访问即可完成配置、日志查看和实例管理API 能力提供配置读取与修改的 API适合自动化运维和批量操作硬件要求不需要 GPU建议内存 2GB 以上磁盘按日志量规划端口要求默认监听 HTTP/HTTPS 端口UI 与 API 使用独立端口具体端口可在 Compose 中映射日志能力支持访问日志、攻击审计日志可对接外部日志平台适合场景个人站点防护、企业多站点网关、API 服务前置防护、等保合规日志留存、安全测试验证环境从这张表能看出来BunkerWeb 的定位很明确用容器化方式把 Web 安全能力标准化。你不需要自己折腾 ModSecurity 规则怎么引入也不需要手动写一堆 Nginx 防护片段装好镜像、填好环境变量核心防护就有了。有一点需要提前说明BunkerWeb 和市场上常见的商业 WAF 相比优势在于透明可定制、日志可控、规则可调但它不替代代码层的安全开发也不能保证拦截所有攻击。把它理解为一个“默认安全基线 可编程策略”的入口网关更合适。2. 适用场景与使用边界先回答“适不适合我用”这个问题。如果你属于下面几类情况BunkerWeb 值得优先考虑个人或小团队运营了多个 Web 服务之前靠裸 Nginx 反代想统一加一层 WAF 能力又不想买商业 WAF。公司内部有测试环境、预发环境或对外提供 API 服务需要基础的攻击拦截、IP 封禁和访问频率控制。运维或安全人员需要一套可编程的 WAF 配置体系希望通过 API 批量修改站点策略而不是每次手动登录控制台。业务有日志留存和访问审计要求希望把 Nginx 层访问日志、WAF 拦截日志统一收集方便追溯。反过来BunkerWeb 不适合的场景也要说清楚。第一你的业务已经重度依赖 Nginx 原生模块比如自定义的负载均衡逻辑、特殊的上游协议、深度修改的 header 处理迁移到 BunkerWeb 需要额外评估兼容性。虽然 BunkerWeb 本身是 Nginx 内核但它的配置生成方式是标准化的自定义空间比纯手写 Nginx conf 要小。第二你的业务属于超大规模流量入口对转发性能有极致要求BunkerWeb 默认带 ModSecurity 和 CRS 规则开启全部检测会带来额外开销。这时候要先做压测再决定是开启全部规则还是做规则裁剪。第三你没有规则调优的耐心。WAF 上线后最怕误伤正常业务CRS 规则集在默认模式下可能拦截某些包含攻击特征但实际无恶意的请求。如果业务方不愿意配合加白名单、改规则WAF 上线会非常痛苦。安全边界这部分必须单独强调。BunkerWeb 是防护工具不是攻击工具。部署后建议先在自己的测试站点上验证规则不要对未授权的第三方网站做任何安全测试。涉及用户数据、Cookie、个人信息的流量要注意日志脱敏和访问权限控制。另外WAF 拦截绕过是一个真实存在的风险攻击者可能通过编码变形、分块传输、业务逻辑漏洞绕过规则所以核心安全还是要在应用代码层面做好输入校验和权限控制。3. 本地部署环境准备与前置条件BunkerWeb 是纯 CPU/内存型服务不涉及 GPU所以显存这个话题可以直接跳过。你只需要准备一台 Linux 服务器或虚拟机甚至本地开发机上的 Docker 环境都可以。最低硬件建议内存至少 2GB。BunkerWeb 容器内包含 Nginx 主服务、配置同步服务、日志处理服务和 UI 服务空闲时内存占用通常在几百 MB 到 1GB 左右实际以镜像版本和配置项多少为准。CPU 分配 1 到 2 核即可。流量大的场景需要多核并开启 Nginx worker 调优。磁盘按日志量规划。WAF 审计日志会持续增长建议单独挂载数据目录方便清理和导出。操作系统方面Debian、Ubuntu、CentOS 或国产化 Linux 发行版都可以前提是能正常安装 Docker 和 Docker Compose。你还需要确认下面几个前置条件Docker 20.10 以上版本Docker Compose v2 插件。服务器防火墙或安全组放行需要用到的端口HTTP 80、HTTPS 443以及 UI/API 端口 7000。域名解析可选。如果你需要测试 HTTPS 证书签发必须准备域名并把 A 记录指向服务器如果只是内网测试用 IP 访问也完全可以。在动手之前先跑一遍环境检查命令# 检查 Docker 版本 docker --version # 检查 Docker Compose 版本 docker compose version # 检查端口占用情况 ss -lntp | grep -E :(80|443|7000)\b如果 80 或 443 已经被其他服务占用请先处理冲突或者把 BunkerWeb 的端口映射改成 8080、8443否则启动后容器会直接失败。BunkerWeb 容器内部默认监听 8080 和 8443外部端口由 Docker 映射决定这也是很多使用者容易忽略的地方。4. 安装部署与启动方式BunkerWeb 最常见的部署方式是 Docker Compose。下面给出一套最小可运行配置适用于单机单站点场景。在服务器上创建项目目录写入docker-compose.ymlservices: bunkerweb: image: bunkerity/bunkerweb:latest ports: - 80:8080 - 443:8443 - 7000:7000 environment: SERVER_NAME: www.example.com MULTISITE: yes USE_BUNKERWEB_UI: yes USE_MODSECURITY: yes MODSECURITY_CRS: yes volumes: - ./data:/data restart: unless-stopped这个配置说明几点SERVER_NAME是你想要保护的站点域名也可以填localhost或 IP 做测试。MULTISITEyes表示启用多站点模式之后可以同时管理多个域名。USE_BUNKERWEB_UIyes会启动内置管理界面。USE_MODSECURITYyes与MODSECURITY_CRSyes表示开启 ModSecurity 并加载 OWASP CRS 规则集。./data:/data用于持久化配置、缓存和日志建议一定挂载。启动命令docker compose up -d启动后先看容器状态docker compose ps如果状态是Up说明容器已经正常运行。再检查日志确认没有报错docker compose logs -f --tail100之后打开浏览器访问http://服务器IP:7000应该能看到 BunkerWeb 的管理界面。首次登录需要根据界面提示完成管理员账号初始化这一步做完整个部署就结束了。如果你的服务器已经有 80 或 443 端口被占可以在ports里改成自定义映射例如8080:8080、8443:8443。BunkerWeb 内部并不强制要求宿主端口必须为 80只要外部访问路径和容器端口对应即可。5. 功能测试与效果验证服务跑起来之后我们要验证的不是“界面能不能打开”而是“WAF 规则到底拦不拦得住攻击 payload”。下面这套验证流程可以在你自己控制的测试站点上进行千万不要对未授权的目标做安全测试。5.1 验证站点访问先确认 Nginx 入口正常。假设你映射的是80:8080直接请求服务器 IP 或测试域名curl -I http://127.0.0.1正常情况下你会看到 Nginx 返回的HTTP/1.1 200 OK或301/302重定向说明站点入口通了。5.2 SQL 注入拦截测试BunkerWeb 默认加载 OWASP CRSSQL 注入是 CRS 重点检测的攻击类型。可以用一个常见的测试 payloadcurl -v http://127.0.0.1/?id1%20OR%2011预期结果是返回403 Forbidden或406 Not Acceptable响应体里通常会有 ModSecurity 的拦截提示。如果返回 200 和正常业务内容说明 WAF 规则没有生效或 payload 被解码后未命中规则。要注意URL 中的单引号和空格需要编码否则 curl 可能解析失败。上面示例已经用了%20代替空格。5.3 XSS 拦截测试跨站脚本XSS同样在 CRS 覆盖范围内测试命令curl -v http://127.0.0.1/?qscriptalert(1)/script这里建议把和做 URL 编码更稳妥curl -v http://127.0.0.1/?q%3Cscript%3Ealert(1)%3C/script%3E预期结果同样是 403 或 406响应内容会显示请求被 WAF 拒绝。如果返回 200请检查 ModSecurity 是否启用、CRS 是否加载以及测试 payload 是否被浏览器或 curl 自动转义。5.4 限流功能测试Limiting 是 WAF 的另一个重要功能。默认情况下 BunkerWeb 没有对全局限流做强制要求但你可以通过配置开启。这里先用一组高频请求查看默认状态下的行为for i in $(seq 1 20); do curl -s -o /dev/null -w %{http_code}\n http://127.0.0.1/ done如果你在配置中启用了限流规则并设置了频率超过阈值的请求会返回 503 Service Unavailable。如果没配置限流看到 200 是正常的。限流配置通常需要指定 URL 和速率例如USE_LIMIT_REQ: yes LIMIT_REQ_URL: /api LIMIT_REQ_RATE: 10r/s意思是/api路径每秒最多允许 10 个请求超过则拒绝。这类参数会在后续版本的管理界面里有更直观的选项但通过环境变量配置是最快的方式。5.5 IP 封禁测试IP 黑白名单是 WAF 的常规能力。在 BunkerWeb 中可以通过环境变量或者 UI 添加封禁 IP例如把203.0.113.10封禁之后用该来源 IP 访问时会直接被拒。测试时可以先把本机出口 IP 加进黑名单再用 curl 访问预期结果是 403测试完记得删除避免影响后续操作。如果你的办公环境使用动态出口 IP做这个测试前要确认 IP 能换否则封错了会影响自己访问。5.6 查看拦截日志WAF 拦截不是玄学每条拦截记录都应该能在日志里找到。BunkerWeb 的容器日志和审计日志都会记录拦截原因。查看容器日志docker logs bunkerweb --tail50如果你挂载了./data目录WAF 审计日志和访问日志也会落在数据目录中。通过查看日志中的攻击规则 ID、匹配目标和请求路径可以确认这次拦截到底命中了哪条规则。6. 接口 API 与自动化配置BunkerWeb 的一大优势是支持 API 配置。这意味着你可以把 WAF 策略纳入自动化运维体系批量修改站点、封禁 IP、查看配置而不是每次都在 UI 上手动点。6.1 开启 API在docker-compose.yml的 environment 中加入USE_API: yes API_HTTP_PORT: 7000然后在容器内或浏览器中访问http://127.0.0.1:7000/api检查 API 信息。如果 API 未开启或端口映射不对请求会超时或返回 404。API 默认有鉴权机制需要提供 API key 才能在管理界面或脚本中调用。你需要在 UI 中生成 API token或者通过环境变量设置初始 token。调用时在请求头中带上认证信息。6.2 获取当前配置一个典型的 API 请求示例curl -H Authorization: Bearer YOUR_API_TOKEN \ http://127.0.0.1:7000/api/config返回内容通常是 JSON 格式包含当前 BunkerWeb 实例的全部配置项。注意不同版本的 API 路径可能不同这里的/api/config是常见路径实际操作时以项目文档或 UI 中的 API 说明为准。6.3 通过 API 修改配置API 修改配置的通用思路是读取当前配置 - 修改目标字段 - 提交配置 - 等待 BunkerWeb 重新生成 Nginx 配置并 reload。伪代码如下curl -X POST \ -H Authorization: Bearer YOUR_API_TOKEN \ -H Content-Type: application/json \ -d {config: {USE_BLACKLIST: yes, BLACKLIST_IP: 203.0.113.10}} \ http://127.0.0.1:7000/api/config如果 API 设计有专门的配置更新接口提交后会返回任务 ID你可以通过该 ID 查询生效状态。提交失败时重点检查 JSON 格式、字段名和鉴权 token 是否过期。6.4 批量任务脚本思路API 的真正价值在于批量任务。比如运营同学反馈某个网段频繁扫描你想一键封禁一万个 IP手工在 UI 里操作是不现实的。写一个脚本循环调用 API 是更合理的做法import requests API_URL http://127.0.0.1:7000/api/config HEADERS { Authorization: Bearer YOUR_API_TOKEN, Content-Type: application/json } block_ips [ 203.0.113.10, 203.0.113.11, 203.0.113.12 ] for ip in block_ips: payload { config: { BLACKLIST_IP: ip } } try: resp requests.post(API_URL, jsonpayload, headersHEADERS, timeout10) print(ip, resp.status_code, resp.text) except Exception as e: print(ip, request error, e)这个脚本只是一个批量操作的思路实际字段和提交方式需要按你当前 BunkerWeb 版本的 API 文档调整。核心要点是批量任务要对每个请求做状态记录失败的要重试重试仍失败的要把 IP 单独保存方便人工处理。6.5 集群与多实例配置如果你跑的是多台服务器组成的集群BunkerWeb 支持通过共享数据库或协调服务将多个实例统一管理。这样你在一个控制台修改配置其他节点会自动同步。集群模式下 API 和 UI 的地址规划会变化部署前建议先读官方集群文档把网络策略和存储依赖梳理清楚。7. 资源占用与性能观察BunkerWeb 的日常资源观察不需要 GPU重点看 CPU、内存、磁盘和 Nginx 连接数。7.1 容器监控启动后执行docker stats --format table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}可以看到 BunkerWeb 容器的 CPU 使用率和内存占用。空闲状态下容器内多个进程共享内存内存占用通常在几百 MB 到 1GB 之间这个数字受镜像版本、开启功能数量、日志缓冲大小影响。没有标准答案最好的办法是在自己的环境里观察一个稳定期的均值。7.2 性能影响因素是否开启 ModSecurity 和 CRS 全量规则检测越全面CPU 开销越高。请求体大小上传大文件时WAF 需要对 body 做缓冲和检测内存占用会上升。并发连接数Nginx 的 worker 数、keepalive 设置会影响 CPU 占用。日志级别debug 级别日志会显著增加 CPU 和磁盘开销生产环境建议用 info 或 warning。反爬虫和限流策略如果启用了 JS 挑战或验证码对用户体验和服务器开销都有影响。7.3 降低占用、提升稳定性第一次部署先关闭 CRS 里的部分高开销规则观察业务正常后再逐步开启。合理设置client_max_body_size避免超大请求体砸到 WAF 上。日志输出到单独磁盘或外部日志平台避免本地日志膨胀打满根分区。在多核服务器上调整 Nginx worker 数量但不要超过 CPU 核数太多。定期检查容器日志是否有大量 4xx 攻击请求导致日志量暴增如果有考虑加 IP 封禁和限流。8. 常见问题与排查方法实际使用中下面几个问题出现频率最高我把排查思路整理成一张表。问题现象可能原因排查方式解决方案UI 页面打不开安全组未放行 7000 端口或端口映射错误检查防火墙、安全组、docker compose ps放行 7000 端口检查 ports 映射80 端口启动失败宿主已有服务占用 80 端口ss -lntp | grep :80换映射端口或停掉占用进程访问站点返回 502上游 Web 服务不可达或配置错误查看容器日志检查反代目标地址修正上游地址和端口SQL/XSS 测试未被拦截ModSecurity 未开启、CRS 未加载或 payload 被编码检查环境变量和日志确认 USE_MODSECURITYyes、MODSECURITY_CRSyes正常用户被拦截CRS 规则误伤或本地 IP 被误封查看审计日志中的规则 ID加白名单或临时关闭对应规则API 返回 401token 错误或 API 未开启检查鉴权字段重新生成 token在 UI 中创建新的 API token日志不产生数据目录未挂载或日志级别为 none检查 volumes 和日志配置挂载 /data 目录调整日志级别批量任务卡住单个请求超时或 API 并发限制查看脚本日志增加超时时间分批执行失败重试值得单独提一下“waf 绕过”的问题。你在测试时可能发现某些编码后的 payload 没有触发拦截这不一定是工具不行更常见的原因是OWASP CRS 版本过低、规则被手动关闭、请求体经过多次编码导致规则未匹配、或者攻击链路发生在业务逻辑层而不是请求特征层。正确做法是先把审计日志打开记录下没拦截的请求再分析是规则覆盖问题还是业务逻辑问题。不要一上来就怀疑 WAF 失效也不要本末倒置地去追求“绕过技巧”。安全防护是分层设计WAF 只承担其中一环。9. 最佳实践与使用建议如果你决定把 BunkerWeb 用到真实业务里下面这几条建议值得保留。第一先小流量试运行。不要把 WAF 直接全量接入线上先在测试环境跑几天观察 CRS 规则是否误伤正常业务。上线时可以先设置为“仅记录”模式让 WAF 对攻击请求只记录不拦截等规则和业务对齐后再切换到“拦截”模式。第二维护好白名单。搜索引擎爬虫、支付回调、运维监控探针、办公网出口 IP 都可能被 CRS 误杀。把这些来源提前加入白名单能显著降低上线后的投诉量。第三数据目录和日志要“外置”。BunkerWeb 容器随时可能更新或重建配置、缓存、日志都要挂载到宿主机目录。日志要定期归档有条件就接入 Elasticsearch 或第三方日志平台方便告警和溯源。如果业务有等保合规要求WAF 日志留存时间要按规范设置不能只放在容器里随容器销毁。第四API 访问限制。BunkerWeb 的 API 拥有修改 WAF 配置的能力如果暴露到公网等于把安全产品本身变成了攻击面。建议 API 端口只在内网开放或者通过安全组限制来源 IP不要直接用 0.0.0.0 暴露到公网。第五镜像和规则要更新。OWASP CRS 会持续更新规则库BunkerWeb 镜像也会修复 bug。建议制定更新周期先拉新镜像到测试环境验证再升级生产。升级前备份配置和数据目录。第六不要依赖单一防御点。BunkerWeb 可以拦截大量自动化攻击但业务逻辑漏洞、越权访问、账号安全等问题需要应用代码层面配合解决。安全水位网络层应用层运维层的综合结果。10. 总结与下一步BunkerWeb 最值得尝试的点在于它把“部署一个 WAF”这件事真正简化到了 Docker Compose 级别同时在能力上没有砍掉 WAAP 的核心内容。你不需要先学会配置 Nginx 安全模块也不需要手工同步 ModSecurity 规则装好镜像后默认的 CRS 规则就能帮你挡住一批常见攻击。第一次部署建议优先验证三件事一是默认 CRS 规则能否拦截 SQL 注入和 XSS二是多站点模式下能否同时代理两个域名三是 UI 和 API 是否满足你的配置习惯。这三项通了BunkerWeb 的基本价值你就已经拿到手了。最容易踩的坑其实就是端口和防火墙。部署文档看得再多安全组没放行 7000 端口UI 照样打不开宿主机 80 端口被占容器照样起不来。动手之前花两分钟检查端口能省掉后面大量排查时间。后续可以继续扩展的方向不少接入 CrowdSec 做威胁情报联动用集群模式统一管理一批边缘节点把 WAF 审计日志接入日志分析平台做自动化告警甚至根据自己的业务场景编写自定义规则。对开源 WAF 来说真正的工作不是安装而是把规则、日志、告警和业务适配好。建议先把这套流程跑通再逐步深入。