# Guide de Dépannage - Monitoring LeCoffre Node

## Problèmes Courants et Solutions

### 1. Services en État "unhealthy"

#### Symptômes
- Service affiché comme "unhealthy" dans `docker compose ps`
- Healthcheck échoue constamment
- Service ne répond pas aux requêtes

#### Diagnostic
```bash
# Vérifier le statut du healthcheck
docker inspect --format='{{.State.Health.Status}}' <service>

# Vérifier les logs du healthcheck
docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' <service>

# Vérifier les logs du service
docker logs <service> --tail 50
```

#### Solutions
1. **Vérifier la connectivité réseau**
   ```bash
   # Vérifier que le service écoute sur le bon port
   docker exec <service> netstat -tlnp

   # Vérifier la connectivité depuis l'extérieur
   curl -f http://localhost:<port>/health
   ```

2. **Vérifier les dépendances**
   ```bash
   # Vérifier que les services de dépendance sont "healthy"
   docker compose --env-file .env.master ps
   ```

3. **Redémarrer le service**
   ```bash
   docker compose --env-file .env.master restart <service>
   ```

### 2. Progression Bitcoin Bloquée

#### Symptômes
- Bitcoin IBD reste à un pourcentage fixe
- Pas de nouveaux blocs téléchargés
- Messages d'erreur dans les logs

#### Diagnostic
```bash
# Vérifier l'état de la blockchain
docker exec bitcoin-signet bitcoin-cli -conf=/etc/bitcoin/bitcoin.conf getblockchaininfo

# Vérifier les connexions
docker exec bitcoin-signet bitcoin-cli -conf=/etc/bitcoin/bitcoin.conf getpeerinfo

# Vérifier les logs
docker logs bitcoin-signet --tail 100 | grep -E "(ERROR|error|Error|WARN|warn|Warn)"
```

#### Solutions
1. **Vérifier la connectivité réseau**
   ```bash
   # Vérifier que Tor fonctionne
   docker logs tor-proxy --tail 20

   # Vérifier la connectivité Bitcoin
   docker exec bitcoin-signet bitcoin-cli -conf=/etc/bitcoin/bitcoin.conf getnetworkinfo
   ```

2. **Vérifier l'espace disque**
   ```bash
   # Vérifier l'espace disponible
   df -h

   # Vérifier la taille du volume Bitcoin
   docker volume inspect 4nk_node_bitcoin_data
   ```

3. **Redémarrer Bitcoin**
   ```bash
   docker compose --env-file .env.master restart bitcoin
   ```

### 3. Services en Attente de Dépendances

#### Symptômes
- Services affichés comme "Stopped"
- Messages "dependency failed to start"
- Services ne démarrent pas

#### Diagnostic
```bash
# Vérifier les dépendances dans docker-compose.yml
grep -A 5 -B 5 "depends_on" docker-compose.yml

# Vérifier le statut des services de dépendance
docker compose --env-file .env.master ps
```

#### Solutions
1. **Démarrer les services dans l'ordre correct**
   ```bash
   # Utiliser le script de démarrage ordonné
   ./scripts/start-with-progress.sh
   ```

2. **Vérifier les conditions de dépendance**
   ```bash
   # Vérifier que les services de dépendance sont "healthy"
   docker inspect --format='{{.State.Health.Status}}' <service-dependance>
   ```

3. **Modifier temporairement les dépendances**
   ```bash
   # Changer condition: service_healthy en condition: service_started
   # (Attention : à remettre en place après résolution)
   ```

### 4. Erreurs de Connexion WebSocket

#### Symptômes
- SDK Relay ne répond pas sur le port 8091
- Erreurs 502 Bad Gateway pour les WebSockets
- Messages "TLS support not compiled in"

#### Diagnostic
```bash
# Vérifier que le service écoute sur le bon port
docker exec sdk_relay netstat -tlnp

# Vérifier les logs du service
docker logs sdk_relay --tail 50

# Tester la connectivité locale
curl -f http://localhost:8091/
```

#### Solutions
1. **Vérifier la configuration Nginx**
   ```bash
   # Vérifier la configuration WebSocket
   sudo grep -A 10 -B 5 "ws/" /etc/nginx/sites-enabled/dev4.4nkweb.com-https.conf

   # Tester la configuration Nginx
   sudo nginx -t
   ```

2. **Vérifier les variables d'environnement**
   ```bash
   # Vérifier la configuration du SDK Relay
   docker exec sdk_relay env | grep SDK_RELAY
   ```

3. **Redémarrer le service**
   ```bash
   docker compose --env-file .env.master restart sdk_relay
   ```

### 5. Problèmes de Permissions

#### Symptômes
- Erreurs "Permission denied"
- Services ne peuvent pas écrire dans les volumes
- Erreurs de montage de volumes

