> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 限流

為每個易被濫用的路由準備的統一限流器。

## 初學者演練

先決條件：閱讀下面的兩個初學者指南，完成 Web 本地設定，並在編輯器的根目錄中開啟此 monorepo。網頁設定屬於`apps/web/.env.local`； Next.js不讀取根`.env`。預設fake模式下的`/dashboard`是無資料庫演示； `/auth` 需要遷移資料庫。

簡而言之：工作區是一個團隊的單獨使用者、資料和設定。伺服器是可信後端；讓提供商金鑰遠離瀏覽器和電話程式碼。遷移是建立或更新表的版本化資料庫更改。人工智慧模型是回答的引擎；型號目錄是伺服器上可用型號 ID 和價格的列表。提供商是一種外部服務，例如人工智慧、電子郵件或計費服務。權利是允許工作區使用某項功能的授權。 Webhook 是一個服務傳送到另一個服務的 URL 的訊息。

1. 在伺服器環境中，為共享生產儲存桶選擇 `RATE_LIMIT_STORE=postgres`，並設定 `PUBLIC_AI_DAILY_BUDGET_MICROUNITS=0` 以保持公共 AI 停用。

2. 僅將 `TRUSTED_PROXY_COUNT` 設定為附加轉發標頭的受控代理的確切數量；不要複製 `1` ，除非您的主機也是如此。

3. 驗證被拒絕的請求返回重試安全錯誤。如果例項之間的限制不同，請檢查它們是否共享 Postgres。

對於自定義程式碼，請從提供的 `prompts/README.md` 開始，然後複製最接近的提示：對於應用程式螢幕為 `prompts/new-app-screen.md`，對於公共頁面為 `prompts/new-landing-page.md`。對於伺服器、資料庫或提供商工作，請為您的編碼代理提供本指南的任務，並要求其讀取 `AGENTS.md`、`.ai/PROJECT_CONTEXT.md` 和匹配的 `.ai/` 映象；檢查此處指定的確切原始檔；列出檔案並在編輯前進行檢查；保留工作區所有權和僅限伺服器的機密；並向您展示差異。告訴它您想要的行為、輸入和輸出欄位、允許的角色、預期的成功和錯誤以及測試帳戶、提供程式或裝置。使用樣本值；永遠不要貼上真正的秘密。

[開始之前](https://supastack.dev/zh-tw/docs/web/before-you-start.md)

[終端基礎知識](https://supastack.dev/zh-tw/docs/web/terminal-basics.md)

[網路本地設定](https://supastack.dev/zh-tw/docs/web/ship-in-5-minutes.md)

[座席提示和專案記憶體](https://supastack.dev/zh-tw/docs/web/agents.md)


## 選擇限制器商店

`RATE_LIMIT_STORE` 是記憶體或 postgres。未設定時，生產環境選擇 Postgres，其他環境選擇記憶體。共享 `rate_limit_bucket` 行協調多個伺服器；儲存故障當前無法開啟以保持 API 可用性。

工作空間/使用者 AI 提交限制和公共 API/MCP 限制器保護其單獨的表面。新增路由時保留現有的特定於呼叫者的儲存桶鍵。


## 僅信任受控代理躍點

`TRUSTED_PROXY_COUNT` 的範圍為 0–10，並計算附加 `x-forwarded-for` 的反向代理。零不信任任何內容並使用共享的未知儲存桶；一個受控代理通常需要 1。不正確的計數會讓不受信任的轉發值影響限制器。


## 限制匿名提供商的支出

`PUBLIC_AI_DAILY_BUDGET_MICROUNITS=0` 停用公共 AI 呼叫。配置的非負每日 UTC 上限在提供商呼叫之前保留平臺支出，並且與每個工作區的預算分開。在任何計費提供商嘗試之前測試併發預訂、重置邊界和拒絕。

```
RATE_LIMIT_STORE=postgres
TRUSTED_PROXY_COUNT=1
PUBLIC_AI_DAILY_BUDGET_MICROUNITS=0
```


## 安裝與配置

rate-limit-runtime 提供接入各易濫用介面的共享限流器 —— 已釋出的預設是 apiV1Limiter（600 次/分鐘）與 authLimiter（300 次/分鐘）。限額按身份加路由桶計鍵，以帶 Retry-After 的可重試 429 作答，而不是籠統錯誤。

把現有 limiter 擴充套件到新的易濫用端點 —— 登入、OTP、結賬、任務提交、金鑰建立 —— 而不是發明各自為政的每路由計數器。

```
export const apiV1Limiter = createNamedRateLimiter("api-v1", 600, 60_000);
export const authLimiter = createNamedRateLimiter("auth", 300, 60_000);
```


## 實現流程

仔細選擇計鍵：已認證操作按使用者、公開流量按 API 金鑰、匿名端點萬不得已才按 IP。合理的突發得到 Retry-After；攻擊撞上天花板。

易濫用路由上的限流器保持 fail-closed —— 儲存不可達時，寧可拒絕昂貴操作，也不要無界放行。


## 驗證與排障

打滿一個限流器直到返回帶合理 Retry-After 的 429，驗證不同工作區有獨立桶，並確認視窗過後突發恢復為成功。記錄拒絕日誌時不要攜帶請求的敏感負載。


## 下一篇

[AI 與後臺任務](https://supastack.dev/zh-tw/docs/modules/ai.md)