crowdsec

CrowdSec — 运维、部署、配置与调试

术语表： AppSec 是引擎组件名称（用于配置、hub 路径、 cscli appsec-*、Helm 工作负载）；WAF 是面向用户的同一功能的称呼。 本文会交替使用这两个术语。

范围 — 本文能做什么、不能做什么

你想要……	使用
安装／升级／卸载 CrowdSec	本文
配置采集、hub、配置文件、通知	本文
安装并连接 bouncer（防火墙、nginx、traefik、caddy）	本文
部署 WAF（AppSec 组件）	本文
部署并调整机器人检测（AppSec 挑战模式）	本文
调试“日志无法解析”／“没有警报”／“bouncer 未拦截”	本文
从 fail2ban 迁移	本文
编写解析器、场景或 WAF（AppSec）规则	crowdsec-local-mcp mcp
操作云端 Service API（以编程方式管理封禁列表／允许列表／防火墙集成／指标／决策）	crowdsec-service-api 技能

步骤 1 — 检测环境

按此顺序运行探测。遇到第一个匹配项后停止。

# systemd / bare-metal
systemctl list-unit-files crowdsec.service >/dev/null 2>&1 && systemctl is-enabled crowdsec >/dev/null 2>&1
# docker
docker ps --format '{{.Names}} {{.Image}}' 2>/dev/null | grep -E '(^|/)(crowdsec)([: ]|$)'
# kubernetes
kubectl get pods -A 2>/dev/null | grep -i crowdsec

如果都不匹配，且用户表示已安装 CrowdSec，请询问安装位置：供应商设备、自定义镜像、/opt/ 中的二进制文件，还是远程主机。否则转到安装流程：参见 references/install/。

pfSense 检测：

uname -i   # → pfSense  (pfSense CE or Plus)

如果确认是 pfSense，直接前往 references/install/pfsense.md — 路径、服务名称和启用流程与 Linux/systemd 完全不同。

权限 — 裸机／systemd 前提条件

在裸机／systemd 环境中，cscli 和 crowdsec 需要 root 权限（它们会读取 /etc/crowdsec/、/var/lib/crowdsec/ 下的数据库，并控制 systemd 单元）。运行任何会修改配置或状态的操作前，请确认用户是 root 或拥有 sudo 权限：

id -u   # 0 = root; otherwise the user needs sudo

如果用户既不是 root，也没有 sudo 权限，请停止并要求授予相应权限 — 不要猜测。确认后，以 root 身份或使用 sudo 前缀运行裸机命令。 Docker/k8s 命令在容器／Pod 内运行，不需要此权限。

步骤 1.5 — 版本与安装来源检查（Linux）

在任何安装任务，以及收到任何“异常行为”报告时（缺少 cscli 命令／标志、hub 项目无法安装、行为与文档不符），都要先执行此检查。引擎若从错误来源安装，版本可能会落后数年 — 这是仅影响 Linux 发行版的陷阱。

将正在运行的引擎与最新发布版本进行比较：

curl -s https://version.crowdsec.net/latest    # → {"tag_name":"v1.7.8",...}; parse tag_name
cscli version                                  # bare-metal: prefix sudo

然后检查软件包来源：

# Debian/Ubuntu
apt-cache policy crowdsec                       # read the *** installed line's origin
ls /etc/apt/sources.list.d/ | grep -i crowdsec
# RHEL-family
dnf info crowdsec ; dnf repolist | grep -i crowdsec

官方来源是 packagecloud 仓库（packagecloud.io/crowdsec/crowdsec，仓库 ID 为 crowdsec_crowdsec）。如果来源是发行版仓库（archive.ubuntu.com、deb.debian.org、 ports.ubuntu.com），或完全没有 crowdsec 仓库文件，则说明该软件包来自发行版自带的旧版本仓库。

**规则：**如果来源不是官方仓库，或者版本明显落后于 tag_name，则应将其视为可能已过时的安装 — 停止调试配置，先迁移到官方仓库：references/operate/upgrades.md § 检测并修复过时／来自发行版软件包的安装。

**Docker/Kubernetes：**没有仓库来源陷阱 — 版本由从 Docker Hub 拉取的镜像标签决定。如果版本远落后于 version.crowdsec.net/latest，请拉取更新的标签 （参见 references/operate/upgrades.md 中的顺利升级流程）。

步骤 1.6 — 功能兼容性

部分功能仅在达到特定引擎版本后才可用，还有少数功能需要具备相应能力的 bouncer。 在排查“配置没问题但什么都没发生”之前，请先查看此处——如果引擎版本较旧，解决方法是升级，而不是修改配置。

