Skip to content

deployment.md

Latest commit

 

History

History
149 lines (110 loc) · 6.5 KB

deployment.md

File metadata and controls

149 lines (110 loc) · 6.5 KB
Raw

Docker Compose 部署与运维

支持范围

VLMForge v0.1 只支持 Docker Compose，本地单工作区、无登录。不要把 API、Web、PostgreSQL、Redis、MinIO 端口直接暴露到公网。Apple Silicon 与 Linux/AMD64 使用同一套多架构基础镜像和 compose.yaml。

前置条件

  • Docker Desktop 4.x 或 Docker Engine 24+；
  • Docker Compose v2；
  • 至少 4 CPU、8 GiB 内存、10 GiB 可用磁盘；
  • 端口 4173、8000、9000、9001 未占用。

首次启动

在仓库根目录逐行执行：

cp .env.example .env

只在本地演示时，占位密码可直接启动；任何共享机器都必须先修改以下值：

POSTGRES_PASSWORD=REPLACE_WITH_A_RANDOM_LOCAL_PASSWORD
MINIO_ROOT_USER=REPLACE_WITH_A_RANDOM_LOCAL_USER
MINIO_ROOT_PASSWORD=REPLACE_WITH_A_RANDOM_LOCAL_PASSWORD

构建和启动：

docker compose config --quiet
docker compose build
docker compose up -d
docker compose ps

vlmforge-migration 正常完成后应显示 Exited (0)；vlmforge-api、vlmforge-worker、vlmforge-web、vlmforge-postgres、vlmforge-redis、vlmforge-minio 应保持运行。

真实 Readiness：

curl --fail http://127.0.0.1:8000/health/live
curl --fail http://127.0.0.1:8000/health/ready

第二个接口必须返回 PostgreSQL、Redis、MinIO 全部为 true。API 和 Worker 启动时也会主动执行 PostgreSQL SELECT 1、Redis 写读删与 MinIO 写读删；依赖失败时进程拒绝 Ready。

启动无密钥 Demo：

curl --fail -X POST http://127.0.0.1:8000/api/v1/demo
open http://127.0.0.1:4173

Linux 可用浏览器手动打开 http://SERVER_IP:4173，但必须通过主机防火墙或反向代理限制访问来源。

环境变量

Compose 从未提交的 .env 读取基础值，并向 API/Worker 注入 VLMFORGE_ 前缀变量。项目按要求不使用 Docker Secret；因此 .env 权限和主机访问控制是安全边界的一部分。

变量 默认/示例 必需 说明
POSTGRES_DB vlmforge 是 Compose PostgreSQL 数据库名
POSTGRES_USER vlmforge 是 Compose PostgreSQL 用户
POSTGRES_PASSWORD 占位符 是 本地数据库密码，共享环境必须更换
MINIO_ROOT_USER 占位符 是 MinIO 根用户
MINIO_ROOT_PASSWORD 占位符 是 MinIO 根密码
VLMFORGE_DATABASE_URL postgresql+asyncpg://... 直跑时是 业务 SQLAlchemy URL；Compose 自动拼装
VLMFORGE_CHECKPOINT_DATABASE_URL postgresql://...?connect_timeout=5 直跑时是 LangGraph psycopg 检查点 URL
VLMFORGE_REDIS_URL redis://.../0 是 ARQ、通知、取消信号
VLMFORGE_MINIO_ENDPOINT host:9000 是 不包含 http:// 或 https://
VLMFORGE_MINIO_ACCESS_KEY 占位符 是 API/Worker MinIO 用户
VLMFORGE_MINIO_SECRET_KEY 占位符 是 API/Worker MinIO 密码
VLMFORGE_MINIO_SECURE false 是 本地 Compose 使用 HTTP
VLMFORGE_MINIO_BUCKET vlmforge 是 制品 Bucket
VLMFORGE_CORS_ORIGINS JSON 数组 是 例如 ["http://localhost:4173"]
VLMFORGE_DATABASE_CONNECT_TIMEOUT_SECONDS 5 是 单次数据库连接超时
VLMFORGE_DATABASE_CONNECT_RETRIES 12 是 有限启动重试次数
VLMFORGE_DATABASE_RETRY_DELAY_SECONDS 1 是 重试间隔
VLMFORGE_MAX_UPLOAD_BYTES 268435456 是 ZIP 上传上限
VLMFORGE_MAX_DATASET_UNCOMPRESSED_BYTES 1073741824 是 ZIP 解压总量上限
VLMFORGE_SSE_HEARTBEAT_SECONDS 15 是 SSE 心跳
VLMFORGE_SSE_POLL_SECONDS 1 是 PostgreSQL 重放轮询间隔
VLMFORGE_LOG_* 见 .env.example 否 控制台/文件级别、轮转和保留
OPENROUTER_API_KEY 占位符 真实模型时 Candidate 的 api_key_env 引用它
OPENAI_COMPATIBLE_API_KEY 占位符 真实模型时 OpenAI-compatible Adapter 可选密钥

