workbuddy 部署需 nginx ≥1.13.6，支持 proxy_http_version 1.1 及 websocket 升级；配置须含 ssl 终止、真实 ip 透传、/ws/ 路径专用代理及静态资源直通优化。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在部署 WorkBuddy 时使用 Nginx 作为反向代理，但服务无法正常转发或出现 502、400、连接中断等异常，则可能是由于 Nginx 版本过低或配置缺失关键指令。以下是满足 WorkBuddy 运行所需的 Nginx 版本要求及对应配置模板：
一、Nginx 最低版本要求与模块依赖
Nginx 必须满足基础协议支持与扩展能力，才能正确代理 WorkBuddy 的 HTTP 流量及 WebSocket 连接。低于该版本将无法启用 proxy_http_version 1.1、Upgrade 头透传等核心功能。
1、Nginx 主版本必须为 1.13.6 及以上，该版本起正式支持 proxy_http_version 1.1 并稳定处理 Upgrade 和 Connection 头；
2、若需启用主动健康检查（如 upstream_check_module），则必须使用已编译该模块的定制版 Nginx，官方预编译包默认不包含；
3、SSL/TLS 终止功能需启用 http_ssl_module，该模块在所有主流发行版的 Nginx 包中默认启用，但需确认 nginx -V 2>&1 | grep -o 'http_ssl_module' 输出非空；
4、建议使用 Nginx 1.20.2 或更高稳定版，以兼容 TLSv1.3、OCSP Stapling 及现代 cipher suite，避免浏览器报 ERR_SSL_VERSION_OR_CIPHER_MISMATCH。
二、标准 HTTP 反向代理配置模板
该模板适用于 WorkBuddy 后端服务监听于 127.0.0.1:8080 的典型部署场景，覆盖 Host 头透传、真实 IP 记录、超时控制等生产必需项。
1、在 /etc/nginx/conf.d/workbuddy.conf 中创建新配置文件；
2、写入以下内容（请严格替换 your_domain.com 为实际域名）：
server {
listen 80;
server_name your_domain.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name your_domain.com;
ssl_certificate /etc/ssl/certs/your_domain.com.fullchain.pem;
ssl_certificate_key /etc/ssl/private/your_domain.com.key;
ssl_trusted_certificate /etc/ssl/certs/your_domain.com.ca-bundle;
location / {
proxy_pass http://127.0.0.1:8080;
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_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
proxy_buffering off;
}
}
使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。
三、WebSocket 反向代理专用配置模板
WorkBuddy 的实时协作、消息推送、Claw 长连接等功能依赖 WebSocket 协议，Nginx 必须显式声明协议升级行为，否则前端连接会因 400 错误中断。
1、确保已在主配置 http 块中定义 upstream（可选，推荐用于多实例）：
upstream workbuddy_ws {
server 127.0.0.1:2346;
}
2、在站点 server 块内添加独立 location 块，路径需与前端 JS 中 new WebSocket() 地址严格一致（例如 /ws/）；
3、配置中必须包含 proxy_http_version 1.1、Upgrade 与 Connection 三项关键指令；
4、完整配置示例如下（假设 WorkBuddy WebSocket 服务监听 127.0.0.1:2346）：
location /ws/ {
proxy_pass http://127.0.0.1:2346;
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;
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
}
四、静态资源直通优化配置
Nginx 应直接响应 WorkBuddy 的前端静态资源（如 JS、CSS、图片），避免请求穿透至后端应用，降低 WorkBuddy 进程负载并提升首屏加载速度。
1、确认 WorkBuddy 已生成构建产物，路径为 /var/www/workbuddy/public/（Linux）或对应安装目录下的 public 子目录；
2、在 server 块内添加如下 location 规则，优先级高于通用 proxy_pass；
3、配置启用 Gzip 压缩，仅对文本类资源生效，避免压缩图片或字体造成体积增大；
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2|ttf|eot)$ {
root /var/www/workbuddy/public;
expires 1y;
add_header Cache-Control "public, immutable";
gzip on;
gzip_types application/javascript text/css image/svg+xml;
gzip_min_length 1000;
}
