Netease_url/使用文档.md

# 网易云音乐工具箱 - 使用文档

## 📖 项目简介

网易云音乐工具箱是一个功能强大的网易云音乐解析工具，支持歌曲搜索、单曲解析、歌单解析、专辑解析和音乐下载等功能。项目提供了友好的Web界面和完整的API接口，支持多种音质选择，包括无损、Hi-Res等高品质音频格式。

## ✨ 功能特性

### 🎵 核心功能
- **歌曲搜索**：支持关键词搜索网易云音乐库中的歌曲
- **单曲解析**：解析单首歌曲的详细信息和下载链接
- **歌单解析**：批量解析歌单中的所有歌曲
- **专辑解析**：批量解析专辑中的所有歌曲
- **音乐下载**：支持多种音质的音乐文件下载

### 🎧 音质支持
- `standard`：标准音质 (128kbps)
- `exhigh`：极高音质 (320kbps)
- `lossless`：无损音质 (FLAC)
- `hires`：Hi-Res音质 (24bit/96kHz)
- `jyeffect`：高清环绕声
- `sky`：沉浸环绕声
- `jymaster`：超清母带

### 🌐 使用方式
- **Web界面**：直观的网页操作界面
- **API接口**：完整的RESTful API
- **批量处理**：支持歌单和专辑的批量解析

## 🚀 快速开始

### 环境要求
- Python 3.7+
- 网易云音乐黑胶会员账号（用于获取高音质资源）

### 安装步骤

1. **克隆项目**
   ```bash
   git clone https://github.com/Suxiaoqinx/Netease_url.git
   cd Netease_url
   ```

2. **安装依赖**
   ```bash
   pip install -r requirements.txt
   ```

3. **配置Cookie**
   
   在 `cookie.txt` 文件中填入黑胶会员账号的Cookie：
   
   > 💡 **获取Cookie方法**：
   > 1. 登录网易云音乐网页版
   > 2. 按F12打开开发者工具
   > 3. 在Network标签页找到任意请求
   > 4. 复制请求头中的Cookie值

4. **启动服务**
   ```bash
   python main.py
   ```

5. **访问界面**
   
   打开浏览器访问：`http://localhost:5000`

## 🎯 使用指南

### Web界面使用

#### 1. 歌曲搜索
1. 选择「歌曲搜索」功能
2. 输入搜索关键词
3. 点击「搜索」按钮
4. 在搜索结果中点击「解析」或「下载」按钮

#### 2. 单曲解析
1. 选择「单曲解析」功能
2. 输入歌曲ID或网易云音乐链接
3. 选择音质等级
4. 点击「解析」按钮查看歌曲信息
5. 点击「下载」按钮下载音乐文件

#### 3. 歌单解析
1. 选择「歌单解析」功能
2. 输入歌单ID或歌单链接
3. 点击「解析歌单」按钮
4. 查看歌单信息和歌曲列表
5. 点击单首歌曲的「解析」或「下载」按钮

#### 4. 专辑解析
1. 选择「专辑解析」功能
2. 输入专辑ID或专辑链接
3. 点击「解析专辑」按钮
4. 查看专辑信息和歌曲列表
5. 点击单首歌曲的「解析」或「下载」按钮

#### 5. 音乐下载
1. 选择「音乐下载」功能
2. 输入音乐ID或链接
3. 选择下载音质
4. 点击「下载」按钮
5. 等待下载完成

### 链接格式支持

项目支持多种网易云音乐链接格式：

- **歌曲链接**：`https://music.163.com/song?id=123456`
- **歌单链接**：`https://music.163.com/playlist?id=123456`
- **专辑链接**：`https://music.163.com/album?id=123456`
- **直接ID**：`123456`

## 🔌 API接口文档

### 基础信息
- **服务地址**：`http://localhost:5000`
- **请求方式**：POST（部分接口支持GET）
- **响应格式**：JSON

### 接口列表

#### 1. 健康检查
```http
GET /health
```

**响应示例**：
```json
{
  "status": 200,
  "success": true,
  "message": "服务运行正常",
  "data": {
    "service": "网易云音乐API",
    "version": "1.0.0",
    "uptime": "2小时3分钟"
  }
}
```

#### 2. 歌曲搜索
```http
POST /search
```

**请求参数**：
```json
{
  "keyword": "搜索关键词",
  "limit": 30
}
```

**响应示例**：
```json
{
  "status": 200,
  "success": true,
  "message": "搜索完成",
  "data": [
    {
      "id": "123456",
      "name": "歌曲名称",
      "artists": "艺术家",
      "album": "专辑名称",
      "picUrl": "封面图片URL"
    }
  ]
}
```

#### 3. 单曲解析
```http
POST /song
```

**请求参数**：
```json
{
  "url": "歌曲ID或链接",
  "level": "lossless",
  "type": "json"
}
```

**响应示例**：
```json
{
  "status": 200,
  "success": true,
  "message": "解析成功",
  "data": {
    "name": "歌曲名称",
    "ar_name": "艺术家",
    "al_name": "专辑名称",
    "level": "lossless",
    "size": "45.2MB",
    "url": "下载链接",
    "pic": "封面图片",
    "lyric": "歌词内容"
  }
}
```

#### 4. 歌单解析
```http
POST /playlist
```

**请求参数**：
```json
{
  "id": "歌单ID"
}
```

