crowdsecurity/crowdsec-openresty 镜像文档

1. 镜像概述和主要用途

crowdsecurity/crowdsec-openresty 是一个基于 OpenResty 官方镜像构建的 Docker 镜像，集成了 CrowdSec Lua Bouncer 组件。该镜像旨在与 CrowdSec 安全引擎配合使用，提供 Web 层的实时安全防护能力，能够根据 CrowdSec 决策自动拦截恶意 IP 地址或触发验证码验证，保护后端服务免受恶意请求攻击。

2. 核心功能和特性

• 双模式运行：支持 stream（流式）和 live（实时）两种工作模式，适应不同防护需求
• 缓存管理：内置决策缓存机制，可配置缓存过期时间和容量，优化性能
• 灵活配置：支持通过环境变量或自定义配置文件进行参数配置
• 多类型决策支持：可指定需要处理的 CrowdSec 决策类型（如 ban）
• 验证码集成：支持 reCAPTCHA、hCaptcha 和 Turnstile 等验证码提供商，实现人机验证
• 基于 OpenResty：继承 OpenResty 完整功能，兼具 Nginx 高性能和 Lua 扩展能力

3. 使用场景和适用范围

适用场景

• 保护基于 OpenResty/Nginx 的 Web 服务（网站、API 等）
• 需要实时拦截恶意 IP（如扫描器、爬虫、DDoS 源）的场景
• 希望通过 CrowdSec 社区威胁情报增强防护能力的环境

适用用户

• 系统管理员、DevOps 工程师
• Web 服务运维人员
• 需构建安全 Web 基础设施的开发团队

4. 使用方法和配置说明

4.1 前提条件

• 已部署 CrowdSec 引擎（包含本地 API，LAPI）
• 通过 cscli 工具生成 Bouncer API 密钥：

  sudo cscli bouncers add <bouncer名称>  # 例如：sudo cscli bouncers add myOpenRestyBouncer
  

  保存生成的 API 密钥，用于后续配置

4.2 快速启动（使用环境变量）

基本命令

docker run -d -p 8080:80 \
  -e API_URL=<CROWDSEC_LAPI_URL> \  # CrowdSec 本地 API 地址（如 [***]
  -e API_KEY=<CROWDSEC_LAPI_KEY> \  # 生成的 Bouncer API 密钥
  --name openresty crowdsecurity/crowdsec-openresty

示例

假设生成的 API 密钥为 abcdefghijklmnopqrstuvwxyz，CrowdSec LAPI 地址为 [***]：

docker run -d -p 8080:80 \
  -e API_URL=[***] \
  -e API_KEY=abcdefghijklmnopqrstuvwxyz \
  --name openresty crowdsecurity/crowdsec-openresty

4.3 自定义配置文件（推荐）

1. 创建配置文件

创建 crowdsec-openresty-bouncer.conf，示例内容：

API_URL=[***]
API_KEY=abcdefghijklmnopqrstuvwxyz
CACHE_EXPIRATION=1          # 缓存过期时间（秒）
BOUNCING_ON_TYPE=ban        # 处理的决策类型
REQUEST_TIMEOUT=0.2         # LAPI 请求超时（秒）
UPDATE_FREQUENCY=10         # 流式模式拉取频率（秒）
MODE=stream                 # 工作模式
CAPTCHA_PROVIDER=recaptcha  # 验证码提供商
SITE_KEY=your_recaptcha_site_key
SECRET_KEY=your_recaptcha_secret_key

2. 挂载配置文件启动

docker run -d -p 8080:80 \
  -v /path/to/your/crowdsec-openresty-bouncer.conf:/etc/crowdsec/bouncers/crowdsec-openresty-bouncer.conf \
  --name openresty crowdsecurity/crowdsec-openresty

4.4 Docker Compose 示例

创建 docker-compose.yml：

version: '3'
services:
  openresty-crowdsec:
    image: crowdsecurity/crowdsec-openresty
    ports:
      - "8080:80"
    environment:
      - API_URL=[***]  # 假设 CrowdSec LAPI 在同一网络中名为 crowdsec-lapi
      - API_KEY=abcdefghijklmnopqrstuvwxyz
      - MODE=stream
      - UPDATE_FREQUENCY=10
    volumes:
      # 可选：挂载自定义 Nginx 配置
      - ./nginx/conf.d:/etc/nginx/conf.d
    depends_on:
      - crowdsec-lapi  # 需确保 CrowdSec LAPI 服务已定义

5. 详细配置说明

5.1 环境变量

5.2 卷挂载

5.3 关键文件位置

6. 相关资源

• GitHub 仓库：
  • cs-openresty-bouncer（Bouncer 源代码）
  • CrowdSec（CrowdSec 引擎）
• 贡献指南：CrowdSec 贡献文档
• 许可证：MIT 许可证（详见 LICENSE）