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

```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 \
  --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️⃣ 自定义镜像仓库和版本

```bash
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️⃣ 验证安装

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

---

## 📊 配置详解

### 全局配置（values.yaml）

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

### 微服务配置示例

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

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

```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  # 暴露更多端点用于调试
```

**部署方式：**
```bash
helm install shop-recycle ./ -f environments/dev-values.yaml
```

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

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

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

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

```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
# 创建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：升级应用版本

```bash
# 升级所有服务到新版本
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：灾难恢复

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

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

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

---

## 🔍 常见操作

### 查看部署状态

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

### 调试和测试

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

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

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

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

### 日志和监控

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

### 端口转发（本地测试）

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

### 进入容器调试

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

### 删除和清理

```bash
# 删除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的模板实现代码复用：

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

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

### Spring Cloud应用属性配置

**标准化的application.properties生成**：

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

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

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

---

## ⚙️ 高级配置

### 副本自动扩展（HPA）

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

### 安全上下文

```yaml
securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  readOnlyRootFilesystem: true
```

### 资源限制

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

---

## 🔐 安全最佳实践

### 1. 资源限制和请求

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

### 2. 敏感信息管理

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

示例：创建Secret

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

### 3. 健康检查

已包含的liveness和readiness probe配置：

```yaml
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状态

```bash
kubectl describe pod <pod-name>
kubectl top nodes
```

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

### 镜像拉取失败

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

### 应用无法启动

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

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

### 验证ConfigMap内容

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

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

---

## 📚 相关资源

- [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)
- [Helm Chart最佳实践](https://helm.sh/docs/chart_best_practices/)

---

## 📝 更新日志

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