Vonode
简

节点软件

安装 Vonode 节点

节点软件把一台装了蜂窝模组的 64 位 Linux 电脑变成 Vonode App 管理的节点。它没有网页界面：装好、和 App 配对，之后的一切都在 App 里管理。

  1. 准备硬件主机、模组、SIM 卡
  2. 安装systemd 安装包
  3. 配对 App扫描一次性二维码
  4. 免费方案或订阅在 App 中选择

准备硬件

购买硬件前，请先在硬件页面查看完整清单。

主机

  • 64 位 x86（amd64）Linux：Debian 12、Ubuntu 22.04 及以上，或 Fedora
  • root 权限和完整的 iproute2 软件包
  • ARM（arm64）开发板：计划在 1.3.1 提供，本版本不支持
主机要求 →

蜂窝模组

  • 带串口和 QMI 接口、基于高通平台的 Quectel 模组。目前已实测：DJI Cellular 模块（内置 EG25-G）
  • 主天线和分集天线都要接上
  • 连接多个模组时，请使用带供电的 USB 集线器
支持的模组 →

SIM 卡与网络

  • 已关闭 PIN 码的 SIM 卡；如需 eSIM，请使用可插拔 eUICC 卡
  • 手机能访问到 TCP 2222 端口：在路由器上做端口转发，或使用 WireGuard、Tailscale 等 VPN
  • 运营商已在套餐中开通 Wi-Fi 通话
SIM 卡与运营商说明 →

开始前，先停用会抢占模组串口的 ModemManager，并确认 Linux 已识别模组：

$ sudo systemctl disable --now ModemManager
$ lsusb | grep -i -E 'quectel|2c7c|qualcomm|05c6'
$ ls /dev/ttyUSB* /dev/cdc-wdm*

每个模组应显示一行 Quectel 信息、四个 ttyUSB 端口和一个 cdc-wdm 端口。

安装

本版本请使用 systemd 安装包：它把节点安装为两个系统服务，不需要 Docker。Docker Compose 方式即将推出，下面列出的步骤仅供参考，商用镜像尚未发布。两种方式的配对和方案用法完全相同。

本版本推荐的安装方式。systemd 安装包把节点安装为两个系统服务，不需要 Docker。

  1. 下载并校验安装包

    下载对应版本的发布包，并核对它的 SHA-256 校验值。

    $ curl -fLO https://github.com/vonode/vonode-releases/releases/download/<version>/vonode_<version>_linux_amd64_commercial.tar.gz
$ curl -fLO https://github.com/vonode/vonode-releases/releases/download/<version>/vonode_<version>_linux_amd64_commercial.tar.gz.sha256
$ sha256sum -c vonode_<version>_linux_amd64_commercial.tar.gz.sha256
$ tar -xzf vonode_<version>_linux_amd64_commercial.tar.gz

  2. 运行安装程序

    安装程序会把程序放到 /opt/vonode，保留已有的配置和数据库，创建系统用户 vonode-gateway，并启动两个服务：vonode，以及 App 连接的加密 SSH 网关服务 vonode-gateway。

    $ cd vonode_<version>_linux_amd64_commercial
$ sudo ./install.sh

  3. 显示配对二维码

    填写手机访问节点时使用的地址。如果转发的是其他端口，请加上 -port <端口>。

    $ sudo /opt/vonode/vonode pair -c /opt/vonode/config/config.yaml -host node.example.com

商用 Docker 镜像尚未发布。

在镜像发布之前，setup.sh 会停下并要求指定镜像：请传入发布说明中的 --image vonode/vonode@sha256:<digest>，或者改用 （在安装包顶层目录、即 docker/ 的上一级运行 sudo ./install.sh），这是本版本支持的安装方式。

  1. 安装 Docker Engine 和 Compose

    Docker 官方的便捷脚本适用于 Debian、Ubuntu 和 Fedora。最后一条命令必须输出 Compose v2 的版本号。

    $ curl -fsSL https://get.docker.com | sh
$ sudo systemctl enable --now docker
$ docker compose version

  2. 下载并校验安装包

    每个版本都发布在 Vonode 节点发布页 上，附带 SHA-256 校验值、软件物料清单（SBOM），以及其中 GPL 和 LGPL 组件的源代码。

    $ curl -fLO https://github.com/vonode/vonode-releases/releases/download/<version>/vonode_<version>_linux_amd64_commercial.tar.gz
$ curl -fLO https://github.com/vonode/vonode-releases/releases/download/<version>/vonode_<version>_linux_amd64_commercial.tar.gz.sha256
$ sha256sum -c vonode_<version>_linux_amd64_commercial.tar.gz.sha256
$ tar -xzf vonode_<version>_linux_amd64_commercial.tar.gz

  3. 运行安装脚本

    --host 是手机访问节点时使用的域名或 IP 地址。脚本会检查主机、列出找到的模组、启动 vonode 和 vonode-gateway 两个容器，等两者都正常运行后显示配对二维码。

    $ cd vonode_<version>_linux_amd64_commercial/docker
