リアルタイム共同編集の運用

Crowi 2.0 のリアルタイム共同編集機能は、Hocuspocus を @crowi/api プロセス内にライブラリとして同居 attach する構成で出荷されています。 別プロセスや別ポートを起動する必要はなく、既存の api コンテナを動かせば そのままリアルタイム共同編集が有効になります。

設計の詳細は RFC-0003 を、利用者向けの使い方は リアルタイム共同編集 を 参照してください。

概要

• Hocuspocus は packages/api/src/collab/attach.ts 経由で api プロセスの http.Server に ws noServer モードで attach されます。
• WebSocket エンドポイントは wss://<crowi-host>/collab/:pageId?token=… で、 api と同じホスト・ポートを使います。リバースプロキシで別プロセスに 振り分ける必要はありません。
• マルチインスタンス構成では @hocuspocus/extension-redis が REDIS_URL 設定時に自動 attach され、Yjs アップデートを Redis pub/sub で全レプリカへ伝搬します。スティッキーセッションは不要です。
• ページ単位の同時編集者上限 (デフォルト 20) は Redis カウンタで管理され、 クラスタ全体で正しくカウントされます。

シングルインスタンスデプロイ

最小構成は api + web + MongoDB の 3 サービスです。

# docker-compose.yml (抜粋)
services:
  api:
    image: ghcr.io/crowi/api:2.0
    environment:
      MONGO_URI: mongodb://mongo:27017/crowi
      WS_TOKEN_SECRET: ${WS_TOKEN_SECRET}
      CROWI_ENCRYPTION_KEY: ${CROWI_ENCRYPTION_KEY}
      # REDIS_URL は任意 (セッション/Socket.IO 共用)
      REDIS_URL: redis://redis:6379
    ports:
      - "3000:3000"
  web:
    image: ghcr.io/crowi/web:2.0
    environment:
      NEXT_PUBLIC_API_URL: https://crowi.example.com
    ports:
      - "3001:3000"
  mongo:
    image: mongo:7

このとき:

• REDIS_URL は省略可ですが、セッション保存と Socket.IO アダプタの 共用先として通常は設定済みのはずです。
• 共同編集自体は Redis なしでも動作します (extension-redis は attach されず、編集者上限 counter は fail-open になります)。
• ブラウザは NEXT_PUBLIC_API_URL から /collab/ への WebSocket URL を 自動導出するため、NEXT_PUBLIC_COLLAB_URL の指定は不要です。
• WS_TOKEN_SECRET はシングルインスタンスでは省略可です — 未設定のまま でもプロセスごとにランダム鍵が生成され (起動時に警告ログ)、1 レプリカなら 無害です。api ノードを 2 台以上に増やすときにのみ CROWI_MULTI_INSTANCE とあわせて設定してください。

マルチインスタンスデプロイ

api を複数レプリカで運用する場合の追加要件:

1. REDIS_URL を全レプリカで同じ Redis に向ける — extension-redis が 自動 attach され、レプリカ間で Yjs アップデートが pub/sub されます。
2. CROWI_MULTI_INSTANCE を宣言し、WS_TOKEN_SECRET を全レプリカで同一値に 揃える — wsToken は任意のレプリカで発行されて任意のレプリカで検証される ため、値がずれると接続が確立できません (詳細は 関連環境変数 参照)。各レプリカに CROWI_MULTI_INSTANCE=1 (またはレプリカ数) を設定すると、WS_TOKEN_SECRET が未設定 (または プレースホルダ) のままだと api は起動時にエラーで停止します (プロセスごとのランダム鍵では他レプリカが wsToken を検証できないため)。 シングルインスタンス構成 (CROWI_MULTI_INSTANCE 未設定) では WS_TOKEN_SECRET 未設定でも起動できます。REDIS_URL の有無だけでは マルチインスタンスとは判定しません (Redis はシングルレプリカでも使われる ため)。
3. スティッキーセッション不要 — クライアントは任意の api レプリカに 接続できます。Yjs 更新は Redis pub/sub 経由で他レプリカへ即座に 伝搬します。
4. Page.yjsState が真実の源 — レプリカ全体の再起動時も MongoDB に 永続化された yjsState から復元されます。Redis はライブのルーティング 専用です。

