Initial commit

DISKS_TROUBLESHOOTING.md

@@ -0,0 +1,299 @@
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+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
+
+```python
+# Avant:
+result = subprocess.run([...], timeout=10)
+
+# Après:
+result = subprocess.run([...], timeout=30)
+```
+
+### Filtrer les disques/partitions
+
+Pour exclure certains disques (exemple: loop devices):
+
+```python
+# 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
+
+```javascript
+// 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
+
+```python
+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
+
+```bash
+# 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/