350 lines
8.6 KiB
Markdown
350 lines
8.6 KiB
Markdown
# 🚀 4NK Node - Infrastructure Docker Complète
|
||
|
||
Infrastructure Docker complète pour le développement et le déploiement de services 4NK avec support des paiements silencieux (Silent Payments).
|
||
|
||
## 📋 Table des Matières
|
||
|
||
- [🏗️ Architecture](#️-architecture)
|
||
- [🚀 Démarrage Rapide](#-démarrage-rapide)
|
||
- [📚 Documentation](#-documentation)
|
||
- [🔧 Configuration](#-configuration)
|
||
- [🧪 Tests et Monitoring](#-tests-et-monitoring)
|
||
- [🌐 Réseau de Relais](#-réseau-de-relais)
|
||
- [🛠️ Développement](#️-développement)
|
||
- [🚨 Dépannage](#-dépannage)
|
||
|
||
## 🏗️ Architecture
|
||
|
||
4NK Node est composé de plusieurs services orchestrés via Docker :
|
||
|
||
| Service | Port | Description | Statut |
|
||
|---------|------|-------------|---------|
|
||
| **Tor** | 9050, 9051 | Proxy anonyme pour Bitcoin Core | ✅ Stable |
|
||
| **Bitcoin Core** | 18443 (RPC), 29000 (ZMQ) | Nœud Bitcoin en mode signet | ✅ Stable |
|
||
| **Blindbit** | 8000 | Service de filtres pour les paiements silencieux | ✅ Stable |
|
||
| **sdk_relay** | 8090-8095 | Services de relais (3 instances) | ✅ Stable |
|
||
|
||
### 🔄 Flux de Données
|
||
|
||
```
|
||
Client → sdk_relay → Bitcoin Core
|
||
↓
|
||
Blindbit → Bitcoin Core
|
||
↓
|
||
Tor (anonymat)
|
||
```
|
||
|
||
## 🚀 Démarrage Rapide
|
||
|
||
### Prérequis
|
||
|
||
- **Docker** et **Docker Compose** installés
|
||
- **10 Go** d'espace disque minimum
|
||
- **Connexion Internet** stable
|
||
- **Clé SSH** configurée pour Gitea (recommandé)
|
||
|
||
### Installation
|
||
|
||
```bash
|
||
# 1. Cloner le repository (SSH recommandé)
|
||
git clone git@git.4nkweb.com:4nk/4NK_node.git
|
||
cd 4NK_node
|
||
|
||
# 2. Amorcer l’environnement (git, Docker, Compose, Node/npm)
|
||
./scripts/orchestrate_start.sh
|
||
# Astuce: se déconnecter/reconnecter pour activer le groupe docker
|
||
|
||
# 3. Démarrer tous les services
|
||
./scripts/restart_4nk_node.sh
|
||
|
||
# 4. Vérifier le statut
|
||
docker ps
|
||
```
|
||
|
||
### Configuration SSH (Recommandé)
|
||
|
||
```bash
|
||
# Générer une clé SSH
|
||
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_4nk -C "4nk-automation"
|
||
|
||
# Ajouter à l'agent SSH
|
||
ssh-add ~/.ssh/id_ed25519_4nk
|
||
|
||
# Configurer Git
|
||
git config --global core.sshCommand "ssh -i ~/.ssh/id_ed25519_4nk"
|
||
|
||
# Ajouter la clé publique à Gitea
|
||
cat ~/.ssh/id_ed25519_4nk.pub
|
||
```
|
||
|
||
## 📚 Documentation
|
||
|
||
### 📖 Guides Principaux
|
||
|
||
- **[Index de la documentation](docs/INDEX.md)** - Table des matières centrale
|
||
- **[Guide d'Utilisation](docs/USAGE.md)** - Utilisation quotidienne et cas d'usage
|
||
- **[Guide de Configuration](docs/CONFIGURATION.md)** - Configuration avancée
|
||
- **[Architecture](docs/ARCHITECTURE.md)** - Architecture détaillée
|
||
|
||
### 🔧 Guides Techniques
|
||
|
||
- **[Architecture Technique](docs/ARCHITECTURE.md)** - Architecture détaillée
|
||
- **[API Reference](docs/API.md)** - Documentation des APIs
|
||
- **[Sécurité](docs/SECURITY.md)** - Sécurité et bonnes pratiques
|
||
- **[Performance](docs/PERFORMANCE.md)** - Optimisation et monitoring
|
||
|
||
### 🧪 Guides de Test
|
||
|
||
- **[Tests de Base](docs/TESTING.md)** - Tests de connectivité et fonctionnalité
|
||
- **[Tests de Synchronisation](docs/SYNC_TESTING.md)** - Tests de synchronisation entre relais
|
||
- **[Tests de Performance](docs/PERFORMANCE_TESTING.md)** - Tests de charge et performance
|
||
|
||
### 🌐 Guides Réseau
|
||
|
||
- **[Réseau et cartographie](docs/NETWORK.md)** - Hostnames, IP, ports, montages et routes Nginx
|
||
|
||
## 🔧 Configuration
|
||
|
||
### Services Disponibles
|
||
|
||
| Service | Configuration | Volume | Description |
|
||
|---------|---------------|---------|-------------|
|
||
| **Bitcoin Core** | `bitcoin/bitcoin.conf` | `bitcoin_data` | Nœud Bitcoin signet avec RPC et ZMQ |
|
||
| **Blindbit** | `blindbit/blindbit.toml` | `blindbit_data` | Service de filtres Silent Payments |
|
||
| **sdk_relay** | `sdk_relay/.conf.docker.*` | `sdk_relay_*_data` | Relais avec synchronisation mesh |
|
||
| **Tor** | `tor/torrc` | - | Proxy anonyme |
|
||
|
||
### Variables d'Environnement
|
||
|
||
```bash
|
||
# Logs
|
||
RUST_LOG=debug,bitcoincore_rpc=trace
|
||
|
||
# Bitcoin
|
||
BITCOIN_COOKIE_PATH=/home/bitcoin/.bitcoin/signet/.cookie
|
||
|
||
# Synchronisation
|
||
ENABLE_SYNC_TEST=1
|
||
```
|
||
|
||
## 🧪 Tests et Monitoring
|
||
|
||
### Tests de Base
|
||
|
||
```bash
|
||
# Test de connectivité
|
||
./test_final_sync.sh
|
||
|
||
# Test de synchronisation
|
||
./test_sync_logs.sh
|
||
|
||
# Test des messages WebSocket
|
||
python3 test_websocket_messages.py
|
||
```
|
||
|
||
### Monitoring
|
||
|
||
```bash
|
||
# Surveillance de la synchronisation
|
||
./monitor_sync.sh
|
||
|
||
# Logs en temps réel
|
||
docker-compose logs -f
|
||
|
||
# Statut des services
|
||
docker ps
|
||
```
|
||
|
||
### Tests de Performance
|
||
|
||
```bash
|
||
# Test de charge WebSocket
|
||
python3 test_websocket_messages.py --load-test
|
||
|
||
# Test de synchronisation
|
||
./test_sync_logs.sh continuous
|
||
```
|
||
|
||
## 🌐 Réseau de Relais
|
||
|
||
### Architecture Mesh
|
||
|
||
L'infrastructure supporte un réseau mesh de relais avec :
|
||
|
||
- **3 relais locaux** : `sdk_relay_1`, `sdk_relay_2`, `sdk_relay_3`
|
||
- **Nœuds externes** : Configuration via `external_nodes.conf`
|
||
- **Synchronisation automatique** : Partage de données entre relais
|
||
- **Découverte automatique** : Découverte des relais voisins
|
||
|
||
### Ajout de Nœuds Externes
|
||
|
||
```bash
|
||
# Ajouter un nœud externe
|
||
./scripts/add_external_node.sh add external-relay-1 external-relay-1.example.com:8090
|
||
|
||
# Lister les nœuds configurés
|
||
./scripts/add_external_node.sh list
|
||
|
||
# Tester la connectivité
|
||
./scripts/add_external_node.sh test external-relay-1
|
||
```
|
||
|
||
### Configuration Externe
|
||
|
||
```toml
|
||
# external_nodes.conf
|
||
[relays]
|
||
external-relay-1 = "external-relay-1.example.com:8090"
|
||
dev3-relay = "dev3.4nkweb.com:443"
|
||
|
||
[discovery]
|
||
auto_discover = true
|
||
bootstrap_nodes = []
|
||
```
|
||
|
||
## 🛠️ Développement
|
||
|
||
### Structure du Projet
|
||
|
||
```
|
||
4NK_node/
|
||
├── bitcoin/ # Configuration Bitcoin Core
|
||
├── blindbit/ # Configuration Blindbit
|
||
├── sdk_relay/ # Configuration des relais
|
||
├── tor/ # Configuration Tor
|
||
├── specs/ # Spécifications techniques
|
||
├── docs/ # Documentation
|
||
├── tests/ # Scripts de test
|
||
├── scripts/ # Scripts utilitaires
|
||
└── docker-compose.yml
|
||
```
|
||
|
||
### Ajout d'un Nouveau Service
|
||
|
||
1. Créer le Dockerfile dans un sous-répertoire
|
||
2. Ajouter le service dans `docker-compose.yml`
|
||
3. Configurer les dépendances et le réseau
|
||
4. Ajouter les healthchecks si nécessaire
|
||
5. Documenter dans la section appropriée
|
||
|
||
### Modification de la Configuration
|
||
|
||
```bash
|
||
# Modifier la configuration Bitcoin Core
|
||
sudo docker-compose down
|
||
# Éditer bitcoin/bitcoin.conf
|
||
sudo docker-compose up -d bitcoin
|
||
|
||
# Modifier la configuration Blindbit
|
||
# Éditer blindbit/blindbit.toml
|
||
sudo docker-compose restart blindbit
|
||
```
|
||
|
||
## 🚨 Dépannage
|
||
|
||
### Problèmes Courants
|
||
|
||
#### 1. Ports Déjà Utilisés
|
||
|
||
```bash
|
||
# Vérifier les ports utilisés
|
||
sudo netstat -tlnp | grep -E "(18443|8000|9050|8090)"
|
||
|
||
# Arrêter les services conflictuels
|
||
sudo docker-compose down
|
||
```
|
||
|
||
#### 2. Problèmes de Synchronisation Bitcoin
|
||
|
||
```bash
|
||
# Vérifier les logs Bitcoin Core
|
||
sudo docker-compose logs bitcoin
|
||
|
||
# Redémarrer Bitcoin Core
|
||
sudo docker-compose restart bitcoin
|
||
```
|
||
|
||
#### 3. Problèmes de Connectivité sdk_relay
|
||
|
||
```bash
|
||
# Tester la connectivité
|
||
cd sdk_relay
|
||
./test_final.sh
|
||
|
||
# Vérifier la configuration
|
||
./debug_container.sh
|
||
```
|
||
|
||
### Logs Détaillés
|
||
|
||
```bash
|
||
# Logs avec timestamps
|
||
sudo docker-compose logs -t
|
||
|
||
# Logs des 100 dernières lignes
|
||
sudo docker-compose logs --tail=100
|
||
|
||
# Logs depuis une date
|
||
sudo docker-compose logs --since="2024-01-01T00:00:00"
|
||
```
|
||
|
||
### Healthchecks
|
||
|
||
```bash
|
||
# Vérifier l'état des healthchecks
|
||
sudo docker-compose ps
|
||
|
||
# Logs des healthchecks
|
||
sudo docker-compose logs | grep health
|
||
|
||
# Test manuel du healthcheck sdk_relay
|
||
sudo docker exec sdk_relay /usr/local/bin/healthcheck.sh
|
||
```
|
||
|
||
## 📈 Performance
|
||
|
||
### Ressources Recommandées
|
||
|
||
- **CPU** : 2 cœurs minimum, 4 cœurs recommandés
|
||
- **RAM** : 4 Go minimum, 8 Go recommandés
|
||
- **Stockage** : 20 Go minimum pour la blockchain signet
|
||
- **Réseau** : Connexion stable pour la synchronisation
|
||
|
||
### Optimisations
|
||
|
||
```bash
|
||
# Limiter l'utilisation CPU
|
||
sudo docker-compose up -d --scale bitcoin=1
|
||
|
||
# Surveiller l'utilisation des ressources
|
||
sudo docker stats
|
||
|
||
# Optimiser l'espace disque
|
||
sudo docker system prune -f
|
||
```
|
||
|
||
## 🤝 Contribution
|
||
|
||
1. Fork le repository
|
||
2. Créer une branche feature (`git checkout -b feature/nouvelle-fonctionnalite`)
|
||
3. Commit les changements (`git commit -am 'Ajout de nouvelle fonctionnalité'`)
|
||
4. Push la branche (`git push origin feature/nouvelle-fonctionnalite`)
|
||
5. Créer une Pull Request
|
||
|
||
## 📄 Licence
|
||
|
||
Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.
|
||
|
||
## 🆘 Support
|
||
|
||
Pour obtenir de l'aide :
|
||
|
||
1. Consulter la [documentation](docs/)
|
||
2. Vérifier les [issues existantes](https://git.4nkweb.com/4nk/4NK_node/issues)
|
||
3. Créer une nouvelle issue avec les détails du problème
|
||
4. Inclure les logs et la configuration utilisée
|
||
|
||
---
|
||
|
||
**✨ Infrastructure 4NK Node - Prête pour la production !**
|