Plusieurs utilisateurs peuvent éditer le même document Markdown simultanément, façon Google Docs, grâce à Yjs (CRDT) et à un canal WebSocket. Ce guide explique le fonctionnement et l'utilisation.

Public : tous les utilisateurs · Fiche technique : features/collaboration.md Voir aussi : Prise en main · API REST

1. Ce que fait la collaboration

Fusion sans conflit via Yjs (CRDT) : deux personnes peuvent taper au même endroit, aucune modification n'est perdue.
Curseurs distants colorés et sélections visibles dans CodeMirror, étiquetés avec le nom de chaque utilisateur.
Indicateur de présence dans l'en-tête de l'éditeur (avatars + statut de connexion).
Reconnexion automatique (backoff exponentiel) : l'état est fusionné au retour.
Persistance serveur : le document est écrit sur disque 2 s après la dernière modification.

2. Utilisation

Aucune configuration n'est nécessaire :

Ouvrez le même fichier dans deux navigateurs (ou deux fenêtres).
Passez en mode Editer (ou Forge) dans les deux.
Tapez : les modifications apparaissent en temps réel des deux côtés, avec les curseurs de chacun.

L'édition collaborative nécessite que la vault soit accessible en écriture (le volume Docker doit être monté sans :ro pour les vaults modifiables).

3. Transport & protocole

Élément	Valeur
Endpoint	`ws(s)://<hôte>/ws/collab/{vault}/{chemin}`
Authentification	Cookie `access_token` (ou paramètre `?token=`)
Autorisation	Contrôle d'accès par vault appliqué à chaque connexion
Protocole	Yjs / CRDT — updates + awareness (curseurs)
Persistance	Écriture disque débouncée (2 s) côté serveur

Le canal est mis à niveau à partir de la même origine que l'application. Derrière un reverse proxy, autorisez les upgrades WebSocket et augmentez proxy_read_timeout (voir Déploiement Docker).

4. Sécurité

L'accès au document est revérifié à la connexion (permissions du compte).
Un utilisateur sans droit sur la vault ne peut pas rejoindre la session.
Les échanges passent par le même domaine que l'application (pas de serveur tiers).

5. Limitations & bonnes pratiques

La collaboration vise les fichiers Markdown.
Évitez d'éditer le même fichier simultanément depuis ObsiGate et une application de synchronisation externe (risque de conflits au niveau fichier).
Le document est écrit après un court délai ; attendez la fin de la sauvegarde avant de fermer brutalement l'onglet.
En cas de conflit de synchronisation externe (Syncthing), l'écran Conflits (/api/conflicts) aide à résoudre.

6. Dépannage

Symptôme	Piste
Les curseurs des autres n'apparaissent pas	Vérifier le WebSocket (proxy sans support `Upgrade`)
Reconnecté sans cesse	Réseau instable ou timeout proxy trop court
Modifications non persistées	Vault montée en lecture seule (`:ro`) ?
`401` à la connexion	Session expirée — se reconnecter
Accès refusé	Le compte n'a pas la permission sur cette vault

3.3 KiB Raw Blame History

📝 Guide Édition & collaboration temps réel