microservice-helm

Shop Recycle - Microservice Platform Helm Chart

📋 概述

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

架构版本： 1.0.0
项目名称： Shop Recycle
微服务数量： 34个
部署环境： dev, staging, production
Spring Cloud框架： Spring Cloud Nacos + Dubbo
端口范围： 1201-1239

---

🎯 主要特性

✅ Umbrella Chart架构 - 统一部署管理34个微服务
✅ 模板代码复用 - 通用base chart，消除重复代码
✅ 灵活的服务启用/禁用 - 可按需启用或禁用任意微服务
✅ 多环境配置管理 - 开发、测试、生产环境差异化配置
✅ 全局配置共享 - 支持跨服务的全局配置
✅ Spring Cloud原生支持 - Nacos服务注册、Dubbo通信
✅ 生产就绪 - 包含health check、资源限制、副本控制

---

📁 项目结构

microservice-helm/
├── Chart.yaml                          # Umbrella Chart定义（34个依赖）
├── values.yaml                         # 全局配置（各服务默认值）
├── README.md                           # 本文档
├── templates/                          # 根级templates（通常为空）
│   ├── configmap.yaml
│   ├── deployment.yaml
│   └── service.yaml
├── charts/                             # 子Chart目录（34个微服务+base）
│   ├── base/                           # 🔷 通用模板库
│   │   ├── Chart.yaml
│   │   ├── values.yaml
│   │   └── templates/
│   │       ├── configmap.yaml          # 标准化的Spring Cloud应用属性
│   │       ├── deployment.yaml
│   │       └── service.yaml
│   │
│   ├── 核心业务服务 (9个)
│   │   ├── shop-recycle-payment/       # 支付服务 (1218)
│   │   ├── shop-recycle-store/         # 商店服务 (1208)
│   │   ├── shop-recycle-pis/           # PIS服务 (1209)
│   │   ├── shop-recycle-merchant/      # 商家服务 (1204)
│   │   ├── shop-recycle-account/       # 账户服务 (1223)
│   │   ├── shop-recycle-msg/           # 消息服务 (1217)
│   │   ├── shop-recycle-order-center/  # 订单中心 (1203)
│   │   ├── shop-recycle-wechat/        # 微信服务 (1231)
│   │   └── shop-recycle-order-search/  # 订单查询 (1238)
│   │
│   ├── 数据和基础服务 (8个)
│   │   ├── shop-recycle-data-statistics/    # 数据统计 (1220)
│   │   ├── shop-recycle-platform/           # 平台服务 (1201)
│   │   ├── shop-recycle-sche/               # 调度服务 (1215)
│   │   ├── shop-recycle-dispatcher/         # 分发器 (1236)
│   │   ├── shop-recycle-dealdata-service/   # 数据处理服务 (1235)
│   │   ├── shop-recycle-async-web/          # 异步服务 (1239)
│   │   └── shop-recycle-import-web/         # 导入Web (1221)
│   │
│   ├── 网关拓展服务 (4个)
│   │   ├── shop-recycle-gateway-out/        # 外部网关 (1226)
│   │   ├── shop-recycle-gateway-out-upgrade/# 网关升级 (1237)
│   │   ├── shop-recycle-out-web/            # 外部Web (1224)
│   │   └── shop-recycle-gateway/            # API网关 (1211)
│   │
│   ├── 客户端Web服务 (8个)
│   │   ├── shop-recycle-wechat-web/         # 微信Web (1214)
│   │   ├── shop-recycle-payment-web/        # 支付Web (1219)
│   │   ├── shop-recycle-store-wechat-web/   # 店铺微信Web (1207)
│   │   ├── shop-recycle-customer-wechat-web/# 客户微信Web (1227)
│   │   ├── shop-recycle-merchant-wechat-web/# 商家微信Web (1206)
│   │   ├── shop-recycle-oss-web/            # OSS Web (1212)
│   │   ├── shop-recycle-login-center/       # 登录中心 (1210)
│   │   └── shop-recycle-vs-web/             # VS Web (1233)
│   │
│   └── 管理后台服务 (6个)
│       ├── shop-recycle-platform-pc-web/    # 平台PC Web (1202)
│       ├── shop-recycle-store-pc-web/       # 店铺PC Web (1222)
│       ├── shop-recycle-marketer-pc-web/    # 营销PC Web (1232)
│       ├── shop-recycle-erp-pc-web/         # ERP PC Web (1228)
│       ├── shop-recycle-merchant-pc-web/    # 商家PC Web (1205)
│       └── shop-recycle-agent-pc-web/       # 代理PC Web (1225)
│
└── 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

