从声网迁移
逐层差异清单：凭证、Token 服务、客户端 SDK、REST 路径、回调，以及明确不支持的能力。
已经接了声网、想换成 ni-meet？这一页给出逐层差异清单：哪些地方代码不用改，哪些必须改，以及改完怎么验证。
第 0 步：先确定你要迁哪一层
| 你用的声网能力 | 迁移改动量 | 说明 |
|---|---|---|
| 客户端 SDK 入会/发布/订阅 | 小（Web 端几乎为零） | 换 App ID + Token 来源即可；API 形状不变 |
| 服务端 Token 签发 | 中 | Token 服务从声网换成 POST /v1/tokens；SDK 侧无感 |
| 服务端 REST（频道查询/踢人） | 小 | 声网兼容路径 /dev/v1/* 已实现，见下 |
| 云端录制 | 中 | 路径与信封一致，但 resourceId 租约语义要按 ni-meet 的调用时序处理 |
| Media Push | 中 | 声网已 sunset 的 entry_points 保留兼容，但现行接口是 rtmp-converters |
| 水晶球 | 中 | 指标口径一致，但接口路径为 /v1/analytics/* |
| 回调接收 | 小 | 事件码、签名头一致；重试节奏与投递日志为 ni-meet 自有实现 |
第 1 步：凭证与域名
| 项 | 声网 | ni-meet |
|---|---|---|
| 项目标识 | App ID | appId（同概念，32 位十六进制） |
| 服务端凭证 | Customer ID / Customer Secret | customerId / customerSecret，同样用 Authorization: Basic base64(id:secret) |
| Token 密钥 | App Certificate | appCertificate（同概念，不出服务端） |
| API 基址 | https://api.agora.io | 你的自建控制面地址，例如 https://api.your-domain.com |
代码里唯一必须改的是基址常量和凭证来源（从声网控制台复制 → 从 ni-meet 控制台 / POST /console/projects 获取）。
第 2 步：Token 服务（后端必改）
声网侧通常使用 agora-token / agora-access-token 之类的库在本地生成 Token。迁移后：
旧：generateToken(appId, appCertificate, channel, uid, role, ttl) // 本地算
新：POST /v1/tokens { channelName, uid, role, ttlSeconds } // 调控制面- 不要自行实现 Token 格式：签名密钥是
appCertificate，算法与载荷见 AccessToken2 语义；
控制面已提供签发、续期、校验三个接口，直接调用即可。
- 续期语义一致：
token-privilege-will-expire→ 调POST /v1/tokens/renew→client.renewToken(newToken)。 - 如果 Token 由 IM 侧提供（RTC Provider 模式），两个方法名与声网一致，直接替换实现即可，
见 Token 鉴权 的「与 IM 的 RTC Provider 接口」。
第 3 步：客户端 SDK（Web 端零改动）
迁移前：
import AgoraRTC from 'agora-rtc-sdk-ng';迁移后（只替换这一行，变量名不变）：
import AgoraRTC from '@nimeet/rtc-web';方法链、事件名、错误标识全部一致，client.join(appId, channel, token, uid)、client.publish([mic, cam])、 client.subscribe(user, mediaType)、user.videoTrack.play('id') 都不需要改。差异只在：
- 媒体边缘地址由部署决定，SDK 按
Token 载荷的 surl→window.__NIMEET_SFU_URL__→ 同源/rtc的顺序解析
（控制面不写 surl，所以推荐同源 /rtc 或显式设置引导变量）；
- 不支持的能力会显式抛
AgoraRTCError.code === 'NOT_SUPPORTED'（例如频道媒体中继、客户端直推 CDN、E2EE），
不会静默成功——迁移时建议在灰度环境里打开 client.on('exception') 收集这些错误。
非 Web 端请看对应平台的「快速开始与功能指南」；各端运行时能力以实际发布的 SDK 包为准。
第 4 步：REST 路径
三条规则，覆盖你 90% 的调用：
| 规则 | 例子 |
|---|---|
| 声网路径原样保留（前缀一致、参数名可能不同） | GET /dev/v1/channel/{appid}、POST /dev/v1/kicking-rule |
云端录制沿用 /v1/apps/{appid}/cloud_recording/... | acquire → start → query → updateLayout → stop |
平台自有语义走 /v1/* | /v1/channels、/v1/recordings、/v1/analytics/* |
差异只有路径参数命名（声网 cname/uid，部分接口使用 channelName；两者都接受时以 API 参考为准）与 响应信封：声网用业务码（{"success":true} / {resourceId,sid}），ni-meet 用 HTTP 状态码 + {code,message,reason,sdkCode}。 完整路径对照表见 频道管理 的「声网路径 ↔ 我们路径对照」。
第 5 步：回调接收（几乎不改）
- 事件码一致：
101–112（频道/用户）、201–203（录制/推流/Token）； - 签名头一致：
Agora-Signature（HMAC-SHA1）与Agora-Signature-V2（HMAC-SHA256），都用 endpoint secret 对原始请求体签名； - 差异：重试次数与退避序列以回调事件定义为准（最多 9 次，5s 起指数退避），
并额外提供投递日志与重放接口。
第 6 步：验证迁移是否成功
按这个顺序验证，每步都可独立复跑：
curl $BASE/healthz→{"status":"ok"}；POST /v1/tokens拿到 Token →GET /v1/tokens/verify?token=...回读权限集与pexp；- 浏览器双人入会：见 快速开始 的 Web SDK 示例；
- 服务端查询：
GET /dev/v1/channel/{appid}能看到刚才的频道； - 回调：配置 webhook 后，用文档示例目录中的
curl/callbacks.sh触发并观察投递日志； - 全量示例：在文档示例目录执行
node examples/run-all.mjs --all（应全部通过）。