6.6 KiB
6.6 KiB
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
常用命令
# 安装依赖
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 指纹哈希 | 自动生成随机值 |
开发规范
添加新接口
- 在
module/目录下创建新的.js文件 - 文件名即为路由路径（
_替换为/），如user_detail.js→/user/detail - 模块导出一个函数：
(params, useAxios) => Promiseparams: 合并后的请求参数（含 cookie、query、body）useAxios: 请求工厂函数，调用createRequest发送请求
// 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