microservice-helm

Shop Recycle - Microservice Platform Helm Chart

📋 概述

这是一个企业级微服务平台的Helm Chart实现，采用Umbrella Chart + 通用模板库的混合架构。用于管理Shop Recycle项目的25个Java Spring Cloud微服务的统一部署、配置管理和多环境部署。

架构版本： 1.0.0
项目名称： Shop Recycle
微服务数量： 25个
部署环境： dev, staging, production
Spring Cloud框架： 标准化的application.properties配置

---

🎯 主要特性

✅ Umbrella Chart架构 - 统一部署管理25个微服务
✅ 模板代码复用 - 通用base chart，消除重复代码
✅ 灵活的服务启用/禁用 - 可按需启用或禁用任意微服务
✅ 多环境配置管理 - 开发、测试、生产环境差异化配置
✅ 全局配置共享 - 支持跨服务的全局配置
✅ Spring Cloud原生支持 - 标准化的应用属性配置
✅ 生产就绪 - 包含health check、资源限制、副本控制
✅ 配置精简化 - 应用属性在模板中固定，避免重复

---

📁 项目结构

microservice-helm/
├── Chart.yaml                          # Umbrella Chart定义（25个依赖）
├── values.yaml                         # 全局配置（各服务默认值）
├── README.md                           # 本文档
├── templates/                          # 根级templates（通常为空）
│   ├── configmap.yaml
│   ├── deployment.yaml
│   └── service.yaml
├── charts/                             # 子Chart目录（25个微服务+base）
│   ├── base/                           # 🔷 通用模板库
│   │   ├── Chart.yaml
│   │   ├── values.yaml
│   │   └── templates/
│   │       ├── configmap.yaml          # 标准化的Spring Cloud应用属性
│   │       ├── deployment.yaml
│   │       └── service.yaml
│   │
│   ├── 后端服务 (8个)
│   │   ├── shop-recycle-payment/       # 支付服务
│   │   ├── shop-recycle-store/         # 商店服务
│   │   ├── shop-recycle-pis/           # PIS服务
│   │   ├── shop-recycle-merchant/      # 商家服务
│   │   ├── shop-recycle-account/       # 账户服务
│   │   ├── shop-recycle-msg/           # 消息服务
│   │   ├── shop-recycle-order-center/  # 订单中心
│   │   └── shop-recycle-wechat/        # 微信服务
│   │
│   ├── 数据和管理服务 (4个)
│   │   ├── shop-recycle-data-statistics/  # 数据统计
│   │   ├── shop-recycle-platform/         # 平台服务
│   │   ├── shop-recycle-gateway/          # API网关
│   │   └── shop-recycle-sche/             # 调度服务
│   │
│   ├── 前端Web服务 (8个)
│   │   ├── shop-recycle-wechat-web/            # 微信Web
│   │   ├── shop-recycle-payment-web/           # 支付Web
│   │   ├── shop-recycle-store-wechat-web/      # 店铺微信Web
│   │   ├── shop-recycle-platform-pc-web/       # 平台PC Web
│   │   ├── shop-recycle-out-web/               # 外部Web
│   │   ├── shop-recycle-store-pc-web/          # 店铺PC Web
│   │   ├── shop-recycle-oss-web/               # OSS Web
│   │   └── shop-recycle-login-center/          # 登录中心
│   │
│   └── 管理后台服务 (5个)
│       ├── shop-recycle-merchant-wechat-web/      # 商家微信Web
│       ├── shop-recycle-import-web/               # 导入Web
│       ├── shop-recycle-marketer-pc-web/          # 营销PC Web
│       ├── shop-recycle-erp-pc-web/               # ERP PC Web
│       └── shop-recycle-merchant-pc-web/          # 商家PC Web
│
└── environments/                       # 环境特定配置
    ├── dev-values.yaml                 # 开发环境（DEBUG日志、单副本）
    ├── staging-values.yaml             # 预发布环境（INFO日志、双副本）
    └── prod-values.yaml                # 生产环境（WARN日志、三副本、高资源）

---

🚀 快速开始

前置条件

• Kubernetes集群 1.16+
• Helm 3.0+
• kubectl 已配置并能访问集群

安装

1️⃣ 部署全部微服务（默认配置）

helm install shop-recycle ./

2️⃣ 部署特定环境

# 开发环境
helm install shop-recycle ./ \
  -f environments/dev-values.yaml

# 预发布环境
helm install shop-recycle ./ \
  -f environments/staging-values.yaml

# 生产环境
helm install shop-recycle ./ \
  -f environments/prod-values.yaml

