# 安装、升级与发布包边界 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`,不能再套一层版本目录。解压后的目标目录名应为: ```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,例如: ```text ui/bootstrap settings/current workflows/ ``` 兼容路由前缀如下: ```text # AstrBot v4.25 legacy bridge /api/plug/astrbot_plugin_imagestudio/ # 当前直接 API /api/v1/plugins/extensions/astrbot_plugin_imagestudio/ ``` `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: ```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`。 升级前至少备份: ```text 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`。对应路径关系示例: ```text # 宿主机 /plugins/astrbot_plugin_imagestudio/ /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*` 与运行数据;禁止对 `` 或 `plugin_data` 根目录执行 `--delete`。 5. 通过 SSH 在 NAS 上重启对应 AstrBot Docker 容器,不使用浏览器安装器重复覆盖。 6. 检查启动日志中是否存在 `ImportError`、`No module named`、`no such table`、迁移失败或 bridge 注册失败,再进行浏览器验收。 源码覆盖和容器重启是两个独立步骤;只替换文件不会让已运行的 Python 进程自动载入新版本。 ## PostgreSQL(可选) 选择 `backend: postgresql`,或在 `backend: auto` 下启用并完整配置 PostgreSQL: ```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" ``` ## 本地无成本验证 ```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`、用户素材、生成图片或配置。 ## 发布包白名单 不要使用无路径限制的 `git archive HEAD`,因为仓库还跟踪测试、审计文档、前端源码和历史 release 文件。正式运行时 ZIP 只归档下列路径: ```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 空目录骨架 ``` PowerShell 示例: ```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*` 内容输出到终端: ```powershell git ls-files -- '.env' '.env.*' '**/.env' '**/.env.*' git ls-files -- 'data/**' git status --short --ignored -- '.env*' ``` 预览白名单归档内容而不生成 ZIP: ```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 - ``` 最终应确认归档根目录存在 `main.py`,且清单中没有 `.env*`、真实 `data`、测试、前端工程、缓存或历史安装包。 ## 密钥安全 - 不提交 `.env*`、API Key、DSN、数据库密码、SSH 私钥或集成 token。 - 日志和错误响应只保留脱敏后的错误类型,不回显 Authorization Header 或密钥。 - 如果凭据曾出现在本机交接文件、终端输出或历史包中,应在发布前轮换;仅仅把文件加入 `.gitignore` 不能让已泄露凭据恢复安全。 - 私伴集成 token 的轮换 endpoint 是 `POST integrations/private-companion/token/rotate`;新 token 只展示一次,配置仅保存 salt 和 hash。