6.9 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 -m compileall adapters backend core database engines main.py
打包
使用 Git 归档可自动排除未跟踪的本地数据和多数开发产物:
git archive --format=zip --output astrbot_plugin_imagestudio.zip HEAD
发布包应包含源码、迁移、pages/imagestudio/ 构建产物、配置模板和文档;不应包含:
.git/、.env*、node_modules/、__pycache__/。data/plugin_data/astrbot_plugin_imagestudio/中的任何运行数据。- 本地测试数据库、生成图片、日志、缓存或密钥。