groales/bookstack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Page: Solución de Problemas
Pages
Actualización Backup y Restauración Configuración Inicial Home NPM Personalización Solución de Problemas Traefik
Clone
Solución de Problemas
groales edited this page 2025-12-04 15:47:55 +01:00
Table of Contents

Solución de Problemas

Diagnóstico y resolución de problemas comunes en BookStack.

Diagnóstico General

Ver Logs

# Logs de BookStack
docker logs bookstack --tail 100 -f

# Logs de MariaDB
docker logs bookstack-db --tail 50

# Logs del stack completo
docker compose logs -f

Verificar Estado

# Estado de contenedores
docker ps -a | grep bookstack

# Uso de recursos
docker stats bookstack bookstack-db --no-stream

# Redes
docker network inspect bookstack-internal
docker network inspect proxy

Problemas Comunes

BookStack No Inicia

Síntomas: Contenedor se reinicia constantemente

Diagnóstico:

docker logs bookstack | grep -i error
docker logs bookstack | grep -i fatal

Causas comunes:

  1. MariaDB no está listo

    docker logs bookstack-db
docker exec bookstack-db mariadb -u bookstack -p${DB_PASSWORD} -e "SELECT 1"

    Solución: Esperar o reiniciar MariaDB

    docker restart bookstack-db
sleep 15
docker restart bookstack

  2. Permisos incorrectos

    docker exec bookstack ls -la /config

    Solución:

    docker run --rm -v bookstack_config:/config alpine chown -R 1000:1000 /config
docker restart bookstack

  3. APP_URL incorrecta

    Síntomas: Redireccionamientos rotos, CSS no carga

    Verificar:

    docker exec bookstack cat /config/www/.env | grep APP_URL

    Solución: Debe coincidir con tu dominio

    # En docker-compose.yml
APP_URL: https://bookstack.tudominio.com

Error de Conexión a Base de Datos

Síntomas:

SQLSTATE[HY000] [2002] Connection refused
SQLSTATE[HY000] [1045] Access denied

Soluciones:

# Verificar que MariaDB está corriendo
docker ps | grep bookstack-db

# Verificar password en .env
cat .env | grep DB_PASSWORD

# Verificar conexión desde BookStack
docker exec bookstack ping bookstack-db

# Resetear conexión
docker restart bookstack-db
sleep 15
docker restart bookstack

Error 502 Bad Gateway (NPM/Traefik)

Síntomas: Proxy no puede conectar con BookStack

Diagnóstico:

# Verificar que BookStack está corriendo
docker ps | grep bookstack

# Verificar puerto 80
docker exec bookstack netstat -tlnp | grep 80

# Verificar desde proxy
docker exec npm ping bookstack

Soluciones:

  • Verificar que BookStack está en red proxy
  • Verificar que el contenedor se llama bookstack
  • Reiniciar BookStack: docker restart bookstack

Lentitud Extrema

Diagnóstico:

# Ver uso de CPU/RAM
docker stats bookstack bookstack-db

# Ver queries lentas en MariaDB
docker exec bookstack-db mariadb -u bookstack -p${DB_PASSWORD} -e "SHOW FULL PROCESSLIST;"

Soluciones:

  1. Limpiar caché

    docker exec bookstack php artisan cache:clear
docker exec bookstack php artisan config:clear
docker exec bookstack php artisan view:clear
docker restart bookstack

  2. Optimizar MariaDB

    docker exec bookstack-db mariadb-optimize -u bookstack -p${DB_PASSWORD} bookstack

  3. Regenerar índice de búsqueda

    docker exec bookstack php artisan bookstack:regenerate-search

Error LDAP

Síntomas:

LDAP bind failed
Could not connect to LDAP server

Diagnóstico:

# Ver configuración LDAP
docker exec bookstack cat /config/www/.env | grep LDAP

# Probar conexión LDAP
docker exec bookstack ldapsearch -x -H ldap://ldap.example.com -D "cn=bookstack,ou=Services,dc=example,dc=com" -W -b "dc=example,dc=com" "(uid=usuario)"

