Vonode
简

节点软件 · 分步指南

从一张空桌子到配对好的节点

买什么、如何准备一台小型 Linux 电脑、安装节点软件、在 Vonode App 中扫描配对二维码，以及在免费方案和订阅之间选择。已经有模组和 Linux 电脑的读者，可以直接看安装页上的简要版本。

节点没有网页界面。装好一次、与 App 配对之后，一切都在 App 里管理。未订阅时，节点以免费方案运行：App 显示你选定的一个号码经蜂窝网络收到的短信。其他所有功能（电话、Wi-Fi 通话、发短信、通知、eSIM 配置文件、代理、自动任务、更多号码）都需要在 App 内购买的有效 Vonode 订阅。一份订阅解锁一个节点。

准备硬件

蜂窝模组

Vonode 通过 USB 串口（AT）和 QMI 接口驱动基于高通平台的 Quectel 模组。哪些模组测试过，列在硬件页面上。简单来说：内置 Quectel EG25-G 的 DJI Cellular 模块，已在一台装有 Ubuntu 22.04 的 amd64 电脑上测试；同系列的其他 Quectel 模组（单独的 EG25-G、EC25、EC20、EC21、EM05/EM06、RM500Q）有代码支持，但尚未测试。

在测试过的模组上，可以经 Wi-Fi 通话打电话。它不支持蜂窝网络通话，其他模组上的蜂窝通话也尚未确认。

常见形态，从最简单到最灵活：

  • 内置模组的 USB 上网卡（塑料外壳里装着模组，一个 SIM 卡槽，两根小天线），插上即用。请确认商品说明写明会提供串口和 QMI 接口（“for Linux”“AT 命令”“QMI”）；只提供网卡功能的上网卡（HiLink、仅 RNDIS 或仅 ECM 固件）不受支持。
  • 装在 USB 转接板上的 Mini PCIe 模组。Mini PCIe 转 USB 转接板，带 SIM 卡槽和两根天线转接线（SMA 或 IPEX）。一台主机接多个模组时通常用这种方式。
  • 装在 M.2 转 USB 转接板上的 M.2 模组，适用于 5G 的 RM500Q。
  • DJI Cellular 模块。需要先切换一次 USB 识别，Linux 才能识别它；步骤见硬件页面。

两根天线（主天线和分集天线）都要接上，并把主机放在手机有信号的地方：靠近窗户，而不是放在柜子里。即使使用 Wi-Fi 通话，模组也至少要看到一次蜂窝网络才能完成注册。

示意图：一个 Quectel EG25-G Mini PCIe 模组插在 USB 转接板上：左侧是 USB-A 插头，模组插在 Mini PCIe 插槽里并用两颗螺丝固定，一张 SIM 卡半插在转接板的卡槽中，两根 U.FL 转接线从模组连到标有 MAIN 和 DIV 的两根 SMA 天线
示意图（不是照片）：装在 USB 转接板上的 Mini PCIe 模组。两根转接线分别连到主天线和分集天线；SIM 卡插在转接板的卡槽里。实际转接板的布局各不相同，但要找的就是这些部件。

主机

  • 任意一台 64 位 x86（amd64）Linux 电脑。Intel N100 迷你主机（无风扇、8 GB 内存、一块小 SSD）很合适：USB 口够用、功耗低、安静。二手瘦客户机或 NUC 也一样可以。节点本身有 2 GB 内存和 4 GB 磁盘就足够。
  • Debian 12、Ubuntu 22.04 及以上，或 Fedora。树莓派等 ARM 开发板计划在 1.3.1 支持；OpenWrt 路由器、macOS 或 Windows 上的 Docker Desktop，以及没有 USB 直通的虚拟机不受支持。
  • 连接多个模组时，请使用带供电的 USB 集线器。模组在发射峰值时电流可达 2 A；两个模组接在主板无外接供电的 USB 口上，经常会随机重启或出现“模组消失”的问题。
  • 建议用有线网络连接到路由器。

