xiaobing.wang 3f5b941eac docs: clarify nodeport-based public entry

2026-03-31 14:34:38 +08:00

13 KiB

Raw Blame History

name	description
gitops-app-onboarding	面向当前 Baizhi GitOps 平台的项目接入工作流，只适用于 `deploy.baizhi.cloud`、`registry.baizhi.cloud`、GitLab + Argo CD 这套固定交付模型。只要用户提到“给当前平台接入新项目”“恢复 .gitlab-ci.yml / deploy 目录”“补齐当前平台的 Helm chart / release bundle”“修当前平台的发版链路”“让应用仓库在发版时推送自己的 release 结果”，就应优先使用这个 skill；如果只是通用 CI、通用 Helm 或通用 GitOps 任务而未指向当前平台，不应触发。

name

description

gitops-app-onboarding

面向当前 Baizhi GitOps 平台的项目接入工作流，只适用于 `deploy.baizhi.cloud`、`registry.baizhi.cloud`、GitLab + Argo CD 这套固定交付模型。只要用户提到“给当前平台接入新项目”“恢复 .gitlab-ci.yml / deploy 目录”“补齐当前平台的 Helm chart / release bundle”“修当前平台的发版链路”“让应用仓库在发版时推送自己的 release 结果”，就应优先使用这个 skill；如果只是通用 CI、通用 Helm 或通用 GitOps 任务而未指向当前平台，不应触发。

GitOps 项目接入 Skill

这个 skill 是 Baizhi GitOps 平台的接入入口与执行摘要。

执行不应依赖用户重复解释平台规则；按本 skill 与当前仓库约定直接推进即可。

目标是让 agent 能独立完成以下工作：

为应用仓库补齐或恢复 .gitlab-ci.yml
生成或修复 deploy/helm/<app>/ Chart
生成或修复 deploy/release/ release bundle
在发版链路中将当前应用自己的 release 结果推送到固定 GitOps 仓库

平台固定常量

除非用户明确要求修改，否则默认使用以下常量：

GitOps 仓库主机：deploy.baizhi.cloud
OCI Registry 主机：registry.baizhi.cloud
Helm OCI 仓库：oci://registry.baizhi.cloud/helm
GitOps 仓库克隆地址：https://deploy.baizhi.cloud/gitops-admin/argodeploy.git
Registry 用户名：registry-ci
共享镜像拉取 Secret：registry-pull-secret
GitOps 控制器：Argo CD
Chart 分发方式：OCI Registry
源代码托管：GitLab

应用仓库 CI 默认依赖以下 GitLab 变量：

GITEA_USER
GITEA_TOKEN
REGISTRY_PASSWORD

通常直接把 REGISTRY_USER 写成 registry-ci。

真相来源与读取顺序

开始改代码前，按下面顺序建立上下文：

先读目标应用仓库 README.md
再读 Dockerfile、包管理文件、构建脚本、现有 deploy 文件
如果用户给了额外设计文档，一并读取

判断规则：

目标应用仓库自己的 README.md 是应用运行架构的真相来源
本 skill 定义平台接入流程、约束和执行重点
如果应用 README 与平台约定冲突，优先识别是“应用设计差异”还是“平台硬约束”
如果冲突会直接改变最终实现且无法安全推断，再问用户；否则优先按已有代码和文档做最小偏差实现

在生成任何文件前，先推断出：

组件列表
每个组件的构建上下文
容器入口
对外暴露模型
运行时配置结构
哪些依赖属于平台共享，哪些是应用私有

不要假设每个项目都长得和现有项目一样。

先判断修改范围

先区分任务属于哪一种：

补齐或修复应用仓库中的 CI、Chart、release 模板
修复应用仓库中的发版链路，使其在发版时推送当前应用自己的 release 结果

边界约束：

本 skill 只处理应用仓库侧接入
不读取、不判断、不修改 GitOps 仓库中的 Application、AppProject 或其他发布侧清单
对 GitOps 的唯一动作，是在应用仓库 CI 中推送当前应用自己的 release 结果或版本引用

交付模型

平台采用两个仓库协同交付：

应用仓库负责源码、Docker 构建、.gitlab-ci.yml、Helm Chart 源码、release bundle 模板
当前 GitOps 仓库负责 Argo CD Application、AppProject、平台 bootstrap、已发布 release bundle、共享配置

标准发布流程：

分支或 MR 只跑测试
打 vX.Y.Z tag 后构建并推送镜像
打 vX.Y.Z tag 后打包并推送 Helm Chart
打 vX.Y.Z tag 后更新当前 GitOps 仓库中该应用的版本引用
推送当前 GitOps 仓库提交
Argo CD 感知当前 GitOps 仓库变更后自动同步

关键约束：

CI 不能直接调用 kubectl
CI 不能调用 argocd app sync
CI 不能把 hard refresh 当常规步骤
当前 GitOps 仓库的提交才是 Argo 的同步信号

