From 4a959cafc27be2123ff0bc0a17adcd4992314593 Mon Sep 17 00:00:00 2001 From: "xiaobing.wang" Date: Tue, 28 Apr 2026 11:40:54 +0800 Subject: [PATCH] docs: make image tags rollback-safe --- gitops-app-onboarding/SKILL.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/gitops-app-onboarding/SKILL.md b/gitops-app-onboarding/SKILL.md index a27fb7f..a059998 100644 --- a/gitops-app-onboarding/SKILL.md +++ b/gitops-app-onboarding/SKILL.md @@ -180,6 +180,7 @@ Go 项目默认变量写在 `.gitlab-ci.yml` 的 `variables:`： - `helm registry login registry.baizhi.cloud` - 在临时目录复制 `deploy/helm//` - 把复制品中的 `version` 和 `appVersion` 改成 tag 版本 +- 业务镜像的默认 tag 必须跟随 `appVersion`，不要依赖 release values 覆盖业务镜像 tag - `helm package` - `helm push` @@ -201,7 +202,7 @@ Go 项目默认变量写在 `.gitlab-ci.yml` 的 `variables:`： 3. 将应用仓库中的 `deploy/release/metadata.yaml` 和 `deploy/release/values.yaml` 复制到 GitOps 仓库的 `releases//metadata.yaml` 与 `releases//values.yaml`，覆盖已有内容 4. 保留已有的 `releases//manifests/kustomization.yaml` 与 `releases//manifests/db-secret.yaml` 5. 将 `deploy/release/secret.yaml` 物化为 `releases//manifests/secret.yaml` -6. 替换 `releases//metadata.yaml` 和 `releases//values.yaml` 中的 `__VERSION__` +6. 替换 `releases//metadata.yaml` 中的 `__VERSION__`；只有第三方镜像、非业务版本字段或明确需要的环境配置才允许替换 `releases//values.yaml` 中的 `__VERSION__` 7. 更新 `apps//application.yaml` 中当前应用 chart source 的 `targetRevision` 8. 只有存在 diff 时才提交并推送 `main` @@ -220,6 +221,9 @@ Chart 必须反映应用的真实运行架构。 - 按职责拆文件，不堆一个大模板 - 模板中不硬编码生产 tag - 所有镜像名从 values 读取 +- 应用自己构建的业务镜像 tag 默认必须来自 `.Chart.AppVersion`，values 中的 tag 只能作为显式覆盖项 +- Deployment 模板必须使用类似 `{{ default .Chart.AppVersion .Values..image.tag }}` 的逻辑渲染业务镜像 tag +- `deploy/helm//values.yaml` 中业务镜像 `tag` 默认写空字符串或不写，不要写生产版本号 - 所有 Service 暴露方式从 values 读取 - nginx 对外 Service 固定使用 `NodePort` - 后端 Service 只做集群内访问 @@ -283,11 +287,14 @@ Chart 必须反映应用的真实运行架构。 至少满足： - 应用自建镜像使用 `registry.baizhi.cloud//...` +- 应用自建镜像不要在 release values 中写业务版本 tag；业务镜像 tag 默认由 Chart `appVersion` 决定，以便 Argo CD UI 回滚 Chart 版本时镜像版本同步回滚 - 第三方镜像保持真实来源 +- 第三方镜像 tag 必须继续显式写在 values 中，不要跟随 Chart `appVersion` - Secret 名与 Chart 约定一致 - PostgreSQL 连接读取应用自己的 `databaseSecret` - 私有镜像包含 `imagePullSecrets` - 与 Chart schema 一致 +- 不要包含 `backend.image.tag`、`server.image.tag`、`frontend.image.tag`、`nginx.image.tag` 等应用自建业务镜像版本覆盖，除非用户明确要求做一次性特殊覆盖 - nginx 对外入口使用 `NodePort` - `NodePort` 值来自用户或平台分配结果 - 不包含 Ingress 配置项 @@ -419,7 +426,9 @@ Chart 必须反映应用的真实运行架构。 - 接入文件齐全 - `.gitlab-ci.yml` 包含 test、镜像构建、Chart 发布、GitOps 同步 - release values 指向 `registry.baizhi.cloud` +- release values 不覆盖应用自建业务镜像 tag；业务镜像 tag 由 Chart `appVersion` 默认决定 - 第三方镜像没有被错误改写到平台 registry +- 第三方镜像仍显式固定 repository 和 tag，且没有错误跟随 Chart `appVersion` - 如果 Dockerfile 原本使用 Docker Hub 源，已切换到 `registry-mirrors.dev.in.chaitin.net`，且未误改其他非 Docker Hub 镜像源 - 如果 Dockerfile 中使用 `apk`，已切换到中科大源 - GitOps update job 指向 `https://deploy.baizhi.cloud/gitops-admin/argodeploy.git` @@ -448,6 +457,7 @@ Chart 必须反映应用的真实运行架构。 - 使用 insecure registry 参数 - Chart 与应用真实组件不匹配 - 在生产 release values 中写示例地址 +- 在 release values 中写应用自建业务镜像 tag，导致 Argo CD UI rollback 只回滚 Chart 但镜像仍被 `main` 上的 values 固定到新版本 - 擅自发明新的公网 host - 在未检测到私有 Git 依赖中的 `git.in.chaitin.net/ai/baizhiyun/opensdk` 时仍强行接入百智云 - Dockerfile 明明使用了 Docker Hub / `apk` 默认源，却没有切到 `registry-mirrors.dev.in.chaitin.net` / 中科大源，或误改了原本不在 Docker Hub 的镜像源