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

> 适用场景：本地 IDE 已通过 **VPN** 接入 `192.168.20.0/24`，需要调用 100 上 GBS Dubbo 服务进行开发联调。  
> 脚本目录：`docs/gbs/scripts/dubbo-dev-proxy/`

---

## 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:32088  --socat-->  10.244.x.x:20880 (user Pod)
                         固定端口                         当前 Pod IP（动态刷新）
```

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

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

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

---

## 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 集群内 - 不变]
        Pod1[user Pod 10.244.x.x:20880]
        Pod2[system Pod 10.244.x.x:20880]
        Nacos[prod-nacos:8848]
    end

    IDE -->|192.168.20.100:32088| FW
    FW --> Socat
    Socat --> Pod1
    Pod2 --> Nacos
    Pod1 --> 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 |

> **safety-eval** 常用：`32080`（system/UserFacade）、`32084`（message/MessageFacade）等，按实际依赖选用。

---

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

### 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 一次性安装

将仓库中脚本目录上传到 100（或在 100 上 git pull 后执行）：

```bash
# 在 100 上执行
cd /path/to/safety-eval-service/docs/gbs/scripts/dubbo-dev-proxy
chmod +x *.sh
sudo ./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. 本机探测 user 代理（示例）
nc -zv 127.0.0.1 32088

# 4. 确认 K8s 未被改动
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 配置 |
| 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 执行：

```bash
# 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 代理（100 上方案 C 启用后）
# Windows 可用 Test-NetConnection
Test-NetConnection 192.168.20.100 -Port 32088
```

### 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. **本地服务注册**：不要以线上同名注册到 `jjb-dragon`（避免污染负载）

### 5.4 safety-eval 本地 Profile 示例

复制 `application-local.example.yml` 为本地使用（**不要提交含密码的私人配置**）：

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

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 环境变量（可选）：

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

### 5.5 Dubbo 依赖与端口对照（按需配置）

| 业务依赖 | 建议显式 URL |
|----------|-------------|
| 用户 Facade（UserFacade，system 服务） | `dubbo://192.168.20.100:32080` |
| 消息 Facade（MessageFacade） | `dubbo://192.168.20.100:32084` |
| 认证/安全 | `dubbo://192.168.20.100:32081` / `32083` |
| 附件 | `dubbo://192.168.20.100:32093` |

若项目通过 `@DubboReference` 自动发现，需在本地 profile 中为对应 reference 配置 `url` 属性，或关闭该 bean 的注册中心发现（按 GBS client 模块约定）。

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

| 类别 | 配置 | 值 |
|------|------|-----|
| Profile | `spring.profiles.active` | `local` |
| Nacos 配置中心 | `spring.cloud.nacos.config.server-addr` | `192.168.20.100:30290` |
| Nacos 命名空间 | `jjb-dragon` | 与线上一致（只读拉配置） |
| 网关 | `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`（与项目默认一致） |
| **禁止** | 注册到线上同名 Nacos 服务 | 使用独立服务名或关闭注册 |

---

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

### Step 1：100 安装代理

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

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

```powershell
Test-NetConnection 192.168.20.100 -Port 32088
Test-NetConnection 192.168.20.100 -Port 30140
Test-NetConnection 192.168.20.100 -Port 30290
```

### Step 3：本地配置 IDE

1. 复制 `application-local.example.yml` 为 `application-local.yml`（放在 `safety-eval-start/src/main/resources/` 或 IDE 外部配置）
2. 设置 VM Options（见 5.4）
3. Active profiles 填 `local`

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

```bash
# 本地启动后检查日志
# - Nacos 配置拉取成功
# - Dubbo 连接 192.168.20.100:32088 成功
# - 无 10.244.x.x 连接超时
```

### Step 5：功能验证

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

---

## 7. 故障排查

| 现象 | 排查 |
|------|------|
| 本地 `32088` 连不上 | VPN 是否通；100 上 `dubbo-proxy-status.sh` 是否 running；防火墙是否开放 |
| Dubbo 仍连 `10.244.*` | 本地未覆盖 URL，仍走 Nacos 自动发现；检查 profile / 环境变量 |
| 代理 running 但调用失败 | Pod 已漂移，执行 `dubbo-proxy-refresh.sh` |
| 100 上某服务显示 skipped | 对应 Pod 非 Running，`kubectl get pods -n jjb-dragon` 检查 |
| 集群内服务异常 | **立即停止代理排查**，确认未改 Deployment env（方案 C 不应影响） |

---

## 8. 安全与维护建议

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

---

## 9. 相关文档

- `docs/gbs/GBS-Dubbo-NodePort映射与还原记录.md` — 已废弃方案与还原记录
- `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` | 停止全部代理 |
| `application-local.example.yml` | 本地 IDE 配置模板 |