microservice-helm

📦 Kubernetes 配置管理方案 - 文件清单和使用指南

新增：统一的 ConfigMap/Secret 入口（两文件管全局）

自本次调整起，所有微服务的非敏感配置与敏感凭证统一由两处入口管理：

• 配置入口：values.yaml（读取 conf//* 自动生成每个服务的 ConfigMap）
• 凭证入口：values-secrets.yaml（.Values.secrets 下定义的条目自动生成 Secret）

实现细节：

• 伞状（Umbrella）Chart 保留；子 Chart 的 ConfigMap 渲染由基础库模板控制，默认关闭。
• 统一模板：templates/unified-configmaps.yaml 与 templates/unified-secrets.yaml。
• 开关：.Values.global.enableConfigMapManagement 与 .Values.global.enableSecretManagement（默认开启）。

使用方式：

# 渲染（示例）
helm upgrade --install shop-recycle ./ \
   -f values.yaml \
   -f values-secrets.yaml

# 仅渲染某环境可再叠加 environment 覆盖
# helm upgrade --install shop-recycle ./ -f values.yaml -f values-secrets.yaml -f environments/prod.yaml

注意事项：

• 子 Chart 若需继续使用各自 ConfigMap，可在子 Chart values 中显式设置 config.enabled: true。
• 统一 ConfigMap 名称规范：<service>-config，与子部署挂载一致（/etc/config 或 /app/conf）。
• Secret 数据值将自动进行 Base64 编码；请在 values-secrets.yaml 中放入明文或占位符（如 ${DB_USERNAME}）。

🎯 本次完成内容总结

基于 conf/ 文件夹中 34 个微服务的配置文件，生成了完整的 Kubernetes 部署方案，包括：

✅ 34 个微服务配置分析
✅ 7 种共享 Secret 模板
✅ 通用 ConfigMap/Deployment 模板
✅ 完整部署指南和故障排查
✅ 自动化脚本

---

📂 文件清单

📖 文档（4 个）

1. CONFIG-MANAGEMENT-SUMMARY.md ⭐ 👈 从这里开始

目的： 项目总体概览
内容：

• 完成内容汇总
• 配置分析结果（34 个服务统计）
• 推荐的配置架构
• 快速部署步骤
• 安全建议

适合： 所有用户快速了解整体方案

---

2. CONFIG-AND-SECRET-STRATEGY.md

目的： 深度配置策略分析
内容：

• 完整的敏感信息分类（7 种）
• 每个敏感信息类型的详细说明
• 26 个后端服务详细分类
• 8 个 Web 服务分类
• 5 个微信服务分类
• Secret 和 ConfigMap 分割方案
• 3 种实施方案对比（全局/分组/按类型）

适合： 架构师、技术决策者、安全团队

---

3. K8S-DEPLOYMENT-GUIDE.md

目的： 完整实施和运维指南
内容：

• 5 步部署流程（详细命令）
• 验证部署的 8 个步骤
• 4 大常见问题及解决方案
• 最佳实践（5 方面）
• Secret 管理安全建议
• 发布流程规范

适合： DevOps、运维人员、开发人员

---

4. CONFIG-MANAGEMENT-SUMMARY.md（本文件）

目的： 快速参考和清单
内容：

• 文件索引
• 快速命令
• 实施清单
• 文件关系图

适合： 快速查阅和任务管理

---

🔐 Secret 模板（1 个文件，7 种 Secret）

secret-templates-common.yaml

共 7 个公共 Secret：

1. common-db-credentials
   ├─ db-username: root
   ├─ db-password: Fxjxtdacf8f_a3d_202600104d6c_41
   ├─ db-host: rm-bp19t90t7u8n5b0fh.mysql.rds.aliyuncs.com
   └─ db-port: 3306
   使用：26 个后端服务

2. common-redis-credentials
   ├─ redis-password: 3sm_redis
   ├─ redis-database: 15
   ├─ redis-sentinel-master: mymaster
   └─ redis-sentinel-nodes: redis.jxfx[1-3].com:27000
   使用：30+ 个服务

