Files
knowledge-governance/docs/PRODUCTION_CD_RUNBOOK.md
T
姚章浩 07a0ee2644
build / build (push) Successful in 1m46s
fix(deploy): 使用 Gitea 单次人工确认发布
2026-11-23 02:24:18 +08:00

6.6 KiB

云测试治理主站应用 CD

正式入口为 http://100.85.111.121:8088/。云端 Compose 项目为 knowledge-governance-cloud-test,工作目录 /opt/knowledge-governance,当前配置链为 compose.json,服务为 api、web、worker。Web 容器提供 8088,通过挂载的 nginx 配置代理 API 的 127.0.0.1:18098。应用 CD 与知识库内容发布各自保留原有授权流程。

建立验收产物

  1. 从干净检出的完整提交构建一次 API、worker、web 镜像。构建调用方对三个镜像都注入 org.opencontainers.image.revision=<完整 SHA>。API 构建身份沿用 scripts/version.py --identity 输出,传给 Dockerfile 的版本、提交和构建时间参数。API 与 worker 各自记录镜像 ID,即使它们来自同一个 Dockerfile。

  2. 封存后用同一份归档部署到隔离验收环境。输出目录必须是新路径,父目录应已存在。三个 --api/--web/--worker 参数是本地镜像的完整 ID。

    python3 scripts/production_cd.py pack --sha "$SHA" --task "$TASK_UUID" \
      --api "$API_ID" --web "$WEB_ID" --worker "$WORKER_ID" --output "$BUNDLE_DIR"
    docker load -i "$BUNDLE_DIR/api.tar"
    docker load -i "$BUNDLE_DIR/web.tar"
    docker load -i "$BUNDLE_DIR/worker.tar"
    
  3. 用验收环境自身的 Compose 和数据库启动这些镜像。用下面的命令读回验收环境运行身份。此处三个服务参数是实际的测试容器名。在业务验收入口执行实际用例并将输出、结果与报告链接放在同一份验收记录里。

    python3 scripts/production_cd.py attest --sha "$SHA" --task "$TASK_UUID" \
      --api "$QA_API" --web "$QA_WEB" --worker "$QA_WORKER" --test-url "$QA_URL" --directory "$BUNDLE_DIR"
    BUNDLE_SHA=$(sha256sum "$BUNDLE_DIR/release.json" | cut -d' ' -f1)
    
  4. 由验收人使用获授权的 HiFox CLI 登记业务结论,读回任务、验收字段和状态。cd_acceptance 是 JSON 字符串类型的 metadata,其解析结果为 {"verdict":"passed","sha":"…","bundle":"…","evidence":"https://…"}。录入人应先核对真实报告与运行身份。随后把对应任务转至已有「待发布」。用 task view --output json 核对实际任务 UUID、空间、状态和验收字段。验收登记重试复用原归档摘要与原记录。以当前版本只接受一个任务,多个任务分别验收。

  5. 在首次发布前,由运维把四个文件放入云主站的 /opt/knowledge-governance/cd/bundles/<release.json SHA256>/。通过安全文件通道传到临时目录,核对摘要与内容后用同一文件系统上的目录重命名发布;已有目录先核对内容,匹配时复用。此目录仅供目标控制器读取,文件由该账号持有且组与其他用户无写权限。

人工确认并自动部署

在 Gitea Actions 打开 deploy-production 并运行工作流。工作流分支选择 main,填写 action=deploy、已验收的完整 sha、归档清单摘要 bundle、HiFox 任务 UUID task 和 confirm=deploy-production。发布人用自己的 Gitea 账号提交一次确认。

主站侧从 Gitea 读取运行、操作者和通过的校验作业,并验证输入摘要及工作流代码。候选代码可来自仓库内的任务分支,以实际验收 SHA 为准。切换前还核验必需 CI 状态、HiFox 验收记录、三份归档、线上源代码血缘及数据库迁移账本。切换复用 scripts/deploy-api-web.sh,仅更换三项 Compose image;保留原配置字节以备回滚。切换后自动读回三镜像、API 二进制 SHA、主站健康、API readiness 及实际提供的前端资源。HiFox 回写包含原始运行 URL、完整提交、摘要、镜像 ID 及核验证据。

目标机已有的 schema_migrations 必须与候选完全相同,API 与 worker 的库连接均须核对。应用会在启动时检查迁移。新增或改变的迁移先按独立流程审查、备份、执行并复验;CD 自身只读迁移账本。发布时运营方应保留 prior tag,保障用原 Compose 字节回滚。

失败恢复

  • rolled_back 表示自动恢复了原 Compose、旧的镜像 ID、API SHA 与站点健康。rollback_failed 或 cutover_started 要求巡检现场、按回执恢复并复验。目标机互斥锁覆盖切换及回写。Gitea 的取消记录只能说明流水线结束,回滚以目标机回执和运行时读回为准。
  • DEPLOYED_HIFOX_PENDING 表示镜像切换和核验已经完成。以同一 sha、bundle、task 人工发起 action=writeback、confirm=retry-writeback。脚本先读原目标回执并复验仍在运行的版本,随后补写 HiFox,保留原部署链接。状态与 metadata 的当前值以 HiFox 读回为准。重复调用核对记录后结束。
  • 目标回执 /opt/knowledge-governance/cd/receipts/<bundle>.json,镜像切换前的 Compose 保存为同名 .compose.backup。SSH 超时或强制中断后,先读回执和当前运行态。已存在未决或失败回执时,重复部署被拒。保留原回执作为事故证据。

一次性配置与权限

  • 目标机安装仓库 scripts/{production_cd.py,cd_migration_probe.py,deploy-api-web.sh,production-cd-ssh.sh} 到 /opt/knowledge-governance/cd/bin/。创建私有 receipts/、bundles/、hifox-home/,初始化 source.git 为 bare Git 仓,并将 .gitea/required-contexts.txt 安装到该目录。仅发布运维可更新这些文件。
  • 填写目标机 /opt/knowledge-governance/cd/deploy-production.yml,内容与 Gitea 主分支的工作流逐字节相同。控制器用 Gitea 发布人账号 ID 和只读日志验证确认。目标端 authorized_keys 为 CI 单独公钥设置 restrict,command="/opt/knowledge-governance/cd/bin/production-cd-ssh.sh"。校验云主机 SSH host key 后将其按 kg-governance-cd 别名写入 KG_CD_KNOWN_HOSTS。对应独立 SSH 私钥保存在 KG_CD_SSH_KEY。Runner 标签为 kg-production-cd,使用 KG_CD_SSH_HOST 和 KG_CD_SSH_PORT 接入批准的 Tailscale 或本机 IPv6 隧道。
  • 将受控 HiFox CLI 安装至 bin/hifox,由账号持有人在目标主机使用 hifox-home 对应的私有配置目录完成登录。身份须能读取指定空间的任务、写 cd_release metadata 并完成对应状态迁移。状态绑定前分别读回组织状态和实际任务类型,复用原有待发布、已发布 ID,保留其余工作流配置。
  • 常规 push CI 负责验证和静态预览。这个 workflow 的唯一事件是 workflow_dispatch。make verify 的 contracts 子项运行 CD 用例。真实切换的验收要求对应候选、现场前置条件和发布人确认。