Docs: Add comprehensive Dubbo RPC documentation and port mapping explanation

README.md

@@ -419,9 +419,235 @@ helm uninstall shop-recycle
 - 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
+```
+
+---
 
 ### 副本自动扩展
 
@@ -463,6 +689,15 @@ kubectl create secret generic db-credentials \
 
 ## 📝 更新日志
 
+### 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通用模板库
@@ -485,8 +720,20 @@ 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-15  
+**最后更新：** 2026-01-21  
 **维护者：** DevOps Team  
 **项目：** Shop Recycle Microservice Platform