Nginx 反向代理

OpenVort 后端（默认端口 8090）已内置前端静态文件服务和 SPA fallback，直接通过 IP:端口 即可访问，无需 Nginx。

如果需要域名访问、HTTPS 或负载均衡，可以使用 Nginx 作为反向代理。

::callout{type="warning"} 关键提醒：OpenVort 使用 WebSocket（/api/ws）实现实时通知和在线状态推送，Nginx 默认不转发 WebSocket 升级请求，必须为 /api/ws 单独配置代理，否则实时功能将完全失效。 ::

完整配置

server {
    listen 80;
    server_name openvort.company.com;

    client_max_body_size 50m;

    # 普通 HTTP 请求（API + 前端页面）
    location / {
        proxy_pass http://127.0.0.1:8090;
        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;
        proxy_read_timeout 300;
    }

    # WebSocket —— 在线状态、实时通知、typing indicator
    location /api/ws {
        proxy_pass http://127.0.0.1:8090;
        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_read_timeout 86400;
    }

    # SSE —— AI 对话流式输出
    location /api/chat/stream/ {
        proxy_pass http://127.0.0.1:8090;
        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_read_timeout 600;
    }
}

配置说明

location	协议	用途	关键配置
/	HTTP	API 接口 + 前端页面	标准反向代理
/api/ws	WebSocket	在线状态、实时通知	Upgrade + Connection 头
/api/chat/stream/	SSE	AI 对话流式输出	关闭 proxy_buffering

为什么 WebSocket 需要单独配置？

WebSocket 连接通过 HTTP Upgrade 机制从 HTTP 协议升级为持久双向连接。Nginx 默认使用 HTTP/1.0 代理且不转发 Upgrade 头，导致升级请求被丢弃。/api/ws 块中的三行配置解决了这个问题：

• proxy_http_version 1.1 — 启用 HTTP/1.1（WebSocket 要求）
• proxy_set_header Upgrade $http_upgrade — 转发客户端的升级请求
• proxy_set_header Connection "upgrade" — 告知上游执行协议升级

HTTPS 配置

使用 Let's Encrypt 免费证书：

# 安装 certbot
apt install certbot python3-certbot-nginx

# 自动配置 HTTPS（会修改 Nginx 配置）
certbot --nginx -d openvort.company.com

Certbot 会自动将上面的 HTTP 配置转换为 HTTPS，并添加 HTTP→HTTPS 重定向。

如果手动配置 HTTPS：

server {
    listen 443 ssl;
    server_name openvort.company.com;

    ssl_certificate /etc/letsencrypt/live/openvort.company.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/openvort.company.com/privkey.pem;

    client_max_body_size 50m;

    location / {
        proxy_pass http://127.0.0.1:8090;
        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;
        proxy_read_timeout 300;
    }

    location /api/ws {
        proxy_pass http://127.0.0.1:8090;
        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_read_timeout 86400;
    }

    location /api/chat/stream/ {
        proxy_pass http://127.0.0.1:8090;
        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_read_timeout 600;
    }
}

server {
    listen 80;
    server_name openvort.company.com;
    return 301 https://$host$request_uri;
}

Docker Compose 端口映射

如果使用 docker-compose.prod.yml 部署，默认端口映射为 10899:8090，Nginx 中的 proxy_pass 需改为：

proxy_pass http://127.0.0.1:10899;

常见问题

WebSocket 连接失败

症状：浏览器控制台显示 WebSocket connection to 'ws://...' failed，页面无实时通知。

排查：

1. 确认 Nginx 配置中有 location /api/ws 块（注意路径是 /api/ws，不是 /ws）
2. 确认该块包含 proxy_http_version 1.1、Upgrade 和 Connection 头
3. 修改配置后执行 nginx -t && nginx -s reload

AI 对话没有流式输出

症状：发送消息后长时间无响应，最后一次性显示全部内容。

排查：

1. 确认 /api/chat/stream/ 块设置了 proxy_buffering off
2. Nginx 默认会缓冲上游响应，SSE 需要关闭缓冲才能逐条推送

上传文件失败

症状：上传知识库文档或头像时报 413 错误。

排查：

确认配置了 client_max_body_size 50m（或更大），Nginx 默认限制 1MB。