423 lines
17 KiB
Markdown
423 lines
17 KiB
Markdown
# Analyse Architecturale Approfondie - 4NK Environment
|
|
|
|
**Date** : 2025-01-27
|
|
**Version** : 2.0
|
|
**Contexte** : Analyse approfondie de l'architecture 4NK et du projet LeCoffre
|
|
|
|
## 📋 Vue d'ensemble Détaillée
|
|
|
|
Cette analyse approfondie présente l'architecture complète de l'environnement 4NK, incluant tous les modules, leurs dépendances, configurations, et le système de déploiement par phases.
|
|
|
|
## 🏗️ Architecture Générale Détaillée
|
|
|
|
### Structure des Submodules
|
|
```
|
|
4NK_env/ # Environnement centralisé
|
|
├── 4NK_modules/ # 13 modules 4NK (SDK, services)
|
|
│ ├── sdk_relay/ # Relais WebSocket central (Rust)
|
|
│ ├── sdk_storage/ # Stockage temporaire (Rust)
|
|
│ ├── sdk_signer/ # Service de signature (TypeScript)
|
|
│ ├── sdk_client/ # Client SDK (Rust/WASM)
|
|
│ ├── sdk_common/ # Composants communs (Rust)
|
|
│ ├── sdk-signer-client/ # Client signeur (TypeScript)
|
|
│ ├── ihm_client/ # Interface utilisateur (Vite/React)
|
|
│ ├── 4NK_vault/ # API sécurisée configurations (Python)
|
|
│ ├── 4NK_certificator/ # Ancrage cryptographique (Rust)
|
|
│ ├── 4NK_miner/ # Service de minage (Rust)
|
|
│ ├── 4NK_web_status/ # Service de statut (Python)
|
|
│ ├── blindbit-oracle/ # Oracle Bitcoin (Rust)
|
|
│ ├── rust-silentpayments/ # Silent Payments (Rust)
|
|
│ └── doc_api/ # Documentation API
|
|
├── projects/lecoffre/ # Projet LeCoffre (notaires)
|
|
│ ├── lecoffre_node/ # Docker de contrôle
|
|
│ ├── lecoffre-front/ # Frontend Next.js
|
|
│ └── lecoffre-back-mini/ # Backend centralisé
|
|
├── IA_agents/ # Agents IA et documentation
|
|
├── docs/ # Documentation centralisée
|
|
├── scripts/ # Scripts de gestion centralisés
|
|
└── confs/ # Configurations déployées (4NK_vault)
|
|
```
|
|
|
|
## 🔧 Modules 4NK - Analyse Approfondie
|
|
|
|
### 1. **sdk_relay** - Service de Relais WebSocket Central
|
|
**Rôle** : Relais central pour les communications WebSocket et la synchronisation mesh
|
|
- **Technologie** : Rust (tokio, async-trait, futures-util)
|
|
- **Ports** : 8090 (WebSocket), 8091 (HTTP health)
|
|
- **Dépendances** :
|
|
- `sdk_common` (git: https://git.4nkweb.com/4nk/sdk_common.git)
|
|
- `bitcoincore-rpc` (0.18) - Interface Bitcoin Core
|
|
- `tokio-tungstenite` (0.21.0) - WebSocket
|
|
- `zeromq` (0.4.1) - ZMQ Bitcoin Core
|
|
- **Fonctionnalités** :
|
|
- Serveur WebSocket configurable
|
|
- Synchronisation mesh entre relais
|
|
- Gestion des processus et membres
|
|
- Interface avec Bitcoin Core (RPC + ZMQ)
|
|
- Intégration Blindbit pour Silent Payments
|
|
- Cache de déduplication
|
|
- Gestion d'état locale dans `~/<data_dir>`
|
|
- **Architecture** : Rust avec gestion d'état locale
|
|
- **Configuration** : Fichier de configuration via `--config`
|
|
- **Healthcheck** : `/health` sur port 8091
|
|
|
|
### 2. **sdk_storage** - Service de Stockage Temporaire Sécurisé
|
|
**Rôle** : Stockage temporaire avec TTL et chiffrement
|
|
- **Technologie** : Rust (tide, async-std)
|
|
- **Port** : 8081 (mappé depuis 8080)
|
|
- **API** :
|
|
- `POST /store` : Stockage avec clé/valeur/TTL
|
|
- `GET /retrieve/:key` : Récupération des données
|
|
- **Fonctionnalités** :
|
|
- Stockage temporaire avec expiration
|
|
- Clés hexadécimales 64 caractères
|
|
- Valeurs hexadécimales
|
|
- TTL optionnel (permanent si non spécifié)
|
|
- Chiffrement des données
|
|
- **Architecture** : Rust avec async-std
|
|
- **Healthcheck** : `/health` sur port 8080
|
|
|
|
### 3. **sdk_signer** - Service de Signature TypeScript
|
|
**Rôle** : Service de signature pour l'écosystème 4NK
|
|
- **Technologie** : TypeScript avec support WASM
|
|
- **Fonctionnalités** :
|
|
- Gestion des processus et signatures
|
|
- Communication sécurisée
|
|
- Compatibilité WASM (stub temporaire)
|
|
- Interface avec le réseau de relais
|
|
- Validation des permissions
|
|
- **Architecture** : TypeScript avec support WASM
|
|
- **État** : Compatible avec stub sdk_client
|
|
- **Dépendances** : Node.js 18+, npm/yarn
|
|
|
|
### 4. **sdk_client** - Client SDK Rust/WASM
|
|
**Rôle** : Client SDK pour l'interaction avec l'écosystème 4NK
|
|
- **Technologie** : Rust avec interface WebAssembly
|
|
- **Fonctionnalités** :
|
|
- Interface avec les services 4NK
|
|
- Gestion des connexions WebSocket
|
|
- Support des processus et transactions
|
|
- Compilation WASM pour le web
|
|
- **Architecture** : Rust avec interface WASM
|
|
- **Usage** : Importé par sdk_signer et autres clients
|
|
|
|
### 5. **sdk_common** - Bibliothèque Commune
|
|
**Rôle** : Composants communs partagés entre tous les modules
|
|
- **Technologie** : Rust
|
|
- **Fonctionnalités** :
|
|
- Types et structures communes
|
|
- Utilitaires partagés
|
|
- Protocoles de communication
|
|
- Support Blindbit (feature: "blindbit-backend")
|
|
- Support parallèle (feature: "parallel")
|
|
- **Usage** : Importé par tous les autres modules
|
|
- **Features** : parallel, blindbit-backend
|
|
|
|
### 6. **sdk-signer-client** - Client Signeur
|
|
**Rôle** : Client pour l'interaction avec le service de signature
|
|
- **Technologie** : TypeScript
|
|
- **Fonctionnalités** :
|
|
- Interface avec sdk_signer
|
|
- Gestion des signatures
|
|
- Communication sécurisée
|
|
- **Architecture** : TypeScript client
|
|
|
|
### 7. **ihm_client** - Interface Homme-Machine
|
|
**Rôle** : Interface utilisateur pour la gestion des clés et processus
|
|
- **Technologie** : Vite + React
|
|
- **Port** : 3003
|
|
- **Fonctionnalités** :
|
|
- Interface de gestion des clés Bitcoin
|
|
- Gestion des processus
|
|
- Interface utilisateur web
|
|
- Variables d'environnement Vite
|
|
- **Dépendances** : sdk_relay, sdk_storage
|
|
- **Variables** : VITE_JWT_SECRET_KEY, VITE_API_BASE_URL, VITE_WS_URL, VITE_STORAGE_URL, VITE_SIGNER_URL, VITE_BOOTSTRAPURL
|
|
|
|
### 8. **4NK_vault** - Système de Gestion des Configurations
|
|
**Rôle** : API sécurisée pour la gestion centralisée des configurations
|
|
- **Technologie** : Python Flask
|
|
- **Port** : 6666 (HTTPS)
|
|
- **Sécurité** :
|
|
- Authentification par clés utilisateur
|
|
- Chiffrement quantique résistant (ChaCha20-Poly1305)
|
|
- Rotation automatique des clés (toutes les heures)
|
|
- Isolation par environnement (dev, prod)
|
|
- **Fonctionnalités** :
|
|
- Résolution des variables d'environnement
|
|
- Synchronisation vers `confs/` dans le docker de contrôle
|
|
- Protection des secrets
|
|
- Clés individuelles par utilisateur/environnement
|
|
- **Endpoints** :
|
|
- `GET /health` - Contrôle de santé
|
|
- `GET /info` - Informations API
|
|
- `GET /routes` - Routes disponibles
|
|
- `GET /<env>/<file>` - Fichier chiffré
|
|
- **Déploiement** : Synchronise les configurations vers `confs/`
|
|
|
|
### 9. **4NK_certificator** - Service d'Ancrage Cryptographique
|
|
**Rôle** : Ancrage périodique sur Bitcoin mainnet des empreintes des échanges
|
|
- **Technologie** : Rust
|
|
- **Fonctionnalités** :
|
|
- Surveillance des messages du relay 4NK
|
|
- Détection des paiements Bitcoin
|
|
- Enregistrement périodique sur blockchain
|
|
- Métriques de volume de données
|
|
- Base de données SQLite
|
|
- **Architecture** : Rust avec base de données SQLite
|
|
- **État** : MVP complet implémenté
|
|
- **Composants** :
|
|
- RelayMonitor (surveillance WebSocket)
|
|
- PaymentWatcher (surveillance Bitcoin)
|
|
- Base de données SQLite
|
|
|
|
### 10. **4NK_miner** - Service de Minage
|
|
**Rôle** : Service de minage Bitcoin (développement/test)
|
|
- **Technologie** : Rust
|
|
- **Fonctionnalités** :
|
|
- Minage sur réseau Signet
|
|
- Génération de blocs de test
|
|
- Interface avec le réseau Bitcoin
|
|
- **Usage** : Développement et tests uniquement
|
|
|
|
### 11. **4NK_web_status** - Service de Statut
|
|
**Rôle** : Service de monitoring et statut des services
|
|
- **Technologie** : Python Flask
|
|
- **Port** : 3006
|
|
- **Fonctionnalités** :
|
|
- Monitoring des services
|
|
- Interface de statut
|
|
- Métriques de santé
|
|
- API REST pour le statut
|
|
- **Dépendances** : Docker socket, logs directory
|
|
|
|
### 12. **blindbit-oracle** - Oracle Bitcoin Silent Payments
|
|
**Rôle** : Service pour les paiements silencieux (Silent Payments)
|
|
- **Technologie** : Rust
|
|
- **Port** : 8000
|
|
- **Fonctionnalités** :
|
|
- Génération d'adresses Silent Payments
|
|
- Validation des transactions
|
|
- Interface HTTP REST
|
|
- Scan filtré BIP158
|
|
- **Dépendances** : Bitcoin Core
|
|
- **Configuration** : blindbit.toml
|
|
|
|
### 13. **rust-silentpayments** - Implémentation Silent Payments
|
|
**Rôle** : Implémentation Rust des Silent Payments
|
|
- **Technologie** : Rust
|
|
- **Fonctionnalités** :
|
|
- Génération d'adresses Silent Payments
|
|
- Validation des transactions
|
|
- Utilitaires cryptographiques
|
|
- **Usage** : Bibliothèque pour blindbit-oracle
|
|
|
|
## 🏢 Projet LeCoffre - Architecture Notariale Détaillée
|
|
|
|
### Contexte Métier
|
|
Le projet LeCoffre est une plateforme de gestion de documents sécurisée pour les notaires, utilisant l'infrastructure 4NK pour la sécurité et l'intégrité des documents.
|
|
|
|
### Composants du Projet LeCoffre
|
|
|
|
#### 1. **lecoffre_node** - Orchestrateur Principal
|
|
**Rôle** : Docker de contrôle et déploiement pour LeCoffre
|
|
- **Architecture** : Docker Compose avec Nginx intégré
|
|
- **Services déployés** :
|
|
- **tor** (btcpayserver/tor:0.4.8.10) - Proxy anonyme
|
|
- **bitcoin** (build: ./bitcoin) - Nœud Bitcoin Signet
|
|
- **blindbit** (git.4nkweb.com/4nk/blindbit-oracle:fixed-source) - Oracle Bitcoin
|
|
- **sdk_relay** (git.4nkweb.com/4nk/sdk_relay:ext) - Relais WebSocket
|
|
- **sdk_storage** (git.4nkweb.com/4nk/sdk_storage:ext) - Stockage temporaire
|
|
- **lecoffre-front** (git.4nkweb.com/4nk/lecoffre-front:ext) - Frontend Next.js
|
|
- **ihm_client** (git.4nkweb.com/4nk/ihm_client:ext) - Interface utilisateur
|
|
- **grafana** (grafana/grafana:latest) - Monitoring
|
|
- **loki** (grafana/loki:latest) - Collecte de logs
|
|
- **promtail** (grafana/promtail:latest) - Agent de collecte
|
|
- **status-api** (build: 4NK_web_status) - API de statut
|
|
- **watchtower** (containrrr/watchtower) - Mise à jour automatique
|
|
- **signet_miner** (build: 4NK_miner) - Minage (profile: miner)
|
|
- **Configuration** : Centralisée dans `confs/` (synchronisée depuis 4NK_vault)
|
|
- **Déploiement** : Scripts automatisés avec phases de démarrage
|
|
- **Réseau** : btcnet (172.20.0.0/16)
|
|
- **Volumes** : Persistance des données (bitcoin_data, blindbit_data, sdk_data, etc.)
|
|
|
|
#### 2. **lecoffre-front** - Interface Utilisateur
|
|
**Rôle** : Frontend Next.js pour l'application LeCoffre
|
|
- **Technologie** : Next.js avec React
|
|
- **Port** : 3004 (mappé depuis 8080)
|
|
- **Fonctionnalités** :
|
|
- Interface utilisateur pour les notaires
|
|
- Gestion des documents
|
|
- Intégration avec l'écosystème 4NK
|
|
- Variables d'environnement Next.js
|
|
- **Variables** : NEXT_PUBLIC_API_URL, NEXT_PUBLIC_4NK_URL, NEXT_PUBLIC_4NK_IFRAME_URL, NEXT_PUBLIC_IDNOT_BASE_URL
|
|
- **Déploiement** : Conteneur Docker sur port 3004
|
|
- **User** : lecoffreuser (non-root)
|
|
|
|
#### 3. **lecoffre-back-mini** - Backend Centralisé
|
|
**Rôle** : Backend centralisé pour les besoins spécifiques des notaires
|
|
- **Déploiement** : Sur dev3.4nkweb.com
|
|
- **Fonctionnalités** :
|
|
- APIs avec Stripe (paiements)
|
|
- Intégration Mailchimp (email marketing)
|
|
- Intégration OVH (SMS)
|
|
- Intégration IdNot (HMR dev3 ↔ dev4 via OAuth2)
|
|
- **Architecture** : Service centralisé indépendant
|
|
- **APIs** :
|
|
- `/api/v1/health` - Santé du service
|
|
- `/api/v1/status` - Statut du service
|
|
- `/api/v1/idnot/state` - État IdNot
|
|
|
|
## 🌐 Architecture de Déploiement Détaillée
|
|
|
|
### Environnements et URLs
|
|
- **dev4.4nkweb.com** : Machine principale (LeCoffre)
|
|
- **dev3.4nkweb.com** : Nœud de bootstrap (signer centralisé, mini back)
|
|
|
|
### URLs et Services
|
|
- **LeCoffre Front** : https://dev4.4nkweb.com/lecoffre
|
|
- **4NK iframe** : https://dev4.4nkweb.com
|
|
- **Signer centralisé** : dev3.4nkweb.com (module 4NK pour notaires)
|
|
- **Mini back** : dev3.4nkweb.com (APIs Stripe, Mailchimp, OVH, IdNot)
|
|
|
|
### Architecture de Déploiement par Phases
|
|
|
|
#### Phase 1: Services de Base (Parallèle)
|
|
- **tor** : Proxy anonyme (btcpayserver/tor:0.4.8.10)
|
|
- **sdk_storage** : Stockage temporaire (git.4nkweb.com/4nk/sdk_storage:ext)
|
|
- **status-api** : API de statut (build: 4NK_web_status)
|
|
|
|
#### Phase 2: Services Blockchain (Séquentiel)
|
|
- **bitcoin** → **blindbit** → **sdk_relay**
|
|
- Chaîne de dépendances blockchain respectée
|
|
|
|
#### Phase 3: Services Applicatifs (Séquentiel)
|
|
- **lecoffre-front** : Frontend Next.js
|
|
- **ihm_client** : Interface utilisateur
|
|
- Dépendances : sdk_relay + sdk_storage
|
|
|
|
#### Phase 4: Services de Monitoring (Indépendant)
|
|
- **loki** → **promtail** → **grafana**
|
|
- Chaîne de dépendances monitoring
|
|
|
|
#### Phase 5: Services Utilitaires
|
|
- **watchtower** : Mise à jour automatique (interval: 30s)
|
|
|
|
## 🔐 Sécurité et Configuration Détaillée
|
|
|
|
### 4NK_vault - Gestion Centralisée des Configurations
|
|
- **Rôle** : API sécurisée pour la gestion des configurations
|
|
- **Sécurité** :
|
|
- Chiffrement quantique résistant (ChaCha20-Poly1305)
|
|
- Authentification par clés utilisateur
|
|
- Rotation automatique des clés (toutes les heures)
|
|
- Isolation par environnement (dev, prod)
|
|
- **Déploiement** : Synchronise vers `confs/` dans le docker de contrôle
|
|
- **Protection des secrets** : Fichiers .env inaccessibles, variables séparées
|
|
|
|
### Variables d'Environnement par Service
|
|
- **bitcoin** : BITCOIN_RPC_USER, BITCOIN_RPC_PASSWORD, BITCOIN_RPC_PORT
|
|
- **blindbit** : BLINDBIT_API_PORT, BITCOIN_RPC_URL
|
|
- **sdk_relay** : RELAY_PORT, RELAY_HTTP_PORT, STORAGE_URL
|
|
- **sdk_storage** : STORAGE_PORT, STORAGE_DATA_DIR
|
|
- **lecoffre-front** : NEXT_PUBLIC_API_URL, NEXT_PUBLIC_4NK_URL, NEXT_PUBLIC_IDNOT_BASE_URL
|
|
- **ihm_client** : VITE_API_URL, VITE_4NK_URL, VITE_RELAY_URL
|
|
- **grafana** : GF_SECURITY_ADMIN_PASSWORD, GF_DATABASE_TYPE
|
|
- **loki** : LOKI_CONFIG_FILE, LOKI_DATA_DIR
|
|
- **promtail** : PROMTAIL_CONFIG_FILE, LOKI_URL
|
|
- **status-api** : STATUS_API_PORT, STATUS_API_HOST
|
|
|
|
## 📊 Monitoring et Observabilité Détaillée
|
|
|
|
### Stack de Monitoring
|
|
- **Grafana** (grafana/grafana:latest) : Dashboards et visualisation
|
|
- **Loki** (grafana/loki:latest) : Collecte et stockage des logs
|
|
- **Promtail** (grafana/promtail:latest) : Agent de collecte des logs
|
|
- **Watchtower** (containrrr/watchtower) : Mise à jour automatique
|
|
|
|
### Configuration Loki (CRITIQUE)
|
|
- **OBLIGATOIRE** : `http_listen_address: 0.0.0.0` (pas 127.0.0.1)
|
|
- **OBLIGATOIRE** : `instance_addr: 0.0.0.0` (pas 127.0.0.1)
|
|
- **Fichier** : `/conf/loki/loki-config.yaml`
|
|
- **Healthcheck** : `wget` (pas `curl`)
|
|
|
|
### Dashboards Disponibles
|
|
- Vue d'ensemble LeCoffre
|
|
- Bitcoin & Miner
|
|
- Services Applications
|
|
- SDK Services
|
|
- Frontend Services
|
|
|
|
### Logs Centralisés
|
|
- **Répertoire** : `/home/debian/4NK_env/projects/lecoffre/lecoffre_node/logs/`
|
|
- **Services** : tor, bitcoin, blindbit, sdk_relay, sdk_storage, lecoffre-front, ihm_client, grafana, loki, promtail, status-api
|
|
- **Collecte** : Promtail → Loki → Grafana
|
|
|
|
## 🔄 CI/CD et Déploiement Détaillé
|
|
|
|
### Branches et Tags
|
|
- **Branche unifiée** : `ext` pour tous les dépôts 4NK
|
|
- **Branches spéciales** : `main` pour 4NK_certificator, 4NK_miner, 4NK_web_status
|
|
- **Tag Docker** : `ext` pour toutes les images
|
|
- **Déclenchement** : Push sur `ext` → Build automatique
|
|
|
|
### Scripts de Déploiement Détaillés
|
|
- **start.sh** : Démarrage complet avec phases et progression
|
|
- **validate-deployment.sh** : Validation complète du déploiement
|
|
- **maintenance.sh** : Menu de maintenance interactif
|
|
- **backup-data.sh** : Sauvegarde des données
|
|
- **update-images.sh** : Mise à jour sécurisée
|
|
- **collect-logs.sh** : Collecte des logs
|
|
- **deploy-grafana.sh** : Déploiement du monitoring
|
|
- **sync-configs.sh** : Synchronisation des configurations
|
|
|
|
### Healthchecks Détaillés
|
|
- **tor** : tor-progress.sh (bootstrap %)
|
|
- **bitcoin** : bitcoin-progress.sh (IBD, blocks, headers)
|
|
- **blindbit** : blindbit-progress.sh (API, scan)
|
|
- **sdk_relay** : sdk-relay-progress.sh (WebSocket, health)
|
|
- **sdk_storage** : curl /health
|
|
- **lecoffre-front** : ps aux | grep next-server
|
|
- **ihm_client** : curl localhost:3003
|
|
- **grafana** : curl /api/health
|
|
- **loki** : wget /ready
|
|
- **promtail** : fichier positions.yaml
|
|
- **status-api** : curl /api
|
|
|
|
## 🎯 Points Clés de l'Architecture Approfondie
|
|
|
|
### 1. **Séparation des Responsabilités**
|
|
- Services applicatifs indépendants du monitoring
|
|
- Monitoring observant sans impacter
|
|
- Dépendances uniquement métier
|
|
|
|
### 2. **Sécurité Multi-Niveaux**
|
|
- 4NK_vault pour la gestion centralisée des configurations
|
|
- Chiffrement quantique résistant
|
|
- Isolation des secrets et variables
|
|
- Utilisateurs non-root dans les conteneurs
|
|
|
|
### 3. **Déploiement Optimisé**
|
|
- Phases de démarrage respectées
|
|
- Scripts spécialisés obligatoires
|
|
- Surveillance continue et diagnostic facilité
|
|
- Healthchecks informatifs
|
|
|
|
### 4. **Maintenance Facilitée**
|
|
- Redémarrage sélectif possible
|
|
- Scripts de maintenance interactifs
|
|
- Documentation centralisée et à jour
|
|
- Logs centralisés et structurés
|
|
|
|
### 5. **Architecture Modulaire**
|
|
- 13 modules 4NK avec rôles spécialisés
|
|
- Projet LeCoffre : Interface notariale
|
|
- 4NK_vault : Gestion centralisée des configurations
|
|
- Scripts centralisés et réutilisables
|
|
|
|
---
|
|
|
|
**Document créé le 2025-01-27**
|
|
**Version** : 2.0
|
|
**Usage** : Analyse architecturale approfondie pour les agents IA et l'équipe de développement
|