Docs: Add comprehensive deployment checklist and validation guide

DEPLOYMENT_CHECKLIST.md

@@ -0,0 +1,267 @@
+# 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结构验证
+```bash
+# 检查Chart.yaml语法
+helm lint ./
+
+# 验证模板渲染
+helm template shop-recycle ./ --debug
+
+# 只渲染特定服务
+helm template shop-recycle ./ --set shop-recycle-merchant.enabled=true
+```
+
+#### 2. 模板定义检查
+```bash
+# 确认所有base模板都有define
+grep -r "define" charts/base/templates/
+# 应该输出：
+# base.service
+# base.configmap
+# base.deployment
+```
+
+#### 3. 依赖关系检查
+```bash
+# 检查依赖路径
+grep "repository:" Chart.yaml
+# 所有路径应该是 file://./charts/xxx
+
+# 验证子chart存在
+ls charts/ | wc -l
+# 应该输出: 35 (34个服务 + base)
+```
+
+#### 4. Values配置验证
+```bash
+# 检查全局values.yaml
+cat values.yaml | wc -l
+# 应该输出: 102行左右
+
+# 验证服务配置
+cat charts/shop-recycle-merchant/values.yaml | grep "dubbo_port"
+# Dubbo服务应该有此字段
+```
+
+#### 5. 镜像仓库检查
+```bash
+# 检查所有服务镜像仓库
+grep -r "repository:" charts/*/values.yaml | grep harbor.stardance | wc -l
+# 应该输出: 34
+```
+
+---
+
+## 🚀 部署命令
+
+### 1. 标准部署
+```bash
+cd /opt/deploy/microservice-helm
+git pull
+helm install shop-recycle ./ -f environments/prod-values.yaml
+```
+
+### 2. 部署单个服务测试
+```bash
+helm install shop-recycle ./ \
+  --set shop-recycle-merchant.enabled=true \
+  -f environments/prod-values.yaml
+```
+
+### 3. 调试模式部署
+```bash
+helm install shop-recycle ./ \
+  -f environments/prod-values.yaml \
+  --debug \
+  --dry-run
+```
+
+---
+
+## 🔍 部署后验证
+
+### 1. 检查Pod状态
+```bash
+# 查看所有Pod
+kubectl get pods -l project=shop-recycle
+
+# 查看特定服务
+kubectl get pods -l app=shop-recycle-merchant
+
+# 检查Pod详细信息
+kubectl describe pod <pod-name>
+```
+
+### 2. 验证Service创建
+```bash
+# HTTP Service
+kubectl get svc shop-recycle-merchant
+
+# Dubbo Headless Service (仅Dubbo服务)
+kubectl get svc shop-recycle-merchant-dubbo
+```
+
+### 3. 验证ConfigMap
+```bash
+# 查看ConfigMap
+kubectl get cm shop-recycle-merchant-config
+
+# 查看配置内容
+kubectl get cm shop-recycle-merchant-config -o yaml
+```
+
+### 4. 验证端口绑定
+```bash
+# 检查容器端口
+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通信
+```bash
+# 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控制台查看服务注册情况
+
+---
+
+## 📊 完整性检查总结
+
+运行以下命令进行完整性检查：
+
+```bash
+#!/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  
+**验证状态**: ✅ 所有已知问题已修复