conti-docs/backend/07-config-governance.md

07. 配置与服务治理

决策

K8s 原生方案：ConfigMap + Secret + Spring Cloud Kubernetes，不引入 Nacos 等额外治理组件，贴合已有 Azure + GitLab CI/CD 部署方式（见 Architecture-Diagram/deployment-architecture-diagram.drawio）。

选这条路而不是 Spring Cloud Alibaba（Nacos）的原因：部署环境已经是 K8s，K8s 本身自带 Service（服务发现）、ConfigMap/Secret（配置）、Deployment 滚动更新（发布），再引入 Nacos 意味着多维护一套集群、多一套"配置到底以谁为准"的心智负担。除非未来有 Nacos 才能提供、K8s 原生方案覆盖不了的能力（比如更细粒度的灰度配置推送），否则先用 K8s 原生的就够。

结构约定

• 非敏感配置（菜单开关、超时参数、日志级别等）放 ConfigMap，挂载成 application-{profile}.yml 或环境变量。
• 敏感配置（DB 密码、JWT secret、F6 API key）放 Secret，都不进代码库、不进镜像。
• 各环境（dev/uat/prod）对应各自 namespace 下的 ConfigMap/Secret + Spring profile，bootstrap 按 SPRING_PROFILES_ACTIVE 加载对应配置。

ConfigMap / Secret 示例

# k8s/configmap-workbench-uat.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: conti-backend-config
  namespace: retailapp-uat
data:
  application-uat.yml: |
    resilience4j:
      circuitbreaker:
        instances:
          f6-api:
            failure-rate-threshold: 50
    workbench:
      degrade-message: "部分数据暂时无法显示，请稍后刷新"

# k8s/secret-uat.yaml（实际值由 CI/CD 从密钥管理服务注入，不手写明文提交）
apiVersion: v1
kind: Secret
metadata:
  name: conti-backend-secret
  namespace: retailapp-uat
type: Opaque
stringData:
  SECURITY_JWT_SECRET: "__injected_by_pipeline__"
  DB_PASSWORD: "__injected_by_pipeline__"
  F6_API_KEY: "__injected_by_pipeline__"

# k8s/deployment-uat.yaml（节选）
spec:
  containers:
    - name: conti-backend
      image: registry.example.com/conti-backend:__TAG__
      envFrom:
        - secretRef:
            name: conti-backend-secret
      env:
        - name: SPRING_PROFILES_ACTIVE
          value: uat
      volumeMounts:
        - name: config-volume
          mountPath: /app/config
  volumes:
    - name: config-volume
      configMap:
        name: conti-backend-config

启用 Spring Cloud Kubernetes 配置热更新

// bootstrap/build.gradle
dependencies {
    implementation 'org.springframework.cloud:spring-cloud-starter-kubernetes-client-config'
}

# application.yml
spring:
  cloud:
    kubernetes:
      config:
        enabled: true
        sources:
          - name: conti-backend-config
      reload:
        enabled: true
        mode: polling # 定期轮询 ConfigMap 变化，无需重启 Pod
        period: 15s

// 需要热更新的配置类加 @RefreshScope
@RefreshScope
@ConfigurationProperties(prefix = "workbench")
@Component
class WorkbenchProperties {
    var degradeMessage: String = "部分数据暂时无法显示"
}

本地开发怎么跑（不需要真的连 K8s）

spring-cloud-starter-kubernetes-client-config 启动时默认会尝试读 ~/.kube/config 或 in-cluster 凭证去调 K8s API 拿 ConfigMap，本地电脑上没有这些东西的话，启动会报错或者卡住去连一个不存在的 API Server。本地开发不需要也不应该依赖真实 K8s，两种可选方案：

方案一（推荐，日常开发默认用这个）：本地 profile 直接关掉 Spring Cloud Kubernetes

# application-local.yml
spring:
  cloud:
    kubernetes:
      config:
        enabled: false   # 本地不连 K8s API，配置全部走本地文件
      reload:
        enabled: false
  datasource:
    url: jdbc:postgresql://localhost:5432/conti_backend
    username: conti
    password: conti_local_password   # 仅本地开发用，不是真实密钥
