feat(auth): 调用秘钥鉴权——AUTH_KEY 环境变量启用，Bearer/X-Api-Key/?key= 三种携带方式，流地址自动附带 key

README.md

@@ -74,6 +74,20 @@ pnpm typecheck   # 仅类型检查，不运行
 
 `/url` 在外部音源与平台直连都失败时，自动降级到**酷我**兜底：按歌名/歌手/时长匹配同一首歌后走 kw 通道（匿名可拿无损）。kg 可由 hash 反查歌曲信息；其它平台需要兜底时给 `/url` 传 `name`/`singer`/`interval` 查询参数。
 
+## 调用鉴权（AUTH_KEY）
+
+设置环境变量 `AUTH_KEY` 后，全部业务接口要求携带调用秘钥（未设置则不鉴权）：
+
+```
+Authorization: Bearer <AUTH_KEY>   # 亦接受裸值
+X-Api-Key: <AUTH_KEY>
+?key=<AUTH_KEY>                    # 查询参数（播放器直接拉流场景）
+```
+
+豁免路径：`/health`、`/`、`/docs`、`/redoc`、`/openapi.json`。秘钥错误返回 401。
+启用鉴权时 `/url` 返回的代理流地址（如 qs 解密流）会自动附带 `?key=`，播放器可直接拉流。
+
+
 ## 外部音源
 
 设置 `SOURCE_ENABLED=1` 后取流优先走外部音源（默认未设置时直接走 SDK 官方直连接口；是否启用由服务端在 `src/server.ts` 决策）。两种脚本都放 `sources/` 目录（不入库），按文件名混排成候选链：取流失败自动切换下一个，某平台连续失败 3 次的脚本降权冷却 5 分钟；整条音源链失败后回落 SDK 直连、再失败走酷我兜底（见上文取流链）。音源候选链只覆盖 kw/kg/tx/wy（音源脚本协议无 qs 平台，`/url/qs` 始终走 SDK）。音源模式下登录态不参与取流，登录自动续期不会启动（手动 `POST /login/refresh` 仍可用）。详见 [docs/source-ivm.md](docs/source-ivm.md) 与 [docs/source-simple.md](docs/source-simple.md)。

src/http/auth-gate.ts

@@ -0,0 +1,40 @@
+// 全局调用秘钥鉴权 —— AUTH_KEY 环境变量启用（未设置则完全不鉴权）
+// 客户端携带方式（任一即可）：
+//   Authorization: Bearer <AUTH_KEY>（也接受裸值不带 Bearer 前缀）
+//   X-Api-Key: <AUTH_KEY>
+//   ?key=<AUTH_KEY>（查询参数，兼容播放器/下载器直接拉流无法带自定义头的场景）
+// 豁免：/health、文档（/、/docs*、/redoc、/openapi.json）与 CORS 预检
+import crypto from 'node:crypto'
+import type { FastifyRequest, FastifyReply } from 'fastify'
+
+// 无敏感信息且会被监控系统高频探测的路径豁免鉴权
+const PUBLIC_PATHS = [/^\/health$/, /^\/$/, /^\/docs(\/|$)/, /^\/redoc$/, /^\/openapi\.json$/]
+
+const safeEqual = (a: string, b: string) => {
+  const bufA = Buffer.from(a)
+  const bufB = Buffer.from(b)
+  return bufA.length === bufB.length && crypto.timingSafeEqual(bufA, bufB)
+}
+
+export const registerAuth = (fastify: any, authKey: string) => {
+  fastify.addHook('onRequest', async(request: FastifyRequest, reply: FastifyReply) => {
+    if (request.method === 'OPTIONS') return
+    const pathname = new URL(request.url, 'http://localhost').pathname
+    if (PUBLIC_PATHS.some(re => re.test(pathname))) return
+
+    const authorization = String(request.headers.authorization || '')
+    const bearer = authorization.startsWith('Bearer ') ? authorization.slice(7).trim() : authorization.trim()
+    const provided = [
+      bearer,
+      String(request.headers['x-api-key'] || ''),
+      String((request.query as any)?.key || ''),
+    ].find(Boolean)
+
+    if (!provided || !safeEqual(provided, authKey)) {
+      return reply.code(401).send({
+        code: 401,
+        msg: '无效或缺少调用秘钥：请在 Authorization: Bearer <key>、X-Api-Key 头或 ?key= 参数中携带',
+      })
+    }
+  })
+}

src/routes.ts

