astrbot_plugin_imagestudio/INSTALL.md

12 KiB

安装、升级与发布包边界

ImageStudio 是 AstrBot 插件,不是独立 Web 服务。本文件同时说明普通安装、旧版本升级、Docker/NAS 手工覆盖和发布包安全边界。

兼容性

  • AstrBot:>= 4.25.0,<5。
  • Python:跟随对应 AstrBot 发行版。
  • 平台:Windows、Linux、macOS 和 Docker,以 AstrBot 本身支持范围为准。
  • 数据库:SQLite 默认可用;PostgreSQL 需要额外驱动。

使用 ZIP 安装

AstrBot 插件安装器接受 ZIP 时,压缩包根目录必须直接包含 main.py 和 metadata.yaml,不能再套一层版本目录。解压后的目标目录名应为:

data/plugins/astrbot_plugin_imagestudio/

最小运行时清单为:

main.py
__init__.py
metadata.yaml
config.yaml
_conf_schema.json
requirements.txt
adapters/
assets_builtin/
backend/
core/
database/
engines/
pages/imagestudio/
web/

发布包还可以包含 README.md、INSTALL.md、CHANGELOG.md 和仅含 .gitkeep 的 data/ 空目录骨架。pages/imagestudio/ 是 AstrBot 正式插件页面;web/ 是兼容构建产物,不能代替宿主注册的插件页面。

安装后重启或重载插件。AstrBot 会发现 main.py 中的 Star 类,依次执行插件初始化、数据库迁移、API 注册和后台 Worker 启动。

首次打开与连接

从 AstrBot 的插件管理页面打开 ImageStudio。插件页面使用相对 bridge endpoint,例如:

ui/bootstrap
settings/current
workflows/<workflow_id>

兼容路由前缀如下:

# AstrBot v4.25 legacy bridge
/api/plug/astrbot_plugin_imagestudio/<endpoint>

# 当前直接 API
/api/v1/plugins/extensions/astrbot_plugin_imagestudio/<endpoint>

window.AstrBotPluginPage.apiGet("ui/bootstrap") 只传相对 endpoint;只有直接 HTTP 请求才拼完整 /api/v1/plugins/extensions/... 前缀。页面会异步初始化并自动重试后端连接;如果持续停在连接中,应先查看 AstrBot 容器日志中的插件导入、迁移和 bridge 注册错误,而不是反复点击安装。

配置模型适配器

推荐在 ImageStudio 设置页完成配置:

  1. 添加一个适配器,填写名称、兼容 API 根地址和 API Key 来源。
  2. 点击“保存并测试”,让测试读取已保存配置,探测模型列表和图片生成 endpoint。
  3. 为图片生成、提示词规划/扩写、素材识别、视觉质检、生成式交叉审查、高清修复等用途分别选择路由。
  4. 生成式交叉审查至少需要一个与主候选不同的可用图片生成模型;视觉质检使用视觉模型,两者不能混作一个配置。

模型输入既可从已探测列表选择,也可手工填写 Provider 的真实模型 ID。工作流节点默认继承该阶段实际路由;只有显式选择覆盖项时,前端才发送 model_route。

配置文件引导 Provider

也可以通过 AstrBot 插件配置提供默认图片 Provider。不要把真实 Key 写进仓库;使用环境变量或宿主 secret store:

default_generation_model: image-main
generation_provider_id: imagestudio_default
generation_provider_base_url: https://provider.example.com
generation_provider_image_endpoint: /v1/images/generations
generation_provider_model: provider-model-id
generation_provider_route: image-main
generation_provider_api_key_env_var: IMAGESTUDIO_PROVIDER_API_KEY
generation_provider_timeout_seconds: 180

等价的 config.yaml 结构:

generation:
  default_model: image-main
  provider:
    provider_id: imagestudio_default
    base_url: https://provider.example.com
    image_endpoint: /v1/images/generations
    model_id: provider-model-id
    route_name: image-main
    api_key_env_var: IMAGESTUDIO_PROVIDER_API_KEY
    timeout_seconds: 180

route_name 是 ImageStudio 内部逻辑路由,model_id 是 Provider 接收的真实模型名。无鉴权的本地 Provider 可以留空 api_key_env_var;其他情况必须在启动 AstrBot 的进程或容器环境中提供对应变量。

