Jitsi Meet中XMPP连接失败，Nginx反向代理配置应如何正确设置？

Question

常见问题：Jitsi Meet部署后Web端可访问，但无法加入会议、频繁断连或提示“Connection failed”——根本原因常为Nginx反向代理未正确透传XMPP WebSocket连接（`/xmpp-websocket`路径）。默认配置下，Nginx会终止HTTP升级请求，导致Prosody的WebSocket握手失败；同时缺少`Upgrade`和`Connection`头转发、超时设置过短（如`proxy_read_timeout 60`不足）、或SSL/TLS终止位置不当（如在Nginx层终止HTTPS但未启用`proxy_ssl_verify off`配合自签名证书），均会阻断XMPP over WebSocket通信。此外，若使用子路径（如`/meet`）部署，`location`块未精确匹配`/xmpp-websocket`并重写URI，也会导致502或404。该问题不报明确错误日志，需结合浏览器开发者工具Network标签查看WebSocket连接状态及Nginx error.log中的`upstream prematurely closed connection`等线索综合诊断。

Answer 1

```html

一、现象层：典型故障表征与用户侧感知

• Web端首页可正常加载（HTML/CSS/JS资源返回200），但点击“Join Meeting”后卡在加载动画或立即弹出“Connection failed”提示
• 已入会用户频繁掉线（<5秒内断连），控制台持续出现 WebSocket is closed before the connection is established
• Chrome DevTools → Network 标签中，/xmpp-websocket 请求状态为 failed 或 cancelled，响应头缺失 Upgrade: websocket
• 无明显前端报错，但浏览器控制台存在大量 Failed to construct 'WebSocket': The URL's scheme must be either 'ws' or 'wss'（常因协议降级或路径重写错误）

二、协议层：XMPP over WebSocket 的握手机制与Nginx阻断点

Jitsi Meet 依赖 Prosody 提供的 XMPP WebSocket 端点（默认 /xmpp-websocket），其建立需完整 HTTP/1.1 Upgrade 流程：

1. 客户端发起 GET /xmpp-websocket?room=xxx HTTP/1.1，携带 Upgrade: websocket 与 Connection: Upgrade
2. Nginx 必须透传该 Upgrade 请求至上游 Prosody（通常为 http://localhost:5280/xmpp-websocket）
3. 若 Nginx 未配置 WebSocket 支持，将直接响应 HTTP/1.1 200（非 101 Switching Protocols），导致握手失败

三、配置层：Nginx 反向代理关键参数对照表

配置项	错误示例	正确配置（含注释）
proxy_http_version	1.0	1.1 —— 必须启用 HTTP/1.1 以支持 Upgrade
proxy_set_header Upgrade	缺失	$http_upgrade —— 动态透传 Upgrade 头
proxy_set_header Connection	close	$connection_upgrade —— 需定义映射：map $http_upgrade $connection_upgrade { default upgrade; '' close; }
proxy_read_timeout	60	3600 —— WebSocket 长连接需超时 ≥ 1 小时（Jitsi 默认心跳间隔 25s）

四、部署拓扑层：SSL终止位置与证书验证陷阱

当使用自签名证书或私有 CA 时，Nginx 到 Prosody 的上游通信易被阻断：

location /xmpp-websocket {
    proxy_pass http://prosody_backend;
    proxy_ssl_verify off;           # 关键！禁用上游 SSL 验证（Prosody 本地 HTTP 或自签 HTTPS）
    proxy_ssl_trusted_certificate /etc/nginx/certs/ca-bundle.crt;
}

若忽略 proxy_ssl_verify off，Nginx 将拒绝连接自签名的 Prosody HTTPS 端点（如 https://localhost:5281），日志报 SSL_do_handshake() failed。

五、路径层：子路径部署（/meet）下的 URI 重写逻辑

若 Jitsi Meet 部署于子路径（如 https://example.com/meet），Nginx 必须精确匹配并剥离前缀：

location ^~ /meet/xmpp-websocket {
    proxy_pass http://prosody_backend/xmpp-websocket;  # 注意末尾斜杠！触发重写
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_read_timeout 3600;
}

错误写法 proxy_pass http://prosody_backend; 将导致请求被转发为 /meet/xmpp-websocket，Prosody 返回 404。

六、诊断层：多维度日志与工具链协同分析

graph LR
A[浏览器 Network] -->|检查| B[/xmpp-websocket 状态码/响应头]
B --> C{是否 101？}
C -->|否| D[Nginx access.log：HTTP 200/502]
C -->|是| E[Chrome Console：WebSocket.readyState]
D --> F[Nginx error.log：upstream prematurely closed connection]
F --> G[Prosody debug.log：是否收到 Upgrade 请求？]

七、验证层：最小化复现与原子性测试脚本

执行以下命令直连 Prosody WebSocket 端点，绕过 Nginx 验证服务可用性：

# 使用 wscat 测试本地 Prosody
npm install -g wscat
wscat -c 'ws://localhost:5280/xmpp-websocket?room=test' --no-check

# 若成功，说明问题 100% 在 Nginx 层；若失败，则检查 Prosody 配置（modules_enabled, cross_domain_websocket）

```