应直接使用 github.com/pquerna/otp 而非自行实现 totp，因其避免时间窗口偏移、base32 编解码不一致、hmac-sha1 截断错误以及时区问题，且维护活跃、测试充分、支持热重载与自定义步长。
为什么直接用 github.com/pquerna/otp 而不是自己实现 TOTP
自己手撸 RFC 6238（TOTP 标准）容易出错：时间窗口偏移、base32 编码/解码不一致、HMAC-SHA1 截断逻辑错位，甚至时区处理翻车。生产环境里，github.com/pquerna/otp 是事实标准，维护活跃、测试充分、支持热重载密钥和自定义时间步长。
- 它默认用
time.Now().UTC()计算计数器，避免本地时区干扰 -
otp.NewTOTP()返回的*TOTP实例可复用，不是一次性对象 - 注意：v1.x 版本不兼容 Go 1.21+ 的
crypto/hmac内部变更，必须用 v2.0.0+（当前最新是 v2.1.0）
otp.GenerateCode() 的参数陷阱和正确调用方式
这个函数看似简单，但两个参数顺序和类型极易搞反：secret 必须是原始字节切片（不是 base32 字符串），time 是 int64 时间戳（单位秒），不是 time.Time。
- 错误示范：
otp.GenerateCode("JBSWY3DPEHPK3PXP", time.Now().Unix())——"JBSWY3DPEHPK3PXP"是 base32 编码后的字符串，不能直接传 - 正确做法：先用
base32.StdEncoding.DecodeString("JBSWY3DPEHPK3PXP")解码成[]byte，再传入 - 时间戳必须对齐 TOTP 步长（默认 30 秒），否则生成口令会和 Google Authenticator 不一致；可用
unixTime / 30 * 30向下取整
如何让生成的口令和 Google Authenticator 完全同步
同步失败八成是因为时间偏差或密钥格式不一致。TOTP 本质是「时间 + 密钥」的 HMAC 输出，差一秒或一个字节就全错。
- 服务端时间必须和 NTP 同步（
ntpd或systemd-timesyncd），误差超过 1 分钟基本无法对齐 - 密钥必须用 base32 编码（RFC 4648 §6），且**全部大写、无空格/换行**；小写或带等号结尾会导致解码后字节不同
- Google Authenticator 默认使用 SHA1，不要在
otp.TOTPConfig{}里擅自改成 SHA256 —— 它不认 - 生成 QR code 时，URI 格式必须为：
otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Example，少一个参数都扫不出来
验证用户输入口令时，为什么要检查前后几个时间窗口
客户端和服务端时钟永远存在微小偏差，单纯比对当前时间窗口的口令必然失败。RFC 6238 明确要求验证器应检查 t−1、t、t+1 三个窗口（即 ±30 秒）。
立即学习“go语言免费学习笔记（深入）”；
-
totp.Validate()默认只校验当前时间窗口；要支持容错，得手动循环调用totp.ValidateCustom() - 示例：对
now.Unix()、now.Add(-30 * time.Second).Unix()、now.Add(30 * time.Second).Unix()分别验证 - 别盲目扩大窗口（比如 ±90 秒）—— 会显著增加重放攻击风险，且违背 TOTP 设计初衷
真正麻烦的是跨语言密钥互通：Node.js 的 speakeasy 默认 base32 编码用 base32.encode(secret, 'hex')，而 Go 的 base32.StdEncoding 对 hex 字符串编码结果完全不同。密钥必须统一用原始字节流做 base32 编码，不能在中间转 hex。
