146 行
11 KiB
Markdown
146 行
11 KiB
Markdown
# 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 官方运行模式核对
|
||
|
||
官方资料:
|
||
|
||
- [插件开发指南](https://docs.astrbot.app/dev/star/plugin-new.html)
|
||
- [插件 Pages](https://docs.astrbot.app/dev/star/guides/plugin-pages.html)
|
||
- [插件配置](https://docs.astrbot.app/dev/star/guides/plugin-config.html)
|
||
- [插件存储](https://docs.astrbot.app/dev/star/guides/storage.html)
|
||
- [AstrBot 官方仓库](https://github.com/AstrBotDevs/AstrBot)
|
||
|
||
核对结论:
|
||
|
||
1. 插件继承 `Star`;AstrBot 在启用时调用 `initialize()`,在停用或重载时调用 `terminate()`。
|
||
2. `pages/<page_name>/index.html` 会被自动发现,并在受限 iframe 中运行;页面通过 `window.AstrBotPluginPage` 调用后端。
|
||
3. 后端使用 `context.register_web_api(route, handler, methods, desc)` 注册,动态路径语法为 `<name>` 和 `<path:name>`。ImageStudio 的 `/<plugin>/<path:endpoint>` catch-all 与官方语法一致。
|
||
4. Page 端传相对 endpoint;Dashboard 转发到 `/api/v1/plugins/extensions/<plugin>/<endpoint>`。v4.25 legacy 前缀仍兼容 `/api/plug/<plugin>/<endpoint>`。
|
||
5. 当前官方 Bridge 的 JSON 操作以 GET/POST 为主;ImageStudio 对旧 Bridge 的 PUT/PATCH/DELETE 使用 POST method-override 信封兼容。
|
||
6. 官方 `PluginRequest` 提供 `username`、`client_host`、`query`、`json()` 和 `path_params` 等字段,不提供可用于细粒度角色授权的完整用户角色模型。
|
||
7. `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、配置安全写入、图片格式识别与远程抓取分别拆入独立服务/核心模块,减少路由与主流程中的重复实现。
|
||
|
||
## 当前发布边界与延期项
|
||
|
||
以下项目不应被误解为已完成:
|
||
|
||
1. **完整多租户 owner 链**:角色档案已按身份隔离,但 workflow、node、image、job、wardrobe、Dashboard 和媒体仍未完成统一祖先链授权。当前产品边界是可信 AstrBot WebUI 管理员工作台。
|
||
2. **可信成本上限**:成本接口可以聚合 Provider usage,但服务端尚无可信价格表;调用方提供的 `unit_prices` 只能用于估算,不能作为强财务控制。
|
||
3. **持久后台 Worker**:生产重试采用受控同步重试闭环;尚未引入跨进程持久 worker、租约和原子 claim 调度器。进程被强制终止时,极端情况下可能遗留 `retrying` 状态,需要恢复任务或后续巡检。
|
||
4. **Provider 物理中止**:远程 HTTP 请求一旦发出无法可靠撤回;取消操作保证结果不提交并清理本地暂存结果,但不能保证上游 Provider 停止计费或计算。
|
||
5. **前端进一步拆分**:已抽出导航、指标/状态原语、图片预览、素材弹窗、角色卡解析及共享工具,但完整 `App.vue` Workbench 仍有约 18,138 行,后续应继续拆分工作流 store/actions、通知和异步资源 composable。
|
||
6. **模型 discovery 语义**:`api-discovery/probe-*` 当前只登记并校验能力元数据,不执行外部网络探测。真实可用性由配置后的 Provider 请求验证;UI 和文档不得把 metadata-only 操作描述为在线探测成功。
|
||
7. **素材包事务边界**:导入前已有完整、确定性的全包预检,但多条素材记录仍不是单一数据库事务;若底层数据库在写入阶段发生异常,可能需要人工处理已写入的前缀记录。
|
||
|
||
## 最终验证
|
||
|
||
最终交付前已执行:
|
||
|
||
```powershell
|
||
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.js`
|
||
- `pages/imagestudio/assets/index-D4NekmM3.css`
|
||
- `web/assets/index-djgvYVE7.js`
|
||
- `web/assets/index-VBJk7aNa.css`
|
||
|
||
旧 hash 产物已由构建流程移除。
|