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 设置页完成配置:
- 添加一个适配器,填写名称、兼容 API 根地址和 API Key 来源。
- 点击“保存并测试”,让测试读取已保存配置,探测模型列表和图片生成 endpoint。
- 为图片生成、提示词规划/扩写、素材识别、视觉质检、生成式交叉审查、高清修复等用途分别选择路由。
- 生成式交叉审查至少需要一个与主候选不同的可用图片生成模型;视觉质检使用视觉模型,两者不能混作一个配置。
模型输入既可从已探测列表选择,也可手工填写 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/ 骨架。
从旧版本升级
- 备份插件数据目录和当前插件源码目录。
- 停止插件或 AstrBot 容器,避免覆盖时仍有任务写文件。
- 把新包解压到临时目录,确认
main.py位于临时目录根部。 - 用新包的运行时白名单覆盖插件源码;不要删除或覆盖
data/plugin_data/astrbot_plugin_imagestudio/。 - 启动 AstrBot。插件会在注册 API 前按顺序执行
database/migrations/*.sql,并在schema_migrations记录版本。迁移设计为幂等执行;已记录但缺失声明表时会重新校验并修复。 - 检查日志,再打开插件页面验证自动连接、角色列表、工作流、队列和设置。
升级会保留旧工作流、旧图片和旧节点 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/
建议流程:
- 将 ZIP 上传到 NAS 临时目录并解压到独立 staging 目录。
- 核对 staging 根目录的
main.py、metadata.yaml、pages/imagestudio/index.html。 - 备份宿主的
plugin_data/astrbot_plugin_imagestudio/。 - 只把运行时白名单同步到
plugins/astrbot_plugin_imagestudio/。如使用rsync --delete,必须把目标解析为准确的插件源码目录,并显式排除任何误放在源码目录内的.env*与运行数据;禁止对<astrbot-data>或plugin_data根目录执行--delete。 - 通过 SSH 在 NAS 上重启对应 AstrBot Docker 容器,不使用浏览器安装器重复覆盖。
- 检查启动日志中是否存在
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。