TiStore 开发文档

中文

English

中文

English

使用 CLI 辅助联调 ​

没有真实设备和客户端时，可以用 CLI 在 macOS 或 Linux 电脑上完成 TiStore 云端联调。CLI 提供两种模式：

  • Web 模式：在本机浏览器里签发两类 Token、模拟设备端上传示例录像，并查询、播放、截图和下载云录像。
  • 命令行模式：在终端里直接签发设备端 Token 和客户端 Token，便于脚本集成。

命令行模式目前对外提供这两项能力。设备端上传和客户端播放请在 Web 模式完成，真实接入按接入流程概览使用 C SDK 和客户端 SDK。

使用前准备 ​

准备 Node.js 和 npm。使用 npm 官方源安装，避免第三方镜像返回旧版本：

bash
npm install -g tirtc-devtools-cli@latest --registry=https://registry.npmjs.org

确认版本：

bash
tirtc-devtools-cli --version

输出以 CLI Version: 开头。@latest 会安装 npm 官方源中 latest 标签指向的版本，后续重新执行安装命令即可升级。

签发 Token 需要 AppId、AccessKeyId 和 AccessKeySecret，模拟上传还需要 device_secret_key。这些凭证只应放在受控开发环境中，不要写进客户端代码、日志、截图或工单。

选择要完成的联调任务 ​

你的目标阅读位置
没有真实设备，先验证设备端上传链路Web 模式下先签发云录像 Token，再进入模拟上传云录像
没有客户端，先验证查询、播放和下载Web 模式下先签发云录像 Token，再进入播放与下载云录像
在脚本或服务里签发 Token命令行签发 Token

Web 模式 ​

Web 界面在本机浏览器里操作，覆盖 Token 签发、模拟上传和云录像播放三部分。

启动：

bash
tirtc-devtools-cli web

CLI 会自动分配端口并打开浏览器。也可以手动指定端口：

bash
tirtc-devtools-cli web --port 8966

Web 界面只监听本机 127.0.0.1。表单里填过的值（包括密钥）保存在启动目录的 .tirtc-devtools.env 文件里，不要把该文件提交到仓库或外发。

签发云录像 Token ​

「签发云录像 Token」页模拟业务服务端签发两类短期 Token。签发前先选择类型并填写：

字段填什么
Token 类型客户端 Token 或设备端 Token
AppId申请开通时下发的应用标识
AccessKeyId、AccessKeySecret申请开通时下发的应用凭证，只填在本机页面里
device_id要访问的目标设备标识
有效期900～43200 秒，默认 43200
录像保留天数只对设备端 Token：正整数，表示本次上传录像在云端保留的天数。须与已开通的产品规格一致，签发和上报使用同一个数字，默认 7

签发成功后：

  • 客户端 Token 显示 Token 文本、二维码和到期时间。可以扫码导入客户端示例，或点「填到播放页」直接用于播放页。
  • 设备端 Token 只显示 Token 文本和到期时间，不生成二维码。点「填到上传页」直接用于上传页。

不要截图或外发包含 AccessKeySecret 的页面。

模拟上传云录像 ​

「模拟上传云录像」页用本机模拟设备端，把一段示例录像上传到云端。上传参数：

字段填什么
device_id、device_secret_key目标设备的身份
设备端 Token粘贴签发页生成的设备端 Token

上传内容是固定的：H.264 视频放在 Channel 11，G.711A 音频放在 Channel 10，时长 120 秒。

点击「开始上传」。成功后页面显示「可用时间段」和「文件列表」，可以点「去播放」直接进入播放页。

上传失败时，核对 device_id、device_secret_key 和设备端 Token 后重试。

播放与下载云录像 ​

「播放与下载云录像」页用本机模拟客户端。填写：

字段填什么
AppId申请开通时下发的应用标识
Token粘贴签发页生成的客户端 Token
视频 Channel ID、音频 Channel ID必须和设备上传时一致，默认是视频 11、音频 10