@@ -136,9 +136,10 @@ export const musicRoutes = async(fastify: any) => {
     // 取流链：外部音源脚本（SOURCE_ENABLED 启用时）→ SDK 官方直连 → 酷我兜底（跨平台匹配）
     const finish = (res: any, via: string) => {
       if (!res?.url) throw new Error('获取播放地址失败')
-      // qs 解密流等代理地址返回相对路径，按请求的协议与 host 补全（兼容本机/局域网播放器）
+      // qs 解密流等代理地址返回相对路径，按请求的协议与 host 补全（兼容本机/局域网播放器）；
+      // 启用 AUTH_KEY 时附带 ?key=（播放器直接拉流无法携带自定义头）
       const url = String(res.url).startsWith('/')
-        ? `${request.protocol}://${request.headers.host}${res.url}`
+        ? `${request.protocol}://${request.headers.host}${res.url}${process.env.AUTH_KEY ? `${String(res.url).includes('?') ? '&' : '?'}key=${encodeURIComponent(process.env.AUTH_KEY)}` : ''}`
         : res.url
       // type 用实际音质（kw 等通道可能降级）；via 标记兜底链中真正命中的通道
       return { type: res.type || quality, url, ...(via !== source ? { via } : {}) }

src/server.ts

@@ -80,6 +80,14 @@ fastify.addHook('onRoute', (routeOptions) => {
 
 fastify.register(cors, { origin: '*' })
 
+// ---- 调用秘钥（AUTH_KEY 环境变量启用；未设置则不鉴权）----
+// 详见 src/http/auth-gate.ts；文档/健康检查豁免，业务接口要求 Bearer / X-Api-Key / ?key=
+const authKey = process.env.AUTH_KEY
+if (authKey) {
+  const { registerAuth } = await import('./http/auth-gate.ts')
+  registerAuth(fastify, authKey)
+}
+
 fastify.addHook('onRequest', async(_request, reply) => {
   reply.header('Cache-Control', 'no-store')
 })
@@ -204,6 +212,7 @@ if (!useSource) {
 export const startServer = async(port = PORT) => {
   await fastify.listen({ port: Number(port), host: '0.0.0.0' })
   console.log(`音乐服务器已启动: http://localhost:${port}`)
+  console.log(`调用鉴权:   ${authKey ? `已启用（AUTH_KEY，Bearer / X-Api-Key / ?key=）` : '未启用（设置 AUTH_KEY 环境变量开启）'}`)
   console.log(`取流通道:   ${useSource ? '外部音源脚本（sources/，SOURCE_ENABLED）' : 'SDK 官方直连接口'}`)
   console.log(`接口文档:   http://localhost:${port}/docs (Swagger UI)`)
   console.log(`ReDoc 文档: http://localhost:${port}/redoc`)

test/smoke-test.ts

@@ -76,12 +76,12 @@ const test = async(name: string, fn: () => Promise<any>) => {
 }
 
 /**
- * 启动本地服务器（指定端口）并返回进程句柄
+ * 启动本地服务器（指定端口，可覆盖环境变量）并返回进程句柄
  */
-const startLocalServer = (port: number) => new Promise((resolve, reject) => {
+const startLocalServer = (port: number, envExtra: Record<string, string> = {}) => new Promise((resolve, reject) => {
   const proc = spawn(process.execPath, ['src/server.ts'], {
     cwd: process.cwd(),
-    env: { ...process.env, PORT: String(port) },
+    env: { ...process.env, PORT: String(port), ...envExtra },
     stdio: ['ignore', 'pipe', 'pipe'],
   })
   let stdout = ''
@@ -94,7 +94,7 @@ const startLocalServer = (port: number) => new Promise((resolve, reject) => {
   }, 10000)
 
   const check = () => {
-    http.get(`${BASE}/health`, res => {
+    http.get(`http://localhost:${port}/health`, res => {
       res.resume()
       if (res.statusCode === 200) {
         clearTimeout(timer)
@@ -608,6 +608,54 @@ await test('登录状态含 xm 字段', async() => {
   return `xm.logged=${r.data.xm.logged}`
 })
 
+// ---- 调用秘钥鉴权（独立实例带 AUTH_KEY 起测；主实例未设 key 时本组自动跳过）----
+if (!externalServer && !process.env.AUTH_KEY) {
+  const AUTH_TEST_KEY = 'smoke-test-secret-key'
+  const authPort = await new Promise<number>(resolve => {
+    const srv = net.createServer()
+    srv.listen(0, '127.0.0.1', () => {
+      const p = (srv.address() as any).port
+      srv.close(() => resolve(p))
+    })
+  })
+  const authBase = `http://localhost:${authPort}`
+  const authServer: any = await startLocalServer(authPort, { AUTH_KEY: AUTH_TEST_KEY })
+  const authFetch = (path: string, init: RequestInit = {}) => fetch(authBase + path, init)
+
+  await test('AUTH_KEY 无秘钥 → 401', async() => {
+    const r = await authFetch('/sources')
+    if (r.status !== 401) throw new Error(`期望 401，实际 ${r.status}`)
+    return 'ok'
+  })
+  await test('AUTH_KEY 错误秘钥 → 401', async() => {
+    const r = await authFetch('/sources', { headers: { Authorization: 'Bearer wrong-key' } })
+    if (r.status !== 401) throw new Error(`期望 401，实际 ${r.status}`)
+    return 'ok'
+  })
+  await test('AUTH_KEY Bearer 通过', async() => {
+    const r = await authFetch('/sources', { headers: { Authorization: `Bearer ${AUTH_TEST_KEY}` } })
+    if (r.status !== 200) throw new Error(`期望 200，实际 ${r.status}`)
+    return 'ok'
+  })
+  await test('AUTH_KEY X-Api-Key 通过', async() => {
+    const r = await authFetch('/sources', { headers: { 'X-Api-Key': AUTH_TEST_KEY } })
+    if (r.status !== 200) throw new Error(`期望 200，实际 ${r.status}`)
+    return 'ok'
+  })
+  await test('AUTH_KEY ?key= 通过', async() => {
+    const r = await authFetch(`/sources?key=${encodeURIComponent(AUTH_TEST_KEY)}`)
+    if (r.status !== 200) throw new Error(`期望 200，实际 ${r.status}`)
+    return 'ok'
+  })
+  await test('AUTH_KEY /health 豁免', async() => {
+    const r = await authFetch('/health')
+    if (r.status !== 200) throw new Error(`期望 200，实际 ${r.status}`)
+    return 'ok'
+  })
+
+  authServer.kill()
+}
+
 // 汇总
 const passed = results.filter(r => r.ok).length
 const failed = results.filter(r => !r.ok)