MengMengCode/VoCat · 上手攻略

  • 仓库：MengMengCode/VoCat
  • 链接：https://github.com/MengMengCode/VoCat
  • 分类：IoT · 蜂窝模组管理
  • 作者：Jay
  • 更新：2026-08-16

是什么

VoCat 是一款面向 Quectel EC20/EC25 系列蜂窝模组（含 EC25、EG25 系列、兼容 EG600 等）的开源 Web 控制面板与工程工具套件。它将模组发现、实时射频状态、AT/USSD 终端、短信、WiFi Calling、eSIM 管理、网络选择、代理路由、通知推送、审计日志和发布自动化全部整合进一个自包含的 Go 服务中，界面由 React + TypeScript 构建，生产前端直接嵌入 Go 二进制，单文件部署。

技术栈：Go 后端 + React/TypeScript 前端（嵌入式）+ SQLite 持久化 + systemd 服务 + Docker 支持。

解决的问题：过去管理 Quectel 蜂窝模组需要分别操作 AT 命令行、QMI 工具、串口调试器，彼此割裂；VoCat 提供统一的 Web UI，涵盖从射频参数（RSRP/RSRQ/SINR）到 eSIM 配置的全套运维能力，并支持 Telegram 机器人远程交互。

解决什么问题

  • 多模组并行管理：同时管理多个 EC20/EC25/EG25 模组，自动发现热插拔，支持友好命名
  • 射频状态透明化：实时查看信号强度、网络模式、频段、信道、运营商等关键指标
  • AT/USSD 交互：浏览器内交互式终端，命令历史保留，无需单独串口软件
  • 短信收发：蜂窝/IMS 双路径，支持长短信、送达报告、Telegram 通知转发
  • WiFi Calling（VoWiFi）：IKEv2/ePDG 隧道建立、IMS 注册与诊断（Linux XFRM/IPsec 环境）
  • eSIM/eUICC 管理： profiles 下载/切换/删除，基于 ICCID 的行为策略
  • 代理路由：SOCKS 路由绑定、国家规则、TCP/UDP 可达性检查

快速安装

一键脚本（推荐，amd64/386/arm64/armv7）

# Root 用户（OpenWrt/Kwrt 等默认无 sudo 的系统）
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | bash

# 普通 Linux 系统（有 sudo）
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | sudo bash

# 仅检查 VoWiFi/XFRM 环境，不安装
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | bash -s -- --check-env

# 安装指定版本（如 0.0.2）
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh -o install.sh
sudo bash install.sh 0.0.2

安装脚本会：检测 CPU 架构 → 下载对应 Release 二进制 → SHA256SUMS 校验 → 安装到 /opt/vocat → 配置 systemd 服务 → 生成随机初始管理员密码。

安装完成后访问：http://<服务器地址>:7575

Docker 部署（需要 --network=host 和 --privileged）

docker pull ghcr.io/mengmengcode/vocat:latest

# 初始化管理员账号
read -rsp "管理员密码: " VOCAT_BOOTSTRAP_PASSWORD; echo
printf '%s\n' "$VOCAT_BOOTSTRAP_PASSWORD" | docker run --rm -i \
  --user 0:0 \
  -v vocat-data:/opt/vocat/data \
  --entrypoint /opt/vocat/bin/vocat \
  ghcr.io/mengmengcode/vocat:latest bootstrap-admin
unset VOCAT_BOOTSTRAP_PASSWORD

# 运行容器
docker run -d \
  --name vocat \
  --restart unless-stopped \
  --network host \
  --privileged \
  --user 0:0 \
  -v vocat-data:/opt/vocat/data \
  -v /dev:/dev \
  -v /sys:/sys:ro \
  ghcr.io/mengmengcode/vocat:latest

⚠️ 容器模式需要 --network=host（让 QMI 网络接口可见）和 --privileged（访问串口/QMI 节点/TUN/网络配置）。仅在受信任的 Linux 主机上使用。

手动二进制安装

# 1. 从 GitHub Releases 下载对应平台的二进制 + SHA256SUMS
# 2. 校验
sha256sum -c SHA256SUMS --ignore-missing

# 3. 安装
sudo install -d -m 0755 /opt/vocat/bin /opt/vocat/data
sudo install -m 0755 vocat-linux-amd64 /opt/vocat/bin/vocat

# 4. 初始化管理员
read -rsp "管理员密码: " VOCAT_BOOTSTRAP_PASSWORD; echo
printf '%s\n' "$VOCAT_BOOTSTRAP_PASSWORD" | sudo /opt/vocat/bin/vocat bootstrap-admin
unset VOCAT_BOOTSTRAP_PASSWORD

