# ImageStudio 发布前最终代码审计(2026-07-22) ## 结论 当前分支的功能测试、前端类型检查和生产构建均通过,但不建议直接发布。发布前至少应关闭两个灾难级风险:在线恢复备份的非原子覆盖,以及插件终止后仍可能存活的后台 worker。其余权限边界、档案归档语义和前端巨型组件问题建议按下方队列处理。 ## 验证证据 - 后端:`python -m pytest -q`,260 passed,178.03s。 - 前端:`npm.cmd run typecheck` 通过。 - 前端契约:`npm.cmd run test:contracts`,26 passed。 - 生产构建:`npm.cmd run build` 通过。 - 构建警告:插件主 JS 约 645.14 kB,独立 Web 主 JS 约 643.15 kB;主 CSS 约 288.72 kB。 - Git:当前分支 `codex/character-profile-document-import`,相对 `main` 增加 5 个提交;无未提交源码改动(审计文档和错题本更新除外)。 ## 发布阻断项 ### P0-1 在线备份恢复可能破坏数据库并产生部分恢复 - 位置:`backend/services/data_backup_service.py:118` - 证据:恢复流程先覆盖配置,再用恢复后的配置决定数据库目标;随后使用 `shutil.copy2` 直接覆盖正在运行的 SQLite 文件,并用 `copytree(..., dirs_exist_ok=True)` 合并媒体目录。 - 灾难路径:worker 或请求仍持有数据库连接时覆盖数据库文件,可能导致活动连接继续写旧 inode/句柄、恢复库被后续写入污染、数据库与媒体不一致;任一复制中途失败还会留下“配置已换、数据库或媒体只恢复一部分”的状态。 - 修复要求:恢复必须进入维护模式,停止并确认所有 worker 已退出,拒绝新写请求;全部内容先恢复到同盘 staging,校验和迁移成功后再原子切换;失败时自动回滚配置、数据库和媒体根;恢复成功后重新初始化数据库与 worker。 - 发布门禁:增加“活动任务期间恢复”“复制中途失败回滚”“恢复后数据库一致性”“旧媒体清理策略”测试。 ### P0-2 插件终止可能遗留仍在执行的旧 worker - 位置:`backend/services/worker_service.py:180`、`backend/services/worker_service.py:251`、`main.py:433` - 证据:单 worker 只 `join` 最多 5 秒并返回 `running` 状态;worker pool 逐个等待;`terminate()` 不检查 stop 结果,随后直接清空 runtime 引用。 - 灾难路径:远程模型调用超过 5 秒时,插件卸载/热重载已返回,但旧 daemon 线程仍可继续写任务和数据库;新插件实例会启动新 worker,进阶素材恢复逻辑还会把旧实例正在处理的任务标记失败,形成旧线程回写、重复执行或状态反转。 - 修复要求:worker handler 引入可取消/可中断的 provider timeout;pool 统一广播停止后并行等待;若仍存活则 `terminate()` 明确失败并阻止新实例启动 worker;不要在 `running=True` 时丢弃 runtime 引用。 - 发布门禁:增加阻塞 provider、热重载、双实例、旧 worker 晚到结果不得复活终态任务的并发测试。 ## 高优先级问题 ### P1-1 Web bridge 对任意已认证用户授予全部管理能力 - 位置:`main.py:104`、`main.py:2324`、`adapters/astrbot_adapter.py:171` - 证据:只要请求中存在 `username` 或 `user_id`,上下文就获得写入、配置、素材和重试权限;dispatcher 解析了 route permission,但没有中央执行权限矩阵,只依赖各 handler 自觉校验。 - 风险:若 AstrBot WebUI 存在非管理员账号或插件入口被反向代理给多用户,普通登录用户可修改模型密钥相关配置、恢复备份、删除素材、重试任务。 - 建议:从 AstrBot 请求读取真实角色/能力;无法读取时只授予 read,管理操作要求管理员声明;dispatcher 按 `RouteMatch.permission` 中央 fail-closed,handler 保留二次校验。 - 当前可接受边界:仅限明确声明的“可信 AstrBot 管理员工作台”,不可宣传为多租户或普通用户共享服务。 ### P1-2 只读权限可触发付费 LLM 文档识别 - 位置:`backend/route_registry.py:62`、`backend/route_registry.py:63`、`backend/routes/profile_routes.py:111` - 证据:快速草稿和文档导入被标记为 `read`,handler 仅要求已登录,但服务会调用配置的结构化文本模型;单次文档允许 120000 字符。 - 风险:只读用户可以批量消耗模型额度,且没有此端点专属速率、token 或成本预算限制。 - 建议:改为 `write` 或独立 `can_use_models` 权限;限制请求字节、估算 token、单用户并发和日配额;把 provider timeout、用量和审计记录纳入返回链路。 ### P1-3 “归档角色”实际执行软删除 - 位置:`backend/routes/profile_routes.py:101`、`backend/services/profile_service.py:136` - 证据:`archive_profile()` 直接调用 `delete_profile()`,仓储状态写为 `deleted`,审计动作也是 `delete_profile`。 - 风险:API 名称、UI 预期和数据状态冲突;归档后角色从正常查询消失,未来清理逻辑可能把本应保留的档案当作已删除数据处理。 - 建议:实现独立 `archive_profile`,状态使用 `archived`,读取/恢复规则与 `deleted` 分离;如果产品只支持删除,应移除 archive 路由和文案。 ### P1-4 备份创建与校验缺少磁盘/内存预算 - 位置:`backend/services/data_backup_service.py:36`、`backend/services/data_backup_service.py:198` - 证据:备份限制文件数但不限制创建总字节或剩余磁盘;校验使用 `archive.read(name)` 计算哈希,会把单个条目整体读入内存。 - 风险:大图库可填满数据盘;超大单文件恢复校验可造成进程内存峰值和 OOM。 - 建议:创建前统计总量和可用空间,设置可配置上限;哈希校验使用流式读取;压缩包本身也限制大小和压缩比,防止 zip bomb。 ## 中优先级优化 ### P2-1 `App.vue` 已成为不可控的单体应用 - 位置:`frontend/standalone-web/src/App.vue:1` - 现状:约 22115 行,script 约 11110 行、template 约 2800 行、全局 style 约 8170 行;约 682 个函数/computed/watch 热点。 - 影响:任何页面改动都可能触发整文件冲突、状态串扰和主包膨胀;测试难以覆盖局部状态机。 - 重构顺序:先抽 `useMediaResolver`、`useThemePreferences`、`useNotifications`、`useGenerationJobs`、`useWorkflowWorkspace`;再把主导航页面变成页面容器;最后把全局 CSS 拆为 token/layout/page 三层。 - 约束:插件 iframe 的核心一级页面仍应同步可用,避免重现短时资源令牌导致的分片失效;可以拆源码和 CSS,但对插件构建采用稳定主包或宿主可持久访问的 chunk 策略。 ### P2-2 主包过大且同步页面继续增加 - 位置:`frontend/standalone-web/src/App.vue:15`、`frontend/standalone-web/src/App.vue:39` - 现状:五个一级页面同步引入是 iframe 稳定性修复,但主 JS 已超过 Vite 500 kB 警戒线。 - 建议:把纯工具库、数据字典、非路由弹窗和独立 Web 专用模块拆为稳定 vendor/helper chunk;插件页继续保证一级页面不依赖易过期动态资源。对插件和 standalone 使用不同 chunk 策略,不要一刀切恢复全量懒加载。 ### P2-3 进阶素材页继续扩大,并存在可访问性细节 - 位置:`frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue:113`、`frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue:1392` - 现状:组件约 2024 行;分类按钮容器声明 `tablist`,按钮却没有 `role=tab`、`aria-selected` 和键盘方向键行为。 - 建议:拆出 `AdvancedMaterialFilterBar`、导入队列、验证面板和封存库网格;如果不实现完整 tab 语义,移除 `tablist` 改为普通筛选按钮组。 ### P2-4 前端备份导出逻辑重复 - 位置:`frontend/standalone-web/src/features/settings/BackupPage.vue:16`、`frontend/standalone-web/src/features/settings/SettingsPage.vue:109` - 现状:两处重复请求、Blob、文件名和下载逻辑,文案及文件名前缀已经分叉。 - 建议:抽 `downloadJsonBackup()` 和统一任务状态 composable;设置页只组合 `BackupPage`,避免保留第二套实现。 ### P2-5 路由权限声明和实际校验存在漂移风险 - 位置:`backend/route_registry.py:9`、`adapters/astrbot_adapter.py:171` - 现状:权限矩阵目前主要用于清单展示,实际执行依赖每个路由函数内部的 `require_*`。新增路由漏写校验时会直接暴露。 - 建议:dispatcher 中央执行权限矩阵;增加自动测试,遍历全部路由验证 permission 与实际行为一致;保留 handler 校验作为纵深防御。 ## 低优先级与工程质量 - `main.py` 约 2500 行且包含插件生命周期、聊天命令、桥接适配、配置映射和媒体响应兼容,应拆为 bootstrap、chat plugin、bridge、runtime config 四个模块。 - `generation_service.py`、`advanced_style_set_service.py` 和两个大型 repository 存在 300-500 行函数;优先按“事务命令 + 纯计算 + provider adapter”拆分,不要只做机械切函数。 - 构建生成的两个 `index.html` 带 CRLF/尾随空白,`git diff --check` 不干净;发布流水线应固定换行符并在提交前执行 `git diff --check`。 - `metadata.yaml`、部分旧 Markdown/注释在当前终端显示乱码,需确认文件真实编码统一为 UTF-8,避免市场页描述或日志在目标环境乱码。 - 固定复用同一个 pytest `--basetemp` 在 Windows 上可能与残留进程/旧目录互相影响;CI 使用唯一临时目录并设置全局超时。正常无 basetemp 全测已通过。 ## 推荐实施队列 1. P0:实现维护模式、原子恢复和失败回滚。 2. P0:修复 worker 可取消停止与热重载双实例竞态。 3. P1:收紧 bridge 权限和付费模型端点权限/配额。 4. P1:修正角色 archive/delete 语义并迁移已有状态。 5. P1:为备份增加容量、流式校验和 zip bomb 防护。 6. P2:拆分 `App.vue` 状态域和 CSS,同时保持插件 iframe 一级页面稳定。 7. P2:拆分进阶素材页并统一下载、媒体解析、任务状态等重复逻辑。 8. 发布门禁:全测、前端契约、typecheck、双构建、`git diff --check`、热重载并发测试、备份恢复故障注入测试。 ## 可立即发布的范围 - 可用于受信任管理员的内部验证环境。 - 不应在修复 P0 前启用“在线恢复备份”。 - 不应在未明确管理员边界前作为多用户共享 Web 服务发布。 - 当前角色文档导入增量本身已有 5 项后端测试,前端类型/契约/构建通过,但其模型成本权限仍需收紧。