MonkeyCode私有化部署实战：Docker+WebSocket+Qwen代码智能平台落地指南

1. 项目概述：MonkeyCode私有化部署到底在解决什么问题？

MonkeyCode不是某个具体开源项目的名字，而是对一类“基于大模型能力封装的代码智能辅助平台”的统称——它泛指那些以Qwen系列（尤其是Qwen1.5、Qwen2、Qwen2.5 Code、Qwen3）为底层推理引擎，集成了代码补全、单行/多行生成、自然语言转代码、单元测试生成、代码解释、错误诊断等能力，并通过Web界面或IDE插件对外提供服务的私有化AI编码助手系统。你在网上搜到的“MonkeyCode官网”“MonkeyCode下载”“MonkeyCode API文档”，绝大多数指向的是企业级代码智能平台的商业化产品形态，其核心逻辑是：把Qwen-Code类模型的能力，封装成可内网部署、可控、可审计、不外泄代码资产的服务。

为什么企业要执着于“私有化部署”？我做过7个制造业、金融和政企客户的代码智能平台落地项目，最常听到的三句话是：“我们的Java微服务代码不能出防火墙”“审计要求所有AI调用日志必须落盘本地”“我们自己训练的领域代码微调模型，必须跑在专属GPU节点上”。这三点，直接击穿了SaaS模式的底线。而MonkeyCode私有化部署，就是用Docker作为交付载体，把模型推理服务（vLLM/Qwen.cpp）、API网关（FastAPI/Starlette）、WebSocket长连接管理、前端静态资源、向量数据库（用于RAG增强）全部打包进一套可复现、可版本化、可灰度发布的容器体系里。它不是简单地“把Qwen跑起来”，而是构建一个具备生产级SLA的代码智能中枢——比如，当开发人员在VS Code里敲下// 根据订单ID查询用户积分，后端需在800ms内完成：代码语义解析 → 向量检索历史相似实现 → 调用Qwen2.5-Code-7B流式生成 → WebSocket逐token推送 → 前端实时渲染高亮。整个链路里，WebSocket不是可选项，而是必选项；Docker不是便利贴，而是安全边界。

关键词“MonkeyCode”“私有化部署”“Docker”“WebSocket”“Qwen”在热词中高频共现，恰恰印证了当前落地的核心矛盾：模型能力（Qwen）已足够强，但工程化闭环（Docker封装+WebSocket实时性+私有环境适配）仍是最大断点。很多人卡在“docker run -p 8000:8000 qwen/codex:latest 启动成功，但前端连不上ws://localhost:8000/v1/chat/ws”这种看似简单实则涉及CORS、反向代理、TLS卸载、心跳保活四层机制的问题上。这篇攻略不讲Qwen模型原理，不堆参数表格，只聚焦一件事：从零开始，在一台Ubuntu 22.04物理机上，用NVIDIA A10 GPU，完整走通MonkeyCode私有化部署的每一道门禁，包括那些官方文档绝不会写的“为什么这里必须加--gpus all”“为什么Nginx配置里proxy_read_timeout必须设为3600”“为什么前端WebSocket连接时Authorization Header总被浏览器丢弃”。你不需要懂Transformer，但需要知道怎么让Qwen真正为你写代码。

2. 整体架构设计与技术选型逻辑拆解

2.1 为什么必须用Docker？裸金属部署行不行？

先说结论：裸金属部署在POC阶段可行，但在生产环境等于自建运维地狱。我曾帮某银行信科部做过对比测试：同样部署Qwen2.5-Code-7B，裸金属方案需要手动编译vLLM（CUDA 12.1+PyTorch 2.3匹配）、配置systemd服务守护、编写日志轮转脚本、处理GPU显存泄漏重启逻辑；而Docker方案，仅需一条命令docker run --gpus all -p 8000:8000 -v /data/models:/models qwen/codex:2.5.7b-vllm-cu121 --model-path /models/qwen2.5-code-7b --tensor-parallel-size 1，所有依赖、路径、权限、资源限制全部固化。更关键的是升级——当Qwen发布2.5.1版本修复了JSON Schema生成bug时，裸金属需重新编译整个vLLM，耗时2小时；Docker只需拉取新镜像、停旧容器、启新容器，平均中断时间47秒。

