VoCat/docs/README.zh-TW.md

VoCat

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 Calling	IKEv2/ePDG 隧道建立、EAP-AKA 驗證、IMS 註冊、IMS 簡訊、重新連線控制、狀態診斷以及依裝置路由。
eSIM 與 eUICC	eUICC 探索、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。

安裝程式會:

• 偵測 amd64、386、arm64、aarch64 或 armv7 架構;
• 下載對應的 GitHub Release 二進位檔;
• 對照 SHA256SUMS 進行校驗;
• 將 Vocat 安裝到 /opt/vocat;
• 建立具有 Vocat 所需硬體與網路存取權限的強化版 systemd 服務;
• 將執行時配置存放在 /etc/vocat/env;
• 首次安裝時產生隨機初始管理員密碼。

安裝完成後開啟:

http://<伺服器位址>:7575

手動二進位安裝

從 GitHub Releases 下載對應的二進位檔與 SHA256SUMS:

平台	發佈檔案
Linux x86-64	vocat-linux-amd64
Linux x86 32 位元	vocat-linux-386
Linux ARM64	vocat-linux-arm64
Linux AArch64	vocat-linux-aarch64
Linux ARMv7	vocat-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
sudo env \
  VOCAT_DATABASE_PATH=/opt/vocat/data/vocat.db \
  VOCAT_ADMIN_PASSWORD=change-this-password \
  /opt/vocat/bin/vocat serve

該手動指令會在前台執行 Vocat。請使用 vocat serve 以直接啟動伺服器；在 TTY 下以 root 執行無參數的 vocat 會進入互動式管理選單。如需託管的 systemd 服務與自動重新啟動,請使用一鍵安裝腳本。

Docker

如果 Linux 主機需要探索每一個接入的受支援 Quectel 模組,並持續感知 USB 熱插拔事件,請以硬體存取模式執行 Vocat:

docker pull ghcr.io/mengmengcode/vocat:latest

docker run -d \
  --name vocat \
  --restart unless-stopped \
  --network host \
  --privileged \
  --user 0:0 \
  -e VOCAT_ADMIN_PASSWORD=change-this-password \
  -v vocat-data:/opt/vocat/data \
  -v /dev:/dev \
  -v /sys:/sys:ro \
  ghcr.io/mengmengcode/vocat:latest

容器啟動後開啟 http://<伺服器位址>:7575。主機網路是必需的,這樣 QMI 網路介面才能對 Vocat 可見;而特權裝置存取是序列埠、QMI 控制節點、TUN 介面、網路配置以及容器啟動後新增裝置所必需的。/dev 掛載使新的 ttyUSB*、ttyACM* 和 cdc-wdm* 節點無需重建容器即可見。

該模式有意賦予 Vocat 對主機裝置與網路堆疊的廣泛存取權限,僅在受信任的 Linux 主機上使用。自動探索目前僅識別受支援的 Quectel USB 模組(USB 廠商 ID 2c7c),不識別任意品牌的模組。僅用 --device 映射單一節點(例如 /dev/ttyUSB2 與 /dev/cdc-wdm0)會將容器限定在這些固定節點上,無法提供完整的多裝置或熱插拔探索。

GHCR 映像發佈為 linux/amd64 與 linux/arm64。

配置

Vocat 先從 VOCAT_CONFIG 讀取可選的 JSON 配置檔,再套用 VOCAT_* 環境變數。環境變數優先級更高。

環境變數	預設值	說明
VOCAT_ADDR	0.0.0.0:7575	HTTP 監聽位址。
VOCAT_DATABASE_PATH	./data/vocat.db	SQLite 資料庫路徑。
VOCAT_ADMIN_USERNAME	admin	初始管理員使用者名稱。
VOCAT_ADMIN_PASSWORD	admin	初始管理員密碼。暴露服務前請務必修改。
VOCAT_SESSION_TTL	24h	驗證工作階段有效期。
VOCAT_SECURE_COOKIES	false	在使用 HTTPS 時將工作階段 Cookie 標記為安全。
VOCAT_SHUTDOWN_TIMEOUT	10s	優雅關閉逾時時間。
VOCAT_MAX_REQUEST_BODY_BYTES	1048576	API 請求主體最大位元組數。
VOCAT_REPO	MengMengCode/VoCat	自我更新器使用的受信任 GitHub 倉庫,格式為 owner/name。
GITHUB_TOKEN	空	可選的 GitHub token,用於私有倉庫或更高的 API 限額。

請勿將 Telegram token、SMTP 密碼、Webhook 金鑰、SIM 憑證或其他私密資料存放在倉庫中。請透過應用設定或受保護的環境檔來配置它們。

Telegram 機器人

啟用 Telegram 通知並配置好 Chat ID 與 Admin ID 後,機器人支援:

/status [裝置]
/esim <裝置>
/switch <裝置> <iccid>
/wfc <裝置> <status|on|off|reconnect>
/sms <裝置> <號碼> <內容>

設定檔切換與簡訊提交使用一次性確認按鈕。機器人不暴露 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

致謝

• Nodeseek.com — 專注伺服器的社群
• Linux.do — 富有啟發的技術社群
• iniwex5 — 風格與功能指南

請我喝杯咖啡

網路	位址
USDT-TRON (TRC20)	TQQAbboBoU8h5xX4YCA1rqWJU2WjK3seSg
USDT-BSC (BEP20)	0xdbfcd4a462550d6ff06d09cbd89026c6b145d9c4
USDT-Polygon	0xdbfcd4a462550d6ff06d09cbd89026c6b145d9c4

授權條款

參見 LICENSE。