Semaphore项目中反向代理路径配置对TOTP二维码生成的影响

问题背景

Semaphore是一个开源的Ansible Web UI工具，在v2.12.4版本中引入了双因素认证(2FA)功能。当用户在使用反向代理(如Nginx)部署Semaphore时，如果配置了非根路径(如/semaphore)，在生成TOTP二维码时会出现路径错误的问题。

技术细节分析

该问题的核心在于Web前端生成TOTP二维码时，API请求路径没有正确处理Web根路径(SEMAPHORE_WEB_ROOT)配置。具体表现为：

1. 当配置SEMAPHORE_WEB_ROOT=/semaphore时
2. 前端生成的二维码请求路径错误地指向了/api/users/...而不是预期的/semaphore/api/users/...
3. 导致浏览器无法正确加载二维码图片

解决方案

Semaphore开发团队在v2.12.7版本中修复了这个问题。修复内容包括：

1. 修改了前端组件(UserForm.vue)中的API请求路径生成逻辑
2. 确保所有API请求都正确考虑了SEMAPHORE_WEB_ROOT配置
3. 使二维码生成功能在反向代理环境下正常工作

配置建议

对于使用反向代理部署Semaphore的用户，建议采用以下Nginx配置模板：

server {
    listen 80;
    server_name your.domain;

    location /semaphore {
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_pass http://backend:3000/semaphore;
    }
    
    location /semaphore/api/ws {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Origin "";
        proxy_pass http://backend:3000/semaphore;
    }
}

升级建议

遇到此问题的用户应升级到v2.12.7或更高版本。升级后，TOTP二维码生成功能将在反向代理环境下正常工作，确保双因素认证流程的完整性。

总结

路径处理是Web应用在反向代理环境下常见的兼容性问题。Semaphore团队通过这个修复，增强了产品在不同部署场景下的适应性。这也提醒开发者，在实现类似功能时，需要充分考虑应用可能运行的各种环境，特别是当涉及URL生成和API请求时。