选择查询起止时间后点击「查询」。单次查询跨度最长 10 天，结果按可用时间段列出。

  • 播放：支持暂停 / 继续、静音、1 / 2 / 4 / 8 倍速。
  • 截图：把当前播放画面保存为 JPEG，成功后浏览器把文件保存到本机下载目录。截图前需要先成功输出至少一帧画面。
  • 下载：按查询结果里的开始和结束时间，把选定时间段导出为 MP4，完成后浏览器把文件保存到本机下载目录。
  • 日志：可以把云录像相关日志上传，页面会返回日志编号，用于问题排查。

查询为空时，确认 Token 绑定的是目标设备、日期正确、两个 Channel ID 与设备上传时一致。

命令行签发 Token ​

命令行模式通过 tistore token issue 模拟业务服务端签发 Token，适合写进脚本。签发只需要应用凭证，不涉及 device_secret_key。

先设置环境变量：

bash
export TISTORE_ENDPOINT="https://api-tistore.tange365.com"
export TISTORE_APP_ID="your_app_id"
export TISTORE_ACCESS_KEY_ID="your_access_key_id"
export TISTORE_ACCESS_KEY_SECRET="your_access_key_secret"

签发设备端 Token，供真实设备 C SDK 上传：

bash
tirtc-devtools-cli tistore token issue \
  --type device \
  --device-id device-001 \
  --duration-seconds 3600 \
  --recording-retention-days 7

签发客户端 Token，供客户端查询、播放和下载：

bash
tirtc-devtools-cli tistore token issue \
  --type app \
  --device-id device-001 \
  --duration-seconds 3600
参数说明
--typeapp 或 device
--device-id目标设备的 device_id
--duration-secondsToken 有效期，900～43200 秒
--recording-retention-days仅设备端 Token：录像保留天数，正整数；须与已开通的产品规格一致，签发和上报使用同一个数字

成功后输出 JSON，包含 access_token 和 expires_at_ms。需要脚本解析时加全局参数 --json：

bash
tirtc-devtools-cli --json tistore token issue \
  --type app \
  --device-id device-001 \
  --duration-seconds 3600

签发的两类 Token 与云端签发 Token中的接口一致，正式接入仍由业务服务端完成授权判断和签发。

常见问题 ​

  • 安装后不是最新版本：
    1. 运行 npm view tirtc-devtools-cli@latest version --registry=https://registry.npmjs.org，记录 npm 官方源中 latest 标签指向的版本。
    2. 重新执行本页的安装命令，再运行 npm prefix -g。npm 全局安装的 CLI 应位于输出目录下的 bin/tirtc-devtools-cli。
    3. 运行 type -a tirtc-devtools-cli。结果按终端查找顺序排列，第一项是终端当前会调用的命令。如果它不是上一步的 npm 全局安装路径，清理同名 alias 或函数、调整 PATH 顺序，或通过原安装方式卸载排在前面的旧副本。
    4. 运行 hash -r 刷新终端命令缓存，再执行 tirtc-devtools-cli --version，确认版本与第一步一致。也可以重新打开终端后再检查。
  • 签发 Token 时报 tistore_configuration_missing：检查以下环境变量是否均已设置：
    • TISTORE_ENDPOINT
    • TISTORE_APP_ID
    • TISTORE_ACCESS_KEY_ID
    • TISTORE_ACCESS_KEY_SECRET
  • 签发 Token 时报 invalid_tistore_token_options：按照上表逐项检查以下参数：
    • --type
    • --device-id
    • --duration-seconds
    • --recording-retention-days
  • Token 过期或二维码无效：重新签发一次，客户端使用新 Token 或新二维码。
  • 查询不到录像：确认 Token 绑定目标设备、日期正确、Channel ID 与设备上传一致，且上传页已经出现可播时间段。

TiStore 开发文档

Copyright © 2025