Docker在此场景的核心价值不是“轻量”，而是“契约化交付”。MonkeyCode私有化包本质是一份运行时契约：它承诺“只要宿主机有Docker Engine + NVIDIA Container Toolkit + 指定GPU驱动，就能100%复现相同行为”。这个契约覆盖了四个维度：

• 环境一致性：Python 3.10.12 + vLLM 0.5.3.post1 + Transformers 4.41.2 + CUDA 12.1.105，全部锁定在镜像层，避免“在我机器上好好的”陷阱；
• 资源隔离性：--memory=16g --cpus=8 --gpus='"device=0"'可精确控制Qwen服务独占1块A10的显存与算力，防止被CI流水线进程抢占；
• 网络可预测性：Docker默认bridge网络使服务IP固定（如172.17.0.2），Nginx反向代理配置无需动态发现；
• 安全收敛性：通过--read-only --tmpfs /tmp:rw,size=512m --cap-drop=ALL最小化容器权限，满足等保2.0对AI服务的基线要求。

提示：别用Docker Desktop！它在Windows/Mac上会启动Linux VM，导致GPU直通失败。生产环境必须用原生Docker Engine（Ubuntu用apt install docker.io，CentOS用dnf install dnf-plugins-core && dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo）。

2.2 为什么WebSocket是刚需？HTTP轮询为什么被淘汰？

MonkeyCode的交互范式决定了它必须用WebSocket。想象一个典型场景：开发者输入// 计算用户近30天订单总额，按支付方式分组，Qwen需生成约120行SQL+Python混合代码。如果走HTTP长轮询（Long Polling），前端需每2秒发一次GET请求问“生成完了吗？”，后端得维护每个请求的上下文状态（谁在问、问到第几token），并发100人时内存暴涨；更致命的是，当生成到第87个token时网络抖动，整个请求失败，用户只能重来。

WebSocket则完全不同：前端建立ws://monkeyCode.internal/v1/chat/ws连接后，服务端通过同一TCP连接持续推送{"type":"token","value":"SELECT"}、{"type":"token","value":" SUM"}...直到{"type":"finish","reason":"stop"}。这种单连接、双工、低开销的通信模式，带来三个不可替代优势：

• 实时性保障：端到端延迟稳定在150ms内（实测A10+Qwen2.5-Code-7B），远超HTTP的300ms+波动；
• 状态轻量化：服务端无需存储请求上下文，每个WebSocket连接绑定一个vLLM生成Stream对象，内存占用降低60%；
• 错误恢复友好：连接断开时，前端可携带last_message_id=abc123重连，服务端从断点续推，而非重头生成。

但这也带来新挑战：WebSocket连接需穿透Nginx/Apache等反向代理。很多团队卡在这里——明明curl http://localhost:8000/health返回200，但浏览器控制台报WebSocket connection to 'ws://monkeyCode.internal/v1/chat/ws' failed: Error during WebSocket handshake: Unexpected response code: 400。根本原因在于代理层未透传WebSocket协议头。解决方案必须包含三要素：Nginx配置proxy_http_version 1.1+proxy_set_header Upgrade $http_upgrade+proxy_set_header Connection "upgrade"，缺一不可。这些细节，正是私有化部署成败的分水岭。

2.3 Qwen模型选型：为什么不是Qwen3，而是Qwen2.5-Code？

当前（2024年中）MonkeyCode私有化落地的主流选择是Qwen2.5-Code系列，而非最新的Qwen3。这不是技术保守，而是工程理性决策。我们做了三组压测对比（A10 GPU，batch_size=1）：

数据说明：Qwen3虽在通用能力上更强，但其新增的“多模态指令理解”模块在纯代码场景反而增加推理开销；而Qwen2.5-Code是专为代码任务优化的分支，移除了非必要权重，强化了AST解析能力。更重要的是生态支持——vLLM 0.5.x对Qwen2.5-Code的PagedAttention优化已成熟，但对Qwen3的FlashInfer适配仍在beta阶段。某券商客户曾强行上线Qwen3，结果在高并发生成时出现显存碎片化，每处理50个请求需重启服务。最终回退到Qwen2.5-Code-7B，配合--enable-prefix-caching参数，稳定支撑200+并发。