3. common-rabbitmq-credentials
   ├─ rabbitmq-username: guest
   ├─ rabbitmq-password: guest
   ├─ rabbitmq-host: mq.bak.com
   └─ rabbitmq-port: 5672
   使用：20+ 个服务

4. wechat-credentials
   ├─ store-app-id/secret
   ├─ merchant-app-id/secret
   ├─ buy-app-id/secret
   └─ aibao-app-id/secret
   使用：5 个微信服务

5. nacos-credentials
   ├─ nacos-username: nacos
   ├─ nacos-password: nacos
   └─ nacos-server-address: nacos.bak.com:8848
   使用：所有服务

6. seata-credentials
   ├─ seata-username: nacos
   ├─ seata-password: nacos
   └─ seata-server-address: nacos.bak.com:8848
   使用：2-3 个分布式事务服务

7. mongodb-credentials
   ├─ mongodb-username: root
   ├─ mongodb-password: 123456
   ├─ mongodb-host: mg.bak.com
   ├─ mongodb-port: 27017
   └─ mongodb-database: recycle
   使用：2-3 个 MongoDB 服务

使用方法：

1. 编辑文件，将 Base64 值替换为实际凭证的 Base64 编码
2. 运行 kubectl apply -f secret-templates-common.yaml
3. 所有 34 个服务都可以引用这些 Secret

---

📦 配置和部署模板（2 个文件）

service-configmap-deployment-template.yaml

包含 3 个可复用的模板：

1. 通用 ConfigMap 模板
   - 占位符：[SERVICE_NAME], [PORT], [CONTEXT_PATH] 等
   - 包含非敏感配置示例
   - 包含如何从 Secret 注入敏感值的注释

2. 通用 Deployment 模板
   - 占位符：[SERVICE_NAME], [IMAGE_REGISTRY], [REPLICAS] 等
   - 包含完整的环境变量注入示例
   - 包含资源限制、健康检查、优雅关闭等最佳实践

3. 通用 Service 模板
   - 占位符：[SERVICE_NAME], [PORT] 等
   - 支持 ClusterIP、NodePort 多种类型

使用方法：

1. 复制对应的模板
2. 使用 sed 或文本编辑器替换占位符
3. 为每个服务生成对应的 YAML
4. 运行 kubectl apply -f

---

Gateway 相关 3 个文件（已优化）

gateway-configmap.yaml    # Gateway 配置（敏感字段已参数化）
gateway-deployment.yaml   # Gateway 部署（已集成 Secret）
gateway-service.yaml      # Gateway 服务（支持多种类型）

特点：

• ✅ 已从配置文件中提取非敏感部分
• ✅ 敏感字段使用环境变量占位符（${REDIS_PASSWORD} 等）
• ✅ 已正确配置 Secret 引用
• ✅ 包含完整的健康检查和优雅关闭

部署方式：

# 1. 先部署 Secret（一次性）
kubectl apply -f secret-templates-common.yaml

# 2. 然后部署 Gateway
kubectl apply -f gateway-configmap.yaml
kubectl apply -f gateway-deployment.yaml
kubectl apply -f gateway-service.yaml

# 3. 验证
kubectl get pods -l app=shop-recycle-gateway
kubectl logs -l app=shop-recycle-gateway -f

---

🛠️ 自动化脚本（1 个）

generate-k8s-manifests.sh

自动分析和生成部署文件

功能：

• 遍历 conf/ 中的 34 个微服务
• 自动提取端口号、服务类型、敏感信息类型
• 生成统计报告
• 提示下一步操作

使用方法：

bash generate-k8s-manifests.sh

输出示例：

🔍 正在读取配置文件...

📝 处理服务: shop-recycle-payment
  ✅ 端口: 1218
  📊 类型: Backend (包含数据库)
  
...（34 个服务）

📊 统计信息：
  - 总服务数: 34
  - 需要数据库凭证的服务: 26
  - 需要微信凭证的服务: 5

---

🚀 使用流程

快速部署（10 分钟）

# 1. 部署共享 Secret（一次性）
kubectl apply -f secret-templates-common.yaml

# 2. 部署 Gateway 作为测试
kubectl apply -f gateway-*.yaml

