VirtuaMesh 文档

理解 VirtuaMesh 内部如何工作，对排查问题非常重要。

整体架构图

连接建立流程（5 步看懂）

1. 节点注册

   节点启动后向控制平面注册，提交自己的公钥和验证信息。

2. 获取对等列表

   控制平面返回该节点可以访问的所有对等节点信息（公钥、虚拟 IP、EndPoint）。

3. NAT 穿透尝试

   节点两两配对，尝试通过 STUN 打洞建立 P2P 直连。80% 的家庭网络都能成功。

4. P2P 建立或回退 DERP

   P2P 成功就直接通信，失败则自动通过 DERP 中继加密数据，连接依然可用。

5. 持续保活

   节点通过 gRPC 长连接向控制平面发送心跳（服务端默认建议 30 秒一次，可在客户端 config.yaml 中调整），保持 NAT 映射不过期；超过 30 秒未收到心跳服务端会判定节点离线（HeartbeatTimeout）。

关键设计原则

多传输协议支持

VirtuaMesh 支持多种传输协议，在 UDP 被限速或 NAT 穿透失败时自动降级，确保连接可靠性：

• WireGuard UDP（默认） — 标准 WireGuard UDP 传输，延迟最低，优先使用
• WireGuard over TCP — 在 UDP 被 QoS 限速或对称 NAT 场景下自动启用，通过 TCP 隧道传输 WireGuard 数据包
• WebSocket Transport — 在严格防火墙/代理环境下（仅允许 HTTP(S) 出站）通过 WebSocket 隧道传输
• KCP over UDP — 在丢包率较高的网络环境下提供可靠 UDP 传输
• DERP 中继 — 兜底中继方案，支持自建 DERP 服务器提升中继带宽
• TURN 中继 — 标准 TURN 中继支持

传输协议按优先级自动切换：UDP → TCP → WebSocket → DERP → TURN，无需手动配置。

数据压缩

传输层内置数据包压缩功能（Deflate 算法），在 TUN 层加密前自动压缩大于 256 字节的 IP 包，减少 30-70% 的实际带宽占用。压缩对用户透明，无需配置。

自建 DERP 服务器

用户可在配置文件中添加自建 DERP 服务器，优先于官方 DERP 服务器使用，解决官方 DERP 带宽不足的问题：

"natTraversal": {
    "customDerpServers": [
        {
            "host": "derp.example.com",
            "port": 443,
            "verifyTls": true,
            "regionName": "华东自建",
            "enabled": true,
            "stunPort": 3478
        }
    ]
}

VirtuaMesh 是一个基于 WireGuard 协议的零信任身份网络连接平台。它通过加密的点对点连接在设备之间建立安全的虚拟网格网络（mesh network），所有流量均使用 WireGuard 的 ChaCha20-Poly1305 加密，确保只有同一网络中的设备才能互相通信。

VirtuaMesh 创建的是对等网格网络，而非传统的中心化 VPN 架构。这意味着设备之间尽可能直接通信（P2P），避免了传统 VPN 中中心网关带来的延迟和单点故障问题。当 P2P 连接不可用时，DERP 中继服务器会自动接管，确保连接始终可用。

核心优势

与传统 VPN 的区别

只需简单几步，即可搭建 VirtuaMesh 虚拟网络。整个过程无需深厚的网络知识，几分钟即可完成。

1. 部署控制平面

   使用 Docker Compose 一键启动服务端，包含 API 服务器、MySQL 数据库、Redis 缓存和 DERP 中继。

   cd /path/to/VirtuaMesh/Server
   docker-compose -f docker-compose.prod.yml up -d

2. 安装客户端

   在需要加入网络的设备上安装 VirtuaMesh 客户端。

   # Windows
   iwr -useb https://control.virtuamesh.com/install/windows.ps1 | iex
   
   # macOS
   curl -fsSL https://control.virtuamesh.com/install/macos.sh | sh
   
   # Linux
   curl -fsSL https://control.virtuamesh.com/install/linux.sh | sh

