VoCat/docs/README.ru.md

VoCat

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

Vocat — это веб-панель управления с открытым исходным кодом и набор инженерных инструментов для сотовых модемов Quectel класса EC20/EC25. Она объединяет в одном автономном сервисе обнаружение модемов, состояние радиосвязи в реальном времени, терминалы AT и USSD, SMS, WiFi Calling, управление eSIM, выбор сети, маршрутизацию через прокси, уведомления, журналы аудита и автоматизацию релизов.

Бэкенд написан на Go, интерфейс построен на React и TypeScript, а производственный фронтенд встроен в бинарный файл Go. Один исполняемый файл содержит веб-приложение и использует SQLite для постоянного хранения состояния.

Возможности

Область	Что предоставляет 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 обычно отсутствует):

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

От обычного пользователя в дистрибутиве с 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;
• создаёт усиленный сервис systemd с доступом к оборудованию и сети, необходимым Vocat;
• хранит конфигурацию времени выполнения в /etc/vocat/env;
• генерирует случайный начальный пароль администратора при первой установке.

После установки откройте:

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

Проверьте и установите его:

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 в режиме доступа к оборудованию:

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, бот поддерживает:

/status [устройство]
/esim <устройство>
/switch <устройство> <iccid>
/wfc <устройство> <status|on|off|reconnect>
/sms <устройство> <номер> <сообщение>

Переключение профилей и отправка SMS используют одноразовые кнопки подтверждения. Бот не предоставляет команды загрузки, удаления или переименования eSIM.

Обновление

Проверить наличие более нового GitHub Release:

vocat update --check --repo MengMengCode/VoCat

Установить последний релиз:

sudo vocat update --repo MengMengCode/VoCat

Обновлятор загружает бинарный файл, соответствующий текущей архитектуре Linux, проверяет его по опубликованному SHA256SUMS, атомарно заменяет исполняемый файл и перезапускает сервис systemd vocat, когда он доступен.

Для установок 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, уведомления и встроенный веб-сервер
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'ы. Делайте изменения сфокусированными, по возможности добавляйте тесты, избегайте коммита учётных данных или данных абонентов и чётко документируйте поведение, специфичное для оборудования.

Перед отправкой изменения:

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

Благодарности

• Nodeseek.com — Сообщество, посвящённое серверам
• Linux.do — Вдохновляющее технологическое сообщество
• iniwex5 — Руководства по стилю и функциональности

Угостите меня кофе

Сеть	Адрес
USDT-TRON (TRC20)	TQQAbboBoU8h5xX4YCA1rqWJU2WjK3seSg
USDT-BSC (BEP20)	0xdbfcd4a462550d6ff06d09cbd89026c6b145d9c4
USDT-Polygon	0xdbfcd4a462550d6ff06d09cbd89026c6b145d9c4

Лицензия

См. LICENSE.