功能	最低引擎版本	还需要	文档
Bot 检测（AppSec 挑战模式）— alpha	1.8.0	支持 Bot 检测的 bouncer（nginx、OpenResty、HAProxy SPOA、Traefik、Envoy），以及能够以编译器模式运行 WASM 的主机	references/appsec/bot-detection/
appsec_configs 中的 Glob 模式	1.8.0	—	references/appsec/bot-detection/deploy.md § 2

版本限制行为统一记录在此处，而不在每份参考文档中重复说明——添加功能时，请为其新增一行，而不是在正文各处零散添加“x.y+”。

步骤 2 — 识别意图

用户提示	跳转到
"install", "set up", "fresh box", "how do I start"	references/install/（按环境选择文件）
"pfsense", "pfSense", "netgate"	references/install/pfsense.md
"configure logs / acquisition", "read journald / syslog / docker logs"	references/configure/acquisition.md
"install a collection / parser / scenario", "hub", "tainted"	references/configure/hub.md
"ban duration", "captcha", "decisions", "simulation", "alerts but no bans"	references/configure/profiles.md
"allowlist my office / CDN / monitoring IP", "I'm getting blocked by CAPI", "exclude IP from any ban"	references/configure/allowlists.md
"whitelist vs allowlist vs postoverflow", "which suppression layer should I use"	references/configure/allowlists.md § 抑制机制
"test my whitelist works", "is my postoverflow / dynamic-IP whitelist actually firing"	references/configure/allowlists.md § 验证 — 白名单是否确实生效？
"notifications", "alert me on slack/email/webhook", "notification not firing"	references/configure/notifications.md
"block at the firewall", "iptables", "nftables", "ipset"	references/configure/bouncers/firewall.md
"nginx bouncer", "lua / openresty module"	references/configure/bouncers/web-servers.md § nginx
"haproxy bouncer", "SPOA / SPOE"	references/configure/bouncers/web-servers.md § haproxy
"apache bouncer", "mod_crowdsec"	references/configure/bouncers/web-servers.md § apache
"traefik bouncer", "traefik plugin / middleware"	references/configure/bouncers/web-servers.md § Traefik
"caddy bouncer", "caddy module / xcaddy"	references/configure/bouncers/web-servers.md § Caddy
"wrong source IP", "real client IP", "behind Cloudflare / reverse proxy / NPM", "X-Forwarded-For", "everyone shows as the proxy IP"	references/configure/bouncers/web-servers.md — 各 bouncer 的真实 IP／可信代理部分
"AppSec", "WAF", "virtual patching", "block by request shape"	references/appsec/ — 概览、部署、配置、故障排除
"bot detection", "challenge mode", "JS challenge", "proof of work", "block headless browsers / puppeteer / selenium / scrapers", "let Googlebot through"	references/appsec/bot-detection/ — 概览、部署、配置、自定义、故障排除
"Console", "enroll", "share signals"	references/install/console.md
"upgrade", "back up", "roll back", "new version", "tainted items after upgrade"	references/operate/upgrades.md
"old/outdated version", "cscli command or flag missing", "hub item won't install", "behavior doesn't match the docs", "installed from the distro package"	references/operate/upgrades.md § 检测并修复过时版本／发行版打包安装（参见上文的 Step 1.5）
"multiple agents", "remote LAPI", "mTLS", "postgres backend"	references/operate/multi-server.md（部分完成 — 机器清理已完成，其余为占位内容）
"stale machines / log processors in cscli machines list", "prune dead agents", "ephemeral k8s pods piling up"	references/operate/multi-server.md § 清理过时机器
"is it working?", "smoke test", "validate install", "verify setup", "did detection / WAF / blocking actually wire up?"	references/operate/health-check.md
调试 — 常见问题 · "it's broken" / "not working" / 一般性诊断	references/debug/common/triage.md → 运行 bash ${CLAUDE_SKILL_DIR}/scripts/diagnose.sh
调试 — 常见问题 · 特定错误字符串	references/debug/common/errors.md
调试 — 常见问题 · "container can't see logs", "mount", "SELinux/AppArmor denied", "k8s RBAC / DaemonSet"	references/debug/common/platform-gotchas.md
调试 — 按症状分类 · "logs not parsed", "0 parsed"	references/debug/symptoms/parsing.md
调试 — 按症状分类 · "no alerts firing"	references/debug/symptoms/no-alerts.md
调试 — 按症状分类 · "decision exists but not blocked"	references/debug/symptoms/not-blocked.md
调试 — 按症状分类 · "bouncer blocks everything", "locked out of all services", "every request 403 after adding the bouncer"	references/debug/symptoms/not-blocked.md § 7 — 反向症状
调试 — 按功能分类 · AppSec/WAF 未拦截、误报、验证码	references/appsec/troubleshoot.md
调试 — 按功能分类 · 挑战页面始终未显示、挑战陷入无限循环、真实爬虫遭遇挑战、启用机器人检测后所有请求均被拦截	references/appsec/bot-detection/troubleshoot.md
"switch from fail2ban"	references/migrate/from-fail2ban.md（TODO — 占位内容）
遇到任何形似调试的问题，几乎总是先执行：

