hyapi-server/docs/戎行OpenVPN接入方案.md

# 戎行数据源 OpenVPN 接入方案（1Panel）

> 目标：**仅** `rongxing`（`http://192.168.3.43:7007`）走企业 VPN；Postgres / Redis / 其它外部 API 仍走原出口。  
> 方案：**OpenVPN 容器 + SOCKS5 代理 + 戎行 HTTP 客户端单独走代理**。

---

## 1. 架构

```
                    hyapi-network（现有 bridge）
┌─────────────────────────────────────────────────────────────┐
│  hyapi-app / hyapi-worker                                   │
│    ├─ DB / Redis / 其它 API  ──► 默认出口（不经 VPN）         │
│    └─ 戎行 Client            ──► socks5://rongxing-vpn:1080 │
│                                      │                      │
│  rongxing-vpn（openvpn + microsocks）│                      │
│    TUN ──► OpenVPN Server 111.31.14.226:32199               │
│         ──► 企业内网 192.168.3.43:7007                       │
└─────────────────────────────────────────────────────────────┘
```

要点：

- 业务容器网络身份不变（端口、健康检查、服务发现保持现状）。
- VPN 只负责进企业网；对外暴露的是 Docker 内网 SOCKS5，不映射到公网。
- OpenVPN 使用 `route-nopull`，只加 `192.168.3.43`，避免抢走默认路由。

---

## 2. VPN 材料要不要上传？

**要上传，但只上传「客户端配置与证书」，不要上传整个 Windows OpenVPN 安装目录。**

| 本地路径（你机器） | 是否上传 | 说明 |
|--------------------|----------|------|
| `OpenVPN\config\tiany0721.ovpn` | ✅ | 连接配置（服务器上会再加路由控制指令） |
| `OpenVPN\config\ca.crt` | ✅ | CA |
| `OpenVPN\config\tiany0721.crt` | ✅ | 客户端证书 |
| `OpenVPN\config\tiany0721.key` | ✅ | 客户端私钥（敏感） |
| `OpenVPN\config\ta.key` | ✅ | tls-auth |
| `OpenVPN\bin\`、`doc\`、`Uninstall.exe` 等 | ❌ | Windows 安装包，容器不用 |

服务器上使用 **Linux 版 OpenVPN 镜像**，复用上述 5 个文件即可。

---

## 3. 1Panel 推荐目录（最优落点）

假设 1Panel 数据盘常用根为 `/opt/1panel`（若你改过安装目录，把前缀换成实际路径）。

**推荐：密钥与业务代码分离。**

```text
/opt/1panel/apps/hyapi/                          # 业务 Compose / 代码（可随发布更新）
├── docker-compose.prod.yml
├── config.yaml / configs/...
├── ...
└── （不要把 .key 放进 git 仓库目录）

