astrbot_plugin_imagestudio/INSTALL.md

296 行
12 KiB
Markdown

# 安装、升级与发布包边界
2026-07-06 04:33:14 +08:00
ImageStudio 是 AstrBot 插件,不是独立 Web 服务。本文件同时说明普通安装、旧版本升级、Docker/NAS 手工覆盖和发布包安全边界。
2026-07-06 04:33:14 +08:00
## 兼容性
2026-07-06 04:33:14 +08:00
- AstrBot:`>= 4.25.0,<5`。
- Python:跟随对应 AstrBot 发行版。
- 平台:Windows、Linux、macOS 和 Docker,以 AstrBot 本身支持范围为准。
- 数据库:SQLite 默认可用;PostgreSQL 需要额外驱动。
2026-07-06 04:33:14 +08:00
## 使用 ZIP 安装
AstrBot 插件安装器接受 ZIP 时,压缩包根目录必须直接包含 `main.py` 和 `metadata.yaml`,不能再套一层版本目录。解压后的目标目录名应为:
```text
data/plugins/astrbot_plugin_imagestudio/
```
最小运行时清单为:
```text
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,例如:
2026-07-06 04:33:14 +08:00
```text
ui/bootstrap
settings/current
workflows/<workflow_id>
2026-07-06 04:33:14 +08:00
```
兼容路由前缀如下:
2026-07-06 04:33:14 +08:00
```text
# AstrBot v4.25 legacy bridge
/api/plug/astrbot_plugin_imagestudio/<endpoint>
# 当前直接 API
/api/v1/plugins/extensions/astrbot_plugin_imagestudio/<endpoint>
2026-07-06 04:33:14 +08:00
```
`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`。
2026-07-06 04:33:14 +08:00
### 配置文件引导 Provider
也可以通过 AstrBot 插件配置提供默认图片 Provider。不要把真实 Key 写进仓库;使用环境变量或宿主 secret store:
```text
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` 结构:
```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` 必须明确配置:
```yaml
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 数据根目录,而不是插件源码目录:
```text
data/plugin_data/astrbot_plugin_imagestudio/
```
其中包含 SQLite 数据库、图片、缩略图、素材、归档、导出和临时状态。配置中的 `data/...` 是映射到该插件数据根目录的逻辑路径,不要再次手工拼接 `data/plugin_data/astrbot_plugin_imagestudio`。
2026-07-06 04:33:14 +08:00
升级前至少备份:
```text
data/plugin_data/astrbot_plugin_imagestudio/
2026-07-06 04:33:14 +08:00
```
使用 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`。对应路径关系示例:
```text
# 宿主机
<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:
2026-07-06 04:33:14 +08:00
```yaml
database:
backend: auto
postgresql:
enabled: true
host: 127.0.0.1
port: 5432
database: imagestudio
user: imagestudio
password: ""
```
SQLite 不需要第三方数据库驱动。使用 PostgreSQL 时任选一种兼容驱动安装到 AstrBot Python 环境:
```powershell
python -m pip install "psycopg[binary]>=3.1"
# 或
python -m pip install "psycopg2-binary>=2.9"
```
2026-07-06 04:33:14 +08:00
## 本地无成本验证
```powershell
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`、用户素材、生成图片或配置。
## 发布包白名单
2026-07-06 04:33:14 +08:00
不要使用无路径限制的 `git archive HEAD`,因为仓库还跟踪测试、审计文档、前端源码和历史 release 文件。正式运行时 ZIP 只归档下列路径:
2026-07-06 04:33:14 +08:00
```text
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 空目录骨架
2026-07-06 04:33:14 +08:00
```
PowerShell 示例:
2026-07-06 04:33:14 +08:00
```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
2026-07-06 04:33:14 +08:00
```
以下内容必须排除:
- `.git/`、`.agents/`、`.codex/`、`.env*` 和所有凭据文件;
- `tests/`、`docs/`、`frontend/`、`node_modules/` 和开发说明/审计源文件;
- `release/` 中的旧包、`.pytest_cache/`、`.pytest_tmp*/`、`__pycache__/`、日志和覆盖率缓存;
- `data/plugin_data/`、数据库、真实图片、素材、缩略图、归档、导出和临时文件。
打包前只检查文件名和 Git 跟踪状态即可,不要把 `.env*` 内容输出到终端:
2026-07-06 04:33:14 +08:00
```powershell
git ls-files -- '.env' '.env.*' '**/.env' '**/.env.*'
git ls-files -- 'data/**'
git status --short --ignored -- '.env*'
2026-07-06 04:33:14 +08:00
```
预览白名单归档内容而不生成 ZIP:
2026-07-06 04:33:14 +08:00
```powershell
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 -
2026-07-06 04:33:14 +08:00
```
最终应确认归档根目录存在 `main.py`,且清单中没有 `.env*`、真实 `data`、测试、前端工程、缓存或历史安装包。
## 密钥安全
2026-07-06 04:33:14 +08:00
- 不提交 `.env*`、API Key、DSN、数据库密码、SSH 私钥或集成 token。
- 日志和错误响应只保留脱敏后的错误类型,不回显 Authorization Header 或密钥。
- 如果凭据曾出现在本机交接文件、终端输出或历史包中,应在发布前轮换;仅仅把文件加入 `.gitignore` 不能让已泄露凭据恢复安全。
- 私伴集成 token 的轮换 endpoint 是 `POST integrations/private-companion/token/rotate`;新 token 只展示一次,配置仅保存 salt 和 hash。