AngelSQL v2.0 Enterprise Architecture

Manual de Configuración y Operación

Guía técnica completa para configurar AngelSQLServer como Servidor Central (Master), enlazar Nodos Clientes remotos y publicar aplicaciones web mediante cuentas AngelSQL.

1. ¿Qué es AngelSQLServer?

AngelSQLServer es una plataforma de software todo-en-uno que unifica cuatro componentes esenciales en un único proceso ejecutable (.NET 10):

  • Servidor Web & Proxy Inverso HTTP/HTTPS: Despacha contenido estático, APIs y enruta dinámicamente a instancias aisladas.
  • Motor AngelDB: Base de datos relacional basada en SQLite con soporte nativo para particionamiento dinámico por rangos de fecha y consultas JSON.
  • Script Engine C# (.csx): Ejecución de backend en caliente con acceso total al motor y librerías sin recompilar.
  • AngelRemote / AngelProxy Clúster: Red privada con túneles TLS bidireccionales para enlazar sucursales a través de Internet sin abrir puertos en el módem.
┌─────────────────────────────────────────────────────────────────────────┐ │ ARQUITECTURA DE ENRUTAMIENTO ANGELSQL │ │ │ │ Navegador Web / Celular Sucursal Remota (Caja POS) │ │ (https://angelsql.net/App) (cluster_client.json) │ │ │ │ │ │ ▼ (HTTPS 443) ▼ (Túnel TCP TLS 4429) │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ ANGELSQL SERVER (Master Hub) │ │ │ │ │ │ │ │ [ Enrutador Universal: /App/ ──► Proxy Interno Kestrel ] │ │ │ │ [ Clúster Server: ──► Túnel Bidireccional hacia Sucursal ] │ │ │ │ [ AngelDB: Base de Datos Global + Script Engine C# (.csx) ] │ │ │ └─────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘

2. Modos de Operación

Modo Servidor Master

Opera en un servidor o VPS con acceso a Internet. Es el receptor de nombres de dominio y certificados SSL.

  • Escucha peticiones en puertos 80 y 443.
  • Aloja y administra aplicaciones locales independientes.
  • Recibe túneles seguros de clientes remotos en el puerto 4429.

Modo Nodo Cliente (Sucursal)

Opera dentro de tiendas, farmacias, cajas de cobro o servidores locales con conexión a Internet estándar.

  • Cero configuración de router: No requiere IP fija ni abrir puertos.
  • Abre una conexión TCP TLS saliente hacia el Master.
  • Responde consultas de ventas, inventarios y archivos en tiempo real.

3. Configuración del Servidor Master

3.1 Puertos y Servicios Principales

Puerto Protocolo Uso y Descripción
80 HTTP Redirección a HTTPS y validación de certificados Let's Encrypt
443 HTTPS Tráfico Web Cifrado para todas las aplicaciones y dominios
4428 HTTP / Local Panel de Administración y Control Maestro de AngelSQL
4429 TCP + TLS Concentrador de Clúster para Nodos Clientes y Sucursales
Captura: Consola de Inicio de AngelSQLServer
Muestra el arranque del servidor, certificados cargados y los puertos 80, 443, 4428 y 4429 escuchando.
images/manual_servidor_startup.png

3.2 Registro de Aplicaciones Locales

Cada aplicación web (por ejemplo, ContabilidadMyB o mybusinesspos) se registra indicando su directorio físico. El servidor asigna un puerto Kestrel local dinámico para aislarla por completo.

Registro vía API o Consola 
// Comando interno para registrar una aplicación
AddApp("ContabilidadMyB", "D:/DesarrolloAngelSQL/ContabilidadMyB");
Captura: Panel de Administración de Aplicaciones
Vista de la lista de aplicaciones registradas, estado de ejecución y URLs locales asignadas.
images/manual_admin_apps.png

4. Enrutamiento Inteligente y Dominios

El enrutador universal centralizado de AngelSQL resuelve las solicitudes automáticamente bajo las siguientes reglas:

1

Ruta Amigable Directa

Al acceder a https://angelsql.net/ContabilidadMyB/, el servidor identifica que el primer segmento corresponde a la app local, remueve el prefijo y entrega el contenido de wwwroot/.

2

Redirección Canónica Automática

Si el usuario escribe https://angelsql.net/ContabilidadMyB (sin barra final), el servidor emite una redirección HTTP 302 hacia /ContabilidadMyB/ para asegurar que los scripts y hojas de estilo relativas (js/main.js, css/styles.css) carguen correctamente.

3

Resolución por Encabezado Referer

Si una página realiza peticiones o llamadas a servicios (ej. /API o AngelPOST), el servidor examina el encabezado Referer del navegador para identificar la app de origen y redirigir el tráfico automáticamente.

Captura: Aplicación Cargada en el Navegador Web
Muestra la pantalla de inicio de sesión de ContabilidadMyB cargada desde https://angelsql.net/ContabilidadMyB/
images/manual_app_browser.png

5. Configuración de Nodos Cliente (Sucursales)

Para enlazar una sucursal remota al Master sin requerir apertura de puertos en el módem, se crea el archivo cluster_client.json en la máquina cliente:

cluster_client.json 
{
  "MasterHost": "angelsql.net",
  "MasterPort": 4429,
  "TenantId": "e1b2c3d4-0000-0000-0000-000000000001",
  "ClientId": "sucursal_norte",
  "SecretKey": "TuClaveCriptograficaSegura123!",
  "UseTls": true
}
Conexión Instantánea Al iniciar el servicio, el cliente establecerá un túnel TCP cifrado con TLS hacia el Master. Toda consulta enviada a https://angelsql.net/--sucursal_norte/ será canalizada en tiempo real a la máquina de la sucursal.
Captura: Consola del Cliente Conectado al Master
Muestra la confirmación del handshake TLS y la sesión activa en el concentrador de clúster.
images/manual_cluster_client.png

6. Exposición a Internet y Cuentas AngelSQL

6.1 Arquitectura Frontend Sin Configuración (Zero-Config)

En cada aplicación web, las llamadas al backend se resuelven mediante rutas relativas nativas en main.js:

Resolución Nativa en main.js 
const url = new URL('AngelPOST', document.baseURI || window.location.href).href;
Portabilidad Absoluta No se requiere ningún script puente ni archivo intermedio. Si la página se abre en localhost, en la red local (192.168.x.x) o en la nube (angelsql.net), el navegador y el enrutador resuelven la ruta de forma totalmente transparente.

6.2 Dominios Personalizados / Parqueados

AngelSQL permite asociar dominios propios (ej. app.minegocio.com) configurando el certificado SSL correspondiente en el panel. El servidor reconocerá el dominio entrante y servirá la aplicación designada como predeterminada.

7. Tabla Comparativa

Característica Servidor Web Tradicional AngelSQL Server
Arquitectura Múltiples componentes (IIS/Nginx + Node/DotNet + SQL + VPN) Proceso Único todo-en-uno (.NET 10 nativo)
Conexión de Sucursales Requiere IP fija, configuración de módem y VPN Túnel TLS saliente automático (cero config)
Actualizaciones de Backend Compilación, publicación y reinicio de servicios Scripts .csx en caliente (guardar y listo)
Proxy Inverso Configuración manual compleja en archivos de texto Enrutador inteligente integrado por URL y Referer

8. Guía Rápida de Diagnóstico (Troubleshooting)

Error 404 en archivos estáticos (.js, .css, imágenes)

Verifica que el nombre en la URL coincida con el ID registrado en el Master y que el directorio wwwroot de la app contenga los archivos.

Cliente Remoto no logra conectar

Comprueba que el puerto 4429 esté permitido en el firewall del servidor Master y que el TenantId y SecretKey sean idénticos en ambos extremos.

Certificados SSL para dominios públicos

Asegúrate de que los puertos 80 y 443 apunten a la IP del Servidor Master para permitir la renovación automática con Let's Encrypt.