遇到 429 Too Many Requests（请求太频繁）怎么办？

1. 先判断：你遇到的是哪种 429？

429 Too Many Requests
  ↓
看报错 URL 域名
  ├─ docker.xuanyuan.me → 免费版限流（见第 2 节）
  └─ 专业版域名（*.xuanyuan.run / 专属域名等）→ 专业版限流（见第 3 节）
       ↓
     等待 24 小时自动解封（无法人工提前）
       ↓
     自查脚本与配置
       ↓
     正常高频业务 → 了解企业版（见第 5 节）

限额均为 API 请求次数，不是 docker pull 命令次数。各版本完整对比见 免费版、专业版与企业版区别。

2. 免费版限流怎么处理

报错 URL 包含 docker.xuanyuan.me 时，一般为免费版限流。每次限流持续约 6 小时，冷却后自动恢复。

1. 暂停短时间内的重复 compose up / pull 重试，等待自动恢复
2. 生产或团队场景建议升级专业版，获得更高限额与更稳定服务
3. 更多规则见 免费版限流说明

典型场景：标签不存在导致回退到免费版

若你使用的是专业版，却仍看到 docker.xuanyuan.me，常见原因是镜像标签不存在于专业版可用范围，Docker 客户端回退到免费版域名后触发限流：

处理要点：核实镜像标签是否存在；排查本地或 compose 是否配置了免费版镜像源，若存在建议删除或调整优先级，避免回退后触发免费版 429。

3. 专业版限流怎么处理

专业版在 24 小时内 API 请求数超过 1,000 次/小时或 10,000 次/天 时，系统自动限流（HTTP 429），24 小时后自动解除，无法人工提前解封。一次 docker pull 或 compose up 会拆分为多次 API 请求（manifest 查询、多架构匹配、layer HEAD/GET、失败重试等），一次 compose 拉取常产生几十甚至上百次请求。

常见触发场景

• • 多台服务器或 CI/CD 流水线并发拉取，累计请求量过大
• • 脚本频繁请求不存在的镜像，或批量拉取时未做错误处理、无退避重试
• • 对同一仓库大量 tag 反复查询 Manifest（如批量同步 rancher/*），单次批量任务就可能超过每小时请求上限

建议处理步骤

1. 等待解封：限制 24 小时后自动解除，解封前无法通过工单提前解封。
2. 自查程序：检查批量脚本、CI 流水线是否存在对同一 Manifest 的重复请求、紧密重试循环、未去重的 tag 列表等。若确认是 Bug，修复后再恢复拉取。
3. 优化拉取：部署本地或内网镜像缓存、合并并发任务、为失败重试增加退避间隔，并只拉取确实需要的 tag。
4. 确认镜像与配置：验证镜像路径与标签正确；检查 daemon.json、代理及多客户端并发是否导致重复请求。
5. 正常高频业务：若排查后确认为合理业务需求，专业版限额不可提升，可了解 企业版方案（见第 5 节）。

附注：若急需使用且手头有其他未受限账户，可临时切换；同时等待解封并修复配置。若有疑问可 提交工单，说明账户、发生时间、镜像名称及使用场景（个人/CI/CD/批量部署等）。

4. 常见报错原文对照

专业版限流时，客户端可能返回以下 JSON 之一。任一形式均表示账户已被风控限流，按第 3 节处理即可。

5. 高频业务与企业版

专业版设有固定的每小时/每天请求上限且不可提升。若你的业务属于批量同步、持续集成、多节点集群部署等天然高频场景，升级企业版可避免反复触达专业版上限。

• • 不设专业版那样的每小时请求上限，默认按分钟级配额计量，并可按需付费扩容
• • 2 TB 流量包 2000 元起购，按实际用量灵活扩展
• • 更适合批量拉取、CI/CD 流水线、大规模集群发布等持续高频访问场景
• • 提供专属客服与更高调度优先级，便于长期稳定运行

版本能力完整对比见 免费版、专业版与企业版区别。如需评估流量规模与合适方案，欢迎 提交工单联系我们。

6. 相关链接

• • 免费版、专业版与企业版区别
• • 免费版限流说明
• • 提交工单咨询