NexusGate

September 9, 2026 · View on GitHub

高性能、P2P 优先的内网穿透与 Overlay Network：Rust Super Node / Edge 客户端 + 独立 React 管理控制台。

公网 Client ──► Server Gateway ──► Control CONNECT ──► Edge ──► 内网服务
                     │                    │
                     └──── Data 1:1 绑定 ──┘

特性

Control / Data 分离：控制通道只传信令，业务字节走独立 1:1 Data Connection
严格 1:1 映射：PublicConn ↔ DataConn ↔ LocalConn，不做传统多路复用大 Tunnel
P2P First / Relay 兜底：架构预留 NAT 穿越与路径切换（当前 MVP 已跑通 Relay）
Super Node：Server 同时承担 Control、Data、TCP Gateway、Relay、Management API
管理面：JWT + RBAC、SQLite 持久化、REST + WebSocket 实时状态
独立前端：web/ 单独构建与发布，不与二进制强耦合

架构与技术

组件

目录	组件	说明
`server/`	`p2p-server`	公网 Super Node + API
`client/`	`p2p-edge`	内网 Edge 节点
`web/`	React Admin	管理控制台（Vite + Ant Design）
`shared/`	协议库	framing / control / dataplane / security 等

关键设计

Edge 与 Server 建立长期 Control Session（长度前缀 JSON：HELLO / AUTH / HEARTBEAT / CONNECT …）
公网访问打到 Server Gateway，按 Route 匹配目标 Edge / 本地地址
Server 生成 connection_id + data_token，经 Control 下发 CONNECT
Edge 拨本地服务，并向 Server Data 口发送 DATA {cid} {token}\n
Server 绑定 Public ↔ Data，之后 RAW TCP 双向拷贝（tokio::io::copy）

技术栈

Rust：Tokio、Axum、SQLx(SQLite)、DashMap、Tracing、JWT / bcrypt
前端：React 18、TypeScript、Vite、Ant Design、ECharts、Zustand
部署：ng 一键管理脚本、二进制发布、Docker / Compose、Systemd、Nginx、Kubernetes

默认端口：

端口	用途
`3000`	Management API / WebSocket
`7000`	Control
`7001`	Data
`8080`	TCP Gateway（Route `public_port` 需与之对齐）
`8088`	Compose 中 Web 面板映射口（可选）

默认管理员：admin / admin123

推荐安装（Linux `ng` 管理脚本）

生产环境推荐用简称命令 ng 管理服务端/客户端：支持安装、启停、配置、从 GitHub 更新、完全卸载，并写入 systemd 开机自启。

1. 安装管理命令

curl -fsSL https://raw.githubusercontent.com/clockclock1/nexusgate/main/scripts/install-ng.sh | sudo bash

安装后可随时唤起数字菜单（输入数字选择功能）：

ng                 # 自动 sudo，进入菜单
sudo ng            # 同上

菜单示例：

======== NexusGate 管理菜单 ========
  1) 安装服务端
  2) 安装客户端
  3) 更新服务端
  ...
  0) 退出
请输入数字选择功能:

也可从本地仓库安装：

sudo bash scripts/install-ng.sh

2. 安装并启动服务端（公网机器）

sudo ng install-server

流程：

从 GitHub Release 下载最新 nexusgate-server-linux-amd64|arm64
逐项交互配置（监听地址、端口、管理员账号、JWT、P2P/中继等；回车保留默认）
确认后写入 systemd 并启用开机自启、立即启动

默认值一般为 API 3000 / Control 7000 / Data 7001 / Gateway 8080，管理员 admin / admin123。

2.1 安装管理面板（通常与服务端同机）

sudo ng install-web

流程：

下载 Release 中的 nexusgate-admin-linux-amd64|arm64（内嵌前端的 Rust 小服务）
逐项配置面板端口（默认 8088）与 API 反代地址（默认 127.0.0.1:3000）
启动 nexusgate-web.service：托管页面并反代 /api/、/ws/ 到服务端

浏览器访问：http://<服务器IP>:8088（账号同服务端管理员）。

也可：sudo ng config-web / sudo ng update-web / sudo ng uninstall-web。

本地也可直接运行（需先 cd web && npm ci && npm run build）：

cargo run -p p2p-admin --release -- --config admin/config/admin.toml

3. 安装并启动客户端（内网机器）

sudo ng install-client

同样先下载，再逐项填写 node_id / token / server 与本地服务映射，最后确认自启。

node_id / token 在服务端管理面板「创建节点」后获得（或调 API /api/nodes）。若安装时暂未拿到 token，可稍后：

sudo ng config-client
sudo ng restart client

4. 日常运维

