49图库接口限流：单 IP 每分钟 60 次

2026 年 8 月 23 日，49图库对只读统计接口启用限流。规则为单 IP 每分钟 60 次、单路径每分钟 20 次，超限返回 429 并在响应头给出建议重试秒数。设置依据是 8 月的真实请求分布：正常使用者峰值每分钟 14 次，而个别脚本单分钟请求超过 2,000 次。

接口原本没有任何频率限制。8 月中旬的一次流量分析显示，某个 IP 在 6 小时内请求了 41 万次明细导出，占总请求量的 12%，导致同时段其他使用者的 P95 响应时间从 86 毫秒升到 640 毫秒。这次事件没有造成数据泄漏，但确实影响了正常使用。

加固的思路是先分清两类请求：人在页面上点出来的请求，和在脚本里循环发出的请求。前者有停顿、有交互、路径分散；后者节奏均匀、路径集中、并发高。限流规则要贴着前者的上限设置，让后者先撞线。

为什么按 IP 和路径双维度计数

只按 IP 计数的问题是共享出口。一栋办公楼、一所学校的出口 IP 可能对应上百人，单 IP 每分钟 60 次会误伤。加上路径维度后，正常使用者往往分散在检索、走势、明细三个路径上，而脚本通常集中打一个导出路径，双维度能更准确地区分。

计数采用滑动窗口，不做固定整分钟重置。固定窗口在边界处允许两倍突发，滑动窗口把 60 次平摊到任意 60 秒内，更接近真实使用节奏。计数状态保存在内存中，单节点失效不影响全局，代价是集群内各节点独立计数，实际阈值会略宽于标称值。

计数使用滑动窗口而不是简单的固定窗口。固定窗口在整分钟边界允许两倍突发，例如 59 秒发 60 次、下一秒再发 60 次，实际一分钟内出现 120 次。滑动窗口按最近 60 秒滚动统计，规则与页面上写的“每分钟 60 次”一致，使用者不必理解窗口实现就能预期自己的配额。

限流规则要能解释给使用者听。说不清为什么被拦，规则就站不住脚。—— 49图库后端负责人 郭文轩

阈值与 8 月实测数据

60 次每分钟的取值来自使用分布的第 99.7 百分位。8 月抽样 3.2 万个活跃会话，每分钟请求次数的中位数为 3 次，第 95 百分位为 9 次，第 99 百分位为 14 次。取 60 次，是给批量核对留出四倍余量，同时远低于脚本的请求节奏。

超限响应固定为 429，响应体写明限制维度与建议重试秒数，响应头带剩余配额。这样脚本作者能自行退避，而不是反复重试加重负担。8 月下旬启用后，脚本类请求占比从 12% 降到 0.3%，P95 回到 92 毫秒。

超限响应固定为 429，响应体包含三个字段：错误码、限制维度（IP 或路径）、建议重试秒数。响应头同时给出剩余配额与重置时间。这四项信息足以让脚本自行退避，不需要查阅文档。页面端的请求遇到 429 时，会显示一句“操作过快，请稍候”，并自动在建议秒数后重试一次。

页面请求与接口请求共用同一份 IP 计数。使用者在页面上连续操作时，浏览器发出的请求也会占用配额，因此单路径阈值定在 20 次而不是更低。批量操作时页面会提示“正在为你合并请求”，把同一秒内的多次点选合并成一次查询，既省配额也省等待。

正常使用者会不会被误伤

启用首周收到 2 例误伤投诉。一例是使用者在同一分钟里连续切换了 21 个期号，触发了单路径 20 次的上限；另一例是办公室共享出口，多人同时导出。两例都在 429 响应里看到了重试秒数，等待十几秒后恢复正常，没有丢数据。

针对这两例，我们把单路径阈值从 15 次提到 20 次，并在页面上加了轻提示：连续快速切换时提示“稍等一秒”。对于机构使用者，提供了按账号提升配额的申请入口，需要说明用途，审核后按周设置上限。

搜索引擎爬虫不走这套计数。识别方式是 UA 加反向解析双重校验，通过后按独立配额放行，避免正常收录被误拦。机构使用者可以提交配额申请，说明用途与预估调用量，审核通过后按周设置上限，到期自动恢复默认值，不需要反复申请。

被拦一次不可怕，可怕的是不知道为什么被拦、也不知道等多久。把这两个信息给清楚，多数人能接受。—— 49图库产品负责人 李承宇

限流规则与响应格式已写入开发文档，包含 429 的响应示例和退避建议。如果业务上确实需要更高的调用频率，可通过关于页的联系方式提交申请，说明用途与预估量，我们按周评估。下一步计划把配额使用情况做成可查询的页面，方便机构使用者自查。