审计 Flux CD GitOps…

在不连接集群的前提下，对本地 Flux CD GitOps 仓库做结构发现、Kubernetes schema 校验、废弃 API 检测、最佳实践与安全审查，并输出分级报告。

适用场景

解决思路

1. Phase 1 发现：运行 `scripts/discover.sh -d <repo-root>`（封装 `flux-schema discover`），读取输出 JSON 中 `.inventory` 下的 `summary`（文件/资源/行数）、`directories`（分类为 kubernetes-manifests、kustomize-overlay、helm-chart、terraform）、`resources`（按 group/version/Kind 计数）、`flux`（每个文件中的 Flux 资源）；多文档文件会被处理。
2. 读取 references/repo-patterns.md 的启发式表格，匹配并分类仓库模式。
3. 检测集群：查找 `clusters/` 下的目录或 `FluxInstance` 资源，阅读 FluxInstance 了解集群配置方式。
4. 检查 `flux-system/` 下是否存在 `gotk-sync.yaml`，若存在说明使用了 `flux bootstrap`，建议迁移到 Flux Operator 的 FluxInstance 资源，并在报告中始终附上迁移指南链接 https://fluxoperator.dev/docs/guides/migration/ 。
5. Phase 2 清单校验：用 `mktemp` 生成唯一临时路径作为 bundle（如 `bundle="$(mktemp "${TMPDIR:-/tmp}/flux-audit-bundle.XXXXXX" 2>/dev/null || true)"`），再运行 `scripts/validate.sh -d <repo-root> ${bundle:+-b "$bundle"}`；bundle 绝不能写在仓库内，避免并发审计互相覆盖；若 tmp 不可写则 mktemp 失败、脚本不带 bundle 运行。
6. 校验脚本会验证每个清单及每个 Kustomize overlay 的渲染输出，发现无效资源或构建失败时以非零退出并给出计数；加密 Secret 和无 schema 的第三方 CRD 会被优雅跳过，视为预期而非失败；`-b` 会把所有清单与渲染 overlay 合并进 `$bundle`，每段带 `# === file/kustomize-overlay: … ===` 来源注释。
7. 用 `-e <dir>` 排除额外目录不参与校验。
8. 若仓库向名称或命名空间做变量替换（如 `name: apps-${app_env}`），schema 正则会在原始 `${...}` 文本上失败；从仓库的变量 ConfigMap 和 `postBuild.substitute` 字面量构建 dotenv 文件（写到临时路径），用 `-E <dotenv>` 重跑，使清单在 `flux envsubst` 之后校验，与集群所见一致。
9. Phase 3 API 合规：运行 `scripts/check-deprecated.sh -d <repo-root>`，它执行 `flux migrate -f . --dry-run`，输出每个废弃 API 的精确文件路径、行号、资源 Kind 及所需版本迁移；退出码 1 表示发现废弃 API。
10. 若发现废弃 API，阅读 references/api-migration.md 获取迁移步骤并写入报告。
11. Phase 4 最佳实践：完整阅读 references/best-practices.md（不要只做摘要），按每个适用类别评估仓库；并非所有清单项都适用于每个仓库，需根据仓库模式、规模和成熟度判断。
12. 按发现结果聚焦相关类别：Monorepo 检查结构、ArtifactGenerator 用法、依赖链；目录驱动的 monorepo（ArtifactGenerator `pathPattern` + `ExternalArtifact` provider）应归类为此模式，缺少手写 per-app Kustomization 是设计意图而非缺陷；多仓库 fleet 检查 RBAC、多租户、ServiceAccount；有 HelmRelease 检查 remediation、漂移检测、版本管理；有 valuesFrom 或 substituteFrom 时在仓库中找到被引用的 ConfigMap/Secret，验证其带 `reconcile.fluxcd.io/watch: "Enabled"` 标签，否则这些资源变更不会触发协调直到下个 interval；有镜像自动化检查 ImagePolicy semver 范围与更新路径；有 ResourceSet 检查 `dependsOn` 命名空间、`wait: true`（与 `spec.steps` 搭配时强制）、Job 注解（`force`、不要 `ttlSecondsAfterFinished`、仅在幂等时用 `recreateOnFailure`）、step 与 applier 超时；有 ArtifactGenerator 验证 FluxInstance 列出 `source-watcher`，且 overlay 引用 `../../base` 时 `pathPattern` 生成器同时复制 base 和 overlay；有 `postBuild.substitute` 或变量 ConfigMap 时检查替换值不以 YAML 指示符开头（如 `>=1.0.0`）、`spec.images[].name` 等于 base 清单中写入的镜像引用、`substituteFrom` 目标存在于同一命名空间；有 Kustomize overlay 时 grep `$bundle`（若已写入）查看渲染后的资源，因为 overlay 的 `patch`/`images` 会改变生效清单，引用行号时用原始文件。
13. 检查相似资源之间的一致性：例如部分 HelmRelease 用现代 `install.strategy` 而其他用旧式 `install.remediation.retries` 时，标记不一致并建议统一到现代模式。
14. 在建议任何 YAML 改动前，对照 `assets/schemas/` 的字段索引核实精确字段名、类型和嵌套；索引文件命名规则为 `{kind}-{group}-{version}.fields.txt`（如 `helmrelease-helm-v2.fields.txt`、`kustomization-kustomize-v1.fields.txt`），每行是一个点分字段路径，可按路径前缀 grep 列出子树（如 `grep '^spec\.install\.' assets/schemas/helmrelease-helm-v2.fields.txt`）或按字段名 grep 定位；不要凭清单摘要猜测 YAML 结构。
15. Phase 5 安全审查：完整阅读 references/security-audit.md，按每个适用类别审计仓库，并使用清单末尾的扫描流程查找常见问题。
16. 按发现结果聚焦相关类别：有 Secret 检查密钥管理（SOPS、External Secrets）；有私有 source 检查源认证与 Workload Identity；有 OCI source 检查供应链安全（Cosign 验证、不可变 tag）；多租户检查 RBAC、ServiceAccount、跨命名空间引用、准入策略；有 FluxInstance 检查 operator 安全设置（multitenant、网络策略）；有跨命名空间 `sourceRef` 时始终报告，严重级别取决于租户模型：多租户仓库为 Critical，单团队仓库为 Warning，仅当 FluxInstance 显式设置 `multitenant: false` 且引用由 ResourceSet 生成（目录驱动 monorepo）时为 Info；有 `type: ExternalArtifact` 的 `ResourceSetInputProvider` 时在多租户集群检查 `serviceAccountName` 和 `selectors[].namespace: "*"` 范围；有镜像自动化检查推送凭据隔离与分支隔离；有 Kustomize overlay 时 grep `$bundle`（若已写入）查找 post-render 安全字段，例如 overlay patch 削弱了 `securityContext` 或重新打 tag 的镜像，这些在 base 文件中看不到。
17. Phase 6 报告：按适用情况组织为以下 markdown 章节——1) Summary：仓库名、仓库 URL、分类（模式名）、集群、Flux/K8s 资源计数、总体状态；2) Directory Structure：仓库布局及目录到集群/环境的映射；3) Validation Results：若发现错误；4) API Compliance：若发现废弃 API 则含迁移步骤；5) Best Practices：对照清单的评估与具体发现；6) Security：密钥、RBAC、网络策略、多租户；7) Recommendations：按严重级别排序为 Critical、Warning、Info。
18. 使用 Flux CRD 参考表核对 API 版本并在建议 YAML 改动前 grep 字段索引，表中列出各 controller 的 Kind、apiVersion 与对应字段索引文件（如 FluxInstance/FluxReport/ResourceSet/ResourceSetInputProvider 为 `fluxcd.controlplane.io/v1`，GitRepository/OCIRepository/Bucket/HelmRepository/HelmChart/ExternalArtifact 为 `source.toolkit.fluxcd.io/v1`，ArtifactGenerator 为 `source.extensions.fluxcd.io/v1beta1`，Kustomization 为 `kustomize.toolkit.fluxcd.io/v1`，HelmRelease 为 `helm.toolkit.fluxcd.io/v2`，Provider/Alert 为 `notification.toolkit.fluxcd.io/v1beta3`，Receiver 为 `notification.toolkit.fluxcd.io/v1`，ImageRepository/ImagePolicy/ImageUpdateAutomation 为 `image.toolkit.fluxcd.io/v1`）。
19. 按需加载参考文件：分类仓库布局或解释模式时读 repo-patterns.md；检查 Flux CRD 字段用法（sources、appliers、notifications、镜像自动化）时读 flux-api-summary.md；检查 Flux Operator CRD（FluxInstance、FluxReport、ResourceSet、ResourceSetInputProvider）时读 flux-operator-api-summary.md；评估运维实践或生成报告最佳实践章节时读 best-practices.md；执行安全审查阶段时读 security-audit.md；发现废弃 API 时读 api-migration.md 并把迁移步骤写入报告。
20. 处理边界情况：非 Flux 仓库（未发现 Flux CRD）要明确说明，可能使用 ArgoCD、纯 kubectl 或其他工具，不要强行套用 Flux 分析；混合工具链（Flux + CI + Terraform）只分析 Flux 部分并注明其他工具；带 `sops:` 元数据块的 SOPS 加密文件不要标记为 YAML 格式错误，校验脚本会剥离 SOPS 元数据后继续校验 Secret 其余部分；`flux-system/gotk-components.yaml` 由 Flux bootstrap 自动生成，不要对其做最佳实践分析；没有 kustomization.yaml 的仓库可能直接用纯 YAML 目录，Flux 可直接协调，不要把缺少 kustomization.yaml 当作错误；多仓库分析（fleet + infra + apps）时各自独立分析但注明跨仓库关系（仓库间的 GitRepository/OCIRepository 引用）；含 `${VARIABLE}` 模式的文件使用 Flux 变量替换，不要标记为损坏的 YAML，它们在协调时解析；无 catalog schema 的第三方 CRD（如 cert-manager `ClusterIssuer`）显示为 skipped 属预期而非校验失败；带 `apiVersion: kustomize.config.k8s.io/v1beta1` 的 `kustomization.yaml` 是 Kustomize 构建配置而非 Flux CRD。

适用边界 · 注意事项

• 仓库不是 Flux CD 管理的（未发现 Flux CRD，可能使用 ArgoCD、纯 kubectl 或其他工具）时，不要强行套用 Flux 分析。
• `flux-system/gotk-components.yaml` 这类由 Flux bootstrap 自动生成的文件，不要对其做最佳实践分析。
• 对 `kustomization.yaml`（`apiVersion: kustomize.config.k8s.io/v1beta1`）这类 Kustomize 构建配置，不要当作 Flux CRD 分析。