sudo ng                 # 数字菜单（除 0 退出外，操作完回菜单）
sudo ng start all
sudo ng stop server
sudo ng restart client
sudo ng update-server      # 拉 GitHub 最新服务端并重启
sudo ng update-client
sudo ng update-web
sudo ng config-server      # 备用：CLI 改服务端（推荐在管理面板 Settings/Server）
sudo ng config-client      # 逐项改客户端配置
sudo ng config-web         # 逐项改管理面板端口/反代
sudo ng show-config        # 查看当前配置（可加 server|client|web）
sudo ng logs server
sudo ng uninstall-client   # 完全卸载客户端
sudo ng uninstall-server   # 完全卸载服务端（含数据）
sudo ng uninstall-web      # 完全卸载管理面板
sudo ng uninstall-all      # 清空全部组件与数据
sudo ng uninstall-ng       # 仅卸载 ng 管理脚本
sudo ng self-update        # 更新 ng 脚本自身

命令	说明
`install-server` / `install-client` / `install-web`	下载 → 逐项配置 → systemd 开机自启
`start` / `stop` / `restart [server\|client\|web\|all]`	启停控制
`update-server` / `update-client` / `update-web`	从 GitHub Release 更新
`config-server` / `config-client` / `config-web`	CLI 配置（服务端日常请用管理面板）
`show-config [server\|client\|web\|all]`	查看当前配置内容
`uninstall-server` / `uninstall-client` / `uninstall-web`	完全卸载（配置/数据/单元）
`uninstall-all`	删除 `/opt/nexusgate`、systemd、系统用户
`uninstall-ng`	仅卸载管理脚本 `ng`（保留已装组件）
`status` / `logs`	状态与日志
`self-update`	更新管理脚本
`mirror` / `test-mirror`	镜像源设置与探测

落盘位置：

/usr/local/bin/ng
/opt/nexusgate/bin/p2p-server
/opt/nexusgate/bin/p2p-edge
/opt/nexusgate/server/config/server.toml
/opt/nexusgate/client/config/edge.toml
/opt/nexusgate/bin/p2p-admin
/opt/nexusgate/web/config/admin.toml
/opt/nexusgate/data/
/etc/systemd/system/nexusgate-server.service
/etc/systemd/system/nexusgate-edge.service
/etc/systemd/system/nexusgate-web.service

二进制安装/更新依赖 Release 资产名：nexusgate-server-linux-amd64|arm64、nexusgate-edge-linux-*、nexusgate-admin-linux-*。请先在仓库发布 Release（Actions 会自动挂载产物）。

GitHub 镜像源（国内网络）

安装/更新会 官方源优先，失败自动切换镜像重试。也可指定优先镜像：

# 安装 ng 时就走镜像（并写入后续默认）
NG_MIRROR=https://ghproxy.net/ curl -fsSL \
  https://ghproxy.net/https://raw.githubusercontent.com/clockclock1/nexusgate/main/scripts/install-ng.sh \
  | sudo -E bash

# 已安装后设置
sudo ng mirror          # 菜单选择镜像
sudo ng test-mirror     # 探测官方/镜像是否可达

# 临时指定
NG_MIRROR=https://ghproxy.net/ sudo -E ng update-server

内置候选镜像包括：ghproxy.net、mirror.ghproxy.com、ghfast.top、gh.ddlc.top、gitclone.com 等。

快速开始（源码开发）

# 1) Server
cargo run -p p2p-server -- --config server/config/server.toml

# 2) Web
cd web && npm ci && npm run dev
# http://127.0.0.1:5173

# 3) 管理面板创建节点，把 node_id / token 写入 client/config/edge.toml

# 4) Edge
cargo run -p p2p-edge -- --config client/config/edge.toml

创建 Service（本地地址例如 127.0.0.1:8000）与 Route（public_port=8080）后访问：

curl http://127.0.0.1:8080/

API 示例：

