入口限流与访问限制

更新日期:2026-11-20。当前API域名为https://api.budyoo.cn,公网经过ESA后以HTTPS回源Nginx,已完成证书与可达性检查;Java上游仅绑定服务器回环地址。API位于深圳唯一正式部署环境,目前处于上线前阶段,实际运行配置仍为dev;没有独立测试服。以下是当前生效的起始限额,App正式开放、客户端验收和容量验证另行维护。

请求频率

范围 持续速率 允许突发额度
全部接口,同一来源IP 20次/秒 额外40次
整个API入口 100次/秒 额外100次
登录与会话接口,同一IP 5次/秒 额外10次
申请手机号/邮箱验证码,同一IP 1次/秒 额外3次
OSS直传申请、确认、取消及媒体凭证JSON,同一IP 共用2次/秒 额外4次
OSS下载授权JSON,同一IP 10次/秒 额外10次
WebSocket建立连接,同一IP 2次/秒 额外6次

使用漏桶限速,突发额度内立即处理,超出直接返回HTTP429。App专用接口同时受全局及普通IP限额约束;云侧CDN回调使用独立精确入口,见下文。以上不是严格“某一秒只能发固定数量”,持续速率与突发额度共同生效。

此前验证码的账号/安装/IP小时额度、60秒冷却、5次校验上限,以及上传业务额度继续生效。入口限流不替代业务校验。

并发、大小与超时

  • 同IP最多40个正在处理的请求,整个入口最多500个;OSS直传、下载授权及媒体凭证JSON控制面同IP各最多4个,WebSocket同IP最多20条。这里的并发数统计正在处理请求的连接,不等同于所有已建立TCP连接;慢请求另受超时控制。
  • 普通JSON正文最大512KiB;OSS申请、确认、取消、下载授权及媒体凭证控制面整包(包括JWE外层)最大16KiB,缓冲也为16KiB。旧App文件上传POST已移除,在读体前返回410;App multipart、image、video、audio和application/octet-stream请求在其他路径同样返回415。文件实际只发OSS,仍受头像/相册10MiB、动态图20MiB、明信片照片/证据5MiB、视频/语音100MiB的签名及业务限制。后台上传独立鉴权和限额。单个请求头或请求行最大8KiB,按需最多4个大头缓冲区。
  • 请求头读取超时10秒,正文连续读取间隔15秒;普通空闲keep-alive15秒,普通上游读取30秒,OSS确认上游读取160秒,用于内网验证与处理已上传文件。WebSocket读取超时90秒,与应用心跳配合。
  • 同一公司/校园/运营商出口可能共享IP;客户端避免无间隔重试。出现正常请求被限流时,由服务端依据日志与容量调整,不能改传X-Forwarded-For绕过。

超限响应

HTTP429,响应包含Retry-After: 1、Cache-Control: no-store、X-Budyoo-Gateway: nginx。中文示例:

{
  "code": "TOO_MANY_REQUESTS",
  "message": "请求过于频繁,请稍后重试。",
  "data": null,
  "errors": []
}

网关按Accept-Language首个语言前缀提供中文、英文、日文、韩文,未知语言默认英文;业务内部继续使用完整的语言解析规则。客户端按HTTP状态与code处理,不能根据message文本判断。

旧App上传入口返回HTTP410/UPLOAD_ENDPOINT_REMOVED,其他App文件MIME请求返回415/UNSUPPORTED_MEDIA_TYPE,二者均在正文读取及JWE解密前拒绝,不调用Java上游。超大正文返回HTTP413/PAYLOAD_TOO_LARGE。被管理员临时封禁的IP或CIDR后续请求返回HTTP403/IP_BLOCKED,到期后解除;这不是用户Token失效,不应自动清空账号登录态。封禁不主动断开既有WebSocket连接。当前实现秒级拒绝与人工临时封禁,不会因为一次429自动永久封禁IP。

加密与重试

Nginx在Java解密之前处理请求,入口拒绝返回普通JSON,即使本次请求使用JWE也可能收到明文429/403/410/413/415。它不是经过JWE认证的业务结果:客户端可据HTTP状态暂停重试或显示本地网络提示,但不能把该明文响应冒充已验证的加密业务数据。已进入Java的业务响应继续按AES/JWE协议加密。

不要自动重试创建、注册完成、刷新Token等写操作;需要重试时按对应业务规则处理。网关限流不会解密、修改或记录Token和业务正文。

当前防护范围

