中文

Linux 与网络

安装 CrowdSec 与防火墙 bouncer

用 CrowdSec 保护您的 Debian 或 Ubuntu 服务器:安装、IP 白名单、防火墙 bouncer、集合、决策与故障排除。

阅读约 7 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

CrowdSec 会分析您服务器的日志,识别恶意行为(SSH 暴力破解、网站扫描等),并决定封禁相关地址。本指南将向您介绍如何在 VPS 或独立服务器上安装它,如何保护您自己的 IP 地址,以及如何在防火墙层面实施封禁。

CrowdSec 的工作原理

组件 作用
Security Engine 读取日志,并借助场景(scenario)检测攻击
Local API (LAPI) 存储决策,默认监听 127.0.0.1:8080
防火墙 bouncer 获取决策,并在防火墙中封禁相应地址
cscli 用于管理一切的命令行工具

前提条件

  • 运行 Debian 12/13 或 Ubuntu 22.04/24.04 的服务器
  • 使用 root 或 sudo 用户的 SSH 访问权限
  • 您管理服务器时所用的公网 IP 地址
  • 备用访问方式:在 VPS 上,使用客户中心的 VNC 控制台。在独立服务器上,请确认可用的访问方式,或通过客户中心联系支持团队

端口: 无需开放任何传入端口。LAPI(8080)和指标(6060)仅监听 127.0.0.1,不应对外暴露。服务器必须能够通过 HTTPS 访问 api.crowdsec.net。

步骤 1:检查本地端口

终端
sudo ss -ltnp | grep -E ':(8080|6060) '

如果该命令没有显示任何内容,请进入下一步。如果端口 8080 已被占用(例如被某个 Docker 容器占用),也请继续:步骤 3 会处理这种情况。

步骤 2:安装 CrowdSec

下载官方的仓库添加脚本,查看其内容,然后执行:

终端
curl -fsSL https://install.crowdsec.net -o crowdsec-repo.sh
less crowdsec-repo.sh
sudo sh crowdsec-repo.sh

然后安装软件包:

终端
sudo apt update
sudo apt install crowdsec

检查服务:

终端
sudo systemctl status crowdsec
sudo cscli version

步骤 3:必要时更改 LAPI 端口

如果端口 8080 被占用,软件包会安装但不会启动服务,并显示 Not attempting to start crowdsec, port 8080 is already used。请选择一个空闲端口(此处为 8180),然后修改相关的两个文件:

终端
sudo sed -i 's|listen_uri: 127.0.0.1:8080|listen_uri: 127.0.0.1:8180|' /etc/crowdsec/config.yaml
sudo sed -i 's|^url: .*|url: http://127.0.0.1:8180|' /etc/crowdsec/local_api_credentials.yaml
sudo systemctl restart crowdsec
sudo cscli lapi status

出现 You can successfully interact with Local API (LAPI) 消息即表示一切正常。

步骤 4:将您的 IP 地址加入白名单

请在安装 bouncer 之前完成此步骤,以免封禁您自己的访问。在 SSH 会话中,显示所用的地址:

终端
echo $SSH_CONNECTION | awk '{print $1}'

创建一个白名单(allowlist),并把该地址加入其中:

终端
sudo cscli allowlists create admins -d 'Admin addresses'
sudo cscli allowlists add admins 您的IP -d 'Admin workstation'
sudo cscli allowlists inspect admins

地址段的添加方式相同,例如 198.51.100.0/24。白名单只能阻止产生新的决策,不会移除已有的决策。如果您的地址已经被封禁:

终端
sudo cscli decisions delete --ip 您的IP

步骤 5:安装防火墙 bouncer

终端
sudo apt install crowdsec-firewall-bouncer-iptables
sudo systemctl status crowdsec-firewall-bouncer
sudo cscli bouncers list

安装在同一台服务器上的 bouncer 会自动向 LAPI 注册:它应当出现在列表中,且 Valid 列带有勾选标记。其配置位于 /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml。

此软件包使用 iptables 和 ipset,可与 UFW 以及 Docker 的 DOCKER-USER 链配合使用。对于完全基于 nftables 的配置,另有 crowdsec-firewall-bouncer-nftables 软件包。

步骤 6:验证检测与封禁

总体状态

终端
sudo cscli capi status
sudo cscli metrics show acquisition parsers

只要自服务启动以来日志中没有写入新的行,来源表格就可能保持为空。

测试 SSH 检测

在一台地址不在您的白名单中的机器上,发起下面这个连接,它通常会失败:

终端
ssh crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl@您的服务器IP

在服务器上,应当出现测试告警:

终端
sudo cscli alerts list -s crowdsecurity/ssh-generic-test

测试封禁

请用您手头一个与管理地址不同的公网地址,代替 203.0.113.10:

终端
sudo cscli decisions add --ip 203.0.113.10 --duration 5m --reason 'Test'
sudo cscli decisions list

几秒钟后,该地址会被加入防火墙,并且无法再访问服务器:

终端
sudo iptables -S CROWDSEC_CHAIN
sudo ipset list crowdsec-blacklists-0 | tail -n 5

然后移除该决策:

终端
sudo cscli decisions delete --ip 203.0.113.10

集合与日志来源