TOKEN=$(curl -s -X POST http://127.0.0.1:3000/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin123"}' | jq -r .token)

curl -s -X POST http://127.0.0.1:3000/api/nodes \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"edge-1"}'

使用方式

1. 注册 Edge

启动 Server
登录管理面板或调用 /api/auth/login
创建 Node，保存返回的 node_id 与一次性 token
写入 client/config/edge.toml 并启动 Edge
面板中节点状态变为 online

2. 暴露内网服务

在 Edge 所在机器准备本地服务（HTTP/TCP）
创建 Service：协议 + local_addr
创建 Route：public_port（当前需等于 Server gateway_port，默认 8080）→ Node → Service
公网访问 http://<server-ip>:8080/（或对应 TCP 客户端）

3. 管理面板页面

Dashboard / Server / Nodes / Services / Routes / P2P / Connections / Traffic / Logs / Users / Settings

日常服务端管理请在面板完成（不再依赖改 TOML / ng config-server）：

面板	能力
服务端节点	多 Super Node 注册 + Admin Hub 在线拓扑（server/edge dial 入）
Nodes（客户端节点）	当前服务端下：创建节点、改名/启用禁用、重置 Token、删除
Server（当前服务端）	查看运行状态、编辑并持久化端口/P2P/中继、重启进程
Settings	写入当前服务端 `server.toml`（监听、端口、JWT、P2P/中继）
Users / Services / Routes	账号与穿透业务 CRUD（作用域=当前选中的服务端）

主机级安装/更新/卸载仍用 ng。端口变更保存后需在 Server 页重启；systemd 单元需 Restart=always（ng install-server 已写入）。

Admin Hub（管理面板即 P2P 中枢）

p2p-admin 监听 Hub Control 7100 / Data 7101（admin.toml）
Super Node 配置 hub_host / hub_token / hub_server_id 后主动 dial 进 Hub
Edge 配置 hub_host / hub_token 后 dial 进 Hub，并尝试对所有在线服务端开通管理通道（优先 P2P，失败则 Hub 中转）
面板访问 /api 时：若目标服务端已在 Hub 在线，走 MGMT_FORWARD；否则回退 HTTP api_upstream

一个管理面板可通过顶栏切换多个服务端；每个服务端各自维护多台 Edge；Hub 侧则可看到全部 dial 入的服务端与客户端。

实时数据通过 /ws/dashboard、/ws/connections、/ws/traffic、/ws/logs 推送（带 server= 选定上游）。

其它部署方式

A. `ng` 脚本（推荐，见上文）

curl -fsSL https://raw.githubusercontent.com/clockclock1/nexusgate/main/scripts/install-ng.sh | sudo bash
sudo ng install-server
sudo ng install-client

B. Release 二进制

发布 GitHub Release 后，Actions 会上传多平台产物：

Server / Edge

nexusgate-server-windows-amd64.exe / nexusgate-edge-windows-amd64.exe
nexusgate-server-linux-amd64 / nexusgate-edge-linux-amd64
linux-arm64 / macos-amd64 / macos-arm64 等同理

前端管理面板（独立二进制，内嵌静态资源）

nexusgate-admin-windows-amd64.exe / nexusgate-admin-linux-amd64 等
负责：托管 SPA + 反代 /api、/ws 到可选多个服务端 API
同时作为 Admin Hub：服务端/客户端 P2P 接入（失败中转）
本地管理接口：/admin/api/servers、/admin/api/hub/*

./nexusgate-server-linux-amd64 --config server/config/server.toml
./nexusgate-admin-linux-amd64 --config admin/config/admin.toml
./nexusgate-edge-linux-amd64 --config client/config/edge.toml

本地自行编译：

cd web && npm ci && npm run build && cd ..
cargo build --release --locked -p p2p-server -p p2p-edge -p p2p-admin

C. Docker（GHCR）

镜像：

ghcr.io/clockclock1/nexusgate-server
ghcr.io/clockclock1/nexusgate-edge
ghcr.io/clockclock1/nexusgate-web

docker run --rm -p 3000:3000 -p 7000:7000 -p 7001:7001 -p 8080:8080 \
  -v nexusgate-data:/opt/nexusgate/data \
  ghcr.io/clockclock1/nexusgate-server:latest

源码本地构建（多阶段）：

docker build -t nexusgate-server .

D. Docker Compose

cd deploy/compose
cp .env.example .env
# 发布后可将 NEXUSGATE_VERSION 改为 v0.1.0
docker compose up -d

API / Gateway：宿主机 3000 / 8080
Web：http://127.0.0.1:8088

E. Systemd（手动）

更推荐直接用 ng（见上文「推荐安装」）。若手动部署：

sudo cp deploy/systemd/p2p-server.service /etc/systemd/system/nexusgate-server.service
sudo cp deploy/systemd/p2p-edge.service /etc/systemd/system/nexusgate-edge.service
# 按需修改 ExecStart 路径后：
sudo systemctl enable --now nexusgate-server
sudo systemctl enable --now nexusgate-edge

F. Nginx 反代

参考 deploy/nginx/p2p-network.conf 与 deploy/nginx/web.conf：

/ → 前端静态资源
/api/、/ws/ → Server :3000
Gateway / Control / Data 端口按需对公网放行

G. Kubernetes

kubectl apply -f deploy/kubernetes/namespace.yaml
kubectl apply -f deploy/kubernetes/pvc.yaml
kubectl apply -f deploy/kubernetes/deployment.yaml
kubectl apply -f deploy/kubernetes/service.yaml

默认镜像 ghcr.io/clockclock1/nexusgate-server:latest 与 ghcr.io/clockclock1/nexusgate-web:latest。

CI / CD（GitHub Actions）

参照 Failover-Proxy workflows，在 Publish Release 时触发（与其相同的两套流水线）：

Workflow	作用
`Build Executables`	各平台先 `npm` 构建前端，再编译 Server / Edge / Admin（Admin 内嵌前端），产物挂到 Release
`Docker Image`	Linux amd64/arm64 同样先构建前端再编译，再推送 server / edge / web 镜像到 GHCR

Release 资产示例：

nexusgate-server-linux-amd64 / nexusgate-edge-linux-amd64 / nexusgate-admin-linux-amd64
Windows / macOS / arm64 同理
镜像：ghcr.io/clockclock1/nexusgate-{server,edge,web}

开发

cargo check
cargo test
cargo clippy --workspace --all-targets
cd web && npm run build

更多文档：

License

Apache-2.0