docs: document workflow collaboration feature

.claude/skills/dify-docs-guides/SKILL.md

@@ -55,6 +55,55 @@ This is a team effort. The user brings documentation expertise and user empathy;
 - Trust the codebase over existing documentation. Existing docs may be outdated or inaccurate.
 - **Code presence ≠ working feature.** A code path existing does not guarantee the feature functions end to end. When behavior is inferred from code analysis rather than observed in the running product, flag it as unverified and ask the user to test before documenting it as fact.
 
+## Environment Variables in User Guides
+
+When a feature is gated by or configured through environment variables (feature toggles, endpoints, self-host-only switches, worker classes), coordinate with the reference doc instead of duplicating it.
+
+### Investigate first
+
+During feature research, check whether the feature has related environment variables:
+
+- Grep `docker/.env.example`, `api/configs/`, and the feature's PR for any `ENABLE_*`, `*_URL`, worker, or socket settings tied to the feature.
+- Note which variables are mandatory vs. optional, and what their defaults are.
+
+If the feature has related variables, use the `dify-docs-env-vars` skill to update `en/self-host/configuration/environments.mdx` in the same session. The reference doc is the single source of truth for variable semantics.
+
+### Division of responsibility
+
+- **Environment Variable Reference** (`en/self-host/configuration/environments.mdx`): exhaustive. Every variable gets a description covering purpose, defaults, interactions, and failure modes. Maintained via the `dify-docs-env-vars` skill.
+- **User Guide**: functional only. Name the mandatory variables and the values to set, then link to the reference. Do not re-explain the mechanism (WebSocket paths, worker classes, scheme rules, fallback behavior). Those details live in the reference.
+
+### How to present in the User Guide
+
+User Guides serve both SaaS (Dify Cloud) and self-hosted readers. Place self-host-only configuration in a callout rather than a dedicated H2 section. The callout surfaces the information clearly for self-hosters while letting SaaS readers skip past it without breaking the flow of the guide.
+
+Choose the callout type by what the variables do:
+
+- **`<Note>`** — when the variables are **mandatory** for the feature to work. Without them, self-hosters will not be able to use the feature at all. Example: `ENABLE_COLLABORATION_MODE` gates the entire collaboration feature.
+- **`<Info>`** — when the variables only **customize** existing behavior (tuning a default, switching backends, adjusting an endpoint). The feature works without them; these are optional knobs.
+
+Pattern (substitute `<Note>` or `<Info>` per the rule above):
+
+```mdx
+<Note>
+On self-hosted deployments, [feature] is turned off by default. Enable it by setting:
+
+- `VAR_NAME` = `value`
+- ...
+
+See [Environment Variables](/en/self-host/configuration/environments#var_name) for details.
+</Note>
+```
+
+Do not promote self-host config to an H2 section. Giving deployment-specific content equal weight with product-facing content clutters the guide for SaaS readers, who are the majority of the audience.
+
+### What to exclude from the User Guide
+
+- Default values already covered in the reference.
+- The "why" behind each variable: worker types, proxy paths, scheme rules, fallback behavior.
+- Custom-domain examples, deployment-specific mechanics, or variable interactions.
+- Anything a reader could find by clicking through to the reference.
+
 ## Style Overrides
 
 No overrides. Follow `writing-guides/style-guide.md` as written.

docs.json

@@ -82,6 +82,7 @@
                           "en/use-dify/build/shortcut-key",
                           "en/use-dify/build/mcp",
                           "en/use-dify/build/version-control",
