常见问题与限制
配额与硬限制、鉴权与网络常见问题、当前实现边界与已知不一致。
这一页集中列出接入时最容易踩到的硬限制、部署边界与常见问题。
硬限制
| 项目 | 限制 | 说明 |
|---|---|---|
| 频道名 | 1–128，字符集 [A-Za-z0-9_-] | 服务端校验 |
| rtcUid | 1..2147483647，不能为 0 | 签发 Token 与加入频道时校验 |
| Token TTL | 60–86400 秒 | 最终会被项目的 tokenTtlSeconds 夹紧 |
| 权限窗口 | min(ttl, project.privilegeTtlSeconds) | 权限与 Token 生命周期分离 |
| 续期宽限 | 权限过期后 300 秒内可续期 | 超过后需重新签发 |
| 即将过期提前量 | 30 秒 | 客户端事件 + 回调 203 |
| uid 映射批量 | 单次最多 200 个 uid | POST /v1/uids:resolve |
| 质量样本批量 | 单次最多 5000 条 | POST /v1/analytics/quality |
| 分页 | page_no ≥ 0，page_size 1–500，默认 100 | 列表接口通用 |
| 请求体大小 | 2 MiB | 超出返回 413 |
| 写请求 Content-Type | 必须为 application/json | 否则返回 415 |
| 封禁时长（平台） | 0–86430 秒，默认 600（踢人/禁言）、3600（规则） | 0 表示立即过期 |
| 封禁时长（声网兼容） | time 0–1440 分钟或 time_in_seconds 0–86430 | /dev/v1/kicking-rule |
| 录制 maxDuration | 10–86400 秒 | 超时自动停止 |
| 推流 idleTimeout | 0–86400 秒，默认 300；0 关闭自动回收 | 无人观看时回收 |
| entryPoint / streamName | [A-Za-z0-9_-]，长度 1–64 / 1–128 | 旁路推流 |
| 项目默认配额 | 录制并发 5、推流并发 5、频道数不限 | 可在控制台调整 |
| Egress 并发 | 并发 8 / 队列 200 / 1000 ms 轮询 | 自托管部署可通过配置调整 |
部署边界
- 本地默认使用内存存储：重启后项目、凭证、频道、任务、回调记录与质量样本会清空，并重新生成演示项目与凭证。生产部署请按 自托管部署 使用持久化存储。
- 控制面按单副本设计：云录制
resourceId注册表、任务调度与回调投递都在控制面进程内。多副本部署前需要将会话状态外置，或把acquire→start固定到同一副本。 - 本地默认使用媒体模拟器：不配置外部 SFU 时使用内存 SFU 模拟器，行为可测但不是真实媒体；生产环境请接入 LiveKit。
- 管理端口不对公网开放：仅集群内网可达，公网反向代理只暴露
/v1/*、/dev/v1/*、/console/*。
能力边界
- 当前版本支持 Token 签发与续期、频道与用户管理、封禁与禁言、云端录制、旁路推流、Media Push / Pull / Gateway、云转码、水晶球、回调与错误码。
- 内容审核（Content Inspect）、E2EE、频道媒体中继、客户端直推 CDN 当前版本不提供；相关方法返回
-4（ERR_NOT_SUPPORTED）。 - AI（转录、降噪、对话式 AI）不在当前产品范围内，仅保留回调接入点。
- 录制文件支持本地对象存储；接入 S3/OSS 请见 自托管部署 的存储配置。
常见问题
Q：Token 能直接给浏览器吗？ 能，但只能给短期 Token，且绝不能同时给出 customerSecret / appCertificate。浏览器里的 Token 一旦泄露，攻击者最多在有效期内使用它；secret 泄露等于项目失守。
Q：为什么我拿 dev/v1 的 appid 请求返回 401 invalid_appid？ /dev/v1/* 路径里的 appid 必须属于当前 Basic 凭证对应的项目。跨项目访问会被拒绝。
Q：录制一直停在 starting？ 检查 Egress 节点容量与任务队列。真实 LiveKit 环境由 Egress 异步启动，通常数秒内变为 running。
Q：推流地址能直接播放吗？ rtmpUrl 是推流地址（给 OBS/云直播），播放请用 hlsUrl。HLS 有分片延迟（约数秒到十几秒），互动场景请走 RTC。
Q：回调总失败怎么办？ 先看 GET /v1/webhook/deliveries 的 lastStatusCode / lastError：401/403 多为签名校验实现错误（用了 JSON.stringify(JSON.parse(body)) 而不是 raw body）；超时请先返回 200 再异步处理；重试预算内可手动 replay。
Q：如何验证本地环境？ 按 快速开始 启动服务并运行示例脚本；示例会先检查健康检查接口，再依次验证 Token、频道与遥测链路。