yuqei/ai-contract-platform
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
main
ai-contract-platform/project-docs/V2-deploy-runbook-2026-06-26.md
T
yuqei 7bc74f06f2
Build and Test Quality Gate / Contract Web typecheck and build (pull_request) Successful in 6m47s
Details
Build and Test Quality Gate / Python tests and Contract API migration (pull_request) Failing after 42m10s
Details
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 16m59s
Details
release: freeze V2 production candidate
2026-07-20 18:39:27 +08:00

6.2 KiB
Raw Permalink Blame History

AI 合同平台 V2 部署 Runbook

日期：2026-06-26

目标

把当前 V2 的本地启动、性能基线、安全收口、烟雾部署和生产变量收成一条可执行路径。

启动顺序

  1. PostgreSQL 启动。
  2. postgres-init-databases 创建 yuqei_contract、yuqei_ai、yuqei_ops。
  3. ai-platform-api-migrate 执行 AI 库迁移。
  4. contract-api-migrate 执行合同库迁移。
  5. 启动 ai-platform-api、contract-api、worker、contract-web。

本地开发

根目录：

Copy-Item yuqei-infra\compose\.env.example yuqei-infra\compose\.env
docker compose --env-file yuqei-infra\compose\.env -f yuqei-infra\compose\docker-compose.yml up --build

如果不走 Docker，服务单独启动命令已经在各自 README.md 中说明：

  • yuqei-contract-platform/services/contract-api/README.md
  • yuqei-ai-platform/services/ai-platform-api/README.md
  • yuqei-ai-platform/services/worker/README.md

收口顺序

  1. 先保留并复跑性能基线，确认高频路径仍在可交付区间。
  2. 再跑安全扫描，把 bandit、npm audit、项目级 pip-audit 一起收口。
  3. 最后整理部署文档和 smoke 命令，形成交付版本。

验证命令

powershell.exe -NoProfile -ExecutionPolicy Bypass -File yuqei-infra\scripts\verify-v2-runtime.ps1

