opsx-vpn/README.md

# VPN 专线管理平台

Gin + Vue3 + SQLite 的多协议 VPN 专线 Web 管理平台：**单二进制交付、配置简单、管理便捷、可扩展自定义协议**。

## 支持协议

| 协议 | 实现方式 | 场景 |
|---|---|---|
| WireGuard | 系统 `wg` / `wg-quick`，多 Peer、NAT/MTU、流量累计 | 内部接入、移动办公（首选） |
| IPSec | StrongSwan `swanctl`，厂商模板一键套用 | **第三方对接**、站点互联 |
| IKEv2 远程接入 | StrongSwan Road Warrior，PSK + EAP-MSCHAPv2 | 员工手机/笔记本原生拨号 |
| L2TP/IPSec | StrongSwan + xl2tpd，支持多拨号用户 | 手机/老设备兼容 |
| FRP | 直接管理 `frps` / `frpc`（TOML），含 STCP/XTCP | 内网穿透、端口映射 |
| GRE | Linux `ip tunnel` 管理标准 GRE 隧道 | 点对点网站互联 |
| OpenVPN | 进程管理 + PKI；UDP/TCP 可切换；证书/密码 + TOTP MFA | 老项目兼容 |
| 自定义协议 | 插件命令钩子（Create/Start/Stop/Status/Config） | 任意协议扩展 |

## 核心功能

- **专线列表**：名称/协议/状态/流量/到期时间，一键启停、编辑、删除、下载配置、WireGuard 二维码
- **创建向导**：选协议 → 依赖检测门控（未就绪不可选，引导下载/安装）→ 填参数（高级折叠）→ 必填校验
- **在线会话**：跨协议统一展示在线用户、公网 IP、VPN IP、连接时长、流量；支持踢下线
- **流量审计**：连接审计日志（connect/disconnect/auth_fail）、异常突发流量告警、管理员手动踢下线
- **流量配额**：隧道级配额（GB）、超额动作（告警/停止/限速）、周期重置（日/月）
- **协议引擎管理**：FRP/OpenVPN 支持平台一键下载部署；WireGuard/StrongSwan 显示系统包安装命令
- **WireGuard Peer 管理**：详情内增删 Peer、按设备下载配置/二维码
- **拨号用户**：OpenVPN / L2TP / IKEv2 共用用户表；支持从平台用户导入、批量创建、LDAP 浏览导入
- **IPSec 第三方对接专页**：设备模板预置 Phase1/Phase2 参数、双方参数一致性检查、一键连通性测试
- **节点管理**：多中继节点，远程节点支持 SSH 凭证验证（密码/私钥、即时测试连接）
- **专线日志**：操作栏「更多 → 查看日志」SSE 实时输出实例进程日志
- **安全**：PSK/私钥 AES-GCM 加密存储、配置文件 0600 权限、操作审计
- **访问控制**：admin / operator / viewer；首登强制改密；登录防爆破；TOTP MFA + 备用码；LDAP

## 快速开始

### 本地构建与运行

```bash
./run.sh run          # 构建并运行（默认 admin / admin123）
./run.sh dev          # 开发模式（前后端分离）
./run.sh restart      # 重新构建并重启
./run.sh stop         # 停止服务
```

### Linux 服务器部署

```bash
# 1. 交叉编译 Linux 二进制（在 macOS 上）
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o opsx-vpn ./backend

# 2. 上传到服务器
scp opsx-vpn user@server:/opt/opsx-vpn/
cd /opt/opsx-vpn && chmod +x opsx-vpn

# 3. 安装系统依赖（按需）
apt install -y wireguard-tools openvpn strongswan strongswan-swanctl iproute2 iptables
# FRP 无需系统包 —— 平台 UI 内点「下载部署」自动从 GitHub 下载到 data/bin/

# 4. 启动（生产建议用 systemd 管理）
VPN_LISTEN_ADDR=:18080 ./opsx-vpn   # 生产管理端口 :18080，数据目录 ./data
```

### systemd 服务（生产推荐）

```ini
# /etc/systemd/system/opsx-vpn.service
[Unit]
Description=VPN Management Platform
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/opsx-vpn
ExecStart=/opt/opsx-vpn/opsx-vpn
Restart=always
RestartSec=5
# 环境变量按需调整
Environment=VPN_LISTEN_ADDR=:18080
Environment=VPN_DATA_DIR=/opt/opsx-vpn/data
# WireGuard/OpenVPN 需要 root 权限（创建 TUN 设备 + iptables）
# 如需降权，需配置 NET_ADMIN capability

[Install]
WantedBy=multi-user.target
```

```bash
systemctl daemon-reload
systemctl enable --now opsx-vpn
journalctl -u opsx-vpn -f   # 查看日志
```

## 防火墙 / 安全组端口

部署到云服务器时，需开放以下端口：

### VPN 数据通道（对公网开放）