因此，MonkeyCode私有化部署的Qwen选型原则是：能力够用、生态成熟、资源可控。对于中小团队，Qwen2.5-Code-1.5B（显存仅需4GB）足以支撑日常补全；中大型企业建议Qwen2.5-Code-7B（需A10/A30）；只有涉及复杂算法生成（如金融风控模型代码）才考虑Qwen2.5-Code-14B（需A100 80G）。切记：模型越大≠效果越好，而是要匹配你的GPU资源与业务SLA。

3. 核心组件部署与实操要点详解

3.1 宿主机环境准备：Ubuntu 22.04 + NVIDIA驱动 + Docker Engine

私有化部署的第一道门，永远是宿主机。别跳过这步——我见过太多团队在“docker run成功”后，卡在GPU无法识别上3天。以下是经过23个生产环境验证的标准化流程：

第一步：确认硬件与内核兼容性
执行lspci | grep -i nvidia确认A10存在，uname -r检查内核版本。Ubuntu 22.04默认内核5.15，完全兼容NVIDIA 535驱动。若为老内核（如5.4），必须升级：sudo apt update && sudo apt install linux-generic-hwe-22.04。

第二步：安装NVIDIA驱动（关键！）
严禁用Ubuntu自带的“附加驱动”GUI工具——它会安装nouveau开源驱动，与CUDA冲突。必须用NVIDIA官方.run包：

# 卸载可能存在的冲突驱动 sudo apt purge *nvidia* && sudo reboot # 下载驱动（以535.129.03为例） wget https://us.download.nvidia.com/tesla/535.129.03/NVIDIA-Linux-x86_64-535.129.03.run sudo chmod +x NVIDIA-Linux-x86_64-535.129.03.run sudo ./NVIDIA-Linux-x86_64-535.129.03.run --no-opengl-files --no-x-check

--no-opengl-files避免覆盖系统OpenGL库，--no-x-check跳过X Server检测（服务器通常无GUI）。安装后执行nvidia-smi应显示A10信息及驱动版本。

第三步：安装Docker Engine与NVIDIA Container Toolkit

# 卸载旧版Docker sudo apt remove docker docker-engine docker.io containerd runc # 安装Docker CE sudo apt update && sudo apt install ca-certificates curl gnupg lsb-release curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt update && sudo apt install docker-ce docker-ce-cli containerd.io # 安装NVIDIA Container Toolkit curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - distribution=$(. /etc/os-release;echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list sudo apt update && sudo apt install -y nvidia-docker2 sudo systemctl restart docker

验证：sudo docker run --rm --gpus all nvidia/cuda:12.1.1-base-ubuntu22.04 nvidia-smi应输出与宿主机一致的GPU信息。若报错docker: Error response from daemon: could not select device driver "nvidia"，说明nvidia-docker2未正确加载，需检查/etc/docker/daemon.json是否含"default-runtime": "nvidia"。

注意：不要用sudo usermod -aG docker $USER将用户加入docker组！这违反最小权限原则。生产环境应创建专用服务账户sudo useradd -r -s /bin/false monkeyCode，后续所有容器均以该用户运行。

3.2 MonkeyCode核心服务部署：vLLM + FastAPI + WebSocket

MonkeyCode私有化包的核心是推理服务层。我们采用vLLM作为推理引擎（因其PagedAttention显著提升吞吐），FastAPI作为API网关（异步非阻塞），并深度定制WebSocket路由。以下是可直接复用的部署脚本：

创建部署目录结构

sudo mkdir -p /opt/monkeyCode/{config,models,logs} sudo chown -R monkeyCode:monkeyCode /opt/monkeyCode sudo -u monkeyCode mkdir -p /opt/monkeyCode/config /opt/monkeyCode/logs

下载Qwen2.5-Code-7B模型（HuggingFace镜像加速）
由于HF官网下载慢且不稳定，必须配置国内镜像源。在/opt/monkeyCode/config/hf_mirror.py中写入：

import os os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com' from huggingface_hub import snapshot_download snapshot_download( repo_id="Qwen/Qwen2.5-Code-7B", local_dir="/opt/monkeyCode/models/qwen2.5-code-7b", revision="main", ignore_patterns=["*.pt", "*.bin"] # 优先下载safetensors )

执行sudo -u monkeyCode python3 /opt/monkeyCode/config/hf_mirror.py，实测下载速度从120KB/s提升至8MB/s。

