服务端 API 参考

这一页是拼好歌服务端的管理接口参考，面向自己部署服务端的人：怎么查服务状态、怎么管理音源脚本、怎么接入账号与数据同步。

接口全部挂在你的服务器域名下，路径形如 https://你的域名/你的API_KEY/api/...。部署方法见服务端部署使用教程；服务端整体设计见服务端架构。

文档范围

本页只描述服务端自身的管理能力。

音源脚本的业务逻辑由使用者自行编写，并在隔离沙箱内执行；服务端只提供运行环境与转发通道，不参与其中任何业务判断。这部分属于插件协议，见音源插件使用教程。

环境变量（API_KEY、PUBLIC_KEY、ADMIN_EMAIL 等）怎么配，见服务端架构 → 环境变量。

统一响应格式

所有接口返回统一的 JSON 格式：

json

{
  "code": 200,
  "msg": "success",
  "data": { }
}

字段	类型	说明
`code`	number	状态码，成功为 200，其余见错误码
`msg`	string	响应消息
`data`	object / null	响应数据，失败时可能为 `null`

鉴权与密钥

服务端用两把密钥，分开鉴权：

路由形态	用途	用什么密钥
`/{apiKey}/api/...`、`/owner/{apiKey}/...`	管理路由	`API_KEY`（兼作 Owner Key）
`/{publicKey}/...`	客户端路由	`PUBLIC_KEY`

本页所有接口都属于管理路由，路径里的 {apiKey} 填 API_KEY。
客户端只需要持有 PUBLIC_KEY；不设置 PUBLIC_KEY 时客户端路由不可用。
API_KEY 有公开默认值，部署后必须改，否则任何人都能访问你的接口。

服务信息

获取服务信息

http

GET /{apiKey}/status

返回服务版本与用量统计等信息。客户端可据此检查连通性和版本兼容性。

响应示例：

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "status": "ok",
    "serverVersion": "1.0.20",
    "serverVersionCode": 1020,
    "platform": "cloudflare",
    "minClientVersion": "1.0.01",
    "minClientVersionCode": 1001,
    "public_key": "a1b2c3d4...",
    "api_call_stats": [{ "date": "2026-07-20", "count": 45 }],
    "api_call_total": 1234
  }
}

版本号随发布变化，示例中的 1.0.20 只用于说明字段格式。

脚本管理接口

音源脚本是使用者自行准备的 JavaScript 文件，导入后由服务端沙箱加载。这一组接口负责导入、查看、设默认与删除。

获取已加载脚本列表

http

GET /{apiKey}/api/scripts/loaded

返回当前已加载的脚本及其运行统计。

响应示例：

json

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": "user_api_abc123",
      "name": "示例脚本",
      "description": "说明文字",
      "author": "作者名",
      "homepage": "https://example.com",
      "version": "1.0.0",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "supportedSources": ["kw", "kg", "tx", "wy", "mg"],
      "isDefault": true,
      "successRate": 0.92,
      "successCount": 100,
      "failCount": 8,
      "totalRequests": 108,
      "isCircuitBroken": false
    }
  ]
}

从 URL 导入脚本

http

POST /{apiKey}/api/scripts/import/url
Content-Type: application/json

{
  "url": "https://example.com/source.js"
}

从原始内容导入脚本

http

POST /{apiKey}/api/scripts/import/raw
Content-Type: application/json

{
  "name": "脚本名称",
  "content": "base64编码的脚本内容"
}

设置默认脚本

http

POST /{apiKey}/api/scripts/default
Content-Type: application/json

{
  "id": "user_api_abc123"
}

删除脚本

http

POST /{apiKey}/api/scripts/delete
Content-Type: application/json

{
  "id": "user_api_abc123"
}

注意：如果删除的是默认脚本，系统会自动将剩余的第一个脚本设为默认。

账号与数据同步接口

这组接口解决什么问题

用于用户账号体系与多设备数据同步：注册、登录、推送、拉取、重置密码、设备会话管理。

客户端在「设置 → 服务器地址」填入 域名/API_KEY 后即可注册或登录；登录后歌单、播放历史等数据会同步到云端，多设备之间保持一致。

本组接口位于 /{apiKey}/api/sync/...，需要 API_KEY（不是 PUBLIC_KEY）。注册码与重置码均由管理员在管理后台生成后发给用户。

注册

http

POST /{apiKey}/api/sync/register
Content-Type: application/json

