Mymusic3/Netease-sync/需求.md

Netease-sync 需求文档

项目概述

在当前目录下新建一个简单的 Node.js 项目，实现和 Navidrome 的联动，将网易云音乐歌单同步到 Navidrome。

核心功能

1. 歌单输入

• 前台页面支持输入网易云音乐的歌单 ID 或分享链接
• 支持从歌单 URL 中提取 ID（如 https://music.163.com/#/playlist?id=123456 提取 123456）
• 只支持网易云音乐平台

2. 歌单读取

• 调用 TuneHub API 获取歌单详情
• API: GET /api/?source=netease&id={playlistId}&type=playlist
• 获取歌单名称、封面、描述、歌曲列表等元数据

3. 歌曲下载

• 调用现有的 sync-server 下载逻辑
• 包括元数据写入（title, artist, album, cover）
• 不创建歌单缓存 JSON 文件，避免和主 app 混淆
• 下载到 sync-server 的 music 目录（Navidrome 也读取此目录）
• 如果下载失败，尝试换源（根据 api.md 支持的平台：netease, kuwo, qq）
• 不重试，失败则跳过

4. Navidrome 歌单创建

• 使用 Navidrome 的 Subsonic API
• 在 Navidrome 中创建同名歌单
• 将下载的歌曲加入歌单
• 同步歌单的所有元数据（封面、描述等）

5. 同步策略

• 增量同步：只新增歌曲，不删除已有歌曲
• 通过网易云音乐歌曲 ID 判断，在本地维护一个映射表（netease_song_id -> navidrome_song_id）
• 定时同步：每 300 秒自动同步一次（可配置）
• 支持手动立即同步

6. 前端界面

• 显示已添加的歌单列表
• 显示每个歌单的同步状态（同步中/成功/失败）
• 显示上次同步时间
• 提供立即同步按钮
• 支持添加/删除歌单

配置项

Docker 环境变量

• NAVIDROME_URL: Navidrome 服务器地址（如 http://navidrome:4533）
• NAVIDROME_USERNAME: Navidrome 用户名
• NAVIDROME_PASSWORD: Navidrome 密码
• SYNC_INTERVAL: 同步间隔（秒），默认 300
• SYNC_SERVER_URL: sync-server 地址（如 http://sync-service:3001）
• SYNC_SERVER_TOKEN: sync-server 的 token（用于 KV API）
• TUNEHUB_API_URL: TuneHub API 地址（如 https://music-dl.sayqz.com）

技术架构

后端

• Node.js + Express
• 调用 sync-server 的 KV API 传递歌曲列表
• 调用 Navidrome Subsonic API 创建歌单
• 定时任务：每 N 秒检查并同步歌单
• 数据持久化：JSON 文件存储歌单列表和映射表

前端

• 简单的 HTML + JavaScript 页面
• 实时显示同步状态（WebSocket 或轮询）
• 添加/删除歌单功能

Subsonic API 集成

认证

所有 API 请求需要包含以下参数：

• u: 用户名
• p: 密码（明文或 hex 格式）
• v: API 版本（如 1.16.0）
• c: 客户端名称（如 netease-sync）

主要端点

1. 创建歌单: createPlaylist

   • 参数：name（歌单名称）、songId（歌曲 ID 列表，逗号分隔）
   • 返回：创建的歌单 ID

2. 更新歌单: updatePlaylist

   • 参数：playlistId（歌单 ID）、songIdToAdd（要添加的歌曲 ID）

3. 获取歌单列表: getPlaylists

4. 搜索歌曲: search3

   • 参数：query（搜索关键词）
   • 用于根据文件名查找 Navidrome 中的歌曲 ID

歌曲匹配策略

参考 sync-server 的去重逻辑，文件名格式为：Artist - Name [source_id].ext

匹配步骤：

1. 下载完成后，Navidrome 会自动扫描新歌曲
2. 通过 search3 搜索文件名（如 Artist - Name [netease_id]）来获取 Navidrome 的歌曲 ID
3. 将网易云音乐歌曲 ID 映射到 Navidrome 歌曲 ID

数据结构

歌单列表 (playlists.json)

{
  "playlists": [
    {
      "id": "netease_123456",
      "neteaseId": "123456",
      "name": "歌单名称",
      "cover": "封面URL",
      "description": "歌单描述",
      "navidromePlaylistId": "navidrome_playlist_id",
      "lastSyncTime": "2025-01-12T10:00:00Z",
      "syncStatus": "success",
      "songMapping": {
        "netease_song_id_1": "navidrome_song_id_1",
        "netease_song_id_2": "navidrome_song_id_2"
      }
    }
  ]
}

换源逻辑

如果网易云音乐下载失败，尝试换源：

• 优先级：kuwo -> qq
• 每个平台只尝试一次，不重试

错误处理

• 某首歌下载失败，跳过继续下载其他歌曲
• 不重试
• 错误日志输出到 Docker 控制台，不存储

Navidrome 扫描延迟

• Navidrome 扫描新歌曲很快，不处理延迟
• 在添加到歌单时直接搜索歌曲 ID