# 📖 网易云音乐工具箱 (v9.x - Web 应用重构版)



本项目是基于原版 `Netease_url` 项目的深度重构，旨在将其从一个依赖本地 `cookie.txt` 的工具，升级为一个**支持多用户、无状态后端、客户端认证**的现代化 Web 应用。



## ✨ V9 核心功能升级



相较于原版，V9 架构带来了质的飞跃：

- **用户认证系统**：
  - **扫码登录**：移除本地脚本，实现了完整的 API 驱动的扫码登录流程。
  - **客户端凭证**：用户 Cookie **不再**存储于服务器。登录成功后，Cookie 凭证安全地存储在**用户自己的浏览器 `localStorage`** 中。
- **无状态 (Stateless) 后端**：
  - 服务器**不保存任何用户状态**。所有 API 请求均通过 `localStorage` 自动携带 Cookie 凭证进行鉴权。
  - **高并发支持**：天然支持多用户同时登录和使用，Cookie 互相隔离，绝不串号。
- **全局播放器**：
  - 实现了一个固定在底部的**全局 APlayer 播放器**。
  - 音乐播放在页面内导航、搜索、解析时**不会中断**，提供了现代音乐站的体验。
- **高级 UI/UX**：
  - **智能错误提示**：当解析高音质失败时，系统会智能判断用户是否未登录，并提示“请登录黑胶会员”。
  - **用户设置**：增加了“自动播放”开关，并将其偏好存储在 `localStorage`。
  - **安全加固**：在 F12 控制台增加了醒目的安全警告，防止用户被“社会工程学”攻击。



## 🚀 部署模式 (重要)



V9 架构支持两种部署模式，灵活性极高：



### 1. 🌍 服务器部署模式 (多用户)



这是标准的线上部署模式。

1. **清空 `cookie.txt`**：将 `cookie.txt` 文件内容设置为空。
2. **启动服务**：`python main.py`。
3. **用户流程**：
   - 访问者**必须**点击右上角的“登录”按钮。
   - 通过 App 扫码登录。
   - Cookie 自动保存在他们各自的浏览器中，全程不接触你的服务器。



### 2. 💻 本地开发模式 (单用户)



这是你自己本地调试时使用的便捷模式。

1. **填写 `cookie.txt`**：在 `cookie.txt` 中填入你自己的黑胶会员 Cookie。
2. **启动服务**：`python main.py`。
3. **开发者流程**：
   - 你**无需**点击“登录”按钮。
   - 当你进行解析、下载等操作时，前端 `index.html` 会发送一个“空”的 Cookie。
   - 后端 `main.py` 的 `_get_cookies_from_request` 函数会检测到 Cookie 为空，并**自动降级 (Fallback)** 去读取 `cookie.txt` 中的内容来完成请求。



## 🔌 API 接口文档 (V9)



原版的 API 文档 已失效。以下是当前 `main.py` 提供的有效接口。

**请求说明**：

- 所有需要鉴权的接口（如下载、解析高音质），都**必须**在 JSON 请求体中包含 `cookie` 字段。
- 前端 `index.html` 的 `getApiPayload` 函数会自动完成这一操作。

------



### /login/qr/generate



- **功能**：生成一个用于扫码登录的二维码 Key 和 Base64 图像。

- **方法**：`POST`

- **请求 (JSON)**：`{}` (无参数)

- **响应 (JSON)**：

  JSON

  ```
  {
    "success": true,
    "data": {
      "qr_key": "xxx-xxx-xxx",
      "qr_img_b64": "data:image/png;base64,..."
    }
  }
  ```

------



### /login/qr/check



- **功能**：轮询检查二维码的扫码状态。

- **方法**：`POST`

- **请求 (JSON)**：

  JSON

  ```
  {
    "qr_key": "xxx-xxx-xxx"
  }
  ```

- **响应 (JSON)** (code: `801`=等待, `802`=已扫码, `803`=成功, `800`=过期)：

  JSON

  ```
  {
    "success": true,
    "data": {
      "code": 803,
      "cookie": "MUSIC_U=...; __csrf=...;",
      "message": "登录成功"
    }
  }
  ```

------



### /search



- **功能**：搜索歌曲。

- **方法**：`POST`

- **请求 (JSON)**：

  JSON

  ```
  {
    "keyword": "蓝莲花",
    "cookie": "...(来自 localStorage)"
  }
  ```

------



### /song



- **功能**：解析单曲详情和播放链接。

- **方法**：`POST`

- **请求 (JSON)**：

  JSON

  ```
  {
    "url": "歌曲ID或链接",
    "level": "lossless",
    "cookie": "...(来自 localStorage)"
  }
  ```

------



### /playlist



- **功能**：解析歌单详情。

