协议与数据模型

文档首页

独立部署说明：文中官方域名为原服务示例，实际使用配置的实例域名；后台ADMIN_ORIGIN要求HTTPS且包含实际非默认端口。可信代理通过TRUSTED_PROXY_IPS显式配置，内部服务/数据路径也已环境化，详见部署文档。初次实例不带旧数据库/密钥/默认插件或原音源启停策略。

1. HTTP 约定

• 公开和管理接口基地址均为 https://wristhyme.tolike.cn，路径区分大小写。
• 音乐元数据读取为 GET，查询参数采用 URL 编码；不要把中文、ref 或歌单链接手工拼接进 URL。
• 写入接口为 POST，JSON 根必须是对象，Content-Type: application/json，须提供一个明确的 Content-Length。设备与后台实现拒绝 Transfer-Encoding 分块上传。
• 成功 JSON 没有统一 data 外层，也不是所有接口都返回 ok；按各接口实际结构解析。
• 网关 JSON 通常为 application/json; charset=utf-8；音频是二进制，不可调用 JSON 解析器。
• 网关/后台通常返回 Cache-Control: no-store、X-Content-Type-Options: nosniff、Referrer-Policy: no-referrer、X-Frame-Options: DENY 及 CSP。静态发布文件遵循反向代理的缓存策略。
• 不存在通用的 Bearer/JWT/API Key 鉴权。不要给音乐请求携带管理员 Cookie、内部密钥或平台登录凭证。
• 当前代码没有通用 CORS/OPTIONS 支持。原生客户端可访问，浏览器建议同源调用；不能假定跨域前端能直接使用。
• 没有统一 HEAD 支持，也没有公共 PUT/PATCH/DELETE 合同。Python 默认处理可能返回 HTML 501，而非 JSON 错误。
• 查询解析只使用同名参数的首个值，空值可能被忽略；因此不要依赖重复参数或空参数来表达列表。
• 未知查询字段不一定被拒绝，但不能据此声称支持该功能。

可选客户端身份头

设备头不是管理员身份，也不证明物理设备或自然人身份。客户端只应向本站 HTTPS /api/ 发送设备凭证，并阻止跨站重定向。

X-Real-IP 由可信反向代理覆盖，仅特定代理地址受信任；不要依靠客户端伪造此头改变限流或封禁。服务端不信任任意 X-Forwarded-For。

2. 标识与有效期

key 与 ref

服务器依据歌曲完整内部对象计算 key，并保存歌曲。客户端不能提交任意平台 ID、标题或 URL 来代替 key。

ref 目前为 base64url(JSON歌曲).HMAC-SHA256，是防篡改引用，不是加密数据。客户端应将其视为不透明字符串，不自行解码、修改、生成或提取第三方信息。原有“签名过期”错误文案不表示 ref 有独立 TTL。

收藏应保存 ref；下次播放可先 /api/restore 获取当前 key。恢复返回的新 key 有可能与原 key 相同，但重新注册缓存项；不要要求 key 一定变化。签名密钥被替换、引用损坏或音源禁用时恢复会失败。

网易云 search_signals 被排除在歌曲缓存和签名之外，避免搜索排名变化改变歌曲身份。经恢复得到的歌曲通常没有该查询的排序信号。

默认插件

• 后台目录 default_plugin 是管理员配置值；effective_default_plugin 是当前实际生效值。
• 公开 /api/sources.default_plugin 和 /api/plugins.default_plugin 返回有效值，不是必须等于原始配置值。
• 没有配置默认时有效值为空，不自动挑插件；原平台 /api/media 仍可使用。
• 已配置的插件禁用后，按后台插件创建时间/ID顺序选择其他启用项；全部禁用时为空。原配置插件重新启用后恢复原默认。
• 公开插件接口中 plugin 省略、default 或稳定别名都会映射有效默认；没有默认返回 503，不会自动转为原平台解析。
• 当前 Android 2.2.2 在解析支持的平台前读 /api/sources；有效默认为空才走原平台。获取配置或插件解析失败会报告错误，不静默换源。

3. 公共数据模型

3.1 Source

已知基础平台：qq、netease、kugou、kuwo、migu、soda、bilibili、qianqian、joox、jamendo、fivesing、apple。后台支持配置不代表当前公开目录全部启用。

LX 映射：netease → wy、qq → tx、kugou → kg、kuwo → kw、migu → mg；汽水和哔哩哔哩不在当前网关 LX 映射中。

3.2 Song

Song 不返回原始平台 id、内部 extra 和上游音频 URL 字段。ref 不透明，不应作为这些字段的公共替代查询接口。

3.3 Playlist

3.4 网易云 search_signals

version.status 为 metadata_hint 或 unmarked_not_original。已识别 kinds：live、cover、remix、instrumental、piano、sped_up、slowed、acoustic、remaster、interlude、rnb。

证据对象：{kind, field, text, confidence: "metadata_hint"}，来自明确标题版本段或 alia/alias。原唱引用对象：{artist_text, field, text, confidence: "reference_only_not_recording_proof"}。

候选字段只是未经解释的观察值；标题、权限码、上游次序都不应被展示为真实热度。未标注版本不等于原版。排序范围是当前页，不是全库热度排序。

4. 错误与状态码

常见错误：

{"error":"结果已过期，请重新搜索"}

可选附加字段有 code、source、upstream_status、state、songs。插件 probe 失败可能返回 {ok:false, detail, error}；客户端可按 error、detail、HTTP 状态依次降级。不存在统一业务数字错误码表；code: access_blocked 是明确存在的例外。

没有保证的 Retry-After。原平台上游 401/403/404/429 等通常被包装为外层 502，原值在 upstream_status，不可只看 HTTP 判断平台原因。

音频响应一旦发送头部，后续断流不能再转为 JSON 错误。HTTP 200 不等于文件完整；完整播放与下载完整性要由客户端核验。

5. 资源与缓存限制

以下为找到的源码默认值，按进程计算，并非公开吞吐 SLA。

服务器搜索/元数据超时通常 12..22 秒；原平台音频连接 35 秒；LX 运行时请求 32 秒、工作进程 28 秒、第三方取流 15 秒。实际端到端可叠加，不应把其中某个值当固定 SLA。

6. 安全与兼容

• 网关仅接受服务器已知歌曲，插件媒体仅接受票据；没有公开任意 URL 代理接口。
• 歌单链接只提取受支持主机的 ID，不任意抓取用户 URL；短链不展开。
• 插件 HTTP 使用 SSRF 防护、公共地址校验及资源限制；启用脚本需要管理员确认信任。
• 管理统计包含真实 IP 等敏感运营数据，不应公开导出示例或备份。
• GET 插件 probe/resolve 会执行第三方请求；不要因其是 GET 就进行预取、爬取或浏览器自动探测。
• 多实例网关的进程内 key/ticket 需要共享存储或粘性路由，签名密钥也须一致。当前代码不提供这套协调机制。
• 接口接受新增字段；客户端应忽略未知字段，但不能把缺失字段填成已确认的热度、原唱、可播放或无损结论。