4nk/anchorage_layer_simple
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
anchorage_layer_simple/docs/MAINTENANCE.md
ncantu 937646cc45 Daily backup to git cron, backup/restore scripts, docs 
**Motivations:**
- Export Signet and mining wallet backups to git with only 2 versions kept
- Document and add backup/restore scripts for signet and mining wallet

**Correctifs:**
- Backup-to-git uses SSH URL for passwordless cron; copy timestamped files only; prune to 2 versions; remove *-latest from backup repo

**Evolutions:**
- data/backup-to-git-cron.sh: daily export to git.4nkweb.com/4nk/backup
- save-signet-datadir-backup.sh, restore-signet-from-backup.sh, export-mining-wallet.sh, import-mining-wallet.sh
- features/backup-to-git-daily-cron.md, docs/MAINTENANCE.md backup section
- .gitignore: data/backup-to-git.log

**Pages affectées:**
- .gitignore, data/backup-to-git-cron.sh, docs/MAINTENANCE.md, features/backup-to-git-daily-cron.md
- save-signet-datadir-backup.sh, restore-signet-from-backup.sh, export-mining-wallet.sh, import-mining-wallet.sh
- Plus autres fichiers modifiés ou non suivis déjà présents dans le working tree
2026-02-04 03:07:57 +01:00