SIM 卡、eSIM 与网络

  • 一张 Nano SIM 卡，并配上适合卡槽的卡托（Mini PCIe 转接板通常使用标准卡或 Micro 卡）。请先在手机上关闭 SIM 卡的 PIN 码，否则节点无法使用这张卡。
  • 模组没有内置 eSIM。要使用 eSIM 配置文件，请在卡槽中插一张可插拔 eUICC 卡（俗称“eSIM 卡”“实体 eSIM”）；之后可以在 Vonode App 中下载、切换和删除其中的配置文件（订阅功能）。
  • Wi-Fi 通话（VoWiFi）需要运营商在你的套餐中开通，和手机上一样。
  • 手机必须能通过一个 TCP 端口（默认 2222）访问到节点：在路由器上做端口转发，或在手机和主机之间使用 WireGuard、Tailscale 等 VPN。如果处在运营商级 NAT 之后（没有公网 IPv4），请使用 VPN。

准备主机

安装 Linux 发行版，连上网络，并用可以使用 sudo 的用户登录。然后更新系统，并停用会抢占模组串口的 ModemManager：

$ sudo apt update && sudo apt full-upgrade -y
$ sudo systemctl disable --now ModemManager

插上模组，确认 Linux 已识别：

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

每个模组应显示一行 Quectel 信息、四个 ttyUSB 端口和一个 cdc-wdm 端口。如果不是，请看故障排查。

下载节点安装包

每个版本都以 vonode_<version>_linux_amd64_commercial.tar.gz 的形式发布在 Vonode 节点发布页上，附带 SHA-256 校验值、软件物料清单，以及其中 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

安装节点（systemd 安装包）

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

在安装包的顶层目录运行安装程序：

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

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

首次启动时，节点会生成一个随机的管理员密码，配置中只保存它的哈希值。明文在 /opt/vonode/config/initial-admin-password 中，只有 root 可读。你很少会用到它。

显示配对二维码，并填写手机访问节点时使用的地址：做端口转发时填 DDNS 域名或公网 IP，否则填主机的 VPN 地址或局域网地址。如果转发的是其他端口，请加上 -port <端口>。

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

终端会以方块图形显示二维码，5 分钟内有效，只能使用一次；需要新的二维码时再运行一次这条命令。

终端里以黑白方块显示的配对二维码，下方写着在 Vonode App 中扫描上方二维码进行配对、有效期至五分钟后的某个时间且只能使用一次，以及后续步骤（截自 Docker 安装脚本；systemd 的 pair 命令显示的是同样的二维码）
终端里的配对二维码。其中的二维码、地址和时间都是示例。

在主机防火墙上放行 TCP 2222 端口；如果手机要从外网连接，还需在路由器上做端口转发：

$ sudo ufw allow 2222/tcp

配对 App

从 App Store 安装 Vonode（免费下载）并打开。在“连接你的节点”页面点按扫描框，把摄像头对准终端上的二维码。App 会通过 SSH 连接节点，固定节点的主机密钥，并在首页显示这个节点。

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

Vonode App 的首次连接页面“连接你的节点”：二维码扫描框、手动登录入口和 App 审核码输入框配对后的 Vonode App 首页：节点卡片显示名称和状态，号码显示各自的通话方式，底部是标签栏（审核演示用的合成数据）
左：扫码页面。右：刚配对完成的首页，已列出节点。App 和节点必须能通过二维码中的地址互相访问；如果 App 提示连接错误，先检查端口转发或 VPN，再生成一个新的二维码。

免费号码或订阅

免费方案。打开“号码”标签页，选择一个你想查看短信的号码。这个选择对该节点永久有效，从备份恢复也会保留。之后“短信”标签页会显示这个号码收到的短信，你可以阅读和删除。

免费方案下 Vonode App 的“号码”标签页：“免费方案”标记和“选择你的免费号码”卡片，说明 App 可以显示一个号码收到的短信，且选定后不能更换；下面是这个节点上的号码、“添加模组”和“解锁全部功能”（测试用合成数据）Vonode App 的“短信”标签页：短信会话列表，显示发件人、预览和时间（审核演示用的合成数据）
左：“号码”标签页中的免费号码选择。右：“短信”标签页。

订阅。打开“更多”，点“查看方案”（或“更多 > 订阅”）并订阅。由 Apple 收费；App 把签名的交易记录交给你的节点，节点几秒内解锁并重启进入完整模式。之后用“添加模组”加入你的模组，为每张 SIM 卡开启 Wi-Fi 通话，并按需设置电话、eSIM、通知和自动任务。