素材识别和视觉质检需要支持图片输入的 OpenAI 兼容多模态模型。连接字段留空时可以复用生图 Provider,但 model_id 必须明确配置:

vision:
  default_route: material_vlm
  provider:
    provider_id: ""
    base_url: ""
    vision_endpoint: /v1/chat/completions
    model_id: vision-model-id
    route_name: material_vlm
    api_key_env_var: ""
    timeout_seconds: 180
    enabled: true

若视觉服务使用不同的地址、密钥或超时,建议配置独立 Provider ID,避免覆盖图片 Provider。素材识别会读取并校验真实 storage:// 图片,再临时编码成 data URL 发送给视觉 Provider;data URL 不会写入异步任务、数据库或轮次快照。

没有真实模型时

未配置 Provider 不影响打开页面、迁移数据库、查看已有角色/图片/历史、编辑普通元数据或管理队列。需要模型的动作不会回退到假结果:

  • 图片生成、高清修复无法确认能力时会返回缺少模型能力或 Provider 配置错误;
  • 素材识别失败时保持待识别状态,不会生成可确认的 mock 标签或提示词;
  • 视觉质检和生成式交叉审查缺少路由时会给出可操作错误;
  • 异步任务失败会保留脱敏后的失败类型和重试入口,不会冒充成功图片。

部署验收默认只检查插件加载、迁移、页面连接、只读接口和无成本交互。只有操作者明确允许并确认计费模型后,才应进行真实生成测试。

运行数据与备份

插件持久化数据位于 AstrBot 数据根目录,而不是插件源码目录:

data/plugin_data/astrbot_plugin_imagestudio/

其中包含 SQLite 数据库、图片、缩略图、素材、归档、导出和临时状态。配置中的 data/... 是映射到该插件数据根目录的逻辑路径,不要再次手工拼接 data/plugin_data/astrbot_plugin_imagestudio。

升级前至少备份:

data/plugin_data/astrbot_plugin_imagestudio/

使用 PostgreSQL 时还要单独备份对应数据库。不要把运行数据库或图片复制回源码仓库的 data/ 骨架。

