games_app/docs/VPS-MONITORING.md
2026-11-01 18:22:18 +02:00

91 lines
3.8 KiB
Markdown
Raw 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.

# Surveillance VPS (back-office Tloto)
Lecture seule des ressources hôte + conteneurs Docker, affichée dans **Options → Surveillance VPS**.
## Architecture
```
Navigateur (HTTPS) → vps-gateway → backend Tloto
↓ PROMETHEUS_URL (réseau Docker)
prometheus (pas de port public)
↓ monitoring-net (internal)
node-exporter cadvisor
```
- **Aucun port publié** pour Prometheus, Node Exporter, cAdvisor.
- Le backend n’exécute **aucune** commande shell/Docker et **ne monte pas** `/var/run/docker.sock`.
- Exception documentée : **cAdvisor** monte `docker.sock` en **lecture seule** uniquement pour les métriques conteneurs.
- L’API n’accepte **pas** de PromQL libre : métriques allowlistées (`cpu`, `mem`, `disk`, `net_in`, `net_out`, `load1`).
## Permission
- Clé : `admin.vps_monitor.view`
- Accordée par défaut au rôle `admin` (sync catalogue) et à `super_admin` (toutes les clés du catalogue via `syncPermissionCatalog`).
- Le rôle `super_admin` passe aussi les garde-fous UI/API même si le JWT local est encore sans la nouvelle clé.
- Vérifiée côté backend (`requirePermissions`) + UI (`PermissionGate` / Options).
- Accès refusés : `logAccessDenied` ; consultations : `audit_logs` (`vps_monitor_*`).
### Vérifier sur le VPS (SQL)
```bash
sudo docker compose exec -T backend node -e "
const {query}=require('./dist/db/connection');
(async()=>{
console.log(await query(\"SELECT key FROM permissions WHERE key='admin.vps_monitor.view'\"));
console.log(await query(\"SELECT r.name, COUNT(*)::int AS n FROM role_permissions rp JOIN roles r ON r.id=rp.role_id JOIN permissions p ON p.id=rp.permission_id WHERE p.key='admin.vps_monitor.view' GROUP BY r.name\"));
process.exit(0);
})().catch(e=>{console.error(e);process.exit(1);});
"
```
## Démarrage (VPS)
```bash
cd ~/projects_repository/games-project
git pull
sudo npm run monitoring:up
# Recreate API so it joins monitoring-net (required once after this networking fix)
sudo docker compose up -d --force-recreate backend
sudo npm run phase-b:up:https
curl -sS https://tloto.net/health
```
Vérifier la stack monitoring + connectivité backend → Prometheus :
```bash
sudo docker compose --profile monitoring ps
sudo docker compose logs --tail=40 prometheus
sudo docker exec crypto_wallet_api node -e "fetch('http://prometheus:9090/-/healthy').then(r=>r.text()).then(console.log).catch(e=>{console.error(e);process.exit(1)})"
sudo ss -tlnp | grep -E '9090|9100|8080' || echo "OK: ports monitoring non exposés"
```
## Variables d’environnement
| Variable | Défaut | Rôle |
|----------|--------|------|
| `PROMETHEUS_URL` | `http://prometheus:9090` | URL interne vue du backend |
| `MONITORING_RETENTION` | `15d` | Rétention TSDB Prometheus |
| `VPS_MONITOR_TIMEOUT_MS` | `8000` | Timeout appels Prometheus |
| `VPS_MONITOR_*_WARN/CRITICAL` | voir `.env.example` | Seuils d’affichage (lecture seule) |
## Rate limiting
Les routes `/api/v1/admin/vps-monitor/*` utilisent `vpsMonitorLimiter` (30 req/min) en plus du limiteur API global.
## Migration vers un autre VPS
1. Copier le dépôt + `.env` (sans secrets dans Git).
2. `docker compose --profile monitoring up -d` puis stack Tloto habituelle.
3. Volume `prometheus_data` = historique (optionnel à migrer).
4. Ne jamais publier 9090/9100/8080 sur l’hôte.
## Mise à jour des images
Versions épinglées dans `docker-compose.yml` (`prom/prometheus:v2.55.1`, `prom/node-exporter:v1.8.2`, `gcr.io/cadvisor/cadvisor:v0.49.1`). Après bump : `sudo npm run monitoring:up` puis tests santé scrape dans la page admin.
## Hors scope (v1)
- Grafana public
- Restart / exec / SSH depuis le back-office
- Édition des seuils depuis l’UI