README.zh-CN.md

September 5, 2026 · View on GitHub

Vocat

VoCat

Go React TypeScript Vite Tailwind CSS SQLite

Linux Docker WiFi Calling eSIM Telegram GitHub Actions

English | العربية | 简体中文 | 繁體中文 | Français | Русский | Español | 日本語

Vocat 是一款面向 Quectel EC20/EC25 系列蜂窝模组的开源 Web 控制面板与工程工具套件。它在一个自包含的服务中整合了模组发现、实时射频状态、AT 与 USSD 终端、短信、WiFi Calling（WiFi 通话）、eSIM 管理、网络选择、代理路由、通知、审计日志以及发布自动化。

后端使用 Go 编写，界面采用 React 与 TypeScript 构建，生产环境前端被嵌入进 Go 二进制中。单个可执行文件即包含完整的 Web 应用，并使用 SQLite 进行持久化存储。

功能

领域Vocat 提供的能力
设备管理自动串口/USB 发现、多模组支持、设备友好名称、概览实时刷新、模组重启、飞行模式以及 USB 网卡模式控制。
射频与网络注册状态、运营商、信号指标、RSRP/RSRQ/SINR、网络模式、频段、信道、运营商扫描以及自动/手动选网。
AT 与 USSD交互式 AT 终端、命令历史、原始模组响应、USSD 发起/继续/取消流程以及清晰的模组错误上报。
短信蜂窝与 IMS 短信直接发送、入站同步、分段短信处理、送达报告、会话历史、未读状态、时间戳以及逐条消息的送达状态。
WiFi CallingIKEv2/ePDG 隧道建立、EAP-AKA 鉴权、IMS 注册、IMS 短信、重连控制、状态诊断以及按设备路由。
eSIM 与 eUICCeUICC 发现、EID 与生产信息、证书元数据、多 eUICC 清单、已安装配置文件列表、启用/禁用/切换操作，以及在卡片支持时进行下载、重命名和删除。
卡策略基于 ICCID 的 WiFi Calling 与飞行模式行为，策略即时应用。
代理路由上游 SOCKS 路由、设备绑定、国家规则、TCP 可达性检查以及面向 WiFi Calling 数据路径的 UDP Associate 检查。
通知通过 Telegram、Bark、邮件、Pushplus 以及签名 Webhook 转发新入站短信，每条短信单独推送。
Telegram 机器人设备状态、已安装配置文件列表与切换、WiFi Calling 控制以及短信发送。敏感操作需要管理员确认。
运维鉴权、CSRF 防护、访问策略、审计事件、实时日志、日志留存、健康检查、响应式布局、深色模式以及中英文应用界面。
分发静态 Linux 二进制、systemd 安装脚本、带 SHA-256 校验的自更新、Docker 镜像、GHCR 发布以及 GitHub Actions 发布构建。

支持的硬件

Vocat 面向基于高通芯片、并暴露兼容 AT、QMI、串口与 USB 网络接口的 Quectel 模组，包括：

  • Quectel EC20
  • Quectel EC25
  • Quectel EG25 系列
  • 兼容的 EG600 及相关模组

可用功能取决于模组固件、USB 复合设备配置、SIM/eSIM 能力、主机驱动、无线网络以及运营商配置。

安装

Linux 一键安装

已是 root（包括默认没有 sudo 的 OpenWrt/Kwrt）：

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 环境，不安装 VoCat：

curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | bash -s -- --check-env

安装指定版本：

curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh -o install.sh
sudo bash install.sh 0.0.2

VoWiFi IMS 必须使用 Linux XFRM/IPsec。OpenWrt/Kwrt 上安装脚本会从当前固件自己的软件源尝试安装严格匹配的 ip-full、kmod-ipsec、kmod-ipsec4/6、kmod-crypto-authenc、AES-CBC 和 SHA1 组件。若软件源没有与当前内核匹配的模块，必须更换包含这些组件的固件，禁止强装其他内核版本的 kmod。

如果内核无法提供 XFRM/IPsec，而你只需要蜂窝短信或数据等非 VoWiFi 功能，可使用 --skip-vowifi-check 安装：

curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh -o install.sh
sudo bash install.sh --skip-vowifi-check

安装程序会：

  • 检测 amd64、386、arm64、aarch64 或 armv7 架构；
  • 下载对应的 GitHub Release 二进制；
  • 对照 SHA256SUMS 进行校验；
  • 将 Vocat 安装到 /opt/vocat；
  • 创建具有 Vocat 所需硬件与网络访问权限的强化版 systemd 服务；
  • 将运行时配置存放在 /etc/vocat/env；
  • 首次安装时生成随机初始管理员密码。

安装完成后打开：

http://<server-address>:7575

