481 lines
17 KiB
Markdown
481 lines
17 KiB
Markdown
# RemLink
|
||
|
||
RemLink 是一套面向工业现场的 IPv4 三层远程接入系统，用于让远程工程师通过中心服务器安全访问现场 PLC、HMI、工控机及其他 IP 设备。
|
||
|
||
系统由三个完全独立的程序组成：
|
||
|
||
- **RemLink Server**：运行在 Linux，负责节点注册、Overlay 地址分配、WireGuard 中心转发、会话调度和 Web 管理。
|
||
- **RemLink Engineer**：运行在工程师 Windows 电脑，提供图形界面，把指定现场网段路由到当前远程会话。
|
||
- **RemLink Site**：运行在现场 Windows 电脑，通过 gVisor 用户态网络栈访问现场局域网设备。
|
||
|
||
典型数据路径：
|
||
|
||
```text
|
||
Engineer Windows
|
||
│
|
||
│ WireGuard Overlay
|
||
▼
|
||
RemLink Server（Linux 中心节点）
|
||
│
|
||
│ WireGuard Overlay
|
||
▼
|
||
Site Windows ── gVisor netstack ── 现场 LAN ── PLC/HMI/工控设备
|
||
```
|
||
|
||
Engineer、Site 和 Server 的发布包、配置及运行数据彼此独立，不能混放或互相替换。
|
||
|
||
## 主要功能
|
||
|
||
- 以 Linux 内核 WireGuard 为中心建立 `10.88.0.0/16` Overlay 网络。
|
||
- Engineer 和 Site 各自只创建并复用一个 `RemLink` Wintun 适配器。
|
||
- 自动注册节点、分配 Overlay IP、维护心跳及在线状态。
|
||
- Engineer 可选择 Site，并为该 Site 设置一个或多个远程 CIDR。
|
||
- 不同 Site 的远程网段分别保存，切换现场时不需要反复删除和重新添加。
|
||
- 支持多个 Engineer、多个 Site，以及不同 Site 使用相同现场网段。
|
||
- Site 使用进程内 gVisor netstack 转发通用 TCP、UDP 和 ICMP Echo 流量。
|
||
- Site 离线后，Server 自动关闭相关会话，Engineer 自动清理当前远程路由。
|
||
- Server 提供中文 Web 管理页面，可查看节点、会话、网络配置和事件日志。
|
||
- Engineer、Site、Server 的面向操作员日志均已中文化，同时保留协议状态和错误码。
|
||
- Engineer 和 Site 使用便携目录，配置、身份、日志和 `wintun.dll` 均位于各自 EXE 目录。
|
||
|
||
## 系统边界
|
||
|
||
- RemLink 是中心辐射结构，所有 Overlay 流量均经过 Server，不建立节点间 P2P。
|
||
- Site 不要求 PLC 或现场设备配置返回 Overlay 的路由。
|
||
- Site 必须从本机通过直连路由或明确静态路由到达现场网段；只有默认路由时会返回 `SITE_NO_ROUTE`。
|
||
- 每个 Engineer 同时只允许一个非终态远程会话。
|
||
- 当前版本只支持 IPv4，不提供二层以太网桥接。
|
||
- Server v1.0 不直接终止 TLS；公网管理和注册入口应置于 HTTPS 反向代理之后。
|
||
|
||
## 项目目录与文件作用
|
||
|
||
| 路径 | 作用 |
|
||
|---|---|
|
||
| `cmd/server/` | Linux Server 程序入口和启动编排 |
|
||
| `cmd/engineer/` | Windows Engineer/Wails GUI 程序入口 |
|
||
| `cmd/site/` | Windows Site 控制台程序入口 |
|
||
| `internal/admin/` | Server 管理 API、节点和网络配置管理 |
|
||
| `internal/bootstrap/` | 节点首次注册、Token 校验和权威配置下发 |
|
||
| `internal/control/` | Server 与 Windows 节点之间的控制通道 |
|
||
| `internal/session/` | 远程会话状态机、超时、关闭和统计 |
|
||
| `internal/overlay/clientwg/` | Windows wireguard-go、Wintun 和 PacketMux |
|
||
| `internal/overlay/serverwg/` | Linux 内核 WireGuard 管理 |
|
||
| `internal/subnetgateway/` | Site gVisor netstack 及 TCP/UDP/ICMP 转发 |
|
||
| `internal/platform/windows/` | Windows 路由、DPAPI、网卡和 Wintun 运行库 |
|
||
| `internal/database/`、`internal/ipam/` | SQLite 持久化和 Overlay 地址分配 |
|
||
| `frontend/engineer/` | Engineer Vue 图形界面，构建后嵌入 Wails EXE |
|
||
| `frontend/server/` | Server Vue Web 管理页面，构建后嵌入 Server 二进制 |
|
||
| `config/*.example.yaml` | Server、Engineer、Site 的安全配置模板 |
|
||
| `deploy/docker/` | Server Dockerfile、Compose、预检和中国网络模板 |
|
||
| `scripts/build-release.ps1` | 构建和验证三端独立发布包 |
|
||
| `scripts/validation/` | 架构、发布包和 T01–T18 验收工具 |
|
||
| `scripts/maintenance/` | Git 候选文件和敏感内容检查 |
|
||
| `specs/` | Phase 0–10 开发任务、规格和验收清单 |
|
||
| `docs/` | 中文部署、实现状态、设计和物理验收文档 |
|
||
| `third_party/`、`THIRD_PARTY_NOTICES.md` | 第三方组件许可说明 |
|
||
| `.github/workflows/ci.yml` | GitHub Actions 自动构建和测试 |
|
||
|
||
以下目录是本地生成内容，不应提交到 Git：
|
||
|
||
- `build/`：临时可执行文件。
|
||
- `dist/`：三端发布目录和 ZIP。
|
||
- `frontend/node_modules/`：前端依赖。
|
||
- `frontend/*/dist/`：前端编译结果。
|
||
- `data/`、`logs/`、`runtime/`、`evidence/`：运行数据和验收证据。
|
||
|
||
## 开发与打包环境
|
||
|
||
推荐在 Windows PowerShell 7 中执行发布脚本，准备：
|
||
|
||
- Go：版本以 `go.mod` 为准。
|
||
- Node.js：与 `.github/workflows/ci.yml` 中的版本一致。
|
||
- npm：使用 `frontend/package-lock.json` 锁定依赖。
|
||
- PowerShell 7。
|
||
- Git。
|
||
|
||
检查环境：
|
||
|
||
```powershell
|
||
go version
|
||
node --version
|
||
npm --version
|
||
git --version
|
||
$PSVersionTable.PSVersion
|
||
```
|
||
|
||
## 构建三个独立发布包
|
||
|
||
在项目根目录执行：
|
||
|
||
```powershell
|
||
$version = "1.0.7"
|
||
./scripts/build-release.ps1 -Version $version
|
||
```
|
||
|
||
版本号必须是语义化版本，例如 `1.0.7` 或 `1.1.0-beta.1`。发布脚本会自动执行：
|
||
|
||
1. Git 仓库候选文件和敏感内容检查。
|
||
2. 前端依赖清洁安装、Vue 类型检查和生产构建。
|
||
3. 前端 Demo 数据泄漏检查。
|
||
4. Go 依赖校验、全量测试和 `go vet`。
|
||
5. 架构规则与验收工具自测。
|
||
6. Windows/Linux 交叉编译。
|
||
7. 三端目录隔离、SHA-256 生成和发布包解压复核。
|
||
|
||
成功后在 `dist/` 得到：
|
||
|
||
```text
|
||
dist/
|
||
├─ RemLink-Engineer-v1.0.7-windows-amd64/
|
||
├─ RemLink-Engineer-v1.0.7-windows-amd64.zip
|
||
├─ RemLink-Site-v1.0.7-windows-amd64/
|
||
├─ RemLink-Site-v1.0.7-windows-amd64.zip
|
||
├─ RemLink-Server-v1.0.7-linux-amd64/
|
||
└─ RemLink-Server-v1.0.7-linux-amd64.zip
|
||
```
|
||
|
||
每个发布目录都包含 `BUILD-INFO.json` 和 `SHA256SUMS.txt`。Engineer 包不会包含 Site 或 Server，Site 包不会包含 Engineer 或 Server，Server 包也不会包含 Windows 客户端。
|
||
|
||
只运行开发检查、不生成发布包时执行：
|
||
|
||
```powershell
|
||
./scripts/maintenance/Test-RepositoryHygiene.ps1
|
||
npm ci --prefix frontend
|
||
npm run typecheck --prefix frontend
|
||
npm run build --prefix frontend
|
||
go test -count=1 ./...
|
||
go vet ./...
|
||
./scripts/validation/Test-FrontendProduction.ps1
|
||
./scripts/validation/Test-Architecture.ps1
|
||
./scripts/validation/Test-AcceptanceTools.ps1
|
||
```
|
||
|
||
## 部署前网络准备
|
||
|
||
| 端口 | 用途 | 是否需要公网或跨网访问 |
|
||
|---|---|---|
|
||
| `8080/tcp` | Web、Bootstrap、Admin API | 仅可信管理网；公网应使用 HTTPS 反向代理 |
|
||
| `51820/udp` | WireGuard 公网入口 | Engineer 和 Site 必须能够访问 |
|
||
| `7001/tcp` | Overlay Control WebSocket | 只在 Overlay 内使用，不映射公网 |
|
||
| `6200/udp` | Overlay Session 数据 | 只在 Overlay 内使用，不映射公网 |
|
||
|
||
部署前确认：
|
||
|
||
- Server 是 Linux amd64，并支持内核 WireGuard 和 `/dev/net/tun`。
|
||
- Engineer 和 Site 是 Windows amd64，并以管理员权限运行。
|
||
- 默认 Overlay `10.88.0.0/16` 不与任一 Windows 主机的本地网络重叠。
|
||
- Server 的 WireGuard UDP 端口已在云安全组、防火墙和 NAT 中放行。
|
||
- Site Windows 本机能够直接访问目标 PLC/HMI 网段。
|
||
|
||
## 部署 Server（Ubuntu + Docker Compose）
|
||
|
||
### 1. 检查宿主机
|
||
|
||
```bash
|
||
uname -m
|
||
test -c /dev/net/tun && echo "TUN 正常"
|
||
sudo modprobe wireguard
|
||
docker version
|
||
docker compose version
|
||
```
|
||
|
||
### 2. 解压和安装 Server 包
|
||
|
||
以下使用 `1.0.7` 举例，实际部署时替换为构建出的版本：
|
||
|
||
```bash
|
||
unzip RemLink-Server-v1.0.7-linux-amd64.zip
|
||
sudo mkdir -p /opt/remlink
|
||
sudo cp -a RemLink-Server-v1.0.7-linux-amd64/. /opt/remlink/
|
||
cd /opt/remlink/docker
|
||
```
|
||
|
||
### 3. 创建 `.env`
|
||
|
||
普通网络环境：
|
||
|
||
```bash
|
||
sudo cp .env.example .env
|
||
```
|
||
|
||
中国大陆网络环境：
|
||
|
||
```bash
|
||
sudo cp .env.china.example .env
|
||
```
|
||
|
||
编辑 `.env`。下面是通用模板的配置形式；如果复制的是 `.env.china.example`，请保留其中已经填写的两个镜像地址，不要用下面的空值覆盖：
|
||
|
||
```dotenv
|
||
REMLINK_WG_ENDPOINT=vpn.example.com:51820
|
||
REMLINK_WG_PORT=51820
|
||
REMLINK_HTTP_BIND=127.0.0.1
|
||
REMLINK_ADMIN_TOKEN=替换为足够长的随机管理令牌
|
||
REMLINK_APT_FORCE_IPV4=1
|
||
REMLINK_APT_DEBIAN_MIRROR=
|
||
REMLINK_APT_SECURITY_MIRROR=
|
||
```
|
||
|
||
关键配置说明：
|
||
|
||
- `REMLINK_WG_ENDPOINT`：Engineer/Site 实际可访问的公网 IP 或域名及 UDP 端口。
|
||
- `REMLINK_WG_PORT`：必须与 endpoint、`server.yaml`、防火墙和 NAT 端口一致。
|
||
- `REMLINK_HTTP_BIND=127.0.0.1`：Web 只允许本机反向代理访问。
|
||
- 需要在可信局域网直接打开 Web 时，可改为 Server 的管理网 IP；只有明确接受风险时才使用 `0.0.0.0`。
|
||
- `REMLINK_ADMIN_TOKEN`：Server Web 和 Admin API 的 Bearer Token，不能提交到 Git。
|
||
- 中国模板已设置适合中国网络的 Debian 镜像和 IPv4 构建参数。
|
||
|
||
### 4. 检查 Server YAML
|
||
|
||
`docker/server.yaml` 默认配置：
|
||
|
||
```yaml
|
||
server:
|
||
http_listen: "0.0.0.0:8080"
|
||
control_listen: "10.88.0.1:7001"
|
||
wireguard_port: 51820
|
||
|
||
data:
|
||
directory: "/app/data"
|
||
|
||
network:
|
||
overlay_cidr: "10.88.0.0/16"
|
||
server_overlay_ip: "10.88.0.1"
|
||
session_udp_port: 6200
|
||
mtu: 1280
|
||
```
|
||
|
||
没有网络冲突时建议保持默认值。如果修改 `wireguard_port`，必须同步修改 `.env`、云安全组、防火墙和 NAT。
|
||
|
||
### 5. 启动 Server
|
||
|
||
```bash
|
||
cd /opt/remlink/docker
|
||
sudo chmod 600 .env
|
||
sudo mkdir -p data
|
||
sudo docker compose --env-file .env -f compose.release.yaml config --quiet
|
||
sudo docker compose --env-file .env -f compose.release.yaml up --build -d
|
||
sudo docker compose --env-file .env -f compose.release.yaml ps
|
||
sudo docker compose --env-file .env -f compose.release.yaml logs --tail=100 server
|
||
curl --fail http://127.0.0.1:8080/api/v1/server/info
|
||
```
|
||
|
||
### 6. 获取 Join Token
|
||
|
||
```bash
|
||
sudo docker compose --env-file .env -f compose.release.yaml exec server \
|
||
remlink-server -config /etc/remlink/server.yaml -print-join-token
|
||
```
|
||
|
||
Join Token 用于 Engineer 和 Site 第一次注册。节点全部注册完成后建议轮换：
|
||
|
||
```bash
|
||
sudo docker compose --env-file .env -f compose.release.yaml exec server \
|
||
remlink-server -config /etc/remlink/server.yaml -rotate-join-token
|
||
```
|
||
|
||
浏览器访问受保护的 Server 地址，例如 `http://服务器管理网IP:8080` 或反向代理后的 HTTPS 域名。在左侧令牌框输入 `.env` 中的 `REMLINK_ADMIN_TOKEN` 并点击“应用”。
|
||
|
||
## 部署 Engineer（Windows）
|
||
|
||
将 Engineer ZIP 单独解压到固定目录，例如：
|
||
|
||
```text
|
||
C:\RemLink\Engineer
|
||
```
|
||
|
||
编辑 EXE 同目录的 `engineer.yaml`：
|
||
|
||
```yaml
|
||
server: "https://remlink.example.com"
|
||
node_name: "Engineer-Shanghai-01"
|
||
join_token: "粘贴从 Server 获取的 Join Token"
|
||
```
|
||
|
||
如果没有配置 HTTPS 反向代理，在可信网络中可临时使用：
|
||
|
||
```yaml
|
||
server: "http://服务器IP:8080"
|
||
```
|
||
|
||
以管理员身份运行：
|
||
|
||
```powershell
|
||
Set-Location C:\RemLink\Engineer
|
||
.\RemLinkEngineer.exe
|
||
```
|
||
|
||
首次启动会注册节点，并在当前目录生成受机器级 DPAPI 保护的 `identity.json`。该身份只能在原 Windows 主机上使用，不能复制到另一台电脑。
|
||
|
||
## 部署 Site（Windows）
|
||
|
||
将 Site ZIP 单独解压到另一台现场 Windows 主机，例如：
|
||
|
||
```text
|
||
C:\RemLink\Site
|
||
```
|
||
|
||
编辑 EXE 同目录的 `site.yaml`：
|
||
|
||
```yaml
|
||
server: "https://remlink.example.com"
|
||
node_name: "Qingdao-Site-01"
|
||
join_token: "粘贴从 Server 获取的 Join Token"
|
||
|
||
netstack:
|
||
tcp_flow_limit: 2048
|
||
udp_flow_limit: 4096
|
||
udp_idle_seconds: 60
|
||
```
|
||
|
||
配置含义：
|
||
|
||
- `tcp_flow_limit`：Site 同时处理的 TCP flow 上限。
|
||
- `udp_flow_limit`：Site 同时处理的 UDP flow 上限。
|
||
- `udp_idle_seconds`：UDP flow 空闲回收时间。
|
||
- Site YAML 不配置现场网段；现场 CIDR 由 Engineer 创建会话时动态下发。
|
||
|
||
以管理员身份运行：
|
||
|
||
```powershell
|
||
Set-Location C:\RemLink\Site
|
||
.\RemLinkSite.exe
|
||
```
|
||
|
||
正常状态应包含：
|
||
|
||
```text
|
||
WireGuard=CONNECTED
|
||
Control=CONNECTED
|
||
RemoteSubnet=READY
|
||
SubnetGateway=GVISOR_NETSTACK/READY
|
||
```
|
||
|
||
建立会话前，先在 Site 本机验证目标和路由：
|
||
|
||
```powershell
|
||
Get-NetRoute -AddressFamily IPv4 | Sort-Object DestinationPrefix,RouteMetric
|
||
ping 192.168.17.10
|
||
Test-NetConnection 192.168.17.10 -Port 502
|
||
```
|
||
|
||
目标网段必须是直连网络或具有明确非默认路由。只有默认路由时，RemLink 会拒绝会话。
|
||
|
||
## 基础使用流程
|
||
|
||
1. 启动 Server，确认 `/api/v1/server/info` 正常。
|
||
2. 使用 Join Token 分别启动并注册 Site 和 Engineer。
|
||
3. 在 Server Web“节点”页面确认两个节点均为“在线（ONLINE）”。
|
||
4. 在 Site 本机确认目标 PLC/HMI 的 IP、端口和明确路由可达。
|
||
5. 打开 Engineer，选择需要连接的 Site。
|
||
6. 为该 Site 添加远程网段，例如 `192.168.17.0/24`。
|
||
7. 等待 Engineer 的本地 CIDR 冲突检查通过。
|
||
8. 点击“连接现场”，等待状态进入“活动中（ACTIVE）”。
|
||
9. 在 Engineer 电脑使用原生工具访问现场设备：
|
||
|
||
```powershell
|
||
ping 192.168.17.10
|
||
Test-NetConnection 192.168.17.10 -Port 102
|
||
Test-NetConnection 192.168.17.10 -Port 502
|
||
Test-NetConnection 192.168.17.10 -Port 80
|
||
```
|
||
|
||
10. 使用完成后点击“断开会话”，确认远程路由被删除。
|
||
|
||
Engineer 会按 Site Node ID 保存远程 CIDR。例如：
|
||
|
||
- 现场 A 保存 `192.168.17.0/24`。
|
||
- 现场 B 保存 `192.168.107.0/24`。
|
||
|
||
切换 Site 时只加载对应现场的 CIDR，不需要手工删除其他现场的网段。Site 离线后，当前会话会自动关闭。
|
||
|
||
## 三端运行文件位置
|
||
|
||
### Engineer
|
||
|
||
```text
|
||
Engineer目录/
|
||
├─ RemLinkEngineer.exe
|
||
├─ engineer.yaml
|
||
├─ identity.json
|
||
├─ site-profiles.json
|
||
├─ wintun.dll
|
||
└─ logs/engineer.jsonl
|
||
```
|
||
|
||
### Site
|
||
|
||
```text
|
||
Site目录/
|
||
├─ RemLinkSite.exe
|
||
├─ site.yaml
|
||
├─ identity.json
|
||
├─ wintun.dll
|
||
└─ logs/site.jsonl
|
||
```
|
||
|
||
### Docker Server
|
||
|
||
```text
|
||
/opt/remlink/docker/
|
||
├─ .env
|
||
├─ server.yaml
|
||
├─ compose.release.yaml
|
||
└─ data/
|
||
├─ remlink.db
|
||
├─ logs/server.jsonl
|
||
└─ WireGuard及Server运行数据
|
||
```
|
||
|
||
不要把 Engineer 和 Site 放在同一个目录，也不要互相复制 `identity.json`。升级 Windows 程序时保留本端 YAML、身份、日志和已校验的 `wintun.dll`。
|
||
|
||
## 常见问题
|
||
|
||
| 现象 | 原因或处理方法 |
|
||
|---|---|
|
||
| Server 页面无法打开 | 检查 `REMLINK_HTTP_BIND`、Docker 端口映射、防火墙和反向代理 |
|
||
| 页面提示需要 Bearer Admin Token | 输入 `.env` 中的 `REMLINK_ADMIN_TOKEN` |
|
||
| `JOIN_TOKEN_INVALID` | Join Token 已轮换或填写错误，重新从 Server 安全获取 |
|
||
| `SITE_NO_ROUTE` / `DEFAULT_ONLY` | Site 没有目标网段的直连或明确静态路由 |
|
||
| `CIDR_LOCAL_CONFLICT` | Engineer 本地已有覆盖远程 CIDR 的网卡或路由 |
|
||
| `OVERLAY_LOCAL_CONFLICT` | `10.88.0.0/16` 与某台 Windows 主机本地网络冲突 |
|
||
| DPAPI `Key not valid for use in specified state` | `identity.json` 来自其他机器/账户状态或已损坏，应隔离旧身份并重新注册 |
|
||
| 容器预检提示 WireGuard 或 `CAP_NET_ADMIN` 不可用 | 检查宿主机 WireGuard、`/dev/net/tun`、Compose 的 `NET_ADMIN` 和 IPv4 forwarding |
|
||
| 中国网络构建停在 `apt-get` | 使用 `.env.china.example`，并检查 Docker DNS、IPv4 和镜像连接 |
|
||
|
||
更完整的故障排查、备份、升级和 HTTPS 配置见部署文档。
|
||
|
||
## 安全注意事项
|
||
|
||
- Join Token 和 Admin Token 都不得提交到 Git、截图或公开日志。
|
||
- Engineer/Site YAML 中只允许明文保存首次注册所需的 Join Token；Node Token 和 WireGuard 私钥由程序及 DPAPI 管理。
|
||
- `.env`、`identity.json`、`site-profiles.json`、数据库、日志和私钥均已加入 `.gitignore`。
|
||
- 不要对 Server 容器启用 `privileged`；当前 Compose 只授予 `NET_ADMIN` 并映射 `/dev/net/tun`。
|
||
- 不要把 `7001/tcp` 和 `6200/udp` 映射到公网。
|
||
- 公网 Bootstrap/Admin 必须使用外部 HTTPS 反向代理保护。
|
||
- ZIP 和 EXE 应放到 GitHub Release 或其他发布渠道，不应直接提交到源码历史。
|
||
|
||
提交前执行：
|
||
|
||
```powershell
|
||
./scripts/maintenance/Test-RepositoryHygiene.ps1
|
||
git status --short
|
||
git diff --check
|
||
```
|
||
|
||
## 文档入口
|
||
|
||
- [完整三端部署与使用指南](docs/deployment-and-usage.md)
|
||
- [当前实现状态](docs/implementation-status.md)
|
||
- [T01–T18 物理验收手册](docs/validation/T01-T18-runbook.md)
|
||
- [需求与证据矩阵](docs/validation/requirements-evidence.md)
|
||
- [自动化测试覆盖说明](docs/validation/automated-coverage.md)
|
||
- [Phase 任务清单](specs/tasks.md)
|
||
- [开发与验收检查表](specs/checklist.md)
|
||
|
||
## 当前验证状态
|
||
|
||
Phase 0–10 的生产代码、前端、自动化测试、发布打包和 Docker 基线均已实现。自动化覆盖 Bootstrap、IPAM、数据库、Control 重连、Session 状态机、数据包验证、gVisor TCP/UDP/ICMP 往返、网络迁移、重复现场 CIDR 隔离及发布包校验。
|
||
|
||
Gate A–D 和 T01–T18 的正式结果必须在符合拓扑要求的 Linux/Windows 实机环境中按验收手册采集证据。单元测试、浏览器测试和一次人工联通不能替代完整物理验收记录。
|