hhhge/NeteaseUrl
Archived
1
0 Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity
81 Commits 1 Branch 0 Tags
main
Commit Graph
7 Commits
Author SHA1 Message Date
snowy-yang 96af56cc27 refactor: auth_system 全面异步化（aiosqlite），拆掉 web/services 层的 to_thread 桥接 
拆掉两类垫片的最后一处：auth_system 原为同步 sqlite3 栈，web 层与 services 的
worker 只能靠 asyncio.to_thread 逐个桥接才不阻塞事件循环——每次 DB 访问都白付一次
线程池调度，且「同步调异步」的边界散落在 100+ 个调用点。B1 已把 worker 变成协程，
本批把访问层本身也迁到原生异步，两条线在此合拢。

改动（按子系统）：
- auth_system：db.py 照 core/db.py 现有范式重建为原生异步访问层（aiosqlite + WAL）
  ——读路径 _q 每次独立连接、无锁、可并发；写路径 _x / write_transaction 用
  asyncio.Lock 串行化，写者不阻塞读者。users / cards / credits / ledger / logs /
  settings / mail / geo / backup 九模块随之全部 async/await；security.py 是纯计算
  （pbkdf2/normalize）不动。__init__ 去掉 _DB_LOCK 与 get_conn 导出。
- web：app / deps / billing / tasks_registry 与 routers/{admin_site,auth,music,
  register,user} 直接 await，拆掉包裹的 to_thread。deps.secret_key 改 async，
  连带 _parse_cookie 也 async（会话解析要读密钥）。
- services：_taskcore / tasks / downloads / podcast 的账本调用与查询直接 await。
  4 处 start_task 调用点（download.py）确认已 await。

设计取舍（为什么这么做，而不是直接包一层）：
- 锁按**事件循环**隔离（_LOOP_LOCKS 以 id(loop) 为键）：asyncio.Lock 绑定创建它的
  loop，应用主 loop 与测试各自的 loop 并存，跨 loop 复用会抛 "bound to a different
  event loop"。
- WAL 切换用**独立锁** _wal_lock 而非 _write_lock：execute() 已持写锁，再在锁内
  connect→_configure 会自锁死（asyncio.Lock 非重入）。切换 + 标记在专用锁内串行并
  二次复查，否则并发首连会同时执行 PRAGMA journal_mode=WAL 争排他锁报
  database is locked（core/db.py 同款教训，实测复现）。
- force_wal 保留：journal_mode 持久化在库文件头，库文件被删重建时新文件不继承，
  必须重设。exists() 判定须在 aiosqlite.connect **之前**（connect 会创建空文件）。
- connect() 用 DB_PATH.parent 兜底建目录，优于 DATA_DIR：生产两者相同，但测试
  monkeypatch 只换 DB_PATH 时兜底仍能命中正确目录。

留在 to_thread 上的仅剩**正当的阻塞卸载**，不是同步门面：PBKDF2 的 10 万次迭代
（登录链路每次都要跑）、smtplib 发信、备份文件的 copy2 / os.replace、secret.key
的文件 IO。原有 aria2 / downloader / zip 侧的 to_thread 未动。

不变量逐条保持（迁移只改执行模型，不改语义）：
- ledger_settle 幂等：账本非 open 直接 return 0，重启后重放不重复退款；
- 终态先到先得：_mark_task_terminal 对已 done/error/canceled 的任务直接 return，
  堵住 canceled→error 的非法迁移边；
- settle 必须在任务锁**外**调用（ledger_settle 要抢 SQLite 写锁，busy 最长 15s，
  持任务锁会让全站进度/提交/取消随库停摆）；
- reserve_and_open 的预扣与开账同事务，消除原两步之间的崩溃丢账窗口。

路径真源红线：DATA_DIR / DB_PATH / BACKUP_DIR / SECRET_KEY_PATH 仍是 auth_system.db
的**模块全局**（用与 core.db 相同的表达式，但**不是**它的别名）。测试只 patch
auth_system.db.*，若改成 core.db 的别名会静默把测试写到生产库。已核 data/site.db
读写前后 sha256 完全一致。
顺带清掉 get_conn：迁移后它只剩「转调 connect()」一层空壳、全仓零消费者（测试
直接开裸连接、备份用 db.connect()），保留等于留一条「拿裸连接自己写」的口子。

