wolffcatskyy/crowdsec-unifi-bouncer

# UniFi OS 的 CrowdSec Firewall Bouncer [](https://github.com/wolffcatskyy/crowdsec-unifi-bouncer/releases) [](https://github.com/wolffcatskyy/crowdsec-unifi-bouncer/stargazers) [](LICENSE) [](https://github.com/wolffcatskyy/crowdsec-unifi-bouncer/actions/workflows/lint.yml) [](https://github.com/wolffcatskyy/crowdsec-unifi-bouncer/actions/workflows/docker-publish.yml) [](https://github.com/wolffcatskyy/awesome-unifi) 在 UniFi OS 设备上直接安装官方 [CrowdSec firewall bouncer](https://github.com/crowdsecurity/cs-firewall-bouncer) —— 具备在固件更新、重启和控制器重新配置后依然存活的持久性。包含一个智能 sidecar 代理，当决策数量超过设备承载能力时，它会对威胁进行评分并划分优先级。 **注意：** 本项目由 AI 开发并提供支持。Issues 和 PR 由 AI 智能体进行分类和响应。如果您需要人工服务只需提出，但说实话 AI 更快、更聪明、更友好。 **CrowdSec 新手？** [CrowdSec](https://crowdsec.net) 是一个免费、开源的安全引擎，利用众包威胁情报检测并拦截恶意 IP。请参阅 [官方安装指南](https://docs.crowdsec.net/docs/getting_started/install_crowdsec/) 入门。 ## 主要功能 - **一行命令安装** —— 在任何受支持的 UniFi 设备上通过 `curl | bash` 引导安装 - **固件更新不影响持久性** —— 可在 UniFi OS 更新、重启和控制器重新配置后幸存 - **自动检测** —— 自动识别您的设备型号并应用安全的 ipset 限制 - **Sidecar 代理** —— 基于 7 个因素对 12万+ 个决策进行评分，将最高优先级的威胁填入设备容量中 - **流感知上限控制** (v2.3.0) —— 通过可配置的驱逐机制，防止在高变动 CAPI 流上发生 ipset 溢出 - **Prometheus 指标** —— 监控 ipset 填充率、被丢弃的决策以及 sidecar 有效性 - **Grafana 仪表板** —— 包含在内，可直接导入 - **AbuseIPDB 上报** (v2.4.0) —— 自动将本地封禁的 IP 上报到 AbuseIPDB，为社区威胁情报做贡献 - **轻量级** —— Bouncer 占用 15 MB 内存，Sidecar 占用 8 MB ## 目录 - [面临的问题](#the-problem) - [快速开始](#quick-start) - [架构](docs/architecture.md) - [设备兼容性](docs/device-compatibility.md) - [安装](#installation) - [配置](docs/configuration.md) - [Sidecar 代理](docs/sidecar.md) - [AbuseIPDB 上报](docs/abuseipdb.md) - [Prometheus 指标](docs/metrics.md) - [故障排除](docs/troubleshooting.md) - [从 v1.x 迁移](#migration-from-python-bouncer) - [相关项目](#complete-unifi--crowdsec-suite) - [贡献](#contributing) ## 面临的问题 两个问题，一个项目解决。 **问题 1：持久性。** 官方的 bouncer 二进制文件在 UniFi 设备上运行完美，但 UniFi OS 很难让它保持运行。固件更新会清除您的 iptables 规则。控制器重新配置会静默移除自定义防火墙规则。Systemd 服务链接会消失。您安装了它，它也能工作，然后有一天它突然静默地停止拦截任何东西了。 **问题 2：容量。** CrowdSec 的社区黑名单 (CAPI) 可能会向您的 bouncer 推送 10万+ 个决策。UniFi 设备具有硬件限制的 ipset 容量（根据型号不同为 1.5K-3万 条目）。当 ipset 满了时，新 IP 会静默失败 —— 日志中深埋着 "Hash is full" 错误，零告警，您最危险的新威胁被丢弃，而上个月的陈旧条目却仍留在集合中。 **解决方案：** 一个安装程序、持久化脚本以及一个可选的 sidecar 代理来解决所有这些问题。一次安装，一劳永逸。 ## 快速开始 **前提条件：** 一个运行中的 [CrowdSec LAPI](https://docs.crowdsec.net/docs/getting_started/install_crowdsec/) 实例，以及您 UniFi 设备的 SSH root 访问权限。 ``` # 1. 在你的 CrowdSec 主机上 — 创建一个 bouncer API key cscli bouncers add my-unifi-bouncer # 保存输出的 API key # 2. 通过 SSH 登录你的 UniFi 设备并进行安装 ssh root@YOUR_UNIFI_IP curl -sSL https://raw.githubusercontent.com/wolffcatskyy/crowdsec-unifi-bouncer/main/bootstrap.sh | bash # 3. 配置 — 设置你的 LAPI 地址和 API key $EDITOR /data/crowdsec-bouncer/crowdsec-firewall-bouncer.yaml # 4. 启动 systemctl start crowdsec-firewall-bouncer # 5. 验证 ipset list crowdsec-blacklists -t | grep "Number of entries" ``` 就这样。Bouncer 会自动检测您的设备，设置安全的 ipset 限制，并在固件更新后保持持久性。 ## 安装 ### 一行命令安装（推荐） 通过 SSH 登录您的 UniFi 设备并运行： ``` curl -sSL https://raw.githubusercontent.com/wolffcatskyy/crowdsec-unifi-bouncer/main/bootstrap.sh | bash ``` 这将下载所有必需的文件并自动运行安装程序。 ### 手动安装 ``` # Clone 此 repo git clone https://github.com/wolffcatskyy/crowdsec-unifi-bouncer.git cd crowdsec-unifi-bouncer # 复制文件到你的 UniFi 设备 scp install.sh setup.sh detect-device.sh detect-sidecar.sh ensure-rules.sh \ ipset-capacity-monitor.sh metrics.sh \ crowdsec-firewall-bouncer.service crowdsec-unifi-metrics.service \ crowdsec-firewall-bouncer.yaml.example \ root@:/tmp/ # SSH 登录并运行安装程序 ssh root@ cd /tmp && bash install.sh ``` ## 配置 编辑 `/data/crowdsec-bouncer/crowdsec-firewall-bouncer.yaml` 并设置您的 `api_url` 和 `api_key`。如果使用 sidecar 代理，请将 `api_url` 指向端口 8084 而不是 LAPI 端口 8080。 有关所有设置、启动命令和验证步骤，请参阅 [完整配置参考](docs/configuration.md)。 ## 架构 三种持久化机制确保 bouncer 在固件更新和控制器重新配置期间持续运行。一个可选的 sidecar 代理基于 7 个因素对 12万+ 个决策进行评分，以便您设备有限的 ipset 始终容纳最高优先级的威胁。 完整图表和持久化机制详情请见 [docs/architecture.md](docs/architecture.md)。 ## 设备兼容性 Bouncer 会自动检测您的 UniFi 设备型号并应用安全的 ipset 限制。支持的层级：Enterprise (8万), Pro (5万), Consumer (1.5万)。不支持 UX 和 UXG-Lite。 完整的设备矩阵、环境变量和使用场景请见 [docs/device-compatibility.md](docs/device-compatibility.md)。 ## Sidecar 代理（可选但推荐） Sidecar 基于 7 个因素（场景严重性、来源、新鲜度、再犯率等）对所有 LAPI 决策进行评分，并仅返回适合您设备的前 N 个。您的本地检测和手动封禁总是会保留 —— 只有低信号的批量导入会被丢弃。 如果您的 LAPI 有超过约 1.5K-3万 个决策，或者您订阅了社区黑名单，请部署它。设置和评分详情请见 [docs/sidecar.md](docs/sidecar.md)。 ## AbuseIPDB 上报（可选） 在 sidecar 中启用此功能可自动将本地检测到的封禁上报给 AbuseIPDB。上报是即发即弃的，绝不会影响 bouncer 的运行。仅上报本地检测 —— 跳过 CAPI 和 blocklist-import 决策以避免循环上报。 配置和场景到类别的映射请见 [docs/abuseipdb.md](docs/abuseipdb.md)。 ## Prometheus 指标 Bouncer 在端口 9101 上公开指标（ipset 填充率、被拦截的 IP、被丢弃的决策）。Sidecar 在端口 8084 上公开有效性指标。`grafana/crowdsec-unifi-bouncer-dashboard.json` 中包含一个 Grafana 仪表板。 完整的指标参考请见 [docs/metrics.md](docs/metrics.md)。 ## 故障排除 常见问题：bouncer 启动但无 IP 被拦截、iptables 规则消失、固件更新后服务丢失、sidecar 502 错误、ipset 已满。 诊断和解决方案请见 [docs/troubleshooting.md](docs/troubleshooting.md)。 ## 从 Python Bouncer 迁移 如果从 v1.x 升级： 1. 停止并删除旧的 Docker 容器 2. 从 UniFi 控制器删除旧的防火墙组（名为 `crowdsec-ban-*`） 3. 删除旧的防火墙规则（索引 20000-20013） 4. 按照上面的 [安装](#installation) 步骤操作 原生 bouncer 直接使用 ipset/iptables： - **无 MongoDB 抖动** —— v1.x API 方式在 IP 超过 2000+ 时会导致路由器冻结 - **无需 UniFi 凭证** - **无 Docker 开销** —— 单个 Go 二进制文件，15 MB 内存 - **响应更快** —— 10s 轮询 vs 60s ## CrowdSec UniFi 生态系统的一部分 | 项目 | 描述 | |---------|-------------| | [crowdsec-unifi-suite](https://github.com/wolffcatskyy/crowdsec-unifi-suite) | 全栈一键安装程序 | | [crowdsec-blocklist-import](https://github.com/wolffcatskyy/crowdsec-blocklist-import) | 将 28+ 个威胁源导入 CrowdSec | | [crowdsec-unifi-parser](https://github.com/wolffcatskyy/crowdsec-unifi-parser) | 解析 UniFi 防火墙日志供 CrowdSec 使用 | ## 贡献 欢迎贡献。在提交 PR 之前，请先开 issue 讨论重大变更。 - **Shell 脚本** 通过 CI 使用 [ShellCheck](https://www.shellcheck.net/) 进行 lint 检查 - **Go 代码** (sidecar) 遵循标准 Go 规范 - 所有 PR 在合并前都需通过 CI ## 支持 本项目使用 AI 辅助支持以加快 issue 响应速度。如果您更倾向于与人工交流，请在您的 issue 中说明，维护者将会收到通知。 ## 许可证 MIT -- 详见 [LICENSE](LICENSE) ## 收录于 - Trent Bauer 撰写的 [CrowdSec + UniFi Installation Guide](https://www.trentbauer.com/guides/installation-guides/crowdsec/unifi)