**响应示例**：
```json
{
  "status": 200,
  "success": true,
  "message": "歌单解析成功",
  "data": {
    "playlist": {
      "name": "歌单名称",
      "creator": "创建者",
      "description": "歌单描述",
      "coverImgUrl": "封面图片",
      "trackCount": 50,
      "tracks": [
        {
          "id": "123456",
          "name": "歌曲名称",
          "artists": "艺术家",
          "album": "专辑名称",
          "picUrl": "封面图片"
        }
      ]
    }
  }
}
```

#### 5. 专辑解析
```http
POST /album
```

**请求参数**：
```json
{
  "id": "专辑ID"
}
```

**响应示例**：
```json
{
  "status": 200,
  "success": true,
  "message": "专辑解析成功",
  "data": {
    "album": {
      "name": "专辑名称",
      "artist": "艺术家",
      "description": "专辑描述",
      "coverImgUrl": "封面图片",
      "songs": [
        {
          "id": "123456",
          "name": "歌曲名称",
          "artists": "艺术家",
          "album": "专辑名称",
          "picUrl": "封面图片"
        }
      ]
    }
  }
}
```

#### 6. 音乐下载
```http
POST /download
```

**请求参数**：
```json
{
  "id": "音乐ID",
  "quality": "lossless"
}
```

**响应**：返回音频文件流，支持直接下载

## 🐳 Docker部署

### 使用Docker Compose

1. **修改配置**（可选）
   
   编辑 `docker-compose.yml` 文件修改端口：
   ```yaml
   ports:
     - "8080:5000"  # 将服务映射到8080端口
   ```

2. **启动服务**
   ```bash
   docker-compose up -d
   ```

3. **查看日志**
   ```bash
   docker-compose logs -f
   ```

4. **停止服务**
   ```bash
   docker-compose down
   ```

### 使用Dockerfile

```bash
# 构建镜像
docker build -t netease-music-api .

# 运行容器
docker run -d -p 5000:5000 -v $(pwd)/downloads:/app/downloads netease-music-api
```

## ⚙️ 配置说明

### 环境变量

可以通过 `.env` 文件或环境变量配置服务：

```bash
# 服务配置
HOST=0.0.0.0
PORT=5000
DEBUG=false

# 下载配置
DOWNLOADS_DIR=downloads
MAX_FILE_SIZE=524288000  # 500MB

# 日志配置
LOG_LEVEL=INFO
```

### Cookie配置

在 `cookie.txt` 文件中配置网易云音乐Cookie：

```
MUSIC_U=你的MUSIC_U值;os=pc;appver=8.9.70;
```

> ⚠️ **重要提示**：
> - 必须使用黑胶会员账号的Cookie
> - Cookie格式必须严格按照示例填写
> - 定期更新Cookie以保持有效性

## 🔧 故障排除

### 常见问题

#### 1. Cookie无效
**问题**：提示Cookie无效或过期

**解决方案**：
- 确认使用的是黑胶会员账号
- 重新获取Cookie并更新 `cookie.txt`
- 检查Cookie格式是否正确

#### 2. 无法下载高音质
**问题**：只能下载标准音质

**解决方案**：
- 确认账号是黑胶会员
- 检查Cookie是否有效
- 确认歌曲本身支持高音质

#### 3. 服务启动失败
**问题**：运行 `python main.py` 报错

**解决方案**：
- 检查Python版本（需要3.7+）
- 安装所有依赖：`pip install -r requirements.txt`
- 检查端口5000是否被占用

#### 4. 下载文件损坏
**问题**：下载的音频文件无法播放

**解决方案**：
- 检查网络连接是否稳定
- 重新下载文件
- 尝试其他音质选项

### 日志查看

服务运行时会生成日志文件 `music_api.log`，可以查看详细的错误信息：

```bash
tail -f music_api.log
```

## 📝 开发说明

### 项目结构

```
Netease_url/
├── main.py              # 主程序入口
├── music_api.py         # 音乐API核心模块
├── music_downloader.py  # 音乐下载模块
├── cookie_manager.py    # Cookie管理模块
├── qr_login.py         # 二维码登录模块
├── templates/
│   └── index.html      # Web界面模板
├── downloads/          # 下载文件目录
├── requirements.txt    # Python依赖
├── Dockerfile         # Docker构建文件
├── docker-compose.yml # Docker Compose配置
└── README.md          # 项目说明
```

### 技术栈

- **后端**：Flask + Python
- **前端**：Bootstrap + jQuery
- **音频处理**：mutagen
- **HTTP客户端**：aiohttp + requests
- **容器化**：Docker

## 📄 许可证

本项目采用 MIT 许可证开源，但**禁止用于任何商业或付费项目**。

## 🤝 贡献指南

欢迎提交Issue和Pull Request！

1. Fork本项目
2. 创建特性分支：`git checkout -b feature/new-feature`
3. 提交更改：`git commit -am 'Add new feature'`
4. 推送分支：`git push origin feature/new-feature`
5. 提交Pull Request

## 📞 联系方式

- **GitHub Issues**：[提交问题](https://github.com/Suxiaoqinx/Netease_url/issues)
- **作者博客**：[https://www.toubiec.cn](https://www.toubiec.cn)

---

**⭐ 如果这个项目对你有帮助，请给个Star支持一下！**