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**:
```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/