safety-eval-service/docs/gbs/本地开发Dubbo代理方案C.md

# 方案 C：100 主机 Dubbo 开发代理（不影响 K8s 集群）

> 适用场景：本地 IDE 已通过 **VPN** 接入 `192.168.20.0/24`，需要调用 100 上 GBS Dubbo 服务进行开发联调。  
> 脚本目录：`docs/gbs/scripts/dubbo-dev-proxy/`  
> **本文档为唯一实施指南**，可独立指导任意新会话从零搭建整套方案。

---

## 0. 新会话快速实施清单

按顺序执行，已完成的步骤可跳过。

| 步骤 | 动作 | 验收标准 |
|------|------|----------|
| 0 | 确认 VPN 连通 `192.168.20.100` | `Test-NetConnection 192.168.20.100 -Port 30140` 成功 |
| 1 | 检查 100 是否已装代理（见 **4.0**） | `dubbo-proxy-status.sh` 显示 `running` |
| 2 | 未安装则执行 **4.2** 或 `deploy_plan_c.py` | `32080`、`32084` 端口 LISTEN |
| 3 | 确认本项目代码改动已就位（见 **5.7**） | `bootstrap.yml` / `application-local.yml` / Dubbo Client 已配置 |
| 4 | IDEA 设置 `local` profile + VM Options（见 **5.4**） | 启动无 Nacos 报错 |
| 5 | 启动本地服务，检查 Dubbo 日志 | 连接 `192.168.20.100:32080`，**无** `10.244.*` 超时 |
| 6 | 功能验证 | 用户同步、短信等依赖 GBS 的接口正常 |

**关键端口速记（safety-eval 常用）**：

| Facade / 服务 | GBS 服务名 | 代理端口 |
|---------------|-----------|----------|
| **UserFacade** | jjb-saas-**system** | **32080** |
| **MessageFacade** | jjb-saas-**message** | **32084** |
| user 服务（非 UserFacade） | jjb-saas-user | 32088 |

> 易错点：`UserFacade` 在 **system（32080）**，不是 user（32088）。

---

## 1. 方案原理

### 1.1 要解决的问题

| 现象 | 原因 |
|------|------|
| 本地连 Nacos 后 Dubbo 调用失败 | Nacos 返回 Provider 地址为 `10.244.x.x:20880`（Pod 网段） |
| VPN 能访问 100，但仍调不通 Dubbo | VPN 通常只路由 `192.168.20.0/24`，不包含 Pod 网段 `10.244.0.0/16` |

### 1.2 方案 C 做法

在 **192.168.20.100 主机** 上运行 `socat` TCP 代理：

```text
本地 IDE  --VPN-->  192.168.20.100:32080  --socat-->  10.244.x.x:20880 (system Pod)
                         固定端口                         当前 Pod IP（动态刷新）
```

### 1.3 与已废弃「NodePort + 改注册」方案 A 的区别

| 对比项 | 已废弃方案 A | **方案 C（本文）** |
|--------|-------------|-------------------|
| 创建 K8s `*-dubbo` Service | 是 | **否** |
| 修改 `DUBBO_IP_TO_REGISTRY` | 是 | **否** |
| 修改 Nacos 注册地址 | 是 | **否** |
| 影响集群内服务互调 | 是 | **否** |
| 本地可通过固定端口访问 Dubbo | 是 | **是** |

**结论：方案 C 只在 100 主机做端口转发，K8s 内部仍保持 Pod IP 注册与 ClusterIP 通讯。禁止重新执行方案 A。**

---

## 2. 架构图

```mermaid
flowchart LR
    subgraph local [本地开发机 VPN]
        IDE[IDE / 本地 Java]
    end

    subgraph host100 [192.168.20.100 主机]
        Socat[socat 32080-32100]
        FW[firewalld]
    end

    subgraph k8s [jjb-dragon 集群内 - 不变]
        PodSystem[system Pod 10.244.x.x:20880]
        PodMessage[message Pod 10.244.x.x:20880]
        Nacos[prod-nacos:8848]
    end

    IDE -->|192.168.20.100:32080 UserFacade| FW
    IDE -->|192.168.20.100:32084 MessageFacade| FW
    FW --> Socat
    Socat --> PodSystem
    Socat --> PodMessage
    PodSystem --> Nacos
    PodMessage --> Nacos
```

