11 KiB
11 KiB
ImageStudio 代码与功能审计(2026-07-10)
审计范围
本轮审计覆盖仓库中的 Python、TypeScript、Vue、HTML、YAML、JSON、SQL 迁移、脚本、测试和全部 Markdown 文档,重点核对:
- AstrBot 插件生命周期、Plugin Page、Web API、Bridge 与持久化目录兼容性。
- 后端路由、服务、数据库外键、配置写入、Provider 调用、任务状态机和错误传播。
- 前端功能入口、API 契约、真实数据与示例数据边界、按钮行为和生产构建产物。
- 重复代码、可复用解析逻辑、生产 mock/fallback、SSRF、身份伪造和 owner 边界。
AstrBot 官方运行模式核对
官方资料:
核对结论:
- 插件继承
Star;AstrBot 在启用时调用initialize(),在停用或重载时调用terminate()。 pages/<page_name>/index.html会被自动发现,并在受限 iframe 中运行;页面通过window.AstrBotPluginPage调用后端。- 后端使用
context.register_web_api(route, handler, methods, desc)注册,动态路径语法为<name>和<path:name>。ImageStudio 的/<plugin>/<path:endpoint>catch-all 与官方语法一致。 - Page 端传相对 endpoint;Dashboard 转发到
/api/v1/plugins/extensions/<plugin>/<endpoint>。v4.25 legacy 前缀仍兼容/api/plug/<plugin>/<endpoint>。 - 当前官方 Bridge 的 JSON 操作以 GET/POST 为主;ImageStudio 对旧 Bridge 的 PUT/PATCH/DELETE 使用 POST method-override 信封兼容。
- 官方
PluginRequest提供username、client_host、query、json()和path_params等字段,不提供可用于细粒度角色授权的完整用户角色模型。 get_astrbot_plugin_data_path()返回 AstrBot 的data/plugin_data根目录,插件仍需追加自己的插件名。因此运行数据正确位置是data/plugin_data/astrbot_plugin_imagestudio/。
已修复问题
AstrBot 接入与安全
- Bridge 不再信任
x-username、x-user-id或x-forwarded-for作为身份来源。 - 用显式能力替代 wildcard 权限;任务重试同时要求
can_write与can_retry_tasks。 - Bridge 同步业务分发移到工作线程,长时间 Provider 请求不再阻塞 AstrBot 事件循环。
- Bridge 路由按方法只注册一个 catch-all,兼容官方 GET/POST 调用、POST method-override 信封和旧版 Quart 请求。
- 媒体下载优先使用 AstrBot
file_response,避免生产请求整文件 base64 复制。 - Provider 限制 HTTP(S)、响应大小、图片魔数和同源重定向,并拒绝非显式允许的私网目标。
- Provider 错误正文中的 Bearer token、API key 与常见密钥字段会在记录和返回前脱敏。
持久化与配置
- 运行数据库、媒体和可写配置映射到 AstrBot 插件数据目录。
- SQLite 强制启用外键。
- 配置、审查策略和集成 token 使用同目录临时文件、原子替换和进程内路径锁。
- YAML 标量解析修复引号内
#和字符串类型漂移。 - 数据库配置切换会先初始化并验证目标数据库,验证失败时不会切换运行连接。
- AstrBot runtime override 管理的 DSN、数据库密码与 Provider API key 不会因设置保存、回滚或快照操作写入 YAML;掩码后的 diff 也不会误报变化。
- 生图和 Vision Provider 配置均可从 AstrBot 配置自动 bootstrap 到运行数据库,fresh install 不再缺少模型路由。
- 配置路由使用稳定 ID;模型变化或配置清空会停用旧路由,Vision 配置也不会覆盖生图 Provider。
Provider、媒体与生成上下文
- Provider 未配置或调用失败时,任务和节点进入失败状态;生产模式不再把 mock 图片当成功结果。
- 默认模型、档案默认模型、Prompt Expansion 和 Cost Guard 已接入生成请求。
- 上游节点图片、草稿参考图、stage input、显式参考图以及已确认素材都会真正传入 Provider,不再只保留 URI 元数据。
storage://图片会校验归属、数量、单图/总大小和文件魔数,再转换为带正确 MIME 的 data URL。- 大型 inline data URL 不再持久化到任务数据库;若旧任务使用 inline 参考图,重试时必须提供替代参考图,不能静默丢失生成条件。
negative_prompt已贯通到兼容 Provider。官方 OpenAI/Azure OpenAI 默认关闭该未知字段,其他路由可通过 capabilities/settings 显式开关。- PNG、JPEG、GIF 与 WebP 按真实魔数保存,并保持文件后缀、元数据 MIME、媒体响应与实际字节一致。
- Provider JSON 响应上限按请求图片数量和 Base64 开销动态计算,总硬上限为 128 MiB。
任务、重试、取消与工作流
- 工作流初始状态执行枚举校验;非法状态不会落库。
- 未完成的生成节点会让工作流审查失败。
- 历史快照在写入前校验图片、工作流和节点归属,避免外键异常泄漏为未知错误。
- 虚拟单图节点允许连续发起生成,不会在第一次完成后永久锁死。
- node retry 与 job retry 都会执行真实、受控的同步重试,并生成新的幂等键、lineage、替代任务记录与有上限的 DLQ 记录。
- job retry 预检失败会恢复原任务和节点状态;并发重试使用 CAS,只有一个请求能取得执行权。
- task 运行、成功、失败和取消均使用比较并交换更新,陈旧请求不能覆盖终态。
- workflow 取消会级联取消其活跃 task/node;若 Provider 已在远程执行,返回结果会被拒绝提交,暂存图片元数据、原图和缩略图会清理。
- 同一 Provider 请求生成多张图时,usage 按 task 聚合,不再按每张输出图重复累计。
素材、素材包与 Vision
- Vision 识别会读取真实
storage://图片,并校验文件大小、扩展名、MIME 和魔数后再发送给 Provider。 - Vision 未配置、调用失败或返回无效时不会回退 mock;素材保持
pending_recognition,且未成功识别的素材不能 confirm。 - 素材包在首条记录写入前对清单、文件、类型、重复 material ID 和所有条目执行确定性预检。
- 素材包
styles当前明确报告为不支持,不再假报成功导入。 - confirmed 素材可由前端导入角色衣橱;未确认素材会被后端拒绝。
前端与代码精简
- Plugin Page 删除重复轻量导航,直接复用完整 Workbench。
- API client 统一解包 AstrBot 与 ImageStudio 响应,并兼容旧 Bridge method override。
- 修复工作流详情解构、角色工作流后端 ID 同步、并发创建去重和素材选择假 ID。
- mock、provider error、fallback 和 degraded 图片不能被采纳、归档或作为后续参考图。
- 快速角色素材选择只提交真实、已确认的后端素材;示例素材只在预览/错误模式显示。
- completed 节点可以持久化切换候选图,selected 节点仍保持锁定;成本面板使用真实 Provider usage。
- 新增
MaterialOperationDialog.vue,提供已有storage://素材登记、素材包 dry-run/apply 和 confirmed 素材导入衣橱入口。 - 导航、指标卡、状态卡、空态、图片预览、素材分类和素材详情已拆为独立组件;外部角色卡解析已拆为纯函数 feature 模块。
- 状态、时间、容量、成本、集合去重和
storage://校验已迁入共享工具,素材/队列/性能页的重复指标模板已合并。 - 搜索支持 Ctrl/Cmd+K、方向键和 Enter;移动导航显示标签,弹窗补齐焦点管理、Escape、safe-area 与
100dvh。 - 真实后端无模型或空素材库时不再伪装成示例数据;示例模型/素材只在明确的预览或错误模式显示。
- node retry 前端只发送一次请求;模型 discovery 文案明确为 metadata-only。
- 13 个 route 文件的重复字符串、数字和布尔参数解析已合并到
backend/routes/params.py。 - 生成参考图收集、任务重试、Provider bootstrap、配置安全写入、图片格式识别与远程抓取分别拆入独立服务/核心模块,减少路由与主流程中的重复实现。
当前发布边界与延期项
以下项目不应被误解为已完成:
- 完整多租户 owner 链:角色档案已按身份隔离,但 workflow、node、image、job、wardrobe、Dashboard 和媒体仍未完成统一祖先链授权。当前产品边界是可信 AstrBot WebUI 管理员工作台。
- 可信成本上限:成本接口可以聚合 Provider usage,但服务端尚无可信价格表;调用方提供的
unit_prices只能用于估算,不能作为强财务控制。 - 持久后台 Worker:生产重试采用受控同步重试闭环;尚未引入跨进程持久 worker、租约和原子 claim 调度器。进程被强制终止时,极端情况下可能遗留
retrying状态,需要恢复任务或后续巡检。 - Provider 物理中止:远程 HTTP 请求一旦发出无法可靠撤回;取消操作保证结果不提交并清理本地暂存结果,但不能保证上游 Provider 停止计费或计算。
- 前端进一步拆分:已抽出导航、指标/状态原语、图片预览、素材弹窗、角色卡解析及共享工具,但完整
App.vueWorkbench 仍有约 18,138 行,后续应继续拆分工作流 store/actions、通知和异步资源 composable。 - 模型 discovery 语义:
api-discovery/probe-*当前只登记并校验能力元数据,不执行外部网络探测。真实可用性由配置后的 Provider 请求验证;UI 和文档不得把 metadata-only 操作描述为在线探测成功。 - 素材包事务边界:导入前已有完整、确定性的全包预检,但多条素材记录仍不是单一数据库事务;若底层数据库在写入阶段发生异常,可能需要人工处理已写入的前缀记录。
最终验证
最终交付前已执行:
python -m compileall -q adapters backend core database engines scripts tests main.py
cd frontend
npm.cmd run typecheck
npm.cmd run build:plugin
npm.cmd run build:web
结果:
- 全量 Python:共 359 项,结果 OK,其中 1 项按环境条件跳过。
- 高风险组合回归:170 项全部通过。
compileall:通过。- 非 UI smoke:通过,111 条路由/handler 注册及调用健康。
- PostgreSQL smoke
--dry-run:通过。 git diff --check:通过;仅报告工作区 LF 将转 CRLF 的提示,无空白错误。- 前端
typecheck、build:plugin、build:web:全部通过。 - 浏览器 UI smoke:桌面与 390×844 移动端渲染正常;导航固定、移动标签、Ctrl/Cmd+K 搜索、队列 tab、明暗主题和图片缩放弹窗通过,控制台无应用 error/warn。
最终构建产物:
pages/imagestudio/assets/index-CF6dVfCE.jspages/imagestudio/assets/index-D4NekmM3.cssweb/assets/index-djgvYVE7.jsweb/assets/index-VBJk7aNa.css
旧 hash 产物已由构建流程移除。