diff --git a/.env.sample b/.env.sample
index ca9ddd4..134730f 100644
--- a/.env.sample
+++ b/.env.sample
@@ -21,8 +21,14 @@ WEB_PORT=3010
 # easyai-web 前端端口，访问地址 ip:3010，初始化管理员 admin/123456
 
 SERVER_HTTP_PORT=3001
-SERVER_WS_PORT=3002
-# easyai-server 后端 HTTP / WebSocket 端口
+# easyai-server 后端 HTTP 端口
+
+# ws-gateway WebSocket 端口（统一作为对外访问映射端口使用）
+CONFIG_WS_PORT=3002
+# ws-gateway 容器内部 TCP 微服务监听地址（供 easyai-server 推送事件）
+CONFIG_TCP_HOST=0.0.0.0
+# ws-gateway 容器内部 TCP 微服务监听端口（默认 4002）
+CONFIG_TCP_PORT=4002
 
 VIDEO_EDIT_PORT=8000
 # 视频编辑服务对外端口
@@ -88,13 +94,57 @@ WATCHTOWER_PORT=8089
 PORTAINER_PORT=8090
 PORTAINER_HTTPS_PORT=8091
 
-# ========== 10. 静态资源 CDN（可选） ==========
+# ========== 10. WS Gateway 集群背板（Redis） ==========
+# 是否启用 ws-gateway Redis 集群背板：true=支持多节点路由，false=仅单机本地投递
+GATEWAY_CLUSTER_REDIS_ENABLED=true
+# 当前 ws-gateway 节点 ID；单节点可保持默认，集群部署时每个实例必须唯一
+GATEWAY_CLUSTER_NODE_ID=easyai-wsgateway-node-1
+# 背板 Pub/Sub 频道名；用于节点间转发消息
+GATEWAY_CLUSTER_REDIS_CHANNEL=easyai:wsgateway:cluster
+# 路由表 key 前缀（记录 channel+clientId 对应的 nodeId）
+GATEWAY_CLUSTER_REDIS_ROUTE_PREFIX=easyai:wsgateway:route
+# 路由 TTL（秒）；连接存活期间会续租，断开后自然过期
+GATEWAY_CLUSTER_REDIS_ROUTE_TTL_SEC=120
+# Redis 失联后自动重连间隔（毫秒）
+GATEWAY_CLUSTER_REDIS_RECONNECT_INTERVAL_MS=5000
+# 可选：Redis URL（配置后优先于 host/port/user/password/db）
+GATEWAY_CLUSTER_REDIS_URL=
+# 以下为 URL 未配置时使用的拆分配置
+GATEWAY_CLUSTER_REDIS_HOST=redis
+GATEWAY_CLUSTER_REDIS_PORT=6379
+GATEWAY_CLUSTER_REDIS_USERNAME=
+GATEWAY_CLUSTER_REDIS_PASSWORD=
+GATEWAY_CLUSTER_REDIS_DB=0
+
+# ========== 11. easyai-server 发布事件到 ws-gateway（TCP） ==========
+# easyai-server 访问 ws-gateway 的 TCP 地址（容器网络内建议写服务名 ws-gateway）
+WS_GATEWAY_TCP_HOST=ws-gateway
+# easyai-server 访问 ws-gateway 的 TCP 端口（需与 CONFIG_TCP_PORT 一致）
+WS_GATEWAY_TCP_PORT=4002
+# 事件发布 Pattern，通常保持默认
+WS_GATEWAY_TCP_EVENT_PATTERN=gateway.event.publish
+# 发布超时时间（毫秒）；超时只记录 ERROR，不中断主进程
+WS_GATEWAY_TCP_TIMEOUT_MS=1500
+
+# ========== 12. WS 会话鉴权（MCP 风格，可选） ==========
+# true=客户端必须鉴权后才能建立可用会话；false=允许匿名会话
+WS_AUTH_REQUIRED=false
+# 鉴权阶段超时时间（毫秒）
+WS_AUTH_TIMEOUT_MS=6000
+# 可用鉴权方法（逗号分隔）：none/bearer/ws_ticket
+WS_AUTH_METHODS=none,bearer
+# bearer 令牌列表（逗号分隔，生产环境请使用安全配置中心）
+WS_AUTH_BEARER_TOKENS=
+# ws_ticket 票据列表（逗号分隔，适合短时授权）
+WS_AUTH_WS_TICKETS=
+
+# ========== 13. 静态资源 CDN（可选） ==========
 NUXT_APP_CDN_URL=
 
-# ========== 11. 版本 ==========
+# ========== 14. 版本 ==========
 VERSION=latest
 
-# ========== 12. OSS 配置（可选，PDF 解析图片上传） ==========
+# ========== 15. OSS 配置（可选，PDF 解析图片上传） ==========
 # 可填写 .env.tools 或在此覆盖
 # OSS_ENDPOINT=
 # OSS_ACCESS_KEY_ID=
diff --git a/docker-compose.yml b/docker-compose.yml
index 6cc6223..037d58a 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -126,7 +126,7 @@ services:
     labels:
       - "com.centurylinklabs.watchtower.enable=true"
     ports:
-      - "${SERVER_WS_PORT}:3002"    #http端口
+      - "${CONFIG_WS_PORT}:3002"    # ws-gateway WebSocket 对外端口映射
     read_only: true
     networks:
       - comfyai