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

5.6 KiB

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)

# 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)

# 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

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