原文
Wristhyme API 文档
整理日期：2026-10-01。语言：中文。适用对象：手机、手表、桌面、iOS 客户端开发者及后台维护者。本独立包已进一步对照服务器只读提取的当前源码，支持配置自己的域名；文中官方地址为原部署示例，接入时替换为本实例ADMIN_ORIGIN对应域名。
本文档依据源码、部署补丁与发布记录整理，不是生产音乐在线验收报告。本次只读提取服务器源码，未登录生产后台、未执行生产管理写操作或真实音乐请求；独立测试结果见包根VERIFICATION.md。示例中的歌曲、标识、签名和令牌都是说明性占位数据，不能直接用于播放。
阅读入口
| 文档 | 内容 |
|---|---|
| 协议与数据模型 | 服务边界、HTTP、鉴权、字段类型、生命周期、状态码、限流与安全 |
| 公开音乐 API | 音源、搜索、歌单、榜单、还原、播放、下载、歌词和插件 |
| 设备统计 API | 隐私说明、自愿注册、心跳、撤回统计 |
| 后台管理 API | 登录、会话、仪表盘、目录、封禁、插件、音源、导入、密码 |
| 内部服务 | LX 运行时、统计内部协议、上游边界及路由清单 |
| 接入与维护 | 调用流程、curl/JavaScript 示例、版本差异、来源索引与验证清单 |
服务划分
公开基地址：https://wristhyme.tolike.cn。
| 层 | 路径/内部地址 | 使用者 | 说明 |
|---|---|---|---|
| 音乐网关 | /api/*，容器端口 8766 |
所有客户端 | JSON 元数据和二进制音频；无需管理员登录 |
| 管理后台 | /admin/api/*，容器端口 8780 |
管理员 | Cookie 会话；POST 必须同源且通过 CSRF |
| 下载发布 | /downloads/* |
更新器、浏览器 | 静态文件，不是歌曲下载任务服务 |
| LX 运行时 | http://watch-music-lx:8770 |
网关 | 不应公开暴露；隔离执行服务器已知脚本 |
| 管理内部接口 | http://watch-music-admin:8780/internal/* |
网关 | 内部共享密钥，不接受公网客户端调用 |
| 上游 | http://watch-music-upstream:8080/music |
网关 | go-music-dl 私有服务；并非公开 /api 的同义路径 |
后台页面是 /admin；主页 /、/LICENSE 是静态内容。客户端收藏、私人歌单、队列、播放模式、本地音乐文件和下载任务主要保存在客户端，没有据此实现的云端用户账号、歌单 CRUD 或队列 API。
接口总表
以下为公开及管理员接口的完整目录；内部接口另见 内部服务。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/health |
网关健康信息 |
| GET | /api/sources |
动态音源与当前有效默认插件 |
| GET | /api/search |
通用歌曲搜索 |
| GET | /api/playlist_search |
公共歌单名称搜索 |
| GET | /api/playlist |
公共歌单歌曲分页/链接导入 |
| GET | /api/watch/search |
每页 10 首的轻量搜索 |
| GET | /api/watch/recommend |
QQ/网易云公开推荐歌单 |
| GET | /api/watch/playlist |
QQ/网易云歌单每页 10 首 |
| GET | /api/charts/hot |
QQ/网易云热歌榜 |
| GET | /api/restore |
从签名引用恢复歌曲 |
| GET | /api/inspect |
原平台音频信息检查 |
| GET | /api/media |
原平台音频流/歌曲附件 |
| GET | /api/playback_status |
原平台网关取流的短期状态 |
| GET | /api/lyric |
原平台歌词 |
| GET | /api/snapshot |
下载时歌曲元数据和歌词快照 |
| GET | /api/plugins |
已启用插件目录 |
| GET | /api/plugin_probe |
插件初始化检测 |
| GET | /api/plugin_resolve |
插件解析并签发网关取流票据 |
| GET | /api/plugin_media |
使用票据取流 |
| GET | /api/plugin_lyric |
插件歌词 |
| GET | /api/device/privacy |
统计隐私说明 |
| POST | /api/device/register |
自愿注册匿名安装实例 |
| POST | /api/device/heartbeat |
匿名实例心跳 |
| POST | /api/device/forget |
撤回统计并清除服务端记录 |
| POST | /admin/api/login |
登录后台 |
| GET | /admin/api/session |
会话与 CSRF |
| GET | /admin/api/dashboard |
活动统计及分页记录 |
| GET | /admin/api/catalog |
插件/音源/封禁/审计目录 |
| POST | /admin/api/logout |
退出 |
| POST | /admin/api/password |
修改管理员密码 |
| POST | /admin/api/ban |
封禁设备或 IP/CIDR |
| POST | /admin/api/unban |
解除封禁 |
| POST | /admin/api/plugin |
修改插件名称及启用状态 |
| POST | /admin/api/default-plugin |
指定/清除默认插件 |
| POST | /admin/api/source |
新增/修改音源目录项 |
| POST | /admin/api/source/delete |
删除自定义音源 |
| POST | /admin/api/forget |
管理员清除活动统计 |
| POST | /admin/api/import |
导入 LX 脚本，支持后台上传与 GitHub 固定提交 |
| GET | /admin/api/maintenance |
读取维护模式 |
| POST | /admin/api/maintenance |
保存全局或指定接口维护模式 |
| GET | /admin/api/releases |
发行文件与更新渠道 |
| POST | /admin/api/releases/begin |
创建分块上传 |
| POST | /admin/api/releases/chunk |
上传二进制块 |
| POST | /admin/api/releases/finish |
校验并完成上传 |
| POST | /admin/api/releases/cancel |
取消上传 |
| POST | /admin/api/releases/publish |
发布更新 feed |
| POST | /admin/api/releases/delete |
删除未发布文件 |
重要边界
- 本包gateway/admin/lx-runtime是从服务器当前文件只读提取后作独立部署适配的完整代码，原始来源及哈希见PROVENANCE.json，不再需要原工作区历史补丁目录才能运行。
- 原API路径保持；域名、可信代理、服务地址及数据路径可配置。本文档保留历史版本比较，部署差异见包根CHANGELOG.md及部署文档。
/api/health.version是网关代码中的字符串，不应当作当前 Android 发行版本或协议版本。- 音源以
/api/sources的实时返回为准；七个启用音源是历史部署设置，不是永久固定配置。 key、ref、插件ticket、匿名设备令牌和后台 Cookie 各有不同用途，不能互换。- 搜索可见、检查可用、插件初始化通过、解析成功、网关开始取流、客户端完整播放是不同状态。
- 新 Android 2.2.2 自动遵循后台有效默认插件；旧客户端可能保持手动选择。
consent=1的服务端合同仍存在。 - 所有示例按单机/进程内缓存实现解释；多实例部署需要额外解决 key、票据和状态共享问题。