Soluciones:

  • Verificar LDAP_SERVER, LDAP_DN, LDAP_PASS
  • Verificar firewall permite conexión a puerto 389/636
  • Probar con ldapsearch desde el contenedor

Imágenes No Cargan

Síntomas: Imágenes rotas, error 404

Diagnóstico:

# Ver directorio de uploads
docker exec bookstack ls -la /config/www/uploads

# Ver permisos
docker exec bookstack stat /config/www/uploads

Soluciones:

# Corregir permisos
docker exec bookstack chown -R abc:abc /config/www/uploads
docker exec bookstack chmod -R 755 /config/www/uploads

# Verificar APP_URL correcto
docker exec bookstack cat /config/www/.env | grep APP_URL

Comandos de Emergencia

Reiniciar Todo

docker restart bookstack bookstack-db

Recrear BookStack (Mantiene Datos)

docker stop bookstack
docker rm bookstack
docker compose up -d bookstack

Acceso de Emergencia

# Shell de BookStack
docker exec -it bookstack bash

# Shell de Laravel (artisan tinker)
docker exec -it bookstack php artisan tinker

# Ejemplo: resetear password de admin
>>> $user = \BookStack\Auth\User::where('email', 'admin@admin.com')->first();
>>> $user->password = bcrypt('nuevapassword');
>>> $user->save();

Resetear Password de Admin

docker exec bookstack php artisan bookstack:create-admin --email=admin@admin.com

Limpiar Todo el Caché

docker exec bookstack php artisan optimize:clear
docker restart bookstack

Recuperación de Desastres

BookStack Corrupto - Restaurar desde Backup

# 1. Detener todo
docker stop bookstack bookstack-db

# 2. Restaurar BD
gunzip < /backups/bookstack/bookstack-backup-FECHA.sql.gz | docker exec -i bookstack-db mariadb -u bookstack -p${DB_PASSWORD} bookstack

# 3. Restaurar config
docker run --rm -v bookstack_config:/restore -v /backups/bookstack:/source alpine tar xzf /source/bookstack-config-FECHA.tar.gz -C /restore

# 4. Iniciar todo
docker start bookstack-db
sleep 15
docker start bookstack

MariaDB Corrupto

# Intentar reparar
docker exec bookstack-db mariadb-check -u bookstack -p${DB_PASSWORD} --auto-repair bookstack

# Si falla, restaurar desde backup
docker stop bookstack-db
docker volume rm bookstack_db
docker volume create bookstack_db
docker start bookstack-db
sleep 20
gunzip < bookstack-backup.sql.gz | docker exec -i bookstack-db mariadb -u bookstack -p${DB_PASSWORD} bookstack

Obtener Ayuda

Información del Sistema

# Versión de BookStack
docker exec bookstack php artisan --version

# Versión de PHP
docker exec bookstack php --version

# Versión de MariaDB
docker exec bookstack-db mariadb --version

# Variables de entorno
docker exec bookstack env | grep -E "DB_|APP_|LDAP_"

# Compose usado
docker inspect bookstack | grep -A 20 Labels

Recursos Oficiales

Prevención

Monitorización

# Script de health check
#!/bin/bash
if docker exec bookstack curl -f http://localhost > /dev/null 2>&1; then
    echo "✓ BookStack OK"
else
    echo "✗ BookStack DOWN"
    docker logs bookstack --tail 50
fi

Alertas

Configura alertas en tu sistema de monitorización:

  • CPU > 80%
  • RAM > 90%
  • Disco > 85%
  • BookStack no responde

Próximos Pasos

  1. Backup - Automatiza backups para prevenir desastres
  2. Actualización - Mantén BookStack actualizado
  3. Comunidad - Pregunta si no encuentras solución

BookStack Wiki

🚀 Inicio

📦 Despliegue

⚙️ Configuración

💾 Mantenimiento