排障手册
按现象索引：入会失败、只有声音没有画面、录制无文件、回调收不到、Token 过期、跨域与防火墙。
版本 v1.1.0 · 更新于 2026-10-26 · 修订 1
按「你看到的现象」索引。每条都给出先查什么、怎么查、根因是什么，不要凭感觉改代码。
入会与鉴权#
| 现象 | 先查 | 常见根因 | 修复 |
|---|
401 missing_authorization | 请求头 | 忘带 Authorization: Basic … | 补上 base64(customerId:customerSecret) |
401 invalid_credentials | 控制台凭证页 | secret 是轮换前的旧值 | 更新环境变量并重启服务 |
401 invalid_appid | customerId 与 appId 是否同项目 | 跨项目复用凭证 | 一个项目一套凭证 |
400 invalid_channel_name | 频道名字符集 | 含空格/中文/超长 | 用 [A-Za-z0-9_-]，≤128 |
403 banned | GET /dev/v1/kicking-rule | 命中 join_channel 封禁 | 删除封禁规则 |
403 service_not_enabled | 项目服务页 | 未开通录制/推流 | 开通后重试 |
SDK 报 -110 / INVALID_TOKEN | GET /v1/tokens/verify?token=&channelName= | Token 与频道/appId 不匹配或已过期 | 重新签发；检查 pexp |
SDK 报 -109 / TOKEN_EXPIRE | Token payload 的 exp | Token 生命周期到了 | 重新入会并换新 Token |
| 入会后立刻被踢 | 回调日志 104/108 | 同 uid 在别处入会（uid 冲突） | 每个客户端用唯一 uid |
媒体与画面#
| 现象 | 先查 | 常见根因 | 修复 |
|---|
| 只有声音没有画面 | user-published 回调 | 没 subscribe 或没 play(容器id) | 补订阅与渲染调用 |
| 本地黑屏但对方能看到 | cameraTrack.play() | 容器 id 不存在或尺寸为 0 | 检查 DOM/容器与 CSS |
| 对方看不到我 | publish 是否成功 | 观众角色 / Token 无 publish_* 权限 | 切 host 角色 + 重签 Token |
一直 RECONNECTING | SFU 地址解析链 | 反代没放行 WebSocket | 开启 Upgrade 透传 |
| 共享屏幕黑屏 | 采集源 | 受保护窗口 / macOS 未授权 | 换整屏；系统设置授权后重启 |
| 弱网下卡顿不降级 | 是否开双流 | 发布端没开 dual stream | enableDualStream() |
| 画面倒置/镜像 | 渲染层 | 前置摄像头镜像 | 调整 mirrorMode |
| 现象 | 先查 | 常见根因 | 修复 |
|---|
403 service_not_enabled | 项目服务 | 未开通录制 | 开通 |
429 recording_quota_exceeded | details.limit / details.active | 并发录制满 | 排队或提配额，见 配额 |
| acquire 后 start 报错 | 时间差 | resourceId 只有 30 秒 TTL | 立刻 start，不要存起来晚点用 |
任务一直 starting | GET /v1/recordings/{id} | egress 节点不可用/队列满 | 检查 Egress 节点容量与任务队列 |
| 录制完成但文件 404 | 存储 vendor 配置 | 桶权限/路径前缀不对 | 跑 文档与接口定义自动化校验 |
| 录出来是黑屏 | 频道里没人发布 | 录制开始时无人上麦 | 先入会再开录，或延长等待 |
推流 / 拉流 / 网关#
| 现象 | 先查 | 常见根因 | 修复 |
|---|
converter state=failed | 回调 202 的 error | RTMP 地址拒绝连接 | 用 ffmpeg/OBS 验证地址 |
| OBS 推流被拒 | streamkey | 过期、频道不符或模板不存在 | 重新签发 streamkey |
| 推流进频道但看不到 | online-streams | 推流没建立会话 | 看网关握手日志与 sid |
拉流 status=failed | player 详情 error | 源地址不可达（内网/localhost） | 换成服务端可访问的 URL |
| 拉流有画面没声音 | audioOptions | 默认静音或轨道缺失 | 检查源是否含音轨 |
| 现象 | 先查 | 常见根因 | 修复 |
|---|
| 完全收不到 | Webhook 配置 | 未配置/enabled:false | 控制台配置 |
| 收到但签名校验失败 | 用的是哪种 body | 反序列化后重新序列化 | 用原始字节校验 |
| 只收到一部分事件 | 订阅的事件列表 | 没勾选对应事件 | 补订阅 |
| 投递日志全是 4xx | 你的接收端 | 路径 404 / 缺 Content-Type | 修接收端 |
| 重试 9 次后放弃 | 投递日志 | 接收端长时间 5xx | 修复后手动重放 |
自检顺序#
- API 是否存活？
curl -s $NIMEET_API_BASE/healthz - 凭证是否可用？调用
POST /v1/tokens 签发 Token，再用 GET /v1/tokens/verify 校验。 - 全链路是否可用？用 Web SDK 或客户端 SDK 加入频道并发布一路轨道。
- 回调是否到达？配置 webhook 后查看
GET /v1/webhook/deliveries。
四步全绿还定位不到问题，就把 X-Request-Id 和出错时间贴进工单——所有服务端日志、回调投递、审计记录都带这个 id。
相关页面#