{
  "reg_code": "ABC123",
  "username": "小明",
  "email": "user@example.com",
  "password": "123456",
  "password_confirm": "123456",
  "device_info": "iPhone 15",
  "platform": "ios",
  "app_version": "1.0.20"
}

请求参数：

字段	类型	必填	说明
`reg_code`	string	是	注册码，由管理员在管理后台生成
`username`	string	是	用户名
`email`	string	是	邮箱（登录账号，需符合邮箱格式）
`password`	string	是	密码，至少 6 位
`password_confirm`	string	是	确认密码，须与 `password` 一致
`device_info`	string	否	设备描述，用于「设备管理」列表
`platform`	string	否	平台标识（如 `ios` / `android` / `windows`）
`app_version`	string	否	客户端版本号

响应示例：

json

{
  "code": 200,
  "msg": "注册成功",
  "data": {
    "sync_token": "8f3c...e1",
    "version": 0,
    "user": { "id": 1, "email": "user@example.com", "username": "小明", "role": "user" }
  }
}

说明：

注册码分 user 与 admin 两类；用 admin 类注册码注册的账号，role 为 admin。
sync_token 是后续所有同步接口的凭证，客户端需安全保存。

错误： 400=缺少必填参数 / 两次密码不一致 / 密码至少 6 位 / 邮箱格式不正确；403=注册码无效；409=邮箱已注册。

推送数据

http

POST /{apiKey}/api/sync/push
Content-Type: application/json

{
  "sync_token": "8f3c...e1",
  "version": 12,
  "data": { }
}

请求参数：

字段	类型	必填	说明
`sync_token`	string	是	登录后获得的凭证
`version`	number	是	客户端当前数据版本，必须 ≥ 服务端版本
`data`	object	是	本次要写入的数据，字段见同步的数据范围

响应示例：

json

{ "code": 200, "msg": "推送成功", "data": { "version": 13 } }

版本冲突（409）： 客户端 version 小于服务端时返回 409，并在 data.server_data 中附带服务端最新数据，客户端应先 pull 合并后再推送：

json

{
  "code": 409,
  "msg": "版本冲突，请先 pull 最新数据",
  "data": {
    "server_data": { "version": 15, "schemaVersion": 1, "lists": [], "timestamps": {} }
  }
}

错误： 400=缺少 sync_token；401=token 无效或已失效；409=版本冲突；413=数据过大（单个歌单或单个类型序列化后超过 900 KB）；500=写入失败（可重试）。

拉取数据

http

GET /{apiKey}/api/sync/pull?sync_token=8f3c...e1&version=12

请求参数：

字段	类型	必填	说明
`sync_token`	string	是	登录凭证
`version`	number	是	客户端当前数据版本

响应示例：

json

{
  "code": 200,
  "msg": "拉取成功",
  "data": {
    "sync_data": { "version": 13, "schemaVersion": 1, "lists": [], "timestamps": {} },
    "version": 13
  }
}

数据未修改： 客户端 version 与服务端一致且服务端版本大于 0 时，返回业务码 304（HTTP 仍为 200），data.version 为服务端版本，客户端可直接跳过合并。

错误： 400=缺少 sync_token；401=token 无效或已失效。

同步的数据范围与体积限制

data 支持以下字段：

字段	类型	说明
`lists`	array	歌单列表（服务端按单个歌单拆行存储）
`playHistory`	array	播放历史
`playListHistory`	array	歌单播放历史
`dislikeRules`	string	不喜欢规则
`deletedSongs`	array	已删除歌曲（用于多端同步删除）
`config`	object	客户端配置
`timestamps`	object	各类型的最后修改时间戳，用于增量同步判脏

说明：

单个体积上限 900 KB：单个歌单、或单个类型序列化后超过 900 KB 会被拒绝（返回 413）。该阈值是为 D1「单值 2 MB」硬限预留余量。
部分推送安全：timestamps 的键集合决定「本次包含哪些类型」。若某类型为空值且未被 timestamps 标记，服务端保留既有值，不会被空值清空。
服务端不做同步频率配额：同步时机（防抖、退后台、满 50 首等）完全由客户端控制。

重置密码

http

POST /{apiKey}/api/sync/reset
Content-Type: application/json

{
  "email": "user@example.com",
  "reset_code": "RST456",
  "new_password": "654321",
  "new_password_confirm": "654321"
}

说明： 重置码由管理员在后台生成，且绑定到指定账号（只能用于该邮箱）。重置成功后，该账号所有设备会话会被作废，需重新登录。