1067 lines
34 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Documentation de Maintenance - Bitcoin Signet Custom
**Auteur** : Équipe 4NK
**Date** : 2026-01-09
**Version** : 1.0
## Table des Matières
1. [Vue d'Ensemble](#vue-densemble)
2. [Architecture](#architecture)
3. [Configuration](#configuration)
4. [Commandes de Maintenance](#commandes-de-maintenance)
5. [Gestion du Conteneur](#gestion-du-conteneur)
6. [Gestion des Clés et du Signet](#gestion-des-clés-et-du-signet)
7. [Mining](#mining)
8. [Accès RPC et API](#accès-rpc-et-api)
9. [Mise à Jour](#mise-à-jour)
10. [Dépannage](#dépannage)
11. [Modifications Apportées](#modifications-apportées)
12. [Sauvegarde et Restauration](#sauvegarde-et-restauration)
---
## Vue d'Ensemble
Ce projet installe et configure un Bitcoin Signet custom basé sur le dépôt [Easepay/easepay-custom-signet](https://github.com/Easepay/easepay-custom-signet.git).
Un Signet est un réseau de test Bitcoin qui permet de tester des applications Bitcoin sans risquer de fonds réels et sans l'imprévisibilité du testnet public.
### Caractéristiques
- **Version Bitcoin Core** : 30.2
- **Type de Wallet** : Descriptor wallets (legacy wallets non supportés depuis Bitcoin Core 30+)
- **Réseau** : Signet custom
- **Mining** : Activé avec délai configurable
- **Containerisation** : Docker
- **Base OS** : Debian Bookworm
---
## Architecture
### Structure des Fichiers
```
bitcoin/
├── Dockerfile # Image Docker avec Bitcoin Core
├── docker-entrypoint.sh # Point d'entrée du conteneur
├── install.sh # Script d'installation initiale
├── run.sh # Script de démarrage du nœud
├── setup-signet.sh # Configuration du signet
├── gen-signet-keys.sh # Génération des clés du signet
├── gen-bitcoind-conf.sh # Génération de bitcoin.conf
├── mine.sh # Script de mining
├── mine-genesis.sh # Mining du bloc genesis
├── logtail.sh # Visualisation des logs
├── rpcauth.py # Génération d'authentification RPC
├── miner # Script Python de mining
├── miner_imports/ # Imports pour le miner
├── .env # Variables d'environnement
├── env.example # Exemple de configuration
└── docs/ # Documentation
```
### Ports Exposés
| Port | Protocole | Service | Description |
|------|-----------|---------|-------------|
| 3010 | HTTP/HTTPS | API REST | API d'ancrage (via nginx) - **Port fixe** |
| 3015 | HTTP/HTTPS | Web | Mempool (explorateur blockchain) |
| 3020 | HTTP/HTTPS | Web | Dashboard de supervision - **Port fixe** |
| 3021 | HTTP/HTTPS | API REST | API Faucet - **Port fixe** |
| 3022 | HTTP/HTTPS | API REST | API Filigrane - **Port fixe** |
| 3023 | HTTP/HTTPS | API REST | API ClamAV (antivirus) - **Port fixe** |
| 38332 | TCP | RPC | Interface JSON-RPC pour contrôler le nœud |
| 38333 | TCP/UDP | P2P | Réseau peer-to-peer Bitcoin Signet |
| 28332 | TCP | ZMQ | Publication des blocs bruts |
| 28333 | TCP | ZMQ | Publication des transactions brutes |
| 28334 | TCP | ZMQ | Publication des hash de blocs |
| 8999 | HTTP | API REST | Mempool Backend API (interne) |
**Note :** Les ports des APIs (3010, 3020, 3021, 3022, 3023) sont fixes et définis dans les services systemd. Voir [DOMAINS_AND_PORTS.md](./DOMAINS_AND_PORTS.md) pour plus de détails.
### Répertoires Importants dans le Conteneur
- `/root/.bitcoin/` : Répertoire de données Bitcoin
- `signet/` : Données de la chaîne signet
- `bitcoin.conf` : Configuration du nœud (générée par `gen-bitcoind-conf.sh` ; référence : [SIGNET-CUSTOM-CONFIG.md](./SIGNET-CUSTOM-CONFIG.md))
- `PRIVKEY.txt` : Clé privée du signer
- `SIGNETCHALLENGE.txt` : Challenge du signet
- `MAGIC.txt` : Magic number du réseau
- `install_done` : Marqueur d'installation complète
---
## Configuration
### Fichier `.env`
Le fichier `.env` contient toutes les variables de configuration nécessaires au fonctionnement du signet.
#### Variables de Mining
```bash
# Délai entre la génération de chaque bloc (en secondes)
BLOCKPRODUCTIONDELAY=600
# Activer le mining (1 = activé, 0 = désactivé)
MINERENABLED=1
# Difficulté minimale pour le mining (format hexadécimal)
NBITS=1e0377ae
# Clé privée du signer (générée automatiquement si vide)
PRIVKEY=cVCKcgQf2ewV5miairzhrHJCPv4kMbMMBZeJvW5SMhFMSWVtCvXS
# Adresse de minage (générée automatiquement si vide)
MINETO=
# Challenge du signet (généré automatiquement si vide)
SIGNETCHALLENGE=5121028b8d4cea1b3d8582babc8405bc618fbbb281c0f64e6561aa85968251931cd0a651ae
```
#### Variables RPC
```bash
# Utilisateur RPC
RPCUSER=bitcoin
# Mot de passe RPC
RPCPASSWORD=bitcoin
```
#### Variables ZMQ
```bash
# Publication des blocs bruts
ZMQPUBRAWBLOCK=tcp://0.0.0.0:28332
# Publication des transactions brutes
ZMQPUBRAWTX=tcp://0.0.0.0:28333
# Publication des hash de blocs
ZMQPUBHASHBLOCK=tcp://0.0.0.0:28334
```
#### Variables Réseau
```bash
# Commentaire User-Agent
UACOMMENT=CustomSignet
# Binding RPC
RPCBIND=0.0.0.0:38332
# IPs autorisées pour RPC
RPCALLOWIP=0.0.0.0/0
# IPs whitelistées
WHITELIST=0.0.0.0/0
# Nœuds à ajouter (séparés par des virgules)
ADDNODE=
# IP externe (pour l'annonce publique)
EXTERNAL_IP=
```
### Génération des Clés
Les clés sont générées automatiquement lors de la première installation si `PRIVKEY` et `SIGNETCHALLENGE` sont vides dans le `.env`.
**Important** : Une fois générées, ces clés doivent être conservées et partagées avec les autres nœuds qui souhaitent rejoindre le même signet.
---
## Commandes de Maintenance
### Vérification de l'État
```bash
# Vérifier que le conteneur est en cours d'exécution
sudo docker ps | grep bitcoin-signet
# Vérifier l'état de la blockchain
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo
# Vérifier l'état du réseau
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnetworkinfo
# Vérifier l'état du wallet
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getwalletinfo
# Vérifier les processus en cours
sudo docker exec bitcoin-signet-instance ps aux | grep -E "(bitcoind|mine)"
```
### Logs
```bash
# Voir les logs en temps réel
sudo docker logs -f bitcoin-signet-instance
# Voir les derniers logs
sudo docker logs bitcoin-signet-instance --tail 50
# Voir les logs de debug Bitcoin
sudo docker exec bitcoin-signet-instance tail -f /root/.bitcoin/signet/debug.log
```
### Accès au Conteneur
```bash
# Accéder au shell du conteneur
sudo docker exec -it bitcoin-signet-instance bash
# Exécuter bitcoin-cli depuis l'hôte
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin <commande>
```
---
## Gestion du Conteneur
### Persistance du datadir (chaîne Bitcoin)
**Important :** Sans volume persistant, la recréation du conteneur (`docker rm` puis `docker run`) supprime les données Bitcoin et le nœud repart sur une **nouvelle chaîne** (hauteur 0). Pour conserver la chaîne (ex. hauteur ~11530), utilisez **toujours** un volume persistant.
**Volume par défaut (chaîne complète) :** Le script `update-signet.sh` utilise par défaut le volume contenant la chaîne Signet complète (~11530 blocs) s'il existe sur la machine : volume Docker d'ID **4b5dca4d940b9f6e5db67b460f40f230a5ef1195a3769e5f91fa02be6edde649** (variable `SIGNET_VOLUME_FULL_CHAIN` dans le script). Ainsi, après une mise à jour ou un redémarrage via `update-signet.sh`, le nœud repart sur la bonne chaîne sans recherche. Si ce volume n'existe pas, le script utilise le volume nommé `signet-bitcoin-data`.
- **Volume « chaîne complète »** (prioritaire si présent) : ID `4b5dca4d940b9f6e5db67b460f40f230a5ef1195a3769e5f91fa02be6edde649`
- **Volume nommé** (sinon) : `-v signet-bitcoin-data:/root/.bitcoin`
- **Montage host** : `-v /chemin/sur/hote/signet-data:/root/.bitcoin` (créer le répertoire avant)
**Sauvegarde prête à télécharger :** `backups/signet-datadir-latest.tar.gz` (symlink vers la dernière archive créée par `./save-signet-datadir-backup.sh`). À utiliser pour restaurer la chaîne sur une autre machine ou après perte du volume. Voir [Sauvegarde et Restauration](#sauvegarde-et-restauration).
Les commandes `docker run` ci-dessous utilisent le volume approprié (voir `update-signet.sh` pour la logique par défaut).
### Démarrage
```bash
cd /home/ncantu/Bureau/code/bitcoin
sudo docker run --env-file .env -d \
--name bitcoin-signet-instance \
-v signet-bitcoin-data:/root/.bitcoin \
-p 38332:38332 \
-p 38333:38333 \
-p 28332:28332 \
-p 28333:28333 \
-p 28334:28334 \
bitcoin-signet
```
### Arrêt
```bash
# Arrêter le conteneur
sudo docker stop bitcoin-signet-instance
# Arrêter et supprimer le conteneur
sudo docker stop bitcoin-signet-instance && sudo docker rm bitcoin-signet-instance
```
### Redémarrage
```bash
# Redémarrer le conteneur
sudo docker restart bitcoin-signet-instance
# Redémarrer après modification du .env
sudo docker stop bitcoin-signet-instance
sudo docker rm bitcoin-signet-instance
sudo docker run --env-file .env -d --name bitcoin-signet-instance \
-v signet-bitcoin-data:/root/.bitcoin \
-p 38332:38332 -p 38333:38333 -p 28332:28332 -p 28333:28333 -p 28334:28334 \
bitcoin-signet
```
### Reconstruction de l'Image
```bash
cd /home/ncantu/Bureau/code/bitcoin
sudo docker build -t bitcoin-signet .
```
---
## Gestion des Clés et du Signet
### Récupération des Clés Générées
```bash
# Récupérer la clé privée
sudo docker exec bitcoin-signet-instance cat /root/.bitcoin/PRIVKEY.txt
# Récupérer le challenge du signet
sudo docker exec bitcoin-signet-instance cat /root/.bitcoin/SIGNETCHALLENGE.txt
# Récupérer le magic number
sudo docker exec bitcoin-signet-instance cat /root/.bitcoin/MAGIC.txt
```
### Mise à Jour du `.env` avec les Clés
```bash
# Mettre à jour PRIVKEY dans .env
PRIVKEY=$(sudo docker exec bitcoin-signet-instance cat /root/.bitcoin/PRIVKEY.txt)
sed -i "s/^PRIVKEY=.*/PRIVKEY=$PRIVKEY/" .env
# Mettre à jour SIGNETCHALLENGE dans .env
SIGNETCHALLENGE=$(sudo docker exec bitcoin-signet-instance cat /root/.bitcoin/SIGNETCHALLENGE.txt)
sed -i "s/^SIGNETCHALLENGE=.*/SIGNETCHALLENGE=$SIGNETCHALLENGE/" .env
```
### Partage du Signet avec d'Autres Nœuds
Pour qu'un autre nœud rejoigne le même signet, il doit avoir dans son `.env` :
1. Le même `SIGNETCHALLENGE`
2. Le même `PRIVKEY` (si mining activé)
3. L'adresse IP du nœud dans `ADDNODE` (ex: `ADDNODE=192.168.1.100:38333`)
---
## Mining
### Configuration du Mining
Le mining est contrôlé par les variables suivantes dans `.env` :
- `MINERENABLED=1` : Active le mining
- `BLOCKPRODUCTIONDELAY=600` : Délai en secondes entre chaque bloc (600 = 10 minutes)
- `NBITS=1e0377ae` : Difficulté minimale (ne pas modifier sauf nécessité)
- `MINETO=` : Adresse de minage (vide = nouvelle adresse par bloc)
- `PRIVKEY` : Clé privée du signer (importée automatiquement dans le descriptor wallet)
**Note Bitcoin Core 30+** : La PRIVKEY est automatiquement importée dans le descriptor wallet au démarrage via `importdescriptors`. Cette importation est nécessaire car le miner utilise `walletprocesspsbt` pour signer les blocs, ce qui nécessite que la clé soit dans le wallet.
### Modification Dynamique du Délai
Pour modifier le délai de production de blocs sans redémarrer :
```bash
# Modifier le délai à 60 secondes (1 minute)
sudo docker exec bitcoin-signet-instance bash -c "echo 60 > /root/.bitcoin/BLOCKPRODUCTIONDELAY.txt"
```
Le script `mine.sh` lit automatiquement ce fichier s'il existe.
### Vérification du Mining
```bash
# Vérifier que le script de mining est actif
sudo docker exec bitcoin-signet-instance ps aux | grep mine.sh
# Voir les logs de mining
sudo docker logs bitcoin-signet-instance | grep -E "(Mine|Delay|block)"
# Vérifier le dernier bloc miné
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getbestblockhash
```
### Arrêt du Mining
Pour arrêter le mining, modifier `.env` :
```bash
MINERENABLED=0
```
Puis redémarrer le conteneur.
---
## Maintenance des Services Systemd
### Services Disponibles
Tous les services APIs sont gérés par systemd avec redémarrage automatique :
| Service | Description | Port | Fichier de Service |
|---------|-------------|------|-------------------|
| `anchorage-api` | API d'Ancrage | 3010 | `api-anchorage/anchorage-api.service` |
| `signet-dashboard` | Dashboard | 3020 | `signet-dashboard/signet-dashboard.service` |
| `faucet-api` | API Faucet | 3021 | `api-faucet/faucet-api.service` |
| `filigrane-api` | API Filigrane | 3022 | `api-filigrane/filigrane-api.service` |
| `clamav-api` | API ClamAV | 3023 | `api-clamav/clamav-api.service` |
### Installation des Services
```bash
# Installer tous les services
sudo cp api-anchorage/anchorage-api.service /etc/systemd/system/
sudo cp signet-dashboard/signet-dashboard.service /etc/systemd/system/
sudo cp api-faucet/faucet-api.service /etc/systemd/system/
sudo cp api-filigrane/filigrane-api.service /etc/systemd/system/
sudo cp api-clamav/clamav-api.service /etc/systemd/system/
# Recharger systemd
sudo systemctl daemon-reload
# Activer les services (démarrage automatique au boot)
sudo systemctl enable anchorage-api
sudo systemctl enable signet-dashboard
sudo systemctl enable faucet-api
sudo systemctl enable filigrane-api
sudo systemctl enable clamav-api
# Démarrer les services
sudo systemctl start anchorage-api
sudo systemctl start signet-dashboard
sudo systemctl start faucet-api
sudo systemctl start filigrane-api
sudo systemctl start clamav-api
```
### Gestion des Services
```bash
# Vérifier le statut d'un service
sudo systemctl status <service-name>
# Démarrer un service
sudo systemctl start <service-name>
# Arrêter un service
sudo systemctl stop <service-name>
# Redémarrer un service
sudo systemctl restart <service-name>
# Voir les logs en temps réel
sudo journalctl -u <service-name> -f
# Voir les derniers logs
sudo journalctl -u <service-name> -n 100
# Voir les logs depuis une date
sudo journalctl -u <service-name> --since "2026-01-24 10:00:00"
```
### Vérification de Tous les Services
```bash
# Vérifier le statut de tous les services
sudo systemctl status anchorage-api signet-dashboard faucet-api filigrane-api clamav-api
# Vérifier que tous les ports sont en écoute
sudo ss -tlnp | grep -E ':(3010|3020|3021|3022|3023)'
# Tester les endpoints de santé
curl http://localhost:3010/health
curl http://localhost:3020/health
curl http://localhost:3021/health
curl http://localhost:3022/health
curl http://localhost:3023/health
```
### Redémarrage Automatique
Tous les services sont configurés avec `Restart=always` et `RestartSec=10`, ce qui signifie :
- Redémarrage automatique en cas d'échec
- Délai de 10 secondes avant redémarrage
- Redémarrage au boot du système
### Ports Fixes
**Important :** Tous les ports sont fixes et définis dans les services systemd :
- Les ports ne peuvent pas être modifiés sans modifier les services
- Les variables d'environnement dans les services ont priorité sur les fichiers `.env`
- Voir [DOMAINS_AND_PORTS.md](./DOMAINS_AND_PORTS.md) pour plus de détails
### Mise à Jour d'un Service
```bash
# 1. Arrêter le service
sudo systemctl stop <service-name>
# 2. Mettre à jour le code (via git, etc.)
cd /home/ncantu/Bureau/code/bitcoin/<api-directory>
git pull
# 3. Installer les dépendances si nécessaire
npm install
# 4. Redémarrer le service
sudo systemctl start <service-name>
# 5. Vérifier les logs
sudo journalctl -u <service-name> -f
```
### Dépannage des Services
```bash
# Si un service ne démarre pas
# 1. Vérifier les logs
sudo journalctl -u <service-name> -n 50
# 2. Vérifier que le port n'est pas déjà utilisé
sudo ss -tlnp | grep :<port>
# 3. Vérifier les permissions
ls -la /home/ncantu/Bureau/code/bitcoin/<api-directory>
# 4. Vérifier que Node.js est installé
which node
node --version
# 5. Tester manuellement
cd /home/ncantu/Bureau/code/bitcoin/<api-directory>
./start.sh
```
### Logs et Monitoring
```bash
# Voir tous les logs de tous les services
sudo journalctl -u anchorage-api -u signet-dashboard -u faucet-api -u filigrane-api -u clamav-api -f
# Voir les erreurs uniquement
sudo journalctl -u <service-name> -p err
# Exporter les logs
sudo journalctl -u <service-name> --since "2026-01-24" > logs-<service-name>.txt
```
Pour plus de détails sur les domaines, ports et configuration, voir :
- [DOMAINS_AND_PORTS.md](./DOMAINS_AND_PORTS.md)
- [ENVIRONMENT.md](./ENVIRONMENT.md)
---
## Accès RPC et API
### Commandes RPC Courantes
```bash
# Obtenir des informations sur la blockchain
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo
# Obtenir des informations sur le réseau
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnetworkinfo
# Obtenir des informations sur le wallet
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getwalletinfo
# Obtenir le solde
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getbalance
# Obtenir une nouvelle adresse
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnewaddress
# Obtenir la liste des transactions
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin listtransactions
# Obtenir le dernier bloc
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getbestblockhash
# Obtenir un bloc spécifique
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblock <hash>
```
### Accès RPC depuis l'Extérieur
Pour accéder au RPC depuis un autre hôte, utiliser :
```bash
bitcoin-cli -rpcconnect=<IP_DU_SERVEUR> -rpcport=38332 \
-rpcuser=bitcoin -rpcpassword=bitcoin \
getblockchaininfo
```
**Sécurité** : En production, restreindre `RPCALLOWIP` dans `.env` et utiliser une authentification plus forte.
### ZMQ
Les notifications ZMQ sont disponibles sur les ports 28332, 28333, 28334.
Exemple avec Python :
```python
import zmq
context = zmq.Context()
socket = context.socket(zmq.SUB)
socket.connect("tcp://localhost:28332")
socket.setsockopt(zmq.SUBSCRIBE, b"rawblock")
while True:
message = socket.recv()
print(f"New block: {message.hex()}")
```
---
## Mise à Jour
### Script de Mise à Jour Automatique
Un script de mise à jour automatique est disponible : `update-signet.sh`
#### Utilisation
```bash
# Mise à jour vers la dernière version disponible
./update-signet.sh
# Mise à jour vers une version spécifique
./update-signet.sh 30.2
# Aide
./update-signet.sh --help
```
#### Fonctionnalités du Script
Le script `update-signet.sh` effectue automatiquement :
1. **Vérification des prérequis** : Docker, fichier `.env`
2. **Détection de la version actuelle** : Depuis `.bitcoin-version` ou le Dockerfile
3. **Récupération de la dernière version** : Depuis les sources officielles Bitcoin
4. **Sauvegarde automatique** : Données du conteneur et fichier `.env`
5. **Mise à jour du Dockerfile** : Modification de la version Bitcoin Core
6. **Reconstruction de l'image** : Build de la nouvelle image Docker
7. **Redémarrage du conteneur** : Arrêt propre et redémarrage avec la nouvelle version (volume **signet-bitcoin-data** pour une seule chaîne Mempool/dashboard/APIs)
8. **Vérification post-mise à jour** : Contrôle de l'état du nœud
#### Procédure Manuelle de Mise à Jour
Si vous préférez effectuer la mise à jour manuellement :
##### 1. Vérifier la Version Actuelle
```bash
# Version dans le Dockerfile
grep BITCOIN_VERSION Dockerfile
# Version enregistrée
cat .bitcoin-version 2>/dev/null || echo "Non enregistrée"
# Version en cours d'exécution
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnetworkinfo | grep subversion
```
##### 2. Récupérer la Dernière Version
Consultez les sources officielles :
- [Bitcoin Core Releases](https://bitcoincore.org/en/download/)
- [GitHub Releases](https://github.com/bitcoin/bitcoin/releases)
##### 3. Sauvegarder les Données
```bash
# Créer un répertoire de sauvegarde
mkdir -p backups
# Sauvegarder les données du conteneur
sudo docker exec bitcoin-signet-instance tar czf /tmp/bitcoin-backup.tar.gz /root/.bitcoin/
sudo docker cp bitcoin-signet-instance:/tmp/bitcoin-backup.tar.gz backups/signet-backup-$(date +%Y%m%d-%H%M%S).tar.gz
# Sauvegarder le .env
cp .env backups/.env.backup-$(date +%Y%m%d-%H%M%S)
```
##### 4. Mettre à Jour le Dockerfile
```bash
# Modifier la version dans le Dockerfile
sed -i 's/ARG BITCOIN_VERSION=\${BITCOIN_VERSION:-[0-9]\+\.[0-9]\+}/ARG BITCOIN_VERSION=${BITCOIN_VERSION:-30.2}/' Dockerfile
# Vérifier la modification
grep BITCOIN_VERSION Dockerfile
```
##### 5. Reconstruire l'Image
```bash
# Reconstruire l'image Docker
sudo docker build -t bitcoin-signet .
```
##### 6. Redémarrer le Conteneur
```bash
# Arrêter le conteneur actuel
sudo docker stop bitcoin-signet-instance
sudo docker rm bitcoin-signet-instance
# Démarrer avec la nouvelle image (volume persistant pour conserver la chaîne)
sudo docker run --env-file .env -d \
--name bitcoin-signet-instance \
-v signet-bitcoin-data:/root/.bitcoin \
-p 38332:38332 \
-p 38333:38333 \
-p 28332:28332 \
-p 28333:28333 \
-p 28334:28334 \
bitcoin-signet
```
##### 7. Vérifier la Mise à Jour
```bash
# Attendre quelques secondes pour le démarrage
sleep 10
# Vérifier la version
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnetworkinfo | grep subversion
# Vérifier l'état de la blockchain
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo
# Vérifier les logs
sudo docker logs bitcoin-signet-instance --tail 50
```
##### 8. Enregistrer la Version
```bash
# Enregistrer la nouvelle version
echo "30.2" > .bitcoin-version
```
### Notes Importantes sur les Mises à Jour
#### Compatibilité des Versions
- **Bitcoin Core 26.0+** : Peut avoir des changements de compatibilité avec les wallets legacy
- **Bitcoin Core 30.2** : Version actuelle recommandée
- Vérifiez toujours les [release notes](https://bitcoincore.org/en/releases/) avant de mettre à jour
#### Impact sur le Mining
- Le mining reprend automatiquement après la mise à jour
- Les blocs minés avant la mise à jour restent valides
- Aucune perte de données si la sauvegarde est effectuée
#### Rollback en Cas de Problème
Si la mise à jour pose problème :
```bash
# Restaurer l'ancienne version du Dockerfile
git checkout HEAD -- Dockerfile
# Restaurer les données si nécessaire
sudo docker stop bitcoin-signet-instance
sudo docker rm bitcoin-signet-instance
sudo docker cp backups/signet-backup-YYYYMMDD-HHMMSS.tar.gz bitcoin-signet-instance:/tmp/
sudo docker exec bitcoin-signet-instance tar xzf /tmp/signet-backup-YYYYMMDD-HHMMSS.tar.gz -C /
# Reconstruire avec l'ancienne version
sudo docker build -t bitcoin-signet .
# Redémarrer (volume persistant pour conserver la chaîne)
sudo docker run --env-file .env -d --name bitcoin-signet-instance \
-v signet-bitcoin-data:/root/.bitcoin \
-p 38332:38332 -p 38333:38333 -p 28332:28332 -p 28333:28333 -p 28334:28334 \
bitcoin-signet
```
### Vérification Régulière des Mises à Jour
Pour vérifier régulièrement si une nouvelle version est disponible :
```bash
# Script de vérification
#!/bin/bash
CURRENT=$(cat .bitcoin-version 2>/dev/null || echo "unknown")
LATEST=$(curl -s https://bitcoincore.org/bin/ | grep -oP 'bitcoin-core-\K[0-9]+\.[0-9]+\.[0-9]+' | sort -V | tail -1)
if [ "$CURRENT" != "$LATEST" ]; then
echo "Nouvelle version disponible: $LATEST (actuelle: $CURRENT)"
echo "Exécutez: ./update-signet.sh $LATEST"
else
echo "Déjà à jour: $CURRENT"
fi
```
---
## Dépannage
### Problèmes Courants
#### Le conteneur ne démarre pas
```bash
# Vérifier les logs
sudo docker logs bitcoin-signet-instance
# Vérifier que les ports ne sont pas déjà utilisés
sudo netstat -tlnp | grep -E "(38332|38333|28332|28333|28334)"
# Vérifier que le fichier .env existe
ls -la .env
```
#### Bitcoind ne démarre pas
```bash
# Vérifier les logs de debug
sudo docker exec bitcoin-signet-instance tail -100 /root/.bitcoin/signet/debug.log
# Vérifier la configuration
sudo docker exec bitcoin-signet-instance cat /root/.bitcoin/bitcoin.conf
# Vérifier les permissions
sudo docker exec bitcoin-signet-instance ls -la /root/.bitcoin/
```
#### Le mining ne fonctionne pas
```bash
# Vérifier que MINERENABLED=1 dans .env
grep MINERENABLED .env
# Vérifier que la clé privée est importée
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin listprivkeys
# Vérifier que le script mine.sh est actif
sudo docker exec bitcoin-signet-instance ps aux | grep mine.sh
```
#### Erreur "Cannot obtain a lock"
Cette erreur indique qu'un autre processus bitcoind est déjà en cours d'exécution.
```bash
# Arrêter tous les processus bitcoind dans le conteneur
sudo docker exec bitcoin-signet-instance pkill bitcoind
# Redémarrer le conteneur
sudo docker restart bitcoin-signet-instance
```
#### Le wallet n'existe pas
```bash
# Créer le wallet manuellement (Bitcoin Core 30+ nécessite descriptor wallets)
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin \
-named createwallet wallet_name="custom_signet" load_on_startup=true descriptors=true
# Charger le wallet si nécessaire
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin loadwallet custom_signet
# Importer la clé privée si mining activé (Bitcoin Core 30+ nécessite descriptor wallets)
PRIVKEY=$(cat .env | grep PRIVKEY | cut -d'=' -f2)
DESCRIPTOR_INFO=$(sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getdescriptorinfo "wpkh($PRIVKEY)")
CHECKSUM=$(echo "$DESCRIPTOR_INFO" | jq -r '.checksum')
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin \
importdescriptors "[{\"desc\":\"wpkh($PRIVKEY)#$CHECKSUM\",\"timestamp\":0,\"internal\":false}]"
```
### Réinitialisation Complète
Si vous devez tout réinitialiser :
```bash
# Arrêter et supprimer le conteneur
sudo docker stop bitcoin-signet-instance
sudo docker rm bitcoin-signet-instance
# Supprimer le volume de données (ATTENTION : perte de données)
sudo docker volume rm $(sudo docker volume ls -q | grep bitcoin)
# Ou supprimer manuellement les données
sudo rm -rf /var/lib/docker/volumes/*/bitcoin-signet-instance/_data
# Relancer avec un nouveau .env (clés seront régénérées ; utiliser un nouveau volume ou supprimer signet-bitcoin-data avant)
sudo docker run --env-file .env -d --name bitcoin-signet-instance \
-v signet-bitcoin-data:/root/.bitcoin \
-p 38332:38332 -p 38333:38333 -p 28332:28332 -p 28333:28333 -p 28334:28334 \
bitcoin-signet
```
---
## Modifications Apportées
### Modifications du Dockerfile
1. **Mise à jour de Debian** : `buster-slim` → `bookworm-slim`
- Raison : Debian Buster n'est plus supporté
2. **Détection automatique de l'architecture** : Remplacement de `TARGETPLATFORM` par `uname -m`
- Raison : `TARGETPLATFORM` n'est pas défini par défaut dans `docker build`
3. **Installation de setuptools** : Via `apt` au lieu de `pip`
- Raison : PEP 668 empêche l'installation système via pip
### Modifications des Scripts
1. **gen-signet-keys.sh** :
- Correction de `ATADIR` → `DATADIR` (ligne 1)
- Mise à jour pour utiliser `descriptors=true` (Bitcoin Core 30+)
- Raison : Faute de frappe empêchait la création du répertoire temporaire, et Bitcoin Core 30+ nécessite des descriptor wallets
2. **setup-signet.sh** : Suppression du démarrage de bitcoind
- Raison : Éviter les conflits de verrou, bitcoind est démarré par `run.sh`
3. **run.sh** : Ajout de la création du wallet descriptor et import automatique de la clé privée
- Raison : Le wallet doit être créé après le démarrage de bitcoind
- Bitcoin Core 30+ nécessite des descriptor wallets (legacy wallets non supportés)
- La clé privée est importée automatiquement dans le descriptor wallet pour permettre le mining
- L'import utilise `importdescriptors` avec le checksum requis (obtenu via `getdescriptorinfo`)
- Le miner utilise `walletprocesspsbt` qui nécessite que la clé soit dans le wallet
---
## Sauvegarde et Restauration
### Sauvegarde
**Sauvegarde datadir (chaîne complète, prête à télécharger) :**
```bash
# Créer une archive complète du datadir (blocs + chainstate + config)
./save-signet-datadir-backup.sh
# Crée backups/signet-datadir-YYYYMMDD-HHMMSS.tar.gz et met à jour le symlink :
# backups/signet-datadir-latest.tar.gz -> dernière archive (prête à télécharger)
```
Le symlink `backups/signet-datadir-latest.tar.gz` pointe toujours vers la dernière archive créée ; utile pour téléchargement ou restauration rapide : `./restore-signet-from-backup.sh backups/signet-datadir-latest.tar.gz`.
**Export wallet de minage (réimportable, pour retrouver les fonds sur cette chaîne) :**
```bash
./export-mining-wallet.sh
# Crée backups/mining-wallet-export-YYYYMMDD-HHMMSS.json et mining-wallet-export-latest.json
# Contient : PRIVKEY, SIGNETCHALLENGE, wallet_name, descriptors avec clés privées, infos chaîne
# Réimporter sur un nœud avec la même chaîne :
./import-mining-wallet.sh backups/mining-wallet-export-latest.json
```
**Export quotidien vers git (2 versions conservées) :**
```bash
# Tâche cron quotidienne : exporte signet-datadir et mining-wallet vers
# https://git.4nkweb.com/4nk/backup (2 versions max de chaque)
./data/backup-to-git-cron.sh
# Voir features/backup-to-git-daily-cron.md pour configuration cron
```
**Sauvegarde manuelle :**
```bash
# Sauvegarder les données Bitcoin
sudo docker exec bitcoin-signet-instance tar czf /tmp/bitcoin-backup.tar.gz /root/.bitcoin/
# Copier la sauvegarde hors du conteneur
sudo docker cp bitcoin-signet-instance:/tmp/bitcoin-backup.tar.gz ./bitcoin-backup-$(date +%Y%m%d).tar.gz
# Sauvegarder le fichier .env
cp .env .env.backup-$(date +%Y%m%d)
```
### Restauration
```bash
# Arrêter le conteneur
sudo docker stop bitcoin-signet-instance
sudo docker rm bitcoin-signet-instance
# Créer un nouveau conteneur (volume persistant pour que les données restaurées soient conservées)
sudo docker run --env-file .env -d --name bitcoin-signet-instance \
-v signet-bitcoin-data:/root/.bitcoin \
-p 38332:38332 -p 38333:38333 -p 28332:28332 -p 28333:28333 -p 28334:28334 \
bitcoin-signet
# Attendre que le conteneur démarre
sleep 5
# Restaurer les données
sudo docker cp bitcoin-backup-YYYYMMDD.tar.gz bitcoin-signet-instance:/tmp/
sudo docker exec bitcoin-signet-instance tar xzf /tmp/bitcoin-backup-YYYYMMDD.tar.gz -C /
# Redémarrer le conteneur
sudo docker restart bitcoin-signet-instance
```
### Sauvegarde des Clés
**Important** : Toujours sauvegarder séparément :
- Le fichier `.env` (contient `PRIVKEY` et `SIGNETCHALLENGE`)
- Les fichiers `/root/.bitcoin/PRIVKEY.txt` et `/root/.bitcoin/SIGNETCHALLENGE.txt`
Ces clés sont essentielles pour maintenir la cohérence du signet.
---
## Commandes Utiles
### Vérification de l'alignement Dashboard / Miner / Signet (chaîne ~11535)
Dashboard, miner et signet utilisent **une seule source de vérité** : le nœud Bitcoin Signet dans le conteneur `bitcoin-signet-instance` (RPC port 38332).
| Composant | Source de la hauteur |
|-----------|----------------------|
| **Signet (nœud)** | `bitcoind` dans le conteneur, datadir `/root/.bitcoin` |
| **Dashboard** | RPC `getblockchaininfo` vers `127.0.0.1:38332` (même nœud) |
| **Miner** | S'exécute dans le conteneur, appelle `bitcoin-cli -datadir=/root/.bitcoin` (même nœud) |
| **Mempool** | Backend connecté au même nœud (CORE_RPC_PORT=38332) |
La chaîne attendue est d’environ **11535 blocs**. Pour vérifier que tout est aligné :
1. **Hauteur depuis le nœud** (référence) :
```bash
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo | grep -E '"chain"|"blocks"'
```
Attendu : `"chain": "signet"`, `"blocks":` proche de 11535.
2. **Hauteur depuis le Dashboard** (doit être identique) :
```bash
curl -s http://localhost:3020/api/blockchain/info | grep -o '"blocks":[0-9]*'
```
3. **Miner** : les logs du conteneur affichent la hauteur à chaque bloc miné (`Mined ... at height N`). Cette hauteur est celle du nœud.
Si le Dashboard affiche une hauteur très différente (ex. 2) ou si l’API d’ancrage retourne « Insufficient Balance » (0 BTC), exécuter sur la machine bitcoin : `./fix-dashboard-anchor-chain.sh` (ou avec chemin de backup pour restaurer la chaîne). Voir [fixKnowledge/dashboard-anchor-wrong-chain-insufficient-balance.md](../fixKnowledge/dashboard-anchor-wrong-chain-insufficient-balance.md) et [fixKnowledge/signet-chain-lost-volume-persistent.md](../fixKnowledge/signet-chain-lost-volume-persistent.md).
**Script de test RPC (même nœud que Mempool) :** `./test-mempool-rpc-config.sh [HOST] [PORT]` (défaut 127.0.0.1 38332). **Script de vérification dashboard signet :** `./verify-dashboard-signet.sh` (machine bitcoin, pour que https://dashboard.certificator.4nkweb.com/ affiche le signet custom). **Script de vérification :** exécuter `./verify-chain-alignment.sh` à la racine du projet pour comparer la hauteur du nœud et du Dashboard et vérifier qu’elle est dans la plage attendue (~11535).
### Script de Vérification Rapide
```bash
#!/bin/bash
echo "=== État du Conteneur ==="
sudo docker ps | grep bitcoin-signet
echo -e "\n=== État de la Blockchain ==="
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo | grep -E "(chain|blocks|bestblockhash)"
echo -e "\n=== État du Réseau ==="
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnetworkinfo | grep -E "(networkactive|connections)"
echo -e "\n=== État du Wallet ==="
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getwalletinfo | grep -E "(walletname|balance)"
echo -e "\n=== Processus de Mining ==="
sudo docker exec bitcoin-signet-instance ps aux | grep -E "(bitcoind|mine)" | grep -v grep
```
### Script de Monitoring
```bash
#!/bin/bash
watch -n 5 'sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo | grep -E "(chain|blocks|bestblockhash|difficulty)"'
```
---
## Références
- [Dépôt Source](https://github.com/Easepay/easepay-custom-signet.git)
- [Documentation Bitcoin Signet](https://en.bitcoin.it/wiki/Signet)
- [Bitcoin Core RPC API](https://developer.bitcoin.org/reference/rpc/)
- [Documentation Docker](https://docs.docker.com/)
- [Mempool Documentation](./MEMPOOL.md) : Documentation de l'explorateur blockchain Mempool
---
**Dernière mise à jour** : 2026-02-02
Reference in New Issue View Git Blame Copy Permalink