Skip to content

A modern and elegant dashboard for network traffic visualization and analysis.

fix(websocket): prefer direct port URL when WS_EXTERNAL_PORT is configured

luolei0b4d050a7e19
diff --git a/CHANGELOG.en.md b/CHANGELOG.en.md
index 6f60bfc..ef644d3 100644
--- a/CHANGELOG.en.md
+++ b/CHANGELOG.en.md
@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.3.6] - 2026-03-26
+
+### Fixed
+
+- **WebSocket port config ineffective in Docker direct-access mode** 🐛
+ - Fixed an issue where setting `WS_EXTERNAL_PORT` had no effect: the frontend still connected to the Web port instead of the configured WS port
+ - Root cause: in production mode, `/_cm_ws` (using `window.location.host`, i.e. the Web port) was tried first; since Next.js has no WebSocket proxy for that path, the connection failed and fell back to HTTP polling before the direct-port URL was ever tried
+ - Fix: when `runtime-config.WS_PORT` is present (i.e. `WS_EXTERNAL_PORT` is set), the direct-port URL is now preferred — no need to set `NEXT_PUBLIC_WS_URL` as a workaround
+
## [1.3.5] - 2026-03-03
### Added
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6bad498..b8721a1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,15 @@
格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),
并且本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/spec/v2.0.0.html)。
+## [1.3.6] - 2026-03-26
+
+### 修复
+
+- **WebSocket 端口配置在 Docker 直连场景下无效** 🐛
+ - 修复生产环境下 `WS_EXTERNAL_PORT` 设置后,前端仍连接到 Web 端口(而非 WS 端口)的问题
+ - 根因:生产模式优先尝试 `/_cm_ws` 路径(使用 `window.location.host`,即 Web 端口),而非配置的 WS 端口;`/_cm_ws` 在 Next.js 中没有 WebSocket 代理,导致连接失败后才 fallback 到直连端口,但此时已触发 HTTP 轮询回退
+ - 修复方式:当 `runtime-config.WS_PORT` 存在时(即用户配置了 `WS_EXTERNAL_PORT`),优先使用直连端口 URL,无需再设置 `NEXT_PUBLIC_WS_URL`
+
## [1.3.5] - 2026-03-03
### 新增
diff --git a/README.en.md b/README.en.md
index cd7a22e..9077f60 100644
--- a/README.en.md
+++ b/README.en.md
@@ -415,7 +415,7 @@ The script will automatically detect and suggest available ports.
| `WS_EXTERNAL_PORT` | `3002` | External WS port mapping in `docker-compose.yml`; also used for direct WS port inference | Direct WS access without proxy and external WS port changed |
| `NEXT_PUBLIC_API_URL` | empty | Override frontend API base URL (e.g. `https://api.example.com`) | API is not same-origin `/api` |
| `NEXT_PUBLIC_WS_URL` | empty | Override frontend WS URL (absolute URL or `/custom_ws`) | Custom WS path/domain |
-| `NEXT_PUBLIC_WS_PORT` | `3002` | WS direct-connection fallback port (build-time exposed) | Direct WS mode needs explicit port |
+| `NEXT_PUBLIC_WS_PORT` | `3002` | WS direct-connection fallback port (**build-time only — setting this at Docker runtime has no effect**; use `WS_EXTERNAL_PORT` instead) | Only for custom source builds |
| `API_URL` | `http://localhost:3001` | Next.js `/api` rewrite target (mainly source/custom builds) | API listen address changed |
| `COOKIE_SECRET` | auto-generated | Cookie signing secret; if not fixed, sessions can be invalidated after restart when data dir is not persisted | Strongly recommended in production |
| `GEOIP_LOOKUP_PROVIDER` | `online` | IP geolocation source (`online` / `local`) | Default to local MMDB lookup |
@@ -442,7 +442,7 @@ The script will automatically detect and suggest available ports.
1. API client base: `runtime-config.API_URL` → `NEXT_PUBLIC_API_URL` → same-origin `/api`
2. `/api` server-side rewrite target: `API_URL` (default `http://localhost:3001`, applied in Next.js rewrites)
-3. WS URL: `runtime-config.WS_URL` → `NEXT_PUBLIC_WS_URL` → auto candidates (production prefers `/_cm_ws`, then direct port fallback)
+3. WS URL: `runtime-config.WS_URL` → `NEXT_PUBLIC_WS_URL` → auto candidates (when `runtime-config.WS_PORT` is set, direct port is preferred; otherwise `/_cm_ws` is tried first)
4. WS port: `runtime-config.WS_PORT` (from `WS_EXTERNAL_PORT`) → `NEXT_PUBLIC_WS_PORT` → `3002`
5. In normal deployments, `NEXT_PUBLIC_WS_URL` is usually unnecessary unless you use a custom WS path/domain
diff --git a/README.md b/README.md
index 9017984..811e684 100644
--- a/README.md
+++ b/README.md
@@ -406,7 +406,7 @@ curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh |
| `WS_EXTERNAL_PORT` | `3002` | `docker-compose.yml` 的 WS 外部端口映射;同时用于前端直连 WS 端口推断 | 非反代直连 WS 且外部端口变化时 |
| `NEXT_PUBLIC_API_URL` | 空 | 覆盖前端 API 基地址(如 `https://api.example.com`) | API 不走同域 `/api` 时 |
| `NEXT_PUBLIC_WS_URL` | 空 | 覆盖前端 WS 地址(支持绝对 URL 或 `/custom_ws`) | WS 路径/域名自定义时 |
-| `NEXT_PUBLIC_WS_PORT` | `3002` | WS 直连端口兜底值(构建时注入) | 非反代直连 WS 且需显式指定端口时 |
+| `NEXT_PUBLIC_WS_PORT` | `3002` | WS 直连端口兜底值(**构建时注入,Docker 运行时设置无效**;Docker 场景请用 `WS_EXTERNAL_PORT`) | 仅源码自构建时需要自定义端口 |
| `API_URL` | `http://localhost:3001` | Next.js `/api` rewrite 目标(主要用于源码/自构建) | 你修改了 API 实际监听地址时 |
| `COOKIE_SECRET` | 自动生成 | Cookie 签名密钥;未固定时会自动生成(数据目录不持久化时重启后会话会失效) | 生产环境强烈建议固定配置 |
| `GEOIP_LOOKUP_PROVIDER` | `online` | IP 地理查询来源(`online`/`local`) | 需要默认走本地 MMDB 查询时 |
@@ -433,7 +433,7 @@ curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/setup.sh |
1. API 客户端基址:`runtime-config.API_URL` → `NEXT_PUBLIC_API_URL` → 默认同域 `/api`
2. `/api` 的服务端转发目标:`API_URL`(默认 `http://localhost:3001`,在 Next.js rewrite 中生效)
-3. WS URL:`runtime-config.WS_URL` → `NEXT_PUBLIC_WS_URL` → 自动候选(生产优先 `/_cm_ws`,失败再尝试直连端口)
+3. WS URL:`runtime-config.WS_URL` → `NEXT_PUBLIC_WS_URL` → 自动候选(`runtime-config.WS_PORT` 存在时优先直连端口,否则优先 `/_cm_ws`)
4. WS 端口:`runtime-config.WS_PORT`(来自 `WS_EXTERNAL_PORT`)→ `NEXT_PUBLIC_WS_PORT` → `3002`
5. 默认部署下无需手动配置 `NEXT_PUBLIC_WS_URL`;仅当你自定义 WS 路径/域名时再设置
diff --git a/apps/web/lib/websocket.ts b/apps/web/lib/websocket.ts
index b81f6e0..87170d7 100644
--- a/apps/web/lib/websocket.ts
+++ b/apps/web/lib/websocket.ts
@@ -151,7 +151,11 @@ function getWsUrlCandidates(): string[] {
const hostForPath = runtime?.WS_HOST || window.location.host;
const pathUrl = `${wsProtocol}://${hostForPath}/_cm_ws`;
- const preferDirect = process.env.NODE_ENV === 'development';
+ // Prefer direct port URL when an explicit WS port is configured at runtime
+ // (e.g. Docker with WS_EXTERNAL_PORT), since /_cm_ws has no WS proxy in Next.js.
+ // In development, also prefer direct so the dev WS server is hit first.
+ const preferDirect =
+ process.env.NODE_ENV === 'development' || !!runtime?.WS_PORT;
if (preferDirect) {
pushCandidate(directUrl);
pushCandidate(pathUrl);
diff --git a/apps/web/next.config.ts b/apps/web/next.config.ts
index 43d01fa..4815f05 100644
--- a/apps/web/next.config.ts
+++ b/apps/web/next.config.ts
@@ -26,7 +26,9 @@ const nextConfig: NextConfig = {
outputFileTracingRoot: join(__dirname, '../..'),
env: {
NEXT_PUBLIC_APP_VERSION: rootPkg.version || "0.0.0",
- // Expose WebSocket port to browser (for client-side use)
+ // NOTE: NEXT_PUBLIC_WS_PORT is a build-time variable baked into the JS bundle.
+ // At runtime (e.g. Docker), use WS_EXTERNAL_PORT env var instead — it is written
+ // into runtime-config.js by docker-start.sh and read via window.__RUNTIME_CONFIG__.
NEXT_PUBLIC_WS_PORT: process.env.NEXT_PUBLIC_WS_PORT || "3002",
},
// Turbopack configuration (formerly experimental.turbopack)
diff --git a/package.json b/package.json
index 5b1864a..81042c2 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "neko-master",
- "version": "1.3.5",
+ "version": "1.3.6",
"description": "Modern traffic analytics for edge gateways",
"private": true,
"workspaces": [