3.1 KiB
3.1 KiB
Image Sync 架构说明
1. 目标
通过 CI(构建) -> Sync(同步) -> CD(部署) 三段分离，将构建稳定性与部署可用性解耦：
- GitHub Actions 只负责构建和推送到 GHCR，并输出权威
digest。 - 本地 Sync Service 负责 webhook 入队、重试、GHCR 到 Harbor 的复制与 digest 校验。
- 本地 K8s 只从 Harbor 拉取镜像，不直接依赖公网构建链路。
2. 端到端流程
push main/develop触发.github/workflows/build-and-notify.yml。- CI 构建镜像并推送到 GHCR，拿到
steps.build.outputs.digest。 - CI 组装 payload，使用
Bearer + HMAC(timestamp.body)调用/sync。 - Sync Service 验签、验 token、验 payload，按
event_id去重并写入 sqlite。 - Worker 轮询任务：
- 若 Harbor 已有目标 digest，直接
VERIFIED。 - 否则执行
skopeo copy推送 tags。 - 再
skopeo inspect校验 digest。
- 若 Harbor 已有目标 digest，直接
- 成功任务标记
VERIFIED，触发 deploy repo AutoPR（可选自动合并）。 - ArgoCD 监听 deploy repo 主分支，自动完成部署。
- 失败按类型写
FAILED_RETRYABLE或FAILED_FATAL。
3. 关键契约
Webhook 必填字段：
event_id,repository,image,git_sha,short_sha,branch,digest,tags,triggered_at
幂等策略：
- 第一层：
webhook_events.event_id UNIQUE - 第二层：
tasks UNIQUE(repository, image, digest, target_repo)
4. 数据模型
webhook_events
event_id UNIQUE：避免同一 webhook 重放重复入队signature：审计留痕received_at：接收时间
tasks
status：PENDING/SYNCING/VERIFIED/FAILED_RETRYABLE/FAILED_FATALretry_count + next_retry_at：指数退避调度verified_at：用于部署联动的可信时间点
5. 失败分类与重试
- 可重试：网络抖动、超时、5xx、429
- 不可重试：凭据错误、镜像不存在、引用格式错误
- 退避：
min(RETRY_BASE_SECONDS * 2^(retry-1), RETRY_MAX_SECONDS) - 超过
MAX_RETRIES后标记FAILED_FATAL
6. 镜像命名
目标仓库统一规则：
harbor.omniverseai.net/ci/<app>
建议 tag：
- 不可变：
sha-<shortsha> - 可读性：
branch-main/branch-develop
7. 触发与兜底
- 主路径：GitHub webhook 到
/sync - 兜底路径：建议增加定时补偿任务（按时间窗口扫描遗漏 digest 并补投）
8. 运维建议
- MVP：单机 sqlite + 单 worker
- 稳定期：systemd 或 compose 常驻
- 扩展期：迁移 PostgreSQL、支持多 worker、引入分布式锁与多 Harbor 目标
- 若 GHCR 日间链路慢：启用夜间同步窗口（
SYNC_WINDOW_*），白天仅入队，夜间集中执行同步
9. 多服务器统一代码
- 业务仓库只保留一条 CD 入口：
build-and-notify.yml。 - 通过 GitHub Secrets 的
SYNC_WEBHOOK_URL指向不同服务器上的 sync-service，实现同代码多服务器复用。 - 通过 sync-service 环境变量
DEPLOY_AUTOPR_*配置各服务器的 deploy 目标（repo/branch/file），不需要改业务代码。 - 每个服务器执行一次
scripts/ops/apply-sync-autopr.sh初始化，后续只需提交代码即可自动部署。