错误： 400=缺少必填参数 / 两次密码不一致 / 密码至少 6 位；403=重置码无效 / 已禁用 / 已过期 / 已使用 / 与账号不匹配；404=用户不存在。

注销登录

http

POST /{apiKey}/api/sync/logout
Content-Type: application/json

{ "sync_token": "8f3c...e1" }

使当前 sync_token 失效，并删除对应的会话记录。

错误： 400=缺少 sync_token；401=token 无效。

设备会话管理

列出登录设备：

http

GET /{apiKey}/api/sync/sessions?sync_token=8f3c...e1

返回该账号的全部设备会话，按最后活跃时间倒序；当前设备 is_current 为 true。

json

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "sync_token": "8f3c...e1",
      "device_info": "iPhone 15",
      "platform": "ios",
      "app_version": "1.0.20",
      "created_at": 1750000000000,
      "last_active": 1750000000000,
      "is_current": true
    }
  ]
}

将某台设备踢下线：

http

POST /{apiKey}/api/sync/sessions/revoke
Content-Type: application/json

{
  "sync_token": "8f3c...e1",
  "target_token": "a1b2...c3",
  "password": "123456"
}

说明：

需提交登录密码做二次校验（服务端不信任客户端）；
不允许踢下线当前设备本身；
目标会话必须属于当前账号，否则返回 404。

错误： 400=缺少目标会话标识 / 请输入登录密码 / 不能踢下线当前设备；401=token 无效或登录密码错误；404=目标设备不存在或不属于当前账号。

修改用户名

http

POST /{apiKey}/api/sync/update-username
Content-Type: application/json

{
  "sync_token": "8f3c...e1",
  "new_username": "新用户名"
}

普通用户修改自己的用户名。若在 body 中额外传 user_id，则视为管理员修改他人用户名，需管理员权限。默认管理员账号不允许通过本接口改用户名（其凭据由 Cloudflare 环境变量管理）。

错误： 400=缺少 sync_token / 用户名不能为空；401=token 无效或已失效；403=无权限 / 默认管理员账号不允许在后台修改用户名。

curl 测试命令

以下命令把域名与密钥换成你自己的即可，全部使用管理路由（API_KEY）。

获取服务信息

bash

curl https://你的域名/你的API_KEY/status

获取已加载脚本

bash

curl https://你的域名/你的API_KEY/api/scripts/loaded

从 URL 导入脚本

bash

curl -X POST https://你的域名/你的API_KEY/api/scripts/import/url \
  -H 'Content-Type: application/json' \
  -d '{"url":"<你的脚本URL>"}'

设置默认脚本

bash

curl -X POST https://你的域名/你的API_KEY/api/scripts/default \
  -H 'Content-Type: application/json' \
  -d '{"id":"user_api_abc123"}'

错误码

状态码	说明
200	成功
400	参数错误
403	无权限（Owner Key 错误）
410	尚未导入任何音源脚本
411	没有支持该源的脚本
412	候选音源均不可用
429	用量已达上限
500	服务器内部错误

业务码 304 与 409

数据同步接口还有两个业务码，HTTP 状态码仍是 200：304（拉取时数据未修改）、409（推送时版本冲突，data.server_data 会带服务端最新数据）。

服务端 API 参考 ​

统一响应格式 ​

鉴权与密钥 ​

服务信息 ​

获取服务信息 ​

脚本管理接口 ​

获取已加载脚本列表 ​

从 URL 导入脚本 ​

从原始内容导入脚本 ​

设置默认脚本 ​

删除脚本 ​

账号与数据同步接口 ​

注册 ​

登录 ​

推送数据 ​

拉取数据 ​

同步的数据范围与体积限制 ​

重置密码 ​

注销登录 ​

设备会话管理 ​

修改用户名 ​

curl 测试命令 ​

获取服务信息 ​

获取已加载脚本 ​

从 URL 导入脚本 ​

设置默认脚本 ​

错误码 ​

相关页面 ​

服务端 API 参考

统一响应格式

鉴权与密钥

服务信息

获取服务信息

脚本管理接口

获取已加载脚本列表

从 URL 导入脚本

从原始内容导入脚本

设置默认脚本

删除脚本

账号与数据同步接口

注册

登录

推送数据

拉取数据

同步的数据范围与体积限制

重置密码

注销登录

设备会话管理

修改用户名

curl 测试命令

获取服务信息

获取已加载脚本

从 URL 导入脚本

设置默认脚本

错误码

相关页面