6 分鐘閱讀 | 最後修改: 0001-01-01, 0:00:00 am

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 中呼叫

# 驗證和停用

很樂意聽到您的反饋，請與我們聯絡 👋

成功傳送訊息！