MusicWorkshop/services/metadata/README.md

Metadata Services

这个目录用来管理 MusicWorkshop 的第三方元数据代理，不改主项目前后端代码。

当前默认地址：

• 网易云：http://127.0.0.1:3000
• QQ：http://127.0.0.1:3300

这两个地址与后端默认配置保持一致，可直接填到设置页的 metadata.netease 和 metadata.qq。

目录说明

services/metadata/
  README.md
  versions.lock
  config/services.env.example
  scripts/
  src/                # 第三方源码，已加入 .gitignore

运行时日志和 PID 会写到：

.dev-runtime/metadata/

初始化

先按需复制一份本地覆盖配置：

cd /home/liumangmang/GiteaRepos/LiuMangMang/MusicWorkshop/services/metadata
cp config/services.env.example .env.local

然后执行初始化：

./scripts/bootstrap.sh

它会：

• 在 src/netease-api/ 准备一个本地 npm 工作区，并固定安装 NeteaseCloudMusicApi
• 拉取 QQ 的第三方源码到 src/qq-music-api/
• 将 QQ 固定到 versions.lock 中的 revision
• 安装各自依赖
• 为 QQ 服务补一个最小端口兼容补丁（仅当上游仍写死 3200 时）
• 为 QQ 服务补一个 /search 兼容层，让返回结构对齐 MusicWorkshop 当前后端解析逻辑

如果 src/qq-music-api/ 里已经存在你自己的工作区，bootstrap.sh 会保留现状，只提示当前 revision 和锁定 revision 是否一致。

启动与停止

启动：

./scripts/start.sh

查看状态：

./scripts/status.sh

停止：

./scripts/stop.sh

设置页填写

在 MusicWorkshop 设置页中填：

• 网易云音乐 API：http://127.0.0.1:3000
• QQ 音乐 API：http://127.0.0.1:3300

保存后，前端会从“尚未检测”进入实际探测状态。

上游来源

• 网易云默认使用 npm 包 NeteaseCloudMusicApi，因为 GitHub 归档仓库主分支已被清空，只保留版权说明
• QQ 默认使用 Rain120/qq-music-api 的固定 revision，因为当前后端已经兼容它的 data.song.list / result.list

如果你要切换到自己的 fork，只需要改 .env.local 里的源类型和对应的 *_REPO_URL / *_REF。