VoCat/docs/README.es.md

VoCat

English | العربية | 简体中文 | 繁體中文 | Français | Русский | 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.

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):

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

Desde un usuario normal en una distribución con sudo:

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:

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

Instalar una versión específica:

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:

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:

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:

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:

/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:

vocat update --check --repo MengMengCode/VoCat

Instalar la última versión:

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:

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:

cd web
npm install
npm run dev

Compilar el frontend incrustado e iniciar el backend:

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

Ejecutar todas las pruebas:

go test ./...

Compilar un binario de producción:

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.

git tag v0.2.0
git push origin v0.2.0

Estructura del proyecto

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:

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

Agradecimientos

• Nodeseek.com — Una comunidad dedicada a los servidores
• Linux.do — Una comunidad tecnológica inspiradora
• 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.