refactor!: uv 管理环境 + 彻底删除技术债（Flask 与 requests 全部移除）

## uv 环境管理
- pyproject.toml 声明 dependencies + [dependency-groups].dev，uv.lock 精确锁定
- 删除 requirements.txt / requirements-fastapi.txt / requirements-dev.txt
- .python-version = 3.12；Dockerfile 改用 uv sync --frozen（可复现构建）
- 新增 jinja2（首页渲染）

## 删除 Flask 技术债
- 从 main.py 用 ast 精确剥离 56 个 Flask 节点（路由/中间件/错误处理/启动），
  框架无关的服务层落为 services/runtime.py（MusicAPIService、下载/打包 worker、
  任务监控、缓存清扫），零 Flask 依赖
- 删除 main.py（4527 行）与 auth_routes.py（1050 行）
- auth_system.py 移除会话/请求上下文层（login_session/current_user/login_required/
  admin_required/_client_ip 等），保留数据与业务层
- 新增 core/net.py（IP 解析）、web/auth_state.py（登录锁定/2FA 票据/发码限流）
- FastAPI 侧改直接依赖 services.runtime，不再 import main
- web/app.py 去掉 Flask fallback；入口默认根路径模式（API_PREFIX 可选）

## 删除 requests 技术债
- 新增 core/sync_http.py：requests 风格的同步门面（底层 aiohttp 连接池，
  流式读取经有界队列背压），含 Session/headers/(connect,read) 元组超时兼容
- core/utils、auth_system、podcast_api、music_downloader、services 全部切换
- 实测真实下载 5.2MB 音频完整成功

## 质量门禁归零
- ruff：0 错误（B904 全部修复，不再忽略）
- pyright：0 错误（类型收窄修复）
- pytest：140/140（含 golden 契约回归、root 模式 66 项路径覆盖）
- 真实 uvicorn 启动：/health、/、/static、受保护端鉴权全部正确

新增 tests/golden/responses.json：删除 Flask 前捕获的 32 例响应快照，
FastAPI 逐字段复现——删除巨石后行为回归仍有硬证据。

core/async_bridge.py

@@ -32,6 +32,11 @@ def _get_loop() -> asyncio.AbstractEventLoop:
     return _loop
 
 