# 5. 启动
sudo env \
  VOCAT_DATABASE_PATH=/opt/vocat/data/vocat.db \
  /opt/vocat/bin/vocat serve

核心用法

Web UI

安装后直接浏览器打开 http://<host>:7575，用初始管理员账号登录。界面支持： - 模组概览（多模组卡片、信号实时刷新） - AT 终端（交互式输入、命令历史） - 短信（发送/接收/会话历史） - eSIM profiles（下载/切换/删除） - WiFi Calling（开关/重连/状态诊断） - Telegram 机器人配置

Telegram 机器人命令

启用 Telegram 通知后，机器人支持以下命令（敏感操作需管理员确认）：

/status [设备]     # 查看设备状态
/switch <设备> <iccid>   # 切换 eSIM profile
/wfc <设备> on|off|reconnect  # WiFi Calling 控制
/sms <设备> <号码> <内容>   # 发送短信
/esim <设备>    # 查看 eSIM profiles

自更新

# 检查更新
vocat update --check --repo MengMengCode/VoCat

# 安装最新版
sudo vocat update --repo MengMengCode/VoCat

关键环境变量

环境变量 默认值 说明
VOCAT_ADDR 0.0.0.0:7575 HTTP 监听地址
VOCAT_DATABASE_PATH ./data/vocat.db SQLite 数据库路径
VOCAT_SESSION_TTL 24h 会话有效期
VOCAT_SECURE_COOKIES false HTTPS 时启用安全 Cookie
GITHUB_TOKEN 空 私有仓库或更高 API 限额

USB SIM 读卡器（PC/SC）

如果使用 USB SIM 读卡器，Debian/Ubuntu 上需安装：

apt install pcscd libccid

典型适用场景

  1. 边缘网关/物联网网关管理：在 OpenWrt 或其他嵌入式 Linux 路由器上集中管理多个 4G 模组，无需串口软件
  2. eSIM 远程运维：远程下载/切换/管理 eSIM profiles，适配跨国物联网部署
  3. VoWiFi/IMS 调试：在 Linux XFRM/IPsec 环境下建立 WiFi Calling 隧道并诊断 IMS 状态
  4. 短信网关：通过 Telegram Bot 实时接收模组收到的短信，结合代理路由做国家封锁绕过
  5. 蜂窝信号监测：实时采集 RSRP/RSRQ/SINR，上报到监控系统

坑与注意

  1. VoWiFi 必须 Linux XFRM/IPsec：WiFi Calling 功能依赖内核 XFRM 栈，OpenWrt 需确认固件包含 ip-full、kmod-ipsec*、kmod-crypto-authenc 等组件；若软件源无匹配内核版本的 kmod，需更换固件而非强行安装
  2. Docker 容器安全风险：--privileged + --network=host 赋予容器对主机设备和网络栈的广泛权限，仅在内网/受信任环境使用
  3. 管理员密码必须初始化：空数据库不预置账号，必须运行一次 vocat bootstrap-admin；配置文件和环境变量无法设置管理员凭据
  4. QMI/USB 设备发现：Docker 模式下 --dev/:/dev 挂载使 ttyUSB/ttyACM/cdc-wdm* 节点可见，支持热插拔；若只映射单个设备节点则失去自动发现和多设备支持
  5. Telegram Bot 权限隔离：机器人不暴露 eSIM 下载/删除/重命名命令，通过 Web UI 单独操作
  6. 模组固件依赖：可用功能高度依赖模组固件版本、USB 复合设备配置、运营商设置

与同类对比

方案 技术栈 特色 局限
VoCat Go + React + SQLite 全功能 Web UI、eSIM/Telegram 支持、单二进制 仅支持 Quectel 系列
Quectel QMI 工具 C/命令行 厂商官方、轻量 无 Web UI、功能分散
ModemManager C + DBus NetworkManager 集成 配置复杂、Web UI 缺失
sakis3g Shell + 脚本 轻量老方案 已多年未更新，不支持 eSIM

VoCat 的核心优势是单一可执行文件 + 全功能 Web UI，覆盖 Quectel 模组从发现到运维的全生命周期，对蜂窝物联网场景开箱即用。

一句话推荐结论

如果你在用 Quectel EC20/EC25/EG25 系列模组做物联网或边缘网关，VoCat 是目前最开箱即用的自托管 Web 管理平台——单二进制覆盖射频监控、短信、eSIM、WiFi Calling 和告警推送，值得在网关初始化时一并部署。

原始链接：https://github.com/MengMengCode/VoCat