---

## 3. 端口映射表

沿用历史开发端口，便于本地配置复用（见 `dubbo-proxy.map`）：

| 本地固定端口 | GBS 服务 | Pod 标签 | Dubbo 端口 |
|-------------|----------|----------|------------|
| **32080** | **jjb-saas-system** | jjb-saas-system-pod | 20880 |
| 32081 | jjb-saas-auth | jjb-saas-auth-pod | 20880 |
| 32082 | jjb-saas-events | jjb-saas-events-pod | 20880 |
| 32083 | jjb-saas-security | jjb-saas-security-pod | 20880 |
| **32084** | **jjb-saas-message** | jjb-saas-message-pod | 20880 |
| 32085 | jjb-saas-login | jjb-saas-login-pod | 20880 |
| 32086 | jjb-saas-base | jjb-saas-base-pod | 20880 |
| 32087 | jjb-saas-process-layout | jjb-saas-process-layout-pod | 20880 |
| 32088 | jjb-saas-user | jjb-saas-user-pod | 20880 |
| 32089 | jjb-saas-official | jjb-saas-official-pod | 20880 |
| 32090 | jjb-saas-facade | jjb-saas-facade-pod | 20880 |
| 32091 | jjb-saas-open-platform | jjb-saas-open-platform-pod | 20880 |
| 32092 | jjb-saas-application | jjb-saas-application-pod | 20880 |
| 32093 | jjb-saas-attachment | jjb-saas-attachment-pod | 20880 |
| 32094 | jjb-saas-formily-design | jjb-saas-formily-design-pod | 20880 |
| 32095 | jjb-saas-desk | jjb-saas-desk-pod | 20880 |
| 32096 | jjb-saas-config | jjb-saas-config-pod | 20880 |
| 32097 | jjb-saas-document | jjb-saas-document-pod | 20880 |
| 32098 | jjb-saas-component-design | jjb-saas-component-design-pod | 20880 |
| 32099 | jjb-saas-view | jjb-saas-view-pod | 20880 |
| 32100 | jjb-saas-gateway | jjb-saas-gateway-pod | 20880 |

---

## 4. 100 服务器需要做什么

### 4.0 判断是否已安装（先执行，可跳过安装）

在 100 上执行：

```bash
# 目录与 systemd 是否存在
ls /opt/dubbo-dev-proxy/dubbo-proxy-status.sh
systemctl is-active dubbo-dev-proxy.timer

# 代理是否在跑
/opt/dubbo-dev-proxy/dubbo-proxy-status.sh

# 关键端口是否在监听
ss -lntp | grep -E ':32080|:32084'
```

**已安装且 running** → 跳到 **4.3** 日常运维，或直接进入本文 **第 5 节** 配置本地。

**未安装或 stopped** → 执行 **4.2** 安装。

从开发机远程一键检查（需 Python + paramiko）：

```bash
python docs/gbs/scripts/dubbo-dev-proxy/debug_plan_c.py
```

### 4.1 前置条件

| 项 | 要求 |
|----|------|
| 主机 | `192.168.20.100`（K8s Master） |
| 权限 | `root` SSH |
| 工具 | `kubectl` 可用、`socat`（脚本自动安装） |
| K8s | 命名空间 `jjb-dragon` 内目标 Pod 为 Running |
| 网络 | 100 主机能访问 Pod IP（`10.244.0.0/16`） |

### 4.2 一次性安装

**方式 A：在 100 上手动安装**

```bash
ssh root@192.168.20.100
cd /path/to/safety-eval-service/docs/gbs/scripts/dubbo-dev-proxy
chmod +x *.sh
sudo ./dubbo-proxy-install.sh
```

