Problemas frecuentes
Síntomas, causas probables y soluciones de los problemas más habituales al instalar y usar HWD POS.
Antes de empezar
- Lea el resumen final que mostró el instalador. Cada ✗ señala un componente. Un ✗ en
sodium, en Chrome/Chromium o en la zona horaria no impide continuar; uno enpdo_mysql, en MariaDB o en el puerto, sí. - Ejecute el diagnóstico:
sudo bash /var/www/HWDPOS/deploy/check.sh(consulte Diagnóstico con check.sh). - Recuerde que reejecutar el instalador es seguro: no borra datos y vuelve a dejar en su sitio los permisos, la configuración del servidor web, los servicios y el cortafuegos.
Acceso web
Causa probable: el puerto no está escuchando o lo bloquea el cortafuegos.
Compruebe que algo escucha en el puerto y que el servidor web está en marcha:
sudo ss -ltn | grep :80
sudo systemctl status apache2 # o httpd, o nginxSi usa un puerto distinto del 80, sustitúyalo en el comando. Asegúrese también de escribir el puerto en la dirección (por ejemplo, http://192.168.1.50:8080/).
Causa probable: el servidor web no está pasando las peticiones de PHP a PHP-FPM.
Reejecute el instalador; deja la configuración del servidor web correcta.
No hay ningún problema: el sitio está en otro puerto y la comprobación lo lee de la configuración. Si persiste, revise que la directiva Listen del servidor web incluya ese puerto. Consulte Configuración del servidor web.
Base de datos
Causa probable: host equivocado. localhost fuerza la conexión por socket.
Use 127.0.0.1 como host en el paso 2 del asistente de instalación.
Causa probable: contraseña equivocada.
Consulte la contraseña que generó el instalador:
sudo cat /var/www/HWDPOS/deploy/DB-CREDENTIALS.txt
# En un servidor de solo base de datos:
sudo cat /root/HWDPOS-DB-CREDENTIALS.txtSi el archivo no coincide con la base, reejecute el instalador: aplica al usuario de la base la contraseña de la configuración (o del archivo de credenciales), de modo que ambos vuelven a coincidir. Consulte Actualizar y reinstalar.
Causa probable: el cupo de conexiones de la base está lleno.
Ajústelo en Sistema → Capacidad de conexiones o con sudo hwdpanel → opción 19.
Permisos y SELinux
Causa probable: permisos de archivos, o SELinux en AlmaLinux.
-
Ubuntu/Debian: entregue la carpeta al usuario web:
sudo chown -R www-data:www-data /var/www/HWDPOS -
AlmaLinux/Rocky/RHEL: reejecute
install-almalinux.sh, que aplica los contextos de SELinux.
Causa probable: SELinux sin configurar. Ningún mensaje de error menciona SELinux, por eso cuesta detectarlo.
Confírmelo con:
sudo ausearch -m avc -ts recentDespués reejecute install-almalinux.sh. Consulte AlmaLinux.
Activación
Causa probable: el servidor no tiene salida a internet. La activación necesita que el servidor pueda conectarse a internet.
Compruébelo desde el servidor:
curl -sI https://3r.com.pa/pos | head -1Si no hay respuesta, revise el DNS, la puerta de enlace y el cortafuegos del servidor. En AlmaLinux, revise también SELinux (ver arriba).
Impresión
Causa probable: el servicio de impresión no está en marcha.
sudo systemctl status hwpos-print
sudo journalctl -u hwpos-print -fReinstale los servicios de fondo con sudo hwdpanel → opción 16. Consulte Impresión.
Causa probable: no hay un Chrome/Chromium que funcione. En Ubuntu, chromium-browser es solo un paso hacia Snap y sin snapd no arranca: sudo -u www-data chromium-browser --version responde «requires the chromium snap».
-
Ubuntu/Debian (amd64): instale Google Chrome desde su paquete oficial, o use
check.sh→ «Chrome/Chromium»:curl -fsSLO https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb sudo apt-get install -y ./google-chrome-stable_current_amd64.deb -
AlmaLinux:
sudo dnf install -y chromium
Compruebe que se ejecuta como el usuario web:
sudo -u www-data google-chrome-stable --versionSi usa otro navegador, configure su ruta en Ajustes → chrome_path dentro de HWD POS.
Causa probable: la impresora A4 está configurada como térmica.
En Sistema → Impresoras, ponga el papel en «A4 documento».
Scripts de instalación
Mensaje habitual:
Repository '…ondrej/php…' changed its 'Label' value … must be accepted explicitlyLos scripts ya usan --allow-releaseinfo-change. Para resolverlo a mano:
sudo apt-get update --allow-releaseinfo-changeEscriba la ruta sin comillas:
/root/HWDPOS-v1.5.0.zipEl script también intenta eliminar las comillas pegadas por error.
El proceso se detuvo antes de terminar. Lea el mensaje de error que apareció antes y vuelva a ejecutar el script. Los scripts son idempotentes: al reejecutarlos no se reinstalan sin necesidad los componentes que ya funcionan.
Los scripts detectan la versión de PHP-FPM que está realmente en uso y comprueban los paquetes con:
dpkg -s phpX.Y-<extension>La comprobación no depende de la versión de php configurada en el terminal. Asegúrese de que la extensión esté instalada para la versión de PHP-FPM que usa el sitio.
Causa probable: no se pudieron obtener install-workers.sh o hwdpanel.sh (el paquete .zip no los incluye).
Contacte con su proveedor, o copie esos archivos en /var/www/HWDPOS/deploy/ y reejecute el instalador.
Está usando una versión anterior del script, que buscaba el instalador dentro del .zip. Vuelva a descargar bootstrap.sh; la versión actual descarga el instalador del servidor de distribución.
Está usando una versión anterior del script (llamaba a apt-get, que ahí no existe). Vuelva a descargarlo:
curl -fsSL https://3r.com.pa/hwdpos_inst/bootstrap.sh | sudo bashSi el instalador de esta familia sigue sin estar disponible, indique su ubicación con INSTALLER_URL=… o copie install-almalinux.sh al servidor y ejecútelo directamente.
Versión anterior: consultaba los paquetes con dpkg, que ahí no existe. Vuelva a descargarlo; la versión actual consulta con rpm y repara ejecutando install-almalinux.sh.
¿Sigue sin resolverse?
Consulte las preguntas frecuentes o contacte con su proveedor de HWD POS enviando el resumen final del instalador y la salida de CHECK_ONLY=1 bash /var/www/HWDPOS/deploy/check.sh.