免费方案下 Vonode App 的“更多”标签页：节点卡片，以及一张说明卡片：免费方案只显示免费号码的短信，电话、发送、自动任务、代理和通知需要订阅，并带“查看方案”按钮（测试用合成数据）
免费方案下的“更多”标签页。“查看方案”会打开订阅页面，Apple 在那里显示你所在地区的方案时长和价格。之后要配对第二台手机，请在 App 中使用“换绑到新手机”，它会显示一个一次性二维码。

日常运维

使用 systemd 安装包时，节点以 vonode 和 vonode-gateway 两个服务运行。

查看状态和日志

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

重启

$ sudo systemctl restart vonode

重启或停止最多需要两分钟：节点会先注销 Wi-Fi 通话并关闭隧道。

忘记管理员密码

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

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

  • 备份：在 App 的“更多 > 备份记录”中操作。备份包含短信、通话记录和订阅绑定，请妥善保管。
  • 手机丢失时，可以在 App 的“已配对的手机”列表中移除它。
  • 订阅到期：如果订阅到期未续订，节点会继续工作 72 小时，让 App 有时间送达续订；请打开 App 续订。之后，或退款后立即，节点回到免费方案，只显示所选号码的短信。

迁移到新硬件

在 App 中为旧节点创建并下载备份，安装并配对新节点，然后导入备份、恢复并重启。备份包含节点的订阅绑定，所以新节点无需重新购买即可解锁，并保留免费方案已选定的号码。请妥善保管备份：其中包含短信、通话记录和绑定信息。不要让旧节点继续用同一份数据运行。

故障排查

“ModemManager is running”

它会先于 Vonode 占用串口。停用它，然后重启节点：

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

如果 lsusb 里没有 Quectel（2c7c）设备，请换一根线或换一个接口，使用带供电的集线器，并查看内核日志中的 USB 供电错误（“over-current”“device not accepting address”）。如果 lsusb 能看到模组但没有 /dev/ttyUSB*，请加载驱动，然后重新插拔模组。有些转接板出厂时让模组处于没有 USB 串口的模式，请按转接板厂商的说明开启；DJI Cellular 模块请看硬件页面。

$ sudo dmesg | tail -n 30
$ sudo modprobe -a option qmi_wwan
App 连不上节点

在你的网络之外的设备上测试端口。没有响应，说明路由器转发或防火墙设置有误，或者宽带运营商使用了运营商级 NAT（没有公网 IPv4）。这时请在手机和主机之间建立 VPN（Tailscale、WireGuard），用主机的 VPN 地址配对，或使用节点文档中介绍的中继选项。

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

配对码 5 分钟内有效，只能使用一次；用安装节点一节中的 pair 命令生成新的配对码。

Wi-Fi 通话注册不上

SIM 卡的套餐需要开通 Wi-Fi 通话，模组至少要用这张 SIM 卡在蜂窝网络上注册过一次，主机还需要能通过 IPv6 或 IPv4 访问运营商的 ePDG。App 的诊断页面会显示当前所处的阶段；它可以导出的支持包，就是要发给支持的材料。

短信时间不对

节点使用主机的时区。请用 timedatectl 设置（使用 Docker 时，给安装脚本传入 --tz Europe/London 这样的 IANA 时区名）。

Docker Compose（即将推出）

即将推出。商用 Docker 镜像尚未发布，所以本版本还不能使用这种方式，请使用上面的 systemd 安装包。下面的步骤说明 Docker 方式推出后的用法。

在镜像发布之前，setup.sh 会停下并要求指定镜像：如果某个版本的发布说明提供了 --image vonode/vonode@sha256:<digest>，请传入它；否则请使用 systemd 安装包（在安装包顶层目录、即 docker/ 的上一级运行 sudo ./install.sh），这是本版本支持的安装方式。

安装 Docker Engine 和 Compose

Docker 官方的便捷脚本可在 Debian、Ubuntu 和 Fedora 上安装 Docker Engine 和 Compose 插件。最后一条命令必须输出 Compose v2 的版本号。

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