重要 (データ消失リスク・推奨はシングルインスタンス): マルチインスタンス 構成には、まれにですが編集内容が失われる既知のリスクがあります。 extension-redis はライブの pub/sub のみを担い、切断中レプリカの Y.Doc を 再構築しません。あるレプリカが古い Page.yjsState から Y.Doc を materialise し、その状態でチェックポイント (compaction) を書き戻すと、別レプリカが書いた 新しい状態を上書きしうるためです。compaction にはクロスインスタンスの ロックがありません (cross-instance ロック + last-writer 調停は現時点で スコープ外)。@crowi/collab はこれをサーバドキュメント保存ロックで 緩和します。ページの revision ポインタは、ライブのサーバ側ドキュメントが materialise された revision を基底とする単一のアトミックな compare-and-set で前進させるため、別経路の編集 (または別レプリカ) がポインタを動かした後の 保存は CONFLICT で拒否され、クライアントは再読み込みします (revision と currentRevision が乖離することはありません)。自動チェックポイントには desync ガードを追加しています。非空ページに対して空ドキュメントを 書き込もうとするチェックポイント (= 読み込み失敗で materialise された ドキュメントの兆候) はスキップし、スキップ時は既存の状態と保留中デルタの 両方を保持するため編集は失われません。エディタからの意図的な削除は (ページの 全消去を含め) 明示的なユーザー操作として通常どおり保存されます (削除は短命の 行ではなく Page.yjsState に永続化されます)。これらにより single/multi 両方で最悪ケースを緩和しますが、完全には防げません。このため Crowi は 当面シングルインスタンス (例: Lightsail 1 台) を推奨します。マルチ インスタンスは同時編集の負荷分散が必要な場合のみ、このリスクを理解した上で 採用してください。

# 2 instance 例
services:
  api:
    image: ghcr.io/crowi/api:2.0
    deploy:
      replicas: 2
    environment:
      MONGO_URI: mongodb://mongo:27017/crowi
      REDIS_URL: redis://redis:6379           # マルチ構成では必須
      WS_TOKEN_SECRET: ${WS_TOKEN_SECRET}     # 全レプリカで揃える
      CROWI_ENCRYPTION_KEY: ${CROWI_ENCRYPTION_KEY}

リバースプロキシ設定

WebSocket の Upgrade ヘッダを api までフォワードする必要があります。

nginx

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

upstream crowi_api {
    server api1:3000;
    server api2:3000;
    # マルチインスタンスでもスティッキー指定不要
}

