Clawdbot+Qwen3:32B部署教程：Web端WebSocket长连接与心跳保活配置-平芜编程栈

Clawdbot+Qwen3:32B部署教程：Web端WebSocket长连接与心跳保活配置

1. 为什么需要WebSocket长连接与心跳保活

你有没有遇到过这样的情况：网页聊天界面突然卡住，发送消息没反应，刷新页面后对话历史全没了？或者模型响应中途断开，用户正在输入时连接突然消失？这些问题在大模型Web应用中非常常见，尤其当后端使用Qwen3:32B这类重型模型时，推理耗时长、连接空闲期易被中间代理或浏览器关闭。

Clawdbot作为轻量级Chat平台网关，本身不处理模型推理，而是将请求转发给Ollama托管的Qwen3:32B。但默认HTTP短连接无法支撑流式响应（streaming）和实时交互——用户打字时希望看到逐字输出，而不是等整段生成完才显示；后台也需持续感知前端是否在线，避免无效资源占用。

这就引出了核心需求：必须用WebSocket替代HTTP，再配合心跳机制维持稳定长连接。这不是可选项，而是Qwen3:32B在Web端真正可用的前提。

本教程不讲抽象概念，只聚焦三件事：

怎么让Clawdbot正确升级到WebSocket协议
怎么配置双向心跳防止Nginx/浏览器自动断连
怎么验证连接真的“活着”且低延迟

所有操作基于真实部署环境，命令可直接复制执行，无需修改参数名。

2. 环境准备与基础服务启动

2.1 确认前置依赖已就绪

Clawdbot本身是Go语言编写的二进制网关，不依赖Python环境，但需确保以下服务已运行：

Ollama服务：Qwen3:32B模型必须已加载并监听本地API
Clawdbot二进制文件：v0.8.2或更高版本（旧版不支持WebSocket心跳）
反向代理（如Nginx）：用于HTTPS终止和端口映射（非必需，但生产环境强烈建议）

执行以下命令验证Ollama状态：

# 检查Ollama是否运行 systemctl is-active ollama # 确认Qwen3:32B已加载（注意大小写） ollama list | grep -i "qwen3.*32b" # 测试基础API连通性（应返回模型信息） curl http://localhost:11434/api/show -d '{"name":"qwen3:32b"}' -H "Content-Type: application/json"

若返回JSON包含"modelfile"字段，说明模型就绪。若提示404 Not Found，请先运行ollama pull qwen3:32b拉取模型。

2.2 启动Clawdbot并启用WebSocket支持

Clawdbot默认以HTTP模式启动，需显式开启WebSocket通道。关键参数如下：

参数	说明	示例值
`--ws-enable`	启用WebSocket协议	`true`
`--ws-heartbeat-interval`	心跳发送间隔（秒）	`30`
`--ws-timeout`	连接空闲超时（秒）	`300`
`--upstream`	Ollama API地址	`http://localhost:11434`

启动命令（保存为start.sh更便于管理）：

#!/bin/bash ./clawdbot \ --port 8080 \ --ws-enable true \ --ws-heartbeat-interval 30 \ --ws-timeout 300 \ --upstream http://localhost:11434 \ --log-level info

注意：--port 8080是Clawdbot监听的内部端口，后续通过Nginx反代到公网80/443。不要与Ollama的11434端口混淆。

启动后，终端会输出类似日志：

INFO[0000] WebSocket server started on :8080/ws INFO[0000] HTTP fallback server started on :8080

此时/ws路径已就绪，但还不能直接访问——需配置反向代理透传WebSocket头。

3. Nginx反向代理配置详解

3.1 为什么必须用Nginx透传特定Header

浏览器建立WebSocket连接时，会发送Upgrade: websocket和Connection: Upgrade两个关键Header。普通HTTP反代会丢弃这些字段，导致连接降级为HTTP，Clawdbot收不到升级请求，直接返回400错误。

Nginx需显式声明透传规则。以下是精简有效的配置（/etc/nginx/conf.d/clawdbot.conf）：