编写vLLM启动脚本
创建/opt/monkeyCode/config/start_vllm.sh：

#!/bin/bash # 设置GPU可见性（若有多卡，指定device=0） export CUDA_VISIBLE_DEVICES=0 # 启动vLLM服务，关键参数说明： # --host 0.0.0.0：监听所有网卡，供Nginx代理 # --port 8000：内部服务端口 # --model /models/qwen2.5-code-7b：模型路径（映射到容器内） # --tensor-parallel-size 1：单卡部署，不启用张量并行 # --gpu-memory-utilization 0.9：显存利用率90%，留10%给系统 # --enable-prefix-caching：启用前缀缓存，提升重复请求性能 # --max-num-seqs 256：最大并发请求数 # --max-model-len 32768：最大上下文长度（Qwen2.5支持32K） exec vllm.entrypoints.api_server \ --host 0.0.0.0 \ --port 8000 \ --model /models/qwen2.5-code-7b \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.9 \ --enable-prefix-caching \ --max-num-seqs 256 \ --max-model-len 32768 \ --disable-log-requests \ --disable-log-stats

赋予执行权限：sudo chmod +x /opt/monkeyCode/config/start_vllm.sh

构建MonkeyCode Docker镜像
创建/opt/monkeyCode/Dockerfile：

FROM vllm/vllm-cu121:0.5.3.post1 # 创建非root用户 RUN useradd -r -u 1001 -g root monkeyCode USER monkeyCode # 复制启动脚本 COPY config/start_vllm.sh /home/monkeyCode/start_vllm.sh # 暴露端口 EXPOSE 8000 # 启动服务 CMD ["/home/monkeyCode/start_vllm.sh"]

构建镜像：sudo docker build -t monkeyCode/qwen2.5-code-7b:v0.1 /opt/monkeyCode/

启动容器（关键！带GPU与日志配置）

sudo docker run -d \ --name monkeyCode-core \ --gpus '"device=0"' \ # 必须指定device，不能只写all --restart=unless-stopped \ --memory=16g \ --cpus=8 \ --network=host \ # 使用host网络，避免bridge网络NAT延迟 -v /opt/monkeyCode/models:/models:ro \ -v /opt/monkeyCode/logs:/var/log/monkeyCode \ -u 1001:0 \ --read-only \ --tmpfs /tmp:rw,size=512m \ --cap-drop=ALL \ monkeyCode/qwen2.5-code-7b:v0.1

验证：sudo docker logs monkeyCode-core | tail -20应看到INFO: Uvicorn running on http://0.0.0.0:8000，且nvidia-smi显示GPU显存被vLLM占用约12GB。

3.3 Nginx反向代理配置：解决WebSocket握手与HTTPS卸载

vLLM服务启动在8000端口，但生产环境必须通过Nginx暴露80/443端口，并处理WebSocket协议升级。这是私有化部署中最易出错的环节。以下是经过金融级安全审计的/etc/nginx/conf.d/monkeyCode.conf：

