407 lines
15 KiB
Markdown
407 lines
15 KiB
Markdown
# Référence Technique Complète - 4NK Environment
|
|
|
|
**Date** : 2025-01-27
|
|
**Version** : 2.0
|
|
**Contexte** : Référence technique complète pour les développeurs et agents IA
|
|
|
|
## 📋 Vue d'ensemble Technique
|
|
|
|
Cette référence technique présente tous les détails techniques de l'environnement 4NK, incluant les configurations, dépendances, ports, et interfaces.
|
|
|
|
## 🔧 Modules 4NK - Référence Technique Complète
|
|
|
|
### 1. **sdk_relay** - Service de Relais WebSocket Central
|
|
**Technologie** : Rust (tokio, async-trait, futures-util)
|
|
**Ports** : 8090 (WebSocket), 8091 (HTTP health)
|
|
**Dépendances Rust** :
|
|
```toml
|
|
anyhow = "1.0"
|
|
async-trait = "0.1"
|
|
bitcoincore-rpc = { version = "0.18" }
|
|
env_logger = "0.9"
|
|
futures-util = { version = "0.3.28", default-features = false, features = ["sink", "std"] }
|
|
hex = "0.4.3"
|
|
log = "0.4.20"
|
|
sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", rev = "e205229e", features = ["parallel", "blindbit-backend"] }
|
|
serde = { version = "1.0.193", features = ["derive"]}
|
|
serde_json = "1.0"
|
|
serde_with = "3.6.0"
|
|
tokio = { version = "1.0.0", features = ["io-util", "rt-multi-thread", "macros", "sync"] }
|
|
tokio-stream = "0.1"
|
|
tokio-tungstenite = "0.21.0"
|
|
zeromq = "0.4.1"
|
|
```
|
|
**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>`
|
|
**Configuration** : Fichier de configuration via `--config`
|
|
**Healthcheck** : `/health` sur port 8091
|
|
**Variables d'environnement** : RELAY_PORT, RELAY_HTTP_PORT, STORAGE_URL
|
|
|
|
### 2. **sdk_storage** - Service de Stockage Temporaire Sécurisé
|
|
**Technologie** : Rust (tide, async-std)
|
|
**Port** : 8081 (mappé depuis 8080)
|
|
**Dépendances Rust** :
|
|
```toml
|
|
tide = "0.16"
|
|
async-std = { version = "1", features = ["attributes"] }
|
|
serde = { version = "1", features = ["derive"] }
|
|
serde_json = "1"
|
|
hex = "0.4"
|
|
env_logger = "0.10"
|
|
```
|
|
**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
|
|
**Healthcheck** : `/health` sur port 8080
|
|
**Variables d'environnement** : STORAGE_PORT, STORAGE_DATA_DIR
|
|
|
|
### 3. **sdk_signer** - Service de Signature TypeScript
|
|
**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
|
|
**Dépendances** : Node.js 18+, npm/yarn
|
|
**Architecture** : TypeScript avec support WASM
|
|
**État** : Compatible avec stub sdk_client
|
|
|
|
### 4. **sdk_client** - Client SDK Rust/WASM
|
|
**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
|
|
**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
|
|
**Technologie** : TypeScript
|
|
**Fonctionnalités** :
|
|
- Interface avec sdk_signer
|
|
- Gestion des signatures
|
|
- Communication sécurisée
|
|
**Architecture** : TypeScript client
|
|
|
|
### 7. **ihm_client** - Interface Homme-Machine
|
|
**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 d'environnement** :
|
|
- 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
|
|
**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
|
|
**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
|
|
**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
|
|
**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
|
|
**Variables d'environnement** : STATUS_API_PORT, STATUS_API_HOST
|
|
|
|
### 12. **blindbit-oracle** - Oracle Bitcoin 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
|
|
**Variables d'environnement** : BLINDBIT_API_PORT, BITCOIN_RPC_URL
|
|
|
|
### 13. **rust-silentpayments** - Implémentation 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 - Référence Technique Complète
|
|
|
|
### 1. **lecoffre_node** - Orchestrateur Principal
|
|
**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
|
|
**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 d'environnement** :
|
|
- 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é
|
|
**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 - Référence Technique
|
|
|
|
### 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 - Référence Technique
|
|
|
|
### 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é - Référence Technique
|
|
|
|
### 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 - Référence Technique
|
|
|
|
### 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 Technique
|
|
|
|
### 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** : Référence technique complète pour les développeurs et agents IA
|