Repository Public
1# Exploitation23## Où tournent les choses45| | |6|---|---|7| Site | https://music.spboucher.ai |8| App mld | `sp-music`, épinglée sur son nœud (`mld status`), port 8690 |9| Dépôt (source de vérité) | sur le nœud : `~/apps/sp-music` ; origin spbgit `sp-music.git` |10| Processus PM2 | `sp-music-web` (`tsx server.ts`), `sp-music-worker`, `sp-music-backup` (cron 03:45) |11| Base | PostgreSQL 17 local, base `sp_music`, rôle `spmusic_app` |12| Bibliothèque | `~/data/sp-music/library` (originaux, pochettes, rendus), mode 0700 |13| Sauvegardes | `~/backups/sp-music` |14| Secrets | `~/apps/sp-music/.env` (0600), `~/.config/sp-music/backup-passphrase` |1516## Prérequis du domaine1718- DNS : `A music.spboucher.ai → 51.161.112.61` (passerelle BHS64).19- HTTPS : certificat obtenu et renouvelé par Caddy ; HTTP redirigé vers HTTPS. Route posée par `mld deploy` (`tunnel.domain`).20- Le proxy transmet les corps en flux ; un morceau d'envoi fait 8 Mo (`UPLOAD_MAX_CHUNK_MB` borne le serveur) : garder la limite de corps du proxy au-dessus.21- `APP_URL` doit être exactement `https://music.spboucher.ai` : c'est l'origine que WebAuthn vérifie.2223## Première installation (faite par le déploiement, pour mémoire)2425```bash26# sur le nœud27brew install ffmpeg # ffmpeg + ffprobe28createuser spmusic_app --pwprompt ; createdb -O spmusic_app sp_music29psql -d sp_music -c 'CREATE EXTENSION IF NOT EXISTS citext; CREATE EXTENSION IF NOT EXISTS pg_trgm;'30mkdir -p ~/data/sp-music/library ~/backups/sp-music ~/.config/sp-music && chmod 700 ~/data/sp-music ~/backups/sp-music ~/.config/sp-music31openssl rand -base64 48 > ~/.config/sp-music/backup-passphrase && chmod 600 ~/.config/sp-music/backup-passphrase32cp .env.example .env && chmod 600 .env # remplir APP_SECRET, DATABASE_URL, OWNER_EMAIL, chemins33# depuis le laptop34mld stage <dossier> sp-music && mld deploy sp-music # pnpm install, migrations, bootstrap, build, PM2, route HTTPS35```3637## Créer le propriétaire et inscrire Face ID / Touch ID38391. Le déploiement a créé le compte propriétaire et écrit un lien à usage unique (24 h) :40 `ssh <nœud> cat ~/data/sp-music/setup-url.txt`41 Lien expiré ? `ssh <nœud>` puis `cd ~/apps/sp-music && node_modules/.bin/tsx scripts/setup-token.ts`.422. Ouvrir ce lien **sur l'appareil à inscrire** (iPhone, iPad ou Mac), dans Safari.433. « Créer la clé d'accès » : iOS / macOS affiche sa propre boîte de dialogue et demande Face ID ou Touch ID. Avec le trousseau iCloud activé, la clé est synchronisée sur vos autres appareils Apple.444. Noter les huit codes de récupération (affichés une seule fois) hors ligne.455. Autres appareils : `/compte` → Clés d'accès → Ajouter, depuis une session ouverte ; sur un appareil sans session, le navigateur propose d'utiliser un iPhone à proximité (QR code).466. Installer en PWA : Safari → Partager → « Sur l'écran d'accueil ».4748Auditeurs : `/admin` → Comptes → Nouveau compte → transmettre le lien (72 h, usage unique).4950## Mettre à jour (sur le nœud — remote-first)5152```bash53ssh <nœud> ; cd ~/apps/sp-music54git pull --ff-only # ou éditer sur place55pnpm install --frozen-lockfile56node_modules/.bin/tsx scripts/migrate.ts57node_modules/.bin/next build58pm2 restart sp-music-web sp-music-worker59git add -A && git commit -m "…" && git push origin main60```6162Les migrations sont transactionnelles et ne s'appliquent qu'une fois ; une migration appliquée puis modifiée fait échouer le déploiement (somme de contrôle). Ne jamais `mld move sp-music` sans déplacer la base et la bibliothèque (voir Restauration).6364## Paroles synchronisées (karaoké)6566Les paroles sont transcrites **sur le nœud** à partir de l'audio (mlx-whisper, modèle `whisper-large-v3-turbo`), avec un67horodatage par mot ; rien n'est envoyé à un service externe et aucun site de paroles n'est interrogé.6869```bash70uv venv ~/.venvs/whisper --python 3.12 && uv pip install -p ~/.venvs/whisper mlx-whisper # une fois71# .env : LYRICS=auto (ou manual), LYRICS_PYTHON=$HOME/.venvs/whisper/bin/python72node_modules/.bin/tsx scripts/lyrics.ts --missing --wait # toute la bibliothèque73node_modules/.bin/tsx scripts/lyrics.ts --album "Thriller" --lang en --overwrite74```7576- `LYRICS=auto` met aussi en file chaque nouvel import ; `manual` laisse l'administrateur décider (`/admin` → Bibliothèque → sélection → Paroles).77- La transcription d'une voix chantée sur de la musique reste imparfaite (mots mal entendus, langue mal détectée quand une piste commence par une longue intro : préciser la langue). Chaque ligne se corrige dans `/admin` → Bibliothèque → icône Paroles de la piste ; une correction manuelle n'est jamais écrasée sans demande explicite.78- Une piste sans voix est marquée « instrumental ». Les phrases inventées par le modèle sur du silence (« Thank you », « Sous-titrage… ») sont filtrées (`src/server/lyrics.ts`).7980## Sauvegarde8182`scripts/backup.sh`, chaque nuit (PM2 `sp-music-backup`) :83841. **Base** : `pg_dump` chiffré AES-256 → `~/backups/sp-music/db/sp-music-AAAAmmjj-HHMMSS.dump.enc` (30 jours), relu par `pg_restore --list` à chaque exécution.852. **Bibliothèque** : miroir `rsync` des originaux et des pochettes → `~/backups/sp-music/library/` ; ce qui disparaît de la bibliothèque va dans `trash/<date>/` pendant `BACKUP_TRASH_DAYS` (30). Les rendus et miniatures, dérivés, ne sont pas sauvegardés.863. `last-backup.json` alimente « Dernière sauvegarde » dans `/admin` → Système.8788**À faire par le propriétaire** : cette sauvegarde est sur le même disque que la bibliothèque. Elle protège d'une suppression accidentelle, pas d'une panne du disque. Copie hors nœud, depuis une autre machine :89`rsync -a <nœud>:backups/sp-music/ /chemin/de/sauvegarde/sp-music/` (planifiable ; les processus PM2 du nœud ne peuvent pas joindre le réseau local). Conserver aussi `backup-passphrase` ailleurs : sans elle les dumps sont illisibles.9091## Restauration9293```bash94createdb -O spmusic_app sp_music # base vide95scripts/restore.sh db ~/backups/sp-music/db/<fichier>.dump.enc "$DATABASE_URL"96scripts/restore.sh library ~/backups/sp-music/library ~/data/sp-music/library97node_modules/.bin/tsx scripts/rebuild-derived.ts # vérifie chaque original, refait les miniatures, remet les rendus en file98pm2 restart sp-music-web sp-music-worker99```100101`rebuild-derived.ts` sort en erreur et liste tout original manquant. Les clés d'accès sont liées au domaine, pas au nœud : elles restent valides après une restauration tant que `APP_URL` / RP ID ne changent pas. La procédure est exécutée par `pnpm test` à chaque passage.102103## Dépannage104105| Symptôme | Cause probable / remède |106|---|---|107| « Clés d'accès indisponibles ici » | page ouverte en HTTP, par IP ou sur un autre hôte → ouvrir `https://music.spboucher.ai` |108| La boîte Face ID n'apparaît pas, « demande annulée » | aucune clé de ce site sur l'appareil (trousseau iCloud désactivé ?) → utiliser un autre appareil, un code de récupération, ou un nouveau lien |109| Connexion refusée après un changement de domaine | `APP_URL` ou `WEBAUTHN_RP_ID` modifiés : les clés existantes ne valent que pour l'ancien RP ID |110| Plus aucune clé ni code | sur le nœud : `tsx scripts/setup-token.ts --recovery` |111| Import bloqué sur « reçu » | worker arrêté : `pm2 logs sp-music-worker`, `pm2 restart sp-music-worker` ; `/admin` → Système indique « Traitement » |112| Import en erreur « type refusé » | le contenu n'est pas un format audio accepté (vérifié sur les octets, pas l'extension) |113| « Non lisible ici » sur une piste | DSD sans `TRANSCODE_DSD=true`, ou rendu AAC en préparation / en échec (`/admin` → Bibliothèque → Réanalyser) |114| La lecture ne démarre pas sur iPhone | iOS exige un geste : toucher Lecture. En arrière-plan, iOS garde la lecture d'un `<audio>` et les commandes de l'écran verrouillé ; le volume se règle par les boutons de l'appareil |115| 413 à l'envoi | fichier au-dessus de `UPLOAD_MAX_FILE_MB`, ou morceau au-dessus de la limite du proxy |116| Santé | `curl https://music.spboucher.ai/api/health` → `{ok, db, storage, worker}` |117118Journaux : `pm2 logs sp-music-web|sp-music-worker|sp-music-backup` (aucun secret ni contenu audio n'y est écrit).119