astrbot_plugin_imagestudio/INSTALL.md

222 行
7.2 KiB
Markdown

# 安装与打包
2026-07-06 04:33:14 +08:00
ImageStudio 是 AstrBot 插件,不是独立 Web 服务。
2026-07-06 04:33:14 +08:00
## 兼容性
2026-07-06 04:33:14 +08:00
- AstrBot `>= 4.25.0`。
- Windows、Linux、macOS 与 Docker(以 AstrBot 本身支持的平台为准)。
- Python 版本跟随对应 AstrBot 发行版。
- SQLite 默认可用;PostgreSQL 需要额外安装驱动。
2026-07-06 04:33:14 +08:00
## 安装到 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:
2026-07-06 04:33:14 +08:00
```text
ui/bootstrap
jobs
settings/current
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")` 这类 bridge 调用只传相对 endpoint;直接请求才拼接当前 `/api/v1/plugins/extensions/...` 前缀。
## 配置图片生成 Provider
2026-07-06 04:33:14 +08:00
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 配置:
2026-07-06 04:33:14 +08:00
```yaml
database:
backend: auto
sqlite:
# 逻辑路径;AstrBot 运行时映射到插件数据目录
2026-07-06 04:33:14 +08:00
path: data/db/imagestudio.db
postgresql:
enabled: false
```
配置中的 `data/...` 是可移植的逻辑路径,AstrBot 运行时会把它映射到上述插件数据根目录;不要在配置里再次手工拼接 `data/plugin_data/astrbot_plugin_imagestudio`,否则可能产生重复目录。图片、素材、缩略图、归档和临时文件也位于同一个插件数据根目录。升级插件源码时不要删除该目录;备份时应单独备份它。
## 可选 PostgreSQL
选择 `backend: postgresql`,或在 `backend: auto` 下启用并完整配置 PostgreSQL 后,ImageStudio 会使用 PG:
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 不需要第三方数据库驱动。为避免给所有安装者强制安装 PG 驱动,`requirements.txt` 中不启用 PostgreSQL 依赖;需要 PG 时任选其一安装:
```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
## 密钥
2026-07-06 04:33:14 +08:00
不要提交 `.env*`、API Key、DSN、数据库密码或集成 token。私伴集成 token 的轮换 endpoint 为:
2026-07-06 04:33:14 +08:00
```text
POST integrations/private-companion/token/rotate
```
返回的新 token 只展示一次,配置仅保存 salt 与 hash。
2026-07-06 04:33:14 +08:00
## 验证
2026-07-06 04:33:14 +08:00
```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:
2026-07-06 04:33:14 +08:00
```powershell
$env:IMAGESTUDIO_TEST_PG_DSN = "postgresql://user:password@127.0.0.1:5432/imagestudio_test"
python -m unittest tests.test_pg_smoke
```
## 打包
2026-07-06 04:33:14 +08:00
使用 Git 归档可自动排除未跟踪的本地数据和多数开发产物:
2026-07-06 04:33:14 +08:00
```powershell
git archive --format=zip --output astrbot_plugin_imagestudio.zip HEAD
```
发布包应包含源码、迁移、`pages/imagestudio/` 构建产物、配置模板和文档;不应包含:
2026-07-06 04:33:14 +08:00
- `.git/`、`.env*`、`node_modules/`、`__pycache__/`。
- `data/plugin_data/astrbot_plugin_imagestudio/` 中的任何运行数据。
- 本地测试数据库、生成图片、日志、缓存或密钥。