# 3. 验证
kubectl get svc shop-recycle-gateway
kubectl port-forward svc/shop-recycle-gateway 1211:1211
curl http://localhost:1211/actuator/health

完整部署（1-2 小时）

# 1. 理解配置策略
read CONFIG-AND-SECRET-STRATEGY.md

# 2. 部署共享 Secret
kubectl apply -f secret-templates-common.yaml

# 3. 为每个服务生成 ConfigMap
# 方式 A：自动生成（推荐）
bash generate-k8s-manifests.sh
kubectl apply -f k8s-manifests/configmaps/

# 方式 B：手动生成
# 使用 service-configmap-deployment-template.yaml 为每个服务生成

# 4. 为每个服务生成 Deployment
bash generate-k8s-manifests.sh
kubectl apply -f k8s-manifests/deployments/

# 5. 为每个服务生成 Service
bash generate-k8s-manifests.sh
kubectl apply -f k8s-manifests/services/

# 6. 验证所有服务
kubectl get pods | grep shop-recycle

故障排查和优化（根据需要）

参考 K8S-DEPLOYMENT-GUIDE.md 中的：

• 故障排查部分（4 大常见问题）
• 最佳实践部分（5 方面改进）
• 验证部署部分（8 个检查步骤）

---

📊 数据一览

服务分类统计

类型	数量	特点
后端服务（有数据库）	26	需要数据库凭证
Web 服务（无数据库）	8	仅需 Cache/Queue 凭证
微信服务	5	额外需要微信凭证
其他特殊	2-3	MongoDB/Seata 等

Secret 使用统计

Secret 名称	服务数	凭证项数	是否共享
common-db-credentials	26	4	✅ 共享
common-redis-credentials	30+	4	✅ 共享
common-rabbitmq-credentials	20+	4	✅ 共享
wechat-credentials	5	8	✅ 共享
nacos-credentials	34	3	✅ 共享
seata-credentials	2-3	3	✅ 共享
mongodb-credentials	2-3	5	✅ 共享
总计	34	31+	7 个 Secret

优势： 只需维护 7 个 Secret，而不是 34 个

---

🔑 关键决策说明

1. 为什么使用共享 Secret？

✅ 优点：

• 简化管理：7 个 Secret vs 34 个
• 易于更新：一次更新，所有服务立即生效
• 节省资源：减少 API 调用和存储

❌ 缺点：

• 如果 Secret 泄露，影响范围大
• 无法细粒度权限控制

2. 为什么 ConfigMap 和 Secret 分离？

✅ 优点：

• 符合最小权限原则
• 敏感信息受到更好的保护
• 配置修改不影响凭证

3. 为什么使用环境变量注入？

✅ 优点：

• 无需修改配置文件
• 环境特定的值可以灵活替换
• 凭证不会被提交到 Git

4. 为什么包含 Gateway 具体例子？

✅ 原因：

• Gateway 是所有请求的入口
• 演示如何处理"无数据库"服务
• 可作为其他 Web 服务的参考

---

⚡ 常用命令快速参考

# 查看所有 Secret
kubectl get secrets | grep common-

# 查看特定 Secret
kubectl describe secret common-db-credentials
kubectl get secret common-db-credentials -o yaml

# 创建/更新 Secret
kubectl apply -f secret-templates-common.yaml

# 查看所有 ConfigMap
kubectl get configmaps | grep shop-recycle

# 查看特定 ConfigMap
kubectl describe configmap shop-recycle-payment-config
kubectl get configmap shop-recycle-payment-config -o yaml

# 查看部署状态
kubectl get deployments,pods,svc | grep shop-recycle

# 查看日志
kubectl logs -l app=shop-recycle-payment -f
kubectl logs pod-name -c container-name

# 验证环境变量注入
kubectl exec -it pod-name -- env | grep DB_

# 编辑资源（临时修改）
kubectl edit configmap shop-recycle-payment-config
kubectl edit secret common-db-credentials

# 重启部署
kubectl rollout restart deployment shop-recycle-payment

# 批量应用
kubectl apply -f .  # 当前目录所有 YAML

# 导出配置备份
kubectl get configmap,secret,deployment -o yaml > backup.yaml

