185 lines
6.6 KiB
Markdown
185 lines
6.6 KiB
Markdown
# CLAUDE.md
|
||
|
||
> KuGouMusicApi 项目指南 — 酷狗音乐 NodeJS 版 API
|
||
|
||
## 项目概述
|
||
|
||
本项目是酷狗音乐的非官方 NodeJS API 服务，通过伪造请求头和调用官方 API 实现酷狗音乐的全部功能。支持两种运行模式：HTTP 服务模式（Express）和编程式调用模式（作为库引入）。
|
||
|
||
- **作者**: Lines（基于 MakcRe 的项目）
|
||
- **版本**: 1.5.1
|
||
- **Node 要求**: >= 12
|
||
- **License**: MIT
|
||
|
||
## 技术栈
|
||
|
||
- **运行时**: Node.js
|
||
- **HTTP 框架**: Express 4.x
|
||
- **HTTP 客户端**: Axios
|
||
- **加密库**: crypto-js（AES/MD5）、node-forge（RSA）
|
||
- **压缩库**: pako（zlib 解压，用于 KRC 歌词解码）
|
||
- **大整数库**: big-integer（用于 MID 计算）
|
||
- **开发工具**: nodemon、prettier、esbuild、pkg
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
KuGouMusicApi/
|
||
├── app.js # CLI 入口（shebang），调用 server.startService()
|
||
├── index.js # 开发入口，require('./app')
|
||
├── main.js # 编程式 API 入口（作为库使用时）
|
||
├── server.js # Express 服务器核心（CORS、Cookie、路由注册）
|
||
├── module/ # API 模块目录（约 160 个接口）
|
||
│ ├── search.js # 搜索
|
||
│ ├── login.js # 登录
|
||
│ ├── login_cellphone.js # 手机登录
|
||
│ ├── song_url.js # 歌曲 URL
|
||
│ ├── playlist_detail.js # 歌单详情
|
||
│ └── ... # 其他接口
|
||
├── util/ # 工具库
|
||
│ ├── index.js # 统一导出入口
|
||
│ ├── config.json # 平台配置（appid、clientver 等）
|
||
│ ├── crypto.js # 加密函数（AES、RSA、MD5、SHA1）
|
||
│ ├── helper.js # 签名函数（signature、sign、signKey）
|
||
│ ├── request.js # HTTP 请求封装（签名、代理、响应处理）
|
||
│ ├── util.js # 通用工具（随机数、Cookie、歌词解码、MID、WebGL 指纹）
|
||
│ ├── runtime.js # 运行时配置（CLI 参数、代理解析）
|
||
│ ├── generate_simulate.js # 行为指纹模拟生成（AES+RSA 加密）
|
||
│ ├── apicache.js # API 响应缓存中间件
|
||
│ └── memory-cache.js # 内存缓存实现
|
||
├── public/ # 前端页面
|
||
│ ├── index.html # 接口文档首页
|
||
│ ├── login_captcha.html # 登录页（依赖 WASM）
|
||
│ ├── login_captcha_simulate.html # 登录页（纯 JS 模拟，不依赖 WASM）
|
||
│ ├── sid_edt_generator.html # SID/EDT 生成工具页
|
||
│ └── verify-pkg/ # WASM 验证码包
|
||
├── docs/ # 接口文档
|
||
├── .env.example # 环境变量配置示例
|
||
├── Dockerfile # Docker 部署配置
|
||
├── vercel.json # Vercel 部署配置
|
||
└── package.json
|
||
```
|
||
|
||
## 核心架构
|
||
|
||
### 请求流程
|
||
|
||
```
|
||
客户端请求 → Express 中间件（CORS → Cookie 解析 → 平台标识注入 → 缓存）
|
||
→ 路由处理器（参数合并 → Cookie 格式化 → Authorization 头解析）
|
||
→ API 模块函数（构建请求参数 → 生成签名 → 调用 createRequest）
|
||
→ createRequest（注入设备标识 → 签名 → 代理 → 发送请求 → 响应处理）
|
||
→ 酷狗服务器
|
||
```
|
||
|
||
### 签名机制
|
||
|
||
所有 API 请求都需要签名验证，支持三种签名类型：
|
||
- **Android 签名**（默认）: `MD5(盐值 + 排序参数 + 请求体 + 盐值)`
|
||
- **Web 签名**: `MD5(盐值 + 排序参数 + 盐值)`
|
||
- **Register 签名**: `MD5("1014" + 排序值 + "1014")`
|
||
|
||
区分标准版和概念版（lite），使用不同的盐值和 appid。
|
||
|
||
### 行为指纹（SID/EDT）
|
||
|
||
酷狗服务端会检测请求的行为指纹，需要生成模拟数据：
|
||
- **SID**: RSA-OAEP 加密的 AES 密钥（Base64）
|
||
- **EDT**: AES-128-CBC 加密的行为数据（Base64）
|
||
- 行为数据包括：鼠标轨迹（贝塞尔曲线）、滚动事件、窗口事件、WebGL 指纹
|
||
|
||
### 双平台支持
|
||
|
||
通过 `.env` 中的 `platform` 环境变量切换：
|
||
- **标准版**（默认）: `appid=1005`, `clientver=20489`
|
||
- **概念版 lite**: `appid=3116`, `clientver=11440`
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 开发模式（热重载）
|
||
npm run dev
|
||
|
||
# 生产模式
|
||
npm start
|
||
|
||
# 自定义端口
|
||
PORT=4000 npm run dev
|
||
|
||
# 使用代理
|
||
KUGOU_API_PROXY=http://127.0.0.1:7890 npm run dev
|
||
|
||
# CLI 参数方式设置代理
|
||
node app.js --proxy=http://127.0.0.1:7890 --platform=lite
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `platform` | 平台类型：`lite`（概念版）或空（标准版） | 空 |
|
||
| `PORT` | 服务端口 | 3000 |
|
||
| `HOST` | 监听地址 | 空（所有地址） |
|
||
| `KUGOU_API_PROXY` | HTTP 代理地址 | 空 |
|
||
| `KUGOU_API_GUID` | 设备 GUID（建议 UUID v4） | 自动生成 |
|
||
| `KUGOU_API_DEV` | 开发设备标识（10位大写字符串） | 自动生成 |
|
||
| `KUGOU_API_MAC` | 设备 MAC 地址 | 02:00:00:00:00:00 |
|
||
| `KUGOU_API_WEBGL` | WebGL 指纹哈希 | 自动生成随机值 |
|
||
|
||
## 开发规范
|
||
|
||
### 添加新接口
|
||
|
||
1. 在 `module/` 目录下创建新的 `.js` 文件
|
||
2. 文件名即为路由路径（`_` 替换为 `/`），如 `user_detail.js` → `/user/detail`
|
||
3. 模块导出一个函数：`(params, useAxios) => Promise`
|
||
- `params`: 合并后的请求参数（含 cookie、query、body）
|
||
- `useAxios`: 请求工厂函数，调用 `createRequest` 发送请求
|
||
|
||
```javascript
|
||
// module/example.js
|
||
module.exports = (params, useAxios) => {
|
||
return new Promise((resolve, reject) => {
|
||
useAxios({
|
||
baseURL: 'https://gateway.kugou.com',
|
||
url: '/v1/example',
|
||
method: 'GET',
|
||
params: { keyword: params.keyword },
|
||
cookie: params.cookie,
|
||
}).then(resolve).catch(reject);
|
||
});
|
||
};
|
||
```
|
||
|
||
### 签名选择
|
||
|
||
- 大多数接口使用 `android` 签名（默认）
|
||
- Web 相关接口使用 `web` 签名
|
||
- 设备注册接口使用 `register` 签名
|
||
|
||
### Cookie 传递
|
||
|
||
Cookie 通过以下方式传递：
|
||
- URL 查询参数: `?cookie=token%3Dxxx%3Buserid%3Dxxx`
|
||
- 请求体: `{ cookie: "token=xxx;userid=xxx" }`
|
||
- Authorization 头: `Authorization: token=xxx;userid=xxx`
|
||
|
||
服务端会自动将 Cookie 字符串转换为 JSON 对象并合并。
|
||
|
||
## 代码风格
|
||
|
||
- 使用 Prettier 格式化（配置见 `.prettierrc.json`）
|
||
- 2 空格缩进
|
||
- 单引号
|
||
- 无分号（Prettier 默认）
|
||
|
||
## 部署
|
||
|
||
- **Docker**: 使用项目根目录的 `Dockerfile`
|
||
- **Vercel**: 使用 `vercel.json` 配置
|
||
- **pkg 打包**: `npm run pkgwin` / `npm run pkglinux` / `npm run pkgmacos`
|
||
- **esbuild 打包**: `npm run pkgjs`
|