# Microservice Platform - Helm Chart

## 📋 概述

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

**架构版本：** 1.0.0  
**支持的微服务：** user-service, order-service, payment-service（可扩展）  
**部署环境：** dev, staging, production

---

## 🎯 主要特性

✅ **Umbrella Chart架构** - 统一部署管理多个微服务  
✅ **模板代码复用** - 通用base chart，减少重复代码  
✅ **灵活的服务启用/禁用** - 可按需启用或禁用任意微服务  
✅ **多环境配置管理** - 开发、测试、生产环境差异化配置  
✅ **全局配置共享** - 支持跨服务的全局配置  
✅ **Spring Boot原生支持** - 完整的Actuator、日志、配置管理  
✅ **生产就绪** - 包含health check、资源限制、副本控制  
✅ **易于扩展** - 快速添加新的微服务  

---

## 📁 项目结构

```
microservice-helm/
├── Chart.yaml                          # Umbrella Chart定义
├── values.yaml                         # 全局配置（各服务默认值）
├── README.md                           # 本文档
├── templates/                          # 根级templates
│   ├── configmap.yaml
│   ├── deployment.yaml
│   └── service.yaml
├── charts/                             # 子Chart目录
│   ├── base/                           # 通用模板库（不部署）
│   │   ├── Chart.yaml
│   │   ├── values.yaml
│   │   └── templates/
│   │       ├── configmap.yaml
│   │       ├── deployment.yaml
│   │       └── service.yaml
│   ├── user-service/                   # 用户服务
│   │   ├── Chart.yaml
│   │   ├── values.yaml
│   │   └── templates/
│   ├── order-service/                  # 订单服务
│   │   ├── Chart.yaml
│   │   ├── values.yaml
│   │   └── templates/
│   └── payment-service/                # 支付服务
│       ├── Chart.yaml
│       ├── values.yaml
│       └── templates/
└── environments/                       # 环境特定配置
    ├── dev-values.yaml
    ├── staging-values.yaml
    └── prod-values.yaml
```

---

## 🚀 快速开始

### 前置条件

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

### 安装

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

```bash
helm install microservice-platform ./
```

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

```bash
# 开发环境
helm install microservice-platform ./ \
  -f environments/dev-values.yaml

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

# 生产环境
helm install microservice-platform ./ \
  -f environments/prod-values.yaml
```

#### 3️⃣ 选择性部署微服务

```bash
# 仅部署user-service和order-service
helm install microservice-platform ./ \
  --set user-service.enabled=true \
  --set order-service.enabled=true \
  --set payment-service.enabled=false
```

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

```bash
helm install microservice-platform ./ \
  --set global.image.registry=your-registry \
  --set user-service.image.tag=v2.0.0 \
  --set order-service.image.tag=v1.5.0
```

#### 5️⃣ 验证安装

```bash
# 查看Release状态
helm list

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

# 查看Deployment状态
kubectl get deployment

# 查看Pod状态
kubectl get pods

# 查看Service和暴露的端口
kubectl get svc
```

---

## 📊 配置详解

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

所有微服务共享的全局配置。详见 `values.yaml` 文件中的 `global` 部分。

### 微服务配置

#### User Service 配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `user-service.enabled` | `true` | 是否启用该服务 |
| `user-service.app.replicaCount` | `1` | Pod副本数 |
| `user-service.image.tag` | `1.0.0` | 镜像标签 |
| `user-service.service.port` | `8080` | 服务端口 |

#### Order Service 配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `order-service.enabled` | `true` | 是否启用该服务 |
| `order-service.app.replicaCount` | `1` | Pod副本数 |
| `order-service.image.tag` | `1.0.0` | 镜像标签 |
| `order-service.service.port` | `8081` | 服务端口 |

#### Payment Service 配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `payment-service.enabled` | `true` | 是否启用该服务 |
| `payment-service.app.replicaCount` | `1` | Pod副本数 |
| `payment-service.image.tag` | `1.0.0` | 镜像标签 |
| `payment-service.service.port` | `8082` | 服务端口 |

---

## 🌍 环境配置

该项目支持多环境部署：

### 开发环境 (dev-values.yaml)

