API 使用限制

本文适用于 RTM 2.x 客户端 SDK 和 RESTful API，介绍各层级的使用限制、超出限制后的行为，以及容量规划时的估算方法。

快速导航Copy Anchor Link

限制层级Copy Anchor Link

RTM 的限制分为四层。上层限制约束总量，下层限制约束单个对象；同一次调用可能同时受到多层限制。

限制类型Copy Anchor Link

1. 账号级限制Copy Anchor Link

2. 项目级限制（App ID）Copy Anchor Link

2.1 怎么估算你的 PCUCopy Anchor Link

RTM 的限制和计费都以 PCU 为单位，而业务指标通常只有 DAU、房间数或课堂数。按业务形态选择对应的估算方法：

峰值系数用于把日均值放大到峰值时段，经验上取 2–3。有明确活动峰值的业务（例如大促、赛事、开学）请直接按活动峰值估算，不要使用日均值。

常见的估算偏差包括：

• 多端登录按多个连接计。同一用户同时在手机和网页登录时，PCU 计 2。
• heartbeatInterval 会影响 PCU。心跳间隔越长，掉线用户被判定离线越慢，统计出的 PCU 越偏高。默认值为 5 秒，范围为 5–1800 秒。

3. 频道级限制Copy Anchor Link

3.1 容量Copy Anchor Link

3.2 频道消息速率建议值Copy Anchor Link

频道消息速率是每秒内所有发布者（客户端和 RESTful API）向同一个频道发送的消息总条数。它是频道级限制，与第 4 章的客户端级限频分别计算：每个客户端都没有超限时，频道合计仍可能超出建议值。

建议值随频道同时在线人数分档。人数越多，每条消息的扇出成本越高，频道能承受的速率越低。

超出后的表现：通常不报错，但延迟可能增加，消息可能丢失，用户可能无法收发消息或反复重连。

接近建议值时：

• 按用户分片到多个频道，每个频道独立对照上表。
• 高频小消息改用 Stream Channel + Topic（单频道不超过 128 人）。
• 在业务服务端聚合后通过 RESTful API 发送，减少上行条数。
• 需要更高速率时提前联系技术支持，可在不影响延迟和稳定性的前提下定制提升。

4. 客户端级限制Copy Anchor Link

以下限制均以单个 RTM 客户端实例为统计单位，多个客户端各自独立计算。

4.1 调用频率限制Copy Anchor Link

RTM 将客户端 API 按功能分为若干操作类别，每个类别拥有独立的每秒调用配额。同一类别内的方法共享配额，不同类别之间互不影响。例如，同一秒内调用 15 次 whoNow 和 15 次 getChannelMetadata 不会触发限频，因为它们属于不同类别；但同一秒内调用 25 次 whoNow 会触发限频。

超出配额的调用不会被执行，也不会排队。SDK 通过错误回调返回限频错误码，需要在业务层节流或退避后重试，见第 8 章。

有特殊配额的操作Copy Anchor Link

其余操作：每个类别各 20 次/秒Copy Anchor Link

下表每一行是一个独立类别，行内的方法共享该类别的 20 次/秒配额。

4.2 连接与实例Copy Anchor Link

4.3 消息规格Copy Anchor Link

4.4 Presence 规格Copy Anchor Link

4.5 Storage 规格Copy Anchor Link

Metadata 写入后会长期保存，频道销毁或用户注销不会自动删除；不再需要时请显式删除。

4.6 Lock 规格Copy Anchor Link

5. RESTful API 限制Copy Anchor Link

6. 场景示例：怎么对照 3.2 做规划Copy Anchor Link

频道消息速率 ≈ 频道内活跃发布者数 × 人均每秒发送次数。先估算这个值，再对照3.2 的分档表。分档表第一列是同时在线人数（决定扇出成本），第二列是发送速率，两者分别估算。

以下规模数字仅为演示，请用真实埋点数据替换：

两个提醒：

• 活跃比例和人均频率对结果影响最大，优先用真实数据替换示例值。
• 分档表描述的是单个频道；分片后每个频道独立对照分档表，但项目级总上行速率（10 万条/秒，第 2 章）仍按所有频道合计。

7. 常见问题Copy Anchor Link

8. 超出限制后怎么办Copy Anchor Link

限频错误的重试模式（各平台 SDK 的回调形式见对应 API 参考）：

send(msg):
  result = rtm.publish(channel, msg)
  if result.error == RATE_LIMITED:
    delay = min(baseDelay * 2 ** attempt, maxDelay)  // 100 ms 到 2 s
    wait(delay)
    attempt += 1
    if attempt < maxAttempts:
      send(msg)
    else:
      report("publish dropped after retries")
  else:
    attempt = 0

更稳妥的做法是在发送侧维护一个按类别的令牌桶（发消息 60 次/秒、其他类别 20 次/秒），从源头避免触发限频，而不是依赖重试。

9. 申请提升与提前沟通Copy Anchor Link

以下项目可以申请提升或需要提前沟通。请联系 rtm-support@agora.io 或技术支持，并附上 App ID、预计规模和上线时间：