CrowdSec 完整教學 2026：1.5 萬星開源 IDS/IPS＋WAF，用「群眾外包」的黑名單把掃描器擋在門外（Linux／Docker 安裝、Bouncer 選擇、AppSec 四步啟用）

直接答案：CrowdSec 是什麼？

CrowdSec 是一套 MIT 授權的開源入侵偵測與防護系統（IDS/IPS）：它讀取你伺服器的 log 與 HTTP 請求，判斷哪些行為是攻擊，產生「封鎖某個 IP」的決策，再交給防火牆或反向代理去執行。 它的差異化在於「群眾外包」——你回報的攻擊會進入社群黑名單，別人被攻擊的 IP 在你被攻擊之前就先被擋掉。

• GitHub 星數：15,233 顆（2026-10-20 以 API 查詢）
• 最新版本：v1.8.1（2026-09-03 發布）
• 授權：MIT（偵測規則在 Hub 上同樣是 MIT）
• 語言：Go；支援 Linux、Windows、Docker、Kubernetes

為什麼會有這個需求？先看痛點

多數人第一次認真看待這件事，是因為 VPS 的 auth.log 長這樣：

Failed password for root from 45.xx.xx.xx port 40222 ssh2
Failed password for root from 45.xx.xx.xx port 40311 ssh2
Failed password for root from 45.xx.xx.xx port 40987 ssh2

一整排、同一個 IP、每秒好幾次。傳統做法是裝 fail2ban，但它有幾個結構性限制：

如果你只是要「SSH 被撞就封 IP」，fail2ban 完全夠用。會想換 CrowdSec，通常是因為你開始同時跑 Web 服務，而且希望拿到「別人被打過」的那份情報。

一表看懂：CrowdSec 的規格與元件

運作流程：從一行 log 到一個封鎖

不需要圖也看得懂，因為它就是一條流水線：

第 ⑥ 步是很多人卡住的地方：Security Engine 本身不會封鎖任何東西。官方文件用警告框寫得很清楚——沒裝 Bouncer，你只會有一堆 alert，攻擊照樣進來。

安裝（Linux，官方指令原文）

步驟 1：加入官方套件庫

curl -s https://install.crowdsec.net | sudo sh

這是官方推薦做法。若你的環境不允許 curl | sh，文件另有手動加 GPG key 與 sources.list.d 的完整步驟（Deb／RPM 分開寫）。

步驟 2：安裝 Security Engine

sudo apt update
sudo apt install crowdsec

安裝過程會互動式詢問要不要加入 CrowdSec Console（可略過，之後再用 cscli console enroll 補）。

步驟 3：裝 Bouncer（必要）

要擋基礎設施（SSH、資料庫、SMTP）：

sudo apt install crowdsec-firewall-bouncer-iptables

先確認你的系統用 iptables 還是 nftables：iptables -V，輸出含 nf_tables 就是 nftables，改裝 crowdsec-firewall-bouncer-nftables。

要擋 Web 應用，改用 具備 WAF 能力的 Bouncer：

Nginx Bouncer 的系統依賴（官方列出的原文）：

sudo apt install nginx lua5.1 libnginx-mod-http-lua luarocks gettext-base lua-cjson
sudo apt install crowdsec-nginx-bouncer

裝完先驗證，別急著調參數

CrowdSec 最有價值的地方是它的可觀測性，cscli 三條指令就能確認「有沒有在做事」：

# ① 有沒有讀到 log？
sudo cscli metrics show acquisition

# ② 有沒有產生決策（封鎖）？
sudo cscli decisions list

# ③ 有沒有觸發告警？從哪個 scenario 來？
sudo cscli alerts list

metrics show acquisition 的輸出長這樣（官方範例）：

Acquisition Metrics:
╭────────────────────────────────┬────────────┬──────────────┬────────────────┬────────────────────────┬───────────────────╮
│             Source             │ Lines read │ Lines parsed │ Lines unparsed │ Lines poured to bucket │ Lines whitelisted │
├────────────────────────────────┼────────────┼──────────────┼────────────────┼────────────────────────┼───────────────────┤
│ file:/var/log/nginx/access.log │ 3          │ 3            │ -              │ -                      │ 3                 │
╰────────────────────────────────┴────────────┴──────────────┴────────────────┴────────────────────────┴───────────────────╯

判讀重點：

• 整張表是空的 → 沒有 log 來源被監控。CrowdSec 是在啟動時 tail log，若服務啟動後該 log 沒有新流量，也可能看不到資料，先製造一點流量再看。
• Lines unparsed 一直很高 → 你的 log 格式跟 parser 對不上（常見於自訂 Nginx log_format）。
• Lines whitelisted 等於 Lines read → 你的流量全被白名單吃掉了，通常是私有網段或反向代理轉發造成。

想單獨測試某一行 log 有沒有被正確理解，用 cscli explain：