测试：19 个文件同步迁移——10 个文件的 web.deps.secret_key 替身改 async；
test_db_conn.py 的多线程首连用例按异步语义拆成 2 条（单 loop gather(16) 覆盖批量
并发首连、WAL 就绪后 8 线程各自 loop 建连覆盖跨 loop）；test_billing_scope.py 去掉
多余的 @pytest.mark.anyio；被 await 且**正常返回**的 monkeypatch 替身一律改 async
（仅 raise 的同步替身仍可用）。

门禁：ruff 全过 / pyright 0-0-0（standard 模式含 tests 与顶层模块）/ pytest
384 项全绿（0 失败 0 error 0 skipped；383→384 因 test_db_conn 拆用例）。
data/site.db 读写前后 sha256 一致（a19f5db…6487），无 -wal/-shm 边车残留。

下一步 B3：删 core/sync_http.py、core/async_bridge.py、core/http_errors.py 及
 tests/test_async_bridge.py——三者在生产侧已零消费者（http_errors 仅 sync_http
 自用，requests 已非声明依赖）。
 2026-09-28 20:13:19 +08:00
snowy-yang f27bd7dd74 refactor: /song 端点拆解（99 行 / 圈 18 → 主函数 27 行 / 圈 8） 
为什么：song 是端点层最重的函数——参数校验（4 条）、账号 Cookie 选择、四种 type
分发、json 分支的三源合并与降级全塞在一处；而四种 type 的返回体形状与降级口径
**没有任何测试记录**（golden 里的 /song 只有一条参数校验用例 song_badid）。

改法：
- _parse_song_query：提取 + 校验，返回 _SongQuery 或**错误消息字符串**。返回
  字符串而非响应对象，是为了让它不依赖响应层、可单独断言（校验段 4 条错误都是
  默认 400，无需状态码）。
- _SongQuery：frozen dataclass。music_id 保持 extract_id 的**字符串原值**——它
  原样进响应体 id 字段、golden 按字符串比对；上游要的 int 走 .mid property。
- _song_url_response / _song_json_response：两个实体分支各自成函数。
- song 主函数只剩「校验 → 选 Cookie → 四路分发」。

刻意保留的语义（是决定，不是疏漏）：
- 解析日志**只在 json 分支**记录，url/name/lyric 三路不记——历史实现如此。
  已写进 _song_json_response 的 docstring：不要为了「统一」把它上提到主函数，
  那会新增三路的可观察副作用。
- 校验顺序（缺参 → ID 非数字 → 音质 → 类型）原样保留，并用测试钉住「同时传错
  时报哪条」。顺序是用户可见行为。
- 三条 404 降级（上游 data 为空 / data=[null] / songs 为空）逐条保留。

复杂度（同口径 AST 实测，重构前后）：
  song                 99 行 / 圈 18 / 嵌套 4  →  27 行 / 圈 8 / 嵌套 2
  _song_json_response   新增                  →  49 行 / 圈 6 / 嵌套 1
  _parse_song_query     新增                  →  21 行 / 圈 5 / 嵌套 1
  文件内 >80 行函数 1 → 0；最大圈 18 → 11（余下最大的是本次未动的 mask_server_nickname）
  注：上一轮口头报的「圈 44」与本轮口径不同，此处以本轮统一口径为准，重测为准绳。

等价性证据（三道，互相独立）：
1. AST 字面量审计：字符串字面量 **227 处完全一致**；数值唯一差异是新增的
   dataclass frozen=True。即没有一条用户可见文案或阈值被改动。
2. 反向注入验证：把 HEAD 的旧 song 换回去，用同一套 tests/test_song_types.py 跑
   → 19 例**全过**，证明这批测试忠实编码了旧行为、对新实现构成等价性验证。
