# 安装与打包 ImageStudio 是 AstrBot 插件,不是独立 Web 服务。 ## 兼容性 - AstrBot `>= 4.25.0`。 - Windows、Linux、macOS 与 Docker(以 AstrBot 本身支持的平台为准)。 - Python 版本跟随对应 AstrBot 发行版。 - SQLite 默认可用;PostgreSQL 需要额外安装驱动。 ## 安装到 AstrBot 推荐通过 AstrBot 插件管理器安装。手工安装时,将仓库完整复制到 AstrBot 配置的插件目录,目录名保持为 `astrbot_plugin_imagestudio`;常见安装位置为: ```text data/plugins/astrbot_plugin_imagestudio/ ``` 至少保留以下运行文件和目录: ```text main.py metadata.yaml _conf_schema.json config.yaml pages/imagestudio/index.html adapters/ backend/ core/ database/ engines/ ``` 重启或在 AstrBot 中重载插件。AstrBot 会发现 `Star` 插件类,调用其 `initialize()`;停用或重载时调用 `terminate()`。插件在 `initialize()` 中使用 `context.register_web_api` 注册 API。 ## 插件页面与 API AstrBot 自动发现 `pages/imagestudio/index.html`。请从 AstrBot 插件管理界面打开页面,不要把未注册的 `/web` 静态目录当作生产入口。 页面 bridge 使用相对 endpoint: ```text ui/bootstrap jobs settings/current ``` 兼容路由如下: ```text # AstrBot v4.25 legacy bridge /api/plug/astrbot_plugin_imagestudio/ # 当前直接 API /api/v1/plugins/extensions/astrbot_plugin_imagestudio/ ``` `window.AstrBotPluginPage.apiGet("ui/bootstrap")` 这类 bridge 调用只传相对 endpoint;直接请求才拼接当前 `/api/v1/plugins/extensions/...` 前缀。 ## 配置图片生成 Provider ImageStudio 不内置可直接用于生产的云端模型。首次生图前,请在 AstrBot 的插件配置页填写: ```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 ``` 并在启动 AstrBot 的进程环境中提供密钥,例如: ```powershell $env:IMAGESTUDIO_PROVIDER_API_KEY = "replace-with-secret" ``` 对应的 `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`;除此之外不要把 API Key 直接写入仓库或 `config.yaml`。配置不完整时,生图接口会返回 `MODEL_CAPABILITY_UNCONFIRMED`;Provider 请求失败时任务和节点会进入失败状态,不会使用 mock 结果冒充生产成功。 ## 配置素材视觉识别 Provider 素材识别需要一个支持图片输入的 OpenAI 兼容多模态模型。在 AstrBot 插件配置页至少填写模型和路由;连接字段留空时会复用上面的生图 Provider。若 Vision 地址、密钥或超时不同而 ID 留空,插件会自动派生独立 Provider ID,避免覆盖生图配置: ```text vision_provider_model: vision-model-id vision_provider_route: material_vlm vision_provider_endpoint: /v1/chat/completions ``` 如需使用独立的视觉服务,可再填写: ```text vision_provider_id: vision_provider vision_provider_base_url: https://vision-provider.example.com vision_provider_api_key_env_var: IMAGESTUDIO_VISION_API_KEY vision_provider_timeout_seconds: 180 vision_provider_enabled: true ``` 等价的 `config.yaml` 配置如下。`provider_id`、`base_url`、`api_key_env_var` 和超时留空时均复用 `generation.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 ``` 识别时 ImageStudio 会从插件 VFS 读取 `storage://` 素材文件,校验实际大小、扩展名和 PNG/JPEG/GIF/WebP 文件签名,再编码为 `data:image/...;base64` 发送给视觉 Provider。未配置有效路由或密钥时接口返回 `MODEL_CAPABILITY_UNCONFIRMED`;Provider 调用失败时素材保持 `pending_recognition`,只记录脱敏后的失败类型,不会生成或允许确认 mock 提示词与标签。 ## 运行数据 AstrBot 插件的持久化数据根目录为: ```text data/plugin_data/astrbot_plugin_imagestudio/ ``` 默认 SQLite 配置: ```yaml database: backend: auto sqlite: # 逻辑路径;AstrBot 运行时映射到插件数据目录 path: data/db/imagestudio.db postgresql: enabled: false ``` 配置中的 `data/...` 是可移植的逻辑路径,AstrBot 运行时会把它映射到上述插件数据根目录;不要在配置里再次手工拼接 `data/plugin_data/astrbot_plugin_imagestudio`,否则可能产生重复目录。图片、素材、缩略图、归档和临时文件也位于同一个插件数据根目录。升级插件源码时不要删除该目录;备份时应单独备份它。 ## 可选 PostgreSQL 选择 `backend: postgresql`,或在 `backend: auto` 下启用并完整配置 PostgreSQL 后,ImageStudio 会使用 PG: ```yaml database: backend: auto postgresql: enabled: true host: 127.0.0.1 port: 5432 database: imagestudio user: imagestudio password: "" ``` 默认 SQLite 不需要第三方数据库驱动。为避免给所有安装者强制安装 PG 驱动,`requirements.txt` 中不启用 PostgreSQL 依赖;需要 PG 时任选其一安装: ```powershell python -m pip install "psycopg[binary]>=3.1" # 或兼容驱动 python -m pip install "psycopg2-binary>=2.9" ``` ## 密钥 不要提交 `.env*`、API Key、DSN、数据库密码或集成 token。私伴集成 token 的轮换 endpoint 为: ```text POST integrations/private-companion/token/rotate ``` 返回的新 token 只展示一次,配置仅保存 salt 与 hash。 ## 验证 ```powershell python scripts/imagestudio_non_ui_smoke.py python scripts/imagestudio_pg_smoke.py --dry-run python -m unittest discover -s tests python -m compileall adapters backend core database engines scripts tests main.py ``` 可选的真实 PostgreSQL smoke: ```powershell $env:IMAGESTUDIO_TEST_PG_DSN = "postgresql://user:password@127.0.0.1:5432/imagestudio_test" python -m unittest tests.test_pg_smoke ``` ## 打包 使用 Git 归档可自动排除未跟踪的本地数据和多数开发产物: ```powershell git archive --format=zip --output astrbot_plugin_imagestudio.zip HEAD ``` 发布包应包含源码、迁移、`pages/imagestudio/` 构建产物、配置模板和文档;不应包含: - `.git/`、`.env*`、`node_modules/`、`__pycache__/`。 - `data/plugin_data/astrbot_plugin_imagestudio/` 中的任何运行数据。 - 本地测试数据库、生成图片、日志、缓存或密钥。