6 分钟阅读 | 最后修改: 2026-11-13, 7:48:03 pm

CrowdSec 防护

配置 CrowdSec bouncer，并通过自定义 EdgeLang 规则检查 HTTP 请求的客户端 IP。

CrowdSec 根据安全事件生成针对客户端 IP 的处置决策，网关节点通过 bouncer 获取并执行这些决策。在 Edge Admin 中，使用自定义 EdgeLang 规则调用 crowdsec-enforce() 启用检查。

此功能在 OpenResty Edge 26.12.1-1 中首次引入，仅适用于 HTTP 应用。

使用前准备

Edge Admin 和目标分区的网关节点使用 OpenResty Edge 26.12.1-1 或更新版本。
提前部署 CrowdSec，并确保每个网关节点都可以访问和认证到 CrowdSec LAPI （本地 API）。LAPI 可以部署在本机或其他服务器。
oredge-crowdsec-bouncer 组件会自动安装。本机已配置好 CrowdSec 服务时，安装时会自动完成本地 bouncer 配置。使用远程 LAPI 或未完成自动配置时，需要手动配置。

需要手动配置 API Key 时，先在 CrowdSec 服务端为 bouncer 注册，具体操作参见 CrowdSec bouncer 注册文档。为各节点准备对应的凭据，不要将真实 API Key 写入页面规则或提交到版本控制系统。

配置 bouncer

配置文件位置

配置文件位于 /usr/local/oredge-node/conf/oredge-crowdsec-bouncer.conf。

配置文件使用 KEY=value 格式，布尔值使用小写 true 或 false，注释另起一行，以 # 开头。直接填写实际值，不要保留 ${API_KEY} 等安装占位符。

sudoedit /usr/local/oredge-node/conf/oredge-crowdsec-bouncer.conf

网关节点从自身 Nginx 启动前缀下的 conf/oredge-crowdsec-bouncer.conf 读取配置。标准 oredge-node 服务使用上述路径。若节点使用其他启动前缀，按实际路径调整。升级已有部署时，将原有配置迁移到节点实际读取的 oredge-crowdsec-bouncer.conf。

bouncer 还会读取实际配置文件旁的 oredge-crowdsec-bouncer.conf.local，其中的同名配置项优先。已有该文件时，请一并检查，避免覆盖主配置中的设置。

IP 封禁配置示例

以下示例供手动配置时参考，使用 API Key 连接同机的 LAPI，只执行 ban 类型的决策。将 API_KEY 替换为实际密钥；如果 LAPI 在其他服务器，将 API_URL 改为节点可访问的地址。安装时已自动完成配置的节点可保留生成的 API_URL 和 API_KEY，按需调整其他选项。

ENABLED=true
API_URL=http://127.0.0.1:8080
API_KEY=replace-with-your-bouncer-api-key
USE_TLS_AUTH=false
SSL_VERIFY=true
MODE=live
CACHE_EXPIRATION=1
REQUEST_TIMEOUT=3000
STREAM_REQUEST_TIMEOUT=15000
UPDATE_FREQUENCY=10
BOUNCING_ON_TYPE=ban
FALLBACK_REMEDIATION=ban
ENABLE_INTERNAL=false
EXCLUDE_LOCATION=
BAN_TEMPLATE_PATH=/usr/local/openresty-plus/crowdsec/templates/ban.html
REDIRECT_LOCATION=
RET_CODE=403

以上值是示例配置，并非所有安装版本的默认值。使用安装包提供的模板时，应确认 BAN_TEMPLATE_PATH 指向的文件存在且可被节点读取。

配置项说明

配置项	说明
`ENABLED`	本地 bouncer 开关。设为 `true` 才会初始化检查；还需要开启分区开关并调用 EdgeLang 动作。
`API_URL`	LAPI 基础地址，包含协议、主机和端口，不要填写 `/v1/decisions` 等接口路径。示例中的 `127.0.0.1` 仅适用于 LAPI 与网关同机。
`API_KEY`	LAPI 为 bouncer 签发的 API Key，不是 CrowdSec Console 登录凭据。
`USE_TLS_AUTH`	是否使用 TLS 客户端证书认证。示例使用 API Key，因此设为 `false`。
`SSL_VERIFY`	使用 HTTPS 访问 LAPI 时是否校验服务器证书。启用时应配置节点信任的 CA；本机 HTTP 示例不使用 TLS。
`MODE`	`live` 在需要时向 LAPI 查询当前 IP，并缓存结果；`stream` 定期同步决策并在本地匹配。这里的 `stream` 是决策同步模式，不表示支持 TCP/UDP 流式应用。
`CACHE_EXPIRATION`	`live` 模式下查询结果的缓存时间，单位为秒。
`REQUEST_TIMEOUT`	`live` 模式访问 LAPI 的超时时间，单位为毫秒。
`STREAM_REQUEST_TIMEOUT`	`stream` 模式同步决策时的请求超时，单位为毫秒。
`UPDATE_FREQUENCY`	`stream` 模式的决策同步间隔，单位为秒。
`BOUNCING_ON_TYPE`	执行的决策类型：`ban`、`captcha` 或 `all`。本例只执行封禁。
`FALLBACK_REMEDIATION`	验证码不可用或收到不支持的处置类型时使用的后备动作，可设为 `ban` 或 `captcha`。它不是 LAPI 连接失败时的通用封禁开关。
`ENABLE_INTERNAL`	是否检查 Nginx 内部请求。设为 `false` 时跳过内部请求。
`EXCLUDE_LOCATION`	不检查的 URI，以逗号分隔；匹配指定路径及其子路径。留空表示不额外排除路径。
`BAN_TEMPLATE_PATH`	封禁时返回的 HTML 模板文件路径。
`REDIRECT_LOCATION`	封禁时的重定向地址。留空时使用封禁页面和状态码；非空时优先执行重定向。
`RET_CODE`	封禁响应的 HTTP 状态码，本例为 `403`。