如果线上故障需要 hard refresh，那是运维例外，不属于通用模板。

应用仓库通常需要生成什么

通常需要创建或修复：

.gitlab-ci.yml
deploy/helm/<app-name>/Chart.yaml
deploy/helm/<app-name>/values.yaml
deploy/helm/<app-name>/templates/*
deploy/release/metadata.yaml
deploy/release/values.yaml
deploy/release/secret.yaml

如果应用还有不适合放进 Chart 的静态清单，可以在后续发布结果中导出到当前 GitOps 仓库的 releases/<app>/manifests/。

GitLab CI 规则

stages

使用这三个 stage：

test
build
release

test job

test job 应运行在分支和 MR 上，并执行目标项目自己的标准测试命令。

要求：

安装该语言栈所需的最小依赖
如果依赖私有代码仓库，补齐认证
使用项目本身的标准测试入口，不要擅自发明新的测试命令

示例：

Go：go mod download、go test ./...
Node：npm ci、npm test

release 触发条件

发布链路只应在 vX.Y.Z 这种语义化 tag 上触发。

build-images job

这个 job 必须：

登录 registry.baizhi.cloud
构建项目所有需要发布的运行时镜像
将镜像推送到 registry.baizhi.cloud/<app-name>/<component>:<version>

如果仓库已经使用 BuildKit 或多构建上下文，优先使用 docker buildx。

如果镜像构建依赖私有 Git 仓库：

用 CI 凭据生成 .netrc
通过 Docker build secret 传入
如需额外 CA 证书，也通过 build secret 传入
不要通过全局关闭 TLS 校验规避问题

不要使用：

http://registry...
--plain-http
--insecure-skip-tls-verify

package-chart job

这个 job 必须：

执行 helm registry login registry.baizhi.cloud
将 Chart 的 version 和 appVersion 更新为 tag 去掉前缀 v 后的版本号
执行 helm package
推送到 oci://registry.baizhi.cloud/helm

update-gitops-repo job

这个 job 必须：

克隆 https://${GITEA_USER}:${GITEA_TOKEN}@deploy.baizhi.cloud/gitops-admin/argodeploy.git
只同步当前应用自己的 release 结果或版本引用
提交并推送到 main

通常需要更新：

releases/<app-name>/values.yaml
releases/<app-name>/metadata.yaml
releases/<app-name>/manifests/ 下由当前应用导出的发布结果

不要在这个 job 中加入集群部署逻辑。

Helm Chart 规则

Chart 必须反映应用的真实运行架构。

推荐结构：

deploy/helm/<app-name>/
├── Chart.yaml
├── values.yaml
└── templates/
    ├── _helpers.tpl
    ├── deployment-<component>.yaml
    ├── service-<component>.yaml 或 services.yaml
    └── 按职责拆分的其他资源

规则：

按职责拆文件，不要堆成一个巨大模板
模板中不要硬编码生产镜像 tag
所有镜像名都从 values 读取
所有 Service 暴露方式都从 values 读取
nginx 对外 Service 固定使用 NodePort
后端 Service 默认使用集群内访问类型，不对外暴露 NodePort
不要生成 Ingress 模板或 Ingress values
设置 enableServiceLinks: false
支持 imagePullSecrets
环境变量注入保持可读
健康检查要符合真实应用行为

_helpers.tpl 一般至少提供：

chart name
fullname
namespace
labels
selector labels

只有当项目本身确实有 path 推导的 URL 时，才增加 URL helper。

对外暴露模型

对外暴露模型使用固定方式，不再按项目自由选择。

固定使用 nginx 作为统一入口，代理前端与后端路径
对外只暴露 nginx 入口，并通过 NodePort 提供入口访问
后端服务默认只在集群内通信
不生成 Ingress 资源，也不要在 values 中保留 Ingress 开关
不要因为应用有多个内部服务，就擅自发明多个公网 host

如果项目当前没有现成的前端代理层，也应按这个固定模型为对外入口预留 nginx 代理方案，而不是改成 Ingress。

Release Bundle 规则

应用仓库中的 deploy/release/ 是导出给当前 GitOps 仓库的标准模板。

`metadata.yaml`

至少应包含：

应用名
Kubernetes release 名
namespace
chart 名
chart 版本
chart 仓库
镜像 tag
源码仓库地址

`values.yaml`

必须是可用于部署的默认值，而不是示例值。

至少应满足：

镜像地址指向 registry.baizhi.cloud/<app-name>/...
Secret 名符合平台约定
私有镜像拉取时包含 imagePullSecrets
与 Chart schema 保持一致
nginx 对外入口使用 NodePort
不包含 Ingress 配置项

`secret.yaml`

用于放应用私有 Secret 模板，key 名必须与 Chart 读取的 key 对齐。

规则：

不要为了“看起来完整”而伪造假的生产值
如果这些值是接入该应用所必需的，应在完成所有非阻塞工作后向用户索取
如果用户暂时没有提供，不要造占位内容冒充可部署配置
可以只保留结构，或暂不生成具体 secret 内容，但必须在最终输出中明确警告缺失项与影响

release bundle 只负责导出当前应用自己的发布结果，不负责维护 GitOps 仓库中的其他对象。

平台共享配置契约

shared/ 目录只放平台级共享配置。

共享资源：

platform-runtime-config
platform-shared-secrets
registry-pull-secret

当前 platform-runtime-config 提供：

LLM_BASE_URL
EMBEDDER_BASE_URL

当前 platform-shared-secrets 提供：

POSTGRES_USER
POSTGRES_PASSWORD
REDIS_PASSWORD
QDRANT_API_KEY
NEO4J_USERNAME
NEO4J_PASSWORD
MINIO_ACCESS_KEY
MINIO_SECRET_KEY

shared 边界：

shared 只负责共享基础设施和通用运行时地址
不要把某个厂商的客户端证书、私钥、应用专属 app_id、tenant id、client id、namespace id、应用独有 webhook 签名密钥放进 shared/
镜像拉取默认使用 registry-pull-secret，不要随便为每个应用再造一个 pull secret，除非平台模型发生变化

可选的百智云用户鉴权接入

有些应用支持可选的百智云用户鉴权接入。

处理规则：

不要把这类鉴权材料当成平台共享配置
不要擅自生成生产值
先完成所有非阻塞工作
如果 README 没明确说明是否启用，最后只问用户一个最小必要问题
如果用户确认需要接入，后续字段就视为必填，不要再把它们当成可选示例值
启用后按固定顺序向用户索取：app_id -> app.crt -> app.key -> ca.crt -> public.key
如果不需要，就跳过这部分百智云鉴权相关的 release values 和 secret 生成
如果用户需要但没有提供完整值，不要写伪造占位内容；在最终输出中明确警告缺失了哪些字段以及可能影响

提问方式要求：

只在真正阻塞最终可部署结果时才问
先做完不依赖这些值的工作
先确认是否启用百智云用户鉴权，再按固定顺序逐项索取必填材料
不要用“把需要的都给我”这种模糊问法
缺少任一必填项时，要明确指出当前卡在哪一项

执行流程

建议按下面顺序推进：

读取应用 README 与构建文件，梳理组件和暴露模型
判断任务是补齐应用仓库接入，还是修复发版链路
生成或修复 .gitlab-ci.yml
生成或修复 Chart 与 values
生成或修复 release bundle
完成非阻塞工作后，再处理可选的百智云用户鉴权提问
自检并在最终输出中说明风险点

自检要求

完成后尽量执行：

git status --short
git diff --check
helm template，前提是 Chart 与 values 已能渲染

至少确认：

应用仓库不再缺少接入文件
.gitlab-ci.yml 包含 test、镜像构建、chart 发布、release 结果同步逻辑
release values 指向 registry.baizhi.cloud
GitOps 仓库更新 job 指向 https://deploy.baizhi.cloud/gitops-admin/argodeploy.git
CI 中没有直接调用 Argo
没有继续使用旧域名
没有继续使用不安全的 HTTP registry 访问方式
如果存在用户未提供的必填私有配置，最终输出中已明确列出缺失项和潜在影响

最终输出要求

默认按下面结构汇报：

修改了哪些文件
关键设计决策
最值得人工复核的 3 个点

如果存在用户未提供的必填私有配置，额外增加“缺失项警告”，明确列出：

缺少哪些字段
因此哪些配置尚未完成
不补齐会影响什么，例如无法直接部署、某功能未启用、secret 仍为空

常见错误

以下都属于接入错误：

把应用私有鉴权材料放进 shared/
在 CI 里直接刷新 Argo
重新引入已废弃的旧域名
在 HTTPS 已恢复后仍使用 insecure registry 参数
生成的 Chart 与应用真实组件不匹配
在生产 release values 中写 registry.example.com 这类示例地址
应用没有这个设计却擅自发明新的公网 host
在用户没有提供必填私有值时，仍然伪造占位内容并假装可以直接部署

13 KiB Raw Blame History Unescape Escape

GitOps 项目接入 Skill

平台固定常量

真相来源与读取顺序

先判断修改范围

交付模型

应用仓库通常需要生成什么

GitLab CI 规则

stages

test job

release 触发条件

build-images job

package-chart job

update-gitops-repo job

Helm Chart 规则

对外暴露模型

Release Bundle 规则

metadata.yaml

values.yaml

secret.yaml

平台共享配置契约

可选的百智云用户鉴权接入

执行流程

自检要求

最终输出要求

常见错误

13 KiB

Raw Blame History

`metadata.yaml`

`values.yaml`

`secret.yaml`