162 lines
7.5 KiB
Markdown
162 lines
7.5 KiB
Markdown
# Stream Control
|
|
|
|
Plan de contrôle web pour piloter des enregistrements OBS répartis sur plusieurs VM/VPS
|
|
(Windows et Ubuntu) depuis une seule interface.
|
|
|
|
```
|
|
┌────────────┐ HTTPS + WS ┌──────────────────┐ WS sortant ┌──────────────────┐
|
|
│ Navigateur │ ───────────────►│ Serveur de │◄────────────────│ Agent (VM) │
|
|
│ dashboard │◄─── temps réel ─│ contrôle │──── commandes ─►│ └► OBS (4455) │
|
|
└────────────┘ │ Express + SQLite│ └──────────────────┘
|
|
└──────────────────┘ ┌──────────────────┐
|
|
◄────────────────│ Agent (VM) … │
|
|
└──────────────────┘
|
|
```
|
|
|
|
**Le sens des connexions est le point clé** : ce sont les agents qui se connectent au
|
|
serveur, pas l'inverse. Aucun port entrant à ouvrir sur les VM d'enregistrement, aucune
|
|
IP publique nécessaire, et obs-websocket reste sur `127.0.0.1`.
|
|
|
|
## Fonctionnalités
|
|
|
|
- Découverte automatique des agents par jeton d'enrôlement, ou provisionnement manuel.
|
|
- État temps réel par VM : OBS connecté, enregistrement en cours, durée, taille du
|
|
fichier, scène active, FPS, frames perdues, CPU, espace disque restant.
|
|
- Commandes unitaires ou groupées : démarrer/arrêter/mettre en pause/découper un
|
|
enregistrement, démarrer/arrêter un stream, changer de scène, de profil, de collection,
|
|
changer le dossier d'enregistrement.
|
|
- Journal d'évènements horodaté, persistant et diffusé en direct.
|
|
- Reconnexion automatique de bout en bout (agent → serveur, agent → OBS, dashboard → serveur).
|
|
|
|
## Prérequis
|
|
|
|
- Node.js **22+** sur le serveur et sur chaque VM (le serveur utilise `node:sqlite`).
|
|
- OBS **28+** sur chaque VM, avec *Outils → Paramètres du serveur WebSocket* activé.
|
|
Note le port (4455 par défaut) et le mot de passe.
|
|
|
|
## Démarrage rapide (développement)
|
|
|
|
```bash
|
|
npm install
|
|
cp .env.example .env # renseigne ADMIN_PASSWORD, SESSION_SECRET, ENROLLMENT_TOKEN
|
|
npm run dev # serveur :8080 + dashboard Vite :5173
|
|
```
|
|
|
|
Puis, dans un autre terminal, un agent local :
|
|
|
|
```bash
|
|
cd packages/agent
|
|
cp agent.config.example.json agent.config.json # colle le ENROLLMENT_TOKEN dans "token"
|
|
npm run dev
|
|
```
|
|
|
|
L'agent s'enrôle, reçoit son jeton permanent, le réécrit dans `agent.config.json`, et
|
|
apparaît dans le dashboard sur <http://localhost:5173>.
|
|
|
|
## Déploiement
|
|
|
|
### Serveur de contrôle
|
|
|
|
```bash
|
|
npm ci && npm run build
|
|
npm start # sert l'API, le WebSocket et le dashboard compilé sur $PORT
|
|
```
|
|
|
|
Mets-le derrière un reverse proxy TLS ([exemple nginx](deploy/nginx.conf.example)) et
|
|
installe l'unité systemd [`deploy/stream-control-server.service`](deploy/stream-control-server.service).
|
|
`ADMIN_PASSWORD` et `SESSION_SECRET` sont obligatoires hors développement.
|
|
|
|
### Agent Ubuntu
|
|
|
|
Copie `packages/agent/dist`, `packages/agent/node_modules` et `agent.config.json` dans
|
|
`/opt/stream-control-agent`, puis installe
|
|
[`deploy/stream-control-agent.service`](deploy/stream-control-agent.service).
|
|
|
|
### Agent Windows
|
|
|
|
Un service Windows classique tourne en session 0 et ne verrait pas OBS. Utilise la tâche
|
|
planifiée « à l'ouverture de session » fournie :
|
|
|
|
```powershell
|
|
.\deploy\windows-agent-task.ps1 -AgentDir 'C:\stream-control-agent' -RunAsUser 'VM01\obs'
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Serveur — `.env` (voir [.env.example](.env.example))
|
|
|
|
| Variable | Rôle |
|
|
| --- | --- |
|
|
| `PORT`, `HOST` | Écoute HTTP/WebSocket |
|
|
| `ADMIN_PASSWORD` | Mot de passe du dashboard |
|
|
| `SESSION_SECRET` | Clé HMAC des sessions (32+ octets aléatoires) |
|
|
| `ENROLLMENT_TOKEN` | Jeton d'auto-enregistrement ; vide = désactivé |
|
|
| `DB_PATH` | Fichier SQLite |
|
|
| `STATUS_INTERVAL_MS` | Fréquence de remontée d'état des agents |
|
|
| `AGENT_TIMEOUT_MS` | Délai avant de déclarer un agent hors-ligne |
|
|
|
|
### Agent — `agent.config.json` (ou variables d'environnement)
|
|
|
|
| Clé | Variable | Rôle |
|
|
| --- | --- | --- |
|
|
| `serverUrl` | `SERVER_URL` | `wss://control.exemple.com/ws/agent` |
|
|
| `token` | `AGENT_TOKEN` | Jeton d'enrôlement puis jeton propre à l'agent |
|
|
| `name` | `AGENT_NAME` | Nom affiché (défaut : hostname) |
|
|
| `obs.host/port/password` | `OBS_HOST` / `OBS_PORT` / `OBS_PASSWORD` | Repli local ; le serveur pousse la config de référence |
|
|
| `insecureTls` | `INSECURE_TLS=1` | Accepter un certificat auto-signé |
|
|
|
|
Les paramètres OBS édités dans le dashboard sont poussés à chaud vers l'agent : pas
|
|
besoin de se connecter à la VM pour changer un mot de passe obs-websocket.
|
|
|
|
## API HTTP
|
|
|
|
Toutes les routes hors `/api/login` exigent `Authorization: Bearer <jeton de session>`.
|
|
|
|
| Méthode | Route | Rôle |
|
|
| --- | --- | --- |
|
|
| `POST` | `/api/login` | Ouvre une session (`{ password }`) |
|
|
| `GET` | `/api/agents` | Liste des agents et de leur état |
|
|
| `POST` | `/api/agents` | Provisionne un agent, renvoie son jeton **une seule fois** |
|
|
| `PATCH` | `/api/agents/:id` | Nom, notes, paramètres OBS, auto-connexion |
|
|
| `POST` | `/api/agents/:id/token` | Régénère le jeton (coupe la session en cours) |
|
|
| `DELETE` | `/api/agents/:id` | Supprime l'agent |
|
|
| `POST` | `/api/agents/:id/command` | `{ action, params }`, attend le résultat de l'agent |
|
|
| `POST` | `/api/commands/bulk` | Même action sur plusieurs agents, résultat par agent |
|
|
| `GET` | `/api/logs?limit=` | Journal récent |
|
|
| `GET` | `/healthz` | Sonde de vie (non authentifiée) |
|
|
|
|
Actions disponibles : `obs.connect`, `obs.disconnect`, `obs.refresh`, `record.start`,
|
|
`record.stop`, `record.pause`, `record.resume`, `record.split`, `stream.start`,
|
|
`stream.stop`, `scene.set`, `profile.set`, `collection.set`, `recordDirectory.set`,
|
|
`agent.ping`.
|
|
|
|
## Structure
|
|
|
|
| Paquet | Rôle |
|
|
| --- | --- |
|
|
| [packages/shared/](packages/shared/) | Types du protocole, partagés par les trois autres |
|
|
| [packages/server/](packages/server/) | API REST, passerelle agents, diffusion dashboard, SQLite |
|
|
| [packages/agent/](packages/agent/) | Binaire à déployer sur chaque VM, pilote OBS |
|
|
| [packages/web/](packages/web/) | Dashboard React/Vite |
|
|
|
|
Points d'entrée utiles : [packages/shared/src/index.ts](packages/shared/src/index.ts)
|
|
(le protocole), [packages/server/src/hub.ts](packages/server/src/hub.ts) (état central et
|
|
dispatch), [packages/agent/src/obs.ts](packages/agent/src/obs.ts) (traduction
|
|
action → obs-websocket).
|
|
|
|
## Sécurité
|
|
|
|
- Les jetons d'agent ne sont stockés qu'en SHA-256 ; le clair n'est affiché qu'à la création.
|
|
- Le mot de passe obs-websocket n'est jamais renvoyé au navigateur (masqué en `********`).
|
|
- Les sessions dashboard sont des jetons HMAC à durée limitée, sans état serveur.
|
|
- **Sers l'application en HTTPS/WSS** : jetons d'agent et de session circulent dans les
|
|
en-têtes et les URL de WebSocket.
|
|
- Après un `POST /api/agents/:id/token`, l'agent est déconnecté jusqu'à ce que son
|
|
`agent.config.json` soit mis à jour.
|
|
|
|
## Pistes d'évolution
|
|
|
|
Enregistrements programmés (cron par agent), rapatriement automatique des fichiers
|
|
(rclone/S3 déclenché à `record.stop`), alertes sur seuil d'espace disque ou de frames
|
|
perdues, comptes utilisateurs multiples, groupes d'agents.
|