3. 新增 19 例行为契约测试：四种 type 正路、json 的三源合并与三种降级（歌词失败
   不阻断 / 直链失败置空 / 详情失败 404）、校验优先级、分享链接解析、
   account=user 无 Cookie 401、全局 Cookie 冒用拦截。

顺带修掉一个测试自身缺陷：新用例里「个人 Cookie 与全局账号一致」一条**单跑通过、
全套失败**——根因是它依赖 GLOBAL_MUSIC_U_CACHE（5 分钟粘性的模块级缓存），别的
文件先跑会把值填上，于是拿到缓存值而非本处 patch 的 Cookie。已改为 fixture 里
用 monkeypatch.setitem 显式重置该缓存，让用例自足。

验证：ruff 全过 · pyright 0/0 · pytest 233 passed（214→233）· 生产 data/ 未被
触碰（全部用例走 tmp_path 沙箱）。
 2026-09-27 07:41:16 +08:00
snowy-yang 6288a98ecc refactor: 拆分 4 个巨石模块为包，清理过时注释并删除作废文档 
为什么：单文件 1100~1900 行的巨石模块让「改一处要通读全文」；同时注释里残留
大量已删台账的编号，以及「Flask/FastAPI 双栈迁移期」这类已失实的架构描述，
会误导后来者按不复存在的架构去改代码。

拆分（对外导入路径不变，行为零变更）：
- music_downloader.py  -> music_downloader/（models/downloader/cover/_http/_log/_concurrency）
- auth_system.py       -> auth_system/（db/security/users/credits/ledger/mail/cards/backup...）
- music_api.py         -> music_api/（api/client/crypto/qr/cookies/compat/constants/errors）
- services/runtime.py  -> services/（api_service/_shared/_taskcore/downloads/batch/podcast/
  streaming/tasks）；services/runtime.py 保留为兼容门面

兼容性做法：各包用 __init__.py 以 __all__ 原样再导出全部符号，既有调用点
（auth_system.xxx / services.xxx / from music_api import Y）零改动；路径常量改为经包属性
动态读取（auth_system.DB_PATH），否则测试的 monkeypatch 会静默失效并写到生产库。

修复 9 处代码损伤（上一轮注释清理把 `()` 当「空括号残留」删掉所致；用「与拆分前逐字
等价」校验逐一定位，静态检查只会报出其中 4 处）：
- core/config.py  ).strip() or '*'
- core/state.py   threading.Lock() x2
- qr_login.py     datetime.now() / .strip()
- music_downloader/downloader.py  .lower()
- services/podcast.py  set() / time.time() x2

清理与删除：
- 删除 部署文档.md / 功能介绍.md / README_私有包警告.txt
- 清理指向已删台账与文档的过时编号注释；把「迁移期 / 两栈 / 双框架 / 已迁移」等
  失实描述改写为现状描述（保留 `<-> Flask /path` 映射表等仍有价值的契约来源说明）
- _mkpkg.py：公开包剔除清单去掉已不存在的文档名；私有包警告改为自包含
- pyproject.toml：补 pythonpath = ["."]，使裸跑 pytest 不再 import core 失败

验证：ruff 全通过；pyright 0 errors / 0 warnings（102 文件）；pytest 144 passed；
真实 uvicorn 冒烟 6 条路由符合预期且生产 data/ 指纹未变；忽略注释的逐字等价性校验通过。
 2026-09-26 12:37:48 +08:00
snowy-yang cd0f1f78a3 refactor: 迁移收尾（管理员2FA）+ 抽取公共工具层，消除 router 间重复 
补齐最后缺口：
- POST /api/v1/auth/admin_login/email、/auth/admin_login/verify（管理员 2FA Step2/3），
  复用 auth_routes 的票据表与尝试上限（跨栈共享），签发会话 Cookie

重构（消除约 200 行重复，11 个 router 受益）：
- web/request_utils.py：request_data / safe_int / extract_id / cookies / dedup_ids
  原在各 router 各复制一份，现集中
- web/serializers.py：format_credits / user_public / record_req_log
- 各 router 改为导入别名，行为逐字不变