powershell.exe -NoProfile -ExecutionPolicy Bypass -File yuqei-infra\scripts\verify-contract-review-worker-flow.ps1 `
  -ContractApiBaseUrl http://localhost:8100 `
  -WorkerExecutionMode docker-compose `
  -RequireConfidence

烟雾部署

现有烟雾部署脚本：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File yuqei-infra\scripts\deploy-v2-smoke-docker.ps1 `
  -UseSshpass `
  -AllowDirtyWorktree

最新一次已通过的 smoke 产物：

  • project-docs/qa-artifacts/v2-smoke-docker-deploy/2026-07-16T11-12-47
  • Web: http://192.168.3.90:13000
  • Contract API: http://192.168.3.90:18100
  • AI Platform API: http://192.168.3.90:18101
  • MinIO Console: http://192.168.3.90:19001
  • AI golden sample asset gate：通过，90 samples、6/6 suites、16/16 checks。
  • Contract review worker smoke：通过。
  • 远端数据库基线：yuqei_contract、yuqei_ai、yuqei_ops 均存在。
  • 发布质量门：project-docs/qa-artifacts/v2-release-quality-gate/2026-07-16T11-18-52，带 --run-benchmark 复跑通过。
  • 安全扫描：project-docs/qa-artifacts/v2-security-scan/2026-07-12T13-08-00，npm、Bandit、pip-audit 均为 0。
  • 源码 secret 扫描：project-docs/qa-artifacts/v2-source-secret-scan/2026-07-12T15-24-56，覆盖冻结索引的 821 个文件；16 个候选均为已审计样例，新增未审计命中和陈旧基线均为 0。
  • 接口压测：project-docs/qa-artifacts/v2-interface-benchmark/2026-07-12T13-24-00，7 个场景全部通过，错误率均为 0。
  • Contract API：单 Uvicorn worker + 2 秒短读缓存；所有写请求前后清缓存。
  • 无邮箱身份 smoke：公开注册/重置/邮箱验证关闭，管理员邀请与员工设密登录通过。
  • 部署归档明确排除 .env、.env.local、.env.production、.env.smoke，本机 secret 不进入远端构建上下文。

生产基线

生产必须显式覆盖这些变量：

CONTRACT_API_ENVIRONMENT=production
CONTRACT_API_DATABASE_AUTO_CREATE=false
CONTRACT_API_SEED_DEMO_DATA=false
CONTRACT_API_UVICORN_WORKERS=1
CONTRACT_API_READ_CACHE_TTL_SECONDS=2
CONTRACT_API_IDENTITY_EMAIL_DELIVERY_MODE=disabled
CONTRACT_API_IDENTITY_SELF_SERVICE_ENABLED=false
CONTRACT_API_IDENTITY_MANUAL_INVITATION_ENABLED=true
CONTRACT_API_IDENTITY_RATE_LIMIT_SECRET=LOAD_A_STABLE_RANDOM_SECRET_OF_AT_LEAST_32_CHARACTERS
AI_PLATFORM_ENVIRONMENT=production
AI_PLATFORM_DATABASE_AUTO_CREATE=false
AI_PLATFORM_UVICORN_WORKERS=1
YUQEI_WORKER_DATABASE_AUTO_CREATE=false

配套说明：

  • 连接串从 yuqei-infra/compose/.env.production.example 开始替换。
  • 生产不允许依赖自动建表。
  • 发布前先迁移，再替换容器。
  • 身份安全迁移的预期 Contract API head 为 20260713_0031；部署后必须验证 identity_security_columns=ok。
  • 首次生产部署在迁移后、开放入口前运行一次 python -m yuqei_contract_api.identity_bootstrap --tenant-id default --email <平台管理员邮箱> --password-file <只读 secret 文件>。命令默认不覆盖已有凭据，轮换必须显式增加 --force-rotate。
  • 当前首发采用管理员线下开通：关闭公开注册、密码重置和邮箱验证；管理员在后台生成一次性邀请链接并通过可信渠道交付。
  • 以后启用 SMTP 时，必须将 IDENTITY_MANUAL_INVITATION_ENABLED 改为 false，SMTP 凭据只能来自受保护环境或只读 secret 文件。
  • 互联网反向代理必须覆盖客户端传入的 X-Real-IP / X-Forwarded-For，避免伪造 IP 绕过验证码限流。
  • 当前短读缓存是进程内缓存；当 CONTRACT_API_UVICORN_WORKERS>1 时会自动禁用。生产扩容到多 worker 前，应先接入支持跨进程失效的共享缓存。

回滚策略

  • 保留上一次 smoke 成功的归档和镜像信息。
  • 如果健康检查、数据库基线或 worker smoke 失败，停止继续推进生产替换。
  • 先修复迁移/配置，再重新跑 smoke。

已知限制

  • 本机是否具备 Docker 不再作为发布前置；权威 smoke 以 192.168.3.90 远端 Docker 环境为准。
  • Trace governance 的 24 小时 smoke 观察窗口列为上线前检查项，production 暂不开启，不阻塞当前交付收口。
  • 代码与依赖审计已经可以在本机或 CI 独立完成，不依赖 Docker。
  • 源码 secret 门禁使用 detect-secrets==1.5.0 和已审计基线；新增未审计命中会阻断 CI，扫描 artifact 写入 project-docs/qa-artifacts/v2-source-secret-scan。
  • 身份线下开通、SMTP 与验证码安全的配置、验证和回滚说明见 project-docs/V2-production-identity-email-security-2026-07-13.md。
  • backend-only production compose、HTTPS edge、只读 preflight、异地备份/恢复验证和真实 Provider 18 样本验收见 project-docs/V2-production-infrastructure-provider-acceptance-2026-07-16.md 与 yuqei-infra/deploy/README.md。这些入口默认不切换流量。
Reference in New Issue View Git Blame Copy Permalink