mirror of
https://github.com/MengMengCode/VoCat.git
synced 2026-08-13 03:13:43 +08:00
Update Readme.md
This commit is contained in:
MengMengCode
@@ -22,7 +22,7 @@
|
||||
<img alt="GitHub Actions" src="https://img.shields.io/badge/GitHub_Actions-Release-2088FF?style=flat-square&logo=githubactions&logoColor=white">
|
||||
</p>
|
||||
|
||||
**English** | [简体中文](docs/README.zh-CN.md)
|
||||
**English** | [العربية](docs/README.ar.md) | [简体中文](docs/README.zh-CN.md) | [Français](docs/README.fr.md) | [Русский](docs/README.ru.md) | [Español](docs/README.es.md)
|
||||
|
||||
Vocat is an open-source web control panel and engineering toolkit for Quectel EC20/EC25-class cellular modems. It combines modem discovery, live radio status, AT and USSD terminals, SMS, WiFi Calling, eSIM management, network selection, proxy routing, notifications, audit logs, and release automation in one self-contained service.
|
||||
|
||||
@@ -46,7 +46,7 @@ The backend is written in Go, the interface is built with React and TypeScript,
|
||||
| Card policy | ICCID-based WiFi Calling and flight-mode behavior with immediate policy application. |
|
||||
| Proxy routing | Upstream SOCKS routing, device bindings, country rules, TCP reachability checks, and UDP Associate checks for WiFi Calling data paths. |
|
||||
| Notifications | New inbound SMS forwarding through Telegram, Bark, email, Pushplus, and signed webhooks. Each SMS is delivered as an individual notification. |
|
||||
| Telegram bot | Device status, installed-profile listing and switching, WiFi Calling controls, SMS sending, timed dialing with automatic hang-up, call status, answer, and hang-up commands. Sensitive actions require administrator confirmation. |
|
||||
| Telegram bot | Device status, installed-profile listing and switching, WiFi Calling controls, and SMS sending. Sensitive actions require administrator confirmation. |
|
||||
| Operations | Authentication, CSRF protection, access policies, audit events, live logs, log retention, health checks, responsive layout, dark mode, and English/Chinese application UI. |
|
||||
| Distribution | Static Linux binaries, systemd installation script, self-update with SHA-256 verification, Docker image, GHCR publishing, and GitHub Actions release builds. |
|
||||
|
||||
@@ -207,13 +207,9 @@ When Telegram notifications are enabled and both Chat ID and Admin ID are config
|
||||
/switch <device> <iccid>
|
||||
/wfc <device> <status|on|off|reconnect>
|
||||
/sms <device> <number> <message>
|
||||
/call <device> <number> <seconds>
|
||||
/calls <device>
|
||||
/answer <device>
|
||||
/hangup <device>
|
||||
```
|
||||
|
||||
Profile switching, SMS submission, and dialing use one-time confirmation buttons. Timed dialing performs the modem call action and automatically hangs up after 1–600 seconds; it does not capture or process call audio. The bot does not expose eSIM download, delete, or rename commands.
|
||||
Profile switching and SMS submission use one-time confirmation buttons. The bot does not expose eSIM download, delete, or rename commands.
|
||||
|
||||
## Updating
|
||||
|
||||
|
||||
@@ -0,0 +1,334 @@
|
||||
<p align="center">
|
||||
<img src="../web/public/favicon.svg" width="96" alt="Vocat">
|
||||
</p>
|
||||
|
||||
<h1 align="center">VoCat</h1>
|
||||
|
||||
<p align="center">
|
||||
<img alt="Go" src="https://img.shields.io/badge/Go-1.25-00ADD8?style=flat-square&logo=go&logoColor=white">
|
||||
<img alt="React" src="https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react&logoColor=111111">
|
||||
<img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.8-3178C6?style=flat-square&logo=typescript&logoColor=white">
|
||||
<img alt="Vite" src="https://img.shields.io/badge/Vite-7-646CFF?style=flat-square&logo=vite&logoColor=white">
|
||||
<img alt="Tailwind CSS" src="https://img.shields.io/badge/Tailwind_CSS-3-06B6D4?style=flat-square&logo=tailwindcss&logoColor=white">
|
||||
<img alt="SQLite" src="https://img.shields.io/badge/SQLite-Embedded-003B57?style=flat-square&logo=sqlite&logoColor=white">
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<img alt="Linux" src="https://img.shields.io/badge/Linux-amd64_%7C_386_%7C_arm64_%7C_aarch64_%7C_armv7-FCC624?style=flat-square&logo=linux&logoColor=111111">
|
||||
<img alt="Docker" src="https://img.shields.io/badge/Docker-Multi--Arch-2496ED?style=flat-square&logo=docker&logoColor=white">
|
||||
<img alt="WiFi Calling" src="https://img.shields.io/badge/WiFi_Calling-IMS_SMS-7B1FA2?style=flat-square">
|
||||
<img alt="eSIM" src="https://img.shields.io/badge/eSIM-LPA_%2F_eUICC-009688?style=flat-square">
|
||||
<img alt="Telegram" src="https://img.shields.io/badge/Telegram-Bot-26A5E4?style=flat-square&logo=telegram&logoColor=white">
|
||||
<img alt="GitHub Actions" src="https://img.shields.io/badge/GitHub_Actions-Release-2088FF?style=flat-square&logo=githubactions&logoColor=white">
|
||||
</p>
|
||||
|
||||
[English](../README.md) | **العربية** | [简体中文](README.zh-CN.md) | [Français](README.fr.md) | [Русский](README.ru.md) | [Español](README.es.md)
|
||||
|
||||
Vocat هي لوحة تحكم ويب مفتوحة المصدر ومجموعة أدوات هندسية لمودمات Quectel الخلوية من فئة EC20/EC25. تجمع في خدمة واحدة مكتفية ذاتيًا بين اكتشاف المودم، وحالة الراديو المباشرة، وطرفيات AT وUSSD، والرسائل القصيرة SMS، وWiFi Calling، وإدارة eSIM، واختيار الشبكة، والتوجيه عبر البروكسي، والإشعارات، وسجلات التدقيق، وأتمتة الإصدارات.
|
||||
|
||||
الواجهة الخلفية مكتوبة بلغة Go، والواجهة مبنية باستخدام React وTypeScript، وتُضمَّن واجهة الإنتاج الأمامية داخل الملف الثنائي لـ Go. يحتوي ملف تنفيذي واحد على تطبيق الويب ويستخدم SQLite للحالة الدائمة.
|
||||
|
||||
<p align="center">
|
||||
<img src="../img/image.png">
|
||||
<img src="../img/image-1.png">
|
||||
</p>
|
||||
|
||||
## الميزات
|
||||
|
||||
| المجال | ما يوفره Vocat |
|
||||
| --- | --- |
|
||||
| إدارة الأجهزة | اكتشاف تلقائي عبر المنفذ التسلسلي/USB، دعم عدة مودمات، أسماء أجهزة مألوفة، تحديثات مباشرة للنظرة العامة، إعادة تشغيل الوحدة، وضع الطيران، وضوابط وضع شبكة USB. |
|
||||
| الراديو والشبكة | حالة التسجيل، المشغّل، مقاييس الإشارة، RSRP/RSRQ/SINR، وضع الشبكة، النطاق، القناة، فحص المشغّلين، والاختيار التلقائي أو اليدوي للشبكة. |
|
||||
| AT وUSSD | طرفية AT تفاعلية، سجل الأوامر، استجابات المودم الخام، تدفقات بدء/متابعة/إلغاء USSD، والإبلاغ الواضح عن أخطاء المودم. |
|
||||
| الرسائل القصيرة | إرسال مباشر للرسائل الخلوية ورسائل IMS، المزامنة الواردة، التعامل مع الرسائل متعددة الأجزاء، تقارير التسليم، سجل المحادثات، حالة عدم القراءة، الطوابع الزمنية، وحالة التسليم لكل رسالة. |
|
||||
| WiFi Calling | إنشاء نفق IKEv2/ePDG، مصادقة EAP-AKA، تسجيل IMS، رسائل IMS القصيرة، ضوابط إعادة الاتصال، تشخيصات الحالة، والتوجيه لكل جهاز. |
|
||||
| eSIM وeUICC | اكتشاف eUICC، ومعلومات EID والإنتاج، والبيانات الوصفية للشهادات، وجرد متعدد لـ eUICC، وقائمة الملفات الشخصية المثبتة، وعمليات التمكين/التعطيل/التبديل، وعمليات التنزيل وإعادة التسمية والحذف عندما تدعمها البطاقة. |
|
||||
| سياسة البطاقة | سلوك WiFi Calling ووضع الطيران بناءً على ICCID مع تطبيق فوري للسياسة. |
|
||||
| التوجيه عبر البروكسي | توجيه SOCKS صاعد، ربط الأجهزة، قواعد الدول، فحوصات الوصول عبر TCP، وفحوصات UDP Associate لمسارات بيانات WiFi Calling. |
|
||||
| الإشعارات | إعادة توجيه الرسائل القصيرة الواردة الجديدة عبر Telegram وBark والبريد الإلكتروني وPushplus وwebhooks الموقّعة. يتم تسليم كل رسالة كإشعار منفصل. |
|
||||
| بوت Telegram | حالة الجهاز، قائمة الملفات الشخصية المثبتة وتبديلها، ضوابط WiFi Calling، وإرسال الرسائل القصيرة. تتطلب الإجراءات الحساسة تأكيد المسؤول. |
|
||||
| العمليات | المصادقة، الحماية من CSRF، سياسات الوصول، أحداث التدقيق، السجلات المباشرة، الاحتفاظ بالسجلات، فحوصات الصحة، تخطيط متجاوب، الوضع الداكن، وواجهة مستخدم بالإنجليزية/الصينية. |
|
||||
| التوزيع | ملفات Linux الثنائية الثابتة، سكربت تثبيت systemd، تحديث ذاتي مع التحقق من SHA-256، صورة Docker، النشر إلى GHCR، وبنى إصدارات GitHub Actions. |
|
||||
|
||||
## الأجهزة المدعومة
|
||||
|
||||
يستهدف Vocat وحدات Quectel المبنية على Qualcomm والتي توفر واجهات AT وQMI والمنفذ التسلسلي وشبكة USB المتوافقة، بما في ذلك:
|
||||
|
||||
- Quectel EC20
|
||||
- Quectel EC25
|
||||
- عائلة Quectel EG25
|
||||
- وحدات EG600 المتوافقة وذات الصلة
|
||||
|
||||
تعتمد الميزات المتاحة على برنامج الوحدة الثابت (firmware)، وتكوين USB، وقدرات SIM/eSIM، وتعريفات المضيف، والشبكة اللاسلكية، وإعدادات المشغّل.
|
||||
|
||||
## التثبيت
|
||||
|
||||
### تثبيت Linux بنقرة واحدة
|
||||
|
||||
بصفتك root (بما في ذلك OpenWrt/Kwrt، حيث يكون `sudo` غير موجود عادةً):
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
من مستخدم عادي على توزيعة تحتوي على sudo:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | sudo bash
|
||||
```
|
||||
|
||||
تحقق من متطلبات VoWiFi/XFRM على المضيف دون تثبيت VoCat:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | bash -s -- --check-env
|
||||
```
|
||||
|
||||
تثبيت إصدار محدد:
|
||||
|
||||
```bash
|
||||
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 من مستودع البرنامج الثابت نفسه.
|
||||
إذا لم تكن وحدات النواة المطابقة متاحة، فاستخدم برنامجًا ثابتًا يتضمنها؛
|
||||
ولا تفرض أبدًا تثبيت kmods مبنية لنواة مختلفة.
|
||||
|
||||
المثبّت:
|
||||
|
||||
- يكتشف `amd64` أو `386` أو `arm64` أو `aarch64` أو `armv7`؛
|
||||
- ينزّل الملف الثنائي المطابق من GitHub Release؛
|
||||
- يتحقق منه مقابل `SHA256SUMS`؛
|
||||
- يثبّت Vocat في `/opt/vocat`؛
|
||||
- ينشئ خدمة systemd محصّنة بوصول الأجهزة والشبكة الذي يتطلبه Vocat؛
|
||||
- يخزّن إعدادات وقت التشغيل في `/etc/vocat/env`؛
|
||||
- يولّد كلمة مرور مسؤول أولية عشوائية عند التثبيت الأول.
|
||||
|
||||
بعد التثبيت، افتح:
|
||||
|
||||
```text
|
||||
http://<عنوان-الخادم>:7575
|
||||
```
|
||||
|
||||
### التثبيت اليدوي للملف الثنائي
|
||||
|
||||
نزّل الملف الثنائي المطابق و`SHA256SUMS` من GitHub Releases:
|
||||
|
||||
| المنصة | ملف الإصدار |
|
||||
| --- | --- |
|
||||
| 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` |
|
||||
|
||||
تحقق منه وثبّته:
|
||||
|
||||
```bash
|
||||
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` حتى
|
||||
يبدأ العملية الخادم مباشرةً؛ إن تشغيل `vocat` دون وسائط بصفتك root
|
||||
على TTY يفتح بدلاً من ذلك قائمة الإدارة التفاعلية. استخدم المثبّت بنقرة
|
||||
واحدة عند الحاجة إلى خدمة systemd مُدارة وإعادة تشغيل تلقائية.
|
||||
|
||||
### Docker
|
||||
|
||||
لمضيف Linux الذي يجب أن يكتشف كل مودم Quectel مدعوم متصل ويواصل
|
||||
رؤية أحداث التوصيل الساخن لـ USB، شغّل Vocat في وضع الوصول إلى الأجهزة:
|
||||
|
||||
```bash
|
||||
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 `2c7c`)، وليس على ماركات مودم عشوائية.
|
||||
إن تركيب العقد الفردية فقط باستخدام `--device`، مثل `/dev/ttyUSB2` و`/dev/cdc-wdm0`،
|
||||
يحصر الحاوية في تلك العقد الثابتة ولا يوفر اكتشافًا كاملاً متعدد الأجهزة أو بالتوصيل الساخن.
|
||||
|
||||
تُنشر صورة GHCR لـ `linux/amd64` و`linux/arm64`.
|
||||
|
||||
## الإعدادات
|
||||
|
||||
يقرأ Vocat ملف إعدادات JSON اختياريًا من `VOCAT_CONFIG`، ثم يطبق متغيرات البيئة `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. |
|
||||
| `VOCAT_SHUTDOWN_TIMEOUT` | `10s` | مهلة الإيقاف السلس. |
|
||||
| `VOCAT_MAX_REQUEST_BODY_BYTES` | `1048576` | الحد الأقصى لحجم جسم طلب API. |
|
||||
| `VOCAT_REPO` | `MengMengCode/VoCat` | مستودع GitHub الموثوق الذي يستخدمه المحدّث الذاتي، بصيغة `owner/name`. |
|
||||
| `GITHUB_TOKEN` | فارغ | رمز GitHub اختياري للمستودعات الخاصة أو حدود API أعلى. |
|
||||
|
||||
لا تخزّن رموز Telegram، أو كلمات مرور SMTP، أو أسرار webhook، أو بيانات اعتماد SIM، أو بيانات خاصة أخرى في المستودع. قم بإعدادها عبر إعدادات التطبيق أو ملفات البيئة المحمية.
|
||||
|
||||
## بوت Telegram
|
||||
|
||||
عند تفعيل إشعارات Telegram وإعداد كلٍّ من Chat ID وAdmin ID، يدعم البوت:
|
||||
|
||||
```text
|
||||
/status [الجهاز]
|
||||
/esim <الجهاز>
|
||||
/switch <الجهاز> <iccid>
|
||||
/wfc <الجهاز> <status|on|off|reconnect>
|
||||
/sms <الجهاز> <الرقم> <الرسالة>
|
||||
```
|
||||
|
||||
تستخدم عمليتا تبديل الملفات الشخصية وإرسال الرسائل القصيرة أزرار تأكيد لمرة واحدة. لا يعرض البوت أوامر تنزيل أو حذف أو إعادة تسمية eSIM.
|
||||
|
||||
## التحديث
|
||||
|
||||
تحقق من وجود GitHub Release أحدث:
|
||||
|
||||
```bash
|
||||
vocat update --check --repo MengMengCode/VoCat
|
||||
```
|
||||
|
||||
ثبّت أحدث إصدار:
|
||||
|
||||
```bash
|
||||
sudo vocat update --repo MengMengCode/VoCat
|
||||
```
|
||||
|
||||
ينزّل المحدّث الملف الثنائي المطابق لبنية Linux الحالية، ويتحقق منه باستخدام `SHA256SUMS` المنشور، ويستبدل الملف التنفيذي بشكل ذري، ويعيد تشغيل خدمة systemd `vocat` عند توفرها.
|
||||
|
||||
لتثبيتات Docker:
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/mengmengcode/vocat:latest
|
||||
```
|
||||
|
||||
أعد إنشاء الحاوية بعد سحب الصورة الجديدة.
|
||||
|
||||
## التطوير
|
||||
|
||||
المتطلبات:
|
||||
|
||||
- Go 1.25 أو أحدث
|
||||
- Node.js 20 أو أحدث
|
||||
- npm
|
||||
|
||||
تشغيل خادم تطوير الواجهة الأمامية:
|
||||
|
||||
```bash
|
||||
cd web
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
بناء الواجهة الأمامية المضمّنة وتشغيل الواجهة الخلفية:
|
||||
|
||||
```bash
|
||||
cd web
|
||||
npm run build
|
||||
cd ..
|
||||
go run ./cmd/vocat
|
||||
```
|
||||
|
||||
تشغيل جميع الاختبارات:
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
```
|
||||
|
||||
بناء ملف ثنائي للإنتاج:
|
||||
|
||||
```bash
|
||||
go build -trimpath -ldflags "-s -w" -o vocat ./cmd/vocat
|
||||
```
|
||||
|
||||
## أتمتة الإصدارات
|
||||
|
||||
يؤدي دفع وسم الإصدار إلى بدء سير عملَي GitHub Actions:
|
||||
|
||||
- `release-binaries` يبني وينشر ملفات `amd64` و`386` و`arm64` و`aarch64` و`armv7` الثنائية مع `SHA256SUMS`.
|
||||
- `docker` يبني وينشر صورة متعددة البنى إلى GitHub Container Registry.
|
||||
|
||||
```bash
|
||||
git tag v0.2.0
|
||||
git push origin v0.2.0
|
||||
```
|
||||
|
||||
## بنية المشروع
|
||||
|
||||
```text
|
||||
cmd/vocat/ نقطة دخول التطبيق وCLI
|
||||
internal/device/ اكتشاف المودم والتحكم في الأجهزة
|
||||
internal/modem/ جلسة AT ومعالجة الاستجابات
|
||||
internal/server/ واجهة HTTP API والإشعارات وخادم الويب المضمّن
|
||||
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؛ وقد يرفضها الجهاز أو الملف الشخصي أو الشبكة أو المشغّل مع ذلك.
|
||||
|
||||
## المساهمة
|
||||
|
||||
نرحّب بالمسائل (issues) وطلبات السحب (pull requests). حافظ على التغييرات مركّزة، وأضِف الاختبارات حيثما أمكن، وتجنّب إيداع بيانات الاعتماد أو بيانات المشتركين، ووثّق بوضوح السلوك الخاص بالأجهزة.
|
||||
|
||||
قبل إرسال تغيير:
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
cd web && npm run build
|
||||
```
|
||||
|
||||
## شكر وتقدير
|
||||
- [Nodeseek.com](https://www.nodeseek.com) — مجتمع مكرّس للخوادم
|
||||
- [Linux.do](https://linux.do) — مجتمع تقني ملهم
|
||||
- [iniwex5](https://github.com/iniwex5) — إرشادات الأسلوب والوظائف
|
||||
|
||||
## ادعُني إلى فنجان قهوة
|
||||
|
||||
| الشبكة | العنوان |
|
||||
| ------- | ------- |
|
||||
| USDT-TRON (TRC20) | `TQQAbboBoU8h5xX4YCA1rqWJU2WjK3seSg` |
|
||||
| USDT-BSC (BEP20) | `0xdbfcd4a462550d6ff06d09cbd89026c6b145d9c4` |
|
||||
| USDT-Polygon | `0xdbfcd4a462550d6ff06d09cbd89026c6b145d9c4` |
|
||||
|
||||
## الرخصة
|
||||
|
||||
انظر [LICENSE](../LICENSE).
|
||||
|
||||
[](https://meteor-history.com)
|
||||
@@ -0,0 +1,336 @@
|
||||
<p align="center">
|
||||
<img src="../web/public/favicon.svg" width="96" alt="Vocat">
|
||||
</p>
|
||||
|
||||
<h1 align="center">VoCat</h1>
|
||||
|
||||
<p align="center">
|
||||
<img alt="Go" src="https://img.shields.io/badge/Go-1.25-00ADD8?style=flat-square&logo=go&logoColor=white">
|
||||
<img alt="React" src="https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react&logoColor=111111">
|
||||
<img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.8-3178C6?style=flat-square&logo=typescript&logoColor=white">
|
||||
<img alt="Vite" src="https://img.shields.io/badge/Vite-7-646CFF?style=flat-square&logo=vite&logoColor=white">
|
||||
<img alt="Tailwind CSS" src="https://img.shields.io/badge/Tailwind_CSS-3-06B6D4?style=flat-square&logo=tailwindcss&logoColor=white">
|
||||
<img alt="SQLite" src="https://img.shields.io/badge/SQLite-Embedded-003B57?style=flat-square&logo=sqlite&logoColor=white">
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<img alt="Linux" src="https://img.shields.io/badge/Linux-amd64_%7C_386_%7C_arm64_%7C_aarch64_%7C_armv7-FCC624?style=flat-square&logo=linux&logoColor=111111">
|
||||
<img alt="Docker" src="https://img.shields.io/badge/Docker-Multi--Arch-2496ED?style=flat-square&logo=docker&logoColor=white">
|
||||
<img alt="WiFi Calling" src="https://img.shields.io/badge/WiFi_Calling-IMS_SMS-7B1FA2?style=flat-square">
|
||||
<img alt="eSIM" src="https://img.shields.io/badge/eSIM-LPA_%2F_eUICC-009688?style=flat-square">
|
||||
<img alt="Telegram" src="https://img.shields.io/badge/Telegram-Bot-26A5E4?style=flat-square&logo=telegram&logoColor=white">
|
||||
<img alt="GitHub Actions" src="https://img.shields.io/badge/GitHub_Actions-Release-2088FF?style=flat-square&logo=githubactions&logoColor=white">
|
||||
</p>
|
||||
|
||||
[English](../README.md) | [العربية](README.ar.md) | [简体中文](README.zh-CN.md) | [Français](README.fr.md) | [Русский](README.ru.md) | **Español**
|
||||
|
||||
Vocat es un panel de control web de código abierto y un conjunto de herramientas de ingeniería para módems celulares Quectel de clase EC20/EC25. Combina, en un único servicio autocontenido, el descubrimiento de módems, el estado de radio en vivo, terminales AT y USSD, SMS, WiFi Calling, gestión de eSIM, selección de red, enrutamiento por proxy, notificaciones, registros de auditoría y automatización de versiones.
|
||||
|
||||
El backend está escrito en Go, la interfaz está construida con React y TypeScript, y el frontend de producción está incrustado en el binario de Go. Un único ejecutable contiene la aplicación web y utiliza SQLite para el estado persistente.
|
||||
|
||||
<p align="center">
|
||||
<img src="../img/image.png">
|
||||
<img src="../img/image-1.png">
|
||||
</p>
|
||||
|
||||
## Funcionalidades
|
||||
|
||||
| Área | Lo que proporciona Vocat |
|
||||
| --- | --- |
|
||||
| Gestión de dispositivos | Descubrimiento serie/USB automático, soporte para múltiples módems, nombres de dispositivo amigables, actualizaciones en vivo de la vista general, reinicio del módulo, modo avión y controles del modo de red USB. |
|
||||
| Radio y red | Estado de registro, operador, métricas de señal, RSRP/RSRQ/SINR, modo de red, banda, canal, búsqueda de operadores y selección de red automática o manual. |
|
||||
| AT y USSD | Terminal AT interactivo, historial de comandos, respuestas sin procesar del módem, flujos de inicio/continuación/cancelación de USSD y reporte claro de errores del módem. |
|
||||
| SMS | Envío directo de SMS celulares e IMS, sincronización entrante, manejo multiparte, informes de entrega, historial de conversaciones, estado de no leído, marcas de tiempo y estado de entrega por mensaje. |
|
||||
| WiFi Calling | Establecimiento de túnel IKEv2/ePDG, autenticación EAP-AKA, registro IMS, SMS IMS, controles de reconexión, diagnósticos de estado y enrutamiento por dispositivo. |
|
||||
| eSIM y eUICC | Descubrimiento de eUICC, EID e información de producción, metadatos de certificados, inventario multi-eUICC, lista de perfiles instalados, operaciones de habilitar/deshabilitar/cambiar, y operaciones de descarga, renombrado y eliminación cuando la tarjeta lo admite. |
|
||||
| Política de tarjeta | Comportamiento de WiFi Calling y modo avión basado en ICCID con aplicación inmediata de la política. |
|
||||
| Enrutamiento por proxy | Enrutamiento SOCKS ascendente, vinculaciones de dispositivos, reglas por país, comprobaciones de accesibilidad TCP y comprobaciones UDP Associate para las rutas de datos de WiFi Calling. |
|
||||
| Notificaciones | Reenvío de nuevos SMS entrantes a través de Telegram, Bark, correo electrónico, Pushplus y webhooks firmados. Cada SMS se entrega como una notificación individual. |
|
||||
| Bot de Telegram | Estado del dispositivo, lista y cambio de perfiles instalados, controles de WiFi Calling y envío de SMS. Las acciones sensibles requieren confirmación del administrador. |
|
||||
| Operaciones | Autenticación, protección CSRF, políticas de acceso, eventos de auditoría, registros en vivo, retención de registros, comprobaciones de salud, diseño adaptable, modo oscuro e interfaz de usuario en inglés/chino. |
|
||||
| Distribución | Binarios estáticos de Linux, script de instalación systemd, autoactualización con verificación SHA-256, imagen Docker, publicación en GHCR y compilaciones de versión de GitHub Actions. |
|
||||
|
||||
## Hardware compatible
|
||||
|
||||
Vocat está dirigido a módulos Quectel basados en Qualcomm que exponen interfaces AT, QMI, serie y de red USB compatibles, incluyendo:
|
||||
|
||||
- Quectel EC20
|
||||
- Quectel EC25
|
||||
- Familia Quectel EG25
|
||||
- Módulos EG600 compatibles y relacionados
|
||||
|
||||
Las funciones disponibles dependen del firmware del módulo, la composición USB, las capacidades SIM/eSIM, los controladores del host, la red de radio y la configuración del operador.
|
||||
|
||||
## Instalación
|
||||
|
||||
### Instalación en Linux con un clic
|
||||
|
||||
Como root (incluyendo OpenWrt/Kwrt, donde `sudo` normalmente está ausente):
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
Desde un usuario normal en una distribución con sudo:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | sudo bash
|
||||
```
|
||||
|
||||
Comprobar los prerrequisitos de VoWiFi/XFRM del host sin instalar VoCat:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | bash -s -- --check-env
|
||||
```
|
||||
|
||||
Instalar una versión específica:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh -o install.sh
|
||||
sudo bash install.sh 0.0.2
|
||||
```
|
||||
|
||||
VoWiFi IMS requiere Linux XFRM/IPsec. En OpenWrt/Kwrt el instalador intenta
|
||||
instalar los paquetes coincidentes `ip-full`, `kmod-ipsec`, `kmod-ipsec4/6`,
|
||||
`kmod-crypto-authenc`, AES-CBC y SHA1 desde el propio feed del firmware.
|
||||
Si no hay módulos de kernel coincidentes disponibles, use un firmware que los incluya;
|
||||
nunca fuerce la instalación de kmods compilados para un kernel diferente.
|
||||
|
||||
El instalador:
|
||||
|
||||
- detecta `amd64`, `386`, `arm64`, `aarch64` o `armv7`;
|
||||
- descarga el binario de GitHub Release correspondiente;
|
||||
- lo verifica contra `SHA256SUMS`;
|
||||
- instala Vocat en `/opt/vocat`;
|
||||
- crea un servicio systemd reforzado con el acceso a hardware y red requerido por Vocat;
|
||||
- almacena la configuración en tiempo de ejecución en `/etc/vocat/env`;
|
||||
- genera una contraseña de administrador inicial aleatoria en la primera instalación.
|
||||
|
||||
Después de la instalación, abra:
|
||||
|
||||
```text
|
||||
http://<dirección-del-servidor>:7575
|
||||
```
|
||||
|
||||
### Instalación manual del binario
|
||||
|
||||
Descargue el binario correspondiente y `SHA256SUMS` desde GitHub Releases:
|
||||
|
||||
| Plataforma | Archivo de versión |
|
||||
| --- | --- |
|
||||
| Linux x86-64 | `vocat-linux-amd64` |
|
||||
| Linux x86 32 bits | `vocat-linux-386` |
|
||||
| Linux ARM64 | `vocat-linux-arm64` |
|
||||
| Linux AArch64 | `vocat-linux-aarch64` |
|
||||
| Linux ARMv7 | `vocat-linux-armv7` |
|
||||
|
||||
Verifíquelo e instálelo:
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
Este comando manual ejecuta Vocat en primer plano. Use `vocat serve` para que el
|
||||
proceso inicie el servidor directamente; ejecutar `vocat` sin argumentos como root
|
||||
en un TTY abre en su lugar el menú de gestión interactivo. Use el instalador de
|
||||
un clic cuando se requiera un servicio systemd gestionado y reinicio automático.
|
||||
|
||||
### Docker
|
||||
|
||||
Para un host Linux que debe descubrir cada módem Quectel compatible conectado y
|
||||
seguir viendo los eventos de conexión en caliente USB, ejecute Vocat en modo de acceso a hardware:
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
Abra `http://<dirección-del-servidor>:7575` después de que el contenedor se inicie. La red del host
|
||||
es necesaria para que las interfaces de red QMI permanezcan visibles para Vocat, mientras que el
|
||||
acceso privilegiado a dispositivos es necesario para los puertos serie, los nodos de control QMI,
|
||||
las interfaces TUN, la configuración de red y los dispositivos añadidos después de que el contenedor
|
||||
se inicie. El montaje bind de `/dev` hace visibles los nuevos nodos `ttyUSB*`, `ttyACM*` y `cdc-wdm*`
|
||||
sin recrear el contenedor.
|
||||
|
||||
Este modo otorga intencionadamente a Vocat un amplio acceso a los dispositivos y a la pila de red
|
||||
del host. Úselo solo en un host Linux de confianza. El descubrimiento automático identifica
|
||||
actualmente los módems USB Quectel compatibles (ID de fabricante USB `2c7c`), no marcas de módems
|
||||
arbitrarias. Mapear solo nodos individuales con `--device`, como `/dev/ttyUSB2` y `/dev/cdc-wdm0`,
|
||||
limita el contenedor a esos nodos fijos y no proporciona un descubrimiento completo de múltiples
|
||||
dispositivos o de conexión en caliente.
|
||||
|
||||
La imagen GHCR se publica para `linux/amd64` y `linux/arm64`.
|
||||
|
||||
## Configuración
|
||||
|
||||
Vocat lee un archivo de configuración JSON opcional desde `VOCAT_CONFIG` y luego aplica las variables de entorno `VOCAT_*`. Las variables de entorno tienen prioridad.
|
||||
|
||||
| Variable de entorno | Predeterminado | Descripción |
|
||||
| --- | --- | --- |
|
||||
| `VOCAT_ADDR` | `0.0.0.0:7575` | Dirección de escucha HTTP. |
|
||||
| `VOCAT_DATABASE_PATH` | `./data/vocat.db` | Ruta de la base de datos SQLite. |
|
||||
| `VOCAT_ADMIN_USERNAME` | `admin` | Nombre de usuario administrador inicial. |
|
||||
| `VOCAT_ADMIN_PASSWORD` | `admin` | Contraseña de administrador inicial. Cámbiela antes de exponer el servicio. |
|
||||
| `VOCAT_SESSION_TTL` | `24h` | Duración de la sesión de autenticación. |
|
||||
| `VOCAT_SECURE_COOKIES` | `false` | Marca las cookies de sesión como seguras cuando se usa HTTPS. |
|
||||
| `VOCAT_SHUTDOWN_TIMEOUT` | `10s` | Tiempo de espera de apagado ordenado. |
|
||||
| `VOCAT_MAX_REQUEST_BODY_BYTES` | `1048576` | Tamaño máximo del cuerpo de solicitud de la API. |
|
||||
| `VOCAT_REPO` | `MengMengCode/VoCat` | Repositorio de GitHub de confianza usado por el autoactualizador, en formato `owner/name`. |
|
||||
| `GITHUB_TOKEN` | vacío | Token de GitHub opcional para repositorios privados o límites de API más altos. |
|
||||
|
||||
No almacene tokens de Telegram, contraseñas SMTP, secretos de webhook, credenciales SIM u otros datos privados en el repositorio. Configúrelos a través de los ajustes de la aplicación o archivos de entorno protegidos.
|
||||
|
||||
## Bot de Telegram
|
||||
|
||||
Cuando las notificaciones de Telegram están habilitadas y tanto el Chat ID como el Admin ID están configurados, el bot admite:
|
||||
|
||||
```text
|
||||
/status [dispositivo]
|
||||
/esim <dispositivo>
|
||||
/switch <dispositivo> <iccid>
|
||||
/wfc <dispositivo> <status|on|off|reconnect>
|
||||
/sms <dispositivo> <número> <mensaje>
|
||||
```
|
||||
|
||||
El cambio de perfil y el envío de SMS usan botones de confirmación de un solo uso. El bot no expone comandos de descarga, eliminación o renombrado de eSIM.
|
||||
|
||||
## Actualización
|
||||
|
||||
Comprobar si hay una GitHub Release más reciente:
|
||||
|
||||
```bash
|
||||
vocat update --check --repo MengMengCode/VoCat
|
||||
```
|
||||
|
||||
Instalar la última versión:
|
||||
|
||||
```bash
|
||||
sudo vocat update --repo MengMengCode/VoCat
|
||||
```
|
||||
|
||||
El actualizador descarga el binario que coincide con la arquitectura Linux actual, lo verifica con el `SHA256SUMS` publicado, reemplaza el ejecutable de forma atómica y reinicia el servicio systemd `vocat` cuando está disponible.
|
||||
|
||||
Para instalaciones Docker:
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/mengmengcode/vocat:latest
|
||||
```
|
||||
|
||||
Recrear el contenedor después de descargar la nueva imagen.
|
||||
|
||||
## Desarrollo
|
||||
|
||||
Requisitos:
|
||||
|
||||
- Go 1.25 o más reciente
|
||||
- Node.js 20 o más reciente
|
||||
- npm
|
||||
|
||||
Ejecutar el servidor de desarrollo del frontend:
|
||||
|
||||
```bash
|
||||
cd web
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Compilar el frontend incrustado e iniciar el backend:
|
||||
|
||||
```bash
|
||||
cd web
|
||||
npm run build
|
||||
cd ..
|
||||
go run ./cmd/vocat
|
||||
```
|
||||
|
||||
Ejecutar todas las pruebas:
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
```
|
||||
|
||||
Compilar un binario de producción:
|
||||
|
||||
```bash
|
||||
go build -trimpath -ldflags "-s -w" -o vocat ./cmd/vocat
|
||||
```
|
||||
|
||||
## Automatización de versiones
|
||||
|
||||
Hacer push de una etiqueta de versión inicia dos flujos de trabajo de GitHub Actions:
|
||||
|
||||
- `release-binaries` compila y publica los binarios `amd64`, `386`, `arm64`, `aarch64` y `armv7` más `SHA256SUMS`.
|
||||
- `docker` compila y publica una imagen multiarquitectura en GitHub Container Registry.
|
||||
|
||||
```bash
|
||||
git tag v0.2.0
|
||||
git push origin v0.2.0
|
||||
```
|
||||
|
||||
## Estructura del proyecto
|
||||
|
||||
```text
|
||||
cmd/vocat/ Punto de entrada de la aplicación y CLI
|
||||
internal/device/ Descubrimiento de módems y control de dispositivos
|
||||
internal/modem/ Sesión AT y manejo de respuestas
|
||||
internal/server/ API HTTP, notificaciones y servidor web incrustado
|
||||
internal/store/ Persistencia SQLite
|
||||
internal/update/ Autoactualizador de GitHub Release
|
||||
internal/vowifi/ Runtime de IKE, EAP-AKA, IMS y WiFi Calling
|
||||
scripts/install.sh Instalador y actualizador de Linux
|
||||
web/src/ Frontend en React y TypeScript
|
||||
.github/workflows/ Automatización de versiones de binarios y Docker
|
||||
```
|
||||
|
||||
## Uso responsable
|
||||
|
||||
Las operaciones con módems celulares y eSIM pueden afectar el servicio del abonado, los perfiles almacenados, el registro de red y el estado del hardware. Mantenga copias de seguridad, revise con cuidado las acciones destructivas y use el software solo en entornos legales donde tenga permiso para operar el hardware y los recursos de red conectados.
|
||||
|
||||
Vocat no elude la autenticación del operador, la política de red, la seguridad del hardware ni los requisitos de confianza de eSIM. El soporte de una operación significa que Vocat puede solicitarla al módem o al eUICC; el dispositivo, el perfil, la red o el operador aún pueden rechazarla.
|
||||
|
||||
## Contribuir
|
||||
|
||||
Las incidencias y pull requests son bienvenidas. Mantenga los cambios enfocados, incluya pruebas cuando sea práctico, evite confirmar credenciales o datos de abonados, y documente claramente el comportamiento específico del hardware.
|
||||
|
||||
Antes de enviar un cambio:
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
cd web && npm run build
|
||||
```
|
||||
|
||||
## Agradecimientos
|
||||
- [Nodeseek.com](https://www.nodeseek.com) — Una comunidad dedicada a los servidores
|
||||
- [Linux.do](https://linux.do) — Una comunidad tecnológica inspiradora
|
||||
- [iniwex5](https://github.com/iniwex5) — Guías de estilo y funcionalidad
|
||||
|
||||
## Invítame a un café
|
||||
|
||||
| Red | Dirección |
|
||||
| ------- | ------- |
|
||||
| USDT-TRON (TRC20) | `TQQAbboBoU8h5xX4YCA1rqWJU2WjK3seSg` |
|
||||
| USDT-BSC (BEP20) | `0xdbfcd4a462550d6ff06d09cbd89026c6b145d9c4` |
|
||||
| USDT-Polygon | `0xdbfcd4a462550d6ff06d09cbd89026c6b145d9c4` |
|
||||
|
||||
## Licencia
|
||||
|
||||
Consulte [LICENSE](../LICENSE).
|
||||
|
||||
[](https://meteor-history.com)
|
||||
@@ -0,0 +1,336 @@
|
||||
<p align="center">
|
||||
<img src="../web/public/favicon.svg" width="96" alt="Vocat">
|
||||
</p>
|
||||
|
||||
<h1 align="center">VoCat</h1>
|
||||
|
||||
<p align="center">
|
||||
<img alt="Go" src="https://img.shields.io/badge/Go-1.25-00ADD8?style=flat-square&logo=go&logoColor=white">
|
||||
<img alt="React" src="https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react&logoColor=111111">
|
||||
<img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.8-3178C6?style=flat-square&logo=typescript&logoColor=white">
|
||||
<img alt="Vite" src="https://img.shields.io/badge/Vite-7-646CFF?style=flat-square&logo=vite&logoColor=white">
|
||||
<img alt="Tailwind CSS" src="https://img.shields.io/badge/Tailwind_CSS-3-06B6D4?style=flat-square&logo=tailwindcss&logoColor=white">
|
||||
<img alt="SQLite" src="https://img.shields.io/badge/SQLite-Embedded-003B57?style=flat-square&logo=sqlite&logoColor=white">
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<img alt="Linux" src="https://img.shields.io/badge/Linux-amd64_%7C_386_%7C_arm64_%7C_aarch64_%7C_armv7-FCC624?style=flat-square&logo=linux&logoColor=111111">
|
||||
<img alt="Docker" src="https://img.shields.io/badge/Docker-Multi--Arch-2496ED?style=flat-square&logo=docker&logoColor=white">
|
||||
<img alt="WiFi Calling" src="https://img.shields.io/badge/WiFi_Calling-IMS_SMS-7B1FA2?style=flat-square">
|
||||
<img alt="eSIM" src="https://img.shields.io/badge/eSIM-LPA_%2F_eUICC-009688?style=flat-square">
|
||||
<img alt="Telegram" src="https://img.shields.io/badge/Telegram-Bot-26A5E4?style=flat-square&logo=telegram&logoColor=white">
|
||||
<img alt="GitHub Actions" src="https://img.shields.io/badge/GitHub_Actions-Release-2088FF?style=flat-square&logo=githubactions&logoColor=white">
|
||||
</p>
|
||||
|
||||
[English](../README.md) | [العربية](README.ar.md) | [简体中文](README.zh-CN.md) | **Français** | [Русский](README.ru.md) | [Español](README.es.md)
|
||||
|
||||
Vocat est un panneau de contrôle web open-source et une boîte à outils d'ingénierie pour les modems cellulaires Quectel de classe EC20/EC25. Il réunit, dans un service autonome unique, la découverte de modems, l'état radio en direct, les terminaux AT et USSD, les SMS, la WiFi Calling, la gestion eSIM, la sélection de réseau, le routage par proxy, les notifications, les journaux d'audit et l'automatisation des versions.
|
||||
|
||||
Le backend est écrit en Go, l'interface est construite avec React et TypeScript, et le frontend de production est intégré dans le binaire Go. Un seul exécutable contient l'application web et utilise SQLite pour l'état persistant.
|
||||
|
||||
<p align="center">
|
||||
<img src="../img/image.png">
|
||||
<img src="../img/image-1.png">
|
||||
</p>
|
||||
|
||||
## Fonctionnalités
|
||||
|
||||
| Domaine | Ce que Vocat fournit |
|
||||
| --- | --- |
|
||||
| Gestion des appareils | Découverte série/USB automatique, prise en charge de plusieurs modems, noms d'appareils conviviaux, mises à jour en direct de la vue d'ensemble, redémarrage du module, mode avion et contrôles du mode réseau USB. |
|
||||
| Radio et réseau | État d'enregistrement, opérateur, métriques de signal, RSRP/RSRQ/SINR, mode réseau, bande, canal, recherche d'opérateurs et sélection de réseau automatique ou manuelle. |
|
||||
| AT et USSD | Terminal AT interactif, historique des commandes, réponses brutes du modem, flux de démarrage/poursuite/annulation USSD et rapport d'erreurs modem clair. |
|
||||
| SMS | Envoi direct de SMS cellulaires et IMS, synchronisation entrante, gestion des messages multiparties, rapports de livraison, historique des conversations, état non lu, horodatages et statut de livraison par message. |
|
||||
| WiFi Calling | Établissement de tunnel IKEv2/ePDG, authentification EAP-AKA, enregistrement IMS, SMS IMS, contrôles de reconnexion, diagnostics d'état et routage par appareil. |
|
||||
| eSIM et eUICC | Découverte eUICC, EID et informations de production, métadonnées de certificat, inventaire multi-eUICC, liste des profils installés, opérations d'activation/désactivation/commutation, ainsi que téléchargement, renommage et suppression lorsque la carte le permet. |
|
||||
| Politique de carte | Comportement WiFi Calling et mode avion basé sur l'ICCID avec application immédiate de la politique. |
|
||||
| Routage par proxy | Routage SOCKS amont, liaisons d'appareils, règles par pays, vérifications d'accessibilité TCP et vérifications UDP Associate pour les chemins de données WiFi Calling. |
|
||||
| Notifications | Transfert des nouveaux SMS entrants via Telegram, Bark, e-mail, Pushplus et webhooks signés. Chaque SMS est livré comme une notification individuelle. |
|
||||
| Bot Telegram | État de l'appareil, liste et commutation des profils installés, contrôles WiFi Calling et envoi de SMS. Les actions sensibles nécessitent une confirmation de l'administrateur. |
|
||||
| Exploitation | Authentification, protection CSRF, politiques d'accès, événements d'audit, journaux en direct, rétention des journaux, vérifications de santé, mise en page réactive, mode sombre et interface utilisateur en anglais/chinois. |
|
||||
| Distribution | Binaires Linux statiques, script d'installation systemd, auto-mise à jour avec vérification SHA-256, image Docker, publication GHCR et builds de version GitHub Actions. |
|
||||
|
||||
## Matériel pris en charge
|
||||
|
||||
Vocat cible les modules Quectel à base Qualcomm qui exposent des interfaces AT, QMI, série et réseau USB compatibles, notamment :
|
||||
|
||||
- Quectel EC20
|
||||
- Quectel EC25
|
||||
- Famille Quectel EG25
|
||||
- Modules EG600 compatibles et apparentés
|
||||
|
||||
Les fonctionnalités disponibles dépendent du firmware du module, de la composition USB, des capacités SIM/eSIM, des pilotes hôtes, du réseau radio et de la configuration de l'opérateur.
|
||||
|
||||
## Installation
|
||||
|
||||
### Installation Linux en un clic
|
||||
|
||||
En tant que root (y compris OpenWrt/Kwrt, où `sudo` est normalement absent) :
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
Depuis un utilisateur normal sur une distribution disposant de sudo :
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | sudo bash
|
||||
```
|
||||
|
||||
Vérifier les prérequis VoWiFi/XFRM de l'hôte sans installer VoCat :
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | bash -s -- --check-env
|
||||
```
|
||||
|
||||
Installer une version spécifique :
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh -o install.sh
|
||||
sudo bash install.sh 0.0.2
|
||||
```
|
||||
|
||||
VoWiFi IMS nécessite Linux XFRM/IPsec. Sur OpenWrt/Kwrt, le programme d'installation tente
|
||||
d'installer les paquets correspondants `ip-full`, `kmod-ipsec`, `kmod-ipsec4/6`,
|
||||
`kmod-crypto-authenc`, AES-CBC et SHA1 depuis le dépôt du firmware lui-même.
|
||||
Si des modules noyau correspondants ne sont pas disponibles, utilisez un firmware qui les inclut ;
|
||||
ne forcez jamais l'installation de kmods compilés pour un noyau différent.
|
||||
|
||||
Le programme d'installation :
|
||||
|
||||
- détecte `amd64`, `386`, `arm64`, `aarch64` ou `armv7` ;
|
||||
- télécharge le binaire GitHub Release correspondant ;
|
||||
- le vérifie par rapport à `SHA256SUMS` ;
|
||||
- installe Vocat sous `/opt/vocat` ;
|
||||
- crée un service systemd renforcé disposant des accès matériel et réseau requis par Vocat ;
|
||||
- stocke la configuration d'exécution dans `/etc/vocat/env` ;
|
||||
- génère un mot de passe administrateur initial aléatoire lors de la première installation.
|
||||
|
||||
Après l'installation, ouvrez :
|
||||
|
||||
```text
|
||||
http://<adresse-du-serveur>:7575
|
||||
```
|
||||
|
||||
### Installation manuelle du binaire
|
||||
|
||||
Téléchargez le binaire correspondant et `SHA256SUMS` depuis GitHub Releases :
|
||||
|
||||
| Plateforme | Fichier de version |
|
||||
| --- | --- |
|
||||
| Linux x86-64 | `vocat-linux-amd64` |
|
||||
| Linux x86 32 bits | `vocat-linux-386` |
|
||||
| Linux ARM64 | `vocat-linux-arm64` |
|
||||
| Linux AArch64 | `vocat-linux-aarch64` |
|
||||
| Linux ARMv7 | `vocat-linux-armv7` |
|
||||
|
||||
Vérifiez-le et installez-le :
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
Cette commande manuelle exécute Vocat au premier plan. Utilisez `vocat serve` pour que le
|
||||
processus démarre directement le serveur ; exécuter `vocat` sans argument en tant que root
|
||||
sur un TTY ouvre plutôt le menu de gestion interactif. Utilisez le programme d'installation
|
||||
en un clic lorsqu'un service systemd géré et un redémarrage automatique sont requis.
|
||||
|
||||
### Docker
|
||||
|
||||
Pour un hôte Linux qui doit découvrir chaque modem Quectel pris en charge connecté et
|
||||
continuer à voir les événements de branchement à chaud USB, exécutez Vocat en mode d'accès matériel :
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
Ouvrez `http://<adresse-du-serveur>:7575` après le démarrage du conteneur. Le réseau de l'hôte
|
||||
est requis pour que les interfaces réseau QMI restent visibles par Vocat, tandis que l'accès
|
||||
privilégié aux périphériques est requis pour les ports série, les nœuds de contrôle QMI, les
|
||||
interfaces TUN, la configuration réseau et les périphériques ajoutés après le démarrage du
|
||||
conteneur. Le montage bind de `/dev` rend les nouveaux nœuds `ttyUSB*`, `ttyACM*` et `cdc-wdm*`
|
||||
visibles sans recréer le conteneur.
|
||||
|
||||
Ce mode donne intentionnellement à Vocat un large accès aux périphériques et à la pile réseau
|
||||
de l'hôte. Ne l'utilisez que sur un hôte Linux de confiance. La découverte automatique
|
||||
identifie actuellement les modems USB Quectel pris en charge (ID fabricant USB `2c7c`), et non
|
||||
des marques de modems arbitraires. Le mappage de nœuds individuels uniquement avec `--device`,
|
||||
comme `/dev/ttyUSB2` et `/dev/cdc-wdm0`, limite le conteneur à ces nœuds fixes et ne fournit
|
||||
pas une découverte multi-périphériques ou à chaud complète.
|
||||
|
||||
L'image GHCR est publiée pour `linux/amd64` et `linux/arm64`.
|
||||
|
||||
## Configuration
|
||||
|
||||
Vocat lit un fichier de configuration JSON optionnel depuis `VOCAT_CONFIG`, puis applique les variables d'environnement `VOCAT_*`. Les variables d'environnement ont la priorité.
|
||||
|
||||
| Variable d'environnement | Par défaut | Description |
|
||||
| --- | --- | --- |
|
||||
| `VOCAT_ADDR` | `0.0.0.0:7575` | Adresse d'écoute HTTP. |
|
||||
| `VOCAT_DATABASE_PATH` | `./data/vocat.db` | Chemin de la base de données SQLite. |
|
||||
| `VOCAT_ADMIN_USERNAME` | `admin` | Nom d'utilisateur administrateur initial. |
|
||||
| `VOCAT_ADMIN_PASSWORD` | `admin` | Mot de passe administrateur initial. Modifiez-le avant d'exposer le service. |
|
||||
| `VOCAT_SESSION_TTL` | `24h` | Durée de vie de la session d'authentification. |
|
||||
| `VOCAT_SECURE_COOKIES` | `false` | Marque les cookies de session comme sécurisés lorsque HTTPS est utilisé. |
|
||||
| `VOCAT_SHUTDOWN_TIMEOUT` | `10s` | Délai d'arrêt gracieux. |
|
||||
| `VOCAT_MAX_REQUEST_BODY_BYTES` | `1048576` | Taille maximale du corps de requête API. |
|
||||
| `VOCAT_REPO` | `MengMengCode/VoCat` | Dépôt GitHub de confiance utilisé par l'auto-updater, au format `owner/name`. |
|
||||
| `GITHUB_TOKEN` | vide | Jeton GitHub optionnel pour les dépôts privés ou des limites d'API plus élevées. |
|
||||
|
||||
Ne stockez pas de jetons Telegram, mots de passe SMTP, secrets de webhook, identifiants SIM ou autres données privées dans le dépôt. Configurez-les via les paramètres de l'application ou des fichiers d'environnement protégés.
|
||||
|
||||
## Bot Telegram
|
||||
|
||||
Lorsque les notifications Telegram sont activées et que le Chat ID et l'Admin ID sont configurés, le bot prend en charge :
|
||||
|
||||
```text
|
||||
/status [appareil]
|
||||
/esim <appareil>
|
||||
/switch <appareil> <iccid>
|
||||
/wfc <appareil> <status|on|off|reconnect>
|
||||
/sms <appareil> <numéro> <message>
|
||||
```
|
||||
|
||||
La commutation de profil et l'envoi de SMS utilisent des boutons de confirmation à usage unique. Le bot n'expose pas les commandes de téléchargement, de suppression ou de renommage eSIM.
|
||||
|
||||
## Mise à jour
|
||||
|
||||
Vérifier l'existence d'une GitHub Release plus récente :
|
||||
|
||||
```bash
|
||||
vocat update --check --repo MengMengCode/VoCat
|
||||
```
|
||||
|
||||
Installer la dernière version :
|
||||
|
||||
```bash
|
||||
sudo vocat update --repo MengMengCode/VoCat
|
||||
```
|
||||
|
||||
L'updater télécharge le binaire correspondant à l'architecture Linux actuelle, le vérifie avec le `SHA256SUMS` publié, remplace l'exécutable de manière atomique et redémarre le service systemd `vocat` lorsqu'il est disponible.
|
||||
|
||||
Pour les installations Docker :
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/mengmengcode/vocat:latest
|
||||
```
|
||||
|
||||
Recréez le conteneur après avoir tiré la nouvelle image.
|
||||
|
||||
## Développement
|
||||
|
||||
Prérequis :
|
||||
|
||||
- Go 1.25 ou plus récent
|
||||
- Node.js 20 ou plus récent
|
||||
- npm
|
||||
|
||||
Lancer le serveur de développement frontend :
|
||||
|
||||
```bash
|
||||
cd web
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Construire le frontend intégré et démarrer le backend :
|
||||
|
||||
```bash
|
||||
cd web
|
||||
npm run build
|
||||
cd ..
|
||||
go run ./cmd/vocat
|
||||
```
|
||||
|
||||
Exécuter tous les tests :
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
```
|
||||
|
||||
Construire un binaire de production :
|
||||
|
||||
```bash
|
||||
go build -trimpath -ldflags "-s -w" -o vocat ./cmd/vocat
|
||||
```
|
||||
|
||||
## Automatisation des versions
|
||||
|
||||
Pousser un tag de version déclenche deux workflows GitHub Actions :
|
||||
|
||||
- `release-binaries` construit et publie les binaires `amd64`, `386`, `arm64`, `aarch64` et `armv7` ainsi que `SHA256SUMS`.
|
||||
- `docker` construit et publie une image multi-architecture vers GitHub Container Registry.
|
||||
|
||||
```bash
|
||||
git tag v0.2.0
|
||||
git push origin v0.2.0
|
||||
```
|
||||
|
||||
## Structure du projet
|
||||
|
||||
```text
|
||||
cmd/vocat/ Point d'entrée de l'application et CLI
|
||||
internal/device/ Découverte de modems et contrôle des appareils
|
||||
internal/modem/ Session AT et gestion des réponses
|
||||
internal/server/ API HTTP, notifications et serveur web intégré
|
||||
internal/store/ Persistance SQLite
|
||||
internal/update/ Auto-updater GitHub Release
|
||||
internal/vowifi/ Runtime IKE, EAP-AKA, IMS et WiFi Calling
|
||||
scripts/install.sh Installeur et updater Linux
|
||||
web/src/ Frontend React et TypeScript
|
||||
.github/workflows/ Automatisation des versions binaires et Docker
|
||||
```
|
||||
|
||||
## Utilisation responsable
|
||||
|
||||
Les opérations sur les modems cellulaires et les eSIM peuvent affecter le service de l'abonné, les profils stockés, l'enregistrement réseau et l'état du matériel. Effectuez des sauvegardes, examinez attentivement les actions destructrices et n'utilisez le logiciel que dans des environnements légaux où vous êtes autorisé à exploiter le matériel et les ressources réseau connectés.
|
||||
|
||||
Vocat ne contourne ni l'authentification de l'opérateur, ni la politique réseau, ni la sécurité matérielle, ni les exigences de confiance eSIM. La prise en charge d'une opération signifie que Vocat peut la demander au modem ou à l'eUICC ; l'appareil, le profil, le réseau ou l'opérateur peut toujours la refuser.
|
||||
|
||||
## Contribution
|
||||
|
||||
Les issues et pull requests sont les bienvenues. Gardez des changements ciblés, incluez des tests lorsque c'est possible, évitez de committer des identifiants ou des données d'abonnés, et documentez clairement les comportements spécifiques au matériel.
|
||||
|
||||
Avant de soumettre un changement :
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
cd web && npm run build
|
||||
```
|
||||
|
||||
## Remerciements
|
||||
- [Nodeseek.com](https://www.nodeseek.com) — Une communauté dédiée aux serveurs
|
||||
- [Linux.do](https://linux.do) — Une communauté technologique inspirante
|
||||
- [iniwex5](https://github.com/iniwex5) — Directives de style et de fonctionnalité
|
||||
|
||||
## Offrez-moi un café
|
||||
|
||||
| Réseau | Adresse |
|
||||
| ------- | ------- |
|
||||
| USDT-TRON (TRC20) | `TQQAbboBoU8h5xX4YCA1rqWJU2WjK3seSg` |
|
||||
| USDT-BSC (BEP20) | `0xdbfcd4a462550d6ff06d09cbd89026c6b145d9c4` |
|
||||
| USDT-Polygon | `0xdbfcd4a462550d6ff06d09cbd89026c6b145d9c4` |
|
||||
|
||||
## Licence
|
||||
|
||||
Voir [LICENSE](../LICENSE).
|
||||
|
||||
[](https://meteor-history.com)
|
||||
@@ -0,0 +1,335 @@
|
||||
<p align="center">
|
||||
<img src="../web/public/favicon.svg" width="96" alt="Vocat">
|
||||
</p>
|
||||
|
||||
<h1 align="center">VoCat</h1>
|
||||
|
||||
<p align="center">
|
||||
<img alt="Go" src="https://img.shields.io/badge/Go-1.25-00ADD8?style=flat-square&logo=go&logoColor=white">
|
||||
<img alt="React" src="https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react&logoColor=111111">
|
||||
<img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.8-3178C6?style=flat-square&logo=typescript&logoColor=white">
|
||||
<img alt="Vite" src="https://img.shields.io/badge/Vite-7-646CFF?style=flat-square&logo=vite&logoColor=white">
|
||||
<img alt="Tailwind CSS" src="https://img.shields.io/badge/Tailwind_CSS-3-06B6D4?style=flat-square&logo=tailwindcss&logoColor=white">
|
||||
<img alt="SQLite" src="https://img.shields.io/badge/SQLite-Embedded-003B57?style=flat-square&logo=sqlite&logoColor=white">
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<img alt="Linux" src="https://img.shields.io/badge/Linux-amd64_%7C_386_%7C_arm64_%7C_aarch64_%7C_armv7-FCC624?style=flat-square&logo=linux&logoColor=111111">
|
||||
<img alt="Docker" src="https://img.shields.io/badge/Docker-Multi--Arch-2496ED?style=flat-square&logo=docker&logoColor=white">
|
||||
<img alt="WiFi Calling" src="https://img.shields.io/badge/WiFi_Calling-IMS_SMS-7B1FA2?style=flat-square">
|
||||
<img alt="eSIM" src="https://img.shields.io/badge/eSIM-LPA_%2F_eUICC-009688?style=flat-square">
|
||||
<img alt="Telegram" src="https://img.shields.io/badge/Telegram-Bot-26A5E4?style=flat-square&logo=telegram&logoColor=white">
|
||||
<img alt="GitHub Actions" src="https://img.shields.io/badge/GitHub_Actions-Release-2088FF?style=flat-square&logo=githubactions&logoColor=white">
|
||||
</p>
|
||||
|
||||
[English](../README.md) | [العربية](README.ar.md) | [简体中文](README.zh-CN.md) | [Français](README.fr.md) | **Русский** | [Español](README.es.md)
|
||||
|
||||
Vocat — это веб-панель управления с открытым исходным кодом и набор инженерных инструментов для сотовых модемов Quectel класса EC20/EC25. Она объединяет в одном автономном сервисе обнаружение модемов, состояние радиосвязи в реальном времени, терминалы AT и USSD, SMS, WiFi Calling, управление eSIM, выбор сети, маршрутизацию через прокси, уведомления, журналы аудита и автоматизацию релизов.
|
||||
|
||||
Бэкенд написан на Go, интерфейс построен на React и TypeScript, а производственный фронтенд встроен в бинарный файл Go. Один исполняемый файл содержит веб-приложение и использует SQLite для постоянного хранения состояния.
|
||||
|
||||
<p align="center">
|
||||
<img src="../img/image.png">
|
||||
<img src="../img/image-1.png">
|
||||
</p>
|
||||
|
||||
## Возможности
|
||||
|
||||
| Область | Что предоставляет Vocat |
|
||||
| --- | --- |
|
||||
| Управление устройствами | Автоматическое обнаружение по последовательному порту/USB, поддержка нескольких модемов, понятные имена устройств, обновление обзора в реальном времени, перезапуск модуля, авиарежим и управление режимом USB-сети. |
|
||||
| Радио и сеть | Статус регистрации, оператор, метрики сигнала, RSRP/RSRQ/SINR, режим сети, диапазон, канал, сканирование операторов и автоматический или ручной выбор сети. |
|
||||
| AT и USSD | Интерактивный AT-терминал, история команд, необработанные ответы модема, потоки запуска/продолжения/отмены USSD и понятные сообщения об ошибках модема. |
|
||||
| SMS | Прямая отправка сотовых и IMS SMS, входящая синхронизация, обработка составных сообщений, отчёты о доставке, история диалогов, статус непрочитанных, метки времени и статус доставки каждого сообщения. |
|
||||
| WiFi Calling | Установка туннеля IKEv2/ePDG, аутентификация EAP-AKA, регистрация IMS, IMS SMS, управление переподключением, диагностика состояния и маршрутизация по устройствам. |
|
||||
| eSIM и eUICC | Обнаружение eUICC, EID и производственная информация, метаданные сертификатов, инвентарь нескольких eUICC, список установленных профилей, операции включения/отключения/переключения, а также загрузка, переименование и удаление при поддержке картой. |
|
||||
| Политика карты | Поведение WiFi Calling и авиарежима на основе ICCID с немедленным применением политики. |
|
||||
| Маршрутизация через прокси | Восходящая маршрутизация SOCKS, привязки устройств, правила по странам, проверки доступности TCP и проверки UDP Associate для путей передачи данных WiFi Calling. |
|
||||
| Уведомления | Пересылка новых входящих SMS через Telegram, Bark, электронную почту, Pushplus и подписанные вебхуки. Каждое SMS доставляется как отдельное уведомление. |
|
||||
| Telegram-бот | Статус устройства, список и переключение установленных профилей, управление WiFi Calling и отправка SMS. Чувствительные действия требуют подтверждения администратора. |
|
||||
| Эксплуатация | Аутентификация, защита CSRF, политики доступа, события аудита, журналы в реальном времени, хранение журналов, проверки работоспособности, адаптивная вёрстка, тёмный режим и интерфейс на английском/китайском. |
|
||||
| Дистрибуция | Статические бинарные файлы Linux, скрипт установки systemd, самообновление с проверкой SHA-256, образ Docker, публикация в GHCR и сборки релизов GitHub Actions. |
|
||||
|
||||
## Поддерживаемое оборудование
|
||||
|
||||
Vocat ориентирован на модули Quectel на базе Qualcomm, которые предоставляют совместимые интерфейсы AT, QMI, последовательный порт и USB-сеть, включая:
|
||||
|
||||
- Quectel EC20
|
||||
- Quectel EC25
|
||||
- Семейство Quectel EG25
|
||||
- Совместимые модули EG600 и родственные
|
||||
|
||||
Доступные функции зависят от прошивки модуля, конфигурации USB, возможностей SIM/eSIM, драйверов хоста, радиосети и настроек оператора.
|
||||
|
||||
## Установка
|
||||
|
||||
### Установка в Linux одной командой
|
||||
|
||||
От имени root (включая OpenWrt/Kwrt, где `sudo` обычно отсутствует):
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
От обычного пользователя в дистрибутиве с sudo:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | sudo bash
|
||||
```
|
||||
|
||||
Проверить предварительные требования VoWiFi/XFRM на хосте без установки VoCat:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/MengMengCode/VoCat/master/scripts/install.sh | bash -s -- --check-env
|
||||
```
|
||||
|
||||
Установить конкретную версию:
|
||||
|
||||
```bash
|
||||
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`;
|
||||
- создаёт усиленный сервис systemd с доступом к оборудованию и сети, необходимым Vocat;
|
||||
- хранит конфигурацию времени выполнения в `/etc/vocat/env`;
|
||||
- генерирует случайный начальный пароль администратора при первой установке.
|
||||
|
||||
После установки откройте:
|
||||
|
||||
```text
|
||||
http://<адрес-сервера>:7575
|
||||
```
|
||||
|
||||
### Ручная установка бинарного файла
|
||||
|
||||
Загрузите соответствующий бинарный файл и `SHA256SUMS` из GitHub Releases:
|
||||
|
||||
| Платформа | Файл релиза |
|
||||
| --- | --- |
|
||||
| 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` |
|
||||
|
||||
Проверьте и установите его:
|
||||
|
||||
```bash
|
||||
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`, чтобы
|
||||
процесс сразу запустил сервер; запуск `vocat` без аргументов от имени root
|
||||
в TTY вместо этого открывает интерактивное меню управления. Используйте установку
|
||||
одной командой, когда требуется управляемый сервис systemd и автоматический перезапуск.
|
||||
|
||||
### Docker
|
||||
|
||||
Для хоста Linux, который должен обнаруживать каждый подключённый поддерживаемый модем Quectel и
|
||||
продолжать видеть события горячего подключения USB, запустите Vocat в режиме доступа к оборудованию:
|
||||
|
||||
```bash
|
||||
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. Автоматическое обнаружение
|
||||
в настоящее время определяет поддерживаемые USB-модемы Quectel (USB vendor ID `2c7c`), а не
|
||||
произвольные марки модемов. Монтирование только отдельных узлов с помощью `--device`, таких как
|
||||
`/dev/ttyUSB2` и `/dev/cdc-wdm0`, ограничивает контейнер этими фиксированными узлами и не
|
||||
обеспечивает полное обнаружение нескольких устройств или горячего подключения.
|
||||
|
||||
Образ GHCR публикуется для `linux/amd64` и `linux/arm64`.
|
||||
|
||||
## Конфигурация
|
||||
|
||||
Vocat читает необязательный JSON-файл конфигурации из `VOCAT_CONFIG`, затем применяет переменные окружения `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` | Помечает cookie сессии как безопасные при использовании HTTPS. |
|
||||
| `VOCAT_SHUTDOWN_TIMEOUT` | `10s` | Тайм-аут корректного завершения работы. |
|
||||
| `VOCAT_MAX_REQUEST_BODY_BYTES` | `1048576` | Максимальный размер тела запроса API. |
|
||||
| `VOCAT_REPO` | `MengMengCode/VoCat` | Доверенный репозиторий GitHub, используемый самообновлятором, в формате `owner/name`. |
|
||||
| `GITHUB_TOKEN` | пусто | Необязательный токен GitHub для приватных репозиториев или более высоких лимитов API. |
|
||||
|
||||
Не храните токены Telegram, пароли SMTP, секреты вебхуков, учётные данные SIM или другие приватные данные в репозитории. Настраивайте их через параметры приложения или защищённые файлы окружения.
|
||||
|
||||
## Telegram-бот
|
||||
|
||||
Когда уведомления Telegram включены и настроены Chat ID и Admin ID, бот поддерживает:
|
||||
|
||||
```text
|
||||
/status [устройство]
|
||||
/esim <устройство>
|
||||
/switch <устройство> <iccid>
|
||||
/wfc <устройство> <status|on|off|reconnect>
|
||||
/sms <устройство> <номер> <сообщение>
|
||||
```
|
||||
|
||||
Переключение профилей и отправка SMS используют одноразовые кнопки подтверждения. Бот не предоставляет команды загрузки, удаления или переименования eSIM.
|
||||
|
||||
## Обновление
|
||||
|
||||
Проверить наличие более нового GitHub Release:
|
||||
|
||||
```bash
|
||||
vocat update --check --repo MengMengCode/VoCat
|
||||
```
|
||||
|
||||
Установить последний релиз:
|
||||
|
||||
```bash
|
||||
sudo vocat update --repo MengMengCode/VoCat
|
||||
```
|
||||
|
||||
Обновлятор загружает бинарный файл, соответствующий текущей архитектуре Linux, проверяет его по опубликованному `SHA256SUMS`, атомарно заменяет исполняемый файл и перезапускает сервис systemd `vocat`, когда он доступен.
|
||||
|
||||
Для установок Docker:
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/mengmengcode/vocat:latest
|
||||
```
|
||||
|
||||
Пересоздайте контейнер после загрузки нового образа.
|
||||
|
||||
## Разработка
|
||||
|
||||
Требования:
|
||||
|
||||
- Go 1.25 или новее
|
||||
- Node.js 20 или новее
|
||||
- npm
|
||||
|
||||
Запустить сервер разработки фронтенда:
|
||||
|
||||
```bash
|
||||
cd web
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Собрать встроенный фронтенд и запустить бэкенд:
|
||||
|
||||
```bash
|
||||
cd web
|
||||
npm run build
|
||||
cd ..
|
||||
go run ./cmd/vocat
|
||||
```
|
||||
|
||||
Запустить все тесты:
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
```
|
||||
|
||||
Собрать производственный бинарный файл:
|
||||
|
||||
```bash
|
||||
go build -trimpath -ldflags "-s -w" -o vocat ./cmd/vocat
|
||||
```
|
||||
|
||||
## Автоматизация релизов
|
||||
|
||||
Отправка тега версии запускает два рабочих процесса GitHub Actions:
|
||||
|
||||
- `release-binaries` собирает и публикует бинарные файлы `amd64`, `386`, `arm64`, `aarch64` и `armv7` вместе с `SHA256SUMS`.
|
||||
- `docker` собирает и публикует мультиархитектурный образ в GitHub Container Registry.
|
||||
|
||||
```bash
|
||||
git tag v0.2.0
|
||||
git push origin v0.2.0
|
||||
```
|
||||
|
||||
## Структура проекта
|
||||
|
||||
```text
|
||||
cmd/vocat/ Точка входа приложения и CLI
|
||||
internal/device/ Обнаружение модемов и управление устройствами
|
||||
internal/modem/ Сессия AT и обработка ответов
|
||||
internal/server/ HTTP API, уведомления и встроенный веб-сервер
|
||||
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; устройство, профиль, сеть или оператор всё равно могут её отклонить.
|
||||
|
||||
## Участие в разработке
|
||||
|
||||
Мы приветствуем issues и pull request'ы. Делайте изменения сфокусированными, по возможности добавляйте тесты, избегайте коммита учётных данных или данных абонентов и чётко документируйте поведение, специфичное для оборудования.
|
||||
|
||||
Перед отправкой изменения:
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
cd web && npm run build
|
||||
```
|
||||
|
||||
## Благодарности
|
||||
- [Nodeseek.com](https://www.nodeseek.com) — Сообщество, посвящённое серверам
|
||||
- [Linux.do](https://linux.do) — Вдохновляющее технологическое сообщество
|
||||
- [iniwex5](https://github.com/iniwex5) — Руководства по стилю и функциональности
|
||||
|
||||
## Угостите меня кофе
|
||||
|
||||
| Сеть | Адрес |
|
||||
| ------- | ------- |
|
||||
| USDT-TRON (TRC20) | `TQQAbboBoU8h5xX4YCA1rqWJU2WjK3seSg` |
|
||||
| USDT-BSC (BEP20) | `0xdbfcd4a462550d6ff06d09cbd89026c6b145d9c4` |
|
||||
| USDT-Polygon | `0xdbfcd4a462550d6ff06d09cbd89026c6b145d9c4` |
|
||||
|
||||
## Лицензия
|
||||
|
||||
См. [LICENSE](../LICENSE).
|
||||
|
||||
[](https://meteor-history.com)
|
||||
@@ -22,7 +22,7 @@
|
||||
<img alt="GitHub Actions" src="https://img.shields.io/badge/GitHub_Actions-Release-2088FF?style=flat-square&logo=githubactions&logoColor=white">
|
||||
</p>
|
||||
|
||||
[English](../README.md) | **简体中文**
|
||||
[English](../README.md) | [العربية](README.ar.md) | **简体中文** | [Français](README.fr.md) | [Русский](README.ru.md) | [Español](README.es.md)
|
||||
|
||||
Vocat 是一款面向 Quectel EC20/EC25 系列蜂窝模组的开源 Web 控制面板与工程工具套件。它在一个自包含的服务中整合了模组发现、实时射频状态、AT 与 USSD 终端、短信、WiFi Calling(WiFi 通话)、eSIM 管理、网络选择、代理路由、通知、审计日志以及发布自动化。
|
||||
|
||||
@@ -46,7 +46,7 @@ Vocat 是一款面向 Quectel EC20/EC25 系列蜂窝模组的开源 Web 控制
|
||||
| 卡策略 | 基于 ICCID 的 WiFi Calling 与飞行模式行为,策略即时应用。 |
|
||||
| 代理路由 | 上游 SOCKS 路由、设备绑定、国家规则、TCP 可达性检查以及面向 WiFi Calling 数据路径的 UDP Associate 检查。 |
|
||||
| 通知 | 通过 Telegram、Bark、邮件、Pushplus 以及签名 Webhook 转发新入站短信,每条短信单独推送。 |
|
||||
| Telegram 机器人 | 设备状态、已安装配置文件列表与切换、WiFi Calling 控制、短信发送、定时拨号并自动挂断、通话状态、接听与挂断命令。敏感操作需要管理员确认。 |
|
||||
| Telegram 机器人 | 设备状态、已安装配置文件列表与切换、WiFi Calling 控制以及短信发送。敏感操作需要管理员确认。 |
|
||||
| 运维 | 鉴权、CSRF 防护、访问策略、审计事件、实时日志、日志留存、健康检查、响应式布局、深色模式以及中英文应用界面。 |
|
||||
| 分发 | 静态 Linux 二进制、systemd 安装脚本、带 SHA-256 校验的自更新、Docker 镜像、GHCR 发布以及 GitHub Actions 发布构建。 |
|
||||
|
||||
@@ -188,13 +188,9 @@ Vocat 先从 `VOCAT_CONFIG` 读取可选的 JSON 配置文件,再应用 `VOCAT_*
|
||||
/switch <设备> <iccid>
|
||||
/wfc <设备> <status|on|off|reconnect>
|
||||
/sms <设备> <号码> <内容>
|
||||
/call <设备> <号码> <秒数>
|
||||
/calls <设备>
|
||||
/answer <设备>
|
||||
/hangup <设备>
|
||||
```
|
||||
|
||||
配置文件切换、短信提交与拨号使用一次性确认按钮。定时拨号会执行模组拨号动作,并在 1–600 秒后自动挂断;不会捕获或处理通话音频。机器人不暴露 eSIM 下载、删除或重命名命令。
|
||||
配置文件切换与短信提交使用一次性确认按钮。机器人不暴露 eSIM 下载、删除或重命名命令。
|
||||
|
||||
## 更新
|
||||
|
||||
|
||||
Reference in New Issue
Block a user