/opt/1panel/apps/hyapi-secrets/openvpn/          # ★ VPN 机密目录（推荐）
├── tiany0721.ovpn                               # 服务器侧改过的版本（见下文）
├── ca.crt
├── tiany0721.crt
├── tiany0721.key                                # 权限 600
└── ta.key                                       # 权限 600
```

备选（同样可以）：

```text
/data/hyapi/secrets/openvpn/                     # 若 1Panel 数据盘挂在 /data
```

**不要放：**

- 网站静态目录 `/opt/1panel/www/...`（易被误暴露）
- 仓库内 `hyapi-server/config/` 或会随 CI 同步的路径（防泄漏）

**权限建议（SSH 上执行）：**

```bash
sudo mkdir -p /opt/1panel/apps/hyapi-secrets/openvpn
sudo chmod 700 /opt/1panel/apps/hyapi-secrets
sudo chmod 700 /opt/1panel/apps/hyapi-secrets/openvpn
# 上传文件后：
sudo chmod 600 /opt/1panel/apps/hyapi-secrets/openvpn/*.key
sudo chmod 644 /opt/1panel/apps/hyapi-secrets/openvpn/*.{crt,ovpn}
```

---

## 4. 服务器侧 OpenVPN 配置（准备好再挂载）

把本地 `tiany0721.ovpn` 拷到服务器后，**追加**以下行（保留原有 `remote` / 证书引用）：

```conf
# --- 仅路由戎行内网，不接管默认网关 ---
route-nopull
route 192.168.3.43 255.255.255.255
```

完整示例见仓库：`deployments/openvpn/tiany0721.ovpn.example`。

证书相对路径保持与 `.ovpn` 同目录即可（`ca ca.crt` 等），挂载整个目录到容器 `/vpn`。

---

## 5. Compose 片段（接入现有 prod）

参考文件：`deployments/openvpn/docker-compose.rongxing-vpn.snippet.yml`

核心服务示意：

```yaml
  rongxing-vpn:
    image: ghcr.io/linuxserver/openvpn-as:latest   # 不推荐 AS；见下方推荐镜像
```

**推荐用轻量客户端镜像**（文档配套 snippet 已按此写）：

- 镜像：`dperson/openvpn-client` **或** 自建 `alpine + openvpn + microsocks`
- 能力：`cap_add: [NET_ADMIN]`，`devices: [/dev/net/tun]`
- 挂载：`/opt/1panel/apps/hyapi-secrets/openvpn:/vpn:ro`
- 网络：加入现有 `hyapi-network`
- **不要**把 `1080` 映射到宿主机公网端口

业务侧：

- `hyapi-app` /（若异步也会调戎行）`hyapi-worker` 保持原 `networks: [hyapi-network]`
- 配置增加代理地址：`socks5://rongxing-vpn:1080`

---

## 6. 应用配置（仅戎行）

在 `rongxing` 段增加代理字段（实现代码时再接线；配置先预留）：

```yaml
rongxing:
  url: "http://192.168.3.43:7007"
  account: "..."
  password: "..."
  app_id: "..."
  private_key: "..."
  timeout: 10s
  # 仅戎行走 VPN 旁路代理；留空则直连（开发机已连 VPN 时可留空）
  proxy: "socks5://rongxing-vpn:1080"
  logging:
    # ...
```

开发机若已用 GUI 连上 VPN，`proxy` 留空即可，无需起 Docker VPN。

---

## 7. 代码改动清单（后续开发）

当前 `RongxingService` 使用裸 `http.Client`，需：

1. `RongxingConfig` / `serviceConfig` 增加 `Proxy string`
2. `NewRongxingServiceWithConfig` 传入 `cfg.Rongxing.Proxy`
3. 创建 `http.Client` 时：若 `Proxy` 非空，用 `http.ProxyURL` 或 SOCKS5 dialer（`golang.org/x/net/proxy`）
4. **只改戎行包**，其它外部服务不动

验证点：未配 `proxy` 时行为与现在一致。

---

## 8. 1Panel 上操作清单

### 8.1 一次性准备

1. SSH 登录服务器，创建 `/opt/1panel/apps/hyapi-secrets/openvpn/`
2. 用 SFTP / `scp` 上传 5 个文件（见第 2 节）
3. 编辑服务器上的 `tiany0721.ovpn`，加上 `route-nopull` + `route 192.168.3.43 ...`
4. 设好目录/文件权限（第 3 节）
5. 确认内核允许 TUN：多数 1Panel/Linux 默认有 `/dev/net/tun`；若容器报错再装 `tun` 模块

### 8.2 接入 Compose

任选其一：

- **A. 1Panel「编排」**：打开现有 hyapi 的 Compose，粘贴 `rongxing-vpn` 服务片段，挂载 secrets 目录，重新部署  
- **B. 独立编排**：单独建一个 `rongxing-vpn` 栈，但必须加入与 hyapi **同一个** Docker network（`hyapi-network` 的外部网络名以 `docker network ls` 为准）

查现有网络名：

```bash
docker network ls | grep hyapi
docker inspect hyapi-app-prod --format '{{json .NetworkSettings.Networks}}'
```

若网络是 compose 项目前缀（如 `hyapi-server_hyapi-network`），独立栈里要：

```yaml
networks:
  hyapi-network:
    external: true
    name: hyapi-server_hyapi-network   # 以实际名为准
```

### 8.3 发布后验证

```bash
# 1) VPN 容器是否拿到 tun / 路由
docker exec -it <rongxing-vpn容器名> ip route
# 应能看到 192.168.3.43 经 tun0

# 2) 在 VPN 容器内测内网（镜像若有 curl）
docker exec -it <rongxing-vpn容器名> wget -qO- --timeout=5 http://192.168.3.43:7007/ || true

# 3) 从业务容器经 SOCKS5 测（需业务镜像有 curl，或临时 alpine）
docker run --rm --network <hyapi网络名> curlimages/curl:8.5.0 \
  -x socks5h://rongxing-vpn:1080 -m 10 -v http://192.168.3.43:7007/

# 4) 确认「不走代理」时业务仍能访问公网/库（对照现有 health）
curl -f http://127.0.0.1:25000/health
```

业务侧再打一笔戎行真实查询，看 `logs/external_services` 下戎行日志是否成功。

---

## 9. 安全与运维

- `.key` / `ta.key` / 账号密码：**不进 Git**；secrets 目录不挂到可下载的 Web 根。
- SOCKS5 **仅**监听容器网络，不 `-p 1080:1080` 到宿主机。
- VPN 证书到期前找对方续期，替换 secrets 目录文件后 `docker compose restart rongxing-vpn`。
- 断线策略：容器 `restart: unless-stopped`；OpenVPN 侧已有 `resolv-retry infinite` / `persist-tun`。
- 监控：可对 `rongxing-vpn` 做 1Panel 容器存活告警；业务侧戎行错误率告警。

---

## 10. 本地文件 → 服务器对照表

| 本地 | 服务器推荐路径 |
|------|----------------|
| `...\OpenVPN\config\tiany0721.ovpn` | `/opt/1panel/apps/hyapi-secrets/openvpn/tiany0721.ovpn`（改过路由） |
| `...\OpenVPN\config\ca.crt` | 同目录 |
| `...\OpenVPN\config\tiany0721.crt` | 同目录 |
| `...\OpenVPN\config\tiany0721.key` | 同目录（600） |
| `...\OpenVPN\config\ta.key` | 同目录（600） |
| Windows `bin/` 整包 | **不上传** |

---

## 11. 实施状态与顺序

**代码与 Compose 已落地**（见仓库当前变更）：

- `rongxing` 支持 `proxy`（SOCKS5/HTTP）
- `docker-compose.prod.yml` 已加入 `rongxing-vpn` 服务
- `deployments/openvpn/` 自建镜像（OpenVPN + microsocks）
- 生产配置 `configs/env.production.yaml`：`proxy: "socks5://rongxing-vpn:1080"`

**1Panel 服务器仍需人工完成：**

1. 创建 `/opt/1panel/apps/hyapi-secrets/openvpn/`，上传 5 个证书/配置文件（可用本机已备好的 `secrets/openvpn/` 内容）
2. 设置环境变量：`RONGXING_VPN_CONFIG=/opt/1panel/apps/hyapi-secrets/openvpn`
3. 拉取/构建并重新部署 Compose（确保服务器能访问 Docker Hub / 镜像源以下载 `alpine`）
4. 验证：`docker exec hyapi-rongxing-vpn ip route` 含 `192.168.3.43`；业务侧打一笔戎行查询