$ sudo ./setup.sh --host node.example.com
    sudo ./setup.sh --host node.example.com 的终端输出：检测到两个 Quectel 2c7c:0125 模组及其设备节点、部署摘要、Docker Compose 启动 vonode 和 vonode-gateway 容器，以及 Both containers are healthy 一行
    再次运行 setup.sh 会保留配置和数据。sudo ./setup.sh --uninstall 停止节点并保留全部数据；加上 --purge 则全部删除。

配对 App

从 App Store 安装 Vonode（免费下载）。在主机防火墙上放行 TCP 2222 端口；如果手机要从外网连接，还需在路由器上做端口转发。配对码 5 分钟内有效，只能使用一次。

Vonode App 在中国大陆以外的 App Store 国家和地区提供；中国大陆的 App Store 目前不提供。

$ sudo ufw allow 2222/tcp
Vonode App 的首次连接页面“连接你的节点”：二维码扫描框、手动登录入口和 App 审核码输入框
扫码打开 Vonode App，在“连接你的节点”页面点按扫描框，把摄像头对准终端上的二维码。
配对后的 Vonode App 首页：节点及其号码和状态（审核演示用的合成数据）
已连接App 通过 SSH 连接节点，固定节点的主机密钥，并列出它的号码。

之后需要新的配对码？再次运行 pair 命令：

$ sudo /opt/vonode/vonode pair -c /opt/vonode/config/config.yaml -host node.example.com

免费方案或订阅

未订阅时，节点以免费方案运行。其他功能都需要在 App 内购买订阅；一份订阅解锁一个节点。

免费方案下 Vonode App 的“号码”标签页：“选择你的免费号码”卡片和节点上的号码（测试用合成数据）
免费方案打开“号码”标签页，选择一个你想查看短信的号码。选定后不能更换。
免费方案下 Vonode App 的“更多”标签页：免费方案卡片和“查看方案”按钮（测试用合成数据）
订阅打开“更多”，点“查看方案”。节点几秒内就会解锁；之后用“添加模组”加入更多模组，并为每张 SIM 卡开启 Wi-Fi 通话。

日常运维

使用 systemd 安装包时，节点以 vonode 和 vonode-gateway 两个服务运行。Docker 方式推出后，对应的命令在安装包的 docker/ 目录下运行。

查看状态和日志

$ systemctl status vonode vonode-gateway
$ journalctl -u vonode -f

两个服务都应显示 active (running)。

重启

$ sudo systemctl restart vonode

忘记管理员密码

$ sudo systemctl stop vonode
$ sudo /opt/vonode/vonode reset-password -c /opt/vonode/config/config.yaml
$ sudo systemctl start vonode

停止服务、重置密码，再启动服务。所有手机都会退出登录，需要重新配对。

Docker（即将推出）

$ sudo docker compose ps
$ sudo docker compose logs -f vonode

Docker 方式下查看状态和日志，在 docker/ 目录下运行。

重启或停止最多需要两分钟：节点会先注销 Wi-Fi 通话并关闭隧道。请保留已配对手机所固定的 SSH 主机密钥：Docker 方式下它保存在 vonode_gateway-private 卷中，所以不要运行 docker compose down -v。

故障排查

ModemManager 正在运行

ModemManager 会先于 Vonode 占用串口。停用它，然后重启节点（使用 Docker 时改为重新运行 sudo ./setup.sh）：

$ sudo systemctl disable --now ModemManager
$ sudo systemctl restart vonode
检测不到模组

如果 lsusb 里没有 Quectel（2c7c）设备，请换一根线或换一个接口，使用带供电的集线器，并用 dmesg 查看 USB 供电错误。如果 lsusb 能看到模组但没有 /dev/ttyUSB*，请加载驱动，然后重新插拔模组：

$ sudo modprobe -a option qmi_wwan
App 连不上节点

在你的网络之外的设备上测试端口。没有响应说明路由器转发或防火墙设置有误，或者宽带运营商使用了运营商级 NAT；这时请在手机和主机之间建立 VPN，并用主机的 VPN 地址配对。

$ nc -vz node.example.com 2222
配对码已过期或已被使用

配对码 5 分钟内有效，只能使用一次。用“配对 App”一节中的 pair 命令生成新的配对码。

需要更详细的说明？

分步指南涵盖硬件选购、setup.sh 的全部选项、迁移到新硬件和更多故障排查。

打开完整指南

节点软件是 VONODE LLC 的专有软件。第三方组件及其许可证列在安装包的 THIRD_PARTY_NOTICES.txt 和 SBOM 中。其中包括 strongSwan（GPL-2.0-or-later）以及静态链接的 glibc 和 GMP（LGPL），对应的源代码随每个版本发布。Vonode 不是紧急通信服务：请只在你有权使用的 SIM 卡、号码和网络上使用。