4. Helm values.yaml 结构：全局参数与镜像参数定义规范

在 Helm Chart 中，values.yaml 是用户与 Chart 交互的核心接口。一个设计良好的 values.yaml 结构，能够大幅降低运维复杂度，尤其在需要统一管理镜像拉取加速配置的场景下，全局参数与镜像参数的合理分层至关重要。本章将深入解析这两类参数的定义规范、层级关系及最佳实践。

4.1 全局参数 vs 镜像参数：职责分离

全局参数（Global Parameters）作用于整个 Release 或跨多个组件，而镜像参数（Image Parameters）仅控制单个容器的镜像拉取行为。错误的参数层级会导致配置冲突或覆盖失效。

4.2 标准 values.yaml 层级结构

以下是一个面向镜像拉取加速场景的推荐 values.yaml 骨架，包含全局段和镜像段：

# ============================================
# 全局配置段（作用于所有组件）
# ============================================
global:
  # 全局镜像仓库镜像（Mirror）地址
  imageRegistry: "mirror.example.com"
  # 全局镜像拉取凭证
  imagePullSecrets:
    - name: regcred-global
  # 全局代理配置（用于拉取外网镜像）
  proxy:
    httpProxy: "http://proxy.example.com:8080"
    httpsProxy: "http://proxy.example.com:8080"
    noProxy: "localhost,127.0.0.1,.cluster.local"
  # 全局拉取加速开关
  imagePullAcceleration:
    enabled: true
    cacheTTL: "24h"
    concurrency: 5

# ============================================
# 组件配置段（每个组件独立定义）
# ============================================
componentA:
  enabled: true
  image:
    repository: "nginx"
    tag: "1.25.3-alpine"
    pullPolicy: "IfNotPresent"
    # 组件级镜像仓库覆盖（优先级高于 global.imageRegistry）
    registry: "docker.io"
    # 组件级拉取凭证覆盖
    pullSecrets:
      - name: regcred-componentA
    # 组件级加速配置
    acceleration:
      enabled: true
      # 使用全局 Mirror 还是自定义 Mirror
      mirrorType: "global"   # 可选: global / custom / none
      customMirror: ""       # 当 mirrorType=custom 时填写

componentB:
  enabled: true
  image:
    repository: "redis"
    tag: "7.2.4"
    pullPolicy: "Always"
    registry: ""             # 留空则使用全局 registry
    pullSecrets: []          # 空列表则使用全局 secrets
    acceleration:
      enabled: false         # 该组件跳过加速
      mirrorType: "none"

4.3 镜像参数定义规范详解

镜像参数是 Helm Chart 中最常被修改的配置项，其定义规范直接影响拉取加速的灵活性和可维护性。

4.3.1 核心字段规范

4.3.2 加速专用字段规范

4.4 全局参数与镜像参数的合并逻辑

理解 Helm 的 values 合并顺序，是避免配置冲突的关键。以下 SVG 图展示了从全局到组件的参数解析流程：

4.5 最佳实践：加速场景下的 values 设计模式

4.5.1 分层覆盖模式

推荐使用三层覆盖结构，确保灵活性与可维护性：

1. Chart 内置默认值（values.yaml）：定义最安全的基线配置，例如 global.imageRegistry: "k8s.gcr.io"。
2. 环境级覆盖（values-production.yaml）：针对生产环境统一修改全局加速参数，例如 global.imageRegistry: "mirror.company.com"。
3. 组件级覆盖（--set 或独立 values）：针对特定组件的特殊需求，例如某个第三方组件必须从原始仓库拉取。

4.5.2 加速配置的模板辅助函数

在 _helpers.tpl 中定义辅助函数，统一处理镜像地址拼接和加速逻辑：

{{- define "common.image" -}}
{{- $registry := .Values.global.imageRegistry -}}
{{- if .Values.image.registry -}}
  {{- $registry = .Values.image.registry -}}
{{- end -}}
{{- if and .Values.acceleration.enabled (eq .Values.acceleration.mirrorType "custom") -}}
  {{- $registry = .Values.acceleration.customMirror -}}
{{- end -}}
{{- if $registry -}}
  {{- printf "%s/%s:%s" $registry .Values.image.repository .Values.image.tag -}}
{{- else -}}
  {{- printf "%s:%s" .Values.image.repository .Values.image.tag -}}
{{- end -}}
{{- end -}}

4.6 参数定义规范检查清单