3️⃣ 选择性部署微服务

# 仅部署后端核心服务
helm install shop-recycle ./ \
  --set shop-recycle-payment.enabled=true \
  --set shop-recycle-store.enabled=true \
  --set shop-recycle-merchant.enabled=true \
  --set shop-recycle-gateway.enabled=true \
  --set shop-recycle-wechat-web.enabled=false

# 禁用特定服务
helm install shop-recycle ./ \
  --set shop-recycle-marketer-pc-web.enabled=false \
  --set shop-recycle-erp-pc-web.enabled=false

4️⃣ 自定义镜像仓库和版本

helm install shop-recycle ./ \
  --set global.image.registry=your-registry \
  --set shop-recycle-payment.image.tag=v2.0.0 \
  --set shop-recycle-store.image.tag=v2.0.0

5️⃣ 验证安装

# 查看Release状态
helm status shop-recycle

# 查看所有部署的资源
kubectl get all -l platform=microservice-platform

# 查看所有Pod
kubectl get pods -l project=shop-recycle

# 查看Service和端口
kubectl get svc

---

📊 配置详解

全局配置（values.yaml）

global:
  image:
    registry: your-registry           # Docker镜像仓库
    pullPolicy: IfNotPresent
  labels:
    platform: microservice-platform
    project: shop-recycle
    version: "1.0"

微服务配置示例

每个微服务的values.yaml结构如下：

app:
  name: shop-recycle-payment          # 应用名称
  replicaCount: 1                     # Pod副本数

image:
  repository: your-registry/shop-recycle-payment
  tag: "1.0.0"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 8080                          # 对外端口
  targetPort: 8080                    # 容器端口

resources:
  requests:
    cpu: 250m
    memory: 256Mi
  limits:
    cpu: 500m
    memory: 512Mi

config:
  yml:                                # application.yml配置
    logging:
      level:
        root: INFO
    management:
      endpoints:
        web:
          exposure:
            include: health,info,metrics

端口分配

所有25个微服务的端口分配：

服务	端口	服务	端口
shop-recycle-payment	8080	shop-recycle-platform	8089
shop-recycle-store	8081	shop-recycle-wechat-web	8090
shop-recycle-pis	8082	shop-recycle-payment-web	8091
shop-recycle-merchant	8083	shop-recycle-store-wechat-web	8092
shop-recycle-account	8084	shop-recycle-platform-pc-web	8093
shop-recycle-msg	8085	shop-recycle-out-web	8094
shop-recycle-order-center	8086	shop-recycle-store-pc-web	8095
shop-recycle-wechat	8087	shop-recycle-login-center	8096
shop-recycle-data-statistics	8088	shop-recycle-oss-web	8097
shop-recycle-gateway	8098	shop-recycle-sche	8099
shop-recycle-merchant-wechat-web	8100	shop-recycle-import-web	8101
shop-recycle-marketer-pc-web	8102	shop-recycle-erp-pc-web	8103
shop-recycle-merchant-pc-web	8104	-	-

---

🌍 环境配置

开发环境 (dev-values.yaml)

global:
  labels:
    environment: development

shop-recycle-payment:
  enabled: true
  app:
    replicaCount: 1                   # 单副本
  image:
    tag: dev-latest
  config:
    yml:
      logging:
        level:
          root: DEBUG                 # DEBUG日志级别
      management:
        endpoints:
          web:
            exposure:
              include: health,info,metrics,env,configprops  # 暴露更多端点用于调试

部署方式：

helm install shop-recycle ./ -f environments/dev-values.yaml

预发布环境 (staging-values.yaml)

global:
  labels:
    environment: staging

shop-recycle-payment:
  enabled: true
  app:
    replicaCount: 2                   # 双副本
  image:
    tag: staging-latest
  config:
    yml:
      logging:
        level:
          root: INFO                  # INFO日志级别

生产环境 (prod-values.yaml)

global:
  labels:
    environment: production

shop-recycle-payment:
  enabled: true
  app:
    replicaCount: 3                   # 三副本高可用
  image:
    tag: "1.0.0"                      # 使用固定版本，不使用latest
  resources:
    requests:
      cpu: 500m                       # 资源请求翻倍
      memory: 512Mi
    limits:
      cpu: 1000m                      # 严格的资源限制
      memory: 1024Mi
  config:
    yml:
      logging:
        level:
          root: WARN                  # 仅记录WARN及以上级别
      management:
        endpoints:
          web:
            exposure:
              include: health,metrics # 仅暴露必要的端点

---

💡 使用示例

示例1：基础部署

