astrbot_plugin_imagestudio/README.md

4.8 KiB

AstrBot ImageStudio

ImageStudio 是运行在 AstrBot 内的角色资产与生图工作台插件,提供角色档案、工作流、素材库、衣橱、任务队列、日志和模型能力档案等功能。

兼容范围

  • AstrBot:4.25.0 及以上。
  • 运行平台:AstrBot 支持的 Windows、Linux、macOS 和 Docker 环境。
  • 数据库:默认 SQLite;PostgreSQL 为可选后端。
  • 生产运行方式:由 AstrBot 加载插件,不启动独立 FastAPI、Flask 或 Vite 服务。

AstrBot 加载方式

AstrBot 通过 main.py 中的 Star 插件类自动发现 ImageStudio,并管理其生命周期:

  • initialize():读取 AstrBot 配置、初始化持久化数据,并通过 context.register_web_api 注册插件 API。
  • terminate():插件停用或重载时释放运行资源。
  • pages/imagestudio/index.html:由 AstrBot 自动发现为插件页面,无需手工注册静态 /web 入口。

打开界面

安装并重载插件后,从 AstrBot 的插件管理界面打开 ImageStudio。生产页面来自:

pages/imagestudio/index.html

仓库中的 web/ 是独立前端构建/兼容产物。除非宿主显式注册对应静态路由,否则 /api/v1/plugins/extensions/astrbot_plugin_imagestudio/web 不是 AstrBot 保证提供的生产入口。

API 兼容模式

插件页面优先使用 window.AstrBotPluginPage bridge。传给 apiGet、apiPost、apiPut 或 apiDelete 的值必须是相对 endpoint,例如:

ui/bootstrap
dashboard/summary
nodes/<node_id>/generate

ImageStudio 同时兼容两套路由前缀:

  • AstrBot v4.25 legacy bridge:/api/plug/astrbot_plugin_imagestudio/<endpoint>。
  • 当前扩展 API:/api/v1/plugins/extensions/astrbot_plugin_imagestudio/<endpoint>。

bridge 会处理宿主前缀;前端不应把完整 /api/plug/... 或 /api/v1/... 地址传给 bridge。直接 fetch 时才使用当前 /api/v1 前缀。

运行与权限边界

ImageStudio 当前定位为 AstrBot WebUI 内的管理工作台。Bridge 只接受 AstrBot 已认证请求,并为插件页面授予显式的写入、配置、素材和任务重试能力;不会信任浏览器自行提交的用户名、用户 ID 或转发 IP 请求头。

角色档案列表和档案读写已按 AstrBot 登录身份隔离,但工作流、图片、任务、衣橱、Dashboard 和媒体索引尚未形成完整的跨资源多租户授权链。因此当前版本应仅暴露给可信 AstrBot 管理员,不应作为面向多个互不信任用户的公共工作台部署。

配置生图 Provider

生产生图需要一个 OpenAI 兼容的图片生成接口。请在 AstrBot 插件配置中填写至少以下字段:

default_generation_model = image-main
generation_provider_base_url = https://provider.example.com
generation_provider_model = provider-model-id
generation_provider_route = image-main
generation_provider_api_key_env_var = IMAGESTUDIO_PROVIDER_API_KEY

然后在 AstrBot 进程环境中设置对应 API Key。无鉴权的本地 Provider 可以把 generation_provider_api_key_env_var 留空。Provider 未配置完整或调用失败时,生产模式会返回明确错误并把任务/节点标记为失败,不会把 mock 图片伪装成成功结果。完整示例见 INSTALL.md。

素材识别还需配置 vision_provider_model、vision_provider_route 和 vision_provider_endpoint。Vision 的 Provider ID、根地址、API Key 环境变量和超时可留空以复用生图 Provider;如果连接或超时不同但 ID 留空,插件会自动派生独立 Vision Provider ID,避免覆盖生图配置。识别模型必须显式填写。识别链会读取并校验真实 storage:// 图片后发送 data URL,无有效路由或 Provider 失败时不会回退到 mock 结果。完整配置见 INSTALL.md。

主要功能

  • 查看运行概览、队列、最近任务、最近图片和日志。
  • 创建角色档案及角色工作流,按节点生成、重试、审查、采纳和归档图片。
  • 管理素材分类、素材库、衣橱与穿搭匹配。
  • 登记、确认和校验 OpenAI 兼容模型能力档案;当前 discovery endpoint 是安全的元数据检查,不会主动向任意地址发起探测请求。
  • 使用 SQLite 零配置运行,或按需切换 PostgreSQL。

持久化数据

运行数据统一放在 AstrBot 数据目录中:

data/plugin_data/astrbot_plugin_imagestudio/

数据库、图片、缩略图、素材、归档和临时文件都应位于该目录下,不能依赖插件源码目录可写。安装、升级和打包细节见 INSTALL.md,开发约定见 DEVELOPMENT.md。

本轮 AstrBot 兼容、后端、前端、功能闭环与安全审计记录见 docs/code-audit-2026-07-10.md。