第 11 章 运维

设备上线后的长期运维:Token 刷新不中断服务、NTP 校准保证签名不失败、roundId 链路定位问题、心跳保活、灰度监控。

目录

• 11.1 Token 刷新策略
• 11.2 NTP 校准
• 11.3 roundId 链路定位
• 11.4 监控与告警
• 11.5 OTA 与远程配置
• 11.6 联系支持规范

11.1 Token 刷新策略

JoyInside 采用双 Token 机制(详见 4.1 鉴权):

Token	有效期	用途
accessToken	2 小时	API 鉴权与 WS 建联
refreshToken	7 天	有效期内刷新 accessToken,失效后需重新 getToken

刷新时机

1. 主动刷新:accessToken 接近 2h 过期前,用 refreshToken 调用 refreshToken 接口获取新 accessToken;
2. 被动刷新:WS 建联返回 40104(token 过期,见 9.7)时,立即刷新后重连。

refreshToken 接口

项目	说明
URL	https://api.joyinside.com/...refreshToken
请求方式	POST
鉴权	Header Authorization: Bearer ${accessToken}

refreshToken 响应字段

字段	类型	说明
accessToken	string	新的访问令牌
expireIn	Integer	访问令牌过期时间(秒),有效期 2 小时
refreshToken	string	刷新令牌,有效期 7 天,有效期内可刷新 accessToken,失效后需重新获取
refreshExpireIn	Integer	刷新令牌过期时间(秒)

端侧刷新建议

每次 WS 建联前确保 token 有效,刷新决策:

def ensure_token():
    """每次 WS 建联前确保 token 有效"""
    if token_expired_or_near_expiry(access_token):
        if refresh_token_valid():
            access_token = refresh_access_token(refresh_token)
        else:
            access_token = get_token()  # 重新签名获取
    return access_token

关键点:

1. accessToken 有效期 2h,建议在 1h45min 时主动刷新,留 15min 余量;
2. refreshToken 有效期 7 天,建议在 6 天时重新 getToken 获取新的 refreshToken;
3. 建议 WS 建连前重新获取 token,不要复用快过期的 token;
4. token 签名依赖 accessTimestamp,必须配合 NTP 校准(见 11.2)。

11.2 NTP 校准

为什么需要 NTP

签名鉴权要求 accessTimestamp:

• 与服务端时间误差 ≤15 分钟;
• 不能大于当前时间戳(不能是未来时间)。

如果设备时间偏差 >15min,getToken 返回 1003 时间戳错误(见 9.1.1)。设备 RTC 漂移是签名失败的首因。

NTP 校准方案

1. 设备上电后立即 NTP 校准,再触发 getToken;
2. 定期校准:设备运行期间每小时校准一次,防止 RTC 漂移;
3. 校准失败兜底:NTP 服务器不可达时,记录上次校准的时间差,本地补偿;
4. NTP 服务器建议:
   • 京东 NTP:time.jd.com
   • 公共 NTP:ntp.aliyun.com / cn.ntp.org.cn
   • 多服务器容错,任一可达即可。

签名前时间戳检查

import time

def get_access_timestamp():
    """获取签名用时间戳,确保在有效窗口内"""
    ts = int(time.time() * 1000)  # 毫秒
    # 校准逻辑应已通过 NTP 保证本地时钟准确
    return ts

时间戳误差窗口:±15min(详见 4.1 签名算法与 9.7 错误码速查)。

11.3 roundId 链路定位

roundId 是端到端排查的主键(详见 4.6 服务端链路设计 · roundId)。

roundId 的作用

• 单轮对话唯一标识:一轮语音对话从 ASR 到 TTS 的全链路用同一个 roundId 串联;
• 服务端日志定位:京东技术支持通过 roundId 在服务端日志中找到这一轮的完整链路;
• 排查粒度:roundId > requestId > botId。

端侧日志建议

设备端日志应记录每轮的:

