Files
Esiah c6b08b4812
CD — Kai-Sa-Cam Deployment / deploy (push) Successful in 1m59s
feat: handle Cloudflare Access session expiry and serve go2rtc same-origin
- add apiFetch wrapper with re-auth popup, retry and session monitor
- proxy go2rtc through the app (/go2rtc) and drop the public stream hostname
- route WebSocket upgrades manually (the talk WSS was rejecting go2rtc MSE)
- harden talkback: paplay error handling, heartbeat, single speaker, reconnect
- sync recording state with the server on load and on 409
- optionally verify Cf-Access-Jwt-Assertion (CF_ACCESS_TEAM_DOMAIN/AUD)
- keep go2rtc on the internal network only
- remove unused env vars, update README and cam-watch script
2026-10-26 00:50:08 +01:00

160 lines
8.7 KiB
Markdown

# Kai-Sa-Cam
Application de surveillance vidéo avec enregistrement manuel, écoute bidirectionnelle via enceinte Bluetooth, et snapshots.
## Architecture
```
┌──────────────────────────────────────────────────────────────┐
│ Cloudflare Access (login, session, JWT) │
│ │ │
│ Cloudflare Tunnel (kai-sa-cam-tunnel) │
│ └── kaisa.esiah.dev → kai-sa-cam:8090 (seule route) │
└──────────────────────────────┬───────────────────────────────┘
▼
┌─────────────────────┐
│ kai-sa-cam │
│ UI + API + recorder│
│ + talkback (WS) │
│ proxy /go2rtc/* │
└──────────┬──────────┘
│ kai-sa-cam-internal (réseau interne)
┌──────────▼──────────┐
│ kai-sa-go2rtc │ ← aucun accès externe
│ (flux webcam) │
└──────────┬──────────┘
▼
/dev/video0 + /dev/snd
kai-sa-cam ──► PulseAudio (socket hôte) ──► enceinte BT
```
go2rtc n'est joignable que depuis `kai-sa-cam` : le flux ne peut pas être consulté sans passer par Cloudflare Access.
## Composants
- **kai-sa-cam** : API Node + UI React/Tailwind + recorder + talkback (WebSocket → paplay → PulseAudio) + proxy `/go2rtc` vers go2rtc
- **kai-sa-go2rtc** : flux webcam, durci (non-privileged, devices restreints), sur le réseau interne uniquement
## Fonctionnalités
- **Live view** : flux MSE via go2rtc, servi en même origine (`/go2rtc/stream.html`)
- **Push-to-record manuel** : enregistrement vidéo (jamais le micro du navigateur)
- **Snapshots manuels** : capture instantanée JPEG
- **Talkback** : micro navigateur → enceinte Bluetooth, reconnexion automatique
- **Stockage plat** : tout dans `./media` sans arborescence
- **Export ZIP** : téléchargement de tous les médias + suppression auto après succès
- **Auth** : Cloudflare Access uniquement, avec validation optionnelle du JWT côté serveur
- **Session expirée** : détectée côté client, popup de reconnexion, requête rejouée sans recharger la page
## Réseaux
- `kai-sa-cam-internal` (internal) : kai-sa-cam ↔ kai-sa-go2rtc
- `kai-sa-cam-tunnel` (external) : exposition de `kai-sa-cam` uniquement via Cloudflare Tunnel
## Cloudflare Access
Application Access sur `kaisa.esiah.dev` (aucun chemin en Bypass) :
- **Session duration** : 24 h ou plus (réglage qui détermine la fréquence des reconnexions)
- **HTTP Only** activé, **Same Site** = Lax, CORS laissé vide (tout est en même origine)
- Aucune route de tunnel ni application Access pour go2rtc
### Validation du JWT côté serveur (optionnel)
Si `CF_ACCESS_TEAM_DOMAIN` et `CF_ACCESS_AUD` sont renseignées, le serveur refuse (401) toute requête HTTP ou WebSocket sans en-tête `Cf-Access-Jwt-Assertion` valide. `/api/health` reste accessible pour les sondes locales. Vides, la vérification est désactivée.
L'AUD tag se trouve dans Zero Trust → Access → Applications → `kaisa.esiah.dev`.
## Installation locale (dev)
```bash
# Prérequis : Docker, Docker Compose, Node.js 20+, PulseAudio/PipeWire, BlueZ
# Enceinte BT appairée (MAC: 69:B2:C0:04:A4:80)
cp .env.example .env # adapter si besoin
make up-dev # démarre kai-sa-cam + kai-sa-go2rtc
```
Accès : `http://localhost:8090`, ou via le proxy Vite qui doit relayer `/api` (WebSocket compris), `/go2rtc` (WebSocket compris) et `/auth` vers `:8090`.
## Installation production (serveur)
```bash
cd /srv/apps/kai-sa-cam
cp .env.example .env # une seule fois, puis renseigner CF_ACCESS_AUD
mkdir -p media config
sudo chown 1001:1001 media # le conteneur tourne en 1001:1001
make up-prod
```
Le runner GitHub Actions `kai-sa-cam` déploie automatiquement sur push `main`. Le fichier `.env` n'est pas versionné : il reste sur le serveur d'un déploiement à l'autre.
## Variables d'environnement
Lues par `docker-compose.yml` depuis `.env` :
| Variable | Défaut | Description |
| ----------------------- | -------------------------------- | ---------------------------------------------------------------------- |
| `TZ` | Europe/Paris | Fuseau horaire |
| `USER_ID` / `GROUP_ID` | 1001 | UID/GID de l'utilisateur hôte |
| `APP_ORIGIN` | https://kaisa.esiah.dev | Origine de l'application |
| `LOG_LEVEL` | info | Niveau de log |
| `MAX_RECORDING_MINUTES` | 120 | Durée max d'un enregistrement |
| `DISK_MIN_FREE_GB` | 2 | Espace disque minimum |
| `CF_ACCESS_TEAM_DOMAIN` | - | Domaine d'équipe Access (ex. `https://esiah-dev.cloudflareaccess.com`) |
| `CF_ACCESS_AUD` | - | AUD tag de l'application Access |
| `PULSE_SERVER` | unix:/run/user/1001/pulse/native | Socket PulseAudio de l'hôte |
| `BT_MAC` | 69:B2:C0:04:A4:80 | Adresse de l'enceinte BT (service hôte) |
Fixées dans le compose (pas dans `.env`) : `MEDIA_DIR=/media`, `CONFIG_DIR=/config`, `GO2RTC_URL`, `GO2RTC_RTSP_URL`.
## Commandes Make
```bash
make up-dev # Démarre en dev (build + hot reload)
make down-dev # Arrête dev
make logs-dev # Logs dev
make up-prod # Démarre en prod
make down-prod # Arrête prod
make logs-prod # Logs prod
make status # État conteneurs
make restart # Redémarre services
```
## Sécurité
- **go2rtc** : non-privileged, `devices: [/dev/video0, /dev/snd]`, `cap_drop: ALL`, `no-new-privileges`, `read_only`, réseau interne uniquement
- **kai-sa-cam** : non-root (UID 1001), `cap_drop: ALL`, `no-new-privileges`, `read_only`, pas de D-Bus
- **Bluetooth** : géré via service hôte `kai-sa-cam-bt.service` (pas de D-Bus dans conteneurs)
- **Auth** : Cloudflare Access + validation optionnelle du JWT dans l'application
## Stockage
- `./media` (hôte) monté sur `/media` : bind mount, pas un volume Docker. Sur le serveur : `/srv/apps/kai-sa-cam/media`
- Tout est à plat (pas de sous-dossiers)
- Enregistrements : `.mp4` (push-to-record manuel, max 120 min)
- Snapshots : `.jpg` (manuels)
- Export ZIP : supprime les fichiers **uniquement si le ZIP se termine sans erreur**
- Pas de rétention automatique, suppression manuelle possible
## Dépannage
| Symptôme | Action |
| ------------------------------ | ------------------------------------------------------------------------------------------------ |
| Pas de vidéo | `make status`, vérifier `/dev/video0`, `make logs-go2rtc` |
| Bandeau « Session expirée » | Cliquer « Se reconnecter » (popup Access) ; allonger la session dans Cloudflare |
| Tout répond 401 | `CF_ACCESS_AUD` / `CF_ACCESS_TEAM_DOMAIN` incorrects : les vider pour désactiver la vérification |
| Micro → enceinte ne marche pas | `make logs-cam`, vérifier Pulse/BT |
| Enregistrement ne démarre pas | Espace disque, droits sur `./media` (1001:1001), `make logs-cam` |
## Déploiement
Le workflow GitHub Actions `.github/workflows/deploy.yml` tourne sur runner `self-hosted` label `kai-sa-cam` :
1. `git pull` sur `/srv/apps/kai-sa-cam`
2. `docker compose --profile prod build`
3. `docker compose --profile prod up -d`
4. `docker image prune -f`