将发布人的状态变更与业务验收报告绑定,复用 Gitea 发布及回滚链路。 从部署回执写入运行身份、镜像及主站登录入口,避免重复调度和回写。
8.1 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 与知识库内容发布各自保留原有授权流程。
建立验收产物
-
从干净检出的完整提交构建一次 API、worker、web 镜像。构建调用方对三个镜像都注入
org.opencontainers.image.revision=<完整 SHA>。API 构建身份沿用scripts/version.py --identity输出,传给 Dockerfile 的版本、提交和构建时间参数。API 与 worker 各自记录镜像 ID,即使它们来自同一个 Dockerfile。 -
封存后用同一份归档部署到隔离验收环境。输出目录必须是新路径,父目录应已存在。三个
--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" -
用验收环境自身的 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) -
由验收人使用获授权的 HiFox CLI 登记业务结论,读回任务、验收字段和状态。
cd_acceptance是 JSON 字符串类型的 metadata,其解析结果为{"verdict":"passed","sha":"…","bundle":"…","evidence":"https://…"}。录入人应先核对真实报告与运行身份。自动发布时,evidence使用同一 HiFox 任务的验收报告评论链接(带#comment-<UUID>)。评论须正文包含完整提交和归档清单摘要,并在发布人确认前完成。用task view --output json核对实际任务 UUID、空间、状态和验收字段。验收登记重试复用原归档摘要与原记录。以当前版本只接受一个任务,多个任务分别验收。 -
在首次发布前,由运维把四个文件放入云主站的
/opt/knowledge-governance/cd/bundles/<release.json SHA256>/。通过安全文件通道传到临时目录,核对摘要与内容后用同一文件系统上的目录重命名发布;已有目录先核对内容,匹配时复用。此目录仅供目标控制器读取,文件由该账号持有且组与其他用户无写权限。
在 HiFox 确认发布
验收、登记、上传归档都完成后,由发布人把原任务移入「待发布」。HiFox 的「知识治理|待发布自动执行 CD」把任务 UUID 交给专用发布 Agent,Agent 调用白名单内的 scripts/hifox_release_trigger.py。桥接脚本读取 HiFox 时间线,校验最近一次状态变更的操作者、状态、同任务验收报告及产物摘要,随后调度 Gitea deploy-production@main。Gitea 仍只开放 workflow_dispatch。目标控制器按完整输入校验 Gitea 运行,并在切换前复查 HiFox 状态和验收摘要。
相同状态事件复用已记录的 Gitea 运行。如果调度结果未知,核查对应 Gitea 运行与本机调度记录后再处理。旧任务已处于「待发布」时,在验收登记完成后重新进入该状态可发起新确认。
也可由发布人使用 Gitea Actions 中原有人工入口应急。分支选 main,使用 action=deploy、完整 sha、bundle、任务 UUID task 和 confirm=deploy-production,仅 HiFox Agent 填写 approval_event 和 acceptance_digest。
主站侧从 Gitea 读取运行、操作者和通过的校验作业,并验证输入摘要及工作流代码。候选代码可来自仓库内的任务分支,以实际验收 SHA 为准。切换前还核验必需 CI 状态、HiFox 验收记录、三份归档、线上源代码血缘及数据库迁移账本。切换复用 scripts/deploy-api-web.sh,仅更换三项 Compose image;保留原配置字节以备回滚。切换后自动读回三镜像、API 二进制 SHA、主站健康、API readiness 及实际提供的前端资源。HiFox 回写包含原始运行 URL、完整提交、摘要、镜像 ID 及核验证据。任务评论另含主站登录地址和已核验的运行版本,带 OCI 版本标签时显示其值,其余镜像显示完整提交。
目标机已有的 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_releasemetadata 并完成对应状态迁移。状态绑定前分别读回组织状态和实际任务类型,复用原有待发布、已发布 ID,保留其余工作流配置。 - 在专用发布 Agent 的 Ubuntu 开发机安装
scripts/{production_cd.py,hifox_release_trigger.py}到~/.local/lib/kg-hifox-release/。该机使用受控 HiFox 登录和已配置的 Gitea Git 凭据助手,凭据不传入自动化指令。使用私有目录~/.local/state/kg-hifox-release/存放active-since(UTC,YYYY-MM-DDTHH:MM:SSZ)及调度记录。首次接通时,将active-since设为通道启用时刻,历史状态事件不追发。发布期间需要 Agent 执行机和 HiFox Daemon 在线。 - 常规 push CI 负责验证和静态预览。这个 workflow 的唯一事件是
workflow_dispatch。make verify的contracts子项运行 CD 用例。真实切换的验收要求对应候选、现场前置条件和发布人确认。