手动二进制安装

从 GitHub Releases 下载对应的二进制与 SHA256SUMS：

平台发布文件
Linux x86-64vocat-linux-amd64
Linux x86 32 位vocat-linux-386
Linux ARM64vocat-linux-arm64
Linux AArch64vocat-linux-aarch64
Linux ARMv7vocat-linux-armv7

校验并安装：

sha256sum -c SHA256SUMS --ignore-missing
sudo install -d -m 0755 /opt/vocat/bin /opt/vocat/data
sudo install -m 0755 vocat-linux-amd64 /opt/vocat/bin/vocat
read -rsp "Admin password: " VOCAT_BOOTSTRAP_PASSWORD; echo
printf '%s\n' "$VOCAT_BOOTSTRAP_PASSWORD" | sudo /opt/vocat/bin/vocat bootstrap-admin
unset VOCAT_BOOTSTRAP_PASSWORD
sudo env \
  VOCAT_DATABASE_PATH=/opt/vocat/data/vocat.db \
  /opt/vocat/bin/vocat serve

该手动命令会在前台运行 Vocat。请使用 vocat serve 以直接启动服务器；在 TTY 下以 root 运行无参数的 vocat 会进入交互式管理菜单。如需托管的 systemd 服务与自动重启，请使用一键安装脚本。

Docker

如果 Linux 主机需要发现每一个接入的受支持 Quectel 模组，并持续感知 USB 热插拔事件，请以硬件访问模式运行 Vocat：

docker pull ghcr.io/mengmengcode/vocat:latest

read -rsp "Admin password: " 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

容器启动后打开 http://<server-address>:7575。必须使用主机网络，才能让 QMI 网络接口保持对 Vocat 可见；串口、QMI 控制节点、TUN 接口、网络配置以及容器启动后新增的设备则需要特权设备访问。/dev 绑定挂载使新的 ttyUSB*、ttyACM*、cdc-wdm* 和 MHI wwan* 节点无需重建容器即可见。

该模式有意赋予 Vocat 对主机设备和网络栈的广泛访问权限，请仅在受信任的 Linux 主机上使用。自动发现会识别受支持的 Quectel USB 模组（USB 厂商 ID 2c7c），以及通过 Linux WWAN 子系统暴露的 PCIe/MHI 模组；它不能识别任意模组布局。仅用 --device 映射单个节点，例如 /dev/ttyUSB2、/dev/cdc-wdm0 或 /dev/wwan0qmi0，会将容器限定在这些固定节点上，无法提供完整的多设备或热插拔发现。

GHCR 镜像发布为 linux/amd64 与 linux/arm64。

Tip

NAS / QNAP Container Station 部署说明： 在 QNAP QTS / QuTS hero（Container Station）等 NAS 操作系统上，自定义的非 root 管理员账号和卷隔离机制可能导致 Docker 命名卷（例如 -v vocat-data:/opt/vocat/data）在一次性的 bootstrap-admin 初始化和后台服务容器中解析为不同的隔离路径，从而在 Web 登录时出现“密码错误”。 在 NAS 环境中，强烈建议初始化和运行时均以主机绝对路径的绑定挂载替代命名卷（例如 QNAP 上的 -v /share/Container/vocat/data:/opt/vocat/data），以保证 SQLite 数据库持久化存储的一致性。

USB SIM 读卡器

USB SIM 读卡器使用 Linux PC/SC 服务。一键安装程序会在支持的软件包管理器上自动安装并启动 pcscd 及 CCID 驱动。Debian/Ubuntu 上等效的手动安装命令为 apt install pcscd libccid。如果 USB 已识别 CCID 读卡器，但 PC/SC 不可用，VoCat 会继续在添加设备对话框中显示该读卡器，并报告缺少的服务或驱动，而不是静默隐藏它。

QMI 命令行工具

VoCat 使用 qmicli 验证 QMI 控制通道是否就绪，并使用 qmi-proxy 复用对该通道的访问。分组数据会话由内置 QMI WDS 客户端管理，而非使用 qmi-network 的 CID/PDH 状态文件。一键安装程序会安装并验证相应工具。手动部署时，Debian/Ubuntu 使用 apt install libqmi-utils；Arch Linux 使用 pacman -S libqmi，Alpine 使用 apk add qmi-utils，OpenWrt 使用 opkg install qmi-utils。

vocat doctor --repair-dji-qmi 会在更改任何 USB 驱动绑定或置位 DTR 之前检查 qmicli。如果该工具不可用，命令会停止并给出安装提示，保持设备当前状态不变。

配置

Vocat 先从 VOCAT_CONFIG 读取可选的 JSON 配置文件，再应用 VOCAT_* 环境变量。环境变量优先级更高。