upstream monkeyCode_backend { server 127.0.0.1:8000; } server { listen 80; server_name monkeyCode.internal; # HTTP重定向到HTTPS（若启用SSL） # return 301 https://$server_name$request_uri; location / { proxy_pass http://monkeyCode_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_set_header X-Forwarded-Proto $scheme; # 关键！WebSocket超时必须极大延长 proxy_read_timeout 3600; proxy_send_timeout 3600; proxy_connect_timeout 75; # 缓冲区调优，避免大响应截断 proxy_buffering on; proxy_buffer_size 128k; proxy_buffers 4 256k; proxy_busy_buffers_size 256k; } # 专门处理WebSocket路径 location /v1/chat/ws { proxy_pass http://monkeyCode_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_set_header X-Forwarded-Proto $scheme; # WebSocket必须的超时设置 proxy_read_timeout 3600; proxy_send_timeout 3600; proxy_connect_timeout 75; } }

重载Nginx：sudo nginx -t && sudo systemctl reload nginx。

验证WebSocket连通性（不用浏览器，用curl命令）：

# 检查HTTP健康接口 curl http://monkeyCode.internal/health # 检查WebSocket握手（关键！） curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Version: 13" http://monkeyCode.internal/v1/chat/ws

若返回HTTP/1.1 101 Switching Protocols，说明握手成功；若返回400 Bad Request，90%是Nginx未正确配置Upgrade头。

实操心得：很多团队在Nginx配置后仍连不上，最后发现是公司防火墙策略——WebSocket使用HTTP/1.1 Upgrade机制，但某些老旧防火墙会拦截Connection: Upgrade头。解决方案是在Nginx中添加proxy_set_header Connection "keep-alive";并联系网络管理员放行Upgrade协议。

4. 前端集成与WebSocket客户端实现

4.1 前端如何安全传递Authorization Header？

MonkeyCode私有化要求所有API调用携带JWT Token进行鉴权。但浏览器WebSocket API有个致命限制：无法在WebSocket握手请求中设置自定义Header（如Authorization: Bearer xxx）。这是W3C规范明确禁止的，目的是防止CSRF攻击。因此，必须采用URL Query参数方式传递Token。

在前端初始化WebSocket时：

// ❌ 错误：试图设置Header（浏览器会忽略） const ws = new WebSocket('ws://monkeyCode.internal/v1/chat/ws'); ws.setRequestHeader('Authorization', 'Bearer ' + token); // 无效！ // ✅ 正确：Token放入URL参数 const wsUrl = `ws://monkeyCode.internal/v1/chat/ws?token=${encodeURIComponent(token)}`; const ws = new WebSocket(wsUrl);

后端（FastAPI）需在WebSocket路由中解析此参数：

from fastapi import WebSocket, WebSocketDisconnect, Query from jose import JWTError, jwt @router.websocket("/v1/chat/ws") async def chat_websocket( websocket: WebSocket, token: str = Query(..., description="JWT Token from URL query") ): try: payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM]) user_id: str = payload.get("sub") if user_id is None: await websocket.close(code=4001) # 自定义错误码 return except JWTError: await websocket.close(code=4001) return # 鉴权通过，建立连接 await websocket.accept() # ... 后续逻辑

注意：Token有效期建议设为24小时，避免频繁刷新。前端需在Token过期前主动关闭旧连接、用新Token重建连接，否则服务端会在jwt.decode时抛出异常并关闭连接。

4.2 WebSocket心跳保活与断线重连策略

生产环境中，Nginx默认60秒无活动会关闭空闲连接，而Qwen生成代码可能长达数分钟。必须实现心跳机制。标准做法是：前端每45秒发送{"type":"ping"}，服务端收到后回复{"type":"pong"}，双方维持连接活跃。

前端重连逻辑（防抖+指数退避）：

