CrowdSec Lua Plugin 技术文档

一、镜像概述和主要用途

CrowdSec Lua Plugin 是一款与 Ingress Nginx 控制器配合使用的 Lua 插件（bouncer），用于集成 CrowdSec 安全防护系统。其核心用途是将 CrowdSec 生成的安全决策（如 IP 封禁、限流等）应用于 Ingress Nginx 层面，实现对入站流量的实时过滤和防护，有效阻止***请求访问后端服务。

二、核心功能和特性

1. 多模式运行：支持两种工作模式

   • stream 模式：定期从 CrowdSec 本地 API（LAPI）拉取安全决策并缓存（默认模式）
   • live 模式：实时查询 LAPI 验证每个请求的决策

2. 高效缓存机制：通过 lua_shared_dict 实现跨 Worker 进程的决策缓存，减少对 LAPI 的重复请求，提升性能

3. 灵活的决策配置：可指定需要处理的决策类型（如 ban、captcha 等），支持自定义缓存过期时间、缓存大小和请求超时

4. 配置方式多样：支持通过环境变量动态配置，或挂载自定义配置文件覆盖默认设置

三、使用场景和适用范围

适用场景

• 使用 Ingress Nginx 作为入口控制器的 Kubernetes 集群环境
• 需要集成 CrowdSec 安全决策（如 IP 封禁、异常流量拦截）的 Web 应用防护场景
• 需实时或定期同步安全策略，提升入口层防护能力的场景（如 DDoS 缓解、爬虫治理等）

适用范围

• 基于 Nginx/OpenResty 的反向代理或入口控制器
• 与 CrowdSec 本地 API（LAPI）部署在同一网络环境，确保插件可访问 LAPI 服务

四、配置说明

4.1 配置方式

插件支持两种配置方式，优先级为：挂载自定义配置文件 > 环境变量。

• 环境变量：通过容器环境变量注入配置（适用于动态调整）
• 配置文件：挂载自定义配置文件至 /etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf（适用于复杂配置）

4.2 环境变量详解

4.3 缓存配置

插件使用 Nginx 的 lua_shared_dict 共享内存区域存储决策缓存，默认大小为 50m。如需调整缓存大小，需通过 Ingress Nginx 的 ConfigMap 配置（参考 Ingress Nginx 文档），示例配置：

yaml
# ingress-nginx ConfigMap 片段
apiVersion: v1
kind: ConfigMap
metadata:
  name: ingress-nginx-controller
  namespace: ingress-nginx
data:
  lua-shared-dicts: "crowdsec_cache 100m"  # 调整缓存大小为 100m

五、使用方法

5.1 Docker 部署示例

以下为简化的 Docker 运行示例（实际场景中通常与 Ingress Nginx 容器集成）：

bash
docker run -d \
  --name crowdsec-lua-plugin \
  -e API_URL="[***]" \
  -e API_KEY="your_lapi_secret_key" \
  -e MODE="stream" \
  -e UPDATE_FREQUENCY="10" \
  -e CACHE_SIZE="2000" \
  -v /path/to/custom/config:/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf \  # 可选：挂载自定义配置文件
  crowdsecurity/crowdsec-lua-plugin:latest

注意：实际部署时需确保插件与 Ingress Nginx 控制器在同一网络，且 LAPI 地址可访问。

5.2 Kubernetes 配置提示

在 Kubernetes 环境中，通常通过 Helm 安装 Ingress Nginx 时集成该插件，关键配置项包括：

• 通过 --set controller.extraEnvs 注入环境变量
• 通过 --set controller.config.lua-shared-dicts 调整缓存大小
• 通过 --set controller.extraVolumes 和 --set controller.extraVolumeMounts 挂载自定义配置文件

六、卷挂载说明

七、重要文件位置

• 插件代码路径：/usr/local/openresty/lualib/plugins/crowdsec（CrowdSec Lua 库文件）
• Nginx 配置路径：/etc/nginx/conf.d（加载插件和配置的 Nginx 配置文件）

八、其他信息

8.1 项目地址

• cs-openresty-bouncer GitHub
• CrowdSec GitHub

8.2 贡献指南

请阅读 贡献文档 了解代码规范和 PR 提交流程。

8.3 许可证

本项目基于 MIT 许可证开源，详见 LICENSE 文件。