Semaphore项目中NGINX反向代理导致控制台实时输出失效的解决方案

问题现象分析

在使用Semaphore项目时，当通过NGINX反向代理访问Web界面时，任务执行的控制台输出无法实时更新，必须手动刷新页面才能看到最新日志。而直接访问Semaphore服务端口(3000)时则能正常实时显示输出内容。

技术背景

这种实时输出功能通常依赖于WebSocket协议实现。WebSocket允许服务端主动向客户端推送数据，是实现实时通信的关键技术。当使用反向代理时，需要特殊配置才能保证WebSocket连接正常建立。

根本原因

NGINX默认配置不会自动处理WebSocket连接升级请求。当客户端尝试通过反向代理建立WebSocket连接时，如果没有正确配置，连接升级会失败，导致实时通信功能失效。

解决方案

在NGINX配置中需要添加专门的WebSocket支持配置：

1. 对于特定路径（如/api/ws）需要单独配置
2. 必须包含以下关键指令：
   • proxy_http_version 1.1：启用HTTP/1.1协议
   • proxy_set_header Upgrade $http_upgrade：处理协议升级头
   • proxy_set_header Connection "upgrade"：保持连接升级

完整配置示例

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_buffering off）
2. 如果使用nginx-proxy-manager等管理工具，需要在界面中明确启用"Websockets Support"选项
3. 建议同时配置HTTP到HTTPS的重定向，确保所有连接都使用安全协议

验证方法

部署配置后，可以通过浏览器开发者工具检查：

1. 网络请求中应能看到101 Switching Protocols响应
2. WebSocket连接应显示为持续活跃状态
3. 控制台输出应能实时更新而无需刷新页面

通过以上配置，可以确保Semaphore在反向代理环境下也能提供完整的实时控制台输出功能。