From 557f2f18a9c5335a65905ad7f5b0e3e3ef291f89 Mon Sep 17 00:00:00 2001 From: jxxghp Date: Sun, 23 Aug 2026 08:57:39 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20=E4=BF=AE=E5=A4=8D=E8=BF=90=E8=A1=8C?= =?UTF-8?q?=E6=97=B6=E9=85=8D=E7=BD=AE=E9=80=92=E5=BD=92=E4=B8=8E=E6=8F=92?= =?UTF-8?q?=E4=BB=B6=E5=85=BC=E5=AE=B9=E5=85=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- app/startup/modules_initializer.py | 4 +- docker/update.sh | 7 ++- .../backend-architecture-next-stage.md | 59 +++++++++++++++++++ scripts/perf/moviepilot_docker_ab.py | 2 +- tests/test_configuration_ports.py | 11 ++++ tests/test_docker_bootstrap.py | 6 ++ tests/test_docker_payload_contract.py | 9 +++ 7 files changed, 95 insertions(+), 3 deletions(-) diff --git a/app/startup/modules_initializer.py b/app/startup/modules_initializer.py index 2257d44d2..2a418a591 100644 --- a/app/startup/modules_initializer.py +++ b/app/startup/modules_initializer.py @@ -574,7 +574,9 @@ async def init_modules() -> HostRuntime: scheduler=lambda: build_scheduler_runtime_config(settings), chain=lambda: build_chain_runtime_config(settings), ) - runtime_settings = RuntimeSettingsService(settings) + # RuntimeSettingsService 必须持有真实 Settings；RuntimeSettingsCompat 是旧 ABI 代理， + # 将代理自身注入服务会让 model_dump() 在代理和服务之间无限递归。 + runtime_settings = RuntimeSettingsService(legacy_settings) host_runtime = HostRuntime( agent_chat=AgentChatRuntime( async_session=get_async_db, diff --git a/docker/update.sh b/docker/update.sh index 570192d51..44c20534a 100644 --- a/docker/update.sh +++ b/docker/update.sh @@ -286,7 +286,12 @@ function stage_runtime_payload() { else mkdir -p "${stage_plugin_dir}" || return 1 fi - rm -f "${stage_plugin_dir}/__init__.py" + # 保留 app.plugins 兼容入口；V1/V2 插件仍从这里导入 _PluginBase。 + # 删除后 app.plugins 会退化为 namespace package，旧插件会在启动时全部导入失败。 + if [ ! -f "${stage_plugin_dir}/__init__.py" ]; then + ERROR "插件运行目录缺少 app.plugins 兼容入口" + return 1 + fi resource_source_dir="$(existing_resource_dir)" mkdir -p "${stage_resource_dir}" || return 1 diff --git a/docs/refactor/backend-architecture-next-stage.md b/docs/refactor/backend-architecture-next-stage.md index 21a041a3f..4cfa7c61d 100644 --- a/docs/refactor/backend-architecture-next-stage.md +++ b/docs/refactor/backend-architecture-next-stage.md @@ -8,6 +8,65 @@ > 相关文档：`docs/architecture-overview.md`、`docs/refactor/backend-architecture-governance.md`、`docs/refactor/backend-module-refactor-compatibility.md` > 实施进度：阶段 0～6 的宿主架构能力已完成收口；API/Application 公共复杂度基线已清零，启动组合根的 SystemConfigOper 构造点已由 14 降至 1；插件仓适配、Outbox 外围扩展和 Model 查询兼容面仍按风险切片推进。 +## 当前复核结论（2026-08-23） + +本节是本轮全面复核后的当前事实源。本文后续的阶段实施记录保留历史审计证据， +其中的数量和判断以当时审计提交为准，不能直接当作当前未完成项。 + +### 总体判断 + +当前架构总体合理，已经从跨层混合的遗留单体收敛为**边界清晰的模块化单体**： + +- 继续采用单进程控制面是正确选择，不建议现在拆成微服务；插件、调度器、工作流、事件和数据库共享进程内状态，拆分会放大部署、事务和兼容成本。 +- `foundation/domain/runtime/adapters/application/chain/api/startup` 的职责方向基本成立；宿主架构基线、复杂度 ratchet、异步阻塞 ratchet 当前均通过。 +- 依赖图当前约 `796` 个 Python 模块、`6432` 条内部导入边；唯一非平凡 SCC 位于隔离的 TMDB 第三方移植包内部，不应为了指标归零重写。 +- 当前主要风险已经从“目录和依赖失控”转移到运行时协议、后台副作用的可靠性和遗留兼容面。换言之，下一阶段重点应是**语义收口和可验证性**，而不是继续搬文件或机械拆大文件。 + +综合评价：架构方向可持续，生产可用性较高；可演进性仍处于中等水平。现阶段没有静态审计发现必须立即推倒重来的 P0 架构问题，但存在需要按 P1/P2 计划治理的真实债务。 + +### P1：需要优先治理的真实债务 + +1. **后台任务没有统一的所有权和恢复模型。** 当前约有 `50` 个 `create_task`/等价任务创建点，另有 FastAPI `BackgroundTasks`、线程池和 APScheduler 并存。生命周期清单能关闭模块、插件、调度器和 Agent，但 API 层的若干任务集合（如 `app/api/endpoints/agent.py`、`app/api/endpoints/plugin.py`）没有统一注册到 HostRuntime，也没有在 shutdown 阶段统一等待或取消。`app/api/endpoints/webhook.py:32`、`app/api/endpoints/site.py:178` 这类接口会先返回成功，再执行关键副作用；进程崩溃、重启或客户端断开时可能丢失。需要为每类任务明确 owner、取消、等待、重试、幂等和是否 durable，关键业务副作用优先接入已有 Outbox/恢复表。 +2. **动态模块契约仍以 legacy 聚合语义为主。** 当前登记 `212` 个模块方法，其中 `194` 个仍使用 `legacy` aggregation，只有 `14` 个 `first_non_empty`、`4` 个 `ordered_list_merge`。`app/runtime/extensions/module/contracts.py:422-455` 已能登记 family、输入/结果标签和基础签名诊断，但 `193` 个方法没有 required parameters，调度器 `app/runtime/extensions/module/dispatcher.py:109-260` 仍主要依赖运行时反射、返回值形状和短路规则。未知第三方方法保留 legacy fallback 是兼容要求，不应删除；宿主高频能力则应逐族补齐可执行的输入校验、结果校验、超时和错误语义。 +3. **查询侧数据库兼容 ABI 仍未完全收口。** 写事务装饰器已降为 `0`，事务所有权已经明显改善；但 `app/db/models` 仍有 `106` 个 `db_query/async_db_query`（`62` 个同步、`44` 个异步）。这些装饰器会在调用方未传 Session 时隐式创建并关闭会话（见 `app/db/decorators.py:224-298`），查询返回的 ORM 对象仍可能跨层流转，导致事务组合、对象生命周期和懒加载行为需要依赖隐含约定。应按高频业务路径逐步迁移到显式 Query/Repository + 请求/任务级 Session，不宜一次性全仓改写。 +4. **组合根和全局状态仍形成复杂的隐式运行时图。** Singleton 实例、模块级 provider、`configure_*` 注册函数和兼容 Facade 同时存在；它们解决了旧 ABI 和启动顺序问题，但增加测试污染、重复装配、实例身份和初始化顺序风险。`app/startup/lifecycle/__init__.py:161-376` 已有声明式生命周期，`app/startup/modules_initializer.py:505-530` 也有分阶段关闭，但尚未做到所有进程级资源都只通过 typed HostRuntime 访问。后续应以“新代码禁止新增 Service Locator/Singleton 依赖、旧入口有命中观测”为 ratchet。 + +### P2：中长期可演进性债务 + +- **大型职责域仍偏重。** 代表性热点包括 `app/chain/subscribe.py`（约 `4141` 行）、`app/chain/transfer.py`（约 `2944` 行）、`app/agent/orchestrator.py`（约 `3535` 行）、`app/agent/llm/provider.py`（约 `3529` 行）、`app/adapters/external/market.py`（约 `2805` 行）和 `app/api/endpoints/agent.py`（约 `2326` 行）。复杂度 ratchet 只保证不超过当前基线，不代表这些文件已经易维护。只有在行为快照、调用命中和事务边界明确后，才值得按用例拆分。 +- **类型门禁覆盖面不足。** `mypy.ini` strict 文件清单目前约 `37` 个文件，Agent、Chain、Module、Adapter 大量代码仍依赖动态类型。应从模块契约、生命周期、Repository/Port 和关键 Chain 返回值开始扩展，而不是直接开启全仓 strict。 +- **Pylint 仍是增量硬门禁。** `.github/workflows/pylint.yml` 对改动 Python 文件执行硬检查，但全仓报告使用 `|| true` 仅作 advisory。该策略适合存量迁移，却没有形成全仓质量趋势约束；应增加按目录和新增问题数的 ratchet。 +- **测试风格存在历史混用。** 当前约 `499` 个测试文件，仍有约 `70` 个 `unittest.TestCase` 文件。它不是生产架构缺陷，但会增加 fixture、状态隔离和异步测试迁移成本，应在触碰相关模块时渐进迁移。 +- **跨仓治理链路尚未完全闭环。** 前端已有 lint、typecheck、分片 Vitest 和构建门禁；插件仓有 V1/V2/V3 索引及版本/依赖检查；资源和 Rust 仓有独立构建发布链路。但插件 CI 本地复核因插件仓环境缺少主仓依赖 `httpx2` 无法完成收集，说明“插件仓测试环境与主仓锁定依赖”的可复现性仍需加强。资源构建通过 PR 同步到 `MoviePilot-Resources`，Rust 发布后自动向主仓发依赖 bump PR，链路合理但仍是多仓异步发布，需保留版本 provenance 和回滚点。 + +### 已解决、不应重复治理的问题 + +- 分层依赖和重点禁止边已建立门禁；不要再以“减少目录数量”作为目标。 +- 全功能多 worker 的误导性配置已由 `app/runtime/topology.py` 和 `app/main.py` 拒绝；V3 默认单 worker 的部署事实已经明确。 +- 写事务已由组合根/UoW/Outbox 方向收口，`db_update/async_db_update` 为零；不要重新引入 Model 自动提交。 +- 已具备 correlation ID、`/health/live`、`/health/ready`、模块/事件/调度观测端口和兼容 Facade 命中指标；历史文档中“完全缺少观测能力”的描述已过时。 +- 旧导入路径、SDK 导出、插件 manifest 和 V1/V2/V3 索引均有白名单或版本约束；兼容层应继续保持“薄、可观测、只增不删”，不应为了清理目录直接删除。 +- TMDB 移植包内部 SCC 属于第三方隔离代码，按现状豁免是合理的技术决策。 + +### 刻意保留的兼容成本 + +以下内容不是遗漏，而是当前产品 ABI 的有意成本： + +1. 未知第三方插件自定义模块方法继续走 `legacy` fallback，不能因宿主契约收口而拒绝加载旧插件。 +2. `PluginManager`、`PluginHelper`、`MoviePilotServerHelper` 等 Facade 继续保留旧公开/私有调用面，并通过 `compat.facade.hit` 统计迁移命中。 +3. `app/runtime/compat` 的精确旧导入映射、`app.sdk._legacy` 薄门面和插件 V1/V2/V3 三代索引继续存在，直到命中数据和发行策略支持删除。 +4. 查询装饰器保留为只读兼容入口，迁移以高频路径和可观测收益为依据，不以“全仓零装饰器”作为短期目标。 + +### 建议的后续治理顺序 + +1. **先做后台任务审计与统一登记**：建立 TaskOwner/生命周期协议，区分请求后非关键通知、可重试 Outbox 副作用和必须在请求内完成的业务写入；为断线、崩溃、重复执行和 shutdown 补测试。 +2. **再做模块契约 V2 增量收口**：优先识别调用量最高、影响下载/整理/识别的能力族，补真实参数对象、结果验证、超时预算和 provider 行为快照；legacy fallback 只保留给第三方未知方法。 +3. **随后迁移查询 ABI**：从订阅、历史、消息、用户和站点等高频查询开始，逐步让 Query/Repository 接收显式 Session，并验证 detached 对象、懒加载和事务组合。 +4. **最后扩展类型和复杂度预算**：每次触碰大型职责域时拆一个可回滚垂直切片，同时扩大 mypy strict 清单和 Pylint 新增问题 ratchet；不要为追求行数指标进行无行为收益的拆分。 +5. **跨仓发布以契约为中心**：保持插件索引、前端远程组件、资源版本、Rust wheel 和主仓依赖的 provenance；将插件测试环境固定为主仓 `uv.lock` 可复现安装，避免本地和 CI 依赖漂移。 + +本轮复核结论：**当前架构不需要推倒重来，真正未完成的是运行时可靠性和协议收口。** 下一轮治理完成上述 P1 后，再评估是否值得继续拆分大型文件或扩大严格类型范围。 + ## 1. 结论先行 MoviePilot V3 当前不是“目录混乱、必须推倒重来”的状态。第一阶段治理已经取得实质成果： diff --git a/scripts/perf/moviepilot_docker_ab.py b/scripts/perf/moviepilot_docker_ab.py index 63e98179d..233174993 100644 --- a/scripts/perf/moviepilot_docker_ab.py +++ b/scripts/perf/moviepilot_docker_ab.py @@ -107,7 +107,7 @@ FROM ${MP_SUBSTRATE} AS frozen RUN set -eux; \ mkdir -p /frozen/plugins /frozen/site; \ cp -a /app/app/plugins/. /frozen/plugins/; \ - rm -f /frozen/plugins/__init__.py; \ + test -f /frozen/plugins/__init__.py; \ rm -rf /frozen/plugins/__pycache__; \ find /app/app/application/site -maxdepth 1 -type f \ \( -name 'sites.*.so' -o -name 'user.sites.v3.bin' \) \ diff --git a/tests/test_configuration_ports.py b/tests/test_configuration_ports.py index ac0f1b46e..ef83c51ac 100644 --- a/tests/test_configuration_ports.py +++ b/tests/test_configuration_ports.py @@ -19,6 +19,7 @@ from app.application.configuration import ( get_api_runtime_config_snapshot, get_transfer_retry_config, ) +from app.runtime.settings import RuntimeSettingsCompat, configure_runtime_settings_compat class _MutableSettings: @@ -62,6 +63,16 @@ def test_runtime_settings_service_hides_mutable_settings_implementation() -> Non assert service.get("VALUE") == "final" +def test_runtime_settings_compat_delegates_to_concrete_service_backend() -> None: + """兼容 Settings 代理委托到真实设置对象时不会在 model_dump 中递归。""" + service = RuntimeSettingsService(_MutableSettings()) + configure_runtime_settings_compat(service) + + assert RuntimeSettingsCompat().model_dump(include={"VALUE"}) == { + "VALUE": "before" + } + + def test_system_config_service_supports_separate_reader_and_writer() -> None: """应用服务可以分别注入只读与写入适配器。""" reader = MagicMock() diff --git a/tests/test_docker_bootstrap.py b/tests/test_docker_bootstrap.py index 63e1dac55..7b789b866 100644 --- a/tests/test_docker_bootstrap.py +++ b/tests/test_docker_bootstrap.py @@ -921,6 +921,9 @@ def test_failed_dependency_sync_does_not_replace_program_files(tmp_path: Path) - (live_app / "app" / "application" / "site").mkdir(parents=True) live_public.mkdir() (live_app / "app" / "old.py").write_text("old", encoding="utf-8") + (live_app / "app" / "plugins" / "__init__.py").write_text( + "# legacy plugin compatibility entrypoint\n", encoding="utf-8" + ) (live_app / "app" / "plugins" / "plugin.py").write_text("plugin", encoding="utf-8") (live_app / "app" / "application" / "site" / "user.sites.v3.bin").write_text( "sites", encoding="utf-8" @@ -931,6 +934,9 @@ def test_failed_dependency_sync_does_not_replace_program_files(tmp_path: Path) - update_tree = tmp_path / "update" / "App" (update_tree / "app" / "plugins").mkdir(parents=True) + (update_tree / "app" / "plugins" / "__init__.py").write_text( + "# legacy plugin compatibility entrypoint\n", encoding="utf-8" + ) (update_tree / "pyproject.toml").write_text("[project]\n", encoding="utf-8") (update_tree / "uv.lock").write_text("version = 1\n", encoding="utf-8") (update_tree / "version.py").write_text("FRONTEND_VERSION = 'v3.0.1'\n", encoding="utf-8") diff --git a/tests/test_docker_payload_contract.py b/tests/test_docker_payload_contract.py index ceb5320b3..cda4b525d 100644 --- a/tests/test_docker_payload_contract.py +++ b/tests/test_docker_payload_contract.py @@ -77,6 +77,15 @@ def test_dockerfile_assigns_each_payload_to_an_independent_stage() -> None: assert "RUN rm -rf /app/frontend-dist" in dockerfile +def test_plugin_runtime_updates_preserve_legacy_base_entrypoint() -> None: + """更新和性能覆盖镜像必须保留旧插件导入 _PluginBase 所需的兼容入口。""" + update_script = _read(ROOT / "docker" / "update.sh") + perf_script = _read(ROOT / "scripts" / "perf" / "moviepilot_docker_ab.py") + + assert 'rm -f "${stage_plugin_dir}/__init__.py"' not in update_script + assert "rm -f /frozen/plugins/__init__.py" not in perf_script + + def test_release_workflows_pin_and_record_external_payload_identities() -> None: """正式与 Beta 构建都必须以真实制品身份驱动缓存并写入镜像标签。""" for workflow_path in (RELEASE_WORKFLOW, BETA_WORKFLOW):