FAQ¶
设备与绑定¶
Q：设备激活返回 40104？
SN 不存在（未出厂预导入且未开 OPEN_ACTIVATION）或型号密钥错误。联系管理员确认 SN 已入库、activation_key 与型号匹配。
Q：绑定时的确认码在哪里看？
用户在用户中心发起绑定后，设备下一次心跳响应的 pending_ops 会带 bind_confirm 指令（6 位数字），设备屏幕显示该码；用户在 5 分钟内回填网页即完成绑定，码一次即焚。错过/过期可在用户中心重新发起（刷新码）。
Q：提示 40304“设备已被他人绑定”？ 一台设备同一时间只能绑定一个用户。联系当前绑定者解绑，或由管理员强制解绑（会作废设备 Token）。
Q：设备取数 40102？ Token 已失效（解绑/管理员重置/重复激活）。固件应自动回退用出厂密钥重新激活。
Q：取数 40101 未绑定 / 40302 未开通？ 40101：设备尚未绑定到任何用户，请先在用户中心绑定；40302：绑定用户未订阅该数据源，在用户中心「数据源订阅」开通。
数据与网关¶
Q：为什么多台设备拿到的 updated_at 一样？
服务端两级缓存全设备共享（千台设备每源 1 份缓存），updated_at 即缓存写入时间；这使回源频率 = 1/cache_ttl，对上游友好。
Q：stale: true 是什么意思？
上游暂时故障，返回的是降级窗口内的旧缓存。数据可用但非最新；updated_at 不变，设备端建议展示“数据更新于 {updated_at}”。
Q：50401 与 50000 的区别？ 50401 = 上游获取失败且无可用缓存（显示“暂无数据”，保留上次画面）；50000 = 平台内部错误（指数退避重试）。
Q：42901 后多久可以重试？
响应 data.retry_after 给出建议等待秒数，按其退避。限流默认 10 次/分/设备/源，可按源覆盖。
Q：为什么我的参数被丢弃了？
数据源 params_schema 未声明的额外参数默认丢弃并告警。传参方式：平铺 query 优先，复杂结构用 params=<urlencoded JSON>。
用户与账号¶
Q：注册用什么账号？ 邮箱即账号（注册后用邮箱登录，老用户名账号仍可用原用户名登录）。密码 ≥8 位且含字母与数字。
Q：注册验证码收不到 / 提示过期？ 验证码为 6 位数字，5 分钟有效、一次即焚；重发冷却 60 秒。收不到请检查垃圾箱、确认邮箱地址无误后重发；报 40307（验证码错误或已过期）时重新获取即可。
Q：改密后为什么所有端都掉线？
改密使 token_version+1，全部现有 JWT 立即失效（安全设计 D-10），重新登录即可。
Q：连续登录失败被锁定？
5 次失败锁定 15 分钟（42902 返回 data.remaining_minutes）。管理员可重置密码解锁。
Q：注销账号会怎样？ 级联解绑全部设备（设备 Token 作废）、停用订阅、软删除账号；设备本身保留可被重新绑定。
Q：提示 40309「需邀请码开通」/ 兑换返回 40308？
付费数据源（当前 comic_audio 听老故事）不支持自助开通，在「数据源订阅」页该源一行输入管理员发放的邀请码，点「兑换开通」即可。40308 表示邀请码无效（不存在/已用/过期/作废），请核对后重试或联系管理员；每个码只能使用一次（大小写不敏感），已订阅的付费源可自由停用/再启用。例外：用户名下有绑定中的库内 VIP 设备（出厂预导入 SN）时，付费源免邀请码直接订阅，设备端免订阅取数（订阅页顶部会显示「VIP 已解锁」）。
Q：为什么我的设备不用订阅也能取所有数据源？ 该设备 SN 为出厂预导入入库（管理后台设备列表带 VIP 徽标），属于 VIP 设备——绑定后全部数据源免订阅直接可用；自行注册（开放模式）的设备无此权益，付费源需邀请码开通。
开发者¶
Q：插件放入目录后多久生效？ 启动扫描或管理端「重新扫描」即注册为“待审核”；管理员审核通过后 ≤5s 生效，全程不重启进程。
Q：插件调用上游的超时/重试谁管？
统一走 ctx.http（超时 fetch_timeout_sec 默认 120s、重试 1 次；长链路插件如新闻播报需要大预算，快源不受影响）；插件自建无超时客户端是审核驳回项。
Q：上游密钥怎么配置？
管理后台 → 数据源管理 → 密钥管理（Fernet 加密落库，读取不回显明文）；插件内 ctx.get_secret(key) 获取。严禁硬编码。
Q：我的源为什么开发者接口里看不到别人的？
开发者（role=2）仅可见 owner=自己 的数据源；管理员可见全部。
运维¶
Q：系统配置修改后何时生效？ 后台保存后立即重载；多实例 ≤5s（sys_config 版本轮询）。全部修改记审计。
Q：公告如何到设备上？
管理后台发布后，设备 GET /api/v1/notice 即返回最新一条生效公告（公开接口，无需鉴权）。