# 禁用特定Web服务
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

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

---

📊 服务详细列表

核心业务服务 (9个)

服务名称	端口	说明
shop-recycle-payment	1218	支付服务
shop-recycle-store	1208	商店服务
shop-recycle-pis	1209	PIS系统
shop-recycle-merchant	1204	商家管理
shop-recycle-account	1223	账户管理
shop-recycle-msg	1217	消息服务
shop-recycle-order-center	1203	订单中心
shop-recycle-wechat	1231	微信集成
shop-recycle-order-search	1238	订单查询

数据和基础服务 (8个)

服务名称	端口	说明
shop-recycle-platform	1201	平台核心
shop-recycle-data-statistics	1220	数据统计
shop-recycle-sche	1215	调度服务
shop-recycle-dispatcher	1236	分发服务
shop-recycle-dealdata-service	1235	数据处理
shop-recycle-async-web	1239	异步处理
shop-recycle-import-web	1221	数据导入

网关拓展服务 (4个)

服务名称	端口	说明
shop-recycle-gateway-out	1226	外部网关
shop-recycle-gateway-out-upgrade	1237	网关升级
shop-recycle-out-web	1224	外部Web
shop-recycle-gateway	1211	API网关

客户端Web服务 (8个)

服务名称	端口	说明
shop-recycle-wechat-web	1214	微信Web
shop-recycle-payment-web	1219	支付Web
shop-recycle-store-wechat-web	1207	店铺微信Web
shop-recycle-customer-wechat-web	1227	客户微信Web
shop-recycle-merchant-wechat-web	1206	商家微信Web
shop-recycle-oss-web	1212	文件管理
shop-recycle-login-center	1210	登录中心
shop-recycle-vs-web	1233	VS页面

管理后台服务 (6个)

服务名称	端口	说明
shop-recycle-platform-pc-web	1202	平台PC Web
shop-recycle-store-pc-web	1222	店铺PC Web
shop-recycle-marketer-pc-web	1232	营销管理
shop-recycle-erp-pc-web	1228	ERP系统
shop-recycle-merchant-pc-web	1205	商家后台
shop-recycle-agent-pc-web	1225	代理后台

---

🌍 环境配置