如需验证码处置，还需要配置 CAPTCHA_PROVIDER、SITE_KEY、SECRET_KEY、 CAPTCHA_TEMPLATE_PATH 和 CAPTCHA_EXPIRATION（验证通过后的有效期，单位为秒）。将 BOUNCING_ON_TYPE 改为 captcha 或 all 前，应先验证所选验证码服务和模板可用。

使用 TLS 客户端证书认证时，还需设置 TLS_CLIENT_CERT 和 TLS_CLIENT_KEY。 APPSEC_URL 及其他 APPSEC_* 选项用于单独部署的 CrowdSec AppSec 服务，本例不启用 AppSec。高级配置请对照已安装 bouncer 的配置模板和 CrowdSec 配置说明。

配置完成后，在使用 systemd 的标准节点上重新加载服务：

sudo systemctl reload oredge-node

修改本地文件或安装 bouncer 后都需要重新加载节点。仅保存或发布 Edge Admin 规则不会重新读取该文件。应限制配置文件和相关私钥的读取权限；非 root 部署需确保实际加载配置的服务账号能够读取这些文件。

在 Edge Admin 中调用

确认分区内每个节点的配置已经生效，并可以访问 LAPI。
将目标分区的 enable_crowdsec 开关设为 true，保存并发布配置。
进入 HTTP 应用的 页面规则，点击 给此页面开始时添加 Edge 语言规则，直接填写以下规则：
```
true =>
    crowdsec-enforce();
```
保存并发布应用配置。

true 表示对执行到此处的所有请求调用检查。也可以按需限制范围，例如：

uri-prefix("/protected/") =>
    crowdsec-enforce();

此动作不接受参数，在 HTTP 请求的改写阶段执行。允许的请求继续执行后续动作；封禁、验证码或重定向响应可以终止当前请求。同一请求中重复调用只检查一次。

检查使用 Edge 识别的可信客户端 IP。节点前有负载均衡器或代理时，应先正确配置可信代理和真实 IP 处理，避免将代理地址误作为客户端地址。

规则编辑方法参见编写自定义 Edge 规则，动作语法参见 EdgeLang crowdsec-enforce()。

验证和停用

在隔离的测试环境中分别验证正常请求、已封禁客户端以及解除封禁后的请求。 stream 模式需等待决策同步，live 模式需考虑缓存时间。节点进程运行或发布成功不等于检查已生效，应同时检查实际响应和节点错误日志。

以下任一情况会跳过 CrowdSec 校验：

未配置 bouncer：节点实际读取的配置文件不存在。
本地 bouncer 被禁用：配置文件中设置了 ENABLED=false。
bouncer 初始化失败，包括组件缺失或配置读取失败。

即使分区开关已开启，这些情况也不会中断请求，后续 Edge 动作会继续执行。初始化失败会记录错误，但不会阻止节点启动；修正配置或补齐组件后需重新加载节点。分区开关关闭时，也不会执行请求校验。

bouncer 初始化成功后，普通 LAPI 连接失败或超时按以下方式处理（未启用 AppSec）：

live 模式优先使用缓存。未命中缓存时，查询失败会记录错误并放行请求，后续 Edge 动作继续执行；请求可能需要等待 REQUEST_TIMEOUT 指定的超时时间。
stream 模式的后台同步失败会记录错误，继续使用已有缓存。未命中缓存处置决策的请求会放行；请求校验不会等待 LAPI 同步。

已有缓存中的封禁等处置决策在有效期内继续生效，不会因 LAPI 无法访问而立即解除。普通 LAPI 网络故障不会直接导致 500；未处理的检查异常仍可能返回 500 并中断后续动作。启用 AppSec 时，最终处置还受 AppSec 检查结果影响。

停用时，先关闭并发布分区的 enable_crowdsec，确认所有节点已生效。如需同时停止后台同步，将各节点实际使用的本地配置改为 ENABLED=false 并重新加载。

CrowdSec 防护

# 使用前准备

# 配置 bouncer

# 配置文件位置

# IP 封禁配置示例

# 配置项说明

# 在 Edge Admin 中调用

# 验证和停用

很乐意听到您的反馈，请与我们联系 👋

成功发送消息！