网络与代理排查 (Network & Proxy)

网络与代理排查 (Network & Proxy)

在自建代理或内网穿透环境中，网络握手是常见故障点。

---

1. Live API WebSocket 连接立即断开

检查清单

• Docker 环境：确保环境变量 ENABLE_LIVE_WS_PROXY=true 已开启。
• Nginx 反向代理配置：如果在外层使用了 Nginx 反向代理，必须显式传递 WebSocket 升级头：

  location /api/live {
      proxy_pass http://127.0.0.1:3001;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "Upgrade";
      proxy_read_timeout 86400s;
  }

• 超时断开：如果闲置超过 5 分钟未说话，后端会按 LIVE_WS_IDLE_TIMEOUT_MS 回收连接，重新点击麦克风即可重新建立会话。

---

2. 跨域 CORS 拦截报错 (Access-Control-Allow-Origin)

现象

前端部署在 https://my-app.pages.dev，后端在 https://api.my-domain.com，控制台提示 CORS 错误。

解决方案

在 Node API 后端服务的 .env 中加入前端域名：

ALLOWED_ORIGINS=https://my-app.pages.dev

多个域名使用英文逗号 , 分隔，修改后重启后端服务。