- 单副本部署
- DEBUG日志级别
- 最新开发镜像
- 宽松的DDL策略（create-drop）

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

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

- 双副本部署
- INFO日志级别
- 最新staging镜像
- 严格的DDL策略（validate）

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

- 三副本高可用部署
- WARN日志级别
- 固定版本镜像（不使用latest）
- 严格的资源限制
- 完全的DDL验证

---

## 💡 使用示例

### 示例1：基础部署

```bash
helm install my-platform ./
```

### 示例2：生产环境部署

```bash
helm install microservice-prod ./ \
  --namespace prod \
  --create-namespace \
  -f environments/prod-values.yaml
```

### 示例3：添加新的微服务

1. 创建Chart目录：
```bash
mkdir -p charts/notification-service/templates
```

2. 创建Chart.yaml和values.yaml

3. 在Chart.yaml中添加依赖声明

4. 在environments/中为新服务添加配置

详见README中的详细说明部分。

### 示例4：升级应用版本

```bash
helm upgrade microservice-platform ./ \
  --set user-service.image.tag=1.1.0 \
  --set order-service.image.tag=1.1.0 \
  --set payment-service.image.tag=1.1.0
```

### 示例5：灾难恢复

```bash
# 查看发布历史
helm history microservice-platform

# 回滚到前一个版本
helm rollback microservice-platform 1
```

---

## 🔍 常见操作

### 查看部署状态

```bash
# 查看Release信息
helm status microservice-platform

# 查看Release使用的values
helm get values microservice-platform

# 查看Release部署的资源
helm get manifest microservice-platform
```

### 调试和测试

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

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

# 详细渲染（查看完整输出）
helm template microservice-platform ./ --debug
```

### 日志和监控

```bash
# 查看所有微服务日志
kubectl logs -l platform=microservice-platform -f

# 查看特定服务日志
kubectl logs -l app=user-service -f

# 查看Pod详情
kubectl describe pod <pod-name>
```

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

```bash
# 转发user-service
kubectl port-forward svc/user-service 8080:8080

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

### 删除Release

```bash
# 删除Release（保留PVC）
helm uninstall microservice-platform

# 删除namespace
kubectl delete namespace <namespace>
```

---

## 🏗️ 架构说明

### Umbrella Chart设计

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

### 模板继承

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

```yaml
{{- include "base.deployment" . -}}
{{- include "base.service" . -}}
{{- include "base.configmap" . -}}
```

这样可以：
- 避免重复代码
- 统一部署配置
- 快速添加新服务
- 简化维护

---

## ⚙️ 高级配置

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

```bash
kubectl autoscale deployment user-service \
  --min=2 --max=10 --cpu-percent=80
```

### 安全上下文

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

### 资源限制

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

---

## 🔐 安全最佳实践

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

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

### 2. 敏感信息管理

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

### 3. 健康检查

已包含的liveness和readiness probe配置可防止故障pod继续服务。

---

## 📈 性能优化

### 调整JVM参数

在environment配置中修改JAVA_OPTS。

### 优化健康检查

- 增加初始延迟时间：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
```

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

---

## 📚 相关资源

- [Helm官方文档](https://helm.sh/docs/)
- [Kubernetes官方文档](https://kubernetes.io/docs/)
- [Spring Boot官方文档](https://spring.io/projects/spring-boot)
- [Helm Chart最佳实践](https://helm.sh/docs/chart_best_practices/)

---

## 📝 更新日志

### v1.0.0 (2026-01-15)
- ✅ 初始化Umbrella Chart架构
- ✅ 创建base通用模板库
- ✅ 实现3个示例微服务（user、order、payment）
- ✅ 创建多环境配置（dev、staging、prod）
- ✅ 完整的文档和示例

---

## ❓ 常见问题（FAQ）

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

**Q: 如何为单个服务禁用某个功能？**  
A: 在该服务对应的environment配置中进行覆盖。

**Q: 如何实现灰度部署？**  
A: 使用Helm分阶段升级，先更新镜像标签到新版本的一部分副本。

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

**Q: 是否支持Helm values的继承？**  
A: 是的，子Chart的values会自动与全局values合并。

---

## 📞 支持

遇到问题或有建议？

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

---

**最后更新：** 2026-01-15  
**维护者：** DevOps Team