配置 API 速率限制的最佳做法

关于速率限制的数据驱动方法

如果没有速率限制，每小时发出数万个请求的单个 CI 集成可能会降低每个用户的整个实例的速度。但设置限制过于积极可能会破坏团队所依赖的集成。数据驱动方法可帮助你找到正确的平衡，首先观察实际使用模式，然后根据收集的数据逐步实施限制。

该方法遵循以下阶段：

       **观察**：启用日志转发和分析 API 流量模式。

       **基线**：启用具有高初始值的速率限制以开始收集速率限制数据。

       **优化**：根据观察到的使用情况调整限制，并与受影响的团队通信。

       **维护**：持续监视和调整一段时间内的限制。

有关通过管理控制台启用速率限制的信息，请参阅配置速率限制。

先决条件

在开始之前，请确保具备：

管理员对管理控制台的访问权限
对日志转发配置的访问权限
能够分析集中式日志
了解组织的 API 使用模式和关键集成

步骤 1：启用日志转发

使用日志转发来集中 API 请求日志进行监视和分析。有关详细信息，请参阅“日志转发”。

分析转发的日志时，请关注以下关键字段：

领域	说明
`Timestamp`	跟踪请求发出的时间
`user` / `gh.actor.login`	标识发出请求的用户或集成
`path_info` / `gh.request.api.route`	要访问的 API 路由
`status`	HTTP 响应代码（例如， `200` 表示成功或 `429` 表示速率限制）
`user_agent`	标识发送请求的客户端或集成

步骤 2：启用限制之前分析 API 趋势

启用速率限制之前，请分析总体使用趋势以建立基线：

        **识别排名靠前的使用者。** 查找发出最大请求数的用户或集成。

        **查看高需求终结点。** 突出显示接收流量最多的 API 路由（`path_info`），并可能受益于优化。

        **检测低效模式。** 请查找系统大量或低效使用的迹象，例如没有缓存的频繁轮询，或冗余请求。

此基线数据将帮助你设置基于实际使用情况而非猜测的速率限制。

步骤 3：启用初始值较高的速率限制

准备好启用速率限制时，请从高阈值开始，以便可以收集其他数据，而不会中断现有工作流。

在管理控制台中，将主要 API 速率限制设置为较高值，例如每小时 25,000 个请求。有关详细信息，请参阅“配置速率限制”。

启用速率限制后，监视 gh.rate_limit 转发日志中显示的字段：

领域	说明
`gh.rate_limit.primary.max`	允许的最大请求数
`gh.rate_limit.primary.remaining`	当前时间段内的剩余请求数
`gh.rate_limit.primary.used`	期间内已发出的请求
`gh.rate_limit.primary.reset`	速率限制期重置时的 Unix 时间戳

步骤 4：优化限制并解决大量使用情况问题

从gh.rate_limit字段中使用数据来做出基于信息的决策：

        **识别接近限额的用户。** 查找经常接近或超过阈值的用户或集成。

        **确定适当的限制。** 根据观察到的使用趋势而不是任意值设置速率限制。

        **与受影响的团队沟通。** 与团队协作，通过请求批处理、响应缓存和条件请求等技术优化 API 使用情况。

随着时间的推移减少限制并进行维护

清楚地了解 API 使用情况后，请逐步降低速率限制，使其与实例的容量和实际使用模式保持一致。监测每次调整后是否有意外中断。

在优化限制时，请与受影响的团队合作。请求批处理、响应缓存和条件请求等技术可以帮助团队减少 API 使用情况。还可以使用 ghe-config 实用工具将特定用户从速率限制中免除。有关详细信息，请参阅“命令行实用程序”。

定期查看速率限制数据，因为随着添加新集成和工作流的发展，使用模式会发生变化。

其他注意事项

        **GraphQL API 限制。** GraphQL API 具有单独的速率限制（默认值：每小时 5000 点），此限制无法通过豁免列表绕过。 有关详细信息，请参阅“[AUTOTITLE](/graphql/overview/rate-limits-and-node-limits-for-the-graphql-api)”。

        **次要速率限制。** 还可以启用辅助速率限制来保护整体服务级别。 有关详细信息，请参阅“[AUTOTITLE](/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-rate-limits#enabling-secondary-rate-limits)”。

延伸阅读

        [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api)

谁可以使用此功能？

在本文中