astrbot_plugin_imagestudio/INSTALL.md

7.2 KiB

安装与打包

ImageStudio 是 AstrBot 插件,不是独立 Web 服务。

兼容性

  • AstrBot >= 4.25.0。
  • Windows、Linux、macOS 与 Docker(以 AstrBot 本身支持的平台为准)。
  • Python 版本跟随对应 AstrBot 发行版。
  • SQLite 默认可用;PostgreSQL 需要额外安装驱动。

安装到 AstrBot

推荐通过 AstrBot 插件管理器安装。手工安装时,将仓库完整复制到 AstrBot 配置的插件目录,目录名保持为 astrbot_plugin_imagestudio;常见安装位置为:

data/plugins/astrbot_plugin_imagestudio/

至少保留以下运行文件和目录:

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:

ui/bootstrap
jobs
settings/current

兼容路由如下:

# 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") 这类 bridge 调用只传相对 endpoint;直接请求才拼接当前 /api/v1/plugins/extensions/... 前缀。

配置图片生成 Provider

ImageStudio 不内置可直接用于生产的云端模型。首次生图前,请在 AstrBot 的插件配置页填写:

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 的进程环境中提供密钥,例如:

$env:IMAGESTUDIO_PROVIDER_API_KEY = "replace-with-secret"

对应的 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;除此之外不要把 API Key 直接写入仓库或 config.yaml。配置不完整时,生图接口会返回 MODEL_CAPABILITY_UNCONFIRMED;Provider 请求失败时任务和节点会进入失败状态,不会使用 mock 结果冒充生产成功。

配置素材视觉识别 Provider

素材识别需要一个支持图片输入的 OpenAI 兼容多模态模型。在 AstrBot 插件配置页至少填写模型和路由;连接字段留空时会复用上面的生图 Provider。若 Vision 地址、密钥或超时不同而 ID 留空,插件会自动派生独立 Provider ID,避免覆盖生图配置:

vision_provider_model: vision-model-id
vision_provider_route: material_vlm
vision_provider_endpoint: /v1/chat/completions

如需使用独立的视觉服务,可再填写:

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 必须显式配置:

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 插件的持久化数据根目录为:

data/plugin_data/astrbot_plugin_imagestudio/

默认 SQLite 配置:

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:

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

默认 SQLite 不需要第三方数据库驱动。为避免给所有安装者强制安装 PG 驱动,requirements.txt 中不启用 PostgreSQL 依赖;需要 PG 时任选其一安装:

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

密钥

不要提交 .env*、API Key、DSN、数据库密码或集成 token。私伴集成 token 的轮换 endpoint 为:

POST integrations/private-companion/token/rotate

返回的新 token 只展示一次,配置仅保存 salt 与 hash。

验证

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:

$env:IMAGESTUDIO_TEST_PG_DSN = "postgresql://user:password@127.0.0.1:5432/imagestudio_test"
python -m unittest tests.test_pg_smoke

打包

使用 Git 归档可自动排除未跟踪的本地数据和多数开发产物:

git archive --format=zip --output astrbot_plugin_imagestudio.zip HEAD

发布包应包含源码、迁移、pages/imagestudio/ 构建产物、配置模板和文档;不应包含:

  • .git/、.env*、node_modules/、__pycache__/。
  • data/plugin_data/astrbot_plugin_imagestudio/ 中的任何运行数据。
  • 本地测试数据库、生成图片、日志、缓存或密钥。