grep 192.168.1.1 /var/log/nginx/access.log | tail -n 1 | sudo cscli explain -f- --type nginx

它會逐層印出 parser 命中了哪些規則——這是 debug 規則問題最快的方法，比讀文件快十倍。

加值功能：AppSec（WAF）四步啟用

AppSec 把 CrowdSec 從「看 log 的 IDS」變成「會擋請求的 WAF」，而且底層是 Coraza，所以 ModSecurity 的 SecLang 規則與 OWASP CRS 可以直接載入。

官方 Nginx／OpenResty 的 quickstart 是「四個 copy-paste」，原文如下：

① 安裝規則集

sudo cscli collections install \
    crowdsecurity/appsec-virtual-patching \
    crowdsecurity/appsec-generic-rules

• appsec-virtual-patching：已知 CVE 的虛擬補丁規則，每天自動更新
• appsec-generic-rules：常見攻擊樣式

② 開啟 AppSec 資料來源

sudo mkdir -p /etc/crowdsec/acquis.d
sudo tee /etc/crowdsec/acquis.d/appsec.yaml > /dev/null <<'EOF'
appsec_configs:
  - crowdsecurity/appsec-default
labels:
  type: appsec
listen_addr: 127.0.0.1:7422
source: appsec
EOF
sudo systemctl restart crowdsec

⚠️ listen_addr 一定要留在 127.0.0.1。官方特別警告：AppSec 元件絕對不能對外網開放，它只該被本機的 Web 伺服器查詢。

③ 讓 Bouncer 指向 AppSec

sudo sed -i 's|^APPSEC_URL=.*|APPSEC_URL=http://127.0.0.1:7422|' \
    /etc/crowdsec/bouncers/crowdsec-nginx-bouncer.conf
sudo systemctl restart nginx

④ 驗證

curl -I http://localhost/.env

正確結果是 HTTP/1.1 403 Forbidden——.env 是典型的「忘記刪掉的憑證檔」，vpatch-env-access 規則會直接擋掉。再看統計：

sudo cscli metrics show appsec

這段流程有個容易誤會的點：只裝規則不會生效。你必須同時啟用 AppSec 的 acquisition 資料來源、重啟 CrowdSec、並讓 Bouncer 指向同一個 listen_addr。三者缺一，curl 就會回 200。

白名單：不做這件事一定會出事

CrowdSec 預設已白名單私有網段，但你自己的固定 IP 沒有。一旦被誤 ban，而且你用的是 iptables／nftables Bouncer，你會連 SSH 都進不去。這不是危言聳聽，是文件明講的風險。

1.6.8 版之後最推薦的做法是 AllowList，改完立即生效、不必重啟：

sudo cscli allowlist create my_allowlist -d 'created from the docs'
sudo cscli allowlist add my_allowlist 203.0.113.10        # 單一 IP
sudo cscli allowlist add my_allowlist 203.0.113.0/24      # CIDR
sudo cscli allowlist inspect my_allowlist

如果被 ban 的是你自己，先自救再研究原因：

sudo cscli decisions delete --ip 203.0.113.10

AllowList 的價值在於它會同時作用在 AppSec、scenario overflow、Console blocklist 等所有元件，比在單一 parser 裡寫 whitelist 乾淨得多。

需要「特定 URI 不要觸發」這種細緻規則時，才回頭寫 parser 白名單（/etc/crowdsec/parsers/s02-enrich/01-my-whitelist.yaml），而且改完要重啟。例如放行健康檢查：

name: my/whitelist
description: "Whitelist events with GET /health"
filter: "evt.Meta.service == 'http' && evt.Meta.log_type in ['http_access-log', 'http_error-log']"
whitelist:
  reason: "GET /health"
  expression:
    - "evt.Meta.http_verb == 'GET' && evt.Meta.http_path == '/health'"

Docker 部署：三個一定要記住的細節

官方 docker run 指令（原文）：

docker run -d \
  --name crowdsec \
  --volume /etc/crowdsec:/etc/crowdsec \
  --volume /var/lib/crowdsec/data/:/var/lib/crowdsec/data/ \
  --volume /var/log:/var/log:ro \
  --env COLLECTIONS="crowdsecurity/linux" \
  -p 127.0.0.1:8080:8080 \
  crowdsecurity/crowdsec:latest

Compose 版本的核心片段：

crowdsec:
  image: crowdsecurity/crowdsec
  restart: always
  ports:
    - 127.0.0.1:8080:8080
  environment:
    COLLECTIONS: "crowdsecurity/nginx"
    GID: "${GID-1000}"
  depends_on:
    - "reverse-proxy"
  volumes:
    - ./crowdsec/acquis.yaml:/etc/crowdsec/acquis.yaml
    - logs:/var/log/nginx
    - crowdsec-db:/var/lib/crowdsec/data/
    - crowdsec-config:/etc/crowdsec/

三個必記細節：