最小化部署，使用所有默认配置：

helm install shop-recycle ./

示例2：完整的多环境部署脚本

#!/bin/bash

# 部署开发环境
helm install shop-recycle-dev ./ \
  --namespace dev \
  --create-namespace \
  -f environments/dev-values.yaml

# 部署预发布环境
helm install shop-recycle-staging ./ \
  --namespace staging \
  --create-namespace \
  -f environments/staging-values.yaml

# 部署生产环境
helm install shop-recycle-prod ./ \
  --namespace prod \
  --create-namespace \
  -f environments/prod-values.yaml

示例3：只部署后端服务

# 创建values文件 backend-only.yaml，禁用所有web服务
helm install shop-recycle ./ \
  --set shop-recycle-wechat-web.enabled=false \
  --set shop-recycle-payment-web.enabled=false \
  --set shop-recycle-store-wechat-web.enabled=false \
  --set shop-recycle-platform-pc-web.enabled=false \
  --set shop-recycle-out-web.enabled=false \
  --set shop-recycle-store-pc-web.enabled=false \
  --set shop-recycle-oss-web.enabled=false \
  --set shop-recycle-login-center.enabled=false \
  --set shop-recycle-merchant-wechat-web.enabled=false \
  --set shop-recycle-import-web.enabled=false \
  --set shop-recycle-marketer-pc-web.enabled=false \
  --set shop-recycle-erp-pc-web.enabled=false \
  --set shop-recycle-merchant-pc-web.enabled=false

示例4：升级应用版本

# 升级所有服务到新版本
helm upgrade shop-recycle ./ \
  --set global.image.tag=v2.0.0

# 或升级特定服务
helm upgrade shop-recycle ./ \
  --set shop-recycle-payment.image.tag=v2.0.0 \
  --set shop-recycle-store.image.tag=v2.0.0

示例5：灾难恢复

# 查看发布历史
helm history shop-recycle

# 回滚到前一个版本
helm rollback shop-recycle 1

# 回滚到特定版本
helm rollback shop-recycle 5

---

🔍 常见操作

查看部署状态

# 查看Release信息
helm status shop-recycle

# 查看Release使用的values
helm get values shop-recycle

# 查看Release部署的资源
helm get manifest shop-recycle

# 查看所有微服务pod
kubectl get pods -l project=shop-recycle -o wide

调试和测试

# 验证Chart语法
helm lint ./

# 渲染模板（不实际部署）
helm template shop-recycle ./

# 详细渲染（查看完整输出）
helm template shop-recycle ./ --debug

# 查看特定环境的渲染结果
helm template shop-recycle ./ -f environments/prod-values.yaml

日志和监控

# 查看所有微服务日志
kubectl logs -l project=shop-recycle -f

# 查看特定服务日志
kubectl logs -l app=shop-recycle-payment -f

# 查看Pod详情（包括事件）
kubectl describe pod <pod-name>

# 查看资源使用情况
kubectl top pods -l project=shop-recycle

端口转发（本地测试）

# 转发payment服务
kubectl port-forward svc/shop-recycle-payment 8080:8080

# 转发gateway服务
kubectl port-forward svc/shop-recycle-gateway 8098:8098

# 在另一个终端测试
curl http://localhost:8080/actuator/health
curl http://localhost:8098/actuator/health

进入容器调试

# 进入pod
kubectl exec -it <pod-name> -- /bin/bash

# 执行命令查看配置
kubectl exec <pod-name> -- cat /etc/config/application.properties

# 测试应用健康状态
kubectl exec <pod-name> -- curl http://localhost:8080/actuator/health

删除和清理

# 删除Release（保留PVC）
helm uninstall shop-recycle

# 删除namespace
kubectl delete namespace shop-recycle

# 删除所有资源
kubectl delete all -l project=shop-recycle

---

🏗️ 架构说明

Umbrella Chart设计

Umbrella Chart 是一个特殊的Helm Chart，主要作用是：

1. 作为25个子Chart的容器
2. 提供全局配置和共享值
3. 支持子Chart的条件启用/禁用
4. 实现统一的部署管理

Umbrella Chart (shop-recycle)
├── Base Chart (可复用模板)
│   ├── Deployment模板
│   ├── Service模板
│   └── ConfigMap模板（标准化Spring Cloud属性）
└── 25个微服务（继承Base模板）
    ├── 后端服务 (8个)
    ├── 数据管理 (4个)
    ├── 前端Web (8个)
    └── 管理后台 (5个)

模板继承和代码复用

各微服务的templates通过引用base chart的模板实现代码复用：