class MonkeyCodeWS { constructor(url) { this.url = url; this.ws = null; this.reconnectAttempts = 0; this.maxReconnectAttempts = 10; this.reconnectDelay = 1000; // 初始1秒 } connect() { this.ws = new WebSocket(this.url); this.ws.onopen = () => { console.log('WebSocket connected'); this.reconnectAttempts = 0; // 连接成功，重置计数 this.startHeartbeat(); }; this.ws.onmessage = (event) => { const data = JSON.parse(event.data); if (data.type === 'pong') return; // 忽略心跳响应 // 处理业务消息 this.handleMessage(data); }; this.ws.onclose = (event) => { console.log(`WebSocket closed: ${event.code} ${event.reason}`); if (this.shouldReconnect(event.code)) { this.reconnect(); } }; this.ws.onerror = (error) => { console.error('WebSocket error:', error); }; } startHeartbeat() { this.heartbeatInterval = setInterval(() => { if (this.ws && this.ws.readyState === WebSocket.OPEN) { this.ws.send(JSON.stringify({ type: "ping" })); } }, 45000); } reconnect() { if (this.reconnectAttempts >= this.maxReconnectAttempts) { console.error('Max reconnection attempts reached'); return; } this.reconnectAttempts++; setTimeout(() => { console.log(`Reconnecting... attempt ${this.reconnectAttempts}`); this.connect(); }, this.reconnectDelay); // 指数退避：下次重连延迟翻倍（最多30秒） this.reconnectDelay = Math.min(this.reconnectDelay * 2, 30000); } shouldReconnect(code) { // 4000-4999为应用自定义错误码，4001=Token失效，不重连 return code !== 4001 && code !== 4002; } }

服务端需在WebSocket路由中处理ping/pong：

@router.websocket("/v1/chat/ws") async def chat_websocket( websocket: WebSocket, token: str = Query(...) ): await websocket.accept() while True: try: data = await websocket.receive_text() message = json.loads(data) if message.get("type") == "ping": await websocket.send_text(json.dumps({"type": "pong"})) continue # 处理实际聊天请求 await handle_chat_request(websocket, message) except WebSocketDisconnect: print("Client disconnected") break except Exception as e: print(f"Error: {e}") break

4.3 流式响应解析：如何把Token逐个渲染成代码？

Qwen生成是流式的，服务端通过WebSocket逐个发送token。前端必须能实时解析并渲染，而非等待全部完成。关键在于处理{"type":"token","value":"..."}和{"type":"finish","reason":"stop"}事件：

handleMessage(data) { switch(data.type) { case 'token': // 追加到编辑器，保持光标在末尾 this.editor.setValue(this.editor.getValue() + data.value); this.editor.setCursor(this.editor.getLength()); break; case 'finish': if (data.reason === 'stop') { // 生成完成，可触发后续操作（如格式化） this.formatCode(); } else if (data.reason === 'length') { // 达到max_tokens限制，提示用户 this.showAlert('生成被截断，请缩短输入或增大max_tokens'); } break; case 'error': this.showError(data.message); break; } }

实操心得：很多前端团队直接用editor.setValue()追加，导致大量DOM重绘卡顿。正确做法是累积10个token后批量更新一次，或使用editor.replaceRange()在光标位置插入，性能提升5倍以上。我们在线上环境实测，单次插入1个字符，1000次操作耗时2.3秒；批量插入10个字符，100次操作仅耗时0.4秒。

5. 常见问题与排查技巧实录

5.1 典型问题速查表

5.2 独家避坑技巧：那些文档不会写的细节

技巧1：解决“stream disconnected before completion”错误
这个错误在vLLM日志中高频出现，表面是网络断开，实则是Nginx的proxy_read_timeout太短。Qwen2.5-Code-7B生成120行代码平均耗时22秒，但若遇到复杂逻辑（如生成Spring Boot+MyBatis完整CRUD），可能达58秒。必须将proxy_read_timeout设为3600（1小时），而非默认60秒。更稳妥的做法是：在Nginx中为WebSocket路径单独配置超时，避免影响其他HTTP接口。

技巧2：绕过浏览器对WebSocket的跨域限制
当开发环境前端运行在http://localhost:3000，而MonkeyCode服务在http://monkeyCode.internal时，浏览器会因跨域拒绝WebSocket连接。解决方案不是关闭浏览器安全策略（危险！），而是用Nginx做开发代理：

# 开发环境专用配置 server { listen 3000; server_name localhost; location / { proxy_pass http://localhost:3000; # 前端开发服务器 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } location /v1/chat/ws { proxy_pass http://monkeyCode.internal/v1/chat/ws; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; } }

这样前端仍访问ws://localhost:3000/v1/chat/ws，实际被Nginx转发，完美规避跨域。

技巧3：强制前端使用HTTPS WebSocket
生产环境必须用wss://。但若Nginx未配置SSL，浏览器会拒绝连接。快速生成可信证书（适用于内网）：

# 生成自签名证书（有效期10年） sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \ -keyout /etc/ssl/private/monkeyCode.key \ -out /etc/ssl/certs/monkeyCode.crt \ -subj "/C=CN/ST=Beijing/L=Beijing/O=MonkeyCode/CN=monkeyCode.internal"

在Nginx配置中添加SSL段：

server { listen 443 ssl; server_name monkeyCode.internal; ssl_certificate /etc/ssl/certs/monkeyCode.crt; ssl_certificate_key /etc/ssl/private/monkeyCode.key; ssl_protocols TLSv1.2 TLSv1.3; # 其余配置同80端口... }

前端连接改为wss://monkeyCode.internal/v1/chat/ws，浏览器地址栏将显示锁图标。

5.3 性能调优实战：从20QPS到120QPS的跃迁

某保险科技客户初期部署Qwen2.5-Code-7B，实测并发20人时首token延迟飙升至2.1秒。我们通过三层调优将其提升至120QPS（首token<800ms）：

第一层：vLLM参数调优

• 将--max-num-seqs从默认的256降至128，减少调度开销；
• 添加