a2host/docs/06-user-guides/admin-manual.md

13 KiB

Manual de Usuario y Administración

Sistema de Gestión Dinámica de Subdominios Apache2 (a2host)

Público Objetivo: Administradores de Sistemas, Ingenieros DevOps y Operadores Técnicos
Proyecto: a2host — Lightweight Subdomain Orchestrator
Versión de la Aplicación: 1.0.0
Fecha: 19 de Noviembre de 2026
Autor: Documentación Técnica & Experiencia de Usuario (@docs)


Registro de Revisiones

Versión Fecha Autor Justificación y Cambios
1.0.0 2026-11-19 Redactor Técnico (@docs) Manual operativo integral: Flujos de autenticación, creación Modo A y B, gestión de carpetas, resolución de errores de sintaxis y diagnóstico.

1. Introducción y Acceso al Panel

a2host es la consola centralizada para aprovisionar y gestionar subdominios bajo elingejose.com. Permite administrar hosts virtuales de Apache2 sin necesidad de acceder a la consola SSH para tareas rutinarias, garantizando la estabilidad del servidor mediante validaciones automáticas.

1.1 Acceso al Sistema

  1. Abra su navegador web e ingrese a la URL del panel:
    http://panel.elingejose.com
    
    (o https://panel.elingejose.com si SSL está activo).
  2. Ingrese las credenciales administrativas asignadas en la instalación (configuradas en el archivo .env).
  3. Presione Iniciar Sesión. La sesión se mantendrá activa mediante una cookie criptográfica segura. Si permanece inactivo por más de 8 horas, el sistema solicitará autenticarse nuevamente por seguridad.
flowchart LR
    A["Pantalla de Login<br/>/login.html"] -->|"Usuario & Contraseña"| B{"Verificación scrypt"}
    B -- "Válido" --> C["Cookie HttpOnly Emitida<br/>Acceso al Dashboard"]
    B -- "Fallido (>5 intentos)" --> D["Bloqueo Temporal IP<br/>(15 minutos)"]

2. Descripción General del Dashboard

Al ingresar al panel, se presenta la consola principal dividida en dos zonas estratégicas: Telemetría de Recursos y Gestión de Subdominios.

+-----------------------------------------------------------------------------------------------------+
| a2host | Panel de Control                      [RAM: 61.6% | RSS: 30MB / 120MB]  (Usuario: admin) [Salir] |
+-----------------------------------------------------------------------------------------------------+
| [ + Crear Nuevo Subdominio ]   [ Explorador /var/www ]   [ Gestión Usuarios ]                       |
+-----------------------------------------------------------------------------------------------------+
| SUBDOMINIOS ACTIVOS                                                                                 |
|-----------------------------------------------------------------------------------------------------|
| Subdominio            | Tipo           | Destino                | Estado        | Acciones          |
|-----------------------|----------------|------------------------|---------------|-------------------|
| git.elingejose.com    | Proxy Inverso  | http://127.0.0.1:3000   | [ PROTEGIDO ] | [ Inmutable ]     |
| blog.elingejose.com   | Carpeta Web    | /var/www/blog          | [ HABILITADO] | [Pausar] [Borrar] |
| api.elingejose.com    | Proxy Inverso  | http://127.0.0.1:5000   | [ PAUSADO   ] | [Activar][Borrar] |
+-----------------------------------------------------------------------------------------------------+

2.1 Tarjetas de Telemetría (Monitoreo de Recursos)

En la cabecera superior se visualizan en tiempo real los indicadores clave del servidor VPS:

  • Memoria RAM del Servidor: Muestra la memoria física total (1 GB) y el porcentaje utilizado por el sistema operativo, MySQL y Apache.
  • Memoria del Proceso (Node.js): Informa el consumo de memoria RSS de a2host (típicamente entre 25 MB y 35 MB) y el techo de seguridad establecido en PM2 (120 MB).
  • Estado de Apache2: Indicador luminoso en verde (Activo / Running) o rojo (Alerta de Servicio).

3. Creación de Subdominios Paso a Paso

Para registrar un nuevo subdominio, haga clic en el botón + Crear Nuevo Subdominio. Se desplegará una ventana modal con dos modalidades de configuración:

3.1 Modo A — Proyecto Web Estático / PHP (Carpeta Física)

Utilice esta modalidad para sitios HTML, CSS, JavaScript estáticos, aplicaciones web empaquetadas (React/Vue compilados en archivos planos) o sitios PHP.

flowchart TD
    FormA["Formulario Modo A:<br/>Nombre: 'portafolio'"] --> SubmitA["Clic en 'Crear Subdominio'"]
    SubmitA --> BackendA["Backend a2host"]
    
    BackendA --> Step1["1. Crea carpeta /var/www/portafolio"]
    Step1 --> Step2["2. Genera index.html de bienvenida"]
    Step2 --> Step3["3. Asigna permisos SGID 2775 (ggc:www-data)"]
    Step3 --> Step4["4. Escribe /etc/apache2/sites-available/portafolio.conf"]
    Step4 --> Step5["5. Ejecuta 'sudo a2ensite' y 'apache2ctl configtest'"]
    Step5 --> Step6["6. Recarga Apache sin interrupción ('systemctl reload')"]

Instrucciones para el Operador:

  1. Seleccione la pestaña "Carpeta Web (Estático / PHP)".
  2. Nombre del Subdominio: Escriba el prefijo deseado (ejemplo: portafolio).
    Nota: Solo se permiten caracteres alfanuméricos en minúsculas y guiones (a-z, 0-9, -). El dominio resultante será portafolio.elingejose.com.
  3. Haga clic en "Crear Subdominio".
  4. Despliegue de Archivos: Una vez creado, el directorio /var/www/portafolio ya se encuentra configurado con permisos SGID 2775 y propietario ggc:www-data.
    • Puede conectarse por SFTP o SSH con el usuario ggc y subir sus archivos directamente a /var/www/portafolio.
    • Puede inicializar un repositorio Git dentro de la carpeta sin utilizar sudo. Apache podrá leer automáticamente los nuevos ficheros creados.

3.2 Modo B — Proxy Inverso por Puerto (Node.js, Python, Go, Docker)

Utilice esta modalidad para redirigir peticiones públicas hacia servicios web, APIs o microservicios que ya se encuentren escuchando en un puerto TCP interno de la máquina.

flowchart TD
    FormB["Formulario Modo B:<br/>Nombre: 'bot-api'<br/>Puerto: 8080"] --> SubmitB["Clic en 'Crear Proxy'"]
    SubmitB --> BackendB["Backend a2host"]
    
    BackendB --> CheckPort{"¿Puerto Válido y Libre?<br/>(1024-65535, No Reservado)"}
    CheckPort -- "No (ej. 3000 o 22)" --> ErrorPort["Error: Puerto Reservado por el Sistema"]
    CheckPort -- "Sí" --> StepB1["1. Escribe sites-available/bot-api.conf<br/>con ProxyPass a 127.0.0.1:8080"]
    StepB1 --> StepB2["2. Ejecuta 'sudo a2ensite' y 'apache2ctl configtest'"]
    StepB2 --> StepB3["3. Recarga Apache ('systemctl reload')"]

Instrucciones para el Operador:

  1. Seleccione la pestaña "Proxy Inverso por Puerto".
  2. Nombre del Subdominio: Escriba el nombre deseado (ejemplo: bot-api).
  3. Puerto de Destino: Ingrese el puerto TCP donde corre su servicio interno (ejemplo: 8080).
    • El puerto debe encontrarse en el rango de 1024 a 65535.
    • Puertos Bloqueados por Seguridad: El sistema impedirá asignar puertos reservados del sistema como 22 (SSH), 80 (HTTP), 443 (HTTPS), 3000 (Gitea), 3005 (Panel de Control), 3306 (MySQL) o 5432 (PostgreSQL).
  4. Haga clic en "Crear Proxy".
  5. Las peticiones hacia http://bot-api.elingejose.com se redirigirán instantáneamente de forma transparente hacia http://127.0.0.1:8080.

4. Gestión de Subdominios Existentes

Para cada subdominio listado en la tabla, el operador dispone de acciones rápidas:

4.1 Pausar / Desactivar un Subdominio (Toggle)

  • Si requiere suspender temporalmente un sitio web sin borrar sus archivos ni su configuración, presione el botón Pausar (icono de pausa o alternador).
  • Acción del sistema: Ejecuta sudo a2dissite <subdominio>.conf y recarga Apache.
  • El archivo .conf y la carpeta /var/www/<subdominio> se mantienen intactos.
  • Cuando desee reactivarlo, haga clic en Activar.

4.2 Eliminación Segura de un Subdominio

Para eliminar permanentemente un VirtualHost:

  1. Haga clic en el botón de eliminación (icono de papelera) en la fila del subdominio.
  2. Se abrirá un diálogo de confirmación con una casilla crítica:
    • [ ] Conservar archivos en /var/www/<subdominio> (Predeterminado): Deshabilita el VirtualHost y elimina el archivo .conf en Apache, pero los archivos de su aplicación se conservan intactos en el disco.
    • [x] Eliminar también la carpeta y todos los archivos en disco: Si marca esta casilla, el sistema purgará irreversiblemente el directorio web.
  3. Confirme la acción presionando "Eliminar Definitivamente".

Protección Inmutable: Los sitios críticos como git.elingejose.com (git.conf) y la configuración base de Apache (000-default.conf) están bloqueados por hardware/software. No mostrarán botones de acción ni podrán ser alterados mediante el panel.


5. Explorador de Carpetas Web (/var/www/)

El módulo Explorador de Carpetas permite auditar el estado del almacenamiento web:

  1. Haga clic en "Explorador /var/www" en el menú superior.
  2. Se listarán todas las carpetas aprovisionadas en el sistema de archivos con:
    • Nombre de la carpeta.
    • Permisos UNIX actuales (debe reflejar 2775).
    • Propietario y grupo (ggc:www-data).
    • Peso total en disco y número de archivos.
  3. Al hacer clic sobre una carpeta, puede inspeccionar la lista de archivos contenidos, sus tamaños individuales y sus fechas de modificación.

6. Gestión de Usuarios y Operadores

Los usuarios con rol admin disponen del módulo de administración de accesos:

  1. Haga clic en "Gestión Usuarios".
  2. Crear Nuevo Operador: Ingrese nombre de usuario, nombre completo, contraseña y seleccione el rol:
    • Administrador (admin): Control total del panel y usuarios.
    • Operador (operator): Puede crear y gestionar subdominios, pero no puede purgar directorios críticos ni crear otros usuarios.
  3. Cambiar Contraseña: Seleccione un usuario de la lista e introduzca la nueva clave. Se regenerará automáticamente el hash scrypt.

7. Diagnóstico y Resolución de Problemas (Troubleshooting)

7.1 Comprensión del "Rollback Atómico"

Si al crear un subdominio o modificar una directiva la pantalla muestra un mensaje de error en color rojo con un código 422 Unprocessable Entity:

[ALERTA DE SINTAXIS APACHE]
AH00526: Syntax error on line 4 of /etc/apache2/sites-available/nuevo-sitio.conf:
Invalid command 'ProxyPassInvalid', perhaps misspelled or defined by a module not included.
-> Transacción abortada. Rollback ejecutado: El sitio fue deshabilitado y removido. Apache sigue funcionando con normalidad.

¿Qué ocurrió? El sistema ejecutó una prueba preventiva con apache2ctl configtest. Como Apache detectó un error en la configuración, el mecanismo de protección de a2host canceló la operación, eliminó el archivo defectuoso y no recargó Apache. Gracias a esto, los demás sitios en producción (como Gitea y el propio panel) continuaron operando sin interrupción.

7.2 Casos Comunes de Error y Soluciones

Síntoma / Mensaje Causa Raíz Solución Recomendada
Puerto 3000 reservado Intento de crear un proxy apuntando al puerto de Gitea u otro servicio interno protegido. Seleccione un puerto disponible entre 1024 y 65535 no asignado a servicios del sistema.
El subdominio ya existe Ya existe un archivo .conf con el mismo nombre en sites-available. Utilice un nombre diferente o elimine previamente el subdominio antiguo si ya no está en uso.
Error 403: Sitio Protegido Intento de deshabilitar o eliminar git.conf o 000-default.conf. Esta operación está prohibida por diseño para evitar la caída de la infraestructura base.
Al ingresar al subdominio público responde error 502 Bad Gateway En Modo B (Proxy), el servicio interno (Node/Python) no está corriendo en el puerto indicado. Conéctese por SSH y verifique que su aplicación esté activa en el puerto: pm2 status o netstat -tlpn.
En Modo A responde 403 Forbidden al entrar en la web La carpeta carece de un archivo index.html o index.php y las directivas prohíben listar directorios. Suba un archivo index.html a la carpeta /var/www/<subdominio>/.

7.3 Comandos Útiles de Diagnóstico en el Servidor (Vía SSH)

En caso de requerir soporte directo en la consola del VPS:

# Conectarse al servidor mediante el alias configurado
ssh vps-jose

# Ver logs del panel a2host en tiempo real
pm2 logs a2host

# Comprobar sintaxis manual de Apache
sudo apache2ctl configtest

# Ver los últimos errores globales del servidor Apache
sudo tail -n 30 /var/log/apache2/error.log