#### Diagnostic
```bash
# Vérifier les permissions des volumes
docker volume inspect <volume-name>

# Vérifier les permissions des dossiers locaux
ls -la logs/
ls -la conf/
```

#### Solutions
1. **Corriger les permissions des volumes**
   ```bash
   # Corriger les permissions des logs
   sudo chown -R 1000:1000 logs/
   sudo chmod -R 755 logs/
   ```

2. **Vérifier la configuration des volumes**
   ```bash
   # Vérifier la configuration dans docker-compose.yml
   grep -A 5 -B 5 "volumes:" docker-compose.yml
   ```

3. **Redémarrer les services**
   ```bash
   docker compose --env-file .env.master down
   docker compose --env-file .env.master up -d
   ```

### 6. Problèmes de Configuration

#### Symptômes
- Services ne démarrent pas
- Erreurs de configuration dans les logs
- Variables d'environnement manquantes

#### Diagnostic
```bash
# Vérifier la configuration Docker Compose
docker compose --env-file .env.master config

# Vérifier les variables d'environnement
docker exec <service> env | grep <VARIABLE>

# Vérifier les fichiers de configuration
cat .env.master | grep <VARIABLE>
```

#### Solutions
1. **Vérifier le fichier .env.master**
   ```bash
   # Vérifier que toutes les variables sont définies
   docker compose --env-file .env.master config --services
   ```

2. **Corriger les variables manquantes**
   ```bash
   # Ajouter les variables manquantes dans .env.master
   echo "VARIABLE=valeur" >> .env.master
   ```

3. **Redémarrer les services**
   ```bash
   docker compose --env-file .env.master down
   docker compose --env-file .env.master up -d
   ```

## Outils de Diagnostic

### Scripts de Diagnostic
```bash
# Diagnostic complet
./scripts/monitor-progress.sh

# Logs avec progression
./scripts/logs-with-progress.sh <service> -p -n 100

# Surveillance en temps réel
./scripts/watch-progress.sh
```

### Commandes Docker Utiles
```bash
# Informations détaillées sur un service
docker inspect <service>

# Logs en temps réel
docker logs -f <service>

# Exécuter une commande dans un conteneur
docker exec -it <service> /bin/bash

# Vérifier l'utilisation des ressources
docker stats <service>
```

### Commandes Système
```bash
# Vérifier l'espace disque
df -h

# Vérifier la mémoire
free -h

# Vérifier les processus
ps aux | grep docker

# Vérifier les ports
netstat -tlnp | grep <port>
```

## Procédures de Récupération

### Récupération Complète
```bash
# Arrêter tous les services
docker compose --env-file .env.master down

# Nettoyer le système Docker
docker system prune -af --volumes

# Redémarrer avec le script de progression
./scripts/start-with-progress.sh
```

### Récupération d'un Service
```bash
# Arrêter le service
docker compose --env-file .env.master stop <service>

# Supprimer le conteneur
docker compose --env-file .env.master rm <service>

# Redémarrer le service
docker compose --env-file .env.master up -d <service>
```

### Récupération des Volumes
```bash
# Arrêter tous les services
docker compose --env-file .env.master down

# Supprimer les volumes
docker volume rm <volume-name>

# Redémarrer les services
docker compose --env-file .env.master up -d
```

## Logs et Monitoring

### Logs Importants
```bash
# Logs Bitcoin
docker logs bitcoin-signet --tail 100

# Logs SDK Relay
docker logs sdk_relay --tail 100

# Logs BlindBit
docker logs blindbit-oracle --tail 100

# Logs Nginx
sudo tail -f /var/log/nginx/error.log
```

### Monitoring des Ressources
```bash
# Utilisation des ressources
docker stats

# Espace disque
df -h

# Mémoire
free -h

# CPU
top
```

## Prévention des Problèmes

### Vérifications Régulières
1. **Vérifier l'espace disque** : `df -h`
2. **Vérifier la mémoire** : `free -h`
3. **Vérifier les logs** : `./scripts/monitor-progress.sh`
4. **Vérifier la connectivité** : Tester les URLs externes

### Maintenance Préventive
1. **Nettoyer les logs** : `docker system prune -f`
2. **Vérifier les mises à jour** : `docker images`
3. **Sauvegarder les configurations** : Copier `.env.master`
4. **Tester les sauvegardes** : Vérifier les volumes

### Surveillance Continue
1. **Utiliser les scripts de monitoring** : `./scripts/watch-progress.sh`
2. **Configurer des alertes** : Surveiller les logs d'erreur
3. **Vérifier les performances** : `docker stats`
4. **Tester la connectivité** : Vérifier les URLs externes

Ce guide de dépannage permet aux agents IA de diagnostiquer et résoudre rapidement les problèmes courants du système de monitoring LeCoffre Node.