657 lines
25 KiB
JavaScript
657 lines
25 KiB
JavaScript
/**
|
||
* @fileoverview KuGouMusic API 服务器核心模块
|
||
*
|
||
* 基于 Express 框架构建的 HTTP 服务，负责：
|
||
* - 动态扫描并加载 `module/` 目录下的所有 API 模块，自动注册路由
|
||
* - 处理 CORS 跨域请求
|
||
* - 解析请求 Cookie 并注入平台标识信息
|
||
* - 提供 2 分钟的响应缓存机制
|
||
* - 统一错误处理与响应返回
|
||
*
|
||
* @module server
|
||
* @requires node:fs
|
||
* @requires node:path
|
||
* @requires express
|
||
* @requires safe-decode-uri-component
|
||
* @requires dotenv
|
||
* @requires ./util/util
|
||
* @requires ./util/crypto
|
||
* @requires ./util/request
|
||
* @requires ./util/apicache
|
||
*/
|
||
|
||
const fs = require('node:fs');
|
||
const path = require('node:path');
|
||
const express = require('express');
|
||
const decode = require('safe-decode-uri-component');
|
||
const { cookieToJson, randomString, getGuid, calculateMid, generateWebGLHash, isUUIDv4 } = require('./util/util');
|
||
const { cryptoMd5 } = require('./util/crypto');
|
||
const { createRequest } = require('./util/request');
|
||
const dotenv = require('dotenv');
|
||
const apiCache = require('./util/apicache');
|
||
apiCache.options({ headerBlacklist: ['set-cookie'] });
|
||
const cache = apiCache.middleware;
|
||
const axios = require('axios');
|
||
const crypto = require('node:crypto');
|
||
|
||
const YMHUT_PROTOCOL_VERSION = 1;
|
||
const YMHUT_MOEKOE_COMMIT = '4581660209c9cdd07669e8bd5bcbe136b7d91e02';
|
||
const PUBLIC_CACHE_ROUTES = new Set([
|
||
'/search',
|
||
'/search/default',
|
||
'/search/hot',
|
||
'/search/lyric',
|
||
'/search/suggest',
|
||
'/rank/list',
|
||
'/rank/top',
|
||
'/top/album',
|
||
'/top/playlist',
|
||
'/top/song',
|
||
'/sheet/detail',
|
||
'/sheet/explore',
|
||
'/sheet/rank',
|
||
'/sheet/song',
|
||
'/sheet/tags',
|
||
'/album',
|
||
'/album/detail',
|
||
'/album/songs',
|
||
'/artist/albums',
|
||
'/artist/audios',
|
||
'/artist/detail',
|
||
'/artist/lists',
|
||
'/artist/videos',
|
||
'/audio',
|
||
'/images',
|
||
'/images/audio',
|
||
'/lyric',
|
||
'/video/detail',
|
||
]);
|
||
|
||
function constantTimeTokenEquals(actual, expected) {
|
||
const actualBytes = Buffer.from(typeof actual === 'string' ? actual : '', 'utf8');
|
||
const expectedBytes = Buffer.from(typeof expected === 'string' ? expected : '', 'utf8');
|
||
return actualBytes.length === expectedBytes.length && crypto.timingSafeEqual(actualBytes, expectedBytes);
|
||
}
|
||
|
||
function isAllowedKugouTarget(rawUrl) {
|
||
try {
|
||
const target = new URL(rawUrl);
|
||
const host = target.hostname.toLowerCase();
|
||
return target.protocol === 'https:' &&
|
||
!target.username &&
|
||
!target.password &&
|
||
(!target.port || target.port === '443') &&
|
||
(host === 'kugou.com' || host.endsWith('.kugou.com'));
|
||
} catch {
|
||
return false;
|
||
}
|
||
}
|
||
|
||
function filterProxyHeaders(headers) {
|
||
const blocked = new Set(['host', 'content-length', 'connection', 'x-ymhut-internal-token']);
|
||
const result = {};
|
||
for (const [name, value] of Object.entries(headers || {})) {
|
||
const normalized = String(name).toLowerCase();
|
||
if (!blocked.has(normalized) && typeof value === 'string' && value.length <= 8192) {
|
||
result[normalized] = value;
|
||
}
|
||
}
|
||
return result;
|
||
}
|
||
|
||
function isAnonymousPublicRequest(req) {
|
||
if (req.headers.authorization || req.query.cookie) return false;
|
||
const rawCookie = String(req.headers.cookie || '');
|
||
return !/(?:^|;\s*)(?:token|userid|vip_token|t1|MUSIC_U|MUSIC_A)=/i.test(rawCookie);
|
||
}
|
||
|
||
function originalRequestPath(req) {
|
||
try {
|
||
return new URL(req.originalUrl || req.url, 'http://127.0.0.1').pathname;
|
||
} catch {
|
||
return '';
|
||
}
|
||
}
|
||
|
||
/**
|
||
* @typedef {Object} ModuleDefinition
|
||
* @description API 模块的定义结构，由 {@link getModulesDefinitions} 生成
|
||
* @property {string} [identifier] - 模块标识符，取自文件名（去除 .js 后缀）
|
||
* @property {string} route - 该模块对应的 Express 路由路径
|
||
* @property {any} module - 模块导出的内容（require 加载时为模块对象，否则为文件路径）
|
||
*/
|
||
|
||
/**
|
||
* @typedef {Object} ExpressExtension
|
||
* @description 对 Express 实例的扩展，附加了 HTTP Server 引用
|
||
* @property {import('http').Server} [server] - 底层 HTTP 服务实例
|
||
*/
|
||
|
||
/**
|
||
* 全局唯一设备标识符（GUID）
|
||
* 对随机生成的 GUID 字符串进行 MD5 哈希，作为默认的设备标识
|
||
* @type {string}
|
||
* @constant
|
||
*/
|
||
const guid = cryptoMd5(getGuid());
|
||
|
||
/**
|
||
* 随机生成的 10 位大写字符串，用作默认的开发设备标识（DEV ID）
|
||
* @type {string}
|
||
* @constant
|
||
*/
|
||
const serverDev = randomString(10).toUpperCase();
|
||
|
||
/**
|
||
* .env 环境变量配置文件路径
|
||
* 优先从项目根目录加载，如果文件存在则通过 dotenv 读取其中的环境变量
|
||
* @type {string}
|
||
*/
|
||
const envPath = path.join(process.cwd(), '.env');
|
||
|
||
if (fs.existsSync(envPath)) {
|
||
// 静默加载 .env 文件中的环境变量到 process.env，quiet 抑制加载日志
|
||
dotenv.config({ path: envPath, quiet: true });
|
||
}
|
||
|
||
/**
|
||
* 动态扫描指定目录，获取所有 API 模块的定义信息
|
||
*
|
||
* 扫描流程：
|
||
* 1. 读取 `modulesPath` 目录下的所有文件
|
||
* 2. 过滤出以 `.js` 结尾且不以 `_` 开头的文件（`_` 前缀的文件视为内部模块，跳过注册）
|
||
* 3. 对文件列表进行倒序排列（与 app.js 中的模块加载顺序保持一致）
|
||
* 4. 根据文件名生成路由路径：默认将文件名中的 `_` 替换为 `/`，如有 `specificRoute` 自定义映射则优先使用
|
||
* 5. 如果 `doRequire` 为 true，则通过 require 加载模块；否则仅返回文件路径
|
||
*
|
||
* @async
|
||
* @param {string} modulesPath - 模块目录的绝对路径（例如 `path.join(__dirname, 'module')`）
|
||
* @param {Record<string, string>} specificRoute - 特定文件名到路由路径的自定义映射表
|
||
* - key 为文件名（如 `"album_new.js"`），value 为自定义路由（如 `"/album/create"`）
|
||
* - 未在映射表中的文件将使用默认的路由生成规则
|
||
* @param {boolean} [doRequire=true] - 是否通过 require 加载模块
|
||
* - `true`：直接 require 模块文件，返回模块导出对象
|
||
* - `false`：仅返回模块文件的绝对路径字符串
|
||
* @returns {Promise<ModuleDefinition[]>} 模块定义数组，每个元素包含 identifier、route、module
|
||
*
|
||
* @example
|
||
* // 扫描 module 目录并加载所有模块
|
||
* const defs = await getModulesDefinitions(path.join(__dirname, 'module'), {});
|
||
*
|
||
* @example
|
||
* // 自定义部分模块的路由
|
||
* const defs = await getModulesDefinitions(
|
||
* path.join(__dirname, 'module'),
|
||
* { "album_new.js": "/album/create" }
|
||
* );
|
||
*/
|
||
async function getModulesDefinitions(modulesPath, specificRoute, doRequire = true) {
|
||
const files = await fs.promises.readdir(modulesPath);
|
||
|
||
/**
|
||
* 根据文件名解析出路由路径
|
||
* 优先使用 specificRoute 中的自定义映射，否则按默认规则生成：
|
||
* - 去掉 .js 后缀
|
||
* - 将下划线 _ 替换为斜杠 /
|
||
* - 加上 / 前缀
|
||
* 例如：`user_detail.js` → `/user/detail`
|
||
* @param {string} fileName - 文件名
|
||
* @returns {string} 路由路径
|
||
*/
|
||
const parseRoute = (fileName) =>
|
||
specificRoute && fileName in specificRoute ? specificRoute[fileName] : `/${fileName.replace(/\.(js)$/i, '').replace(/_/g, '/')}`;
|
||
|
||
return (
|
||
files
|
||
// 倒序排列，确保模块加载顺序与 app.js 中 readdirSync().reverse() 保持一致
|
||
.reverse()
|
||
// 仅保留 .js 结尾且不以 _ 开头的文件（跳过内部/私有模块）
|
||
.filter((fileName) => fileName.endsWith('.js') && !fileName.startsWith('_'))
|
||
.map((fileName) => {
|
||
// 模块标识符：取文件名的主体部分（去掉 .js 后缀）
|
||
const identifier = fileName.split('.').shift();
|
||
// 生成路由路径
|
||
const route = parseRoute(fileName);
|
||
// 模块文件的完整绝对路径
|
||
const modulePath = path.resolve(modulesPath, fileName);
|
||
// 根据 doRequire 决定是加载模块还是仅返回路径
|
||
const module = doRequire ? require(modulePath) : modulePath;
|
||
return { identifier, route, module };
|
||
})
|
||
);
|
||
}
|
||
|
||
/**
|
||
* 构建并配置 Express 应用实例
|
||
*
|
||
* 该函数完成以下工作：
|
||
* 1. 创建 Express 应用
|
||
* 2. 配置 CORS 跨域中间件（处理 OPTIONS 预检请求）
|
||
* 3. 配置自定义 Cookie 解析中间件
|
||
* 4. 注入平台标识 Cookie（PLATFORM、MID、GUID、DEV、MAC）
|
||
* 5. 配置 JSON / URL-encoded 请求体解析
|
||
* 6. 挂载静态文件服务（public 目录和 docs 目录）
|
||
* 7. 配置 2 分钟的 API 响应缓存
|
||
* 8. 遍历所有模块定义，动态注册 Express 路由处理器
|
||
* - 每个路由处理器负责：合并请求参数、调用模块函数、处理 Cookie、返回响应
|
||
*
|
||
* @async
|
||
* @param {ModuleDefinition[]} [moduleDefs] - 可选的模块定义数组
|
||
* - 如果未提供，则自动调用 {@link getModulesDefinitions} 从 `module/` 目录扫描加载
|
||
* @returns {Promise<import('express').Express>} 配置完成的 Express 应用实例
|
||
*/
|
||
async function consturctServer(moduleDefs) {
|
||
const app = express();
|
||
|
||
const internalToken = process.env.YMHUT_INTERNAL_TOKEN;
|
||
if (internalToken) {
|
||
app.use((req, res, next) => {
|
||
if (!constantTimeTokenEquals(req.get('x-ymhut-internal-token'), internalToken)) {
|
||
res.status(401).json({ code: 401, message: 'Unauthorized' });
|
||
return;
|
||
}
|
||
next();
|
||
});
|
||
}
|
||
|
||
// 从环境变量读取允许的跨域来源，若未配置则回退到请求头中的 origin 或 '*'
|
||
const { CORS_ALLOW_ORIGIN } = process.env;
|
||
|
||
// 启用反向代理信任，确保 req.ip 能正确获取客户端真实 IP（如经过 Nginx 反代）
|
||
app.set('trust proxy', true);
|
||
|
||
/**
|
||
* ============================================================
|
||
* CORS 跨域资源共享中间件
|
||
* ============================================================
|
||
*
|
||
* 对非根路径且非静态文件的请求设置 CORS 响应头：
|
||
* - Access-Control-Allow-Credentials: 允许携带凭证（Cookie）
|
||
* - Access-Control-Allow-Origin: 允许的来源域名
|
||
* - Access-Control-Allow-Headers: 允许的请求头
|
||
* - Access-Control-Allow-Methods: 允许的 HTTP 方法
|
||
* - Content-Type: 统一使用 UTF-8 编码的 JSON
|
||
*
|
||
* 对 OPTIONS 预检请求直接返回 204 No Content
|
||
*/
|
||
app.use((req, res, next) => {
|
||
if (req.path !== '/' && !req.path.includes('.')) {
|
||
res.set({
|
||
'Access-Control-Allow-Credentials': true,
|
||
'Access-Control-Allow-Origin': CORS_ALLOW_ORIGIN || req.headers.origin || '*',
|
||
'Access-Control-Allow-Headers': 'Authorization,X-Requested-With,Content-Type,Cache-Control',
|
||
'Access-Control-Allow-Methods': 'PUT,POST,GET,DELETE,OPTIONS',
|
||
'Content-Type': 'application/json; charset=utf-8',
|
||
});
|
||
}
|
||
// OPTIONS 预检请求无需继续处理，直接返回 204
|
||
req.method === 'OPTIONS' ? res.status(204).end() : next();
|
||
});
|
||
|
||
/**
|
||
* ============================================================
|
||
* Cookie 解析中间件
|
||
* ============================================================
|
||
*
|
||
* 手动解析请求头中的 Cookie 字符串，将其转换为键值对对象并挂载到 req.cookies。
|
||
*
|
||
* 解析规则：
|
||
* - 按 `; ` 或末尾空格分隔多个 cookie 键值对
|
||
* - 每个键值对按第一个 `=` 分割为 key 和 value
|
||
* - key 和 value 均通过 safe-decode-uri-component 解码
|
||
* - 跳过无效的键值对（无 `=` 或 `=` 在末尾）
|
||
*/
|
||
app.use((req, _, next) => {
|
||
req.cookies = {};
|
||
(req.headers.cookie || '').split(/;\s+|(?<!\s)\s+$/g).forEach((pair) => {
|
||
const crack = pair.indexOf('=');
|
||
// 跳过无效的 cookie：没有 = 号，或 = 号在最后（无 value）
|
||
if (crack < 1 || crack === pair.length - 1) {
|
||
return;
|
||
}
|
||
req.cookies[decode(pair.slice(0, crack)).trim()] = decode(pair.slice(crack + 1)).trim();
|
||
});
|
||
next();
|
||
});
|
||
|
||
/**
|
||
* ============================================================
|
||
* 平台标识 Cookie 注入中间件
|
||
* ============================================================
|
||
*
|
||
* 自动向请求的 Cookie 对象中注入以下平台标识信息（仅在客户端未提供时补充）：
|
||
* - KUGOU_API_PLATFORM: 平台类型（标准版/概念版 lite），来自环境变量 platform
|
||
* - KUGOU_API_MID: 设备 MID，由 GUID 通过 calculateMid 算法生成
|
||
* - KUGOU_API_GUID: 设备全局唯一标识符，优先使用环境变量 KUGOU_API_GUID，否则使用启动时生成的默认值
|
||
* - KUGOU_API_DEV: 开发设备标识符，优先使用环境变量 KUGOU_API_DEV
|
||
* - KUGOU_API_MAC: 设备 MAC 地址，默认为 '02:00:00:00:00:00'
|
||
*
|
||
* 同时通过 Set-Cookie 将这些值写回客户端，方便调试和后续请求自动携带。
|
||
* 根据请求协议（HTTP/HTTPS）决定 Cookie 的安全属性（SameSite=None; Secure）。
|
||
*/
|
||
app.use((req, res, next) => {
|
||
const cookies = req.cookies || {};
|
||
const isHttps = req.protocol === 'https';
|
||
// HTTPS 下设置 SameSite=None; Secure 以支持跨站 Cookie 传递
|
||
const cookieSuffix = isHttps ? '; PATH=/; SameSite=None; Secure' : '; PATH=/';
|
||
|
||
/**
|
||
* 确保指定的 cookie key 存在，如果不存在则自动写入
|
||
* @param {string} key - Cookie 键名
|
||
* @param {string} value - Cookie 默认值
|
||
*/
|
||
const ensureCookie = (key, value) => {
|
||
// 如果客户端已经提供了该 cookie，则跳过不覆盖
|
||
if (Object.prototype.hasOwnProperty.call(cookies, key)) return;
|
||
cookies[key] = String(value);
|
||
res.append('Set-Cookie', `${key}=${cookies[key]}${cookieSuffix}`);
|
||
};
|
||
|
||
// 获取 env guid
|
||
const env_guid = isUUIDv4(process.env.KUGOU_API_GUID) ? cryptoMd5(process.env.KUGOU_API_GUID) : process.env.KUGOU_API_GUID;
|
||
|
||
// 计算设备 MID（基于 GUID 的衍生标识）
|
||
const mid = calculateMid(env_guid ?? guid);
|
||
|
||
// 依次注入各平台标识 Cookie
|
||
ensureCookie('KUGOU_API_PLATFORM', process.env.platform);
|
||
ensureCookie('KUGOU_API_MID', mid);
|
||
ensureCookie('KUGOU_API_GUID', env_guid ?? guid);
|
||
ensureCookie('KUGOU_API_DEV', (process.env.KUGOU_API_DEV ?? serverDev).toUpperCase());
|
||
ensureCookie('KUGOU_API_MAC', (process.env.KUGOU_API_MAC ?? '02:00:00:00:00:00').toUpperCase());
|
||
ensureCookie('KUGOU_API_WEBGL', process.env.KUGOU_API_WEBGL ?? generateWebGLHash());
|
||
|
||
// 将注入后的 cookies 回写到 req 对象上，供后续中间件和路由处理器使用
|
||
req.cookies = cookies;
|
||
|
||
next();
|
||
});
|
||
|
||
/**
|
||
* ============================================================
|
||
* 请求体解析中间件
|
||
* ============================================================
|
||
*
|
||
* - express.json(): 解析 Content-Type 为 application/json 的请求体
|
||
* - express.urlencoded(): 解析 Content-Type 为 application/x-www-form-urlencoded 的请求体
|
||
* - extended: false 使用 querystring 库解析（不支持嵌套对象）
|
||
*/
|
||
app.use(express.json({ limit: '5mb' }));
|
||
app.use(express.urlencoded({ extended: false, limit: '5mb' }));
|
||
app.use(express.raw({ type: 'application/octet-stream', limit: '100mb' }));
|
||
|
||
app.get('/ymhut/health', (_, res) => {
|
||
res.json({
|
||
protocolVersion: YMHUT_PROTOCOL_VERSION,
|
||
commit: YMHUT_MOEKOE_COMMIT,
|
||
pid: process.pid,
|
||
status: 'ready',
|
||
});
|
||
});
|
||
|
||
app.post('/ymhut/shutdown', (req, res) => {
|
||
res.json({ ok: true });
|
||
setImmediate(() => app.emit('ymhut-shutdown'));
|
||
});
|
||
|
||
// Compatibility bridge for the existing signed provider adapter. It keeps every
|
||
// production KuGou network hop inside this authenticated loopback process.
|
||
app.post('/ymhut/proxy', async (req, res) => {
|
||
const timestamp = String(req.query.timestamp || '');
|
||
if (!/^\d+$/.test(timestamp)) {
|
||
res.status(400).json({ code: 400, message: 'A numeric timestamp is required.' });
|
||
return;
|
||
}
|
||
|
||
const payload = req.body || {};
|
||
if (!isAllowedKugouTarget(payload.url)) {
|
||
res.status(400).json({ code: 400, message: 'Target is not allowed.' });
|
||
return;
|
||
}
|
||
|
||
const method = String(payload.method || 'GET').toUpperCase();
|
||
if (!['GET', 'HEAD', 'POST', 'PUT', 'DELETE'].includes(method)) {
|
||
res.status(405).json({ code: 405, message: 'Method is not allowed.' });
|
||
return;
|
||
}
|
||
|
||
try {
|
||
const response = await axios.request({
|
||
method,
|
||
url: payload.url,
|
||
headers: filterProxyHeaders(payload.headers),
|
||
data: payload.bodyBase64 ? Buffer.from(payload.bodyBase64, 'base64') : undefined,
|
||
responseType: 'arraybuffer',
|
||
timeout: 15000,
|
||
maxRedirects: 0,
|
||
validateStatus: () => true,
|
||
});
|
||
const responseHeaders = {};
|
||
for (const [name, value] of Object.entries(response.headers || {})) {
|
||
if (value !== undefined && !['connection', 'content-length', 'transfer-encoding'].includes(name.toLowerCase())) {
|
||
responseHeaders[name] = Array.isArray(value) ? value : String(value);
|
||
}
|
||
}
|
||
res.json({
|
||
status: response.status,
|
||
headers: responseHeaders,
|
||
bodyBase64: Buffer.from(response.data || []).toString('base64'),
|
||
});
|
||
} catch (error) {
|
||
const code = error && error.code === 'ECONNABORTED' ? 504 : 502;
|
||
res.status(code).json({ code, message: code === 504 ? 'Upstream timeout.' : 'Upstream unavailable.' });
|
||
}
|
||
});
|
||
|
||
/**
|
||
* ============================================================
|
||
* 静态文件服务
|
||
* ============================================================
|
||
*
|
||
* 将项目根目录下的 `public/` 目录作为静态资源目录，
|
||
* 可用于提供前端页面、图标等静态文件
|
||
*/
|
||
app.use(express.static(path.join(__dirname, 'public')));
|
||
|
||
/**
|
||
* API 文档静态服务
|
||
*
|
||
* 将 `docs/` 目录挂载到 `/docs` 路径下，
|
||
* 访问 /docs 可查看项目接口文档
|
||
*/
|
||
app.use('/docs', express.static(path.join(__dirname, 'docs')));
|
||
|
||
/**
|
||
* ============================================================
|
||
* API 响应缓存中间件
|
||
* ============================================================
|
||
*
|
||
* 使用 apicache 对成功的请求（statusCode === 200）进行 2 分钟的缓存。
|
||
* 相同 URL 在 2 分钟内只会向酷狗服务器发送一次请求。
|
||
*
|
||
* 绕过缓存的方式：在请求 URL 后附加不同的 timestamp 参数，
|
||
* 例如: /personal/fm?timestamp=1691256061923
|
||
*/
|
||
app.use(cache(
|
||
'2 minutes',
|
||
(req, res) => req.method === 'GET' &&
|
||
isAnonymousPublicRequest(req) &&
|
||
PUBLIC_CACHE_ROUTES.has(originalRequestPath(req)) &&
|
||
res.statusCode === 200,
|
||
{
|
||
appendKey: (req) => `${req.method}:${req.get('host') || 'loopback'}`,
|
||
}
|
||
));
|
||
|
||
/**
|
||
* ============================================================
|
||
* 动态路由注册
|
||
* ============================================================
|
||
*
|
||
* 如果未传入模块定义数组，则自动扫描 module/ 目录加载所有模块。
|
||
* 遍历每个模块定义，为其注册 Express 路由处理器。
|
||
*/
|
||
const moduleDefinitions = moduleDefs || (await getModulesDefinitions(path.join(__dirname, 'module'), {}));
|
||
|
||
for (const moduleDef of moduleDefinitions) {
|
||
/**
|
||
* 为每个 API 模块注册路由处理器
|
||
*
|
||
* 请求处理流程：
|
||
* 1. 解析并合并 Cookie（支持 query 和 body 中的 cookie 字符串）
|
||
* 2. 合并所有请求参数：query 参数、body 参数、Cookie
|
||
* 3. 提取 Authorization 请求头中的认证信息，合并到 cookie 中
|
||
* 4. 调用模块处理函数，传入合并后的参数和请求工厂函数
|
||
* 5. 处理模块返回的 Cookie（通过 Set-Cookie 写回客户端）
|
||
* 6. 返回模块的响应数据
|
||
* 7. 异常时记录日志并返回错误响应
|
||
*/
|
||
app.use(moduleDef.route, async (req, res) => {
|
||
// Step 1: 解析 query 和 body 中的 cookie 字符串为 JSON 对象
|
||
[req.query, req.body].forEach((item) => {
|
||
if (typeof item.cookie === 'string') {
|
||
item.cookie = cookieToJson(decode(item.cookie));
|
||
}
|
||
});
|
||
|
||
// Step 2: 从 query 中分离出 cookie 参数和其余参数
|
||
const { cookie, ...params } = req.query;
|
||
|
||
// Step 3: 构建统一的 query 对象
|
||
// - cookie: 合并请求 Cookie 和 query 中传入的 cookie 参数
|
||
// - params: query 中除 cookie 外的其余参数
|
||
// - body: 请求体（POST 数据）
|
||
const body = Buffer.isBuffer(req.body) ? { data: req.body } : req.body;
|
||
const query = Object.assign({}, { cookie: Object.assign({}, req.cookies, cookie) }, params, body);
|
||
|
||
// Step 4: 如果请求携带了 Authorization 头，将其解析为 Cookie 并合并
|
||
// 这样客户端可以通过 Authorization 头传递认证信息，例如: token=xxx;userid=xxx
|
||
const authHeader = req.headers['authorization'];
|
||
if (authHeader) {
|
||
query.cookie = {
|
||
...query.cookie,
|
||
...cookieToJson(authHeader),
|
||
};
|
||
}
|
||
|
||
try {
|
||
/**
|
||
* Step 5: 调用模块处理函数
|
||
*
|
||
* 传入两个参数：
|
||
* - query: 合并后的所有请求参数
|
||
* - 请求工厂函数: 接收请求配置，注入客户端 IP 后调用 createRequest 发起实际请求
|
||
*
|
||
* @see createRequest - 底层 HTTP 请求函数
|
||
*/
|
||
const moduleResponse = await moduleDef.module(query, (config) => {
|
||
// 获取客户端真实 IP（去除 IPv6-mapped IPv4 前缀）
|
||
let ip = req.ip;
|
||
if (ip.substring(0, 7) === '::ffff:') {
|
||
ip = ip.substring(7);
|
||
}
|
||
config.ip = ip;
|
||
return createRequest(config);
|
||
});
|
||
|
||
// 请求成功日志
|
||
if (process.env.YMHUT_QUIET !== '1') console.log('[OK]', req.path);
|
||
|
||
// Step 6: 处理模块返回的 Cookie
|
||
// 将模块设置的 Cookie 通过 Set-Cookie 响应头写回客户端
|
||
const cookies = moduleResponse.cookie;
|
||
if (!query.noCookie) {
|
||
if (Array.isArray(cookies) && cookies.length > 0) {
|
||
if (req.protocol === 'https') {
|
||
// HTTPS 协议下设置 SameSite=None; Secure 以解决 CORS 环境下的 Cookie 传递问题
|
||
res.append(
|
||
'Set-Cookie',
|
||
cookies.map((cookie) => {
|
||
return `${cookie}; PATH=/; SameSite=None; Secure`;
|
||
})
|
||
);
|
||
} else {
|
||
// HTTP 协议下仅设置 PATH
|
||
res.append(
|
||
'Set-Cookie',
|
||
cookies.map((cookie) => {
|
||
return `${cookie}; PATH=/`;
|
||
})
|
||
);
|
||
}
|
||
}
|
||
}
|
||
|
||
// Step 7: 返回模块的响应（包含 headers、status、body）
|
||
res.header(moduleResponse.headers).status(moduleResponse.status).send(moduleResponse.body);
|
||
} catch (e) {
|
||
// 异常处理：模块内部错误会被封装为包含 status 和 body 的错误对象抛出
|
||
const moduleResponse = e;
|
||
|
||
// 错误日志
|
||
if (process.env.YMHUT_QUIET !== '1') console.log('[ERR]', req.path, moduleResponse.status);
|
||
|
||
// 如果错误对象没有 body，返回通用 404 响应
|
||
if (!moduleResponse.body) {
|
||
res.status(404).send({
|
||
code: 404,
|
||
data: null,
|
||
msg: 'Not Found',
|
||
});
|
||
return;
|
||
}
|
||
|
||
// 返回模块错误的响应体
|
||
res.header(moduleResponse.headers).status(moduleResponse.status).send(moduleResponse.body);
|
||
}
|
||
});
|
||
}
|
||
|
||
return app;
|
||
}
|
||
|
||
/**
|
||
* 启动 KuGouMusic API 服务
|
||
*
|
||
* 完整启动流程：
|
||
* 1. 从环境变量读取端口号（默认 3000）和主机地址（默认空字符串，即监听所有可用地址）
|
||
* 2. 调用 {@link consturctServer} 构建并配置 Express 应用
|
||
* 3. 在指定端口和主机上启动 HTTP 监听
|
||
* 4. 输出启动成功日志
|
||
* 5. 返回扩展后的 Express 实例（附带底层 server 引用）
|
||
*
|
||
* @async
|
||
* @returns {Promise<import('express').Express & ExpressExtension>} 扩展后的 Express 应用实例，
|
||
* 包含 `service` 属性指向底层 HTTP Server
|
||
*
|
||
* @example
|
||
* // 基本用法
|
||
* const app = await startService();
|
||
* // 服务已启动，可通过 app.service 访问底层 HTTP Server
|
||
*
|
||
* @example
|
||
* // 通过环境变量自定义端口和主机
|
||
* // PORT=4000 HOST=127.0.0.1 node index.js
|
||
*/
|
||
async function startService() {
|
||
// 读取端口号配置，默认为 3000
|
||
const port = Number(process.env.PORT || '3000');
|
||
// 读取主机地址配置，默认为空（监听所有网络接口）
|
||
const host = process.env.HOST || '';
|
||
|
||
// 构建 Express 应用（包含所有中间件和路由）
|
||
const app = await consturctServer();
|
||
|
||
/** @type {import('express').Express & ExpressExtension} */
|
||
const appExt = app;
|
||
|
||
// 启动 HTTP 服务并监听指定端口和主机
|
||
appExt.service = app.listen(port, host, () => {
|
||
console.log(`server running @ http://${host || 'localhost'}:${port}`);
|
||
});
|
||
|
||
return appExt;
|
||
}
|
||
|
||
module.exports = { startService, getModulesDefinitions, consturctServer };
|