3. 注册节点

   将客户端注册到控制平面，获取节点凭证和虚拟 IP。

   virtuamesh register --server https://your-server.com --network-code <CODE>

4. 启动连接

   启动 WireGuard 隧道，连接到虚拟网络。

   virtuamesh up

5. 验证连接

   检查节点状态和连接情况。

   virtuamesh status
   virtuamesh test-connection --target-ip <peer-virtual-ip>

环境要求

部署步骤

1. 安装 Docker

   curl -fsSL https://get.docker.com | sh
   sudo usermod -aG docker $USER

2. 配置环境变量

   复制 .env.example 为 .env 并填写必要配置：

   MYSQL_ROOT_PASSWORD=your_strong_root_password
   MYSQL_PASSWORD=your_strong_mysql_password
   REDIS_PASSWORD=your_strong_redis_password
   JWT_KEY=YourSuperSecretKeyHereMakeItLongEnough32Chars!
   DOMAIN_NAME=your-domain.com

3. 配置防火墙

   sudo ufw allow 80/tcp
   sudo ufw allow 443/tcp
   sudo ufw allow 3478/udp
   sudo ufw enable

4. 启动服务

   docker-compose -f docker-compose.prod.yml up -d

方式二：systemd + 自包含发布（无 Docker）

适用场景：希望直接以系统服务方式运行，规避容器化开销；或部署环境不支持 Docker。底层依赖 .NET 10 运行时 + SQLite，无需 MySQL/Redis（仍可选用外部 Redis 做分布式缓存）：

1. 准备 Linux 环境

   需要 .NET 10 SDK（仅构建时使用；发布产物为自包含可执行文件，运行时无需安装 .NET）：

   # Ubuntu 22.04 安装 .NET 10 SDK
   wget https://dot.net/v1/dotnet-install.sh -O /tmp/dotnet-install.sh
   chmod +x /tmp/dotnet-install.sh
   sudo /tmp/dotnet-install.sh --channel 10.0 --install-dir /usr/share/dotnet
   sudo ln -s /usr/share/dotnet/dotnet /usr/bin/dotnet
   dotnet --version   # 应输出 10.x.x

2. 构建自包含 Linux 发布包

   git clone https://github.com/virtuamesh/virtuamesh.git
   cd virtuamesh/Server
   dotnet publish src/VirtuaMesh.Api -c Release \
     -r linux-x64 --self-contained true \
     -o ./publish/linux-x64