upstream clawdbot_backend { server 127.0.0.1:8080; } server { listen 443 ssl http2; server_name chat.yourdomain.com; # SSL证书配置（略，按实际路径填写） ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; location /ws { proxy_pass http://clawdbot_backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 关键：禁用缓冲，确保流式响应实时推送 proxy_buffering off; proxy_cache off; proxy_redirect off; # 超时设置必须大于Clawdbot的--ws-timeout proxy_read_timeout 310; proxy_send_timeout 310; } # 其他静态资源走HTTP location / { root /var/www/clawdbot-ui; try_files $uri $uri/ /index.html; } }

重点说明：
proxy_read_timeout 310必须比Clawdbot的--ws-timeout 300多10秒，否则Nginx会先断开连接
proxy_buffering off禁用缓冲，否则流式文本会被攒够一定长度才推送，失去实时性
location /ws路径必须与Clawdbot的WebSocket端点一致（默认即/ws）

配置完成后重载Nginx：

sudo nginx -t && sudo systemctl reload nginx

3.2 验证WebSocket握手是否成功

打开浏览器开发者工具（F12），切换到Network标签页，然后访问https://chat.yourdomain.com。在页面加载过程中，筛选WS（WebSocket）类型请求，应看到类似条目：

Name: ws Status: 101 Switching Protocols Protocol: websocket

点击该请求，查看Headers → Request Headers，确认包含：

Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: ...

若状态码是200或400，说明Nginx未正确透传，需检查proxy_set_header配置。

4. 前端WebSocket客户端实现要点

4.1 连接建立与心跳发送

Clawdbot的WebSocket端点为wss://chat.yourdomain.com/ws（HTTPS对应WSS）。前端需主动发送心跳包，格式为JSON字符串：

// 建立连接 const socket = new WebSocket('wss://chat.yourdomain.com/ws'); socket.onopen = () => { console.log('WebSocket connected'); // 启动心跳（每25秒发一次，比服务端30秒间隔略快） const heartbeat = setInterval(() => { if (socket.readyState === WebSocket.OPEN) { socket.send(JSON.stringify({ type: 'ping', timestamp: Date.now() })); } }, 25000); // 存储定时器以便关闭时清理 socket.heartbeat = heartbeat; }; socket.onmessage = (event) => { const data = JSON.parse(event.data); // 服务端心跳响应 if (data.type === 'pong') { console.log('Heartbeat acknowledged'); return; } // 正常消息处理（如模型流式输出） if (data.type === 'response') { appendToChat(data.content); } };

关键细节：
心跳间隔设为25秒（而非30秒），避免网络抖动导致错过一次响应
onmessage中必须区分ping/pong和业务消息，否则会把心跳当聊天内容显示
连接关闭时记得清除定时器：socket.onclose = () => clearInterval(socket.heartbeat);

4.2 处理连接异常与自动重连

真实网络中，WiFi切换、休眠唤醒都可能中断WebSocket。前端需实现智能重连：

let reconnectAttempts = 0; const MAX_RECONNECT = 5; function connectWithRetry() { const socket = new WebSocket('wss://chat.yourdomain.com/ws'); socket.onopen = () => { console.log('Connected after retry'); reconnectAttempts = 0; // 重置计数 }; socket.onclose = (event) => { if (reconnectAttempts < MAX_RECONNECT) { reconnectAttempts++; console.log(`Reconnecting... attempt ${reconnectAttempts}`); setTimeout(connectWithRetry, Math.min(1000 * reconnectAttempts, 10000)); } else { alert('无法连接到聊天服务，请检查网络'); } }; }

此逻辑确保：

首次失败等待1秒，第二次2秒，第三次4秒…指数退避
最多重试5次，避免无限循环消耗资源
用户看到明确提示而非静默失败

5. 后端心跳保活机制验证

5.1 查看Clawdbot实时连接状态

Clawdbot提供内置健康检查端点，可查看当前活跃WebSocket连接数：

# 请求Clawdbot的metrics接口（需启用--metrics参数启动） curl http://localhost:8080/metrics | grep websocket_connections

正常输出类似：

clawdbot_websocket_connections{state="active"} 3 clawdbot_websocket_connections{state="closed"} 12

若active值为0，说明前端未成功建立连接，或Nginx配置有误。

5.2 模拟网络中断测试保活能力

最可靠的验证方式是主动制造网络波动：

在浏览器中打开WebSocket连接

执行命令临时切断本机到服务器的WebSocket流量：

# Linux/macOS：阻断到服务器443端口的连接（不影响其他端口） sudo iptables -A OUTPUT -p tcp --dport 443 -j DROP # 等待30秒后恢复 sudo iptables -D OUTPUT -p tcp --dport 443 -j DROP

观察前端控制台：
- 应在30秒内触发onclose事件
- 自动重连逻辑启动，2-3秒内恢复连接
- 原聊天窗口保持上下文（因Clawdbot不维护会话状态，需前端缓存输入框内容）

重要提醒：Clawdbot本身不存储对话历史，所有上下文需由前端管理。心跳保活只保证连接通道畅通，不解决消息丢失问题。生产环境建议结合localStorage缓存未发送消息。

6. 常见问题排查清单

6.1 连接立即关闭（1006错误）

这是最常见问题，原因及解法：

现象	可能原因	解决方案
浏览器Network显示`1006`	Nginx未透传`Upgrade`头	检查`proxy_set_header Upgrade $http_upgrade`是否遗漏
`curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" https://chat.yourdomain.com/ws`返回400	Nginx SSL配置错误	确认`listen 443 ssl`已启用，且证书路径正确
日志出现`websocket: bad handshake`	Clawdbot版本过低	升级到v0.8.2+，旧版不支持WSS

6.2 心跳无响应（前端收不到pong）

现象	排查步骤
`onmessage`从不触发`type: pong`	用`wscat`工具直连测试： `wscat -c wss://chat.yourdomain.com/ws` 手动发送`{"type":"ping"}`，观察是否返回`{"type":"pong"}`
`wscat`测试正常但前端不行	检查前端代码是否在`onopen`后才启动心跳定时器（避免连接未建立就发ping）
所有客户端均无pong响应	查看Clawdbot日志是否有`received ping from client`，若无则心跳包未送达，检查Nginx`proxy_buffering off`是否生效

6.3 流式响应卡顿（文字逐字显示变慢）

表现	根本原因	修复动作
模型输出前10个字立刻显示，后续每2秒才出1个字	Nginx启用了缓冲	确认配置含`proxy_buffering off`和`proxy_cache off`
整段文字延迟30秒后一次性弹出	Ollama响应头缺少`content-type: text/event-stream`	在Clawdbot启动参数加`--stream-header "content-type: text/event-stream"`