Files
Kai-Sa-Cam/README.md
T
Esiah 73394dfbbc
CD — Kai-Sa-Cam Deployment / deploy (push) Canceled after 0s
feat: restructure to kai-sa-cam layout with apps/ structure
2026-10-25 01:06:31 +02:00

138 lines
5.6 KiB
Markdown

# Kai-Sa-Cam
Application de surveillance vidéo avec enregistrement manuel, écoute bidirectionnelle via enceinte Bluetooth, et snapshots.
## Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ Cloudflare Tunnel (kai-sa-cam-tunnel) │
│ └── kaisa.esiah.dev → kai-sa-cam:8090 │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────┴─────────┐
▼ ▼
┌─────────────────┐ ┌──────────────┐
│ kai-sa-cam │ │kai-sa-go2rtc │
│ (API + UI + │ │ (RTSP flux) │
│ recorder + │ │ │
│ BT bridge) │ │ │
└─────────────────┘ └──────────────┘
│ │
└─────────┬─────────┘
│
┌─────────┴─────────┐
▼ ▼
kai-sa-cam-internal /dev/video0 + /dev/snd
│
▼
┌──────────────────┐
│ PulseAudio/PipeWire │
│ (enceinte BT) │
└──────────────────┘
```
## Composants
- **kai-sa-cam** : API Node + UI React/Tailwind + recorder + BT bridge (WebSocket → PulseAudio)
- **kai-sa-go2rtc** : Flux RTSP webcam (vidéo + son caméra), durci (non-privileged, devices restreints)
## Fonctionnalités
- **Live view** : Flux vidéo MSE via go2rtc, son caméra
- **Push-to-record manuel** : Enregistrement vidéo + son caméra (jamais micro navigateur)
- **Snapshots manuels** : Capture instantanée JPEG
- **Talkback** : Micro navigateur → enceinte Bluetooth (WebSocket → paplay → PulseAudio)
- **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 (pas de JWT interne)
## Réseaux
- `kai-sa-cam-internal` (internal) : Communication kai-sa-cam ↔ kai-sa-go2rtc
- `kai-sa-cam-tunnel` (external) : Exposition via Cloudflare Tunnel
## 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` (via proxy Vite) ou via tunnel si configuré.
## Installation production (serveur)
```bash
# Sur le serveur
cd /srv/apps/kai-sa-cam
make up-prod
```
Le runner GitHub Actions `kai-sa-cam` déploie automatiquement sur push `main`.
## Variables d'environnement
| Variable | Défaut | Description |
|----------|--------|-------------|
| `TZ` | Europe/Paris | Fuseau horaire |
| `USER_ID` / `GROUP_ID` | 1001 | UID/GID pour volumes |
| `APP_ORIGIN` | https://kaisa.esiah.dev | Origine CORS |
| `MEDIA_DIR` | ./media | Stockage médias |
| `CONFIG_DIR` | ./config | Config go2rtc |
| `LOG_LEVEL` | info | Niveau de log |
| `MAX_RECORDING_MINUTES` | 120 | Durée max enregistrement |
| `DISK_MIN_FREE_GB` | 2 | Espace disque minimum |
| `GO2RTC_USERNAME` | kai-sa-cam | Auth go2rtc |
| `GO2RTC_PASSWORD` | - | Auth go2rtc |
| `BT_MAC` | 69:B2:C0:04:A4:80 | Adresse enceinte BT |
## 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`
- **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 uniquement
## Stockage
- Tout dans `/media` (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` |
| Pas de son caméra | Cliquer sur la vidéo, vérifier gain |
| Micro → enceinte ne marche pas | `make logs-cam`, vérifier Pulse/BT |
| Enregistrement ne démarre pas | Espace disque, `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`