ai-contract-platform/project-docs/archive/implementation-history/V2-ai-worker-deploy-runtime-closure-2026-06-23.md

AI Platform V2 Worker 部署运行闭环记录

时间：2026-06-23 20:30

本轮目标

延续《AI 合同平台 V2 重构版开发方案》，完成知识库 worker 的生产化运行闭环：

1. worker 可以通过 Docker Compose 持续运行，而不是只做 health 命令。
2. AI Platform API 提供 worker 健康、对象存储连通性、OCR provider 配置和检查接口。
3. 管理后台可以查看 worker 心跳、队列状态，并热更新 OCR provider 配置。
4. 对象存储、OCR provider、worker 状态形成上线前可检查的闭环。
5. 管理员可以在 /admin/ai-runtime 手动执行一次 worker，并把执行结果写回运行时间线。

已完成

1. Worker 运行方式

• yuqei-infra/docker/worker.Dockerfile
  • PYTHONPATH 同时包含 worker 和 ai-platform-api。
  • 安装 worker 消费所需依赖：SQLAlchemy、psycopg、boto3、httpx、pypdf、python-docx。
  • 默认命令改为持续消费：python -m yuqei_worker.main。
• yuqei-infra/compose/docker-compose.yml
  • worker 连接 PostgreSQL、Redis、MinIO。
  • worker 使用 S3/MinIO 对象存储配置。
  • worker 增加 healthcheck：python -m yuqei_worker.main --health。
  • ai-platform-api 也接入 MinIO/S3 对象存储配置。

2. Worker 心跳

• 新增 worker_heartbeats 表。
• worker 每次 run_once 后写入：
  • worker_name
  • status
  • queue_name
  • processed
  • succeeded
  • failed
  • error_message
  • updated_at
• API 新增：
  • GET /api/v1/runtime/worker-health
  • POST /api/v1/runtime/worker-heartbeats

3. 对象存储连通性检查

• 对象存储抽象增加 delete_object。
• API 新增：
  • GET /api/v1/runtime/object-storage/check
• 检查逻辑：
  • 写入探针文件
  • 读取探针内容
  • 删除探针文件
  • 返回 ok/warning/error/skipped 结构化结果

4. OCR Provider 后台化

• 新增 ocr_provider_configs 表。
• API 新增：
  • GET /api/v1/runtime/ocr-provider
  • PUT /api/v1/runtime/ocr-provider
  • GET /api/v1/runtime/ocr-provider/check
• OCR 密钥对前端脱敏，只返回 api_key_set。
• 管理员保存 OCR 配置时，如果不填写新密钥，则保留旧密钥。
• worker 会优先读取数据库里的 OCR provider 配置，实现热更新。

5. 管理后台页面

• 新增 /admin/ai-runtime
  • Worker queue counts
  • Worker heartbeat list
  • Run worker once
  • Worker run timeline
  • Object storage probe
  • OCR provider config form
  • OCR provider connectivity check
• 管理区和侧边栏新增 AI Runtime 入口。

6. 手动执行 Worker 与运行审计

• 新增 worker_run_executions 表。
• API 新增：
  • GET /api/v1/runtime/worker-runs
  • POST /api/v1/runtime/worker-runs/run-once
• 手动执行会复用 worker 真实消费逻辑：
  • 获取 queued 知识库导入任务
  • 读取对象存储原始文件
  • 解析/OCR/入库/切分
  • 写入 worker 心跳
  • 写入本次执行记录
• 执行记录包含：
  • worker_name
  • trigger_type
  • triggered_by
  • queue_name
  • status
  • limit
  • processed/succeeded/failed
  • error_message
  • duration_ms
  • started_at/completed_at

Docker Compose 启动方式

docker compose -f yuqei-infra\compose\docker-compose.yml up --build

worker 单次消费验证：

docker compose -f yuqei-infra\compose\docker-compose.yml run --rm worker python -m yuqei_worker.main --run-once --limit 1

worker 健康验证：

docker compose -f yuqei-infra\compose\docker-compose.yml run --rm worker python -m yuqei_worker.main --health

管理后台检查入口

/admin/ai-runtime

可检查：

• worker 是否写入心跳
• 是否可以手动执行一次 worker
• 手动执行结果是否进入 Run timeline
• queued/running/succeeded/failed 任务数量
• MinIO/S3 写读删探针
• OCR provider 是否启用、endpoint 是否可达

环境变量要点

AI Platform API：

AI_PLATFORM_OBJECT_STORAGE_BACKEND=s3
AI_PLATFORM_OBJECT_STORAGE_BUCKET=ai-platform-uploads
AI_PLATFORM_OBJECT_STORAGE_ENDPOINT_URL=http://minio:9000
AI_PLATFORM_OBJECT_STORAGE_ACCESS_KEY_ID=...
AI_PLATFORM_OBJECT_STORAGE_SECRET_ACCESS_KEY=...

Worker：

YUQEI_WORKER_DATABASE_URL=postgresql+psycopg://...
YUQEI_WORKER_OBJECT_STORAGE_BACKEND=s3
YUQEI_WORKER_OBJECT_STORAGE_BUCKET=ai-platform-uploads
YUQEI_WORKER_OBJECT_STORAGE_ENDPOINT_URL=http://minio:9000
YUQEI_WORKER_OBJECT_STORAGE_ACCESS_KEY_ID=...
YUQEI_WORKER_OBJECT_STORAGE_SECRET_ACCESS_KEY=...
YUQEI_WORKER_WORKER_NAME=knowledge-worker-1

下一步建议

1. 增加 worker 死亡/心跳超时的告警策略。
2. 把 runtime 配置变更纳入 AI 审计 Trace，记录谁改了 OCR endpoint、密钥状态和启用状态。
3. 给 Docker Compose 增加发布前 smoke test 脚本。