# 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️⃣ 部署全部微服务（默认配置）

```bash
helm install shop-recycle ./
```

#### 2️⃣ 部署特定环境

```bash
# 开发环境
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️⃣ 选择性部署微服务

```bash
# 仅部署核心后端服务
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️⃣ 自定义镜像仓库和版本

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

#### 5️⃣ 验证安装

```bash
# 查看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)

```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)

```yaml
global:
  labels:
    environment: staging

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

### 生产环境 (prod-values.yaml)

```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：基础部署

```bash
helm install shop-recycle ./
```

### 示例2：多环境部署脚本

```bash
#!/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：升级应用版本

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

### 示例4：查看部署状态

```bash
# 查看所有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 .
```

---

## 🔍 常见操作

### 调试和测试

```bash
# 验证Chart语法
helm lint ./

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

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

### 端口转发

```bash
# 转发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
```

### 日志查看

```bash
# 查看所有服务日志
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

```bash
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`中配置两个端口：

```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模式不适用）**
```yaml
apiVersion: v1
kind: Service
metadata:
  name: shop-recycle-merchant
spec:
  type: ClusterIP
  ports:
    - name: http
      port: 1204          # 外部访问端口
      targetPort: 1204    # 容器内端口
```

**2. Dubbo Headless Service（RPC通信）**
```yaml
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
   ```bash
   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`中配置：

```yaml
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服务是否正常工作：

```bash
# 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服务无法连接**
```bash
# 检查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中的配置**：
```yaml
service:
  type: ClusterIP
  port: 1204              # ← Service暴露的端口（对外访问）
  targetPort: 1204        # ← Pod内容器监听的端口
  dubbo_port: 2023        # ← Dubbo RPC端口（仅Dubbo服务）
```

**deployment.yaml中的配置**：
```yaml
ports:
- name: http
  containerPort: 1204     # ← 容器内应用监听的端口
  protocol: TCP
- name: dubbo
  containerPort: 2023     # ← 仅在有dubbo_port时创建
  protocol: TCP
```

#### 端口访问方式

```bash
# 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
```

---

### 副本自动扩展

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

### 资源限制

详见各环境配置文件。

---

## 🔐 安全最佳实践

### 敏感信息管理

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

### 健康检查

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

---

## 📚 相关资源

- [Helm官方文档](https://helm.sh/docs/)
- [Kubernetes官方文档](https://kubernetes.io/docs/)
- [Spring Cloud官方文档](https://spring.io/projects/spring-cloud)
- [Spring Boot Actuator](https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html)

---

## 📝 更新日志

### 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