完成网络音乐、工具页面与安装器体验升级
This commit is contained in:
+184
@@ -0,0 +1,184 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user