guides/serveur/diagnostic-espace-disque.md

# Guide de diagnostic d'espace disque Linux

Guide complet pour identifier et résoudre les problèmes d'espace disque sur un serveur Linux.

## 1. Vue d'ensemble : quel disque est plein ?

```bash
df -h
```

**Cherche :**
- La ligne `/dev/sda1` (ou `/dev/nvme0n1p1`, `/dev/vda1`) montée sur `/`
- Si `Use%` > 80% → Problème

**Exemple :**
```
/dev/sda1    59G   57G   171M  100%  /   ← PROBLÈME ICI
```

**Comprendre la sortie :**

| Colonne | Signification |
|---------|---------------|
| Filesystem | Nom du disque/partition |
| Size | Capacité totale |
| Used | Espace utilisé |
| Avail | Espace disponible |
| Use% | Pourcentage d'utilisation |
| Mounted on | Point de montage (où le disque est accessible) |

---

## 2. Niveau 1 : Identifier les gros dossiers à la racine

```bash
sudo du -sh /* 2>/dev/null | sort -h
```

**Explication :**
- `du` : **D**isk **U**sage (utilisation disque)
- `-s` : **S**ummary (résumé total)
- `-h` : **H**uman-readable (Go, Mo au lieu d'octets)
- `/*` : Tous les dossiers à la racine
- `2>/dev/null` : Masque les erreurs de permission
- `sort -h` : Trie par taille humaine (comprend que 10G > 2G)

**Résultat typique :**
```
4.0K    /mnt
128M    /boot
2.1G    /usr
15G     /var
40G     /home   ← SUSPECT
```

---

## 3. Niveau 2 : Descendre dans le dossier suspect

**Si `/home` est gros :**

```bash
sudo du -sh /home/* | sort -h
```

**Si `/var` est gros :**

```bash
sudo du -sh /var/* | sort -h
```

**Continue à descendre dans l'arborescence :**

```bash
# Exemple : /var/lib est gros
sudo du -sh /var/lib/* | sort -h

# Puis /var/lib/docker est gros
sudo du -sh /var/lib/docker/* | sort -h
```

**Astuce :** Garde seulement les 10 plus gros avec `tail -10` :

```bash
sudo du -sh /var/* | sort -h | tail -10
```

---

## 4. Trouver les plus gros fichiers (top 20)

```bash
sudo find /home -type f -size +100M -exec ls -lh {} \; 2>/dev/null | sort -k5 -h | tail -20
```

**Explication :**
- `find /home` : Cherche dans /home (change le path selon besoin)
- `-type f` : Seulement les fichiers (pas les dossiers)
- `-size +100M` : Fichiers de plus de 100 MB
- `-exec ls -lh {} \;` : Affiche les détails de chaque fichier trouvé
- `sort -k5 -h` : Trie par la 5ème colonne (taille) en mode humain
- `tail -20` : Garde les 20 derniers (= les plus gros)

**Variantes :**

| Taille | Option |
|--------|--------|
| Plus de 100 MB | `-size +100M` |
| Plus de 500 MB | `-size +500M` |
| Plus de 1 GB | `-size +1G` |
| Plus de 10 GB | `-size +10G` |

---

## 5. Cas particuliers

### A. Fichiers supprimés mais encore ouverts (fantômes)

Les fichiers supprimés mais encore ouverts par un processus continuent d'occuper l'espace disque jusqu'à ce que le processus se termine.

**Identifier les fichiers fantômes :**

```bash
sudo lsof +L1 | grep deleted
```

**Calculer l'espace total occupé :**

```bash
sudo lsof +L1 | grep deleted | awk '{sum+=$7} END {print "Space: " sum/1024/1024/1024 " GB"}'
```

**Solution :** Redémarre le service qui garde les fichiers ouverts :

```bash
# Identifier le processus
sudo lsof +L1 | grep deleted

# Redémarrer le service (exemple avec Docker)
docker restart container_name

# Ou redémarrer un service système
sudo systemctl restart service_name
```

### B. Logs système volumineux

Les logs système peuvent grossir indéfiniment et remplir le disque.

**Vérifier la taille des logs :**

```bash
sudo journalctl --disk-usage
```

**Nettoyer les logs (garder seulement 500M) :**

```bash
sudo journalctl --vacuum-size=500M
```

**Nettoyer les logs de plus de 7 jours :**

```bash
sudo journalctl --vacuum-time=7d
```

### C. Docker qui prend trop de place

Docker accumule des images, conteneurs, volumes et cache de build.

**Voir l'utilisation Docker :**

```bash
docker system df
```

**Exemple de sortie :**
```
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          10        3         2.935GB   2.719GB (92%)
Containers      3         2         110.1MB   0B (0%)
Local Volumes   1         0         0B        0B
Build Cache     35        0         108.7MB   108.7MB
```

**Nettoyer Docker :**

⚠️ **ATTENTION :** Cette commande supprime :
- Toutes les images non utilisées
- Tous les conteneurs arrêtés
- Tous les volumes non utilisés
- Tout le cache de build

```bash
docker system prune -a --volumes
```

**Nettoyage conservateur (seulement les ressources danglings) :**

```bash
docker system prune
```

### D. Cache APT (paquets téléchargés)

Les paquets `.deb` téléchargés par APT sont conservés dans le cache.

**Taille du cache :**

```bash
sudo du -sh /var/cache/apt
```

**Nettoyer :**

```bash
sudo apt clean
```

---

## 6. Méthodologie complète (étape par étape)

Voici la séquence complète pour diagnostiquer un problème d'espace disque :

```bash
# 1. Vue globale - quel disque est plein ?
df -h

# 2. Identifier les gros dossiers à la racine
sudo du -sh /* 2>/dev/null | sort -h | tail -10

# 3. Descendre dans le dossier suspect (exemple : /home)
sudo du -sh /home/* | sort -h | tail -10

# 4. Descendre encore plus profond (exemple : /home/debian)
sudo du -sh /home/debian/* | sort -h | tail -10

# 5. Trouver les gros fichiers individuels
sudo find /home/debian -type f -size +100M -exec ls -lh {} \; 2>/dev/null

# 6. Vérifier les fichiers fantômes (supprimés mais ouverts)
sudo lsof +L1 | grep deleted

# 7. Vérifier les logs système
sudo journalctl --disk-usage

# 8. Vérifier Docker
docker system df
```

---

## 7. Outil interactif : ncdu (recommandé)

`ncdu` est un outil interactif qui permet d'explorer visuellement l'espace disque, comme un explorateur de fichiers en mode texte.

**Installation :**

```bash
sudo apt install ncdu
```

**Utilisation :**

```bash
# Scanner un dossier
sudo ncdu /home

# Scanner depuis la racine (lent sur gros disques)
sudo ncdu /
```

**Navigation :**
- `↑` `↓` : Se déplacer dans la liste
- `Entrée` : Entrer dans un dossier
- `←` : Remonter au dossier parent
- `d` : Supprimer le fichier/dossier (⚠️ ATTENTION !)
- `g` : Afficher en graphique
- `?` : Aide
- `q` : Quitter

---

## 8. Mémo rapide (cheat sheet)

À garder sous la main pour un diagnostic rapide :

```bash
# Vue globale
df -h

# Top 10 gros dossiers dans un path
sudo du -sh /path/* | sort -h | tail -10

# Top 20 gros fichiers dans un path
sudo find /path -type f -size +100M -exec ls -lh {} \; 2>/dev/null | tail -20

# Fichiers fantômes (supprimés mais ouverts)
sudo lsof +L1 | grep deleted

# Logs système
sudo journalctl --disk-usage
sudo journalctl --vacuum-size=500M

# Docker
docker system df
docker system prune -a --volumes

# Cache APT
sudo apt clean

# Outil interactif
sudo ncdu /
```

---

## 9. Exemples de problèmes courants

### Problème 1 : Cache d'archives Git (Forgejo/GitLab)

**Symptôme :**
```
/home/user/forgejo/data/gitea/repo-archive → 48G
```

**Solution :**
```bash
# Supprimer le cache d'archives
sudo rm -rf /home/user/forgejo/data/gitea/repo-archive/*

# Configurer une expiration automatique dans app.ini
[repository.local]
ARCHIVE_EXPIRY = 604800  # 7 jours

# Ajouter un cron de nettoyage quotidien
sudo crontab -e
# Ajouter : 0 3 * * * find /path/to/repo-archive -type f -mtime +1 -delete
```

### Problème 2 : Logs Docker volumineux

**Symptôme :**
```
/var/lib/docker/containers/.../container-json.log → 10G
```

**Solution :**
```bash
# Limiter la taille des logs Docker
sudo nano /etc/docker/daemon.json
```

Ajouter :
```json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
```

```bash
# Redémarrer Docker
sudo systemctl restart docker
```

### Problème 3 : Base de données SQLite gonflée

**Symptôme :**
```
/var/lib/app/database.db → 5G
```

**Solution :**
```bash
# Vacuum (compacter) la base de données
sqlite3 /var/lib/app/database.db "VACUUM;"
```

---

## 10. Prévention

**Meilleures pratiques pour éviter les disques pleins :**

1. **Rotation des logs**
   - Configurer `logrotate` pour limiter la taille des logs
   - Utiliser `journalctl --vacuum-size=500M`

2. **Nettoyage automatique**
   - Ajouter des crons pour nettoyer les caches/tmp
   - Docker auto-prune régulier

3. **Monitoring**
   - Alertes quand le disque dépasse 80%
   - Vérifier régulièrement `df -h`

4. **Limites de taille**
   - Configurer `max-size` pour les logs Docker
   - Limiter les caches applicatifs

5. **Stockage externe**
   - Monter les gros volumes sur des disques séparés
   - Utiliser du stockage objet (S3) pour les archives

---

## Ressources complémentaires

**Commandes utiles :**

```bash
# Voir les inodes (nombre de fichiers)
df -i

# Trouver les dossiers avec beaucoup de petits fichiers
sudo find / -type d -exec sh -c 'echo "$(find "$1" -maxdepth 1 | wc -l) $1"' _ {} \; 2>/dev/null | sort -n | tail -20

# Voir l'espace utilisé par utilisateur
sudo du -sh /home/* | sort -h

# Monitoring en temps réel
watch -n 5 'df -h'
```

**Pages man utiles :**
- `man df` - Afficher l'espace disque
- `man du` - Calculer l'utilisation disque
- `man find` - Rechercher des fichiers
- `man lsof` - Lister les fichiers ouverts

---

**Guide créé le 2026-02-03**