3. 上传到服务器并解压

   REMOTE_DIR=/data/virtuamesh/server
   ssh user@server "sudo mkdir -p $REMOTE_DIR && sudo chown \$USER:\$USER $REMOTE_DIR"
   scp -r ./publish/linux-x64/* user@server:$REMOTE_DIR/
   ssh user@server "chmod +x $REMOTE_DIR/VirtuaMesh.Api"

4. 生成密钥文件

   项目使用 /etc/virtuamesh/secrets.env 注入 JWT 与 DERP 注册密钥（避免硬编码在配置中）。运行项目自带的密钥生成脚本：

   sudo mkdir -p /etc/virtuamesh
   sudo bash scripts/rotate-secrets.sh    # 生成 VIRTUAMESH_JWT_KEY 等
   sudo chmod 600 /etc/virtuamesh/secrets.env

5. 放置生产配置

   sudo cp scripts/appsettings.Production.example.json $REMOTE_DIR/appsettings.Production.json
   sudo vim $REMOTE_DIR/appsettings.Production.json   # 修改 Database/StunServer/P2P 等节点

6. 初始化 SQLite 数据库

   单节点部署推荐使用 SQLite（零依赖、零运维）。如需 MySQL 集群可参考 docker-compose.prod.yml 切换连接串：

   scp scripts/database-init-sqlite.sql user@server:/tmp/
   ssh user@server "cd $REMOTE_DIR && sqlite3 virtuamesh.db < /tmp/database-init-sqlite.sql"

7. 安装 systemd 单元

   sudo cp scripts/virtuamesh-api.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable virtuamesh-api
   sudo systemctl start virtuamesh-api
   sudo systemctl status virtuamesh-api     # 应显示 active (running)

8. 配置防火墙与日志轮转

   sudo ufw allow 80/tcp
   sudo ufw allow 443/tcp
   sudo ufw allow 53478/udp    # STUN（与 Docker 部署不同：默认端口 53478）
   # journald 默认保留日志；如需长期归档可参考 scripts/ 下 logrotate 配置

方式三：Kubernetes 部署（生产级高可用）

适用场景：多副本高可用、跨节点故障转移、自动伸缩（HPA）。项目自带 Server/k8s/ 完整 YAML 清单（Kustomize 管理），包含 API / DERP / Redis / Ingress / HPA / NetworkPolicy 等：

1. 前置条件
   • Kubernetes 1.24+ 集群（任意发行版：EKS / AKS / GKE / 自建）
   • kubectl + kustomize 已安装
   • 已配置 StorageClass（用于 Redis 持久化）
   • 已部署 Nginx Ingress Controller 或等价组件
2. 推送镜像到镜像仓库

   # 构建并推送
   docker build -t registry.example.com/virtuamesh/api:1.0.0 -f src/VirtuaMesh.Api/Dockerfile .
   docker build -t registry.example.com/virtuamesh/derp:1.0.0 -f src/VirtuaMesh.DerpServer/Dockerfile .
   docker push registry.example.com/virtuamesh/api:1.0.0
   docker push registry.example.com/virtuamesh/derp:1.0.0

3. 配置密钥与域名

   # 1) 编辑 secret.yaml，填入 VIRTUAMESH_JWT_KEY 等密钥（建议用 sealed-secrets 或 external-secrets）
   vim k8s/secret.yaml
   
   # 2) 编辑 ingress.yaml，把 host 改为你的域名
   vim k8s/ingress.yaml
   
   # 3) 如需修改镜像 tag，编辑 kustomization.yaml
   sed -i 's|latest|1.0.0|g' k8s/kustomization.yaml

4. 一键部署

   kubectl apply -k k8s/
   
   # 验证
   kubectl -n virtuamesh get pods
   kubectl -n virtuamesh get svc
   kubectl -n virtuamesh get ingress

5. 查看自动伸缩状态

   kubectl -n virtuamesh get hpa
   # NAME              REFERENCE                 TARGETS   MINPODS  MAXPODS  REPLICAS
   # virtuamesh-api    Deployment/virtuamesh-api  45%/70%   2        10       3

方式四：Windows MSI 安装包（图形化部署）

适用场景：Windows Server 用户、希望零配置安装（包含 EULA 协议 + VC++ 运行库 + Windows 服务自动注册）。项目使用 WiX 3.14 工具链构建：

1. 下载 MSI

   从 GitHub Releases 或 https://control.virtuamesh.com/download/ 下载 virtuamesh-server-windows-x64.msi（自包含 .NET 10 运行时，~80MB）。

2. 双击安装

   按向导填写：

   • 安装路径（默认 C:\Program Files\VirtuaMesh\Server）
   • 数据目录（默认 C:\ProgramData\VirtuaMesh）
   • HTTPS 证书（.pfx 路径 + 密码）
   • 监听端口（默认 58443）
3. 服务自动启动

   MSI 会自动注册 Windows 服务 VirtuaMesh.Api，并配置 3 次失败后重启（sc failure 动作）。

   # 验证服务状态
   sc query VirtuaMesh.Api
   # 查看日志
   Get-EventLog -LogName Application -Source VirtuaMesh.Api -Newest 50

DERP（Detoured Encrypted Relay Protocol）是 VirtuaMesh 的中继服务器协议。当两个节点之间无法建立 P2P 直连时（例如双方都在对称型 NAT 后面），DERP 服务器会作为中继转发加密流量，确保连接始终可用。

端口说明

配置示例

{
  "DerpServer": {
    "Enabled": true,
    "Port": 443,
    "StunPort": 3478,
    "Hostname": "derp.your-region.com",
    "UseHttps": true,
    "MaxConnections": 1000,
    "Region": "ap-east"
  }
}

独立部署 DERP 中继（跨区域降低延迟）

DERP 中继是无状态服务（不需要数据库 / JWT / STUN 配置），可以独立部署到不同地理区域，通过 MultiRegistry 注册到主控制平面。项目自带 virtuamesh-derp.service systemd 单元 + virtuamesh-derp-deploy.sh 部署脚本：

1. 构建并打包

   dotnet publish src/VirtuaMesh.DerpServer -c Release \
     -r linux-x64 --self-contained true \
     -o ./publish/derp-linux-x64
   cd ./publish/derp-linux-x64
   zip -r /tmp/VirtuaMesh-DerpServer-Linux.zip .

2. 上传到目标区域的服务器

   scp /tmp/VirtuaMesh-DerpServer-Linux.zip user@derp-ap-east:/tmp/
   scp scripts/virtuamesh-derp.service user@derp-ap-east:/tmp/
   scp scripts/derp-appsettings.Production.json user@derp-ap-east:/tmp/

3. 在目标服务器上执行部署

   mkdir -p /data/virtuamesh/derp
   cd /data/virtuamesh/derp
   unzip /tmp/VirtuaMesh-DerpServer-Linux.zip
   cp /tmp/derp-appsettings.Production.json ./appsettings.Production.json
   # 修改 ControlPlaneUrl 为你的主控制平面地址
   vim appsettings.Production.json
   chmod +x VirtuaMesh.DerpServer
   
   sudo cp /tmp/virtuamesh-derp.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable --now virtuamesh-derp
   sudo systemctl status virtuamesh-derp

4. 验证注册成功

   部署完成后 DERP 会自动调用主控制平面 POST /api/derp-servers 注册。在管理后台 → DERP 中继列表中应能看到新节点，状态为 Healthy。

$ virtuamesh register --server https://control.virtuamesh.com --network-code ABC123
错误: 配置文件不存在，请先运行 `virtuamesh init`

$ virtuamesh up
错误: 控制平面服务器URL未配置。请先运行注册命令。

安装客户端

基本使用流程

1. 初始化配置

   生成默认配置文件和 WireGuard 密钥对。

   virtuamesh init

2. 注册到控制平面

   使用管理员提供的 Token 注册节点。

   virtuamesh register --server https://your-server.com --network-code <CODE>

3. 启动网络连接

   建立 WireGuard 加密隧道并连接到虚拟网络。

   virtuamesh up

4. 查看连接状态

   查看当前节点信息和对等节点列表。

   virtuamesh status
   virtuamesh peers

MagicDNS 是 VirtuaMesh 内置的 DNS 服务，为虚拟网络中的每台设备自动分配易读的域名，让你无需记忆 IP 地址即可访问任意节点。它参考了 Tailscale MagicDNS 的核心设计，并在此基础上提供了自动域名注册、自定义记录（A/AAAA/CNAME/TXT）、反向解析等能力。

工作原理

当节点加入 VirtuaMesh 网络时，控制平面会自动为该节点注册一条 DNS 记录，将节点的主机名映射到其虚拟 IP 地址。客户端会在本地配置 DNS 搜索域（Search Domain），使得在虚拟网络内的设备可以直接使用短主机名互相访问。

# 完整域名格式
my-server.virtuamesh.com    → 100.64.0.3

# 短名称访问（同网络内）
my-server                   → 100.64.0.3

# 多级子域名
api.production.virtuamesh.com → 100.64.1.10

启用与配置

MagicDNS 默认启用。你可以在客户端配置文件中控制其行为：

network:
  magic_dns:
    enabled: true
    suffix: "virtuamesh.com"

自定义 DNS 记录

除了自动注册的节点记录外，你还可以添加自定义 DNS 记录，为内部服务映射专属域名。支持 A、AAAA、CNAME 和 TXT 记录类型。

# 通过 CLI 为节点注册主机名（节点需先加入网络）
virtuamesh dns register --hostname "grafana" --network-id <guid> --node-id <guid>

# 查看指定网络的所有 DNS 记录
virtuamesh dns list --network-id <guid>

# 注销节点的主机名
virtuamesh dns unregister --network-id <guid> --node-id <guid>

DNS 诊断命令

VirtuaMesh 提供了一组 DNS 诊断命令，帮助你排查 DNS 解析问题：

# 解析指定域名
virtuamesh dns resolve my-server

# 查看 DNS 统计信息
virtuamesh dns stats

# 清空本地 DNS 缓存
virtuamesh dns cache clear

常见使用场景

场景一：微服务内部通信

在微服务架构中，各服务通过 MagicDNS 域名互相访问，无需硬编码 IP 地址。服务迁移或扩容时，DNS 记录自动更新，无需修改配置。

# 服务间调用
curl http://api-gateway:8080/v1/users
curl http://redis-cache:6379
curl http://kafka-broker:9092

场景二：内部服务域名映射

对于 Grafana、Redis、Kafka 等内部服务，可通过 virtuamesh dns register 为节点注册主机名，映射稳定的内部域名，避免硬编码 IP。

# 为节点注册主机名（需指定所属网络 ID 和节点 ID）
virtuamesh dns register --hostname "grafana" --network-id <guid> --node-id <guid>
virtuamesh dns register --hostname "docs" --network-id <guid> --node-id <guid>

故障排查

DNS 解析失败

# 查看 DNS 统计信息
virtuamesh dns stats

# 清空 DNS 缓存
virtuamesh dns cache clear

# 查看详细解析过程
virtuamesh dns resolve --verbose my-server

短名称无法解析

如果短名称（如 my-server）无法解析，请检查：

• MagicDNS 是否已启用：virtuamesh dns stats 查看统计
• DNS 搜索域是否正确配置
• 目标节点是否在线并已注册 DNS 记录

Split DNS 不生效

确认 Split DNS 配置中的域名后缀与实际查询的域名匹配。使用 virtuamesh dns check-availability --hostname <name> 命令可以检查主机名是否可注册。

出口节点可以让网络中某台设备的全部互联网流量，通过另一台指定的节点转发出去。就像给设备套了一层"安全代理"，所有对外访问都从出口节点的网络发出。

工作原理

当你在客户端启用出口节点后，设备的所有非局域网流量都会通过 WireGuard 隧道发送到出口节点，由出口节点代你访问互联网，再把结果原路返回。全程端到端加密，中间节点（包括 DERP 中继）无法解密流量内容。

如何配置出口节点

virtuamesh exit-node enable

virtuamesh exit-node use <节点ID>

常用命令

virtuamesh exit-node enable     # 启用出口节点（允许本机作为出口）
virtuamesh exit-node disable    # 禁用出口节点
virtuamesh exit-node status     # 查看出口节点状态

virtuamesh exit-node use server-01   # 使用指定出口节点
virtuamesh exit-node off             # 不使用出口节点（直连）

应用场景

与普通代理（VPN）的区别

VirtuaMesh 支持两种 WireGuard 实现模式，可根据平台和性能需求灵活选择。

配置示例

network:
  interface_name: "virtuamesh0"
  virtual_ip: ""
  mtu: 1280
  wireguard_mode: "userspace"  # "userspace" 或 "kernel"

安装内核模式依赖

# Ubuntu/Debian
sudo apt-get install wireguard-tools

# CentOS/RHEL
sudo yum install wireguard-tools

节点管理

网络连接

状态查询

网络诊断

工具命令

DNS 命令

服务端端口

客户端端口

客户端配置文件使用 YAML 格式，默认路径为 ~/.virtuamesh/config.yaml。

version: "1.0"

node:
  id: ""
  hostname: ""

control:
  server_url: "https://control.virtuamesh.com"
  node_token: ""

network:
  interface_name: "virtuamesh0"
  virtual_ip: ""
  mtu: 1420
  wireguard_mode: "userspace"
  magic_dns:
    enabled: true
    suffix: "virtuamesh.com"

  exit_node:
    enabled: false
  subnet_router:
    enabled: false

derp:
  servers: []

nat_traversal:
  stun_servers:
    - "stun.l.google.com:19302"
    - "stun.cloudflare.com:3478"
  turn_servers: []

logging:
  level: info
  retained_days: 30
  max_file_size_mb: 10
  max_file_count: 7
  console_output: true

在开始部署前，请逐项检查下面的内容。✓ 一项一项打勾能帮你避免 90% 的常见坑。

选型时容易纠结，这里给出主流组网方案的横向对比，帮你 5 分钟决策。

遇到问题别慌，按下面的流程一步步排查。99% 的问题都能在前 3 步解决。

一键诊断

先跑这个命令，它会自动测试到所有对等节点的连通性：

virtuamesh test-connection --all

输出会显示到每个节点的延迟和丢包率，帮你快速定位问题节点。

决策流程图

常见症状速查

日志查看

# 客户端实时日志
virtuamesh logs follow

# 客户端调试日志（更详细）
virtuamesh logs show --level debug

# 服务端日志（Docker 部署）
docker logs -f virtuamesh-api
docker logs -f virtuamesh-derp

# 服务端日志（systemd 部署）
journalctl -u virtuamesh-api.service -f

# 按关键字过滤客户端日志
virtuamesh logs show --level error

如何查看节点连接状态？

virtuamesh status

该命令会显示当前节点的虚拟 IP、连接状态、在线对等节点数量等信息。

P2P 连接失败怎么办？

VirtuaMesh 会自动回退到 DERP 中继服务器，确保连接始终可用。如果延迟较高，建议在更近的区域部署 DERP 服务器。使用 virtuamesh test-connection --all 可以测试到所有对等节点的连通性。

如何查看日志？

# 服务端日志（Docker 部署）
docker-compose -f docker-compose.prod.yml logs -f api

# 服务端日志（systemd 部署）
journalctl -u virtuamesh-api.service -f

# 服务端日志文件
tail -f /data/virtuamesh/server/logs/virtuamesh-*.log

# 客户端日志
virtuamesh logs follow
virtuamesh logs show --level error

如何更新客户端？

客户端内置自动更新功能，会在启动时检查服务端 /api/v1/updates/latest 接口并自动下载新版本。也可在管理后台 → 节点管理中触发指定节点的更新。

Linux 内核模式需要什么依赖？

使用 kernel WireGuard 模式需要安装 wireguard-tools：

# Ubuntu/Debian
sudo apt-get install wireguard-tools

# CentOS/RHEL
sudo yum install wireguard-tools

如何配置出口节点（Exit Node）？

在客户端配置中启用 exit_node.enabled: true，然后将该节点指定为出口节点，其他节点的所有流量将通过该节点路由。注意：出口节点功能在内核模式下有限制。

如何配置子网路由（Subnet Router）？

在客户端配置中启用 subnet_router.enabled: true，可以将本地子网暴露给 VirtuaMesh 网络，让其他节点可以访问本地子网中的设备。

MagicDNS 短名称无法解析怎么办？

首先使用 virtuamesh dns stats 查看 DNS 统计信息，然后使用 virtuamesh dns resolve --verbose <name> 查看详细解析过程。常见原因包括：MagicDNS 未启用、目标节点不在线、DNS 缓存过期未刷新（使用 virtuamesh dns cache clear 清空缓存）。

如何为内部服务配置自定义域名？

使用 virtuamesh dns register 命令为节点注册主机名。例如：virtuamesh dns register --hostname "grafana" --network-id <guid> --node-id <guid>。注册后即可通过 grafana.virtuamesh.com 访问该节点。

看到这一节说明你的网络已经跑起来了。下面是一份新手/开发者都能用的后续路线，按"从浅到深"排序，每一步都告诉你具体能解决什么问题。

点击下方任意一个路线标题展开内容。打开/关闭状态会自动记忆，下次访问会保持你的选择。

🛠 日常维护清单（建议每月做一次）

🌍 想要更多？