bash ${CLAUDE_SKILL_DIR}/scripts/diagnose.sh

（或使用 --env docker --container <name> / --env k8s --namespace ... --pod ...）。

第 3 步 — 通用 cscli 速查表

这些命令适用于所有环境。在裸机/systemd 环境中，前缀加上 sudo（除非你是 root）——请参阅上文的 权限。在 docker/k8s 中，前缀加上 docker exec <name> / kubectl exec -n <ns> <pod> --（这些命令会在容器/Pod 内以 root 身份运行）。

用途	命令
引擎版本	cscli version
生效的配置（路径、LAPI URL、数据库类型）	cscli config show
一次性排查表	cscli metrics
最近的告警	cscli alerts list -l 50
活跃的封禁	cscli decisions list
删除一条封禁	cscli decisions delete -i <ip>
Hub 状态（已安装项 + tainted/missing 标记）	cscli hub list
刷新 Hub 索引，然后升级项目	cscli hub update && cscli hub upgrade
允许列表——列出 / 检查单个 IP / 添加	cscli allowlists list、cscli allowlists check <ip>、cscli allowlists add <name> <ip>
列出 bouncer 及其上次拉取时间	cscli bouncers list
列出已注册到此 LAPI 的 Agent	cscli machines list
检查 LAPI 是否可访问（Agent→LAPI）	cscli lapi status
检查 CAPI/Console 连通性（是否已注册、是否正在拉取/共享）	cscli capi status
Console 功能开关（custom/manual/tainted/context/console_management）	cscli console status
在 Console 中注册此引擎	cscli console enroll <key>，然后重新加载（请参阅 references/install/console.md）
通过解析器重放日志文件（只读）	cscli explain --file <path> --type <syslog|nginx|...>
重放单条日志	cscli explain --log '<line>' --type <type>
编辑任何 yaml（采集/配置文件/配置）后验证配置	crowdsec -t（裸机环境；systemctl reload 也会自动运行）——然后通过 cscli metrics show acquisition 确认数据源有读取记录
查看模拟状态（有告警但无决策）	cscli simulation status
检查决策配置文件（筛选条件 / 封禁时长）	cat /etc/crowdsec/profiles.yaml——没有 cscli profiles 命令（截至 v1.7.8）；请参阅 references/configure/profiles.md

默认裸机安装中的文件位置：

• 二进制文件：/usr/bin/crowdsec、/usr/bin/cscli
• 配置根目录：/etc/crowdsec/
• 采集配置：/etc/crowdsec/acquis.yaml 和/或 /etc/crowdsec/acquis.d/*.yaml
• Hub 项目：/etc/crowdsec/hub/，启用的符号链接位于 /etc/crowdsec/{parsers,scenarios,collections,postoverflows,contexts}/ 下
• 本地覆盖：*/parsers/*/_custom/、*/scenarios/*/_custom/ 等
• 数据（sqlite 数据库、geoip）：/var/lib/crowdsec/data/
• 日志：/var/log/crowdsec.log（Agent）和 /var/log/crowdsec_api.log（LAPI）
• LAPI 默认监听地址：127.0.0.1:8080
• Systemd 单元：crowdsec.service

第 4 步 — 严禁事项

执行以下任何操作前，都必须先征得用户确认：

• cscli decisions delete --all——会清除所有活跃的封禁，包括从 CAPI 拉取的阻止列表。请使用有针对性的 delete -i、delete -r、delete --id、delete --origin lists --scenario <name>。
• 修改 /etc/crowdsec/{parsers,scenarios,collections,postoverflows,contexts}/ 下由 Hub 管理的文件，而不是使用同级的 _custom/ 目录——请参阅 references/debug/common/triage.md § 严禁事项。
• 为消除误报而整体禁用某个签名集合——请根据 references/configure/allowlists.md § 抑制机制，选择正确的抑制层（允许列表 / 白名单解析器 / postoverflow）。
• 未经确认就更改主机防火墙状态（安装防火墙 bouncer、执行 ipset 清空、在 iptables 与 nftables 之间切换）——防火墙 bouncer 可能会清除其他工具依赖的规则链。
• 执行 helm upgrade crowdsec 时省略 --reset-then-reuse-values——这会在不提示的情况下丢弃配置值。

文档

权威参考文档：https://docs.crowdsec.net/。references/ 中的每个文件都会注明所依据的具体页面，请点击链接查看，而不要凭记忆转述。