## 什么是 Bach Dang WAF？ Bach Dang WAF 是一个用于 Nginx 和 ModSecurity 的**自托管管理控制台**。它通过简洁的 Web 界面替代了基于 SSH 的配置编辑：在一个地方管理域名、SSL 证书、IP 访问策略、ModSecurity 规则、告警阈值以及集群副本节点。 适用于： - **实验室和教育** — 通过真实的管理 UI 学习 WAF、Nginx 和 ModSecurity - **DevOps / SRE 团队** — 在现有 Nginx 基础设施之上提供可视化管理层 - **安全工程师** — 细粒度的 ModSecurity 规则控制，无需 SaaS 定价 - **VMware 和家庭实验室** — 零许可成本的企业级 WAF - **本地部署** — 完全自托管，无遥测，无外部依赖 ## 功能 ### 流量防护 - 带有严重性分类的 WAF 事件日志：PASS / ALERT / BLOCK - IP 防火墙 — 支持 CIDR 的允许/拒绝列表以及 JSON 导入/导出 - ModSecurity 集成 OWASP CRS，支持逐规则启用/禁用及自定义规则编辑器 ### 基础设施 - 域名管理及上游服务器配置 - SSL/TLS — 手动上传、Let's Encrypt ACME、自动续期跟踪 - 带有健康检查监控的负载均衡上游池 - 副本节点管理 — 将配置从控制器同步到副本 WAF 节点 ### 可观测性 - 实时仪表板：每秒请求数、带宽、错误率、威胁事件、地理位置地图 - 性能指标：CPU、内存、磁盘、连接池、nginx worker 统计 - 带有可配置规则、阈值和严重性级别的告警引擎 - 带有定时配置快照的备份和恢复 - 包含完整操作员操作历史的审计日志 ### 访问控制 | 角色 | 权限 | |------|-------------| | Admin | 完全访问权限：系统配置、用户管理、所有 WAF 控制 | | Operator | WAF 管理、域名、告警 — 无用户管理权限 | | Observer | 只读：仪表板、日志、指标 | 身份验证：JWT access + refresh token、bcrypt、基于 TOTP 的 2FA ## 架构 ``` ┌───────────────────────────────────────────────────────┐ │ Browser / Operator │ └────────────────────────┬──────────────────────────────┘ │ HTTP :8080 ┌────────────────────────▼──────────────────────────────┐ │ Nginx – Management Console │ │ Serves React SPA + proxies /api → :3001 │ └───────────────┬───────────────────────────────────────┘ │ :3001 (internal only) ┌───────────────▼──────────────┐ ┌─────────────────────┐ │ Express + Prisma API │ │ Nginx + ModSecurity │ │ Auth, WAF mgmt, Alerting │ │ Traffic proxy :80/443│ └───────────────┬───────────────┘ └─────────────────────┘ │ ┌───────────────▼───────────────┐ │ PostgreSQL 16 │ └───────────────────────────────┘ ``` 设计原则： - 管理控制台 (`:8080`) 和 WAF 代理 (`:80`/`:443`) 是隔离的进程。控制台的配置错误不会中断实时流量。 - 所有 API 调用使用相对 `/api` 路径 — 构建中不硬编码任何 IP。无需重新构建即可在任何地址上运行。 - 后端 API 永不暴露于互联网。Nginx 在内部代理 `/api`。 ## 快速开始 ### 一键安装 (Ubuntu 22.04 / 24.04) ``` curl -fsSL https://raw.githubusercontent.com/huynhtrungcsc/bach-dang-waf/main/scripts/deploy.sh | sudo bash ``` 安装 Nginx + ModSecurity（从源码编译）、PostgreSQL、Node.js 22、systemd 服务和 UFW 规则。 ### 选项 A — Docker Compose **要求：** Docker 24+, Compose v2 ``` git clone https://github.com/huynhtrungcsc/bach-dang-waf.git cd bach-dang-waf cp .env.example .env # Edit DB credentials and secrets docker compose up -d ``` 打开 `http://:8080` | 用户名 | 密码 | 角色 | |----------|----------|------| | `admin` | `admin123` | Admin | | `operator` | `operator123` | Operator | | `viewer` | `viewer123` | Observer | 首次登录后立即更改所有默认密码。 ### 选项 B — 裸金属 ``` git clone https://github.com/huynhtrungcsc/bach-dang-waf.git cd bach-dang-waf sudo bash scripts/deploy.sh ``` 配置内容：Node.js 22、pnpm、PostgreSQL (Docker)、从源码编译的 Nginx 1.28 + ModSecurity 3.x、systemd 服务、UFW（端口 22, 80, 443, 8080）。 ### 选项 C — 开发环境 ``` git clone https://github.com/huynhtrungcsc/bach-dang-waf.git cd bach-dang-waf cp .env.example .env pnpm install pnpm --filter @bach-dang-waf/api db:generate pnpm --filter @bach-dang-waf/api db:push pnpm --filter @bach-dang-waf/api db:seed pnpm dev ``` | 服务 | URL | |---------|-----| | Frontend | `http://localhost:5000` | | Backend API | `http://localhost:3001` | Vite 开发服务器会自动将 `/api` 请求代理到后端。 ## 更新 ### Docker Compose ``` cd /opt/bach-dang-waf git pull origin main docker compose up -d --build ``` ### 裸金属 (systemd) ``` cd /opt/bach-dang-waf sudo bash scripts/update.sh ``` 或手动操作： ``` git pull origin main pnpm install pnpm --filter @bach-dang-waf/api db:generate pnpm --filter @bach-dang-waf/api db:deploy pnpm --filter @bach-dang-waf/web build sudo systemctl restart bach-dang-waf-backend bach-dang-waf-frontend ``` ## 配置 复制 `.env.example` 为 `.env` 并设置所需值： | 变量 | 必填 | 描述 | |----------|----------|-------------| | `DATABASE_URL` | 是 | PostgreSQL 连接字符串 | | `JWT_ACCESS_SECRET` | 是 | 签名密钥 — 使用 `openssl rand -hex 48` 生成 | | `JWT_REFRESH_SECRET` | 是 | 刷新密钥 | | `SESSION_SECRET` | 是 | 会话加密密钥 | | `CORS_ORIGIN` | 否 | 允许的来源，逗号分隔 | | `BCRYPT_ROUNDS` | 否 | 默认 12 | | `TOTP_ISSUER` | 否 | 身份验证器应用中显示的应用名称 | | `NODE_ENV` | 否 | `development` 或 `production` | `VITE_API_URL` 不是必需的 — 前端使用相对 `/api` 路径。 ## 防火墙 ``` ufw allow 22/tcp # SSH — always allow first ufw allow 80/tcp # HTTP — WAF proxy + ACME challenge ufw allow 443/tcp # HTTPS — WAF proxy TLS ufw allow 8080/tcp # Management console ufw enable ``` `deploy.sh` 会自动配置 UFW。 ## 技术栈 | 层级 | 技术 | |-------|------------| | Frontend | React 19, TypeScript, Vite 7, TanStack Router, Tailwind CSS 4, shadcn/ui | | Backend | Node.js 22, Express, TypeScript, Prisma ORM | | Database | PostgreSQL 16 | | WAF Engine | Nginx 1.28, ModSecurity 3.x, OWASP Core Rule Set | | Auth | JWT (access + refresh), bcrypt, TOTP 2FA | | Deployment | Docker Compose, nginx (SPA + API proxy), systemd | | Monorepo | Turborepo, pnpm workspaces | ## 项目结构 ``` bach-dang-waf/ ├── apps/ │ ├── api/ Express backend │ │ ├── src/domains/ Feature modules (WAF, SSL, alerts, backup…) │ │ ├── src/config/ Environment configuration │ │ └── prisma/ Schema, migrations, seed │ └── web/ React SPA │ └── src/ │ ├── components/ UI components │ ├── routes/ TanStack Router file-based routes │ └── queries/ TanStack Query hooks ├── config/ Nginx WAF config templates ├── docker/ Dockerfiles and nginx console config ├── scripts/ │ ├── deploy.sh Full bare-metal deployment (Ubuntu) │ ├── update.sh In-place update │ └── quickstart.sh Quick dev setup └── docker-compose.yml ``` ## 路线图 - [ ] 实时 WebSocket 日志流 - [ ] 通过 ACME 实现 Let's Encrypt 自动续期 - [ ] 带全文搜索的 OWASP CRS 规则浏览器 - [ ] Webhook / Telegram / Slack 告警投递 - [ ] LDAP / Active Directory 身份验证 - [ ] 多节点副本同步仪表板 - [ ] 深色模式 - [ ] 面向生产就绪的全面安全审计 ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。欢迎提交 Pull Request。对于重大更改，请先开启 issue。 ## 安全 通过 [GitHub Security Advisories](https://github.com/huynhtrungcsc/bach-dang-waf/security/advisories/new) 报告漏洞。请勿针对安全发现公开开启 issue。 完整策略和部署加固清单请参见 [SECURITY.md](SECURITY.md)。 ## 许可证 [MIT](LICENSE) — Copyright 2025–2026 [Huỳnh Chí Trung](https://github.com/huynhtrungcsc)

**Bach Dang WAF** — 掌控您的安全边界。 [在 GitHub 上 Star](https://github.com/huynhtrungcsc/bach-dang-waf) · [提交 Issue](https://github.com/huynhtrungcsc/bach-dang-waf/issues) · [讨论](https://github.com/huynhtrungcsc/bach-dang-waf/discussions)

标签：AppImage, DevSecOps, GNU通用公共许可证, Homelab, IP访问控制, MITM代理, ModSecurity, Nginx, Node.js, OWASP CRS, PostgreSQL, SRE工具, SSL证书自动化, TypeScript, WAF, Web应用防火墙, 上游代理, 入侵防御, 反向代理, 安全插件, 提示注入, 测试用例, 网络安全, 自动化攻击, 自托管, 规则管理, 请求拦截, 隐私保护, 集群管理, 零厂商锁定