本次 v0.1 新增的 .env 配置集中在 PostgreSQL、LangGraph checkpoint、Redis、MinIO、CORS、上传/SSE 上限、日志和两个可选 Provider Key；完整可复制清单只以根目录 .env.example 为准。

日志和故障定位

docker compose logs --tail=200 vlmforge-api
docker compose logs --tail=200 vlmforge-worker
docker compose logs --tail=200 vlmforge-migration

日志只应包含 request/run/attempt ID、节点、状态、耗时和错误摘要。发现图片、完整 Prompt、完整响应或 Key 时视为安全问题。

常见故障：

  • Migration 非零退出：先查看 vlmforge-migration 日志，核对 PostgreSQL 密码与磁盘。
  • API 反复重启：/health/ready 所需的 Redis/MinIO 真实读写可能失败，不要只检查端口。
  • Demo 一直 queued：查看 Worker 是否启动、ARQ 是否连到同一 Redis、LangGraph checkpoint URL 是否使用 psycopg 格式。
  • Web 可开但 API 报错：确认 Nginx /api/ 代理和 vlmforge-api health。
  • 数据集 422：先运行 vlmforge validate，检查 ZIP 根目录、Schema、规则和图片 MIME。

升级与最短停机

本地 v0.1 只有单 API/Worker 实例，无法宣称零停机。升级时先构建镜像，再执行迁移和定向替换，避免先 down：

git pull --ff-only
docker compose build vlmforge-api vlmforge-worker vlmforge-migration vlmforge-web
docker compose run --rm vlmforge-migration
docker compose up -d --no-deps vlmforge-api vlmforge-worker vlmforge-web
curl --fail http://127.0.0.1:8000/health/ready

数据库迁移必须保持向后兼容，先扩展、后切换、最后清理。不要在运行中删除旧列或更改已有字段语义。

备份与停止

业务真相备份：

docker compose exec -T vlmforge-postgres pg_dump -U vlmforge -d vlmforge -Fc > vlmforge.dump

MinIO 数据位于命名卷 vlmforge-minio-data，应使用对象存储兼容工具做独立备份。仅停止服务且保留数据：

docker compose stop

docker compose down -v 会删除 PostgreSQL、Redis、MinIO 和日志卷，无法通过普通启动恢复；除非明确要清空本地数据，否则不要执行。

验收清单

  • docker compose config --quiet 通过。
  • Migration Exited (0)。
  • API、Worker、Web 与三项依赖正常运行。
  • /health/ready 三项依赖均为 true。
  • Replay Demo 完成并生成唯一推荐。
  • SSE 断线后能从最后事件继续。
  • Markdown/HTML/JSON/CSV 均可导出。
  • 日志未暴露图片、Prompt、完整响应或密钥。