CD — Kai-Sa-Cam Deployment / deploy (push) Successful in 1m59s
- 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
160 lines
8.7 KiB
Markdown
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`
|