| 端口 | 协议 | 类型 | 用途 |
|---|---|---|---|
| UDP 51820 | WireGuard | UDP | WG 默认监听端口（可在创建时改） |
| UDP 1194 | OpenVPN | UDP | OpenVPN 默认端口（可改 TCP） |
| TCP 1194 | OpenVPN | TCP | OpenVPN TCP 模式（如选 TCP） |
| UDP 500 | IPSec / IKEv2 / L2TP | UDP | IKE 密钥交换 |
| UDP 4500 | IPSec / IKEv2 / L2TP | UDP | NAT-T 穿透 |
| UDP 1701 | L2TP | UDP | L2TP 隧道 |
| TCP 7000 | FRP | TCP | frps 绑定端口（客户端连接用） |
| IP 协议 47 | GRE | GRE | GRE 封装（无 TCP/UDP 端口） |

### 管理（仅限你的 IP 或内网）

| 端口 | 协议 | 类型 | 用途 |
|---|---|---|---|
| TCP 18080 | 管理平台 | TCP | Web UI + API（**勿对公网开放**，建议 Nginx HTTPS 后改 443） |
| TCP 22 | SSH | TCP | 远程管理 |

### 安全组配置示例

```
# VPN 数据通道（对公网开放）
UDP  500/4500    0.0.0.0/0    # IPSec/IKEv2/L2TP 密钥交换 + NAT-T
UDP  51820       0.0.0.0/0    # WireGuard
UDP  1194        0.0.0.0/0    # OpenVPN UDP
TCP  1194        0.0.0.0/0    # OpenVPN TCP（如启用）
UDP  1701        0.0.0.0/0    # L2TP
TCP  7000        0.0.0.0/0    # FRP server
# GRE 不是 TCP/UDP 端口，需在安全组中放行 GRE / IP 协议 47
GRE  协议 47      对端公网 IP/32  # 建议只允许对端地址

# 管理（仅限你的 IP）
TCP  18080       你的IP/32    # 管理 UI
TCP  22          你的IP/32    # SSH
```

> **注意**：IPSec 必须同时开放 UDP 500 + 4500（缺一个连不上）。GRE 需要**本端、对端及中间云安全组**双向允许 **IP 协议 47**，不是端口号；Linux 端依赖 `iproute2` 的 `ip tunnel`。管理端口 18080 切勿对公网开放。仅用 WireGuard 最简部署只需 3 个端口：UDP 51820 + TCP 18080 + TCP 22。

## 协议依赖安装

| 协议 | 安装方式 | 平台下载 |
|---|---|---|
| WireGuard | `apt install -y wireguard-tools` | ❌ 系统包 |
| OpenVPN | `apt install -y openvpn` | ✅ GitHub Release / 系统包 |
| StrongSwan (IPSec/IKEv2/L2TP) | `apt install -y strongswan strongswan-swanctl` | ❌ 系统包 |
| GRE | `apt install -y iproute2`（多数系统默认已安装） | ❌ 系统包 |
| FRP | 无需系统包 | ✅ 平台 UI「下载部署」自动从 GitHub 下载 |

在「总览 → 协议引擎状态」表中，未就绪的协议会显示「下载部署」或「安装命令」按钮。

## 环境变量

| 变量 | 默认 | 说明 |
|---|---|---|
| `VPN_LISTEN_ADDR` | `:18080` | 监听地址 |
| `VPN_DATA_DIR` | `./data` | 数据目录（SQLite、密钥、实例配置、下载的二进制） |

## 常用命令

| 命令 | 说明 |
|---|---|
| `./run.sh run` | 构建并后台运行单二进制（默认） |
| `./run.sh build` | 全量构建（前端 + 后端二进制） |
| `./run.sh dev` | 开发模式（前后端分离） |
| `./run.sh stop` | 停止所有服务 |
| `./run.sh restart` | 重新构建并重启 |
| `./run.sh status` | 查看服务状态 |

## 项目结构

```
frontend/               # Vue3 + Element Plus 前端
backend/
  main.go               # Gin 入口（内嵌前端 embed.FS）
  internal/
    api/                # REST 路由与鉴权
    core/               # Protocol 统一接口 + 注册中心
    model/              # GORM 数据模型
    store/              # SQLite + AES-GCM 密钥存储
    service/            # 协议实现
      wireguard/ ipsec/ ikev2/ l2tp/ frp/ openvpn/
      custom/           # 自定义协议插件
    monitor/            # 状态/流量/会话/配额采集引擎
    sessionmgr/         # 在线会话同步 + 连接审计
    trafficmgr/         # 流量配额 + 异常检测 + 限速
    binmgr/             # 协议二进制下载部署 + 安装引导
    sshutil/            # SSH 连接测试（节点验证）
```

## 交付形态

- **单二进制**：前端构建后通过 `go:embed` 内嵌进 Go 二进制，`./opsx-vpn` 单文件即可运行（含 SPA + REST API + SQLite）
- 不依赖 Docker、不依赖外部数据库
- 纯静态编译：`CGO_ENABLED=0` 可交叉编译到任意 Linux/Windows