运行安装脚本

在安装包的 docker/ 目录下运行。--host 是手机访问节点时使用的域名或 IP；不填时，脚本会建议使用主机的局域网地址，在同一 Wi-Fi 下首次配对时这样就可以。

$ cd vonode_<version>_linux_amd64_commercial/docker
$ sudo ./setup.sh --host node.example.com --image vonode/vonode@sha256:<digest>

脚本会检查主机（Linux、amd64、root、Docker、Compose、ModemManager），列出找到的模组及其设备节点，在脚本旁边创建 config/、data/ 和 logs/，写入 .env 和 docker-compose.override.yml，拉取镜像，启动两个容器（核心 vonode，以及供 App 连接的 SSH 网关 vonode-gateway），并等待两者都报告 healthy，首次启动大约需要半分钟。默认把整个 /dev 绑定进核心容器，这样重新枚举或热插拔的模组仍能使用；--devices 只映射当前存在的设备节点。可变的镜像标签会被拒绝，除非加上 --allow-tag。最后，脚本会显示初始管理员密码的位置（config/initial-admin-password，只有 root 可读）和配对二维码。

sudo ./setup.sh --host node.example.com 的终端输出：检测到两个 Quectel 2c7c:0125 模组及其 ttyUSB、cdc-wdm 和 wwan 设备节点，部署摘要（镜像 digest、SSH 端口 2222、时区、本机回环管理端口、整个 /dev 绑定进核心），拉取镜像，Docker Compose 创建并启动 vonode 和 vonode-gateway 容器，Both containers are healthy 一行，以及初始管理员密码的位置
真实的 setup.sh 输出；与主机相关的值已替换为示例。

传入 --port <n> 可以使用其他 SSH 端口；路由器转发的外部端口不同时，再传入 --public-port <n>。随时生成新的配对码（在同一目录下）：

$ sudo docker compose exec vonode /app/vonode pair -c /app/config/config.yaml -host node.example.com -port 2222

Docker 方式的日常运维

以下命令都在安装包的 docker/ 目录下运行。

操作命令
查看状态（两个服务都应为 healthy）sudo docker compose ps
查看日志sudo docker compose logs -f vonode
生成新的配对码sudo docker compose exec vonode /app/vonode pair -c /app/config/config.yaml -host <address> -port 2222
新增或移动了模组（重新检测模组，其余保持不变）sudo ./setup.sh
重启（最多两分钟）sudo docker compose restart vonode
停止并保留数据sudo ./setup.sh --uninstall
全部删除sudo ./setup.sh --uninstall --purge
忘记管理员密码（所有手机需要重新配对）sudo docker compose stop vonode, sudo docker compose run --rm --no-deps vonode reset-password -c /app/config/config.yaml, sudo docker compose start vonode
升级：把新的镜像引用写入 .env（或传入 --image），再运行脚本vonode/vonode@sha256:<digest> → .env / --image, sudo ./setup.sh

不要运行 docker compose down -v：vonode_gateway-private 卷保存着已配对手机所固定的 SSH 主机密钥。setup.sh --uninstall 会保留它。

  • 127.0.0.1:7575 端口已被占用：另一个程序占用了节点的本机配对页端口。运行 sudo ./setup.sh --admin-port 17575（任意空闲端口），脚本会同时把端口写入配置和 Compose 环境。
  • 容器不是 healthy：用 sudo docker compose logs vonode 查看原因。核心在内部套接字创建后即为 healthy；vonode-gateway 在能访问该套接字并监听 2222 端口后为 healthy。最常见的原因是 2222 端口冲突（ss -ltn | grep 2222），请用 --port 换一个端口。
  • 模组重置后端口变了：模组重置后会重新枚举，ttyUSB 编号可能改变。默认绑定整个 /dev 时，它们会自动出现；如果你用了 --devices，请再运行一次 sudo ./setup.sh。

节点软件是 VONODE LLC 的专有软件。第三方组件及其许可证列在安装包的 THIRD_PARTY_NOTICES.txt 和 SBOM 中。Vonode 不是紧急通信服务：请只在你有权使用的 SIM 卡、号码和网络上使用，并遵守运营商的条款。