Semaphore项目中TOTP二维码生成路径错误的解决方案

Semaphore是一个基于Web的开源Ansible管理界面，在v2.12.4版本中引入了双因素认证(2FA)功能。然而，当系统部署在反向代理环境下时，用户发现TOTP(基于时间的一次性密码)二维码生成功能存在路径配置问题。

问题现象

在配置了反向代理的场景下，当用户尝试启用2FA功能时，系统生成的TOTP二维码URL路径不正确。具体表现为：

• 预期路径应包含Web根路径前缀(如/semaphore)
• 实际生成的URL缺少此前缀，导致二维码无法加载

问题根源

这个问题主要源于前端组件(UserForm.vue)在生成TOTP二维码URL时，没有正确处理Web根路径(SEMAPHORE_WEB_ROOT)配置。当系统部署在子路径下时，所有API请求都应该包含这个前缀，但二维码生成逻辑中遗漏了这一点。

解决方案

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

1. 确保所有API请求路径都正确包含Web根路径前缀
2. 统一前端路由处理逻辑，使其与反向代理配置兼容

配置建议

对于使用反向代理的用户，建议采用以下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或更高版本。升级后，系统将能够正确处理以下配置：

• SEMAPHORE_WEB_ROOT环境变量
• 反向代理下的子路径部署场景
• TOTP二维码生成功能

总结

路径处理是Web应用在反向代理环境下常见的配置问题。Semaphore团队通过这个修复，提高了系统在不同部署场景下的兼容性。对于需要安全认证的企业用户来说，确保2FA功能正常工作尤为重要，建议所有用户及时升级到修复版本。