- **方法**：`POST`

- **请求 (JSON)**：

  JSON

  ```
  {
    "id": "歌单ID或链接",
    "cookie": "...(来自 localStorage)"
  }
  ```

------



### /album



- **功能**：解析专辑详情。

- **方法**：`POST`

- **请求 (JSON)**：

  JSON

  ```
  {
    "id": "专辑ID或链接",
    "cookie": "...(来自 localStorage)"
  }
  ```

------



### /download_song_zip



- **功能**：打包下载单曲（含封面、歌词）。

- **方法**：`POST`

- **请求 (JSON)**：

  JSON

  ```
  {
    "id": "歌曲ID",
    "quality": "lossless",
    "cookie": "...(来自 localStorage)"
  }
  ```

- **响应**：`application/zip` 文件流。

------



### /download_playlist_zip



- **功能**：打包下载整个歌单。

- **方法**：`POST`

- **请求 (JSON)**：

  JSON

  ```
  {
    "id": "歌单ID",
    "quality": "lossless",
    "cookie": "...(来自 localStorage)"
  }
  ```

- **响应**：`application/zip` 文件流。

------



### /download_album_zip



- **功能**：打包下载整个专辑。

- **方法**：`POST`

- **请求 (JSON)**：

  JSON

  ```
  {
    "id": "专辑ID",
    "quality": "lossless",
    "cookie": "...(来自 localStorage)"
  }
  ```

- **响应**：`application/zip` 文件流。



## 📝 架构与开发说明





### V9 核心架构



本项目成功的关键在于**“责任分离”**：

1. **`main.py` (服务层)**：作为“总指挥”。它**只负责**编排请求 (接收 HTTP、解析参数) 和响应 (返回 JSON 或 Zip)。它**不**包含任何Cookie管理或API请求的硬编码逻辑。
2. **`qr_login.py` (认证模块)**：**只负责**生成和检查二维码。
3. **`music_api.py` (API 模块)**：**只负责**调用网易云的 *JSON* API (如搜索、歌单详情)。它必须是“无状态的”，并接收 `cookies` 作为参数。
4. **`music_downloader.py` (下载模块)**：**只负责**获取 *文件* API (如歌曲 URL、歌词)，并处理打包逻辑。它也必须接收 `cookies` 参数。
5. **`cookie_manager.py` (工具模块)**：**只负责**解析 Cookie 字符串 (`parse_cookie_string`) 和读取 `cookie.txt` (作为备用)。
6. **`index.html` (客户端)**：作为“用户界面”和“**凭证保险箱**”。它**全权负责**存储 `userCookie`，并在**每一次** API 调用时主动提供它。



### 项目结构 (V9)



```
Netease_url/
├── main.py              # [!! 重构 !!] Flask 主程序, 路由层
├── music_api.py         # API 核心模块 (基本不变, 仅被调用)
├── music_downloader.py  # [!! 重构 !!] 下载模块 (已解耦, 需传入 cookie)
├── cookie_manager.py    # Cookie 管理工具 (现主要用于解析)
├── qr_login.py          # [!! 重构 !!] 从脚本变为 QR 登录 API 模块
├── templates/
│   └── index.html      # [!! 重构 !!] V9 前端应用
├── static/              # [!! 新增 !!] 静态文件目录
│   └── favicon.ico     # [!! 新增 !!] 网站图标
├── requirements.txt
├── cookie.txt           # (可选) 仅用于本地开发模式
└── README_v9.md         # (本文档)
```



### 未来升级的基石 (v10 展望)



基于 V9 的“无状态后端 + 客户端凭证”架构，我们为下一阶段的升级打下了完美的基础：

- **实现“我的音乐”**：
  - 后端：在 `music_api.py` 中新增 `get_user_playlists(uid, cookies)` 函数。
  - 后端：在 `main.py` 中新增 `/my/playlists` 路由，它调用上述函数。
  - 前端：在登录成功后，`fetch('/my/playlists')` 并在 `index.html` 中渲染一个新区域。
- **实现“真实进度条”**：
  - 后端：`main.py` 引入 `Flask-SocketIO`。
  - 后端：`_package_tracks_as_zip` 在 `for` 循环中 `socketio.emit` 真实进度。
  - 前端：`handleDownloadClick` 不再使用假进度 `setInterval`，而是 `socket.on('progress', ...)` 来更新进度条。
- **实现“歌单即时播放”**：
  - 前端：在 `renderCollection` 中增加“播放全部”按钮。
  - 前端：点击后，循环 `tracks` 列表，为每首歌调用 `/song` 接口。
  - 前端：将所有返回的 `data.url` 组装成一个列表，一次性 `globalAPlayer.list.add([...])`。