开发环境 (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

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

global:
  labels:
    environment: staging

shop-recycle-payment:
  enabled: true
  app:
    replicaCount: 2
  image:
    tag: staging-latest

生产环境 (prod-values.yaml)

global:
  labels:
    environment: production

shop-recycle-payment:
  enabled: true
  app:
    replicaCount: 3
  image:
    tag: "1.0.0"
  resources:
    requests:
      cpu: 500m
      memory: 512Mi
    limits:
      cpu: 1000m
      memory: 1024Mi

---

💡 使用示例

示例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：升级应用版本

helm upgrade shop-recycle ./ \
  --set shop-recycle-payment.image.tag=v2.0.0 \
  --set shop-recycle-store.image.tag=v2.0.0

示例4：查看部署状态

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

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

# 验证服务健康
curl -s localhost:1218/actuator/health | jq .

---

🔍 常见操作

调试和测试

# 验证Chart语法
helm lint ./

# 渲染模板
helm template shop-recycle ./

# 查看特定环境的配置
helm template shop-recycle ./ -f environments/prod-values.yaml

端口转发

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

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

# 测试
curl http://localhost:1218/actuator/health

日志查看

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

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

# 查看最近的日志
kubectl logs -l app=shop-recycle-payment --tail=50

删除Release

helm uninstall shop-recycle

---

🏗️ 架构说明

Umbrella Chart设计

Umbrella Chart 管理34个子Chart，提供：

1. 统一的部署管理
2. 全局配置共享
3. 灵活的服务启用/禁用
4. 环境隔离配置

Spring Cloud配置

所有微服务的配置文件已集成到对应的charts/<service-name>/values.yaml中的config.yml部分，包含以下标准配置：

• Spring Cloud Nacos服务发现
• 数据库连接配置
• Redis连接配置
• RabbitMQ消息队列配置
• Dubbo服务配置
• 日志级别配置

Dubbo RPC通信架构

13个服务使用Dubbo进行RPC通信：

Dubbo服务列表

shop-recycle-platform (2021)
shop-recycle-order-center (2022)
shop-recycle-merchant (2023)
shop-recycle-store (2024)
shop-recycle-pis (2025)
shop-recycle-msg (2026)
shop-recycle-payment (2027)
shop-recycle-data-statistics (2028)
shop-recycle-account (2030)
shop-recycle-wechat (2031)
shop-recycle-dealdata-service (2032)
shop-recycle-dispatcher (2033)
shop-recycle-order-search (2034)

Service配置说明

每个Dubbo服务在values.yaml中配置两个端口：

service:
  type: ClusterIP
  port: 1204              # HTTP REST API端口
  targetPort: 1204        # 容器内HTTP服务端口
  dubbo_port: 2023        # Dubbo RPC端口

Kubernetes Service架构

部署每个Dubbo服务时，会自动创建两个Service：

1. 标准HTTP Service（Headless模式不适用）

apiVersion: v1
kind: Service
metadata:
  name: shop-recycle-merchant
spec:
  type: ClusterIP
  ports:
    - name: http
      port: 1204          # 外部访问端口
      targetPort: 1204    # 容器内端口

2. Dubbo Headless Service（RPC通信）

apiVersion: v1
kind: Service
metadata:
  name: shop-recycle-merchant-dubbo
spec:
  type: ClusterIP
  clusterIP: None         # ← Headless Service
  ports:
    - name: dubbo
      port: 2023          # Dubbo协议端口
      targetPort: 2023    # 容器内Dubbo端口

Headless Service的作用

Headless Service（clusterIP: None）的关键特性：

1. DNS A记录 - 返回所有Pod的IP列表，而非VIP

   nslookup shop-recycle-merchant-dubbo.default.svc.cluster.local
   # 返回所有Pod IP: 10.x.x.x, 10.x.x.y, ...
   

2. 点对点连接 - Dubbo消费者直接连接到生产者Pod

   Dubbo消费者 → DNS查询 → 获取所有Pod IP → 直连任意Pod
   

3. 负载均衡 - Dubbo框架自身处理负载均衡，无需Kubernetes代理

   不经过Service VIP，直接RPC通信，性能更高
   

Dubbo配置示例

每个Dubbo服务在config.yml中配置：

dubbo:
  application:
    name: shop-recycle-merchant-service  # 应用名称
  provider:
    registry:
      address: nacos://nacos.bak.com:8848  # Nacos注册中心
    filter: tracing                         # 链路追踪
  consumer:
    filter: tracing
  protocol:
    name: dubbo                             # 使用Dubbo协议
    port: 2023                              # Dubbo端口

验证Dubbo通信

部署后，验证Dubbo服务是否正常工作：

# 1. 查看HTTP Service
kubectl get svc shop-recycle-merchant

# 2. 查看Headless Dubbo Service
kubectl get svc shop-recycle-merchant-dubbo
# 输出：shop-recycle-merchant-dubbo   None         <none>        2023/TCP

# 3. 验证DNS解析
kubectl run -it --rm debug --image=alpine --restart=Never -- \
  nslookup shop-recycle-merchant-dubbo.default.svc.cluster.local

# 4. 查看Pod日志中的Dubbo启动信息
kubectl logs -l app=shop-recycle-merchant | grep -i dubbo

# 5. 查看容器端口绑定
kubectl exec <pod-name> -- netstat -tlnp | grep 2023

维护和故障排查

问题1: Dubbo服务无法连接

# 检查Headless Service是否创建
kubectl get svc | grep dubbo

# 检查Pod是否运行
kubectl get pods -l app=shop-recycle-merchant

# 查看Pod事件和日志
kubectl describe pod <pod-name>
kubectl logs <pod-name>

问题2: 添加新的Dubbo服务

1. 在 values.yaml 中添加 service.dubbo_port
   service:
     dubbo_port: 2035

2. 更新 config.yml 中的Dubbo配置
   dubbo:
     protocol:
       port: 2035

3. 重新部署
   helm upgrade shop-recycle ./

问题3: 修改Dubbo端口

1. 修改 charts/<service>/values.yaml 的 dubbo_port
2. 修改 config.yml 中的 dubbo.protocol.port
3. Helm会自动创建新的Headless Service
4. 旧的Dubbo Service会被清理

---

📌 重要概念说明

容器端口与Service端口的映射

在Helm部署中，每个微服务涉及多个端口层级，理解这些端口的作用至关重要：

端口映射流程

外部访问（Port）
    ↓
Service VIP:1204
    ↓
iptables规则转发
    ↓
Pod IP:1204（targetPort）
    ↓
容器应用:1204

配置位置

values.yaml中的配置：

service:
  type: ClusterIP
  port: 1204              # ← Service暴露的端口（对外访问）
  targetPort: 1204        # ← Pod内容器监听的端口
  dubbo_port: 2023        # ← Dubbo RPC端口（仅Dubbo服务）

deployment.yaml中的配置：

ports:
- name: http
  containerPort: 1204     # ← 容器内应用监听的端口
  protocol: TCP
- name: dubbo
  containerPort: 2023     # ← 仅在有dubbo_port时创建
  protocol: TCP

端口访问方式

# 1. 集群内通过Service VIP访问
kubectl port-forward svc/shop-recycle-merchant 1204:1204
curl http://localhost:1204

# 2. 直接访问Pod
kubectl port-forward pod/<pod-name> 1204:1204
curl http://localhost:1204

# 3. 集群内部通过DNS访问
# Pod内: curl http://shop-recycle-merchant:1204

# 4. Dubbo RPC直连（通过Headless Service）
# Dubbo消费者自动DNS解析shop-recycle-merchant-dubbo获取所有Pod IP

---

副本自动扩展

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

资源限制

详见各环境配置文件。

---

🔐 安全最佳实践

敏感信息管理

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

健康检查

所有服务都配置了liveness和readiness probe，使用/actuator/health端点。

---

📚 相关资源

• Helm官方文档
• Kubernetes官方文档
• Spring Cloud官方文档
• Spring Boot Actuator

---

📝 更新日志

v1.1.0 (2026-01-21)

• ✅ 精简全局values.yaml（1073行 → 102行）
• ✅ 移除不必要的占位符，直接使用实际值
• ✅ 添加revisionHistoryLimit自动清理旧ReplicaSets
• ✅ 创建自动部署脚本和清理脚本
• ✅ 为13个Dubbo服务添加Headless Service支持
• ✅ 更新镜像仓库为harbor.stardance格式
• ✅ 完整的Dubbo架构和故障排查文档

v1.0.0 (2026-01-15)

• ✅ 初始化Umbrella Chart架构
• ✅ 创建base通用模板库
• ✅ 实现34个shop-recycle微服务Chart
• ✅ 使用正确的端口号（1201-1239）
• ✅ 标准化Spring Cloud应用属性配置
• ✅ 创建多环境配置（dev、staging、prod）
• ✅ 完整的文档和使用示例

---

❓ 常见问题

Q: 如何修改服务端口？
A: 各服务的端口号已在对应的charts/<service-name>/values.yaml中的service.port和service.targetPort字段中定义。

Q: 是否可以修改应用名称？
A: 应用名称固定为service name，在configmap模板中自动设置。

Q: 如何只部署部分服务？
A: 使用--set <service-name>.enabled=false禁用不需要的服务。

Q: 什么是Headless Service，为什么Dubbo需要它？
A: Headless Service（clusterIP: None）使Dubbo消费者能直接获取所有生产者Pod的IP地址，从而实现点对点的RPC通信，避免Service VIP的代理开销。见上文"Dubbo RPC通信架构"部分。

Q: 如何验证Dubbo服务是否正常通信？
A: 使用以下命令检查Headless Service和Pod的Dubbo端口绑定（详见"验证Dubbo通信"部分）。

Q: Dubbo和HTTP Service有什么区别？
A: HTTP Service用于REST API访问（VIP模式），Dubbo Service用于RPC通信（Headless模式）。两个Service独立运行，互不干扰。

Q: 添加新Dubbo服务时需要做什么？
A: 在values.yaml中添加service.dubbo_port字段，Helm会自动为其创建Headless Service（见"添加新的Dubbo服务"部分）。

---

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