1. /var/lib/crowdsec/data 一定要掛 volume。1.7.0 之後官方明講沒掛就拒絕啟動。
2. GID 要對齊 log 檔的群組，否則容器讀不到 /var/log/nginx。
3. -p 127.0.0.1:8080:8080：Local API 綁在 loopback，不要寫成 8080:8080 全開。

六個文件級踩坑（先看過再動手）

與 fail2ban／ModSecurity 的差異對照

實務上三者不互斥：CrowdSec 的官方定位就是「你已經有 ModSecurity 規則？直接餵給它」。而它的 IP 信譽層，是 fail2ban 完全沒有的東西。

費用與治理：哪些免費、哪些要錢

• 軟體本身：MIT，免費，自架。
• 社群黑名單（CAPI）：免費，但是交換關係——你回報攻擊訊號，才換得到別人的名單。
• CrowdSec Console：可免費註冊；Premium 的功能（進階 stack 管理、告警暴增通知、延長告警保留、集中清單管理、SaaS API 等）需付費。
• 價格：官網 pricing 頁目前只列功能區塊，沒有公開數字（2026-10-20 查證）。第三方威脅情報（Platinum Blocklists、Live Exploit Tracker、IP Reputation API）另外計價，需詢價。
• 官方另有「Emergency bug fixes」「Premium service and support」以 $1K／月 計價的加購項。

已知限制與本文沒做的事

這一段是本站產品文的固定段落，請務必看完再決定要不要跟：

1. 本文未在生產環境實測。 所有指令取自 CrowdSec 官方文件原文（Linux 安裝、Nginx Bouncer、AppSec quickstart、白名單、Docker），版本為 v1.8.1／firewall bouncer v0.0.36／nginx bouncer v1.2.3（2026-10-20 以 GitHub Releases API 查詢）。沒有實際跑過一輪流量測試，因此效能數字（每秒可處理多少請求、誤擋率）本文完全不給——給了也是猜的。
2. 價格未公開：Console Premium 與威脅情報的實際費用需詢價，官網沒有標價。
3. Console 需要帳號：要用集中管理或社群黑名單可視化，得註冊 CrowdSec Console（可 Google 帳號登入）。不想註冊也能純 CLI 運作，但會少掉跨機器視圖。
4. 需要自己決定「誰可以封」：CrowdSec 不會幫你判斷「這個 IP 是不是你的合作夥伴」。上線前一定要先把固定 IP、監控系統、金流 callback 來源加進 AllowList，否則第一次誤 ban 就會出事。
5. 硬體門檻低但要花注意力：它不是裝完就忘的工具，parser 對不上、scenario 太敏感都需要調。

誰適合？誰不需要？

適合

• 有對外服務的 VPS／自架站（Nginx、Caddy 前面的各種服務），想加一層 IP 信譽＋WAF
• 一次管很多台機器，想要一個地方看所有告警
• 已經在用 fail2ban，但想要「別人被打過的名單」與 HTTP 層防護
• 有 WordPress 或自架後台，想補虛擬補丁（vpatch）擋已知 CVE

不需要

• 只跑一台關閉對外連線的內網機器
• 前面已經有 Cloudflare／CDN 的 WAF 且不想多一層維運
• 完全不想調參數、希望「裝了就好」——這類工具都需要看 metrics 調

站內延伸閱讀

• Caddy 完整教學 2026：75K 星自動 HTTPS 網頁伺服器 — 如果你用 Caddy 當反向代理，先架好入口再來談防護
• Cloudflare Tunnel 完整教學 2026：不開防火牆 port 也能對外 — 走 Tunnel 的架構下，封鎖點該放在哪裡
• Uptime Kuma 完整教學 2026：91K 星自架監控神器 — 搭配使用：一個管可用性，一個管「誰在打你」
• Proxmox VE 9 完整教學 2026 — 多台 VM 的環境，Security Engine 與 Bouncer 可以分開放
• Vaultwarden 完整教學 2026：自架 Bitwarden 相容密碼管理器 — 自架服務的另一個高風險入口，值得同步加防護

資料來源與查證方式

• CrowdSec 官方文件：Linux 安裝、Docker 安裝、Bouncer 清單、Nginx Bouncer、AppSec 元件介紹、Nginx／OpenResty AppSec Quickstart、Acquisition、Whitelists／AllowLists、Firewall Bouncer — docs.crowdsec.net
• CrowdSec GitHub crowdsecurity/crowdsec README（與 fail2ban、ModSecurity／Coraza 的比較段落）— GitHub
• CrowdSec 官網 pricing 頁（功能區塊，未公開價格）— crowdsec.net/pricing
• 星數、授權、版本號以 GitHub API 於 2026-10-20 查詢：crowdsecurity/crowdsec 15,233 星／MIT／v1.8.1（2026-09-03）

取材順序依本站慣例：官網 → 官方文件 → GitHub API，不使用 NotebookLM——產品官網與官方文件本身就是一手來源，多一層彙整反而失真。