一个集合(collection)汇集了某项服务的解析器和场景。安装时,CrowdSec 会检测已有的服务,并将相应的来源写入 /etc/crowdsec/acquis.d/。

终端
sudo cscli collections list
sudo cscli collections list -a

对于在 CrowdSec 之后安装的服务(例如 Nginx),请添加相应的集合:

终端
sudo cscli collections install crowdsecurity/nginx

然后创建 /etc/crowdsec/acquis.d/nginx.yaml:

YAML
filenames:
  - /var/log/nginx/*.log
labels:
  type: nginx

测试配置并重启:

终端
sudo crowdsec -t && sudo systemctl restart crowdsec
sudo cscli metrics show acquisition

管理决策

操作 命令
列出决策 sudo cscli decisions list
封禁某个地址 24 小时 sudo cscli decisions add --ip 203.0.113.10 --duration 24h --reason 'Manual ban'
封禁一个地址段 sudo cscli decisions add --range 203.0.113.0/24 --reason 'Manual ban'
解封某个地址 sudo cscli decisions delete --ip 203.0.113.10
查看告警 sudo cscli alerts list
某个地址的告警 sudo cscli alerts list --ip 203.0.113.10

不带 --duration 时,手动决策持续 4 小时。请避免使用 sudo cscli decisions delete --all,它会同时删除本地决策和社区决策。

保护 Docker 容器

Docker 发布的端口经过 FORWARD 链,而不是 INPUT 链。要让 bouncer 覆盖它们,请创建 /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml.local:

YAML
iptables_chains:
  - INPUT
  - DOCKER-USER

此文件中的列表会替换主文件中的列表:因此请保留 INPUT。必须已安装 Docker,因为 DOCKER-USER 链由它创建。若要让 bouncer 在 Docker 之后启动,请添加一个 systemd 补充配置:

终端
sudo systemctl edit crowdsec-firewall-bouncer
配置
[Unit]
After=docker.service
Wants=docker.service

重启并检查:

终端
sudo systemctl restart crowdsec-firewall-bouncer
sudo iptables -S DOCKER-USER

CrowdSec 控制台(可选)

网页控制台可以帮助您跟踪告警和服务器。请在 app.crowdsec.net 创建账户,获取您的注册密钥,然后执行:

终端
sudo cscli console enroll ENROLLMENT_KEY

在控制台中接受该服务器,然后用 sudo systemctl restart crowdsec 重启服务。不执行此步骤,CrowdSec 同样可以工作。

更新

先更新软件包,再更新 Hub 中的内容(集合、场景、解析器):

终端
sudo apt update
sudo apt install --only-upgrade crowdsec crowdsec-firewall-bouncer-iptables
sudo cscli hub update
sudo cscli hub upgrade
sudo systemctl restart crowdsec

您在本地修改过的内容不会被 cscli hub upgrade 更新。

备份

配置位于 /etc/crowdsec,数据(包括默认的 SQLite 数据库)位于 /var/lib/crowdsec/data。复制期间请先停止服务,以获得一致的数据库:

终端
sudo systemctl stop crowdsec
sudo tar czf crowdsec-backup.tar.gz /etc/crowdsec /var/lib/crowdsec/data
sudo systemctl start crowdsec
sudo chmod 600 crowdsec-backup.tar.gz

此归档包含凭据:请将其妥善保存在服务器之外。

故障排除

您被 CrowdSec 封禁了

通过 VNC 控制台连接(独立服务器则联系支持团队),然后移除该决策并将您的地址加入白名单:

终端
sudo cscli decisions delete --ip 您的IP
sudo cscli allowlists add admins 您的IP

如有需要,sudo systemctl stop crowdsec-firewall-bouncer 会暂停封禁,以便您修正问题。

bind: address already in use

另一项服务正在使用 LAPI 的端口。用 sudo ss -ltnp | grep 8080 找出它,然后按照 步骤 3 处理。如果 bouncer 已经安装,还需更新其配置中的 api_url 并重启它。

bouncer 显示 connection refused

  • 确认 CrowdSec 正在运行:sudo systemctl status crowdsec
  • 将 bouncer 配置中的 api_url 与 /etc/crowdsec/config.yaml 中的 listen_uri 进行比对
  • 查看 /var/log/crowdsec-firewall-bouncer.log

bouncer 显示 API error: access forbidden

它的密钥已不再被识别。请用新名称创建一个密钥,将其填入 api_key,然后重启 bouncer:

终端
sudo cscli bouncers add firewall-bouncer-2
sudo nano /etc/crowdsec/bouncers/crowdsec-firewall-bouncer.yaml
sudo systemctl restart crowdsec-firewall-bouncer

ent: machine not found 或 incorrect Username or Password

本地凭据与数据库不再匹配:

终端
sudo cscli machines add -a --force
sudo systemctl restart crowdsec

没有任何日志行被分析

  • 列出来源:sudo cscli metrics show acquisition
  • 检查 /etc/crowdsec/acquis.d/ 中的文件以及日志的实际路径
  • 查找错误:sudo grep -E 'level=(error|fatal)' /var/log/crowdsec.log

添加 DOCKER-USER 后 bouncer 无法再启动

在 Docker 启动之前,该链并不存在。请检查 sudo systemctl status docker,然后检查 sudo iptables -S DOCKER-USER。

参考资料