Semaphore项目中使用NGINX反向代理时实时日志更新问题的解决方案

问题背景

在使用Semaphore这一开源Ansible Web UI工具时，很多用户会选择通过NGINX反向代理来提供HTTPS访问。但在实际部署中发现，当通过NGINX访问Semaphore时，任务运行控制台的实时日志输出会出现更新延迟，必须手动刷新页面才能看到最新内容，而直接访问Semaphore的3000端口则能正常实时更新。

技术分析

这个问题本质上与WebSocket协议的支持有关。Semaphore的控制台实时输出功能依赖于WebSocket连接，而NGINX默认配置可能无法正确处理WebSocket的升级请求。具体表现为：

1. 常规HTTP请求通过反向代理工作正常
2. WebSocket连接无法建立或保持，导致实时数据无法推送
3. 直接访问后端服务时WebSocket连接正常

解决方案

要使NGINX正确转发WebSocket流量，需要在配置文件中添加专门的WebSocket支持配置。以下是经过验证的有效配置方案：

location /api/ws {
    proxy_pass http://semaphore:3000/api/ws;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Origin "";
}

关键配置说明：

1. proxy_http_version 1.1：强制使用HTTP/1.1协议，这是WebSocket工作的基础
2. Upgrade和Connection头：处理协议升级请求，将HTTP连接升级为WebSocket连接
3. Origin头设置为空：避免跨域问题

完整配置建议

对于生产环境，建议采用以下完整配置：

server {
    listen 443 ssl;
    server_name your.domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # 安全相关头
    add_header Strict-Transport-Security "max-age=31536000" always;

    # SSL优化配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256';
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;

    # 禁用缓冲以确保实时性
    proxy_buffering off;
    proxy_request_buffering off;

    # 主代理配置
    location / {
        proxy_pass http://semaphore:3000/;
        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专用配置
    location /api/ws {
        proxy_pass http://semaphore:3000/api/ws;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Origin "";
    }
}

常见问题排查

如果配置后仍然存在问题，可以检查以下几点：

1. 确认NGINX配置已重载：执行nginx -s reload
2. 检查防火墙设置：确保443端口和WebSocket端口(通常为80或443)开放
3. 查看浏览器开发者工具中的Network标签，确认WebSocket连接状态
4. 检查NGINX错误日志：通常位于/var/log/nginx/error.log

总结

通过正确配置NGINX对WebSocket协议的支持，可以完美解决Semaphore控制台实时日志更新的问题。这一解决方案不仅适用于Semaphore，对于其他需要WebSocket支持的Web应用通过反向代理访问时也同样适用。配置时特别注意协议升级头和连接保持的设置，这是WebSocket正常工作的关键。

对于使用Nginx Proxy Manager等管理工具的用户，只需在高级配置中启用"Websockets Support"选项即可，工具会自动添加必要的配置参数。