2026-07-11 21:50:34 +08:00
|
|
|
|
# 安装与打包
|
2026-07-06 04:33:14 +08:00
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
|
ImageStudio 是 AstrBot 插件,不是独立 Web 服务。
|
2026-07-06 04:33:14 +08:00
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
|
## 兼容性
|
2026-07-06 04:33:14 +08:00
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
|
- AstrBot `>= 4.25.0`。
|
|
|
|
|
|
- Windows、Linux、macOS 与 Docker(以 AstrBot 本身支持的平台为准)。
|
|
|
|
|
|
- Python 版本跟随对应 AstrBot 发行版。
|
|
|
|
|
|
- SQLite 默认可用;PostgreSQL 需要额外安装驱动。
|
2026-07-06 04:33:14 +08:00
|
|
|
|
|
2026-07-11 21:50:34 +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
|
2026-07-11 21:50:34 +08:00
|
|
|
|
ui/bootstrap
|
|
|
|
|
|
jobs
|
|
|
|
|
|
settings/current
|
2026-07-06 04:33:14 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
|
兼容路由如下:
|
2026-07-06 04:33:14 +08:00
|
|
|
|
|
|
|
|
|
|
```text
|
2026-07-11 21:50:34 +08:00
|
|
|
|
# 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
|
|
|
|
```
|
|
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
|
`window.AstrBotPluginPage.apiGet("ui/bootstrap")` 这类 bridge 调用只传相对 endpoint;直接请求才拼接当前 `/api/v1/plugins/extensions/...` 前缀。
|
|
|
|
|
|
|
|
|
|
|
|
## 配置图片生成 Provider
|
2026-07-06 04:33:14 +08:00
|
|
|
|
|
2026-07-11 21:50:34 +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:
|
2026-07-11 21:50:34 +08:00
|
|
|
|
# 逻辑路径;AstrBot 运行时映射到插件数据目录
|
2026-07-06 04:33:14 +08:00
|
|
|
|
path: data/db/imagestudio.db
|
|
|
|
|
|
postgresql:
|
|
|
|
|
|
enabled: false
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
|
配置中的 `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: ""
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
|
默认 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-11 21:50:34 +08:00
|
|
|
|
## 密钥
|
2026-07-06 04:33:14 +08:00
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
|
不要提交 `.env*`、API Key、DSN、数据库密码或集成 token。私伴集成 token 的轮换 endpoint 为:
|
2026-07-06 04:33:14 +08:00
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
|
POST integrations/private-companion/token/rotate
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
|
返回的新 token 只展示一次,配置仅保存 salt 与 hash。
|
2026-07-06 04:33:14 +08:00
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
|
## 验证
|
2026-07-06 04:33:14 +08:00
|
|
|
|
|
|
|
|
|
|
```powershell
|
2026-07-12 02:54:45 +08:00
|
|
|
|
python -m compileall adapters backend core database engines main.py
|
2026-07-06 04:33:14 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
|
## 打包
|
2026-07-06 04:33:14 +08:00
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
|
使用 Git 归档可自动排除未跟踪的本地数据和多数开发产物:
|
2026-07-06 04:33:14 +08:00
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
|
git archive --format=zip --output astrbot_plugin_imagestudio.zip HEAD
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
|
发布包应包含源码、迁移、`pages/imagestudio/` 构建产物、配置模板和文档;不应包含:
|
2026-07-06 04:33:14 +08:00
|
|
|
|
|
2026-07-11 21:50:34 +08:00
|
|
|
|
- `.git/`、`.env*`、`node_modules/`、`__pycache__/`。
|
|
|
|
|
|
- `data/plugin_data/astrbot_plugin_imagestudio/` 中的任何运行数据。
|
|
|
|
|
|
- 本地测试数据库、生成图片、日志、缓存或密钥。
|