**方式 B：从开发机 SSH 自动部署（推荐新会话使用）**

```bash
# 需 pip install paramiko
python docs/gbs/scripts/dubbo-dev-proxy/deploy_plan_c.py
```

脚本会上传 `*.sh` 与 `dubbo-proxy.map` 到 100 的 `/opt/dubbo-dev-proxy-src/`，再执行 `dubbo-proxy-install.sh`。

安装脚本会：

1. 安装 `socat`
2. 复制配置到 `/opt/dubbo-dev-proxy/`
3. 开放防火墙 `32080-32100/tcp`
4. 注册 systemd 服务 + 定时器（每 3 分钟自动刷新 Pod IP）

### 4.3 日常运维命令

```bash
# 查看代理状态
/opt/dubbo-dev-proxy/dubbo-proxy-status.sh

# Pod 重启/漂移后手动刷新
/opt/dubbo-dev-proxy/dubbo-proxy-refresh.sh

# 停止全部开发代理（下班/不需要本地联调时）
/opt/dubbo-dev-proxy/dubbo-proxy-stop.sh

# 重新启用
systemctl start dubbo-dev-proxy.service
systemctl start dubbo-dev-proxy.timer
```

### 4.4 验证（在 100 上）

```bash
# 1. 代理进程
/opt/dubbo-dev-proxy/dubbo-proxy-status.sh

# 2. 端口监听
ss -lntp | grep -E '3208[0-9]|32100'

# 3. 本机探测 safety-eval 常用代理
nc -zv 127.0.0.1 32080   # system / UserFacade
nc -zv 127.0.0.1 32084   # message / MessageFacade

# 4. 确认 K8s 未被改动（方案 A 残留检查）
kubectl get svc -n jjb-dragon | grep dubbo          # 应无 *-dubbo
kubectl get deploy -n jjb-dragon -o yaml | grep DUBBO_IP_TO_REGISTRY  # 应无输出
```

### 4.5 100 服务器清单（汇总）

| 类别 | 路径/端口 | 说明 |
|------|-----------|------|
| 安装目录 | `/opt/dubbo-dev-proxy/` | 脚本与 map 配置 |
| 上传暂存 | `/opt/dubbo-dev-proxy-src/` | `deploy_plan_c.py` 上传位置 |
| PID 目录 | `/var/run/dubbo-dev-proxy/` | socat 进程 PID |
| 日志 | `/var/log/dubbo-dev-proxy/` | 按端口分日志 |
| systemd | `dubbo-dev-proxy.service` | 刷新代理 |
| systemd timer | `dubbo-dev-proxy.timer` | 每 3 分钟自动刷新 |
| 防火墙 | `32080-32100/tcp` | 仅开发代理端口 |
| **不改** | K8s Deployment/Service | 无 env、无 NodePort Service |
| **不改** | Nacos 注册信息 | Provider 仍为 Pod IP |

---

## 5. 本地开发机需要做什么

### 5.1 前置条件

| 项 | 要求 |
|----|------|
| VPN | 已连接，能访问 `192.168.20.100` |
| JDK | 1.8（与项目一致） |
| IDE | IntelliJ IDEA / 其他支持 Spring Boot |

### 5.2 基础连通性自检

在本地 PowerShell / Git Bash 执行：

```powershell
# VPN + 网关
curl -s -o /dev/null -w "gateway:%{http_code}\n" http://192.168.20.100:30140/

# Nacos
curl -s -o /dev/null -w "nacos:%{http_code}\n" http://192.168.20.100:30290/nacos/

# Dubbo 代理（safety-eval 常用端口）
Test-NetConnection 192.168.20.100 -Port 32080   # UserFacade
Test-NetConnection 192.168.20.100 -Port 32084   # MessageFacade
```

### 5.3 本地配置原则

