11 KiB
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 全测已通过。
推荐实施队列
- P0:实现维护模式、原子恢复和失败回滚。
- P0:修复 worker 可取消停止与热重载双实例竞态。
- P1:收紧 bridge 权限和付费模型端点权限/配额。
- P1:修正角色 archive/delete 语义并迁移已有状态。
- P1:为备份增加容量、流式校验和 zip bomb 防护。
- P2:拆分
App.vue状态域和 CSS,同时保持插件 iframe 一级页面稳定。 - P2:拆分进阶素材页并统一下载、媒体解析、任务状态等重复逻辑。
- 发布门禁:全测、前端契约、typecheck、双构建、
git diff --check、热重载并发测试、备份恢复故障注入测试。
可立即发布的范围
- 可用于受信任管理员的内部验证环境。
- 不应在修复 P0 前启用“在线恢复备份”。
- 不应在未明确管理员边界前作为多用户共享 Web 服务发布。
- 当前角色文档导入增量本身已有 5 项后端测试,前端类型/契约/构建通过,但其模型成本权限仍需收紧。