从旧版本升级

  1. 备份插件数据目录和当前插件源码目录。
  2. 停止插件或 AstrBot 容器,避免覆盖时仍有任务写文件。
  3. 把新包解压到临时目录,确认 main.py 位于临时目录根部。
  4. 用新包的运行时白名单覆盖插件源码;不要删除或覆盖 data/plugin_data/astrbot_plugin_imagestudio/。
  5. 启动 AstrBot。插件会在注册 API 前按顺序执行 database/migrations/*.sql,并在 schema_migrations 记录版本。迁移设计为幂等执行;已记录但缺失声明表时会重新校验并修复。
  6. 检查日志,再打开插件页面验证自动连接、角色列表、工作流、队列和设置。

升级会保留旧工作流、旧图片和旧节点 ID。详细角色旧 key 会惰性映射到新 11 节点目录,缺失的下半身节点只做增量补充,不重建整条工作流。旧 final_archive_* 档案仍可只读查看。

不要在未恢复数据库备份的情况下直接降级插件源码;新版本迁移后的数据库不保证被旧代码完整理解。如果出现 no such table,优先确认是否混用了新旧源码、数据库目录权限是否正确、迁移日志是否完整,不要先删除数据库。

Docker / NAS 手工覆盖

NAS 上通常把宿主 .../data 挂载到容器 /AstrBot/data。对应路径关系示例:

# 宿主机
<astrbot-data>/plugins/astrbot_plugin_imagestudio/
<astrbot-data>/plugin_data/astrbot_plugin_imagestudio/

# 容器内
/AstrBot/data/plugins/astrbot_plugin_imagestudio/
/AstrBot/data/plugin_data/astrbot_plugin_imagestudio/

建议流程:

  1. 将 ZIP 上传到 NAS 临时目录并解压到独立 staging 目录。
  2. 核对 staging 根目录的 main.py、metadata.yaml、pages/imagestudio/index.html。
  3. 备份宿主的 plugin_data/astrbot_plugin_imagestudio/。
  4. 只把运行时白名单同步到 plugins/astrbot_plugin_imagestudio/。如使用 rsync --delete,必须把目标解析为准确的插件源码目录,并显式排除任何误放在源码目录内的 .env* 与运行数据;禁止对 <astrbot-data> 或 plugin_data 根目录执行 --delete。
  5. 通过 SSH 在 NAS 上重启对应 AstrBot Docker 容器,不使用浏览器安装器重复覆盖。
  6. 检查启动日志中是否存在 ImportError、No module named、no such table、迁移失败或 bridge 注册失败,再进行浏览器验收。

源码覆盖和容器重启是两个独立步骤;只替换文件不会让已运行的 Python 进程自动载入新版本。

PostgreSQL(可选)

选择 backend: postgresql,或在 backend: auto 下启用并完整配置 PostgreSQL:

database:
  backend: auto
  postgresql:
    enabled: true
    host: 127.0.0.1
    port: 5432
    database: imagestudio
    user: imagestudio
    password: ""

SQLite 不需要第三方数据库驱动。使用 PostgreSQL 时任选一种兼容驱动安装到 AstrBot Python 环境:

python -m pip install "psycopg[binary]>=3.1"
# 或
python -m pip install "psycopg2-binary>=2.9"

本地无成本验证

python -m compileall adapters backend core database engines main.py
python -m pytest -q --basetemp=.pytest_tmp_release
npm.cmd --prefix frontend run typecheck
npm.cmd --prefix frontend run build:plugin
npm.cmd --prefix frontend run build:web

测试完成后清理 .pytest_tmp*、.pytest_cache、__pycache__ 和未使用构建缓存。不得删除真实 data/plugin_data、用户素材、生成图片或配置。

发布包白名单

不要使用无路径限制的 git archive HEAD,因为仓库还跟踪测试、审计文档、前端源码和历史 release 文件。正式运行时 ZIP 只归档下列路径:

main.py
metadata.yaml
config.yaml
_conf_schema.json
requirements.txt
__init__.py
README.md
INSTALL.md
CHANGELOG.md
adapters/
assets_builtin/
backend/
core/
database/
engines/
pages/
web/
data/          # 仅跟踪的 .gitkeep 空目录骨架

PowerShell 示例:

git archive --format=zip --output=release/astrbot_plugin_imagestudio.zip HEAD -- `
  main.py metadata.yaml config.yaml _conf_schema.json requirements.txt __init__.py `
  README.md INSTALL.md CHANGELOG.md `
  adapters assets_builtin backend core database engines pages web data

以下内容必须排除:

  • .git/、.agents/、.codex/、.env* 和所有凭据文件;
  • tests/、docs/、frontend/、node_modules/ 和开发说明/审计源文件;
  • release/ 中的旧包、.pytest_cache/、.pytest_tmp*/、__pycache__/、日志和覆盖率缓存;
  • data/plugin_data/、数据库、真实图片、素材、缩略图、归档、导出和临时文件。

打包前只检查文件名和 Git 跟踪状态即可,不要把 .env* 内容输出到终端:

git ls-files -- '.env' '.env.*' '**/.env' '**/.env.*'
git ls-files -- 'data/**'
git status --short --ignored -- '.env*'

预览白名单归档内容而不生成 ZIP:

git archive --format=tar HEAD -- `
  main.py metadata.yaml config.yaml _conf_schema.json requirements.txt __init__.py `
  README.md INSTALL.md CHANGELOG.md `
  adapters assets_builtin backend core database engines pages web data |
  tar -tf -

最终应确认归档根目录存在 main.py,且清单中没有 .env*、真实 data、测试、前端工程、缓存或历史安装包。

密钥安全

  • 不提交 .env*、API Key、DSN、数据库密码、SSH 私钥或集成 token。
  • 日志和错误响应只保留脱敏后的错误类型,不回显 Authorization Header 或密钥。
  • 如果凭据曾出现在本机交接文件、终端输出或历史包中,应在发布前轮换;仅仅把文件加入 .gitignore 不能让已泄露凭据恢复安全。
  • 私伴集成 token 的轮换 endpoint 是 POST integrations/private-companion/token/rotate;新 token 只展示一次,配置仅保存 salt 和 hash。