> ## 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/docs/web/before-you-start.md)

[终端基础知识](https://supastack.dev/zh/docs/web/terminal-basics.md)

[网络本地设置](https://supastack.dev/zh/docs/web/ship-in-5-minutes.md)

[座席提示和项目内存](https://supastack.dev/zh/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/docs/modules/ai.md)