# 删除资源
kubectl delete secret common-db-credentials
kubectl delete configmap shop-recycle-payment-config
kubectl delete deployment shop-recycle-payment

---

📚 文档导航树

您在这里 ← CONFIG-MANAGEMENT-SUMMARY.md
    │
    ├─→ 快速了解方案
    │   └─→ 阅读本文档第一部分
    │
    ├─→ 理解配置策略
    │   └─→ 阅读 CONFIG-AND-SECRET-STRATEGY.md
    │       ├─ 34 个服务分类
    │       ├─ 敏感信息类型
    │       ├─ Secret vs ConfigMap 分割
    │       └─ 3 种实施方案对比
    │
    ├─→ 部署和运维
    │   └─→ 阅读 K8S-DEPLOYMENT-GUIDE.md
    │       ├─ 5 步部署流程
    │       ├─ 验证检查清单
    │       ├─ 故障排查（4 大问题）
    │       ├─ 最佳实践
    │       └─ 安全建议
    │
    ├─→ 查看模板
    │   ├─→ secret-templates-common.yaml
    │   │   └─ 7 种共享 Secret 模板
    │   │
    │   ├─→ service-configmap-deployment-template.yaml
    │   │   └─ 通用 ConfigMap/Deployment/Service 模板
    │   │
    │   └─→ gateway-*.yaml（3 个文件）
    │       └─ Gateway 具体例子
    │
    └─→ 自动化
        └─→ generate-k8s-manifests.sh
            └─ 自动分析和生成脚本

---

✅ 实施检查清单

准备阶段

• 阅读 CONFIG-MANAGEMENT-SUMMARY.md（本文档）
• 了解 34 个服务的分类
• 理解 Secret vs ConfigMap 的差异
• 有权访问 Kubernetes 集群

部署阶段

• 编辑 secret-templates-common.yaml 替换实际凭证
• 部署 Secret：kubectl apply -f secret-templates-common.yaml
• 生成 ConfigMap：bash generate-k8s-manifests.sh
• 生成 Deployment：使用模板为每个服务创建
• 生成 Service：为每个服务创建负载均衡

验证阶段

• 检查 Secret：kubectl get secrets | grep common-
• 检查 ConfigMap：kubectl get configmaps | grep shop-recycle
• 检查 Pod：kubectl get pods | grep shop-recycle
• 检查日志：kubectl logs -l app=shop-recycle-gateway -f
• 测试健康：curl http://localhost:port/actuator/health

生产化阶段

• 配置 RBAC 权限
• 设置监控告警
• 建立备份和恢复流程
• 记录变更日志
• 定期安全审计

---

🔗 外部资源

官方文档：

• Kubernetes ConfigMap
• Kubernetes Secret
• Spring Cloud Kubernetes

最佳实践：

• 12 Factor App - Config
• OWASP Secret Management

工具：

• Kustomize - 配置管理
• ArgoCD - GitOps CD
• External Secrets Operator
• Sealed Secrets

---

📞 常见问题

Q: 为什么没有为所有 34 个服务生成具体文件？
A: 为了避免文件冗余。使用提供的模板和脚本可以快速生成所有服务的配置。

Q: 可以修改 Secret 吗？
A: 可以，但修改后需要重启使用该 Secret 的所有 Pod。

Q: ConfigMap 大小有限制吗？
A: 是的，单个 ConfigMap 限制 1MB（etcd 限制）。如果超过，需要分割。

Q: 如何在 Git 中管理 Secret？
A: 不要提交 Secret 到 Git。使用 Sealed Secrets、External Secrets Operator 或仅在 CI/CD 中注入。

---

📝 版本历史

版本	日期	更新内容
1.0.0	2026-01-16	初始版本：完整的 34 个服务配置方案

---

最后更新： 2026-01-16
维护者： DevOps 团队
许可证： 内部使用

---

👉 下一步：

1. 根据环境修改 secret-templates-common.yaml
2. 部署 Secret：kubectl apply -f secret-templates-common.yaml
3. 部署 Gateway 测试：kubectl apply -f gateway-*.yaml
4. 查看日志验证：kubectl logs -l app=shop-recycle-gateway -f