环境变量默认值说明
VOCAT_ADDR0.0.0.0:7575HTTP 监听地址。
VOCAT_DATABASE_PATH./data/vocat.dbSQLite 数据库路径。
VOCAT_SESSION_TTL24h鉴权会话有效期。
VOCAT_SECURE_COOKIESfalse在使用 HTTPS 时将会话 Cookie 标记为安全。
VOCAT_SHUTDOWN_TIMEOUT10s优雅关闭超时时间。
VOCAT_MAX_REQUEST_BODY_BYTES1048576API 请求体最大字节数。
VOCAT_REPOMengMengCode/VoCat自更新器使用的受信任 GitHub 仓库，格式为 owner/name。
GITHUB_TOKEN空可选的 GitHub token，用于私有仓库或更高的 API 限额。

用户提供的 Apple 运营商配置包可通过 vocat carrier import-ipcc 转换为可审查、符合允许列表的运营商配置文件；参见 docs/CARRIER_IPCC_IMPORT.md。

管理员凭据仅存储在 SQLite 中。使用 vocat bootstrap-admin 对空数据库执行一次初始化；环境变量和 JSON 配置不能设置或覆盖管理员用户名或密码。

请勿将 Telegram token、SMTP 密码、Webhook 密钥、SIM 凭据或其他私密数据存放在仓库中。请通过应用设置或受保护的环境文件来配置它们。

Telegram 机器人

启用 Telegram 通知并配置好 Chat ID 与 Admin ID 后，机器人支持：

/status [device]
/esim <device>
/switch <device> <iccid>
/wfc <device> <status|on|off|reconnect>
/sms <device> <number> <message>

配置文件切换与短信提交使用一次性确认按钮。机器人不暴露 eSIM 下载、删除或重命名命令。

更新

检查是否有更新的 GitHub Release：

vocat update --check --repo MengMengCode/VoCat

安装最新发布版：

sudo vocat update --repo MengMengCode/VoCat

更新器会下载与当前 Linux 架构匹配的二进制，使用已发布的 SHA256SUMS 进行校验，原子性地替换可执行文件，并在可用时重启 vocat systemd 服务。

Docker 安装的更新方式：

docker pull ghcr.io/mengmengcode/vocat:latest

拉取新镜像后重建容器。

开发

依赖要求：

  • Go 1.25 或更新版本
  • Node.js 20 或更新版本
  • npm

运行前端开发服务器：

cd web
npm install
npm run dev

构建嵌入的前端并启动后端：

cd web
npm run build
cd ..
go run ./cmd/vocat

运行全部测试：

go test ./...

构建生产二进制：

go build -trimpath -ldflags "-s -w" -o vocat ./cmd/vocat

发布自动化

推送版本标签会触发两个 GitHub Actions 工作流：

  • release-binaries 构建并发布 amd64、386、arm64、aarch64 与 armv7 二进制及 SHA256SUMS。
  • docker 构建并向 GitHub Container Registry 发布多架构镜像。
git tag v0.2.0
git push origin v0.2.0

项目结构

cmd/vocat/                  应用入口与 CLI
internal/device/            模组发现与设备控制
internal/modem/             AT 会话与响应处理
internal/server/            HTTP API、通知与内嵌 Web 服务器
internal/store/             SQLite 持久化
internal/update/            GitHub Release 自更新器
internal/vowifi/            IKE、EAP-AKA、IMS 与 WiFi Calling 运行时
scripts/install.sh          Linux 安装与更新脚本
web/src/                    React 与 TypeScript 前端
.github/workflows/          二进制与 Docker 发布自动化

负责任地使用

蜂窝模组与 eSIM 操作可能影响用户服务、已存储的配置文件、网络注册以及硬件状态。请做好备份，谨慎审视破坏性操作，并仅在您被允许操作所连接的硬件与网络资源的合法环境中使用本软件。

Vocat 不会绕过运营商鉴权、网络策略、硬件安全或 eSIM 信任要求。支持某项操作意味着 Vocat 能够向模组或 eUICC 发起该请求；但设备、配置文件、网络或运营商仍可能拒绝。

贡献

欢迎提交 Issue 与 Pull Request。请保持改动聚焦，在可行处附带测试，避免提交凭据或用户数据，并清晰地说明硬件相关行为。

提交改动前：

go test ./...
cd web && npm run build

致谢

请我喝杯咖啡

网络地址
USDT-TRON (TRC20)TWSAkvzVsFc7KqncDLmUfRxpPQbpV5CgTB
USDT-BSC (BEP20)0xb43031387342ebb1ff536fb9ad6440b9e6377139
USDT-Polygon0xb43031387342ebb1ff536fb9ad6440b9e6377139

许可证

参见 LICENSE。

Star History Chart