Nginx只对已核对的ESA回源网段采用ESA覆写的ali-real-client-ip,随后向Java重新生成转发头。其他来源仍以真实TCP连接IP为准,不能靠自报X-Forwarded-For、X-Real-IP或ali-real-client-ip改变身份、地区或限流键。受信网段只配置在API的HTTPS虚拟主机,不扩展到后台、文档或官网。

这套策略减少接口洪泛、过多并发和超大请求进入应用的机会,不代表已经具备大流量DDoS清洗、WAF或自动攻击识别能力。HTTPS/WSS状态仍以加密与认证为准。

ESA接入与香港中转边界

api.budyoo.cn 已接入 ESA,由 ESA 边缘节点统一处理公网 TLS、动态转发和 /ws/v1/realtime Upgrade,再回源到本机 Nginx;Java 继续只监听回环地址。真实客户端 IP 头仅在连接来自已确认的 ESA 回源地址时生效,不能为了“恢复海外真实 IP”而信任任意 X-Forwarded-For 或 ali-real-client-ip。

Google、FCM 等外部服务规划走单独的香港 ECS 中转节点。中转节点是服务端出站代理,不能承载用户 API/WebSocket,也不能对公网开放通用转发。香港服务器尚未购买或配置;上线前要为每个供应商固定目标、使用 mTLS/签名鉴权并配置健康检查、失败策略、审计脱敏和费用告警。2026-11-20已部署ESA客户端IP信任配置;此清单是代理头信任边界,不是只允许ESA访问443端口的防火墙规则。后台、文档和官网共用入口,API直接访问仍受原Nginx限制。边缘证书签发及API DNS切换状态见安全说明。香港节点按用户计划在开发完成后再购买。

验证范围:服务器隔离Nginx50项检查通过,覆盖五种退役入口、编码与归一化路径、chunked和Expect、四语410、文件MIME415、拒绝时无上游请求及临时文件、16KiB控制面与并发限额、原媒体GET、后台独立上传及既有全局限流/超时/IP封禁。实际受信HTTPS通过仅发送1GiB声明请求头验证五入口410,上游调用0,文件正文0字节;Java过滤器和真实Servlet验证及全量结果见当前交付说明。未执行容量压测或云侧DDoS清洗验收。

OSS下载授权

/api/v1/media/downloads仅接收≤16KiB的JSON/JWE控制报文,每IP10r/s、burst10、4并发,仍叠加普通及整站限制。授权按已审公开状态返回长期OSS地址或私密短效OSS GET地址,不经Nginx传送普通媒体正文;尚未适配的原媒体GET保留原行为。

CDN媒体入口

官网、后台和文档主题的公开资源使用独立static.budyoo.cn,只在/site-assets/缓存允许发布的资源,4xx/5xx不缓存,其余路径绕过缓存。静态源站位于文档虚拟主机,不给Java增加公网监听,不扩展API代理头信任,也不提供管理员API或业务媒体。详见网站静态资源CDN。

固定媒体地址与远程鉴权已于2026-11-19在深圳正式部署环境(上线前阶段,当前运行配置为dev)启用。POST /api/v1/media/credentials仍走App身份、公共头、HTTPS和JWE,不接收媒体正文;共用上传控制面2r/s/burst4及4并发,整包和缓冲16KiB。其他部署CDN开关关闭时合法会话得到404,不为OSS签发媒体凭证。

CDN专用GET /api/v1/media/cdn/authorize当前已在公网HTTPS入口启用;关闭模式仍由Nginx及Java拒绝。启用模板仅接受GET、正文上限1KiB,不向Java转发正文、Content-Length或App Authorization,使用独立回调秘密与媒体凭证鉴权。回调不套普通App每IP请求速率:云节点IP不能等同于终端用户IP,终端IP由CDN可信自定义头覆盖;CDN限频与回调容量需单独验收。成功只有200,其他状态和3秒超时由CDN拒绝。独立回调不放宽普通App API的认证或JWE。

2026-11-17服务器同模板的CDN关闭/隔离开启模式15项检查通过,覆盖默认拒绝无上游调用、GET精确路由、POST/HEAD拒绝、去掉App凭证及正文头、1KiB回调上限、16KiB凭证上限和限频。2026-11-19另完成真实CDN公网15项检查,包括缓存HIT后鉴权、跨账号与退出后拒绝、HEAD和Range;详情见CDN契约。同日已配置媒体域名带宽/下行流量/边缘请求数告警及CDN、OSS产品日费用预警,配置回读通过,未制造超限流量验证通知送达。按用户确认仅告警,不启用自动停用;告警不代替限频或费用硬上限,容量及设备链路仍未验收。