1. **Nacos**：用 NodePort `30290` 拉配置，namespace `jjb-dragon`
2. **HTTP**：走网关 `http://192.168.20.100:30140`
3. **MySQL/Redis**：直连 `192.168.20.100:33080` / `6379`
4. **Dubbo**：**不要**依赖 Nacos 自动发现的 `10.244.*` 地址；对需要的接口使用 **显式 URL** `dubbo://192.168.20.100:32xxx`
5. **本地服务注册**：关闭 Nacos discovery，避免以线上同名注册到 `jjb-dragon`

### 5.4 safety-eval 本地 Profile 配置

**模板文件**（完整版，含数据源密码）：

```text
docs/gbs/scripts/dubbo-dev-proxy/application-local.example.yml
```

**本项目已提交的配置**（精简版，依赖 nacos 公共配置）：

```text
safety-eval-start/src/main/resources/application-local.yml
```

`bootstrap.yml` 已在 `local` profile 中 import `application-local.yml`，**无需额外改动 bootstrap**。

IDE VM Options 示例：

```text
-Dspring.profiles.active=local
-Dnacos.url=192.168.20.100:30290
-Dmysql.host=192.168.20.100
-Dmysql.port=33080
-Dmysql.username=root
-Dmysql.password=Mysql@zcloud33080
-DGBS_USER_FACADE_URL=dubbo://192.168.20.100:32080
-DGBS_MESSAGE_FACADE_URL=dubbo://192.168.20.100:32084
```

IDEA 环境变量（可选，与 VM Options 二选一）：

```text
GBS_USER_FACADE_URL=dubbo://192.168.20.100:32080
GBS_MESSAGE_FACADE_URL=dubbo://192.168.20.100:32084
```

### 5.5 Dubbo 依赖与端口对照

| 业务依赖 | GBS 服务 | 显式 URL |
|----------|----------|----------|
| 用户 Facade（**UserFacade**） | jjb-saas-system | `dubbo://192.168.20.100:32080` |
| 消息 Facade（**MessageFacade**） | jjb-saas-message | `dubbo://192.168.20.100:32084` |
| 认证 / 安全 | jjb-saas-auth / security | `32081` / `32083` |
| 附件 | jjb-saas-attachment | `dubbo://192.168.20.100:32093` |

更多端口见 `dubbo-reference-local.example.properties`。

### 5.6 本地清单（汇总）

| 类别 | 配置 | 值 |
|------|------|-----|
| Profile | `spring.profiles.active` | `local` |
| Nacos 配置中心 | `spring.cloud.nacos.config.server-addr` | `192.168.20.100:30290` |
| Nacos 命名空间 | `jjb-dragon` | 与线上一致（只读拉配置） |
| Nacos 服务注册 | `spring.cloud.nacos.discovery.enabled` | `false` |
| 网关 | `gateway.url` | `http://192.168.20.100:30140` |
| MySQL | host/port | `192.168.20.100:33080` |
| Redis | host/port | `192.168.20.100:6379` |
| Dubbo UserFacade | `GBS_USER_FACADE_URL` | `dubbo://192.168.20.100:32080` |
| Dubbo MessageFacade | `GBS_MESSAGE_FACADE_URL` | `dubbo://192.168.20.100:32084` |
| 本地服务端口 | `server.port` | `8095` |

### 5.7 本项目已改文件清单（新会话核对用）

| 文件 | 改动说明 |
|------|----------|
| `safety-eval-start/src/main/resources/bootstrap.yml` | `local` profile import `application-local.yml` |
| `safety-eval-start/src/main/resources/application-local.yml` | 关闭 discovery；配置 Dubbo 显式 URL |
| `safety-eval-infrastructure/.../GbsUserFacadeClient.java` | `@DubboReference(url = "${safety-eval.gbs-user-sync.user-facade-url:}")` |
| `safety-eval-infrastructure/.../SmsRemote.java` | `@DubboReference(url = "${safety-eval.dubbo.message-facade-url:}")` |

新增 Dubbo 依赖时，按同样模式在 `application-local.yml` 增加 URL 属性，并在对应 `@DubboReference` 绑定 `${...}` 占位符。

