WebSocket Service Architecture#

Dify's WebSocket support is built around a dedicated api_websocket Docker Compose service for real-time workflow collaboration. It uses Socket.IO with a Redis-backed cross-process pub/sub manager for multi-worker correctness, and JWT authentication that requires a shared SECRET_KEY across all API processes.

Service Activation (Profile-Based)#

The api_websocket service runs the same langgenius/dify-api image as the main API, but is only started when the collaboration Compose profile is active 1. It was separated from the main api service to isolate WebSocket workload 2.

The service mounts the shared storage volume (./volumes/app/storage:/app/api/storage) to persist user files and the auto-generated .dify_secret_key, and depends on the init_permissions service to ensure correct ownership is set before startup 3.

In docker/.env.example, COMPOSE_PROFILES includes collaboration by default, so the service starts automatically in standard deployments 3:

COMPOSE_PROFILES=${VECTOR_STORE:-weaviate},${DB_TYPE:-postgresql},collaboration

The service's worker configuration can be tuned independently from the main API 4:

Nginx routes /socket.io/ traffic to the upstream defined by NGINX_SOCKET_IO_UPSTREAM (default: api_websocket:5001) 5 6.

Redis-Backed Multi-Worker Pub/Sub#

The core of multi-worker support is socketio.RedisManager, initialized in ext_socketio.py. Without this, Socket.IO room broadcasts are process-local, so a client connected to worker A would not receive events emitted by worker B 7.

Key implementation details in create_socketio_client_manager():

• Redis URL: reads dify_config.normalized_pubsub_redis_url, which resolves to PUBSUB_REDIS_URL if set, or falls back to building a URL from the standard REDIS_* variables 8.
• Channel namespacing: the pub/sub channel is serialize_redis_name("socketio"), which applies the deployment's REDIS_KEY_PREFIX — preventing cross-deployment interference on shared Redis instances 9 10.
• TLS support: if the Redis URL scheme is rediss://, SSL options (REDIS_SSL_CERT_REQS, REDIS_SSL_CA_CERTS, etc.) are forwarded to the manager 11.
• Global sio object: socketio.Server is instantiated once at module load with async_mode="gevent", client_manager=create_socketio_client_manager(), and max_http_buffer_size=dify_config.WEBSOCKET_MAX_HTTP_BUFFER_SIZE 12. The buffer size setting prevents large workflow graph payloads in sync_request events from exceeding Engine.IO's limit and disconnecting clients.

PR #38242 also added Redis hash wrapper methods (hkeys, hexists) to ext_redis.py to ensure prefixed key operations work correctly for collaboration session tracking 13.

┌─────────────────┐ ┌─────────────────┐
│ api_websocket │ │ api_websocket │
│ (Process A) │ │ (Process B) │
│ sio (Server) │ │ sio (Server) │
└────────┬────────┘ └────────┬────────┘
         │ │
         └───────────┬───────────┘
              Redis pub/sub
           (channel: <prefix>:socketio)

JWT Authentication#

Every Socket.IO connection is authenticated on the connect event in api/controllers/console/socketio/workflow.py:

1. The access token is extracted from the request environ.
2. PassportService().verify(token) decodes the JWT using HS256 with dify_config.SECRET_KEY.
3. The user_id is pulled from the decoded payload and the account is loaded and permission-checked.
4. On success, socket identity is saved via the collaboration service; on failure, False is returned, rejecting the connection.

Critical: PassportService uses dify_config.SECRET_KEY for both signing (issue) and verification (verify) 14. In any deployment where api and api_websocket are separate processes — including multi-worker or Kubernetes — all instances must share the same SECRET_KEY. A mismatch causes InvalidSignatureError and silently drops all WebSocket connections.

When SECRET_KEY is left empty (the documented default in .env.example), the application auto-generates a persistent key in the storage directory. For this to work correctly, all services (api, worker, api_websocket) must mount the same storage volume so they read the same .dify_secret_key file. The storage volume mount on api_websocket ensures this consistency 15.

Key Files#

Related PRs#

• #35981 — chore: separate websocket service — introduced dedicated api_websocket service and collaboration Compose profile
• #38242 — fix: support multi-worker workflow collaboration — added socketio.RedisManager for cross-process pub/sub, configurable worker count
• #39424 — fix(docker): mount shared storage volume in api_websocket — added storage volume mount and init_permissions dependency to api_websocket for SECRET_KEY consistency