必须使用otpnet库，严格采用base32编码密钥、30秒时间步长、标准otpauth uri格式，并启用verificationwindow滑动窗口验证，否则极易因密钥编码、时间偏移或协议不合规导致验证失败。
直接用 TotpProvider 或手写 HMAC-SHA1 + 时间戳逻辑，大概率验证失败——不是算法错，而是密钥编码、时间窗口、QR 协议三处全踩坑。真正在生产环境跑通，必须用 OtpNet 库，并严格控制 Base32 编码、timeStep=30、otpauth URL 格式。
密钥必须用 RNGCryptoServiceProvider 生成并 Base32 编码
用 Guid.NewGuid().ToString() 或 Random.Next() 生成的“密钥”根本不能用：它既不是 Base32，长度也不固定，OtpNet 的 Totp.ValidateTotp() 会静默失败或抛 ArgumentException。
- 正确做法：用
RandomNumberGenerator.Create().GetBytes(keyBytes)生成 20 字节随机数组（推荐长度，兼容所有主流客户端） - 再调用
Base32Encoding.ToString(keyBytes)得到大写、无=填充的字符串（如JBSWY3DPEHPK3PXP），这才是 secret 参数合法值 - 千万别用 Base64 —— Google Authenticator 只认 Base32，且区分大小写（必须大写）
- 存入数据库时，只存这个 Base32 字符串，别存原始字节或 Guid
QR 码内容必须是完整、URL 编码的 otpauth://totp 链接
扫码后显示 “Invalid key” 或 iOS 不显示应用名？90% 是 URL 拼错了。otpauth 协议对参数顺序、编码、必需字段极其敏感。
- 最小可用格式：
otpauth://totp/{issuer}:{user}?secret={secret}&issuer={issuer}&period=30&digits=6&algorithm=SHA1 -
{issuer}和{user}中的空格、@、/ 等字符必须Uri.EscapeDataString()编码（例如alice@example.com→alice%40example.com） -
secret值本身不用再编码（它已是合法 Base32 字符串），但整个 URL 字符串传给 QR 生成器前必须是完整字符串 - 用
QRCoder时，输入就是这个 URL 字符串；漏掉issuer参数，Android 可能正常，iOS 客户端常不显示应用图标
服务端验证必须启用滑动窗口且校准时间偏移
用户手机时间慢了 45 秒，或你服务器 NTP 同步有偏差，ValidateTotp() 直接返回 false——这不是 bug，是 TOTP 协议设计使然。
- 永远不要只传当前时间戳：用
totp.ValidateTotp(secret, inputCode, out long timeStepMatched, new VerificationWindow(2, 2)) -
VerificationWindow(2, 2)表示向前查 2 个周期、向后查 2 个周期（共 5 个 30 秒窗口），覆盖 ±60 秒偏差 - 拿到
timeStepMatched后可记录实际匹配的时间步，用于后续分析设备时钟漂移趋势 - 首次绑定成功后，建议在登录页加一行小字提示：“请确保手机系统时间已开启自动同步”
OtpNet 是唯一靠谱选择，别碰 TotpProvider 或手写 HMAC
TotpProvider（来自早期 ASP.NET Identity）默认用 SHA1 + 30 秒，但不暴露 VerificationWindow、不处理 Base32 编解码容错、不支持 SHA256；手写容易在 Unix 时间戳取整（ToUnixTimeSeconds() vs DateTime.Now.Subtract(...).TotalSeconds）、HMAC 输入字节序、动态截断（decoding）等环节翻车。
- NuGet 安装：
Install-Package OtpNet（.NET 6+ 推荐 7.x 版本） - 生成密钥：
var key = KeyGeneration.GenerateRandomKey(20); var secret = Base32Encoding.ToString(key); - 验证入口：
new Totp(key).ValidateTotp(inputCode, ...)，key 是原始字节数组，不是 Base32 字符串 - 别用
TwoStepsAuthenticator—— 它不维护、不支持滑动窗口、无 .NET 6+ 官方适配
最易被忽略的一点：TOTP 绑定流程中，服务端生成密钥、生成 QR、返回 secret 给前端，这三步必须原子化完成；如果中间发生异常（比如 QR 图片生成失败但密钥已存库），会导致用户扫了无效码，而服务端却以为绑定成功——这种状态不一致问题，比算法错误更难排查。