security:
  jwt:
    secret: local-dev-only-secret-not-for-real-use

# 本地起依赖（DB 等），配合 docker-compose 用
docker compose up -d postgres

# 用 local profile 启动
SPRING_PROFILES_ACTIVE=local ./gradlew :bootstrap:bootRun

application-local.yml 不提交敏感真实值（本来也没有，本地密码本身就是假的），可以放进代码库方便新人直接跑起来；local profile 和 dev/uat/prod 的关键区别就是 spring.cloud.kubernetes.config.enabled=false，其余代码逻辑完全一致——这也是为什么 06-api-design.md 强调的"配置外置"很重要：业务代码不知道、也不需要知道配置到底来自 K8s 还是本地文件。

这是个人本机调试用的，跟团队共享的 Dev 环境不是一回事——Dev 环境跑在公司内网一台 Ubuntu 服务器的 k3s 集群上，走真实的 K8s ConfigMap/Secret（跟下面"方案二"是同一套思路，只是长期跑着给团队用，而不是临时验证），团队通过公司 VPN 访问，具体见 09-build-deploy.md。

方案二（需要验证 ConfigMap 热更新等 K8s 特有行为时才用）：本地起一个真实的小集群

用 Docker Desktop 自带的 Kubernetes、Kind（Kubernetes in Docker）或 Minikube 在本机跑一个单节点集群，把上面"ConfigMap / Secret 示例"里的 yaml 应用到本地集群，验证 @RefreshScope 热更新、ServiceAccount 权限这些真正依赖 K8s API 的行为：

kind create cluster --name conti-local
kubectl config use-context kind-conti-local

kubectl create namespace retailapp-local
kubectl apply -f k8s/configmap-local.yaml -n retailapp-local
kubectl apply -f k8s/secret-local.yaml -n retailapp-local

# 应用本身也可以跑成本地集群里的 Pod（用本地构建的镜像），
# 或者在宿主机直接跑 jar、用 KUBECONFIG 指向 kind 集群验证配置读取
export KUBECONFIG=~/.kube/config
SPRING_PROFILES_ACTIVE=dev ./gradlew :bootstrap:bootRun

日常业务开发用方案一就够了，只有专门验证"配置中心相关能力本身"（比如调试 spring.cloud.kubernetes.reload 轮询逻辑）才需要方案二。

关键规则

• 配置变更优先走 ConfigMap 热更新（@RefreshScope + spring.cloud.kubernetes.reload），不重新构建镜像；涉及 Secret 轮换的走正常发布流程（Secret 变化通常需要重启 Pod 才能生效，不像 ConfigMap 可以做到无重启热更）。
• 对应架构图里 Config Center（菜单配置、开关配置、WebView 入口策略）暂时也落在 ConfigMap；如果后续配置项复杂到需要审批流程、按门店灰度下发、版本回滚，再评估引入独立配置中心（比如 Apollo）。
• Pod 需要有权限读取所在 namespace 的 ConfigMap（spring-cloud-kubernetes 底层调用 K8s API），需要配置好对应的 ServiceAccount + Role/RoleBinding。

附录：ConfigMap 和 Secret 的本质区别，以及为什么两者都要用

两者在 K8s API 层面结构几乎一样，都是 key-value 集合，区别主要在于：

• Secret 的值默认 base64 编码存储（不是加密，只是编码），K8s 对 Secret 有一些额外处理：不会出现在 kubectl describe 的默认输出里、可以配置只挂载到内存卷（tmpfs）不落盘、可以对接外部密钥管理服务（Azure Key Vault 等）做真正的静态加密和访问审计。
• ConfigMap 没有这些额外保护，设计上就是给"泄漏了也不严重"的配置用的。

所以规则很简单：这个值如果出现在日志里、被同事在 kubectl get configmap -o yaml 时看到会不会造成安全问题——会，就放 Secret；不会，就放 ConfigMap。DB 密码、JWT 签名密钥、第三方 API key 毫无疑问要放 Secret；而"首页降级提示文案"这种放哪都无所谓的东西放 ConfigMap 就行，还能享受到热更新不用走发布流程的好处。

Azure 上 Secret 的真正来源：Key Vault（不是手写 K8s Secret）

