astrbot_plugin_imagestudio/docs/final-release-audit-2026-07-22.md

11 KiB

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 项后端测试,前端类型/契约/构建通过,但其模型成本权限仍需收紧。