astrbot_plugin_imagestudio/审计/README.md

119 行
11 KiB
Markdown

# AstrBot ImageStudio 代码审计
**审计对象**:`AstrBot ImageStudio` 插件仓库
**分支 / 基线**:`codex/character-profile-document-import` @ `8040a1b`(工作树含未提交改动)
**审计日期**:2026-07-27
**审计范围**:仓库全部源码(后端 Python ~64,100 行、前端 Vue/TS 39,254 行、测试 11,559 行)
**排除范围**:`.tmp/` 部署快照、`.tmp_pytest_*`、`node_modules/`、`__pycache__/`、`release/` 内的源码、`web/` 与 `pages/imagestudio/` 的构建产物内容
---
## 状态:✅ 已完成(含终审校验)
| 环节 | 状态 |
|---|---|
| 15 个维度并行审计 | ✅ 完成 · 产出 214 条发现 |
| C0 测试实跑验证 | ✅ 完成 · 后端 263 passed / 188.72s,前端 26 passed,`typecheck` (strict) 通过 |
| 对抗式复核(P0/P1 逐条) | ✅ 完成 · 覆盖 56 条,**推翻 16 条**,维持 40 条(其中 **33 条下调**严重度,仅 7 条维持原判) |
| 5 份主报告汇总 | ✅ 完成 |
| **终审校验**(推翻项回扫 / 密钥泄露检查 / 数字一致性 / 行号抽验 / 漏收回扫) | ✅ 完成 · 见下方「终审记录」 |
---
## 目录
| 文件 | 一句话摘要 | 关键结论 |
|---|---|---|
| [01-总览与架构.md](01-总览与架构.md) | 规模统计、五层架构地图、依赖热点、前后端契约面。 | 约 350 文件 / 115,000 行;`App.vue` 22,563 行、`advanced_style_set_service.py` 4,491 行是两座巨石;扇入 Top3 是 `core.identity`(65) / `database.db_helper`(56) / `backend.dto.common`(54)。 |
| [02-BUG清单.md](02-BUG清单.md) | 缺陷清单:**94 条**成立缺陷(P0×1 / P1×10 / P2×64 / P3×19),含两条完整可利用攻击链、逐条位置与修复建议。 | 唯一 P0 是打进 19 个部署 tar 并推送到 NAS 的 5 类真实凭据(**必须轮换,删文件无效**)。P1 集中在权限分级缺失、五链路 IDOR、队列 LIFO、PG 后端不可用、`displayMediaUrl` 副作用。 |
| [03-耦合分析.md](03-耦合分析.md) | 后端内部耦合 + 前后端耦合:9 条分层违规、35 个分散装配函数、11 处业务逻辑双写、类型契约漂移。 | **病灶不是"接错线",是"没有装配台"**——组合根缺失导致 34 处各自重读 `config.yaml`、同一个 `WorkflowService` 被装配成行为不一致的实例。URL 层很干净(166 条路由 ↔ 143 个 endpoint,**零个会 404**),漏的是"规则"没被下发。 |
| [04-代码精简方案.md](04-代码精简方案.md) | 可执行的精简方案:净删 **≈3,513 行**(后端 1,746 / 前端 1,767),另 ≈7,200 行属 App.vue 迁出;含仓库卫生与 **10 条"不建议做的事"**。 | 后端:连接样板 ×131、`_optional_text` ×30、`_string_list` ×17。前端:拆 `App.vue` **必须 CSS 先行**(8,395 行未 `scoped` 的全局样式才是拆不动的直接原因)。 |
| [05-优化路线图.md](05-优化路线图.md) | 决策文档:5 个阶段(止血 → 安全边界 → 正确性 → 解耦 → 精简)、风险矩阵、量化目标、5 人日 / 20 人日两套投入方案、方法与 7 条局限声明。 | **前三阶段(≈4 周)解决"会出事",后两阶段解决"改得慢",不要倒过来做。** 阶段 0(凭据轮换)是唯一不可被插队的 24 小时事项。 |
| [findings/](findings/) | 15 个维度的原始发现(分维度独立文件)+ `_raw.json` 结构化全量 + `_复核结论.md` 复核意见全文。 | 原始材料,**严重度以主报告为准**(原始发现未经复核校准)。 |
---
## 发现总数与复核统计
### 按维度
15 个并行维度,共 **214 条**发现:
| 维度组 | 维度 | 条数 |
|---|---|---:|
| A · 功能域 | A1 生成与队列 13 · A2 工作流与轮次 11 · A3 素材与风格集 14 · A4 数据层 11 · A5 核心与安全 13 · A6 引擎与适配器 15 · A7 路由与插件入口 13 · A8 前端 App 主体 12 · A9 前端功能组件 15 | 117 |
| B · 耦合 | B1 前后端耦合 17 · B2 后端内部耦合 14 | 31 |
| C · 横向 | C1 后端精简 20 · C2 前端精简 15 · C3 测试与仓库卫生 14 · C4 横切关注点 17 | 66 |
| **合计** | | **214** |
(另有 C0「测试实跑结果」,为基线事实而非发现。)
### 按类别与严重度(原始判定)
| 类别 | 条数 | | 原始严重度 | 条数 |
|---|---:|---|---|---:|
| bug | 59 | | P0-致命 | 6 |
| hygiene | 46 | | P1-严重 | 51 |
| coupling | 34 | | P2-中等 | 104 |
| simplify | 28 | | P3-轻微 | 53 |
| perf | 24 | | | |
| security | 23 | | | |
### 复核统计(对抗式验证)
对全部 **56 条 P0/P1** 各派一名独立复核者,立场预设为「**默认这是误报**」,要求实际 Read 源码后方可判定成立。
| 结果 | 条数 | 占比 |
|---|---:|---:|
| **推翻**(误报,不得作为成立缺陷收录) | **16** | 29% |
| 维持但**下调**严重度 | **33** | 59% |
| 维持原判 | 7 | 12% |
复核后严重度分布(56 条):P0 × 1 · P1 × 9 · P2 × 20 · P3 × 26(含 16 条推翻项的 P3 残留定级)。
换算成"原判 → 现判":原判 P0 的 6 条只剩 **1** 条仍是 P0(凭据泄露),3 条降 P1、1 条降 P2、1 条被推翻;原判 P1 的 50 条中仅 **6** 条维持 P1,19 条降 P2、10 条降 P3、15 条被推翻。
> **误报率 29% + 下调率 59% 本身就是一条结论**:并发类与影响链类推演的出错率很高,动手修之前先写一个能复现的测试,红了再改。
**16 条被推翻的发现按类别**:bug 9 · perf 2 · security 1 · coupling 1 · hygiene 3。其中 12 条属 `bug/security/perf`(02 报告的收录范围),已全部从"成立的缺陷"中剔除 —— 11 条的残留技术债按复核给出的降级严重度收录在 02 §6 的 P3 表并标注「经复核降级」、**不计入 94 条统计**;剩余 1 条(SQLite 未启用 WAL)的残留内容与另一条独立成立的 P2 性能发现指向同一处代码,已合并。
复核同时修正了原报告的事实错误,例如:泄露文件的 `api_key_plaintext` 实际在第 **25** 行(原报告写 :26);`_string_list` 真实是 **17** 处而非 18 处(多算的在 `.tmp/` 构建快照里);"23 个 service 零测试"经 `coverage 7.15.2` 实测证伪(真实为 9 个模块 ≈1,966 行零执行)。
被推翻条目的完整复核意见见 [findings/_复核结论.md](findings/_复核结论.md),**16 条逐条附完整反驳论证**。
---
## 终审记录(2026-07-27)
对 5 份主报告做了一轮独立终审,检查项与结果:
| 检查项 | 结果 |
|---|---|
| **被推翻的 16 条是否仍被当成立缺陷写进主报告** | 发现 **2 处**并已修正:03 §1.1 复述了被证伪的「单测构造 `GenerationService` 需连带 import 31 个依赖」(`tests/test_workflow_round_queue_runtime.py:12` 直接反证);03 §2.2 #3 复述了被证伪的 `adopt-image` 触发路径(`history_service.py:55` 原子写两字段,真实路径是 `image_service.select_image`)。 |
| **是否出现真实密钥值** | ✅ 未发现。全文仅出现类型 / 长度 / 前 4 位(`sk-3` / `sk-B` / `eyJh`),无完整 key、无 JWT、无口令、无 IP。 |
| **严重度是否与复核结论一致** | 发现 **7 处**不一致并已修正:03 §2.2 三条误标"维持 P1"(实为 P2/P2/P3);03 三处路线图行沿用 P1;02 §0.2/0.3 标题误标 P1(实为 P2);04/05 三处把 `displayMediaUrl` 标为 P0(复核降为 P1);05 风险矩阵与 3-8 沿用了被证伪的"无法自恢复的报错"。 |
| **数字是否自相矛盾** | 发现 **4 处**并已实测校准:`App.vue` 的 `endpoints.` 引用 171 → **183**;`ref`/`computed` 计数 133/135 与 206/203 两种口径混用 → 已统一为 206/203 并注明字面量口径;`main.py` 短命令别名 50 → **38**;`_optional_text` 28 → **30**。已核对无误的数字:`App.vue` 22,563 行(script 11,356 / template 2,784 / style 8,395)、`main.py` 2,580 行、`RouteSpec` 166 条、`endpoints.ts` 143 键、`_string_list` 17 处、`core/queue_manager.py` 112 行、前端 39,254 行。 |
| **`文件:行号` 是否编造**(抽验 14 处高危引用) | ✅ **全部命中**。逐条 Read 确认:`main.py:104-106`(BRIDGE_PERMISSIONS) · `main.py:2337`(赋权) · `core/runtime_paths.py:43-45`(绝对路径放行) · `core/storage.py:51-53`(`will_overwrite` 未被使用) · `profile_repository.py:46`(字面量 `%`) · `job_repository.py:150`(`ORDER BY created_at DESC`) · `single_flow.py:61`(只读 `aspect_ratio`) · `chat_media_import_service.py:33-36`(裸 `read_bytes`) · `App.vue:11146`(`displayMediaUrl`) · `App.vue:997`(`galleryImages`) · `App.vue:4576`(`slice(-1)`) · `workflow-lock-state.ts:12`(`sealed_at`) · `routes/common.py:12-16`(吞异常) · `settings_service.py:614`(明文快照)。泄露文件的 5 处凭据行号(:25/:45/:57-61/:73/:75-76)亦经字段名核对无误。 |
| **是否有维度被漏收**(回扫 `_raw.json` 全部 214 条) | 发现 **17 条**未被任何主报告覆盖,已补录:10 条集中在 A1/A2/A3/A4/A5/C4(补入 02 §6.1)、4 条耦合项(补入 03 附二)、4 条卫生项(补入 04 §3.5)、3 条并入 05 的阶段 1/2 任务(1-5b 归属校验语义统一、2-8 并发限流空操作、2-12b 通知链路静默失败)。**106 条 `bug/security/perf` 发现经逐条比对,全部在 02 报告中有对应条目**(含复核修正后的定位)。 |
补录中最值得注意的三条:
1. `backend/services/profile_service.py:160` —— `ProfileService._require_owner` **不认管理员权限**,与 `ResourceAccessService._can_access` 语义相反。做 IDOR 改造(05 阶段 1 的 1-3~1-5)前必须先统一,否则矛盾会被扩散到五条链路。
2. `backend/services/worker_service.py:400` —— `_BoundedWorkerHandler` 的并发限流**在生产配置下是空操作**,且限流点位于「认领之后」,与 05 的 2-8 背压项同源。
3. `backend/services/workflow_round_worker_runtime.py:262` —— 主动通知的三个失败出口**一行日志都没有**,用户收不到轮次完成通知且运维无从得知。
---
## 阅读顺序建议
- **决策者 / 只有 10 分钟** → [05-优化路线图.md](05-优化路线图.md) 的「§1 一页纸结论」+「§5 投入产出建议」。
- **今天就要动手** → [02-BUG清单.md](02-BUG清单.md) 的「§0 立即处置」(凭据轮换清单 + 3 个低成本断链点)。
- **要理解为什么这样改** → [03-耦合分析.md](03-耦合分析.md) 的「§1.4 装配分散」+「§2.2 业务逻辑重复实现」。
- **排期与工作量** → [05-优化路线图.md](05-优化路线图.md) 的「§3 分阶段路线图」。
- **质疑某条结论** → 先看 [findings/_复核结论.md](findings/_复核结论.md) 是否已被推翻,再看 `findings/` 下对应维度的原始证据。
## 使用本报告的三条注意
1. **严重度以主报告为准,不要用 `findings/` 里的原判**。原始发现未经复核校准,误报率实测 29%。
2. **动手前先写一个能复现的测试**。并发类与性能类结论以静态分析为主,未做压测与浏览器实跑(局限声明见 05 §6)。
3. **行号会漂移**。本报告基于 `8040a1b`,定位前请 `git blame` 复核。