直接用 TotpProvider 会失败，因密钥未Base32编码且长度不合规，或timeStep/时间偏移与客户端不一致；QR码需严格遵循otpauth://totp协议并URL编码；推荐使用OtpNet库而非手写实现。
为什么直接用 TotpProvider 会失败？
很多开发者一上来就搜 “C# 双因素认证”，抄个 TotpProvider 示例代码，结果生成的二维码扫不出来，或验证总是返回 false。根本原因不是代码写错了，而是漏掉了两个关键前提：密钥必须 Base32 编码且长度合规、时间步长（step）和时间偏移必须和服务端/客户端一致。Google Authenticator 和 Microsoft Authenticator 默认使用 30 秒步长、SHA1 算法、10 字节以上 Base32 密钥（推荐 20 字节）。用 Guid.NewGuid().ToString() 当密钥？它既不是 Base32，也不固定长度，Totp 验证必然失败。
- 生成密钥务必用
RNGCryptoServiceProvider或RandomNumberGenerator生成字节数组，再用Base32.Encode（别用 Base64） - 验证时传入的
timeStep必须和生成二维码时一致（通常是 30），否则服务端和客户端时间窗口对不上 - 客户端设备时间不准（偏差 > 1 分钟）会导致验证失败，先提醒用户校准系统时间
如何生成可被 Google Authenticator 扫描的 QR Code？
QR 码内容不是随便拼接的 URL，必须严格遵循 otpauth://totp/ 协议格式，且参数需 URL 编码。常见错误是把公司名/用户名里空格或特殊字符没编码，导致扫码后显示 “Invalid key”。另外，secret 参数值必须是 Base32 编码后的字符串（大写、无填充符 =），不能是原始字节或 Base64。
- 正确格式：
otpauth://totp/MyApp:alice@example.com?secret=JBSWY3DPEHPK3PXP&issuer=MyApp&algorithm=SHA1&digits=6&period=30 -
secret值用Base32.Encode(keyBytes)得到（推荐用OtpNet库的Base32Encoding.ToString(keyBytes)） - 用
QRCoder生成图片时，确保输入字符串是完整、合法的 otpauth URL，不要漏掉issuer（否则 iOS 客户端可能不显示应用名）
OtpNet 和手写 TOTP 验证哪个更可靠？
手写 TOTP（比如用 HMACSHA1 + 时间戳计算）看似可控，但极易出错：时间戳取整偏差、Unix 时间起点搞错（.NET 的 DateTimeOffset.UtcNow.ToUnixTimeSeconds() 是 1970-01-01，但有些示例误用 DateTime.Now.Subtract(...).TotalSeconds 引入浮点误差）、Base32 解码忽略大小写或填充。而 OtpNet 经过大量生产环境验证，内置容错（如允许 ±1 时间窗口）、支持 SHA256/SHA512、自动处理 Base32 编解码，还提供 VerifyTotp 的重载支持滑动窗口。
- 验证时优先用
totp.VerifyTotp(userInput, out long timeStepMatched, verificationWindow: 2)，避免因网络延迟或客户端时间慢半拍导致失败 - 别自己实现 Base32 解码——
OtpNet的Base32Encoding.Decode能处理常见变体（如去掉 O/I/U 等易混淆字符的编码） - 注意
OtpNet默认使用 SHA1；如需更强安全性，初始化Totp时显式传入new HMACSHA256(key)
用户换手机或重装 App 后怎么安全恢复？
双因素不是“设一次就永远有效”。用户丢失设备时，不能只依赖“备用码”（容易丢），也不能直接在后台删掉密钥重启绑定（这等于绕过 MFA）。真实场景中必须配合账户恢复流程：比如要求用户通过已验证邮箱+短信双重确认，再进入“MFA 重置”页面，由管理员审核或触发二次人工验证。技术上，旧密钥必须明确失效（数据库字段 IsRevoked 设为 true），新密钥生成后立即绑定，且旧密钥不可再用于验证。
- 数据库中存储密钥时，绝不要明文存；至少 AES 加密（密钥由主密钥派生，如
DeriveKeyFromUserPassword） - 每次成功验证后记录时间戳，若发现同一密钥在 1 小时内被多设备频繁尝试，触发风控告警
- 提供一次性备用码（10 个），生成后立即 AES 加密存库，并标记为“未使用”，每次使用一个就置为已用——别让用户截图保存明文备用码
实际落地中最容易被跳过的，是密钥生命周期管理：没人记得密钥该定期轮换，也没人处理用户离职后残留的活跃 MFA 绑定。这些不是代码问题，是权限策略问题。