server {
    listen 443 ssl http2;
    server_name crowi.example.com;

    # /api/v2/* と /collab を同じ upstream へ
    location /api/v2/ {
        proxy_pass http://crowi_api;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 末尾スラッシュ無しの `/collab` も含む prefix match。HocuspocusProvider は
    # bare `ws[s]://<host>/collab` で接続し、page id は handshake 後の protocol
    # で送るため、`location /collab/` (末尾スラッシュ付き) だと bare upgrade が
    # マッチしません。`location /collab` (末尾なし) は `/collab` と `/collab/...`
    # の両方をカバーします。
    location /collab {
        proxy_pass http://crowi_api;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 3600s;   # 接続は長時間 keep-alive
        proxy_send_timeout 3600s;
    }

    location / {
        proxy_pass http://crowi_web:3000;
    }
}

Traefik

# docker-compose.yml の api service に
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.crowi-api.rule=Host(`crowi.example.com`) && (PathPrefix(`/api/v2`) || PathPrefix(`/collab`))"
  - "traefik.http.services.crowi-api.loadbalancer.server.port=3000"
  # スティッキーセッション無効 (デフォルト)

ポイント:

• /api/v2/pages/:id/yjs-token (HTTP) と /collab (WebSocket。HocuspocusProvider が bare /collab で接続し、page id は protocol 経由で送る) を同じ api アップ ストリームに向ける必要があります。
• WebSocket 接続のアイドルタイムアウトは長め (1 時間程度) に設定して ください。長時間の閲覧/編集セッションが prematurely 切断されると ユーザー体験が悪化します。
• スティッキーセッションは不要です。

Note (Crowi 2.0 / RFC-0005): ページプレゼンス機能の WebSocket は /presence/:pageId に attach されており、/collab/* とまったく同じ 構成です。リバースプロキシでは /presence ロケーションを /collab と同じ要領で api アップストリームへ向け、Upgrade ヘッダを転送して ください (nginx なら上記 location /collab と同じブロックをパスだけ 変えて複製、Traefik なら rule の PathPrefix に /presence を追加)。 プレゼンスのビューア状態とマルチインスタンス間の伝搬は REDIS_URL の Redis を共用します (専用の追加インフラはありません)。プレゼンスの WebSocket が届かない場合でも、ライブプレゼンス行が静かに隠れるだけで ページ閲覧自体には影響しません。

関連環境変数

Redis 接続数の見積もり

@hocuspocus/extension-redis は pub + sub の 2 接続 を api インスタンス ごとに張ります。既存のセッション/Socket.IO 用接続と合算して Redis 側の maxclients を見積もる必要があります。

例: 10 api レプリカ + 1 web レプリカの構成

• 共同編集 extension-redis: 10 × 2 = 20 接続 (pub + sub の専用 ioredis client)
• セッション/Socket.IO: 10 × 1 = 10 接続 (node-redis client)
• 編集者上限 counter: セッション/Socket.IO と同じ node-redis client に相乗り (追加接続 0)
• web 側からの直接 Redis 接続: なし (api 経由)

合計約 30 接続が常時消費されます。デフォルトの maxclients=10000 内で 十分まかなえますが、Redis Cluster や ElastiCache の低リソースインスタンス (cache.t3.micro / cache.t4g.micro 等) では余裕を持って割り当ててください。

2 インスタンス smoke テスト手順

実機での multi-instance 検証は docker compose --scale で簡単に組めます:

# 1. 既存の compose 構成にスケール指示を加えて起動
docker compose --profile app up -d --build --scale api=2

# 2. 2 つの api コンテナが立っていることを確認
docker compose ps api
# crowi-api-1   Up   3000/tcp
# crowi-api-2   Up   3000/tcp

# 3. 各 api コンテナのログをそれぞれ tail
docker compose logs -f api
# extension-redis (identifier=…) の attach ログを 2 行確認

検証手順:

1. 2 つのブラウザウィンドウ (Chrome 通常 + シークレット、または異なる ブラウザ) で別ユーザーとしてログイン。
2. 同じページの /_edit?page_id=<pageId> を 2 ウィンドウで開く。
3. 一方で文字を入力 → もう一方にリアルタイムで反映されることを確認。
4. nginx などのロードバランサーが手前にある場合は、各ウィンドウが 別レプリカに振り分けられていることを確認 (api 側ログの onConnect 出力で instance= 識別子が異なれば OK)。
5. 一方の api コンテナを docker compose stop api-1 で停止 → 残った レプリカに自動再接続し、編集が継続できることを確認。

障害時の挙動 (Failure modes)

• Redis 障害 (REDIS_URL 設定済み、接続不可): extension-redis の ioredis 再接続ループが動き続けます。新規 Yjs 更新はローカルの Hocuspocus engine 内では伝搬しますが、他レプリカへの pub/sub は 途切れます。編集者上限 counter は fail-open (上限チェックを 通す) に倒れます。Redis 復旧後は自動で pub/sub が再開します。
• WS_TOKEN_SECRET 不一致 / 未設定: あるレプリカが発行した wsToken を別の レプリカが検証できず、onAuthenticate で reject されます。クライアントは WebSocket connect 後すぐに切断され、エディタが "接続できませんでした" 状態のままになります。対処: 全レプリカで同じ secret を再設定して ローリング再起動。なお CROWI_MULTI_INSTANCE を宣言しつつ WS_TOKEN_SECRET を未設定 (または既知のプレースホルダ) にした場合、api は起動時にエラーで 停止してこの問題を未然に防ぎます。シングルインスタンス構成 (CROWI_MULTI_INSTANCE 未設定) は secret なしで問題なく起動します。これらの 診断 (wsToken 検証失敗 / 編集者上限到達) は本番ログにサンプリングされた警告 として出力されるため、"接続できませんでした" の真因 (期限切れ / secret 不一致 / クロック skew / 上限到達) を切り分けられます。
• WS_TOKEN_SECRET が短すぎる (32 文字未満): 値は設定されているものの 32 文字に満たない場合 (既知のプレースホルダは対象外)、NODE_ENV=production (未設定時のデフォルトも production 扱い) では api が起動時にエラーで停止します。 エラーメッセージには変数名・現在の長さ・要求 (32 文字以上)・ openssl rand -base64 32 での生成方法が含まれます。development / test など production 以外の NODE_ENV では起動を止めず、他の env 検証と同じ 起動時の警告レポートに 1 回まとめて出力されます。entropy や辞書のような 推測的なチェックは行わず、文字数のみの単純なチェックです。
• マルチインスタンスでの編集消失 (既知のリスク): 上記「マルチインスタンス デプロイ」の重要注記を参照。stale なレプリカが古い Page.yjsState から materialise した Y.Doc で compaction を書き戻すと、新しい状態を上書きしうる 既知のリスクです。サーバドキュメント保存ロックと desync ガードで緩和されますが 完全には防げず、シングルインスタンス運用を推奨します。
• WebSocket Upgrade 失敗: リバースプロキシで Upgrade ヘッダが 落とされていると /collab/ 接続が 400/426 で失敗します。nginx 設定で proxy_set_header Upgrade $http_upgrade を確認してください。
• ライブ編集セッション中の外部編集: 共同編集セッションが開いている ページに対して、REST API・MCP の crowi_update_page・プロセス内の Page.updatePage などの外部経路から本文が更新されると、Crowi は currentRevision を新しい revision に張り替え Page.yjsState を null に します。このとき同一 api プロセス内にライブな Y.Doc があれば、Crowi は 保存コミット後にその Y.Doc を無効化します — 接続中の全クライアントへ crowi:force-reload を broadcast し、ドキュメントの基底 revision を tombstone して進行中の古い保存を CONFLICT で拒否し、短い猶予の後に ライブ接続を閉じます。これにより、先に reload したクライアントが古い ライブ Y.Doc に再アタッチして CONFLICT ループに陥ることを防ぎます。 クライアント側は警告ダイアログを出してページを reload し、未保存の ローカル編集は復旧バッファから復元できます。次回接続時は新しい currentRevision の本文から再構築されます。
  • 既知の制約 (マルチインスタンス / プロセス外): 無効化のハンドルは その api プロセス内のライブ Y.Doc にしか届きません。別レプリカで 開いているライブ Y.Doc や、プロセス外の書き込み (DB を直接叩く admin CLI の Page.updatePage 等) には届かないため、マルチインスタンス 構成では外部編集後に接続中クライアントが古い内容のまま編集を続ける 可能性があり、手動で再接続するまで収束しません。クロスインスタンスの 無効化チャネル (Redis pub/sub による全レプリカへの伝搬) は将来対応であり 現時点ではスコープ外です (RFC-0003 §5b)。これもシングルインスタンス 運用を推奨する理由のひとつです。
• Page.yjsState 破損: onLoadDocument で yjsState の Y.applyUpdate が失敗した場合、Crowi は revision の Markdown 本文から Y.Doc を再構築し、接続中の全クライアントへ force-reload 通知を送ります。 クライアント側は警告ダイアログを出してページを reload します。
• renderedAst 不整合 (RFC-0002 連動): 共同編集の保存は Revision.prepareRevision を呼び出して renderedAst を自動再生成 します。何らかの理由で Page.body と最新 Revision.body がずれた 場合は、crowi-admin renderer:rebuild (RFC-0002) で再ビルドして ください。
• api プロセスダウン: 接続中の全クライアントが reconnect ループに 入ります。ヘルスチェックで他レプリカへフェイルオーバーする構成なら クライアントは自動的に他レプリカへ繋ぎ直し、Y.Doc は MongoDB の yjsState から復元されます。

キャパシティチューニング

• COLLAB_MAX_EDITORS_PER_PAGE で同時編集者上限を変更できます。20 は 経験則的な目安で、awareness の cursor 描画コストが大きくなる前の 上限です。これを大きく上げる場合は、editor 側の同時 awareness 配信に 対する描画負荷も検証してください。
• Y.Doc の差分は debounce: 2000 ms で onChange に流れます。これは Hocuspocus のデフォルトを継承していて、変更が小さいうちは無駄な PageYjsUpdate 書き込みを抑えます。
• PageYjsUpdate は TTL 1 時間で自動 expire し、ベースラインの Page.yjsState への compaction も定期的に走ります。1 ページに対して 延々と編集が続いても DB は線形には肥大化しません。

Save の SLO

• 保存処理は通常 100-500ms で完了します。
• サーバ側には 5 秒のタイムアウトがあり、5 秒を超えると 408 相当の エラーをクライアントへ返します。
• ただしタイムアウトしても実際には保存が成功している可能性が あります (DB は書き込み済みで応答が遅延しただけのケース)。 クライアント側は自動リトライしません。ページを reload して最新 revision を確認するのが正しい対処です。
• 5 秒タイムアウトはあくまで extreme slow への安全網であり、通常の ネットワーク条件では十分余裕があります。タイムアウトが恒常的に 発生する場合は MongoDB のレイテンシ / renderer 処理時間 / 接続 プールサイズを疑ってください。