前面 k8s/secret-uat.yaml 示例里 stringData 写的是占位符（__injected_by_pipeline__），这一节说清楚这个占位符具体是怎么被替换成真实值的。

根据现有部署架构（见 Architecture-Diagram/deployment-architecture-diagram.drawio），我们的 AKS 是 Private AKS Cluster，Key Vault 也是通过 Private Endpoint（privatelink.vaultcore.azure.net）访问的——也就是说真实密钥长期存在 Azure Key Vault 里，代码库、镜像、Git 历史里都不出现明文。落地到 K8s Secret 有两种方式，我们现在用的是方式一（跟 CI/GitLab 侧的配置习惯一致，不需要额外在 AKS 上装东西）。

方式一（现用）：CI/CD 流水线在部署前从 Key Vault 读值，渲染成 K8s Secret

# GitLab CI job 里（Runner 需要有权限访问 Key Vault，见 09-build-deploy.md）
JWT_SECRET=$(az keyvault secret show --vault-name conti-backend-kv --name security-jwt-secret --query value -o tsv)
kubectl create secret generic conti-backend-secret \
  --namespace retailapp-uat \
  --from-literal=SECURITY_JWT_SECRET="$JWT_SECRET" \
  --dry-run=client -o yaml | kubectl apply -f -

• 密钥值只在 CI job 的执行过程中短暂出现（不会写进 CI 日志、不会落盘到镜像里），kubectl apply 之后就是一个普通的 K8s Secret，Deployment 照常用 envFrom.secretRef 引用（见前面 k8s/deployment-uat.yaml 示例）。
• 好处是不需要在 AKS 上额外装插件、不需要给节点/Pod 配置 Managed Identity 绑定，全部配置集中在 GitLab（CI 变量里存 Runner 访问 Key Vault 所需的 Service Principal/Managed Identity，业务代码和 K8s yaml 完全不感知 Key Vault 的存在），跟本地开发用 application-local.yml 手工填值、只是"谁来填值"变成了流水线,心智负担更小。
• 权衡：Key Vault 里密钥更新后，不会自动同步到已经跑着的 Secret，需要重新跑一次部署（或专门加一个"仅同步 Secret，不发版本"的 job）才能生效——这点上不如方式二自动。日常密钥轮换频率不高的情况下这个权衡是划算的。

方式二（可选的未来增强）：CSI Secret Store Driver，运行时直接挂载，K8s Secret 不落地明文

展开查看（AKS 需装 `azure-keyvault-secrets-provider` 插件 + 配置 Managed Identity，运维成本更高，暂不采用）

# k8s/secretproviderclass-uat.yaml
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: conti-backend-kv-uat
  namespace: retailapp-uat
spec:
  provider: azure
  parameters:
    usePodIdentity: "false"
    useVMManagedIdentity: "true"        # 用 AKS 节点/Pod 的 Managed Identity 免密访问 Key Vault
    userAssignedIdentityID: "<managed-identity-client-id>"
    keyvaultName: "conti-backend-kv"
    tenantId: "<azure-tenant-id>"
    objects: |
      array:
        - |
          objectName: security-jwt-secret
          objectType: secret
  secretObjects:                         # 顺便同步成一个 K8s Secret，供 envFrom 引用
    - secretName: conti-backend-secret
      type: Opaque
      data:
        - objectName: security-jwt-secret
          key: SECURITY_JWT_SECRET

优点是密钥更新后 CSI driver 会定期轮询自动同步、Pod 用 Managed Identity 直连 Key Vault 不经过 CI；代价是要在 AKS 上启用插件、每个环境配置对应的 SecretProviderClass 和身份绑定，运维配置面更大。如果以后密钥轮换频率变高、或者审计要求"密钥不能经过 CI 执行上下文"，再切换到这条路径，现阶段先用方式一。

两种方式不需要同时维护——选一个用，文档里保留方式二只是留个参考路径，不是说两者要并存。

待补充

• 具体 ConfigMap/Secret 命名规范和 namespace 划分细节。
• 多环境 profile 的详细参数列表。

参考链接

• Spring Cloud Kubernetes 官方文档
• Kubernetes ConfigMap 官方文档
• Kubernetes Secret 官方文档