+def get_loop() -> asyncio.AbstractEventLoop:
+    """后台事件循环（供需要直接提交协程的调用方使用）。"""
+    return _get_loop()
+
+
 def run_sync[T](coro: Coroutine[Any, Any, T], timeout: float | None = None) -> T:
     """在同步代码中运行协程并等待结果。
 

core/net.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+"""客户端 IP 解析工具（框架无关）。
+
+从 auth_system 抽出：可信反代判定与 XFF/X-Real-IP 解析规则。
+Flask 侧原本经 request.headers 取头；FastAPI 侧由 web.ratelimit 传入 header 值调用，
+故此处只保留纯函数（不依赖任何 Web 框架）。
+"""
+
+
+def is_loopback_ip(ip: str) -> bool:
+    """可信反代判定（第 91 条 P2-4：从"所有内网源"收窄为仅回环地址）。
+    服务绑 0.0.0.0 时内网任意主机都可直连伪造 XFF/X-Real-IP 轮换绕过限流与
+    登录锁定（实测实锤）；同机 Caddy 反代（127.0.0.1 → Flask）不受影响。"""
+    try:
+        import ipaddress
+        addr = ipaddress.ip_address(ip)
+        return addr.is_loopback
+    except ValueError:
+        return False
+
+
+
+
+def trusted_proxy_ip(header_value: str) -> str:
+    """第 97 条（P2-1）：从可信反代转发的 X-Forwarded-For 中取最右一个可解析 IP。
+    最右段是可信反代（Caddy）追加的直连方地址；最左段与 X-Real-IP 均可被客户端
+    伪造（Caddy 默认不改写客户端自带的 X-Real-IP），采信它们等于给限流/锁定/省份
+    记录开了伪造口。无有效值返回空串，调用方回落 remote_addr。"""
+    if not header_value:
+        return ''
+    import ipaddress as _ipa
+    for part in reversed(header_value.split(',')):
+        part = part.strip()
+        if not part:
+            continue
+        try:
+            return str(_ipa.ip_address(part))
+        except ValueError:
+            continue
+    return ''
+
+
+# 兼容原名（auth_system 等历史调用点沿用下划线命名）
+_is_loopback_ip = is_loopback_ip
+_trusted_proxy_ip = trusted_proxy_ip

core/sync_http.py

@@ -0,0 +1,202 @@
+# -*- coding: utf-8 -*-
+"""同步 HTTP 门面（底层 aiohttp）——彻底移除 requests 依赖。
+
+为什么需要它：部分代码天然是同步的（worker 线程里的流式下载、纯函数里的短链展开/
+IP 归属地查询）。本模块提供 requests 风格的同步 API，但底层复用 aiohttp 连接池，
+不再引入 requests。
+
+流式读取的实现：在后台事件循环起一个读取协程，把块推入有界队列（背压），
+同步侧从队列消费——每次搬运只过一次队列，不做「每块一次跨线程调度」。
+"""
+import asyncio
+import queue
+import threading
+from collections.abc import Iterator, Mapping
+from typing import Any
+
+from core import async_bridge
+from core.http_client import client as _client
+
+_DEFAULT_TIMEOUT = 30
+
+
+class RequestException(Exception):
+    """请求异常基类（对齐 requests 命名，便于迁移）。"""
+
+
+class HTTPError(RequestException):
+    """raise_for_status() 抛出的 HTTP 状态异常。"""
+
+    def __init__(self, message: str, response: 'SyncResponse | None' = None):
+        super().__init__(message)
+        self.response = response
+
+
+class SyncResponse:
+    """requests.Response 的同步子集（底层 aiohttp）。"""
+
+    def __init__(self, status: int, headers: Mapping[str, str], content: bytes | None,
+                 url: str, stream_state: dict | None = None):
+        self.status_code = status
+        self.headers = dict(headers)
+        self.url = url
+        self._content = content
+        self._stream = stream_state
+
+    @property
+    def content(self) -> bytes:
+        if self._content is None:
+            self._content = b''.join(self.iter_content(64 * 1024))
+        return self._content
+
+    @property
+    def text(self) -> str:
+        return self.content.decode('utf-8', errors='replace')
+
+    def json(self, **kw) -> Any:
+        import json as _json
+        return _json.loads(self.text, **kw)
+
+    def raise_for_status(self) -> None:
+        if self.status_code >= 400:
+            raise HTTPError(f'HTTP {self.status_code}', self)
+
+    def iter_content(self, chunk_size: int = 64 * 1024) -> Iterator[bytes]:
+        """流式读取响应体（大小写与 requests 一致：chunk_size 为字节数）。"""
+        if self._content is not None:
+            for i in range(0, len(self._content), chunk_size):
+                yield self._content[i:i + chunk_size]
+            return
+        st = self._stream
+        assert st is not None
+        q: queue.Queue = st['queue']
+        while True:
+            item = q.get()
+            if item is None:                      # 正常结束
+                break
+            if isinstance(item, BaseException):   # 读取出错
+                raise item
+            yield item
+
+    def close(self) -> None:
+        st = self._stream
+        if st and st.get('cancel') is not None:
+            try:
+                async_bridge.run_sync(_cancel(st))
+            except Exception:
+                pass
+
+    def __enter__(self) -> 'SyncResponse':
+        return self
+
+    def __exit__(self, *exc) -> bool:
+        self.close()
+        return False
+
+
+async def _cancel(st: dict) -> None:
+    st['cancelled'] = True
+    resp = st.get('resp')
+    if resp is not None:
+        resp.close()
+
+
+def _stream_reader(st: dict, chunk_size: int) -> None:
+    """在后台事件循环读块 → 有界队列（背压），同步侧消费。"""
+    async def _run():
+        try:
+            async for chunk in st['resp'].content.iter_chunked(chunk_size):
+                if st.get('cancelled'):
+                    break
+                while True:  # 背压：队列满则稍等，避免内存无界
+                    try:
+                        st['queue'].put(chunk, timeout=0.5)
+                        break
+                    except queue.Full:
+                        if st.get('cancelled'):
+                            return
+        except Exception as e:
+            st['queue'].put(e)
+        finally:
+            try:
+                st['resp'].close()
+            except Exception:
+                pass
+            st['queue'].put(None)
+
+    asyncio.run_coroutine_threadsafe(_run(), async_bridge.get_loop())
+
+
+class Session:
+    """requests.Session 的同步子集（连接池由底层 aiohttp 统一维护）。"""
+
+    trust_env = False
+
+    def __init__(self, **kw) -> None:
+        # headers：会话级默认头（与 requests.Session().headers.update 等价）
+        self.headers: dict[str, str] = dict(kw.pop('headers', {}))
+
+    def _merge(self, kw: dict) -> dict:
+        h = dict(self.headers)
+        h.update(kw.pop('headers', None) or {})
+        if h:
+            kw['headers'] = h
+        return kw
+
+    def get(self, url: str, **kw) -> SyncResponse:
+        return _request('GET', url, **self._merge(kw))
+
+    def post(self, url: str, **kw) -> SyncResponse:
+        return _request('POST', url, **self._merge(kw))
+
+    def close(self) -> None:
+        pass
+
+
+def _norm_timeout(timeout):
+    """requests 允许 (connect, read) 元组；aiohttp 只接受单一总时长——取较大者。"""
+    if isinstance(timeout, (tuple, list)):
+        vals = [float(v) for v in timeout if isinstance(v, (int, float))]
+        return max(vals) if vals else _DEFAULT_TIMEOUT
+    return timeout
+
+
+def _request(method: str, url: str, *, headers: Mapping[str, str] | None = None,
+             cookies: Mapping[str, str] | None = None, params: Mapping[str, Any] | None = None,
+             data: Any = None, json: Any = None, timeout: float | None = _DEFAULT_TIMEOUT,
+             allow_redirects: bool = True, stream: bool = False) -> SyncResponse:
+    timeout = _norm_timeout(timeout)
+    if stream:
+        return _open_stream(method, url, headers=headers, cookies=cookies, params=params,
+                            data=data, json=json, timeout=timeout,
+                            allow_redirects=allow_redirects)
+    resp = async_bridge.run_sync(_client.request(
+        method, url, headers=headers, cookies=cookies, params=params, data=data,
+        json_body=json, timeout=timeout, allow_redirects=allow_redirects))
+    return SyncResponse(resp.status, resp.headers, resp.text.encode('utf-8'),
+                        resp.url)
+
+
+def _open_stream(method: str, url: str, **kw) -> SyncResponse:
+    timeout = _norm_timeout(kw.pop('timeout', _DEFAULT_TIMEOUT))
+    # AsyncHTTPClient.open 只接受 headers/cookies/timeout/allow_redirects；
+    # 流式场景不支持 params/data/json（调用方直接把查询串拼进 URL）
+    for unsupported in ('params', 'data', 'json'):
+        kw.pop(unsupported, None)
+    resp = async_bridge.run_sync(_client.open(method, url, timeout=timeout, **kw))
+    st = {'resp': resp, 'queue': queue.Queue(maxsize=8), 'cancel': object(), 'cancelled': False}
+    th = threading.Thread(target=_stream_reader, args=(st, 64 * 1024), daemon=True)
+    th.start()
+    return SyncResponse(resp.status, resp.headers, None, str(resp.url), stream_state=st)
+
+
+# 模块级便捷函数（等价于共享 Session 的 get/post）
+_default_session = Session()
+
+
+def get(url: str, **kw) -> SyncResponse:
+    return _default_session.get(url, **kw)
+
+
+def post(url: str, **kw) -> SyncResponse:
+    return _default_session.post(url, **kw)

core/utils.py

@@ -105,9 +105,9 @@ def expand_shortlink(url: str) -> str:
         return hit
     expanded = url
     try:
-        import requests
+        from core import sync_http
 
-        response = requests.get(url, allow_redirects=False, timeout=10)
+        response = sync_http.get(url, allow_redirects=False, timeout=10)
         expanded = response.headers.get('Location', url)
     except Exception:
         expanded = url