🖥️ Architecture Raspberry Pi

Documentation technique synthétique de l'infrastructure physique, applicative, réseau et des sauvegardes.

1. Architecture Physique & Système Hôte

🍓 Matériel & OS

Hôte : Raspberry Pi (aarch64)
OS : Debian GNU/Linux 13 (trixie)
Stockage : MicroSD 64 Go (50 Go dispo)

🔒 Sécurité SSH & Système

Root direct : Interdit
Mots de passe : Désactivés
Accès SSH : Clés publiques uniquement
Privilèges API : Exécution en root restreinte au socket Fail2ban

2. Architecture Logicielle & Cartographie des Flux

🌍 Internet / LAN (Clients)

↓ (TCP 80, 443 / UDP 51821)

🛡️ Nginx Proxy Manager

🔑 WireGuard / PiVPN

↓ (Réseau interne Docker : proxy-net)

🔐 Vaultwarden
127.0.0.1:8080

⚡ pi-api (FastAPI)
127.0.0.1:8000

🤖 Telegram Bot
Polling Out

3. Matrice d'Exposition Réseau

Service	Port Externe	Binding Hôte	Isolation / Usage
SSH	`22/TCP`	`0.0.0.0`	Accès restreint Clés SSH publiques
Nginx PM	`80, 443/TCP`	`0.0.0.0`	Public Reverse Proxy & Certificats SSL
WireGuard	`51821/UDP`	`0.0.0.0`	VPN Tunnel d'administration à distance
NPM Admin	`81/TCP`	`127.0.0.1`, `10.100.42.1`	Protégé Interface Web (VPN / Local)
Vaultwarden	`8080/TCP`	`127.0.0.1`	Isolé Accessible via Nginx PM uniquement
pi-api	`8000/TCP`	`127.0.0.1`	Isolé Socket Fail2ban + API système

4. Guides d'Évolution (Extensibilité)

➕ Ajouter un nouvel Endpoint dans pi-api

1Créer le routeur dans app/routers/mon_module.py :

from fastapi import APIRouter

router = APIRouter(prefix="/mon-module", tags=["Mon Module"])

@router.get("/status")
async def get_status():
    return {"status": "ok"}

2Déclarer le routeur dans app/main.py :

from app.routers.mon_module import router as mon_module_router

app.include_router(mon_module_router, dependencies=[Depends(verify_api_key)])

3Reconstruire et relancer :

cd /home/hua/pi-api && docker compose up -d --build

🤖 Ajouter une nouvelle commande dans le Bot Telegram

1Créer le fichier de commande dans commands/ma_commande.py :

import os, httpx
from telegram import Update
from telegram.ext import CommandHandler, ContextTypes
from utils.security import restricted

description = "Description de la commande"
API_URL = os.getenv("PI_API_URL", "http://172.17.0.1:8000")
API_KEY = os.getenv("PI_API_KEY", "")

@restricted
async def ma_commande_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    headers = {"X-API-Key": API_KEY}
    async with httpx.AsyncClient() as client:
        res = await client.get(f"{API_URL}/mon-module/status", headers=headers)
        await update.message.reply_text(f"Résultat : {res.json().get('status')}")

handler = CommandHandler("macommande", ma_commande_callback)

2Reconstruire le bot :

cd /home/hua/bot-telegram-command-handler && docker compose up -d --build

5. Stratégie de Sauvegarde & Restauration (backup_infra.sh)

⚙️ Fonctionnement du Script

Exécution : Quotidienne via Cron
Espace de travail : /tmp (RAM / tmpfs) pour préserver la MicroSD
Base de données : Sauvegarde à chaud SQLite (sqlite3 .backup)
Chiffrement : Archive .tar.gz.gpg chiffrée en AES256
Stockage Distant : Envoi automatique vers Google Drive (rclone) & Telegram
Rétention : 14 jours (garde-fou automatique)

📁 Périmètre d'Archivage

Vaultwarden : DB SQLite + fichiers de données
Nginx PM : DB SQLite + certificats Let's Encrypt
WireGuard : Conf /etc/wireguard & PiVPN
Applications : Code & Envs de pi-api et bot-telegram-command-handler
Système : Scripts, Crontab & clés SSH (/home/hua/.ssh)

🚨 Procédure de Restauration d'Urgence

1Déchiffrer l'archive GPG :

gpg --batch --yes --decrypt --passphrase "TON_MOT_DE_PASSE" -o infra_backup.tar.gz infra_backup_YYYYMMDD_HHMMSS.tar.gz.gpg

2Extraire les données :

tar -xzf infra_backup.tar.gz && cd backup_YYYYMMDD_HHMMSS/

3Restaurer les services :

# Exemple pour Vaultwarden
cp vaultwarden/db.sqlite3 /home/hua/vaultwarden/data/
rsync -az vaultwarden/data_files/ /home/hua/vaultwarden/data/

# Relance des stacks Docker
cd /home/hua/pi-api && docker compose up -d
cd /home/hua/bot-telegram-command-handler && docker compose up -d