innotexBoard/DISKS_TROUBLESHOOTING.md

Guide de Troubleshooting - Disques et Partitions

Problèmes courants et solutions

1. L'endpoint retourne une liste vide

Symptôme: L'API retourne {"devices": [], "total_size": "0 B", ...}

Causes possibles:

• La commande lsblk n'est pas disponible sur le système
• lsblk n'est pas dans le PATH
• Le timeout de 10s a été dépassé

Solutions:

# Vérifier que lsblk est installé
which lsblk
lsblk --json

# Si absent, installer selon votre distribution:
# Ubuntu/Debian:
sudo apt-get install util-linux

# Red Hat/CentOS/Fedora:
sudo yum install util-linux

# Alpine:
apk add util-linux

2. L'interface affiche "Impossible de charger les disques"

Symptôme: Message d'erreur dans la vue frontend

Causes possibles:

• Le backend n'est pas accessible
• L'authentification a expiré
• Problème CORS
• L'endpoint n'existe pas

Solutions:

# Vérifier que le backend fonctionne
curl http://localhost:8000/api/system/stats -H "Authorization: Bearer YOUR_TOKEN"

# Vérifier que l'endpoint est enregistré
# Aller sur http://localhost:8000/docs (Swagger UI)
# L'endpoint /system/disks doit apparaître

# Vérifier les logs du backend
# Chercher les erreurs dans la sortie de FastAPI

3. Les informations d'utilisation sont incorrectes

Symptôme: Le pourcentage d'utilisation ne correspond pas à df

Causes possibles:

• Les points de montage ne sont pas accessibles
• Permission refusée lors de psutil.disk_usage()
• Caches système affectant les calculs

Solutions:

# Comparer avec la commande du système
df -h

# Vérifier les permissions des points de montage
ls -la /mnt
mount | grep -E 'rw|ro'

# Les statistiques psutil incluent l'espace "utilisé" différemment
# de "df" du fait des réserves du système de fichiers

4. Les partitions n'apparaissent pas

Symptôme: Le disque s'affiche mais sans ses partitions

Causes possibles:

• Les partitions ne sont pas montées
• Le disque n'a pas de partition (ex: raw device)
• Pas de point de montage accessible

Solutions:

# Vérifier la structure
lsblk --json

# Monter les partitions si nécessaire
sudo mount /dev/sda1 /mnt/partition1

# L'interface affichera les partitions même sans mountpoint,
# mais sans taux d'utilisation

5. Erreur 401 Unauthorized

Symptôme: La requête est rejetée avec 401

Cause: Token d'authentification invalide ou expiré

Solutions:

# Vous reconnecter dans l'interface
# Ou obtenir un nouveau token:
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin"}'

# Vérifier la validité du token dans les headers:
# Authorization: Bearer <token>

6. Timeout (erreur 504)

Symptôme: Request timeout en récupérant les disques

Cause: lsblk prend plus de 10 secondes

Solutions:

# Augmenter le timeout dans system.py:
# timeout=10 → timeout=30

# Identifier ce qui ralentit lsblk:
time lsblk --json

# Sur les gros systèmes ou systèmes de fichiers réseau lents,
# augmenter le timeout dans system.py peut être nécessaire

7. Les styles CSS ne s'appliquent pas correctement

Symptôme: Les barres de progression n'ont pas de couleur ou de dégradé

Causes possibles:

• Tailwind CSS n'est pas compilé
• Les classes Tailwind ne sont pas générées
• Conflit CSS

Solutions:

cd frontend

# Régénérer les styles Tailwind
npm run build

# Ou en mode développement:
npm run dev

# Vérifier dans DevTools que les classes sont appliquées
# Onglet Elements > Inspect > Vérifier les classes

Logique de débogage

Tester l'endpoint directement

# 1. Se connecter
TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin"}' | jq -r '.access_token')

# 2. Appeler l'endpoint
curl -s -X GET http://localhost:8000/api/system/disks \
  -H "Authorization: Bearer $TOKEN" | jq '.'

# 3. Vérifier les résultats

Vérifier la commande lsblk

# Exécuter la même commande que le backend
lsblk --json --bytes --output NAME,TYPE,SIZE,FSTYPE,MOUNTPOINTS | jq '.'

# Vérifier le format JSON
lsblk --json --bytes --output NAME,TYPE,SIZE,FSTYPE,MOUNTPOINTS | python3 -m json.tool

Vérifier psutil

python3 << 'EOF'
import psutil

# Lister les partitions montées
for part in psutil.disk_partitions():
    print(f"Device: {part.device}, Mountpoint: {part.mountpoint}")
    usage = psutil.disk_usage(part.mountpoint)
    print(f"  Total: {usage.total}, Used: {usage.used}, Free: {usage.free}")
EOF

Configurations avancées

Augmenter le timeout

Fichier: backend/app/services/system.py, ligne ~212

# Avant:
result = subprocess.run([...], timeout=10)

# Après:
result = subprocess.run([...], timeout=30)

Filtrer les disques/partitions

Pour exclure certains disques (exemple: loop devices):

# Dans get_block_devices(), ajouter après la boucle:
if block_device['type'] == 'loop':
    continue  # Ignorer les disques loop

if block_device.get('size', 0) < 1024*1024*100:  # < 100MB
    continue  # Ignorer les petits disques

Changer la fréquence de rafraîchissement

Fichier: frontend/src/views/DisksView.vue, ligne ~162

// Avant:
this.refreshInterval = setInterval(() => {
  this.fetchDisks()
}, 30000)  // 30 secondes

// Après:
this.refreshInterval = setInterval(() => {
  this.fetchDisks()
}, 60000)  // 60 secondes

Logs et débogage

Activer les logs dans le backend

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)

# Dans get_block_devices():
logger.debug(f"lsblk output: {result.stdout}")
logger.debug(f"Devices found: {len(devices)}")

Vérifier les erreurs dans le navigateur

1. Ouvrir la console (F12)
2. Onglet "Network" > Filtrer par "Fetch"
3. Cliquer sur la requête /api/system/disks
4. Regarder la "Response" pour l'erreur complète

Vérifier les logs du backend

# Si FastAPI s'exécute en ligne de commande, les logs s'affichent
# Chercher les messages d'erreur

# Ou rediriger vers un fichier:
python main.py 2>&1 | tee backend.log

Performance

Optimisations possibles

1. Caching: Mettre en cache les résultats pendant 5s pour éviter les appels répétés
2. Pagination: Si beaucoup de disques, paginer la réponse
3. Workers: Utiliser plusieurs workers Gunicorn pour le backend
4. Lazy loading: Charger les partitions à la demande au frontend

Benchmark

Sur un système typique:

• Exécution de lsblk --json: ~50ms
• Récupération d'utilisation (psutil): ~100ms
• Total endpoint: ~150-200ms

Si vous observez des temps plus longs, vérifier:

• Les disques réseau montés
• Les systèmes de fichiers lents
• Le nombre de partitions

Ressources supplémentaires

• lsblk man page: man lsblk
• Documentation psutil: https://psutil.readthedocs.io/
• Tailwind CSS: https://tailwindcss.com/
• Vue 3: https://vuejs.org/
• FastAPI: https://fastapi.tiangolo.com/