BunkerWeb项目故障排查与问题解决指南

BunkerWeb项目故障排查与问题解决指南

bunkerweb 🛡️ Make your web services secure by default ! 项目地址: https://gitcode.com/gh_mirrors/bu/bunkerweb

前言

BunkerWeb作为一款现代化的Web应用防火墙和安全解决方案，在实际部署和使用过程中可能会遇到各种问题。本文将系统性地介绍BunkerWeb常见问题的排查方法和解决方案，帮助用户快速定位和解决问题。

日志分析：故障排查的第一步

日志是排查问题的关键工具，BunkerWeb提供了详细的日志记录功能。默认日志级别为notice，可以通过设置LOG_LEVEL=info来提高日志详细程度。

不同部署方式的日志查看方法

Docker环境

docker logs <容器名称>
# 或使用docker-compose
docker-compose logs <服务名称>

Kubernetes环境

kubectl logs <pod名称>

Linux原生安装

# 查看服务日志
journalctl -u bunkerweb --no-pager
# 访问常规日志
cat /var/log/bunkerweb/error.log
cat /var/log/bunkerweb/access.log

常见问题分类与解决方案

1. 权限问题

BunkerWeb出于安全考虑以非特权用户身份运行。当遇到权限问题时：

• 检查BunkerWeb使用的文件和目录权限
• 确保自定义配置至少具有：
  • 文件：读写权限(RW)
  • 目录：读写执行权限(RWX)

2. ModSecurity相关问题

BunkerWeb默认使用Core Rule Set(CRS)规则集，采用异常评分模式，默认异常阈值为5(请求)和4(响应)。

典型ModSecurity日志分析示例

日志通常包含三个部分：

1. 匹配的具体规则(如930120)
2. 匹配的其他规则(如932160)
3. 最终拒绝访问的规则(949110)

注意：949110是阈值规则，不应删除。如果出现误报，应调整触发的前置规则。

调整建议

• 修改异常评分阈值
• 调整规则敏感度(Paranoia Level)
• 添加自定义规则排除

3. IP封禁问题

临时解除IP封禁

需要启用API(USE_API=yes)后执行：

# Docker环境
docker exec <容器名称> bwcli unban <IP地址>
# Linux原生环境
sudo bwcli unban <IP地址>

预防误封

• 合理设置"不良行为"检测参数
• 为合法机器人添加白名单

4. 白名单配置最佳实践

对于需要特殊访问权限的客户端：

• 使用IP白名单(WHITELIST_IP)
• 避免使用URI或User-Agent白名单(除非值足够复杂)
• 常见白名单场景：
  • 健康检查机器人
  • 支付回调(如IPN)
  • 社交媒体爬虫

高级问题排查技巧

1. 临时禁用安全检查

调试时可临时添加全局白名单：

WHITELIST_IP=0.0.0.0/0

2. 时区问题处理

容器环境可能出现时区不一致问题，可通过设置环境变量解决：

TZ=Asia/Shanghai  # 设置为本地时区

3. Web UI问题处理

密码重置

1. 连接到数据库
2. 使用bcrypt生成新密码哈希
3. 更新数据库中的密码字段

2FA问题处理

• 可临时禁用管理员账户的2FA
• 或通过恢复代码重置

数据库操作指南

SQLite数据库操作

sqlite3 /var/lib/bunkerweb/db.sqlite3

常用SQL命令

-- 查看所有用户
SELECT * FROM bw_ui_users;

-- 重置管理员密码
UPDATE bw_ui_users SET password = '<哈希值>' WHERE admin = 1;

-- 禁用2FA
UPDATE bw_ui_users SET totp_secret = NULL WHERE admin = 1;

插件上传问题

可能遇到的问题：

1. 缺少压缩文件处理包
   • 解决方案：安装必要依赖(zip/unzip等)
2. Safari浏览器安全限制
   • 解决方案：调整浏览器安全设置

总结

本文详细介绍了BunkerWeb常见问题的排查方法和解决方案。通过系统性地分析日志、理解安全机制原理和掌握关键工具的使用，用户可以高效地解决大多数运行问题。对于复杂问题，建议分步骤排查，从日志分析入手，逐步验证各项配置。

bunkerweb 🛡️ Make your web services secure by default ! 项目地址: https://gitcode.com/gh_mirrors/bu/bunkerweb