速率限制與反向代理Rate limiting and proxies

採 token bucket：以固定速率補充額度，容許短暫叢發，持續超量時回 429 並附 Retry-After 標頭。預設每個來源 IP 每分鐘 120 次、突發 30 次。

rate-limit:
  enabled: true
  per-ip-per-minute: 120
  burst: 30
  global-per-minute: 0      # 所有來源合計，0 = 不限
  exempt-authenticated: true
  exempt-ips: ["127.0.0.1"]

反向代理後方

掛在 Cloudflare／Nginx／Apache 後方時，所有訪客的來源都會是代理主機，速率限制與 IP 豁免都會失準。開啟後改從代理標頭取得真實 IP：

real-ip:
  enabled: true
  trusted-proxies:
    - "cloudflare"        # 展開為官方公布的所有區段
    - "127.0.0.1/32"

代理標頭可由用戶端任意偽造，因此只有當連線來源本身屬於 trusted-proxies 時才會被採信。 X-Forwarded-For 由右往左掃描，略過可信代理後取第一個非可信位址；直接取最左邊會被偽造的前綴欺騙。

Token bucket: credit refills at a fixed rate and short bursts are allowed, but sustained overuse returns 429 with a Retry-After header. The default is 120 requests per minute per source IP with a burst of 30.

rate-limit:
  enabled: true
  per-ip-per-minute: 120
  burst: 30
  global-per-minute: 0      # across all sources, 0 = unlimited
  exempt-authenticated: true
  exempt-ips: ["127.0.0.1"]

Behind a reverse proxy

Behind Cloudflare, Nginx or Apache every visitor appears to come from the proxy, which throws off both rate limiting and IP exemptions. Turn this on to read the real address from proxy headers:

real-ip:
  enabled: true
  trusted-proxies:
    - "cloudflare"        # expands to every published range
    - "127.0.0.1/32"

Proxy headers are trivially forged, so they are only trusted when the connection itself comes from trusted-proxies. X-Forwarded-For is scanned right to left, skipping trusted proxies to reach the first address that is not one — taking the leftmost entry would be fooled by a forged prefix.