592 lines
No EOL
11 KiB
Markdown
592 lines
No EOL
11 KiB
Markdown
# Troubleshooting Guide - Build System Provisioning
|
|
|
|
Guía completa para resolver problemas comunes del sistema de build del poster Provisioning.
|
|
|
|
## 🆘 Problemas Más Comunes
|
|
|
|
### 1. ❌ Build Falla
|
|
|
|
#### Síntomas
|
|
|
|
```rust
|
|
bash
|
|
nu scripts/dev.nu build
|
|
# Error: command not found / syntax error
|
|
```
|
|
|
|
#### Posibles Causas y Soluciones
|
|
|
|
**A. Versión de Nushell Incorrecta**
|
|
|
|
```nushell
|
|
bash
|
|
# Verificar versión
|
|
nu --version
|
|
# Debe ser 0.105.2 o superior
|
|
|
|
# Si es menor, actualizar:
|
|
# - Usando cargo: cargo install nu
|
|
# - Usando homebrew: brew install nushell
|
|
# - Desde releases: https://github.com/nushell/nushell/releases
|
|
```
|
|
|
|
**B. Archivos de Configuración Corruptos**
|
|
|
|
```toml
|
|
bash
|
|
# Verificar configuración
|
|
nu -c "open config/build.config.nu"
|
|
|
|
# Si da error, regenerar configuración:
|
|
cp config/build.config.nu config/build.config.nu.backup
|
|
# Luego recrear manualmente o desde template
|
|
```
|
|
|
|
**C. Dependencias Missing**
|
|
|
|
```rust
|
|
bash
|
|
# Verificar que todos los scripts existen
|
|
ls scripts/
|
|
# Debe mostrar: build.nu, dev.nu, prod.nu, optimize-*.nu, utils.nu
|
|
|
|
# Verificar permisos
|
|
chmod +x scripts/*.nu
|
|
```
|
|
|
|
**D. Working Directory Incorrecto**
|
|
|
|
```rust
|
|
bash
|
|
# Verificar que estás en directorio correcto
|
|
pwd
|
|
# Debe terminar en .../poster/
|
|
|
|
# Verificar estructura
|
|
ls
|
|
# Debe mostrar: src/, scripts/, config/, docs/
|
|
```
|
|
|
|
---
|
|
|
|
### 2. 🌐 Servidor No Inicia
|
|
|
|
#### Síntomas
|
|
|
|
```rust
|
|
bash
|
|
nu scripts/dev.nu --port 3000
|
|
# Error: port in use / server won't start
|
|
```
|
|
|
|
#### Soluciones
|
|
|
|
**A. Puerto Ocupado**
|
|
|
|
```rust
|
|
bash
|
|
# Verificar qué usa el puerto
|
|
lsof -i :3000
|
|
# O en Linux: netstat -tlnp | grep 3000
|
|
|
|
# Matar proceso que usa el puerto
|
|
kill -9 <PID>
|
|
|
|
# O usar puerto diferente
|
|
nu scripts/dev.nu --port 8080
|
|
```
|
|
|
|
**B. Firewall Bloqueando**
|
|
|
|
```rust
|
|
bash
|
|
# macOS: verificar firewall
|
|
sudo pfctl -sr | grep 3000
|
|
|
|
# Linux: verificar iptables
|
|
sudo iptables -L | grep 3000
|
|
|
|
# Permitir puerto temporalmente
|
|
# macOS: System Preferences → Security → Firewall
|
|
# Linux: sudo ufw allow 3000
|
|
```
|
|
|
|
**C. Permisos Insuficientes**
|
|
|
|
```rust
|
|
bash
|
|
# Verificar permisos del directorio dist
|
|
ls -la dist/
|
|
|
|
# Corregir permisos si necesario
|
|
chmod -R 755 dist/
|
|
```
|
|
|
|
**D. Python No Disponible**
|
|
|
|
```rust
|
|
bash
|
|
# El servidor usa Python, verificar instalación
|
|
python3 --version
|
|
# O: python --version
|
|
|
|
# Si no está instalado:
|
|
# macOS: brew install python3
|
|
# Linux: sudo apt install python3
|
|
# Windows: descargar desde python.org
|
|
```
|
|
|
|
---
|
|
|
|
### 3. 📄 Archivos Muy Grandes
|
|
|
|
#### Síntomas
|
|
|
|
```rust
|
|
bash
|
|
nu scripts/prod.nu --analyze
|
|
# Total size: 150KB+ (debería ser ~70KB)
|
|
```
|
|
|
|
#### Diagnóstico y Soluciones
|
|
|
|
**A. Configuración Demasiado Conservadora**
|
|
|
|
```toml
|
|
bash
|
|
# Verificar configuración actual
|
|
grep -A 10 "inline_css_max_size" config/build.config.nu
|
|
grep -A 5 "svg_precision" config/build.config.nu
|
|
|
|
# Hacer más agresiva
|
|
# Editar config/build.config.nu:
|
|
export const config = {
|
|
inline_css_max_size: 5120, # 5KB en lugar de 10KB
|
|
svg_precision: 1, # Menos precisión = menor tamaño
|
|
critical_css_modules: 1, # Menos CSS inline
|
|
css_minify: true, # Asegurar minificación
|
|
svg_optimize: true # Asegurar optimización SVG
|
|
}
|
|
```
|
|
|
|
**B. SVGs Sin Optimizar**
|
|
|
|
```rust
|
|
bash
|
|
# Verificar tamaños SVG
|
|
du -h src/assets/svg/*.svg
|
|
|
|
# Si son muy grandes (>20KB), optimizar manualmente:
|
|
# Instalar SVGO: npm install -g svgo
|
|
# svgo src/assets/svg/symbols.svg
|
|
|
|
# O ajustar precisión en config
|
|
svg_precision: 0 # Mínima precisión
|
|
```
|
|
|
|
**C. CSS Sin Minificar**
|
|
|
|
```rust
|
|
bash
|
|
# Verificar que minificación está habilitada
|
|
grep "css_minify" config/build.config.nu
|
|
|
|
# Verificar resultado
|
|
head -10 dist/assets/css/main.min.css
|
|
# Debe ser una línea compacta, no con espacios
|
|
```
|
|
|
|
**D. Archivos Duplicados**
|
|
|
|
```rust
|
|
bash
|
|
# Verificar que no hay duplicados
|
|
find dist/ -name "*.css" | wc -l
|
|
# Debe ser 1
|
|
|
|
find dist/ -name "*.svg" | wc -l
|
|
# Debe ser 2-3 máximo
|
|
|
|
# Limpiar y rebuild si hay duplicados
|
|
nu scripts/dev.nu clean
|
|
nu scripts/prod.nu
|
|
```
|
|
|
|
---
|
|
|
|
### 4. 🎨 Animaciones Rotas
|
|
|
|
#### Síntomas
|
|
|
|
- Logo no gira
|
|
- Texto sin gradiente
|
|
- Línea progresiva no aparece
|
|
|
|
#### Diagnóstico y Soluciones
|
|
|
|
**A. SVG Animado Movido a Archivo Externo**
|
|
|
|
```rust
|
|
bash
|
|
# Las animaciones CSS/SVG DEBEN estar inline en HTML
|
|
# Verificar que symbols.svg está embebido:
|
|
grep -A 5 "symbol.*logo-black" src/index.html
|
|
|
|
# Si no está, el build movió incorrectamente el SVG
|
|
# Los SVGs animados deben permanecer inline
|
|
```
|
|
|
|
**B. CSS Crítico Muy Limitado**
|
|
|
|
```rust
|
|
bash
|
|
# Animaciones necesitan estar en CSS crítico
|
|
# Editar config/build.config.nu:
|
|
critical_css_modules: 3, # Incluir módulo de animaciones
|
|
|
|
# O ajustar threshold
|
|
inline_css_max_size: 15360, # 15KB para incluir más CSS
|
|
```
|
|
|
|
**C. Minificación Rompió CSS**
|
|
|
|
```rust
|
|
bash
|
|
# Verificar CSS minificado
|
|
head -10 dist/assets/css/main.min.css
|
|
|
|
# Si las animaciones se ven incorrectas, debug:
|
|
# Deshabilitar minificación temporalmente
|
|
# Editar config/build.config.nu:
|
|
css_minify: false
|
|
|
|
# Rebuild y verificar
|
|
nu scripts/dev.nu build
|
|
```
|
|
|
|
**D. JavaScript Deshabilitado/Faltante**
|
|
|
|
```rust
|
|
bash
|
|
# El poster no debería necesitar JS
|
|
# Verificar que no hay dependencias JS accidentales:
|
|
grep -r "script" src/index.html
|
|
grep -r "javascript" src/
|
|
|
|
# Si hay JS, eliminar o hacer opcional
|
|
```
|
|
|
|
---
|
|
|
|
### 5. 🔧 File Watching No Funciona
|
|
|
|
#### Síntomas
|
|
|
|
```rust
|
|
bash
|
|
nu scripts/dev.nu --watch
|
|
# No detecta cambios en archivos
|
|
```
|
|
|
|
#### Soluciones
|
|
|
|
**A. Archivos No Existen**
|
|
|
|
```rust
|
|
bash
|
|
# Verificar que archivos watched existen
|
|
ls src/index.html
|
|
ls src/assets/css/modules/*.css
|
|
ls src/assets/svg/*.svg
|
|
|
|
# Crear archivos faltantes si necesario
|
|
touch src/assets/css/main.css
|
|
```
|
|
|
|
**B. Permisos de Lectura**
|
|
|
|
```rust
|
|
bash
|
|
# Verificar permisos
|
|
ls -la src/
|
|
ls -la src/assets/css/modules/
|
|
|
|
# Corregir permisos
|
|
chmod -R 644 src/
|
|
chmod 755 src/ src/assets/ src/assets/css/ src/assets/css/modules/
|
|
```
|
|
|
|
**C. Demasiados Archivos**
|
|
|
|
```rust
|
|
bash
|
|
# Verificar número de archivos watched
|
|
find src/ -name "*.css" -o -name "*.html" -o -name "*.svg" | wc -l
|
|
|
|
# Si son muchos (>50), puede haber límites del sistema
|
|
# Reducir scope de watching o aumentar límites:
|
|
ulimit -n 1024
|
|
```
|
|
|
|
**D. Editor Locks**
|
|
|
|
```rust
|
|
bash
|
|
# Algunos editores crean locks temporales
|
|
# Verificar archivos temporales
|
|
find src/ -name "*.tmp" -o -name "*~" -o -name "*.swp"
|
|
|
|
# Limpiar archivos temporales
|
|
find src/ -name "*.tmp" -delete
|
|
find src/ -name "*~" -delete
|
|
find src/ -name "*.swp" -delete
|
|
```
|
|
|
|
---
|
|
|
|
### 6. 📦 Deploy Falla
|
|
|
|
#### Síntomas
|
|
|
|
```rust
|
|
bash
|
|
./dist/deploy.sh
|
|
# Permission denied / connection failed
|
|
```
|
|
|
|
#### Soluciones
|
|
|
|
**A. Script No Ejecutable**
|
|
|
|
```rust
|
|
bash
|
|
# Hacer script ejecutable
|
|
chmod +x dist/deploy.sh
|
|
|
|
# Verificar permisos
|
|
ls -la dist/deploy.sh
|
|
```
|
|
|
|
**B. Variables de Entorno No Configuradas**
|
|
|
|
```toml
|
|
bash
|
|
# Verificar variables
|
|
echo $DEPLOY_HOST
|
|
echo $DEPLOY_PATH
|
|
echo $DEPLOY_USER
|
|
|
|
# Configurar si están vacías
|
|
export DEPLOY_HOST="tu-servidor.com"
|
|
export DEPLOY_PATH="/var/www/provisioning-poster"
|
|
export DEPLOY_USER="deploy"
|
|
|
|
# O editar script directamente
|
|
nano dist/deploy.sh
|
|
```
|
|
|
|
**C. SSH Keys/Permisos**
|
|
|
|
```rust
|
|
bash
|
|
# Verificar conexión SSH
|
|
ssh $DEPLOY_USER@$DEPLOY_HOST
|
|
|
|
# Si falla, configurar SSH keys
|
|
ssh-keygen -t rsa
|
|
ssh-copy-id $DEPLOY_USER@$DEPLOY_HOST
|
|
```
|
|
|
|
**D. Directorio Destino No Existe**
|
|
|
|
```rust
|
|
bash
|
|
# Crear directorio en servidor
|
|
ssh $DEPLOY_USER@$DEPLOY_HOST "mkdir -p $DEPLOY_PATH"
|
|
|
|
# Verificar permisos de escritura
|
|
ssh $DEPLOY_USER@$DEPLOY_HOST "touch $DEPLOY_PATH/test.txt && rm $DEPLOY_PATH/test.txt"
|
|
```
|
|
|
|
---
|
|
|
|
## 🔍 Herramientas de Diagnóstico
|
|
|
|
### Verificación Rápida del Sistema
|
|
|
|
```rust
|
|
bash
|
|
#!/usr/bin/env nu
|
|
# diagnosis.nu - Script de diagnóstico rápido
|
|
|
|
# Verificar prerequisitos
|
|
echo "=== DIAGNÓSTICO RÁPIDO ==="
|
|
|
|
echo "1. Nushell version:"
|
|
nu --version
|
|
|
|
echo "2. Directorio actual:"
|
|
pwd
|
|
|
|
echo "3. Estructura de archivos:"
|
|
ls
|
|
|
|
echo "4. Scripts disponibles:"
|
|
ls scripts/
|
|
|
|
echo "5. Configuración:"
|
|
try { open config/build.config.nu | get config } catch { "Error leyendo config" }
|
|
|
|
echo "6. Espacio en disco:"
|
|
df -h .
|
|
|
|
echo "7. Permisos:"
|
|
ls -la scripts/dev.nu
|
|
|
|
echo "=== FIN DIAGNÓSTICO ==="
|
|
```
|
|
|
|
### Logging Verbose para Debug
|
|
|
|
```rust
|
|
bash
|
|
# Debug build completo
|
|
nu scripts/dev.nu build --verbose 2>&1 | tee build-debug.log
|
|
|
|
# Debug servidor
|
|
nu scripts/dev.nu --verbose --port 8080 2>&1 | tee server-debug.log
|
|
|
|
# Analizar logs
|
|
grep -i error build-debug.log
|
|
grep -i warning build-debug.log
|
|
```
|
|
|
|
### Test de Conectividad
|
|
|
|
```rust
|
|
bash
|
|
# Test de puertos
|
|
nc -zv localhost 8080
|
|
nc -zv localhost 3000
|
|
|
|
# Test de archivos servidos
|
|
curl -I http://localhost:8080/index.html
|
|
curl -I http://localhost:8080/assets/css/main.min.css
|
|
```
|
|
|
|
---
|
|
|
|
## 📋 Checklist de Troubleshooting
|
|
|
|
### Antes de Reportar Bug
|
|
|
|
- [ ] Verificar versión Nushell (≥0.105.2)
|
|
- [ ] Confirmar directorio correcto (poster/)
|
|
- [ ] Revisar permisos de archivos
|
|
- [ ] Probar con puerto diferente
|
|
- [ ] Limpiar build cache (`nu scripts/dev.nu clean`)
|
|
- [ ] Revisar logs con --verbose
|
|
- [ ] Verificar espacio en disco suficiente
|
|
|
|
### Información para Bug Report
|
|
|
|
```rust
|
|
bash
|
|
# Recopilar información del sistema
|
|
echo "Nushell: $(nu --version)"
|
|
echo "OS: $(uname -a)"
|
|
echo "PWD: $(pwd)"
|
|
echo "Config: $(open config/build.config.nu | get config)"
|
|
echo "Files: $(ls)"
|
|
echo "Disk space: $(df -h .)"
|
|
```
|
|
|
|
---
|
|
|
|
## 🚨 Problemas Críticos y Recovery
|
|
|
|
### Corrupción de Archivos Fuente
|
|
|
|
```rust
|
|
bash
|
|
# Backup automático (ejecutar regularmente)
|
|
tar -czf backup-$(date +%Y%m%d).tar.gz src/ config/
|
|
|
|
# Recovery desde backup
|
|
tar -xzf backup-YYYYMMDD.tar.gz
|
|
|
|
# O recovery desde git (si está en control de versiones)
|
|
git checkout HEAD -- src/ config/
|
|
```
|
|
|
|
### Build System Completamente Roto
|
|
|
|
```rust
|
|
bash
|
|
# Reset completo del sistema
|
|
rm -rf dist/ node_modules/ .cache/
|
|
|
|
# Verificar integridad de scripts
|
|
ls -la scripts/
|
|
md5sum scripts/*.nu # O shasum en macOS
|
|
|
|
# Re-download scripts si necesario
|
|
# (desde repository o backup)
|
|
```
|
|
|
|
### Recovery de Emergency
|
|
|
|
```rust
|
|
bash
|
|
# Versión mínima de servidor HTTP sin build system
|
|
cd src/
|
|
python3 -m http.server 8080
|
|
|
|
# Acceder a http://localhost:8080
|
|
# Funcionalidad reducida pero poster visible
|
|
```
|
|
|
|
---
|
|
|
|
## 📞 Recursos de Ayuda
|
|
|
|
### Documentación
|
|
|
|
- **Nushell Book**: <https://www.nushell.sh/book/>
|
|
- **Build System README**: ../README.md
|
|
- **Interactive Guide**: docs/howto/interactive-guide.html
|
|
|
|
### Comandos de Ayuda Útiles
|
|
|
|
```rust
|
|
bash
|
|
# Ayuda del sistema
|
|
nu scripts/dev.nu help
|
|
nu scripts/prod.nu help
|
|
|
|
# Ayuda de Nushell
|
|
nu --help
|
|
help commands
|
|
|
|
# Manual de funciones específicas
|
|
help open
|
|
help glob
|
|
help ls
|
|
```
|
|
|
|
### Debugging Avanzado
|
|
|
|
```rust
|
|
bash
|
|
# Modo debug de Nushell
|
|
nu --debug scripts/dev.nu build
|
|
|
|
# Profiling de performance
|
|
time nu scripts/prod.nu
|
|
|
|
# Trace de system calls (Linux/macOS)
|
|
strace -e trace=file nu scripts/dev.nu build # Linux
|
|
dtruss -f nu scripts/dev.nu build # macOS
|
|
```
|
|
|
|
¡Con esta guía deberías poder resolver la mayoría de problemas del sistema de build! |