 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
|
69a50c2c31
|
refactor: worker 子系统全面异步化，拆掉同步转异步的桥接层
拆掉「同步调异步 / 异步桥同步」两类垫片的第二半（HTTP 线 B2 见前序提交）。
worker 侧此前是「起线程跑同步函数、函数体内部再用 asyncio.to_thread 把活塞给
另一条循环」——线程与协程互等，取消/暂停只能靠轮询。本轮把 worker 自身变成
协程，由 _start_task 直接挂到应用事件循环上，桥接层随之失去存在理由。
改动（按子系统）：
- music_downloader：downloader / _aria2 / _concurrency / cover / _http /
__main__ 全链路协程化。per-file 锁改 asyncio.Lock；计数闸改
「active 计数 + await asyncio.sleep(0.5)」的可取消等待（原阻塞式 with 会让
已取消任务仍要等全局名额腾出，卡死并拖后腿退款）；aria2p 的同步 RPC 仍经
to_thread，轮询改 asyncio.sleep；新增 core.http_client.iter_chunks，把**流式
读取期**的 aiohttp.ClientError 收敛成 UpstreamNetworkError（请求建立阶段早已
有这条路径，读取阶段此前没有，断流会绕过调用方的 UpstreamError 分类）。
删除 get_http_session / _SESSION_LOCAL。
models._RetryFromScratch 不再继承 requests.RequestException 而继承 Exception：
它是「续传起点失效、残片已清、从头重下」，既不是确定性失败
(DownloadException)，也不是残片已保留的网络失败(UpstreamError)，必须独立
成类且在 except 链中先于二者捕获。
- music_api：podcast.py 全部函数协程化（直链解析内部改
await NeteaseAPI.get_song_url）；compat.py 删除——16 个死掉的同步门面早已
清空，文件只剩空壳。
- services：_taskcore / _zipcore / batch / downloads / podcast / tasks 协程化。
threading.Thread → loop.create_task（任务句柄字段 worker_thread →
worker_task），ThreadPoolExecutor → asyncio.gather + asyncio.Semaphore，
终态函数与结算回调全部改 await；监控线程里「worker 已死」判定改 task.done()。
删除 services/streaming.py（同步流垫片，唯一消费者已迁到
core.http_client.open）。zipfile 实例仍非线程安全，故「下载」并行、
「入包」严格串行。
- web：路由层 130+ 处 to_thread 拆除——被包住的目标自己已是协程，再包一层只是
把协程丢进线程里跑一圈。tasks_registry.start_task 直接 create_task。
web/app.py 关闭段去掉 async_bridge.shutdown()（不再有第二条约循环）。
web/routers/download.py 的播客端点补上 3 处漏掉的 await
（extract_podcast_ref / get_radio_detail）——漏掉时不报错、只静默返回协程对象，
靠 pyright 抓出来后修正。
留在 to_thread 上的都是**正当的阻塞卸载**：同步 SQLite 落库与账本结算、
mutagen 全量重写标签、zipfile 整段拷贝、shutil.rmtree、aria2p 的同步 RPC、
PBKDF2 的 10 万次迭代。ruff 对残留的本地元数据操作（exists/stat/os.replace/
往 .part 顺序写分块）按「微秒级、卸载的调度开销大于操作本身」放行，pyproject
逐条注明理由。
取消/暂停仍由 threading.Event 承载：置位方是请求线程/监控线程，读取方是 worker
协程，只有「置位」与「轮询读取」两种操作，既不需要跨循环唤醒也不会卡住事件
循环——比 asyncio.Event 更省心（ASYNC110 同理按此豁免）。
测试：10 个文件的替身边界同步迁移——网络替身从 core.sync_http 的
get_http_session 换成 downloader/服务模块的 _http.open + **真实** iter_chunks
（顺带钉住读取期异常收敛）；`_run` 改为在独立线程里 asyncio.run(worker(...))；
aria2 的假时钟从 time.sleep 换成 _POLL_INTERVAL=0；monitor 的线程句柄替身换成
done() 可控的轻量替身（asyncio.Task 的构造需要运行中的事件循环，而监控循环跑在
常驻线程里）；podcast / 封面 / 结算包装等替身一律改 async。
门禁：ruff 全过 / pyright 0-0 / pytest 383 项全绿（0 失败）。
下一步 B2：auth_system 12 个模块改 aiosqlite 背板、web 层剩余 to_thread 收尾；
B3：删 core/sync_http.py、core/async_bridge.py、core/http_errors.py（现仅
sync_http 自用）。
|
2026-09-28 19:36:56 +08:00 |
|
|
snowy-yang
|
7a70eef636
|
refactor: 删除 services.runtime 兼容门面，7 处调用点直连真实子模块
为什么：上一次分包重构把 1900 行巨石按职责拆成 9 个子模块后，留了一个
runtime.py 作为「原样再导出」的兼容门面，好让调用点零改动。但迁移期结束后
没有一个调用点迁走——门面成了永久中间层：每次读代码都要先跳一层才知道
符号真正住在哪，pyright 也无法从门面追溯定义位置。
改法：保持「函数内延迟导入」的形式不变，只把导入目标换成真实子模块。
**刻意不提到模块顶部**——services/__init__.py 里有依赖自检
（缺 auth_system/podcast_api/music_api/music_downloader/qr_login 就 sys.exit(1)），
提到顶层会让「import web.*」这一步就触发该自检，改变启动语义，超出本次范围。
7 处调用点（AST 精确扫描确认全集）：
- web/routers/download.py ×4：download / download_batch_zip / podcast_download /
podcast_batch_zip，分别直连 services.downloads / batch / podcast / tasks
外加 _shared._build_download_base 与 api_service.api_service
- web/routers/tasks.py ×2：_semaphores 取 _shared.BATCH_ZIP_SEM + api_service，
topen 取 _shared.ENDPOINT_NAMES
- web/tasks_registry.py ×1：start_task 直连 _taskcore._start_task_thread
子模块短名统一加 `services_` 前缀别名（services_tasks 等），避免与函数内
既有局部名相撞。
顺带清理：9 个子模块 docstring 里「（自 services/runtime.py 拆出……）」的
历史说明在门面删除后已成悬空引用，一并去掉；包的模块划分说明改为
「不再有兼容门面层」。
验证：
- 符号可达：11 个被引符号在真实子模块上全部 hasattr 通过；
services.runtime 已 ModuleNotFoundError；api_service 仍是同一实例对象
- 三个调用方模块均可正常 import
- 门禁：ruff 0 · pyright 0 errors 0 warnings · pytest 175 passed
- 真实 uvicorn 冒烟 8/8（含 POST /auth/login 400），临时数据目录独立落库
9 张表，生产 data/ 指纹三项一致
|
2026-09-26 14:48:05 +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
|
8446166120
|
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 逐字段复现——删除巨石后行为回归仍有硬证据。
|
2026-09-26 11:10:17 +08:00 |
|
|
snowy-yang
|
9df0028195
|
feat(routes): 迁移下载/批量打包/播客下载（账本事务）+ 修密钥绑定缺陷
迁移端点：
- POST /api/v1/download（单曲：file 后台任务 / json 同步交付+结算）
- POST /api/v1/download/batch_zip（按去重歌曲数计费）
- POST /api/v1/podcast/download、/podcast/download/batch_zip
- 新增 web/billing.py（预扣+开账同事务 / 只退 open 行 / rename 承接）
与 web/tasks_registry.py（任务登记/容量闸/账本撞名重试，与 main 同口径）
- worker 仍复用 main 既有实现（无 flask 依赖），账本与交付语义不变
修复我引入的真实缺陷：
- download 参数校验分支（ID/音质/格式非法）漏退款 → 预扣泄漏。改为统一 _fail() 退款
- web/routers/{auth,register}.py 在导入期绑定 deps.secret_key，导致 patch web.deps.secret_key
无效、且测试顺序相关。改为调用期 deps.secret_key() 解析
测试：tests/test_download_billing.py 7 项沙箱用例如实断言账本守恒
（预扣必退、无 open 行残留、次数不足不建任务）；
全套 pytest 69/69（顺序无关）；ruff All checks passed；pyright 0 errors；奇偶 36/36。
|
2026-09-26 10:13:16 +08:00 |
|