Helm Chart部署前验证清单

✅ 已修复的问题

1. 模板定义缺失

问题: base模板未使用define包装，导致include调用失败
修复:
- base/templates/service.yaml - 添加 {{- define "base.service" -}}
- base/templates/configmap.yaml - 添加 {{- define "base.configmap" -}}
- base/templates/deployment.yaml - 添加 {{- define "base.deployment" -}}
状态: ✅ 已修复

2. Chart依赖路径

问题: file://../charts/xxx 路径
修复: 改为 file://./charts/xxx
状态: ✅ 已修复

3. Dubbo Service配置

问题: Dubbo服务需要Headless Service
修复:
- 为13个Dubbo服务添加 dubbo_port 配置
- service.yaml自动创建Headless Service（clusterIP: None）
- deployment.yaml添加dubbo容器端口
状态: ✅ 已完成

4. 配置占位符优化

问题: 不必要的变量占位符（如${nacos.service-address}）
修复: 直接使用实际值，简化配置
状态: ✅ 已完成

5. 全局values.yaml冗余

问题: 重复定义所有服务配置（1073行）
修复: 精简为102行，只保留全局配置和启用开关
状态: ✅ 已完成

📋 部署前检查清单

必检项目

1. Chart结构验证

# 检查Chart.yaml语法
helm lint ./

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

# 只渲染特定服务
helm template shop-recycle ./ --set shop-recycle-merchant.enabled=true

2. 模板定义检查

# 确认所有base模板都有define
grep -r "define" charts/base/templates/
# 应该输出：
# base.service
# base.configmap
# base.deployment

3. 依赖关系检查

# 检查依赖路径
grep "repository:" Chart.yaml
# 所有路径应该是 file://./charts/xxx

# 验证子chart存在
ls charts/ | wc -l
# 应该输出: 35 (34个服务 + base)

4. Values配置验证

# 检查全局values.yaml
cat values.yaml | wc -l
# 应该输出: 102行左右

# 验证服务配置
cat charts/shop-recycle-merchant/values.yaml | grep "dubbo_port"
# Dubbo服务应该有此字段

5. 镜像仓库检查

# 检查所有服务镜像仓库
grep -r "repository:" charts/*/values.yaml | grep harbor.stardance | wc -l
# 应该输出: 34

🚀 部署命令

1. 标准部署

cd /opt/deploy/microservice-helm
git pull
helm install shop-recycle ./ -f environments/prod-values.yaml

2. 部署单个服务测试

helm install shop-recycle ./ \
  --set shop-recycle-merchant.enabled=true \
  -f environments/prod-values.yaml

3. 调试模式部署

helm install shop-recycle ./ \
  -f environments/prod-values.yaml \
  --debug \
  --dry-run

🔍 部署后验证

1. 检查Pod状态

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

# 查看特定服务
kubectl get pods -l app=shop-recycle-merchant

# 检查Pod详细信息
kubectl describe pod <pod-name>

2. 验证Service创建

# HTTP Service
kubectl get svc shop-recycle-merchant

# Dubbo Headless Service (仅Dubbo服务)
kubectl get svc shop-recycle-merchant-dubbo

3. 验证ConfigMap

# 查看ConfigMap
kubectl get cm shop-recycle-merchant-config

# 查看配置内容
kubectl get cm shop-recycle-merchant-config -o yaml

4. 验证端口绑定

# 检查容器端口
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[0].ports}'

# 验证HTTP端口(1204)
kubectl port-forward svc/shop-recycle-merchant 1204:1204
curl http://localhost:1204/actuator/health

# 验证Dubbo端口(2023) - 从Pod内部
kubectl exec <pod-name> -- netstat -tlnp | grep 2023

5. 验证Dubbo通信

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

# 查看Dubbo日志
kubectl logs -l app=shop-recycle-merchant | grep -i dubbo

⚠️ 常见错误和解决方案

错误1: template not found

Error: template: no template "base.service" associated with template "gotpl"

原因: base模板未定义
解决: 确保已git pull最新代码，base/templates/下所有文件都有{{- define "base.xxx" -}}

错误2: 依赖路径错误

Error: chart requires missing dependency

原因: Chart.yaml中repository路径错误
解决: 确保路径为file://./charts/xxx

错误3: Pod无法启动

CrashLoopBackOff or ImagePullBackOff

原因: 镜像不存在或配置错误
解决:

检查镜像仓库: harbor.stardance/shoprecycle/shop-xxx:v2.0.0
查看Pod事件: kubectl describe pod <pod-name>
查看日志: kubectl logs <pod-name>

错误4: ConfigMap配置错误

服务启动后配置未生效

原因: ConfigMap未正确挂载或YAML格式错误
解决:

验证ConfigMap: kubectl get cm <name> -o yaml
检查挂载: kubectl exec <pod> -- ls /etc/config
查看文件内容: kubectl exec <pod> -- cat /etc/config/application.yml

错误5: Dubbo服务无法通信

No provider available

原因: Headless Service未创建或端口配置错误
解决:

检查Service: kubectl get svc | grep dubbo
验证端口: 确保values.yaml中的dubbo_port与config.yml中的dubbo.protocol.port一致
检查Nacos注册: 登录Nacos控制台查看服务注册情况

📊 完整性检查总结

运行以下命令进行完整性检查：

#!/bin/bash
cd /opt/deploy/microservice-helm

echo "=== 1. 拉取最新代码 ==="
git pull

echo "=== 2. Lint检查 ==="
helm lint ./

echo "=== 3. 模板验证 ==="
helm template shop-recycle ./ --debug > /dev/null 2>&1
if [ $? -eq 0 ]; then
  echo "✅ 模板验证通过"
else
  echo "❌ 模板验证失败"
  exit 1
fi

echo "=== 4. 检查base模板定义 ==="
grep -r "define" charts/base/templates/ | wc -l
echo "期望: 3 (service, configmap, deployment)"

echo "=== 5. 检查镜像仓库 ==="
grep -r "harbor.stardance" charts/*/values.yaml | wc -l
echo "期望: 34"

echo "=== 6. 检查Dubbo端口 ==="
grep -r "dubbo_port" charts/*/values.yaml | wc -l
echo "期望: 13"

echo "=== 所有检查完成 ==="

最后更新: 2026-01-21
验证状态: ✅ 所有已知问题已修复

DEPLOYMENT_CHECKLIST.md 6.2 KB Permalink Histórico Raw