覆盖率：Flask 90 条业务路由全部有 FastAPI 等价端点（含 5 个向后兼容别名）。
验证：pytest 69/69；ruff All checks passed；pyright 0 errors；奇偶 36/36；冒烟 10/10。
 2026-09-26 10:20:46 +08:00
snowy-yang 6c3181341b feat(routes): 迁移账号/全局歌单端点 + 鉴权依赖测试 
迁移路由（/api/v1/*，与 Flask 同端点逐字段对齐）：
- account/vip：admin/user 双路径 + 5 分钟缓存（降级结果 30s），
  VIP 探测单飞锁与 Flask 同源跨栈共享；未登录可访问（同 Flask）
- global/playlists、global/playlist：管理员闸（require_admin，403 对齐）
- web/deps.py 新增 require_admin；_resolve_user_cookies 支持可选用户（匿名审计保底）

测试：46/46（新增 10 项鉴权依赖：有效/管理员/封禁/禁用/顶号/伪造 Cookie、
401/403 闸）；ruff All checks passed；pyright 0 errors。

契约奇偶校验：16 项全 OK（新增 account:vip、global:playlists/playlist、
非管理员 403）；uvicorn 实跑双栈 account/vip 均 200、未授权歌单 403。
 2026-09-26 01:15:22 +08:00
snowy-yang a2758aa0da feat(routes): 迁移解析端点 /song /playlist /album + 响应卫生中间件 
迁移路由（/api/v1/*，与 Flask 同端点逐字段对齐）：
- song（type: url/name/lyric/json）、playlist、album
  个人账号路径实现全局账号冒用拦截（同 Flask 口径）；json 模式 asyncio.gather 并发
  song/url/lyric（歌词失败不阻断，与 Flask 线程池语义一致）
- core/media.py：format_file_size/quality_display_name/parse_cookie_str 纯函数复用

web/middleware.py（镜像 Flask after_request）：
- 音频直链 → HMAC 签名代理地址（密钥同源，两栈 token 互认）
- 安全头 nosniff/DENY/Referrer-Policy/CSP 基线；Server 抹为 NeteaseUrl；429 带 Retry-After
- 纯 ASGI 逐段转发（不破坏流式下载）；JSON 200 延迟 start 并**重算 Content-Length**
  ——修实测 IncompleteRead（原实现转发旧长度 + 新 body）

契约奇偶校验：12 项全 OK（新增 album/playlist/song×3）；
token/CDN 主机归一化（均为易变值，非契约漂移）。

验证：pytest 36/36；ruff All checks passed；pyright 0 errors；
uvicorn 实跑 /api/v1/song 直链已代理、CSP/Server 头正确。
 2026-09-26 01:12:54 +08:00
snowy-yang 2c55b55e03 feat(routes): 迁移查询类路由到 FastAPI + 会话互通 + 统一错误/限流 
会话互通（迁移关键）：
- core/session.py：itsdangerous 兼容的签名 Cookie 编解码（同密钥/同 salt/同
  时间戳编码），Flask 与 FastAPI 双向可读——实测 F->core 与 core->F 双向解出一致，
  篡改/错密钥返回 None

FastAPI 基础设施：
- web/deps.py    会话→当前用户（封禁/顶号校验，口径同 auth_system.current_user）
- web/errors.py  AppError + 全局异常处理，404/405/400 统一为本站包体
- web/ratelimit.py 复用 core.state 同一批限流桶（跨栈共享，避免绕框架绕过限流）
- core/repo.py  补 get_user_by_id（异步）

迁移路由（/api/v1/*，与 Flask 同端点逐字段对齐）：
- toplist / artist_songs / comments / search，走 music_api 异步方法
- search 的服务器昵称遮蔽改为 FastAPI 侧异步实现（不再依赖 main）

契约奇偶校验：扩展至 7 项（含登录会话互通 + 未登录 401），全 OK；
CDN 分片主机差异归一化（上游易变值，非契约漂移）。

验证：pytest 33/33；ruff All checks passed；pyright 0 errors；
uvicorn 实跑未登录 401 包体与 Flask 一致。
 2026-09-26 01:09:01 +08:00