+                          "en/use-dify/build/workflow-collaboration",
                           {
                             "group": "Debug",
                             "expanded": false,
@@ -514,6 +515,7 @@
                           "zh/use-dify/build/shortcut-key",
                           "zh/use-dify/build/mcp",
                           "zh/use-dify/build/version-control",
+                          "zh/use-dify/build/workflow-collaboration",
                           {
                             "group": "调试",
                             "expanded": false,
@@ -946,6 +948,7 @@
                           "ja/use-dify/build/shortcut-key",
                           "ja/use-dify/build/mcp",
                           "ja/use-dify/build/version-control",
+                          "ja/use-dify/build/workflow-collaboration",
                           {
                             "group": "デバッグ",
                             "expanded": false,

en/self-host/configuration/environments.mdx

@@ -91,6 +91,19 @@ Default: `300` (5 minutes)
 
 How long signed file URLs remain valid, in seconds. After this time, the URL is rejected and the file must be re-requested. Increase for long-running processes; decrease for tighter security.
 
+### ENABLE_COLLABORATION_MODE
+
+Default: `false`
+
+Master switch for real-time collaboration on the Workflow canvas, covering simultaneous editing, in-canvas comments, and @mentions.
+
+Setting this alone is not sufficient. Collaboration runs over WebSocket, which also requires:
+
+- `SERVER_WORKER_CLASS` set to `geventwebsocket.gunicorn.workers.GeventWebSocketWorker` (see [Container Startup Configuration](#container-startup-configuration)).
+- `NEXT_PUBLIC_SOCKET_URL` set to a WebSocket URL your browser can reach (see [CORS Configuration](#cors-configuration)).
+
+If you use your own reverse proxy, forward `Upgrade` and `Connection` headers on `/socket.io/` (the bundled nginx template already does this). Running multiple API replicas requires sticky sessions.
+
 ### System Encoding
 
 | Variable | Default | Description |
@@ -165,7 +178,7 @@ Only effective when starting with Docker image or Docker Compose.
 | `DIFY_BIND_ADDRESS` | `0.0.0.0` | Network interface the API server binds to. `0.0.0.0` listens on all interfaces; set to `127.0.0.1` to restrict to localhost only. |
 | `DIFY_PORT` | `5001` | Port the API server listens on. |
 | `SERVER_WORKER_AMOUNT` | `1` | Number of Gunicorn worker processes. With gevent (default), each worker handles multiple concurrent connections via greenlets, so 1 is usually sufficient. For sync workers, use `(2 x CPU cores) + 1`. [Reference](https://gunicorn.org/design/#how-many-workers). |
-| `SERVER_WORKER_CLASS` | `gevent` | Gunicorn worker type. Gevent provides lightweight async concurrency. Changing this breaks psycopg2 and gRPC patching—it is strongly discouraged. |
+| `SERVER_WORKER_CLASS` | `gevent` | Gunicorn worker type. `gevent` provides lightweight async concurrency. Set to `geventwebsocket.gunicorn.workers.GeventWebSocketWorker` when `ENABLE_COLLABORATION_MODE` is `true`; left at `gevent`, WebSocket handshakes fail silently. Other values break psycopg2 and gRPC patching. |
 | `SERVER_WORKER_CONNECTIONS` | `10` | Maximum concurrent connections per worker. Only applies to async workers (gevent). If you experience connection rejections or slow responses under load, try increasing this value. |
 | `GUNICORN_TIMEOUT` | `360` | If a worker doesn't respond within this many seconds, Gunicorn kills and restarts it. Set to 360 (6 minutes) to support long-lived SSE connections used for streaming LLM responses. |
 | `CELERY_WORKER_CLASS` | (empty; defaults to gevent) | Celery worker type. Same gevent patching requirements as `SERVER_WORKER_CLASS`—it is strongly discouraged to change. |
@@ -321,6 +334,7 @@ Controls cross-domain access policies for the frontend.
 | `CONSOLE_CORS_ALLOW_ORIGINS` | `*` | Allowed origins for cross-origin requests to the console API. If not set, falls back to `CONSOLE_WEB_URL`. |
 | `COOKIE_DOMAIN` | (empty) | Set to the shared top-level domain (e.g., `example.com`) when frontend and backend run on different subdomains. This allows authentication cookies to be shared across subdomains. When empty, cookies use the most secure `__Host-` prefix and are locked to a single domain. |
 | `NEXT_PUBLIC_COOKIE_DOMAIN` | (empty) | Frontend flag for cross-subdomain cookies. Set to `1` (or any non-empty value) to enable—the actual domain is read from `COOKIE_DOMAIN` on the backend. |
+| `NEXT_PUBLIC_SOCKET_URL` | `ws://localhost` | Browser-side WebSocket endpoint for real-time collaboration. Scheme + host + port only (path `/socket.io/` is fixed). Swap `http(s)://` for `ws(s)://`. Example: `wss://dify.example.com`. The default targets the bundled nginx on port 80. Applied at runtime; container restart picks up changes. |
 | `NEXT_PUBLIC_BATCH_CONCURRENCY` | `5` | Frontend-only. Controls how many concurrent API calls the UI makes during batch operations. |
 
 ### File Storage Configuration

en/use-dify/build/workflow-collaboration.mdx

@@ -0,0 +1,39 @@
+---
+title: Collaborate with Teammates
+description: Edit workflows with teammates in real time and discuss design decisions through in-canvas comments
+sidebarTitle: Collaboration
+---
+
+Building a workflow sometimes takes more than one person: a prompt engineer tuning instructions, a domain expert validating logic, a reviewer flagging edge cases.
+
+Rather than taking turns, you can edit the same workflow alongside your teammates and leave comments directly on the canvas, so the discussion stays with the work.
+
+<Tip>
+Comments and collaborator cursors can be hidden from the zoom menu in the bottom-right corner of the canvas.
+
+<Frame>
+![Hide Comments and Collaborator Cursors](/images/use-dify/workflow/hide-comments-collaborator-cursor.png)
+</Frame>
+</Tip>
+
+## Real-Time Editing
+
+Workspace members with editor permissions or above can edit the same workflow simultaneously. When two members change the same element at the same time, the last edit wins.
+
+## Comments
+
+Right-click an empty area of the canvas and select **Add Comment** to leave a note. To drop multiple comments in a row, press `C` to enter comment mode. Comments persist across workflow versions.
+
+If you @mention a teammate in a comment, they'll receive an email notification.
+
+Anyone with access to the app can read comments; adding, editing, or resolving requires editor permissions or above.
+
+<Note>
+On self-hosted deployments, collaboration is turned off by default. Enable it by setting:
+
+- `ENABLE_COLLABORATION_MODE` = `true`
+- `SERVER_WORKER_CLASS` = `geventwebsocket.gunicorn.workers.GeventWebSocketWorker`
+- `NEXT_PUBLIC_SOCKET_URL` = your deployment's WebSocket URL (e.g., `wss://dify.example.com`)
+
+See [Environment Variables](/en/self-host/configuration/environments#enable_collaboration_mode) for details.
+</Note>

ja/self-host/configuration/environments.mdx

@@ -93,6 +93,19 @@ Dockerネットワーク内のサービス間通信で使用されるファイ
 
 署名付きファイルURLの有効期間（秒）。この時間を過ぎるとURLは拒否され、ファイルを再リクエストする必要があります。長時間実行プロセスの場合は増加し、セキュリティを強化する場合は減少させてください。
 
+### ENABLE_COLLABORATION_MODE
+
+デフォルト値：`false`
+
+ワークフローキャンバスのリアルタイム共同編集（同時編集、キャンバス上のコメント、@メンション）を制御するマスタースイッチです。
+
+この変数を設定するだけでは不十分です。共同編集は WebSocket 経由で動作するため、以下も必要です：
+
+- `SERVER_WORKER_CLASS` を `geventwebsocket.gunicorn.workers.GeventWebSocketWorker` に設定します（[コンテナ起動設定](#コンテナ起動設定)を参照）。
+- `NEXT_PUBLIC_SOCKET_URL` をブラウザからアクセス可能な WebSocket URL に設定します（[CORS設定](#cors設定)を参照）。
+
+独自のリバースプロキシを使用する場合は `/socket.io/` パスで `Upgrade` および `Connection` ヘッダーを転送してください（同梱の nginx テンプレートにはこの設定が含まれています）。API を複数レプリカで運用する場合はスティッキーセッションが必要です。
+
 ### システムエンコーディング
 
 | 変数 | デフォルト値 | 説明 |
@@ -167,7 +180,7 @@ DockerイメージまたはDocker Composeで起動する場合にのみ有効で
 | `DIFY_BIND_ADDRESS` | `0.0.0.0` | APIサーバーがバインドするネットワークインターフェース。`0.0.0.0`はすべてのインターフェースでリッスンします。`127.0.0.1`に設定するとローカルホストのみに制限されます。 |
 | `DIFY_PORT` | `5001` | APIサーバーのリッスンポート。 |
 | `SERVER_WORKER_AMOUNT` | `1` | Gunicornワーカープロセス数。gevent（デフォルト）使用時は各ワーカーがgreenletで複数の同時接続を処理するため、通常1で十分です。同期ワーカーの場合は`(2 x CPUコア数) + 1`を使用してください。[参考ドキュメント](https://gunicorn.org/design/#how-many-workers)。 |
-| `SERVER_WORKER_CLASS` | `gevent` | Gunicornワーカータイプ。Geventは軽量な非同期並行処理を提供します。この設定を変更するとpsycopg2とgRPCのパッチが壊れます。変更は強く非推奨です。 |
+| `SERVER_WORKER_CLASS` | `gevent` | Gunicorn ワーカータイプ。`gevent` は軽量な非同期並行処理を提供します。`ENABLE_COLLABORATION_MODE` が `true` の場合、`geventwebsocket.gunicorn.workers.GeventWebSocketWorker` に設定します。`gevent` のままだと WebSocket ハンドシェイクがサイレントに失敗します。他の値は psycopg2 と gRPC のパッチを壊します。 |
 | `SERVER_WORKER_CONNECTIONS` | `10` | ワーカーごとの最大同時接続数。非同期ワーカー（gevent）にのみ適用されます。高負荷時に接続拒否やレスポンス遅延が発生する場合は、この値を増加してください。 |
 | `GUNICORN_TIMEOUT` | `360` | ワーカーがこの秒数以内に応答しない場合、Gunicornはそのワーカーを終了して再起動します。ストリーミングLLMレスポンスに使用される長時間SSE接続をサポートするため、360（6分）に設定されています。 |
 | `CELERY_WORKER_CLASS` | （空；デフォルトはgevent） | Celeryワーカータイプ。`SERVER_WORKER_CLASS`と同じgeventパッチ要件があります。変更は強く非推奨です。 |
@@ -323,6 +336,7 @@ sentinel://<redis_username>:<redis_password>@<sentinel_host>:<sentinel_port>/<re
 | `CONSOLE_CORS_ALLOW_ORIGINS` | `*` | コンソールAPIへのクロスオリジンリクエストの許可オリジン。設定されていない場合、`CONSOLE_WEB_URL`にフォールバックします。 |
 | `COOKIE_DOMAIN` | （空） | フロントエンドとバックエンドが異なるサブドメインで実行される場合、共有トップレベルドメイン（例：`example.com`）に設定します。これにより認証Cookieをサブドメイン間で共有できます。空の場合、Cookieは最もセキュアな`__Host-`プレフィックスを使用し、単一ドメインにロックされます。 |
 | `NEXT_PUBLIC_COOKIE_DOMAIN` | （空） | クロスサブドメインCookieのフロントエンドフラグ。`1`（または任意の非空値）に設定して有効化します。実際のドメインはバックエンドで`COOKIE_DOMAIN`から読み取られます。 |
+| `NEXT_PUBLIC_SOCKET_URL` | `ws://localhost` | リアルタイム共同編集のためのブラウザ側 WebSocket エンドポイント。スキーム + ホスト + ポートのみを指定します（パス `/socket.io/` は固定）。`http(s)://` を `ws(s)://` に置き換えてください。例：`wss://dify.example.com`。デフォルトは同梱 nginx の 80 番ポートに対応します。ランタイムで適用されるため、コンテナ再起動で反映されます。 |
 | `NEXT_PUBLIC_BATCH_CONCURRENCY` | `5` | フロントエンドのみ。バッチ操作時にUIが発行する同時APIコール数を制御します。 |
 
 ### ファイルストレージ設定

ja/use-dify/build/workflow-collaboration.mdx

@@ -0,0 +1,41 @@
+---
+title: チームメンバーと共同作業
+description: チームメンバーとリアルタイムでワークフローを編集し、キャンバス上のコメントで設計判断を議論できます
+sidebarTitle: コラボレーション
+---
+
+<Note> ⚠️ このドキュメントはAIによって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/use-dify/build/workflow-collaboration)を参照してください。</Note>
+
+ワークフローの構築には複数のメンバーが関わることがよくあります。プロンプトエンジニアが指示を調整し、ドメインエキスパートがロジックを検証し、レビュアーがエッジケースを指摘します。
+
+順番に作業する代わりに、チームメンバーと同じワークフローを同時に編集し、キャンバス上に直接コメントを残せます。議論が作業と一体になります。
+
+<Tip>
+コメントと共同編集者のカーソルは、キャンバス右下のズームメニューから非表示にできます。
+
+<Frame>
+![コメントと共同編集者のカーソルを非表示にする](/images/use-dify/workflow/hide-comments-collaborator-cursor.png)
+</Frame>
+</Tip>
+
+## リアルタイム編集
+
+編集権限以上を持つワークスペースメンバーは、同じワークフローを同時に編集できます。2 人のメンバーが同じ要素を同時に変更した場合、最後の編集が優先されます。
+
+## コメント
+
+キャンバスの空白部分を右クリックして **コメントを追加** を選択し、コメントを残します。連続して複数のコメントを追加するには、`C` キーを押してコメントモードに入ります。コメントはワークフローのバージョンをまたいで保持されます。
+
+コメント内でチームメンバーを @ メンションすると、メールで通知されます。
+
+アプリにアクセスできるメンバーは誰でもコメントを閲覧できます。コメントの追加、編集、解決には編集権限以上が必要です。
+
+<Note>
+セルフホスト環境では、共同編集機能はデフォルトで無効です。以下の環境変数を設定して有効化します：
+
+- `ENABLE_COLLABORATION_MODE` = `true`
+- `SERVER_WORKER_CLASS` = `geventwebsocket.gunicorn.workers.GeventWebSocketWorker`
+- `NEXT_PUBLIC_SOCKET_URL` = あなたのデプロイの WebSocket URL（例：`wss://dify.example.com`）
+
+詳細とデフォルト値は [環境変数](/ja/self-host/configuration/environments#enable_collaboration_mode) を参照してください。
+</Note>

tools/translate/config.json

@@ -28,13 +28,13 @@
             "code": "zh",
             "name": "Chinese",
             "directory": "zh",
-            "translation_notice": "<Note> ⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考[英文原版]({source_path})。</Note>\n\n"
+            "translation_notice": "<Note> ⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版]({source_path})。</Note>\n\n"
         },
         "ja": {
             "code": "ja",
             "name": "Japanese",
             "directory": "ja",
-            "translation_notice": "<Note> ⚠️ このドキュメントはAIによって自動翻訳されています。不正確な部分がある場合は、[英語版]({source_path})を参照してください。</Note>\n\n"
+            "translation_notice": "<Note> ⚠️ このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版]({source_path}) を参照してください。</Note>\n\n"
         }
     },