# Wristhyme API 文档

整理日期：2026-10-01。语言：中文。适用对象：手机、手表、桌面、iOS 客户端开发者及后台维护者。本独立包已进一步对照服务器只读提取的当前源码，支持配置自己的域名；文中官方地址为原部署示例，接入时替换为本实例ADMIN_ORIGIN对应域名。

本文档依据源码、部署补丁与发布记录整理，**不是生产音乐在线验收报告**。本次只读提取服务器源码，未登录生产后台、未执行生产管理写操作或真实音乐请求；独立测试结果见包根VERIFICATION.md。示例中的歌曲、标识、签名和令牌都是说明性占位数据，不能直接用于播放。

## 阅读入口

| 文档 | 内容 |
| --- | --- |
| [协议与数据模型](./protocol.md) | 服务边界、HTTP、鉴权、字段类型、生命周期、状态码、限流与安全 |
| [公开音乐 API](./public.md) | 音源、搜索、歌单、榜单、还原、播放、下载、歌词和插件 |
| [设备统计 API](./devices.md) | 隐私说明、自愿注册、心跳、撤回统计 |
| [后台管理 API](./admin.md) | 登录、会话、仪表盘、目录、封禁、插件、音源、导入、密码 |
| [内部服务](./internal.md) | LX 运行时、统计内部协议、上游边界及路由清单 |
| [接入与维护](./integration.md) | 调用流程、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**。

## 接口总表

以下为公开及管理员接口的完整目录；内部接口另见 [内部服务](./internal.md)。

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| 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` | 删除未发布文件 |

## 重要边界

1. 本包gateway/admin/lx-runtime是从服务器当前文件只读提取后作独立部署适配的完整代码，原始来源及哈希见PROVENANCE.json，不再需要原工作区历史补丁目录才能运行。
2. 原API路径保持；域名、可信代理、服务地址及数据路径可配置。本文档保留历史版本比较，部署差异见包根CHANGELOG.md及部署文档。
3. `/api/health.version` 是网关代码中的字符串，不应当作当前 Android 发行版本或协议版本。
4. 音源以 `/api/sources` 的实时返回为准；七个启用音源是历史部署设置，不是永久固定配置。
5. `key`、`ref`、插件 `ticket`、匿名设备令牌和后台 Cookie 各有不同用途，不能互换。
6. 搜索可见、检查可用、插件初始化通过、解析成功、网关开始取流、客户端完整播放是不同状态。
7. 新 Android 2.2.2 自动遵循后台有效默认插件；旧客户端可能保持手动选择。`consent=1` 的服务端合同仍存在。
8. 所有示例按单机/进程内缓存实现解释；多实例部署需要额外解决 key、票据和状态共享问题。