Focalboard WebSocket 连接失败排查反向代理配置与 /ws 实时通道原理【免费下载链接】focalboardFocalboard is an open source, self-hosted alternative to Trello, Notion, and Asana.项目地址: https://gitcode.com/GitHub_Trending/fo/focalboard导读Focalboard 通过 WebSocket 实现看板、卡片与属性的实时同步当浏览器端长期无法建立 WebSocket 连接时界面通常表现为能打开页面但数据不更新、操作无实时反馈。本文以官方排障指南 website/site/content/guide/websocket-errors/_index.md 为核心骨架结合前端 webapp/src/wsclient.ts 与后端 server/ws/server.go 的源码实现系统讲解连接失败的根因、两种部署形态下的修复方法以及一套可复现的验证流程。读完本文你将掌握如何用正确的 NGINX 反向代理配置让 Focalboard 的 WebSocket 通道稳定工作。一、先定位WebSocket 连接失败的典型表现与日志特征Focalboard 的前端 WebSocket 客户端位于 webapp/src/wsclient.ts其连接 URL 的构造逻辑非常关键const url new URL(this.getBaseURL()) const protocol (url.protocol https:) ? wss: : ws: const wsServerUrl ${protocol}//${url.host}${url.pathname.replace(/\/$/, )}/ws即浏览器会以ws://或wss://协议向与页面同源的/ws端点发起连接。后端在 server/ws/server.go 中注册了对应路由func (ws *Server) RegisterRoutes(r *mux.Router) { r.HandleFunc(/ws, ws.handleWebSocket) }当连接无法建立时前端会留下以下可检索的日志特征源码可见于 webapp/src/wsclient.tsWSClient websocket onerror. data: ...—— 由ws.onerror回调输出说明 TCP/代理层握手失败WSClient websocket onclose, code: X, reason: Y—— 由ws.onclose回调输出code/reason 可用于区分正常关闭与异常中断Unexpected WSClient close与Reopening websocket connection, count: N—— 说明连接被意外关闭客户端正按reopenDelay间隔自动重连直至达到reopenMaxRetries上限后输出Reached max websocket re-opening attempts。服务端侧升级握手失败时会输出ERROR upgrading to websocket见 server/ws/server.go。因此排查的第一步是确认浏览器 DevTools 的 Network 面板中/ws请求是否返回101 Switching Protocols以及上述日志的出现位置——这能快速判断问题出在客户端、反代层还是服务端。二、根因Web 代理没有透传 HTTP Upgrade 握手WebSocket 连接的建立依赖 HTTP 的协议升级机制客户端在请求头中携带Upgrade: websocket与Connection: Upgrade服务端同意后返回101状态码随后的通信转为全双工 WebSocket 帧。Focalboard 官方排障文档明确指出如果 WebSocket 持续无法连接应首先检查 Web 代理的配置是否正确。原因在于任何位于浏览器与 Focalboard 服务之间的代理NGINX、Caddy、云负载均衡等若未显式透传这两个升级头或未将/ws路径的请求交给支持长连接的后端浏览器与后端之间的握手就会被截断表现为页面正常、实时同步失效。Focalboard 官方指南给出的检查路线有两条分别对应两种部署形态以 Mattermost 插件形式运行 Focalboard见 部署形态说明以 Personal Server 独立服务运行并前置 NGINX见 Personal ServerUbuntu部署文档。下面分别展开。三、场景一以 Mattermost 插件部署时检查 Mattermost 侧代理当 Focalboard 作为 Mattermost 插件运行时前端并不直接连接 Focalboard 自身的/ws而是复用 Mattermost 的 WebSocket 连接。这一点在 webapp/src/wsclient.ts 中有明确分支当this.client ! null即插件模式时客户端为 Mattermost 的 WebSocket 客户端注册onConnect / onReconnect / onClose / onError四类回调其中onClose还会以 500ms 间隔轮询底层conn.readyState直到状态回到1OPEN才触发重连恢复。后端对应实现在 server/ws/plugin_adapter.go它通过 Mattermost 插件 API 接收WebSocketMessageHasBeenPosted等事件消息动作统一以custom_focalboard_为前缀如custom_focalboard_UPDATE_BLOCK见 server/ws/adapter.go。这意味着若 Mattermost 本身运行在某个 Web 代理之后该代理必须同样支持 WebSocket Upgrade 透传否则插件模式下 Focalboard 的实时同步同样会失效排查时可先直接访问 Mattermost 原生界面确认其自身的实时事件是否正常——若 Mattermost 的 WebSocket 也不通问题出在 Mattermost 的前置代理若 Mattermost 正常而 Focalboard 无实时更新再检查插件版本与订阅消息是否成功。四、场景二Personal Server NGINX 的完整修复配置对于独立部署的 Focalboard Personal Server默认监听8000端口该端口由config.json指定官方推荐使用 NGINX 作为 Web 代理将 80 端口的 HTTP 与 WebSocket 请求转发至后端。以下配置完整取自部署文档的 Configure NGINX 一节见 website/site/content/docs/personal-edition/ubuntu.md其中location ~ /ws/*块正是解决 WebSocket 连接失败的核心upstream focalboard { server localhost:8000; keepalive 32; } server { listen 80 default_server; server_name focalboard.example.com; location ~ /ws/* { proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; client_max_body_size 50M; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Frame-Options SAMEORIGIN; proxy_buffers 256 16k; proxy_buffer_size 16k; client_body_timeout 60; send_timeout 300; lingering_timeout 5; proxy_connect_timeout 1d; proxy_send_timeout 1d; proxy_read_timeout 1d; proxy_pass http://focalboard; } location / { client_max_body_size 50M; proxy_set_header Connection ; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Frame-Options SAMEORIGIN; proxy_buffers 256 16k; proxy_buffer_size 16k; proxy_read_timeout 600s; proxy_cache_revalidate on; proxy_cache_min_uses 2; proxy_cache_use_stale timeout; proxy_cache_lock on; proxy_http_version 1.1; proxy_pass http://focalboard; } }关键配置项逐条解析配置项作用与 WebSocket 的关系proxy_set_header Upgrade $http_upgrade;将客户端的Upgrade请求头原样转发给后端WebSocket 握手的关键缺失则后端无法感知升级意图proxy_set_header Connection upgrade;强制将Connection头改写为upgrade配合Upgrade头完成 101 升级缺失则握手失败proxy_read_timeout 1d;设置后端响应读取超时为 1 天WebSocket 长连接空闲时不会因默认 60s 超时被 NGINX 掐断proxy_connect_timeout 1d;/proxy_send_timeout 1d;连接建立与发送超时同样放宽避免高延迟网络下握手被中断upstream ... keepalive 32;与后端保持 32 个空闲长连接减少频繁重建 TCP 连接带来的握手抖动proxy_http_version 1.1;普通 location 块使用 HTTP/1.1 与后端通信普通请求块中配合清空的Connection头支持 keepalive注意它与 WebSocket 块的Connection upgrade互斥需分块配置两个 location 块分工明确/ws/*走 WebSocket 升级语义/走常规 HTTP 缓存语义Connection 清空连接头以启用 keepalive。切勿将Connection upgrade误用在普通请求块或将普通块的无升级头配置套用到/ws块这是最常见的配置错误。启用与验证创建配置后按顺序执行完整步骤见 website/site/content/docs/personal-edition/ubuntu.md# 若存在默认站点需先移除 sudo rm /etc/nginx/sites-enabled/default # 启用 Focalboard 站点、测试配置并重载 sudo ln -s /etc/nginx/sites-available/focalboard /etc/nginx/sites-enabled/focalboard sudo nginx -t sudo /etc/init.d/nginx reload部署文档提供了两条验证命令curl localhost:8000 curl localhost第一条检查 Focalboard 服务是否在 8000 端口默认正常运行第二条检查 NGINX 是否成功代理两条命令应返回相同的 HTML 片段。若第二条失败说明代理层配置有误若两条均正常但 WebSocket 仍报错则需用下方诊断方法进一步确认。五、深度诊断从客户端日志到服务端握手1. 浏览器侧确认 101 状态码打开 DevTools → Network → 筛选ws类型的请求查看/ws请求状态为101 Switching Protocols代理与后端升级成功问题不在传输层状态为200/404/502或持续(failed)说明请求被普通 HTTP 逻辑处理或代理层拒绝即升级头未正确透传结合第一节的客户端日志可判断是onerror握手失败还是onclose连接被中途掐断常见原因是代理超时。2. 服务端侧确认升级路径在后端 server/ws/server.go 中握手失败会输出ERROR upgrading to websocket。若服务端持续输出该错误说明升级请求未到达或到达时缺少正确的请求头若没有任何该日志则请求可能根本没被路由到/ws例如被前置代理按静态资源处理。3. 订阅与鉴权链路握手成功只是第一步。连接建立后前端在ws.onopen中会发送AUTH认证指令若配置了 token随后发送SUBSCRIBE_TEAM/SUBSCRIBE_BLOCKS等订阅消息动作常量定义见 server/ws/adapter.go。若代理层将 WebSocket 数据帧误判为普通请求并缓冲/丢弃会出现连接显示已建立但收不到任何推送的现象此时应检查代理是否对/ws关闭了缓存与缓冲类指令。六、补充Docker 部署与端口映射使用 Docker 运行 Personal Server 时见 website/site/content/docs/personal-edition/docker.md单条命令即可启动docker run -it -p 80:8000 mattermost/focalboard将宿主 80 端口映射到容器 8000 端口后浏览器直接访问http://localhost即可此时 WebSocket 同样经由 80 端口工作。若仍需在前置再加一层代理请复用第四节中的/ws升级头配置若直接暴露 8000 端口访问则不存在代理截断问题但仍需确认防火墙放行该端口。七、客户端自动重连机制为什么问题会被掩盖值得一提的细节是Focalboard 前端内置了自动重连逻辑这在 webapp/src/wsclient.ts 中体现得很充分——ws.onclose中只要关闭的不是主动发起的ws this.ws就会按reopenDelay间隔递增重连次数并重新调用open()达到reopenMaxRetries上限后才停止。因此配置错误时用户看到的往往是反复刷新仍不同步而非直接报错容易被误判为服务端故障。掌握第一节的日志关键字Unexpected WSClient close、Reopening websocket connection是快速区分代理配置问题与服务端故障的关键。结语Focalboard 的 WebSocket 通道是一条从浏览器/ws到后端 server/ws/server.go 的完整链路任何一层代理对 Upgrade 握手的改造都会导致实时同步失效。按照官方排障指南的路线插件部署查 Mattermost 侧代理独立部署查 NGINX 的location ~ /ws/*升级头与超时配置再配合本文提供的日志关键字与 curl 验证命令即可系统化地定位并修复连接问题。【免费下载链接】focalboardFocalboard is an open source, self-hosted alternative to Trello, Notion, and Asana.项目地址: https://gitcode.com/GitHub_Trending/fo/focalboard创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Focalboard WebSocket 连接失败排查：反向代理配置与 /ws 实时通道原理
Focalboard WebSocket 连接失败排查反向代理配置与 /ws 实时通道原理【免费下载链接】focalboardFocalboard is an open source, self-hosted alternative to Trello, Notion, and Asana.项目地址: https://gitcode.com/GitHub_Trending/fo/focalboard导读Focalboard 通过 WebSocket 实现看板、卡片与属性的实时同步当浏览器端长期无法建立 WebSocket 连接时界面通常表现为能打开页面但数据不更新、操作无实时反馈。本文以官方排障指南 website/site/content/guide/websocket-errors/_index.md 为核心骨架结合前端 webapp/src/wsclient.ts 与后端 server/ws/server.go 的源码实现系统讲解连接失败的根因、两种部署形态下的修复方法以及一套可复现的验证流程。读完本文你将掌握如何用正确的 NGINX 反向代理配置让 Focalboard 的 WebSocket 通道稳定工作。一、先定位WebSocket 连接失败的典型表现与日志特征Focalboard 的前端 WebSocket 客户端位于 webapp/src/wsclient.ts其连接 URL 的构造逻辑非常关键const url new URL(this.getBaseURL()) const protocol (url.protocol https:) ? wss: : ws: const wsServerUrl ${protocol}//${url.host}${url.pathname.replace(/\/$/, )}/ws即浏览器会以ws://或wss://协议向与页面同源的/ws端点发起连接。后端在 server/ws/server.go 中注册了对应路由func (ws *Server) RegisterRoutes(r *mux.Router) { r.HandleFunc(/ws, ws.handleWebSocket) }当连接无法建立时前端会留下以下可检索的日志特征源码可见于 webapp/src/wsclient.tsWSClient websocket onerror. data: ...—— 由ws.onerror回调输出说明 TCP/代理层握手失败WSClient websocket onclose, code: X, reason: Y—— 由ws.onclose回调输出code/reason 可用于区分正常关闭与异常中断Unexpected WSClient close与Reopening websocket connection, count: N—— 说明连接被意外关闭客户端正按reopenDelay间隔自动重连直至达到reopenMaxRetries上限后输出Reached max websocket re-opening attempts。服务端侧升级握手失败时会输出ERROR upgrading to websocket见 server/ws/server.go。因此排查的第一步是确认浏览器 DevTools 的 Network 面板中/ws请求是否返回101 Switching Protocols以及上述日志的出现位置——这能快速判断问题出在客户端、反代层还是服务端。二、根因Web 代理没有透传 HTTP Upgrade 握手WebSocket 连接的建立依赖 HTTP 的协议升级机制客户端在请求头中携带Upgrade: websocket与Connection: Upgrade服务端同意后返回101状态码随后的通信转为全双工 WebSocket 帧。Focalboard 官方排障文档明确指出如果 WebSocket 持续无法连接应首先检查 Web 代理的配置是否正确。原因在于任何位于浏览器与 Focalboard 服务之间的代理NGINX、Caddy、云负载均衡等若未显式透传这两个升级头或未将/ws路径的请求交给支持长连接的后端浏览器与后端之间的握手就会被截断表现为页面正常、实时同步失效。Focalboard 官方指南给出的检查路线有两条分别对应两种部署形态以 Mattermost 插件形式运行 Focalboard见 部署形态说明以 Personal Server 独立服务运行并前置 NGINX见 Personal ServerUbuntu部署文档。下面分别展开。三、场景一以 Mattermost 插件部署时检查 Mattermost 侧代理当 Focalboard 作为 Mattermost 插件运行时前端并不直接连接 Focalboard 自身的/ws而是复用 Mattermost 的 WebSocket 连接。这一点在 webapp/src/wsclient.ts 中有明确分支当this.client ! null即插件模式时客户端为 Mattermost 的 WebSocket 客户端注册onConnect / onReconnect / onClose / onError四类回调其中onClose还会以 500ms 间隔轮询底层conn.readyState直到状态回到1OPEN才触发重连恢复。后端对应实现在 server/ws/plugin_adapter.go它通过 Mattermost 插件 API 接收WebSocketMessageHasBeenPosted等事件消息动作统一以custom_focalboard_为前缀如custom_focalboard_UPDATE_BLOCK见 server/ws/adapter.go。这意味着若 Mattermost 本身运行在某个 Web 代理之后该代理必须同样支持 WebSocket Upgrade 透传否则插件模式下 Focalboard 的实时同步同样会失效排查时可先直接访问 Mattermost 原生界面确认其自身的实时事件是否正常——若 Mattermost 的 WebSocket 也不通问题出在 Mattermost 的前置代理若 Mattermost 正常而 Focalboard 无实时更新再检查插件版本与订阅消息是否成功。四、场景二Personal Server NGINX 的完整修复配置对于独立部署的 Focalboard Personal Server默认监听8000端口该端口由config.json指定官方推荐使用 NGINX 作为 Web 代理将 80 端口的 HTTP 与 WebSocket 请求转发至后端。以下配置完整取自部署文档的 Configure NGINX 一节见 website/site/content/docs/personal-edition/ubuntu.md其中location ~ /ws/*块正是解决 WebSocket 连接失败的核心upstream focalboard { server localhost:8000; keepalive 32; } server { listen 80 default_server; server_name focalboard.example.com; location ~ /ws/* { proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; client_max_body_size 50M; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Frame-Options SAMEORIGIN; proxy_buffers 256 16k; proxy_buffer_size 16k; client_body_timeout 60; send_timeout 300; lingering_timeout 5; proxy_connect_timeout 1d; proxy_send_timeout 1d; proxy_read_timeout 1d; proxy_pass http://focalboard; } location / { client_max_body_size 50M; proxy_set_header Connection ; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Frame-Options SAMEORIGIN; proxy_buffers 256 16k; proxy_buffer_size 16k; proxy_read_timeout 600s; proxy_cache_revalidate on; proxy_cache_min_uses 2; proxy_cache_use_stale timeout; proxy_cache_lock on; proxy_http_version 1.1; proxy_pass http://focalboard; } }关键配置项逐条解析配置项作用与 WebSocket 的关系proxy_set_header Upgrade $http_upgrade;将客户端的Upgrade请求头原样转发给后端WebSocket 握手的关键缺失则后端无法感知升级意图proxy_set_header Connection upgrade;强制将Connection头改写为upgrade配合Upgrade头完成 101 升级缺失则握手失败proxy_read_timeout 1d;设置后端响应读取超时为 1 天WebSocket 长连接空闲时不会因默认 60s 超时被 NGINX 掐断proxy_connect_timeout 1d;/proxy_send_timeout 1d;连接建立与发送超时同样放宽避免高延迟网络下握手被中断upstream ... keepalive 32;与后端保持 32 个空闲长连接减少频繁重建 TCP 连接带来的握手抖动proxy_http_version 1.1;普通 location 块使用 HTTP/1.1 与后端通信普通请求块中配合清空的Connection头支持 keepalive注意它与 WebSocket 块的Connection upgrade互斥需分块配置两个 location 块分工明确/ws/*走 WebSocket 升级语义/走常规 HTTP 缓存语义Connection 清空连接头以启用 keepalive。切勿将Connection upgrade误用在普通请求块或将普通块的无升级头配置套用到/ws块这是最常见的配置错误。启用与验证创建配置后按顺序执行完整步骤见 website/site/content/docs/personal-edition/ubuntu.md# 若存在默认站点需先移除 sudo rm /etc/nginx/sites-enabled/default # 启用 Focalboard 站点、测试配置并重载 sudo ln -s /etc/nginx/sites-available/focalboard /etc/nginx/sites-enabled/focalboard sudo nginx -t sudo /etc/init.d/nginx reload部署文档提供了两条验证命令curl localhost:8000 curl localhost第一条检查 Focalboard 服务是否在 8000 端口默认正常运行第二条检查 NGINX 是否成功代理两条命令应返回相同的 HTML 片段。若第二条失败说明代理层配置有误若两条均正常但 WebSocket 仍报错则需用下方诊断方法进一步确认。五、深度诊断从客户端日志到服务端握手1. 浏览器侧确认 101 状态码打开 DevTools → Network → 筛选ws类型的请求查看/ws请求状态为101 Switching Protocols代理与后端升级成功问题不在传输层状态为200/404/502或持续(failed)说明请求被普通 HTTP 逻辑处理或代理层拒绝即升级头未正确透传结合第一节的客户端日志可判断是onerror握手失败还是onclose连接被中途掐断常见原因是代理超时。2. 服务端侧确认升级路径在后端 server/ws/server.go 中握手失败会输出ERROR upgrading to websocket。若服务端持续输出该错误说明升级请求未到达或到达时缺少正确的请求头若没有任何该日志则请求可能根本没被路由到/ws例如被前置代理按静态资源处理。3. 订阅与鉴权链路握手成功只是第一步。连接建立后前端在ws.onopen中会发送AUTH认证指令若配置了 token随后发送SUBSCRIBE_TEAM/SUBSCRIBE_BLOCKS等订阅消息动作常量定义见 server/ws/adapter.go。若代理层将 WebSocket 数据帧误判为普通请求并缓冲/丢弃会出现连接显示已建立但收不到任何推送的现象此时应检查代理是否对/ws关闭了缓存与缓冲类指令。六、补充Docker 部署与端口映射使用 Docker 运行 Personal Server 时见 website/site/content/docs/personal-edition/docker.md单条命令即可启动docker run -it -p 80:8000 mattermost/focalboard将宿主 80 端口映射到容器 8000 端口后浏览器直接访问http://localhost即可此时 WebSocket 同样经由 80 端口工作。若仍需在前置再加一层代理请复用第四节中的/ws升级头配置若直接暴露 8000 端口访问则不存在代理截断问题但仍需确认防火墙放行该端口。七、客户端自动重连机制为什么问题会被掩盖值得一提的细节是Focalboard 前端内置了自动重连逻辑这在 webapp/src/wsclient.ts 中体现得很充分——ws.onclose中只要关闭的不是主动发起的ws this.ws就会按reopenDelay间隔递增重连次数并重新调用open()达到reopenMaxRetries上限后才停止。因此配置错误时用户看到的往往是反复刷新仍不同步而非直接报错容易被误判为服务端故障。掌握第一节的日志关键字Unexpected WSClient close、Reopening websocket connection是快速区分代理配置问题与服务端故障的关键。结语Focalboard 的 WebSocket 通道是一条从浏览器/ws到后端 server/ws/server.go 的完整链路任何一层代理对 Upgrade 握手的改造都会导致实时同步失效。按照官方排障指南的路线插件部署查 Mattermost 侧代理独立部署查 NGINX 的location ~ /ws/*升级头与超时配置再配合本文提供的日志关键字与 curl 验证命令即可系统化地定位并修复连接问题。【免费下载链接】focalboardFocalboard is an open source, self-hosted alternative to Trello, Notion, and Asana.项目地址: https://gitcode.com/GitHub_Trending/fo/focalboard创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
