1. 项目概述BunkerWeb配置参数全景解析如果你正在寻找一款集成了现代Web服务器、WAFWeb应用防火墙、反向代理和负载均衡器于一体的安全解决方案那么BunkerWeb绝对值得你花时间深入研究。它基于NGINX构建但通过模块化插件和丰富的配置参数将安全防护能力提升到了一个新的维度。今天我们不谈安装部署而是聚焦于其核心——配置参数。这些参数是BunkerWeb的灵魂从全局性能调优到细粒度的安全策略都依赖它们来定义。理解并熟练运用这些参数是让BunkerWeb从“能用”到“好用”甚至“强大”的关键一步。很多人在初次接触BunkerWeb时面对上百个配置项会感到无从下手。是应该先开启ModSecurity的严格模式还是先配置速率限制DNSBL和CrowdSec哪个更适合拦截恶意IP全局的USE_GZIP和站点级的CLIENT_CACHE_CONTROL又该如何协同工作这篇文章将为你系统性地拆解BunkerWeb的配置体系从全局基础设置到核心安全防护插件结合我多年的实战经验为你提供一份可直接“抄作业”的配置指南和避坑手册。无论你是负责保护一个简单的博客还是一个复杂的微服务API网关这篇文章都能帮你构建起清晰、有效的BunkerWeb配置思路。2. 全局与基础设置构建服务的基石在深入安全插件之前我们必须先打好地基。BunkerWeb的“杂项”Miscellaneous插件和“通用”General设置定义了Web服务最基础的行为和性能特征。这部分配置虽然不直接拦截攻击但决定了服务的稳定性、兼容性和可观测性。2.1 服务器行为与协议控制首先我们需要明确服务器如何响应请求。DISABLE_DEFAULT_SERVER这个参数至关重要。默认情况下如果一个HTTP请求的Host头不匹配任何配置的虚拟主机server_nameNGINX会使用第一个定义的server块即默认服务器来响应。这常被攻击者用于“虚拟主机扫描”或“请求走私”攻击。将DISABLE_DEFAULT_SERVER设置为yesBunkerWeb会为不匹配的请求返回444状态码NGINX特有直接关闭连接而不发送任何响应从而隐藏服务器指纹消除一个潜在的攻击面。与之配套的是DISABLE_DEFAULT_SERVER_STRICT_SNI。对于HTTPS连接服务器名称指示SNI扩展用于在握手早期指明目标主机名。启用此选项设为yes后BunkerWeb会拒绝任何不提供有效SNI的TLS连接。这进一步加强了安全性但需要注意如果你的BunkerWeb前面还有一层TLS终结代理如CDN且该代理不转发SNI信息那么启用此选项会导致所有HTTPS连接失败。在生产环境启用前务必在测试环境充分验证。接下来是HTTP方法控制。ALLOWED_METHODS参数允许你定义一个管道符|分隔的允许方法列表例如GET|POST|HEAD|OPTIONS。任何不在此列表中的HTTP方法请求都将收到405 Method Not Allowed响应。这是一个典型的最小权限原则应用。对于大多数Web应用GET、POST、HEAD用于获取资源头信息和OPTIONS用于CORS预检请求就足够了。务必不要将TRACE或CONNECT方法加入白名单它们极少被合法使用却可能被用于跨站追踪XST攻击或构造代理隧道。实操心得在配置ALLOWED_METHODS时我曾遇到一个坑。一个使用PATCH方法进行部分更新的RESTful API突然全部失败。排查后发现是全局配置中遗漏了PATCH。教训是在应用全局严格策略前务必梳理清楚所有后端服务实际使用的HTTP方法可以通过分析访问日志来确认。2.2 请求与连接管理资源限制是防止滥用和DoS攻击的第一道防线。MAX_CLIENT_SIZE定义了客户端请求体包括文件上传的最大尺寸默认是10m10兆字节。你可以使用k、m、g后缀。对于纯API服务可以设置得较小如1m对于文件上传服务则需要调大。切忌轻易设置为0无限制这会使服务器极易因一个巨大的请求体而耗尽内存。MAX_HEADERS限制每个请求的头部行数默认为100。过多的请求头可能是恶意客户端试图耗尽服务器资源的标志。保持默认值通常足够。现代协议支持能显著提升性能与安全。HTTP2和HTTP3参数默认均为yes建议保持开启。HTTP/2的多路复用、头部压缩等特性对性能提升明显。HTTP/3基于QUIC协议能更好地解决队头阻塞问题尤其是在高延迟网络中。但请注意NGINX对HTTP/3的支持仍标记为“实验性”。启用HTTP3后还需要设置HTTP3_ALT_SVC_PORT默认为443它会在响应头中告知客户端可通过该UDP端口访问HTTP/3服务。启用前务必在测试环境验证兼容性。2.3 静态文件服务与缓存优化SERVE_FILES和ROOT_FOLDER共同决定了BunkerWeb是否以及从哪里提供静态文件。当BunkerWeb作为纯粹的反向代理所有动态内容都由后端应用服务器处理时可以将SERVE_FILES设为no减少攻击面。如果需要提供静态资源如图片、CSS、JS则设为yes并通过ROOT_FOLDER指定路径。在多站点模式下ROOT_FOLDER支持变量{server_name}例如/var/www/html/{server_name}BunkerWeb会自动替换为当前站点的域名。性能优化离不开缓存。USE_OPEN_FILE_CACHE及相关参数提供了文件描述符缓存机制。当设置为yes时BunkerWeb会在内存中缓存打开文件的描述符和元数据如文件大小、修改时间。这对于提供大量小静态文件的站点性能提升巨大因为它避免了每次请求都进行耗时的stat()系统调用。OPEN_FILE_CACHE: 定义缓存行为如max1000 inactive20s表示最多缓存1000个条目20秒内未被访问的条目将被移除。OPEN_FILE_CACHE_ERRORS: 设为yes时连文件查找错误如文件不存在也会被缓存一段时间这可以防止攻击者通过反复请求不存在的文件来消耗系统资源一种时序攻击。OPEN_FILE_CACHE_MIN_USES: 文件在非活动期内被访问至少该次数才会被保留在缓存中。默认为2。OPEN_FILE_CACHE_VALID: 缓存条目被认为有效的时长超过后即使未过期也会重新验证。默认为30s。注意事项文件缓存对动态内容如PHP、代理传递的内容无效。它只作用于SERVE_FILES提供的静态文件。对于高动态性的站点开启缓存可能收益不大反而占用内存。建议根据实际场景决定。3. 核心安全防护插件深度配置安全是BunkerWeb的立身之本。其安全能力通过一系列插件实现每个插件都像一道关卡共同构建起纵深防御体系。3.1 ModSecurity与OWASP CRSWeb应用防火墙USE_MODSECURITY和USE_MODSECURITY_CRS是启用WAF的核心开关默认均为yes。OWASP核心规则集CRS是防御SQL注入、XSS、RCE等常见Web攻击的利器。版本与模式选择MODSECURITY_CRS_VERSION可选3稳定版v3.3.9或4稳定版v4.27.0默认。v4规则更先进误报可能更少建议新部署直接使用v4。MODSECURITY_SEC_RULE_ENGINE控制规则执行引擎On拦截并记录、DetectionOnly仅记录不拦截用于调试、Off关闭。上线初期可设为DetectionOnly观察日志无大量误报后再切换为On。请求体处理MODSECURITY_REQ_BODY_NO_FILES_LIMIT定义了不含文件上传的请求体大小限制默认为128KB131072。ModSecurity需要将请求体缓冲到内存中进行检测。如果应用涉及大JSON或XML payload的API需要适当调大此值例如1m1MB。但这里有一个关键陷阱对于专门用于文件上传的端点如/upload即使调大此参数ModSecurity处理数GB的文件仍可能导致工作进程内存溢出OOM。正确的做法是在该反向代理的location上使用REVERSE_PROXY_MODSECURITY_N: “no”来完全关闭ModSecurity检查。同时应配合文件扫描插件如ClamAV来检查已上传的文件内容实现安全与性能的平衡。偏执级别与排除项CRS有偏执级别Paranoia Level, PL概念从PL1到PL4严格度递增。默认是PL1误报最少。你可以在/etc/bunkerweb/configs/modsec-crs/目录下创建自定义配置文件来调整PL或添加排除项。例如为WordPress创建文件wordpress-exclusion.conf内容可以是CRS项目提供的预排除规则片段用以避免对wp-admin或wp-json等路径的误报。插件扩展USE_MODSECURITY_CRS_PLUGINS和MODSECURITY_CRS_PLUGINS允许你集成额外的规则集。例如MODSECURITY_CRS_PLUGINS: “wordpress-rule-exclusions fake-bot”会下载并启用针对WordPress的排除插件和一个模拟恶意爬虫检测的插件。这能让你在保持通用防护的同时获得更精准的针对特定应用的保护。3.2 访问控制黑白名单、灰名单与国家封锁这是基于客户端特征的访问控制层。黑白名单Whitelist/Blacklist概念直观。WHITELIST_IP和BLACKLIST_IP接受IP或CIDR格式用空格分隔。白名单优先级高于黑名单。一个常见的场景是将管理后台的IP段加入WHITELIST_IP同时用BLACKLIST_IP封禁已知的恶意IP。这些列表也支持通过*_URLS设置从远程URL或本地文件动态加载便于集中管理。灰名单Greylist这是一个非常实用的概念。USE_GREYLIST启用后只有匹配GREYLIST_*规则的访问者才能通过其他人一律拒绝。但通过灰名单的访问者仍然要接受其他所有安全检查如ModSecurity、速率限制。这相当于创建了一个“受监控的访问通道”。例如你可以将公司办公网IP段GREYLIST_IP、合作伙伴的ASN号GREYLIST_ASN或内部监控系统的User-AgentGREYLIST_USER_AGENT加入灰名单。这样内部流量可以畅通无阻但仍受WAF保护而外部未知流量则被完全屏蔽极大缩小了攻击面。国家封锁Country基于IP地理位置的封锁。WHITELIST_COUNTRY和BLACKLIST_COUNTRY支持ISO两位国家代码如US,CN和预定义分组如EU代表欧盟国家。例如一个仅面向国内用户的服务可以设置WHITELIST_COUNTRY: “CN”。分组功能很强大FIVE_EYES五眼联盟、ASEAN东盟等方便进行地缘策略配置。需要注意的是IP地理位置数据库并非100%准确且可能存在代理IP干扰因此不建议将其作为唯一的安全措施。3.3 实时威胁情报CrowdSec与DNSBL这两者都是利用外部情报来增强防护。CrowdSec这是一个基于行为的协同式安全引擎。USE_CROWDSEC启用后BunkerWeb会作为其“防暴器”bouncer向CrowdSec的本地APICROWDSEC_API查询每个来访IP是否有“决策”如封禁。决策来自CrowdSec分析你本地的日志如BunkerWeb的访问日志发现的攻击模式也来自其社区共享的威胁情报。集成步骤部署CrowdSec服务并配置其采集acquisition来解析BunkerWeb的日志/var/log/bunkerweb/access.log等。在CrowdSec中为BunkerWeb创建一个防暴器API密钥cscli bouncers add bunkerweb-bouncer。在BunkerWeb配置中设置USE_CROWDSEC: “yes”CROWDSEC_API: “http://crowdsec:8080”CROWDSEC_API_KEY: “生成的密钥”。可选启用应用安全组件CROWDSEC_APPSEC_URL: “http://crowdsec:7422”。这允许CrowdSec对请求体进行深度检查而不仅仅是IP信誉。操作模式CROWDSEC_MODE可选live实时查询延迟低但API压力大或stream流模式定期拉取决策列表到本地缓存查询快但更新有延迟。对于高流量站点stream模式是更佳选择你需要通过CROWDSEC_UPDATE_FREQUENCY默认10秒来平衡情报新鲜度与性能。DNSBLDNS黑名单通过查询外部DNSBL服务器如Spamhaus来判断客户端IP是否在已知的垃圾邮件或僵尸网络列表中。配置简单USE_DNSBL: “yes”DNSBL_LIST: “zen.spamhaus.org”。zen.spamhaus.org聚合了多个Spamhaus列表是常用的选择。由于需要发起DNS查询会引入少量延迟。可以通过DNSBL_IGNORE_IP和DNSBL_IGNORE_IP_URLS来排除受信任的IP避免误伤。经验之谈CrowdSec和DNSBL可以叠加使用但要注意逻辑。CrowdSec更侧重于行为分析能发现本地独有的攻击模式DNSBL则是基于IP声誉的全局名单。我的建议是对于面向公众的服务可以同时开启利用CrowdSec的社区情报和DNSBL的垃圾邮件IP库。对于内部或API网关可能更依赖CrowdSec分析业务日志产生的决策。务必监控被阻止的日志确认是否有误封。3.4 速率与连接限制Limit这是防止滥用和DDoS攻击的基础手段。USE_LIMIT_REQ和USE_LIMIT_CONN分别控制请求速率和并发连接。请求速率限制LIMIT_REQ_URL定义应用此规则的URL路径PCRE正则LIMIT_REQ_RATE定义速率格式为Nr/t如5r/s每秒5次、100r/m每分钟100次。你可以为不同路径设置不同规则。例如对登录接口^/api/login可以设置严格的2r/s而对公开的API文档^/docs可以设置宽松的30r/s。BunkerWeb使用“漏桶”算法进行限流超出限制的请求会收到429 Too Many Requests响应。连接限制限制单个IP的并发连接数针对不同协议LIMIT_CONN_MAX_HTTP1: 每个IP的HTTP/1.x并发连接数默认10。LIMIT_CONN_MAX_HTTP2: 每个IP的HTTP/2并发流数默认100。注意一个HTTP/2连接可以包含多个流。LIMIT_CONN_MAX_HTTP3: 每个IP的HTTP/3并发流数默认100。LIMIT_CONN_MAX_STREAM: 每个IP的TCP/UDP流连接数默认10用于非HTTP服务。配置要点对于API网关连接数可以设小一些因为HTTP/2/3的多路复用特性使得单个连接就能处理大量请求。对于传统Web应用可能需要根据会话特性调整。设置过低会影响用户体验过高则可能无法起到防护作用。最佳实践是通过监控日志观察正常用户和恶意攻击的连接模式再逐步调整到一个合理的阈值。4. 性能、缓存与高级功能配置安全与性能需要兼顾。BunkerWeb提供了丰富的性能优化和高级功能配置。4.1 内容传输优化Gzip与客户端缓存Gzip压缩USE_GZIP: “yes”即可启用。关键参数是GZIP_COMP_LEVEL1-9默认5在压缩率和CPU消耗间取得了平衡。对于几乎不变的静态资源如jQuery库可以设置为9追求极致压缩对于动态生成的API响应设置为1或2以减少服务器CPU压力。GZIP_TYPES定义了哪些MIME类型需要压缩默认列表已包含text/htmltext/cssapplication/javascript等。确保不要压缩已经是压缩格式的图片如jpg png。客户端缓存通过USE_CLIENT_CACHE启用。它通过设置Cache-Control和ETag响应头指示浏览器缓存静态资源。CLIENT_CACHE_EXTENSIONS: 定义需要缓存的静态文件扩展名如jpg|jpeg|png|css|js。CLIENT_CACHE_CONTROL: 缓存控制指令如public max-age31536000 immutable。max-age定义缓存有效期秒immutable告诉浏览器该资源永不变更非常适合带版本哈希的文件名如main.a1b2c3.css。CLIENT_CACHE_ETAG: 是否启用ETag验证。实战配置对于版本化的前端资源采用激进缓存策略USE_CLIENT_CACHE: “yes” CLIENT_CACHE_EXTENSIONS: “css|js|woff|woff2|svg” CLIENT_CACHE_CONTROL: “public max-age31536000 immutable”对于频繁更新的资源如用户头像则采用较短缓存或禁用缓存CLIENT_CACHE_EXTENSIONS: “jpg|jpeg|png” CLIENT_CACHE_CONTROL: “public max-age3600”4.2 安全头部Headers与CORS安全头部是低成本高收益的安全加固手段。Headers插件帮你一键配置。STRICT_TRANSPORT_SECURITY: HSTS头强制浏览器使用HTTPS。建议值max-age63072000; includeSubDomains; preload。一旦设置浏览器在有效期内只会通过HTTPS访问该域名及其子域名。CONTENT_SECURITY_POLICY: CSP头用于防止XSS。配置需要谨慎错误的策略会破坏网站功能。初期可以使用CONTENT_SECURITY_POLICY_REPORT_ONLY: “yes”启用仅报告模式在浏览器控制台观察违规报告而不实际拦截待策略稳定后再关闭报告模式。X_FRAME_OPTIONS: 防止点击劫持设为SAMEORIGIN或DENY。X_CONTENT_TYPE_OPTIONS:nosniff阻止浏览器MIME类型嗅探。REFERRER_POLICY: 控制Referer头信息保护用户隐私如strict-origin-when-cross-origin。REMOVE_HEADERS: 移除可能泄露服务器信息的头如ServerX-Powered-By。CORS跨源资源共享当你的前端https://app.example.com需要访问后端APIhttps://api.example.com时需要配置CORS。USE_CORS: “yes”CORS_ALLOW_ORIGIN: 允许的源可以是*任何源不安全self同源或PCRE正则如^https://(.\.)?example\.com$允许example.com及其所有子域名。CORS_ALLOW_METHODS: 允许的HTTP方法如GET POST OPTIONS。CORS_ALLOW_CREDENTIALS: 是否允许携带Cookie等凭据。如果设为yes则CORS_ALLOW_ORIGIN不能为*必须指定具体域名。CORS_MAX_AGE: 预检请求OPTIONS结果的缓存时间减少重复预检。4.3 SSL/TLS与证书管理自定义SSL证书如果你已有CA签发的证书可以使用Custom SSL certificate插件。USE_CUSTOM_SSL: “yes”CUSTOM_SSL_CERT_PRIORITY:file优先使用文件路径或data优先使用Base64编码数据。CUSTOM_SSL_CERT/CUSTOM_SSL_KEY: 证书和私钥的文件路径。或者使用CUSTOM_SSL_CERT_DATA/CUSTOM_SSL_KEY_DATA直接提供PEM格式的内容。自动化Let‘s Encrypt对于自动化证书管理Let‘s Encrypt插件是首选。AUTO_LETS_ENCRYPT: “yes”EMAIL_LETS_ENCRYPT: 接收证书到期提醒的邮箱重要。LETS_ENCRYPT_CHALLENGE: 验证方式http需要在80端口放置验证文件或dns需要通过DNS提供商API添加TXT记录。http方式最简单但要求80端口可公开访问。dns方式更通用支持通配符证书USE_LETS_ENCRYPT_WILDCARD: “yes”但需要配置DNS提供商API密钥通过LETS_ENCRYPT_DNS_CREDENTIAL_ITEM设置。USE_LETS_ENCRYPT_STAGING: 测试时设为yes使用Let‘s Encrypt的测试环境避免触发生产环境的速率限制。4.4 数据库、指标与自定义页面数据库集成Database插件支持SQLite默认、PostgreSQL、MySQL等用于集中存储配置、作业日志等。对于单机部署SQLite足够。对于多实例集群需要使用如PostgreSQL这样的网络数据库通过DATABASE_URI配置连接。这确保了所有实例的配置同步和日志集中。指标监控Metrics插件默认启用USE_METRICS: “yes”收集被阻止请求、性能指标等数据。这些数据可以通过Web UI查看或通过/metricsAPI端点需配置USE_API以JSON格式获取方便集成到Prometheus等监控系统。METRICS_MAX_BLOCKED_REQUESTS控制每个工作进程内存中保存的被阻止请求数量可根据流量调整。自定义错误与反机器人页面Custom PagesPRO版功能和Errors插件允许你替换BunkerWeb默认的错误页、验证码页等使其与你的网站风格一致。例如通过CUSTOM_ERROR_PAGE指定一个自定义的404页面模板提升用户体验。5. 高级场景与排错指南5.1 多站点与反向代理配置BunkerWeb的强大之处在于其多站点Multisite能力。通过设置MULTISITE: “yes”并利用SERVER_NAME变量可以在一套实例上承载数十上百个域名。每个站点的配置可以通过环境变量前缀、或通过调度器Scheduler的数据库进行管理。反向代理是核心功能。配置通常如下SERVER_NAME: api.example.com USE_REVERSE_PROXY: “yes” REVERSE_PROXY_HOST: “http://backend-app:8080” REVERSE_PROXY_URL: “/”你可以配置多个上游REVERSE_PROXY_HOST_2REVERSE_PROXY_URL_2实现简单的路由。对于更复杂的负载均衡可以使用Load BalancerPRO插件定义上游服务器组和健康检查。5.2 常见问题与排查技巧配置不生效检查配置作用域确认参数是设置在global全局、multisite多站点还是server特定站点上下文。错误的上下文会导致配置被忽略。查看调度器日志BunkerWeb Scheduler负责生成最终配置。查看其日志docker logs bunkerweb-scheduler或journalctl -u bunkerweb-scheduler是否有错误特别是“configuration successfully generated”的提示。手动重载在修改配置后需要触发BunkerWeb重载。在Docker环境下通常调度器会自动完成。也可以手动向调度器API发送重载请求。误报False Positive太多ModSecurity误报首先将MODSECURITY_SEC_RULE_ENGINE设为DetectionOnly观察日志中触发的规则ID如942100。然后到OWASP CRS的排除项仓库或对应插件的文档中寻找针对你所用技术栈如WordPress Drupal的预定义排除规则通过modsec-crs自定义配置加载。CrowdSec误封在CrowdSec控制台查看决策来源。如果是本地场景local触发的可以调整该场景的阈值或直接禁用该场景。如果是社区列表如crowdsecurity/http-cve可以考虑将该列表从你的CrowdSec配置中移除。性能问题检查活动连接数使用ss或netstat命令查看BunkerWeb工作进程的连接状态。如果LIMIT_CONN_MAX_HTTP1设置过低可能导致正常用户无法连接。监控工作进程内存过大的MODSECURITY_REQ_BODY_NO_FILES_LIMIT或过多的缓存条目METRICS_MAX_BLOCKED_REQUESTS可能导致内存增长。使用top或htop观察进程RES内存使用情况。调整工作进程数通过WORKER_PROCESSES全局设置调整NGINX工作进程数量通常设置为与CPU核心数相等或2倍。证书问题Let‘s Encrypt申请失败首先检查USE_LETS_ENCRYPT_STAGING: “yes”在测试环境是否成功。如果失败查看BunkerWeb日志中Certbot的详细输出。常见原因DNS解析不正确、80/443端口被防火墙阻挡、域名验证文件无法被Let‘s Encrypt访问。自定义证书不加载确保CUSTOM_SSL_CERT_PRIORITY设置正确并且证书和密钥文件的路径在Scheduler容器内可读且是有效的PEM格式。可以尝试在容器内用openssl x509 -in /path/to/cert.pem -text -noout命令验证证书。5.3 配置管理与版本控制对于生产环境强烈建议将BunkerWeb的配置进行版本控制。可以将所有环境变量整理到一个.env文件或Kubernetes ConfigMap中。对于通过调度器数据库管理的配置定期导出数据库快照。对于自定义的ModSecurity规则、错误页面HTML文件等也应纳入Git等版本控制系统。这样可以在出现问题时快速回滚也便于在多个环境开发、测试、生产间保持配置一致性。最后安全配置是一个持续的过程而非一劳永逸。定期审查BunkerWeb的访问日志、错误日志和安全事件日志关注被阻止的请求分析攻击趋势并据此调整你的安全策略。例如如果发现大量针对某个特定API路径的慢速攻击可以单独为该路径设置更严格的LIMIT_REQ_RATE。通过持续观察和调整你的BunkerWeb配置才会越来越精准和强大。