ai-contract-platform/project-docs/V2-deploy-runtime-baseline-2026-06-24.md

AI 合同平台 V2 - T6 部署与运行基线闭环记录

日期：2026-06-24

目标

对照《AI 合同平台 V2 重构版开发方案》，本轮进入 T6：部署与运行基线。目标是保证 V2 从空库到运行有明确路径：

• 数据库迁移可显式执行。
• 环境变量可校验。
• 健康检查可判断服务是否可用。
• Docker/compose 能启动主要服务。
• 发布前有统一验证命令。

本轮完成

Contract API 运行检查

• 新增运行配置检查模型：
  • RuntimeConfigCheck
  • RuntimeConfigStatus
• 新增配置校验：
  • 生产环境不能使用 SQLite。
  • 生产环境必须关闭 DATABASE_AUTO_CREATE。
  • 生产环境必须关闭 demo 数据种子。
  • AI 平台地址必须是 HTTP(S) URL。
  • 审查 worker 间隔和批量限制必须有效。
  • 文件存储目录不能为空。
• GET /health 增加：
  • config_status
  • database_backend
  • database_auto_create
  • seed_demo_data
• 新增 GET /api/v1/runtime/config-check。

Docker/compose

• 新增 contract-api-migrate，启动 API 前执行 Contract API Alembic migration。
• 新增 ai-platform-api-migrate，启动 AI Platform 前执行 AI Platform Alembic migration。
• AI Platform 和 Contract API 使用独立 Alembic version table，避免本地 compose 共用一个 Postgres 数据库时互相覆盖：
  • ai_platform_alembic_version
  • contract_api_alembic_version
• Contract API / AI Platform API 容器增加 healthcheck。
• Contract Review Worker 和 Knowledge Worker 改为等待 API healthcheck。
• 新增 contract-web Dockerfile 和 compose 服务。
• 新增 contract-files volume，合同附件从容器生命周期中独立出来。
• compose 本地启动后可访问：
  • http://localhost:3000
  • http://localhost:8100
  • http://localhost:8101
  • http://localhost:9001

前端健康页

• 修复 /health 页面乱码。
• 健康面板改为通过 Next 代理读取 Contract API health/config-check，避免浏览器跨域。
• 增加运行配置状态、数据库模式、auto create、seed demo 展示。

验证脚本

新增：

yuqei-infra\scripts\verify-v2-runtime.ps1

检查内容：

• Contract API /health。
• Contract API /api/v1/runtime/config-check。
• AI Platform /health。
• AI Platform worker runtime health。
• AI Platform object storage check。
• Contract Web /health 可访问性。

文档

• 新增 yuqei-infra/README.md。
• 更新 Contract API .env.example。
• 更新 compose .env.example。
• 更新 Contract OpenAPI 契约。

验证结果

• python -m pytest yuqei-contract-platform\services\contract-api\tests -q：通过。
• python -m compileall yuqei-contract-platform\services\contract-api\src\yuqei_contract_api：通过。
• Contract API Alembic 空库迁移到 head：通过。
• AI Platform / Contract API migration 文件编译：通过。
• OpenAPI YAML 解析：通过。
• compose YAML 解析：通过。
• npm --prefix yuqei-contract-platform\apps\contract-web run build：通过。
• npm --prefix yuqei-contract-platform\apps\contract-web run typecheck：通过。
• yuqei-infra\scripts\verify-v2-runtime.ps1 PowerShell 语法解析：通过。

当前本地环境没有 docker 命令，因此本轮未实际执行 docker compose config 和 docker compose up --build。compose 文件已完成 YAML 解析校验，真实容器启动需要在安装 Docker 的环境中执行。

后续建议

下一步可以进入 T7：合同流程接入 AI 中台的生产级收口，重点检查合同系统只通过 yuqei-ai-sdk-python 调用 AI 中台，不再把 Prompt、模型参数、知识库检索逻辑塞回合同系统。