【踩坑记录】自建 2FAuth 无法识别二维码、扫描后白屏的终极解决方案

最近在折腾自建 2FAuth（一个基于 Web 的二步验证 OTP 管理工具），部署过程还算顺利，但在最关键的“扫描/上传二维码”添加账号环节卡了很久。

起初是上传无反应，解决后又变成了识别成功但界面卡死白屏。经过一番排查，终于发现了是 Nginx 配置和 “自动获取图标” 的网络问题导致的。这里记录一下解决过程。

一、 问题现象

1. 上传无反应：点击上传二维码图片，前端没有任何提示，或者直接报错 response is undefined。
2. 识别后白屏：修复上传问题后，图片能上传了，但在解析出 OTP 链接后，界面一直转圈，最后白屏或无响应。查看 F12 网络请求，发现 decode 接口返回 200（成功），但随后的 preview 接口报 499 或超时错误。

二、 排查与解决步骤

第一步：解决 Nginx 上传限制（上传报错的元凶）

如果是使用 Docker + Nginx（或 Nginx Proxy Manager）反代，默认的上传体积限制太小，且缓冲区设置可能会导致图片上传中断。

解决方法：
在 Nginx 的 location 配置块中加入以下两行，扩大上传限制：codeNginx

location ^~ / {
    # ... 其他配置 ...
    
    # 关键配置：允许大文件上传，防止 413 错误
    client_max_body_size 10M;
    # 关键配置：增加缓冲区，防止写入临时文件权限问题
    client_body_buffer_size 128k; 
    
    # ... 其他配置 ...
}

修改后记得重载 Nginx。

第二步：解决“获取官方图标”导致的超时（白屏卡死的元凶）

解决了上传问题后，我发现日志里 POST /api/v1/qrcode/decode 已经返回 200 了，说明二维码内容已经解出来了，但紧接着的 preview 请求却一直 Pending 直到超时。

原因分析：
2FAuth 有一个贴心但“致命”的功能：自动获取官方图标。
当你扫描二维码后，后端会根据解析出的域名（比如 Google, Github），尝试去国外的图标源 API（如 2fa.directory 或 Brandfetch）下载 Logo。
如果你的服务器在国内，或者网络环境无法顺畅访问这些国外 API，后端就会一直卡在“下载图标”这一步，导致前端收不到响应，最终造成页面假死。

终极解决方法：

进入 Settings (设置) -> User Management (用户管理) 。

找到 Getting official icons (获取官方图标) 区域：

这里有两个方案：

1. 方案 A（彻底解决）：
   直接取消勾选 显示图标和获取官方图标（Getting official icons）。
   • 优点：速度最快，秒添加。
   • 缺点：添加的账号默认没有图标（显示首字母），需要后续手动上传。
2. 方案 B（优化体验）：
   如果你依然想要自动图标，尝试修改 Favorite icon source。
   • 默认可能是连接不畅的源，将其改为 2fa.directory（如图所示）或者其他你服务器能访问通的源。
   • 如果所有源都连不上，请老实选择方案 A。

三、 总结

自建服务最怕的就是网络环境导致的“水土不服”。

• Nginx 413/400 错误 -> 检查 client_max_body_size。
• 接口 499/504 超时 -> 99% 是后端在尝试请求发不通的外网资源（如下载图标、检查更新）。

只要关掉自动获取图标的功能，2FAuth 的体验瞬间如丝般顺滑。希望这个记录能帮到同样遇到“卡死”问题的 Docker 玩家！