问题排查

接入异常时，先找出最早没有完成的阶段，再检查这一阶段的输入、返回值和回调。不要只凭“接口返回成功”判断录像已经上传、可以查询、已经播放或下载完成。

先从接入流程概览确认问题位于服务端签名、设备上传、客户端查询、Replay 播放还是本地文件生成，再依次检查各阶段。

先确认问题停在哪个阶段

1. 服务端签名或 Token 签发失败

• 先用固定测试向量验证签名器，不要直接拿真实凭证试错。
• 检查 UTC 请求时间、最终发送的原始 Body、Canonical Query、Credential Scope 和 SignedHeaders。
• 确认 AppId 与 AccessKeyId 属于同一应用，两类 Token 的目标和用途没有混用。
• 保留 HTTP 状态、业务错误码和 request_id，不要记录 AccessKeySecret、Authorization 或完整 Token。

2. 设备 SDK 没有启动或上传任务没有完成

• 检查 TiStoreInit()、Service 创建和启动结果，以及 device_access_token 是否有效。
• TiStoreQueueWriteFrame() 返回成功只表示 SDK 接收当前帧；继续检查帧时间戳、关键帧、队列状态和服务回调。
• 结束持续录像时调用 TiStoreUploadSetEnd()，并等待该 upload_id 的 on_result 最终结果。
• TiStoreServiceStop() 会中止活动任务并丢弃尚未分发的回调，不能用它等待上传完成。

3. 客户端查询不到录像

• 确认 app_access_token 绑定目标设备，而且查询范围使用 UTC Unix 毫秒。
• 查询范围应覆盖已经完成上传的实际时间，不要使用本地时区字符串。
• 确认目标区间没有被删除；删除成功后，客户端录像时间段查询和播放会精确扣除该区间。
• 设备写帧成功但上传尚未完成时，查询为空不等于 SDK 丢帧。

4. 已查询到录像，但播放没有声音或画面

• 使用查询返回的可用时间段创建 Replay，不要跨越录像空洞。
• 确认音频和视频 Output 已绑定当前 Replay。
• 检查 Replay、Output 和 Store 是否被应用提前释放。
• 按当前平台 API 的状态、回调或 Promise 判断播放是否真正开始。

5. 下载录像失败

• 确认时间范围来自查询结果，SDK 缓存目录可写且磁盘空间充足。
• 保持 Export Task 或 Recording Task 及其依赖对象有效。
• 进度回调不是完成标志，以 Task 的最终结果为准。
• 区分 SDK 缓存文件与应用持久文件；需要长期保留时显式复制或移动。

问题仍未解决时收集证据

问题复现后尽快保存同一次复现的服务端、设备端和客户端材料，避免日志滚动覆盖。至少包括：

• 问题发生时间和时区，最好同时提供 UTC Unix 毫秒。
• 平台、操作系统、CPU 架构、SDK 版本和 Build Info。
• 脱敏 AppId、device_id，以及服务端接口名、HTTP 状态、错误码和 request_id。
• 关键调用的返回值、状态、最终结果回调和前后日志。
• 查询、播放或下载的开始与结束时间，以及设备实际写帧时间范围。

获取设备 C SDK 日志

在设备投入使用前配置可持久化的日志输出。问题复现后，取回覆盖 Service 启动、上传任务创建、写帧、设置结束时间和最终结果回调的连续记录。

如果设备只把日志输出到控制台且当时没有保存，历史记录无法补回，需要先增加文件、环形缓冲区或应用日志回调，再次复现。

获取客户端日志

保留 Store 创建、录像查询、Replay、Output、导出任务的返回值与状态变化，并按目标平台的应用日志机制导出原始记录。

提交排查材料

把以下材料发给开通时的联系人，或发送到 business@tange.ai。

• 最短复现步骤，以及问题停在哪个阶段。
• 同一次复现的服务端 request_id、设备端日志和客户端日志。
• 使用的平台、SDK 版本、时间范围、返回码和关键状态。
• 预期结果与实际结果。

提交前移除 Token、Authorization、AccessKeySecret、device_secret_key、用户信息和音视频内容中的敏感数据。