---

## 6. 完整操作流程（首次）

### Step 1：100 安装或确认代理

```bash
# 先检查（4.0），未安装则：
python docs/gbs/scripts/dubbo-dev-proxy/deploy_plan_c.py
# 或 SSH 到 100 手动执行 dubbo-proxy-install.sh
```

### Step 2：本地验证 VPN + 代理端口

```powershell
Test-NetConnection 192.168.20.100 -Port 32080
Test-NetConnection 192.168.20.100 -Port 32084
Test-NetConnection 192.168.20.100 -Port 30140
Test-NetConnection 192.168.20.100 -Port 30290
```

### Step 3：本地配置 IDE

1. 确认 `application-local.yml` 存在（或从 example 复制）
2. 设置 VM Options（见 5.4）
3. Active profiles 填 `local`

### Step 4：启动本地服务并验证

启动后检查日志：

- Nacos 配置拉取成功
- Dubbo 连接 `192.168.20.100:32080` / `32084` 成功
- **无** `10.244.x.x` 连接超时

### Step 5：功能验证

- 调用依赖 GBS 用户的接口（用户同步）
- 调用依赖短信的接口（MessageFacade）
- 通过网关 `30140` 访问前端页面（可选）

---

## 7. 故障排查

| 现象 | 排查 |
|------|------|
| 本地 `32080` / `32084` 连不上 | VPN 是否通；100 上 `dubbo-proxy-status.sh` 是否 running；防火墙是否开放 |
| Dubbo 仍连 `10.244.*` | 未走 `local` profile；未配置显式 URL；检查 `GbsUserFacadeClient` / `SmsRemote` |
| 代理 running 但调用失败 | Pod 已漂移，执行 `dubbo-proxy-refresh.sh` 或 `debug_plan_c.py` |
| 100 上某服务显示 skipped | 对应 Pod 非 Running，`kubectl get pods -n jjb-dragon` 检查 |
| 集群内服务异常 | 确认未改 Deployment env；`kubectl get svc -n jjb-dragon \| grep dubbo` 应为空 |
| UserFacade 调不通但 32088 通 | **端口配错**：UserFacade 用 `32080`（system），不是 `32088`（user） |

---

## 8. 安全与维护建议

1. **限制访问源**：若 VPN 网段固定，可将 `32080-32100` 仅对 VPN 网段开放（`firewall-cmd --add-rich-rule`）
2. **下班停止**：不需要联调时 `dubbo-proxy-stop.sh`，减少暴露面
3. **禁止方案 A**：不得创建 `*-dubbo` NodePort Service 或设置 `DUBBO_IP_TO_REGISTRY`
4. **Pod 大规模重启后**：手动执行一次 `dubbo-proxy-refresh.sh`
5. **定期核对**：`kubectl get svc -n jjb-dragon | grep dubbo` 应始终为空

---

## 9. 相关文档

- `docs/gbs/GBS底座服务手册v2.md` — 端口与 Nacos 外部访问说明
- `docs/本地JAR打包发布到100服务器完整流程.md` — K8s 部署流程（与本地开发并行）

---

## 10. 脚本文件说明

| 文件 | 用途 |
|------|------|
| `dubbo-proxy.map` | 端口 ↔ Pod 标签映射 |
| `dubbo-proxy-install.sh` | 100 一次性安装 |
| `dubbo-proxy-refresh.sh` | 刷新 socat 到当前 Pod IP |
| `dubbo-proxy-status.sh` | 查看运行状态 |
| `dubbo-proxy-stop.sh` | 停止全部代理 |
| `deploy_plan_c.py` | 从开发机 SSH 上传并安装（新会话推荐） |
| `debug_plan_c.py` | 远程诊断代理与 Pod 状态 |
| `application-local.example.yml` | 本地 IDE 完整配置模板 |
| `dubbo-reference-local.example.properties` | Dubbo 显式 URL 速查 |