更新日志亮点

**v2.4.0** -- AbuseIPDB 上报。自动将本地封禁的 IP 上报到 AbuseIPDB，包含场景到类别的映射、每日速率限制和智能来源过滤。即发即弃，绝不影响 bouncer 运行。 **v2.3.0** -- 流感知决策上限。`MAX_DECISIONS` 和 `EVICTION_MODE` 控制 CAPI 决策限制。本地决策始终通过。 **v2.2.0** -- Sidecar 代理的有效性指标：按来源的保留/丢弃计数器、分数分布、再犯统计、假阴性检测。多架构 Docker 镜像发布到 GHCR。 **v2.1.0** -- 具有 7 因素评分的智能 sidecar 代理。对决策划分优先级，确保最危险的威胁始终能进入您的 ipset。 **v2.0.0** -- 完全重写。用直接使用 ipset/iptables 的官方 Go 二进制文件取代了 Python/Docker bouncer（UniFi 控制器 API）。无 MongoDB 抖动，无需凭证，15 MB 内存。 所有版本请见 [完整变更日志](https://github.com/wolffcatskyy/crowdsec-unifi-bouncer/releases)。

## 致谢 - [CrowdSec](https://crowdsec.net) —— 开源安全引擎 - [crowdsecurity/cs-firewall-bouncer](https://github.com/crowdsecurity/cs-firewall-bouncer) —— 官方 Go 二进制文件 - [unifi-utilities/unifios-utilities](https://github.com/unifi-utilities/unifios-utilities) —— 在 UniFi OS 上持久化自定义服务的社区模式 - [Trent Bauer](https://www.trentbauer.com) —— 社区指南和文章

标签：Bouncer, CrowdSec, Cutter, Docker, EVTX分析, IP 封禁, Shell 脚本, UBNT, UDM, UniFi, UniFi OS, 入侵防御, 威胁情报, 安全防御评估, 家庭实验室, 开发者工具, 恶意流量检测, 日志审计, 系统持久化, 网关安全, 网络安全, 自动化防护, 自定义请求头, 请求拦截, 运维工具, 防火墙, 隐私保护