# shop-recycle-payment/templates/deployment.yaml
{{- include "base.deployment" . -}}

这样可以：

• ✅ 避免重复代码（DRY原则）
• ✅ 统一部署配置逻辑
• ✅ 快速添加新服务
• ✅ 维护和修复更简单

Spring Cloud应用属性配置

标准化的application.properties生成：

ConfigMap模板中直接固定生成标准的Spring Cloud配置：

spring.application.name=shop-recycle-payment
spring.protocol.name=spring
server.port=8080

这样做的优势：

• ✅ 消除了values文件中的重复配置
• ✅ 保证配置的一致性和可靠性
• ✅ 简化了values.yaml的复杂度
• ✅ 应用名称和端口始终保持关联

---

⚙️ 高级配置

副本自动扩展（HPA）

kubectl autoscale deployment shop-recycle-payment \
  --min=2 --max=10 --cpu-percent=80

安全上下文

securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  readOnlyRootFilesystem: true

资源限制

始终为容器定义资源请求和限制，防止资源耗尽。详见environment配置。

---

🔐 安全最佳实践

1. 资源限制和请求

详见environment配置文件中的资源设置。

2. 敏感信息管理

• ✅ 使用Kubernetes Secrets存储密码
• ✅ 不要在ConfigMap中存储敏感信息
• ✅ 定期轮换凭证

示例：创建Secret

kubectl create secret generic db-credentials \
  --from-literal=username=dbuser \
  --from-literal=password=dbpass

3. 健康检查

已包含的liveness和readiness probe配置：

livenessProbe:
  httpGet:
    path: /actuator/health
    port: http
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /actuator/health
    port: http
  initialDelaySeconds: 5
  periodSeconds: 5

---

📈 性能优化

调整JVM参数

在环境配置中修改JAVA_OPTS（需在base chart中配置）。

优化Health Check

• 增加初始延迟时间：initialDelaySeconds
• 减少检查频率：periodSeconds

Pod亲和力配置

实现Pod高可用分布，避免单点故障。

---

🐛 故障排查

Pod处于Pending状态

kubectl describe pod <pod-name>
kubectl top nodes

原因： 资源不足或节点有污点

镜像拉取失败

原因： 镜像地址错误、标签不存在或凭证不正确

应用无法启动

kubectl logs <pod-name>
kubectl logs <pod-name> --previous

原因： 配置错误、依赖服务不可用

验证ConfigMap内容

# 查看ConfigMap
kubectl get cm shop-recycle-payment-config -o yaml

# 验证application.properties
kubectl exec <pod-name> -- cat /etc/config/application.properties

---

📚 相关资源

• Helm官方文档
• Kubernetes官方文档
• Spring Cloud官方文档
• Spring Boot Actuator
• Helm Chart最佳实践

---

📝 更新日志

v1.0.0 (2026-01-15)

• ✅ 初始化Umbrella Chart架构
• ✅ 创建base通用模板库
• ✅ 实现25个shop-recycle微服务Chart
• ✅ 标准化Spring Cloud应用属性配置
• ✅ 创建多环境配置（dev、staging、prod）
• ✅ 优化配置结构，消除重复代码
• ✅ 完整的文档和使用示例

---

❓ 常见问题（FAQ）

Q: 如何添加新的微服务？
A: 在charts目录下创建新Chart，按照现有服务的结构创建Chart.yaml、values.yaml和templates，然后在Umbrella Chart的Chart.yaml中声明依赖。

Q: 能否修改应用的Spring属性？
A: 应用的基本属性（spring.application.name、spring.protocol.name、server.port）在configmap模板中固定。可以在config.yml中自定义logging和management端点配置。

Q: 如何实现灰度部署？
A: 使用Helm分阶段升级，先更新特定服务的镜像标签，或通过kubectl打补丁逐步更新。

Q: base chart的版本如何管理？
A: 在Umbrella Chart的Chart.yaml中指定版本，提升base版本时更新所有依赖声明。

Q: 是否支持Helm values的继承？
A: 是的，子Chart的values会自动与全局values合并，同名参数子Chart优先级更高。

Q: 如何只部署部分服务？
A: 使用--set选项禁用不需要的服务，如 --set shop-recycle-payment.enabled=false

---

📞 支持

遇到问题或有建议？

• 提交Issue：https://github.com/jiangkai/microservice-helm/issues
• 发起讨论：https://github.com/jiangkai/microservice-helm/discussions

---

最后更新： 2026-01-15
维护者： DevOps Team
项目： Shop Recycle Microservice Platform