字段	来源	用途
roundId	下行事件 content.roundId	排查主键,必须打印
requestId	下行事件 requestId	一次 WS 建连的标识
botId	建联参数	设备身份
eventType	下行事件	事件类型
eventTime	事件 t	时间戳
sessionId	建联参数	会话标识

排查流程

1. 复现问题:记录问题发生时的时间、用户输入、设备表现;
2. 提取 roundId:从设备日志中找到对应轮次的 roundId;
3. 联系支持:将 roundId + 时间 + 现象提供给京东技术支持;
4. 服务端查日志:京东技术支持通过 roundId 在 ASR → Flow → TTS 全链路定位。

没有 roundId 京东技术支持无法帮你查。设备端务必在每轮对话日志中打印 roundId。

常见问题排查指引

现象	排查入口
建联失败 / 互踢	9.1 建联失败类
不说话 / 答非所问	9.2 设备不说话
打断失效	9.3 打断失效
有声书异常	9.4 有声书
IOT 指令异常	9.5 IOT 指令类
音色 / 查询	9.6 音色查询

11.4 监控与告警

⚠ 本节待补充:平台侧监控告警能力与 JoyInside 团队对齐。以下为端侧 + 业务侧监控建议框架。

端侧监控指标

指标	采集方式	告警阈值建议
WS 建联成功率	建联成功数 / 建联尝试数	<95% 告警
对话完成率	收到 COMPLETE 事件数 / 建联数	<90% 告警
TTS 播放成功率	TTS_COMPLETE 数 / TTS 开始数	<95% 告警
互踢率(REPEAT_CLIENT_SESSION)	互踢事件数 / 建联数	>1% 告警
签名失败率	getToken 失败数 / getToken 调用数	>1% 告警(NTP 可能异常)
心跳成功率	PONG 收到数 / PING 发送数	<99% 告警
首次响应延迟	ASR 首包到 TTS 首包间隔	>2s 告警

端侧日志上报建议

• 异常时通过端侧上报接口(如有)或日志导出提供完整链路(日志字段见 11.3 roundId 链路定位);
• 关键错误(40104 token 过期 / REPEAT_CLIENT_SESSION / 网络断连)实时上报。

平台侧监控

⚠ 平台侧监控大盘与告警能力待 JoyInside 团队提供。可联系技术支持获取设备维度 / 应用维度的运行数据。

11.5 OTA 与远程配置

⚠ 本节待补充:OTA 固件升级、远程配置下发能力与 JoyInside 团队对齐。

远程配置可下发的项

以下配置在运营平台修改后,需设备重建 WS 连接生效(根因见 9.6.1 音色切换不生效):

配置项	章节
音色	7.1
全局人设 / 提示词	3.2
技能 / 指令集	6.1 / 7.1 外部智能体接入
交互策略(开场白 / 静默推送)	7.2

端侧 OTA 建议

1. 固件 OTA:设备固件升级由厂商 OTA 通道负责,JoyInside SDK 不内置固件 OTA;
2. 配置 OTA:人设 / 技能 / 音色等通过运营平台配置,设备重建 WS 即可拉取最新配置;
3. 灰度发布:新版本配置建议先灰度小批量设备,见 10.4。

11.6 联系支持规范

提供信息清单

联系京东技术支持时,请提供:

1. roundId:问题轮次的 roundId(必须,见 11.3);
2. botId / vendorId / appId:设备身份与企业标识;
3. 时间:问题发生的精确时间(精确到分钟);
4. 现象:用户输入什么、设备表现什么(建联失败 / 不说话 / 打不断 / 答非所问等);
5. 设备日志:设备端打印的完整事件链路(含 eventType / eventTime);
6. 公网 IP:建联失败类问题(400/408)需提供设备公网 IP(见 9.1.2)。

沟通渠道

• 京东技术对接群(企业入驻后加入);
• 提供工单或对接人直接沟通。

下一步

• 上线验收:读 第 12 章 验收
• 量产流程:读 第 10 章 量产
• 故障排查:读 第 9 章