TOTP 入门文档

一、TOTP 是什么

TOTP 的全称是 Time-based One-Time Password，中文可以理解为“基于时间的一次性密码”。

它是一种用于生成动态验证码的技术，常见于双因素认证，也就是我们经常说的 2FA。

平时登录系统时，通常只需要输入用户名和密码：

用户名 + 密码

开启 TOTP 双因素认证后，登录时还需要输入验证器应用生成的动态验证码：

用户名 + 密码 + 动态验证码

这个动态验证码一般是 6 位数字，并且会按照固定时间间隔自动变化，常见的变化周期是 30 秒。

二、TOTP 解决了什么问题

只使用密码登录存在一个明显问题：如果密码泄露，别人就可能直接登录账号。

TOTP 可以增加第二道防线。即使攻击者知道用户名和密码，如果没有绑定账号的验证器或密钥，也很难通过第二步验证。

可以这样理解：

密码证明“你知道什么”，TOTP 验证码证明“你手里有什么”。

这里的“手里有什么”，通常指已经绑定账号的手机和身份验证器应用。

三、TOTP 的工作原理

TOTP 不需要每次都通过短信平台发送验证码，而是由系统和验证器应用根据同一个密钥和当前时间，分别计算出验证码。

基本过程如下：

系统保存一份密钥
验证器 App 保存同一份密钥
          ↓
系统时间 + 密钥
验证器时间 + 密钥
          ↓
双方计算出相同的动态验证码
          ↓
用户输入验证码，系统进行验证

简单的概念公式可以表示为：

动态验证码 = 根据密钥和当前时间计算出的结果

系统和验证器使用相同密钥，并且时间基本一致，因此可以生成同一个验证码。时间窗口结束后，验证码就会变化。

从技术标准上看，TOTP 建立在 HOTP 之上，只是把递增的计数器替换成了当前时间。常见实现会使用 HMAC 算法，并将结果转换成 6 位或 8 位数字。

四、TOTP 使用过程中涉及的几个概念

1. 密钥

密钥是一段随机生成的字符串，是系统和验证器应用之间的共同凭证。

绑定账号时，系统会生成密钥，并将它转换成二维码或文本形式。

密钥不能随意泄露。如果别人获得了这个密钥，就可能在自己的验证器中生成同样的验证码。

2. 二维码

二维码中包含账号名称、服务器信息和密钥等绑定信息。

用户使用验证器 App 扫描二维码后，App 就能保存这份密钥，并开始生成动态验证码。

二维码通常只需要扫描一次。以后打开验证器时，App 会根据已经保存的密钥继续生成验证码。

3. 动态验证码

动态验证码一般是 6 位数字，例如：

它会定期变化。验证码变化后，旧验证码通常就不能继续使用。

4. 时间窗口

系统不会永远接受一个验证码。验证码通常只在当前时间窗口内有效，例如 30 秒。

为了避免手机和服务器存在少量时间差，系统有时会允许前后相邻的时间窗口，例如前一个或后一个验证码也可以通过验证。

五、常见的身份验证器应用

能够生成 TOTP 验证码的应用有很多，常见的包括：

Google Authenticator
Microsoft Authenticator
Authy
1Password
Bitwarden

不同应用的界面可能不一样，但基本使用方式相同：扫描二维码、保存账号、查看动态验证码。

六、TOTP 与短信验证码的区别

对比项	TOTP 验证码	短信验证码
生成方式	验证器 App 本地生成	服务器通过短信发送
是否依赖网络	生成验证码时通常不需要网络	依赖短信服务和手机网络
使用成本	通常不需要短信费用	可能产生短信费用
安全性	不容易受到短信拦截影响	可能受到 SIM 卡、短信拦截等影响
使用前准备	需要绑定验证器	需要能够接收短信
设备丢失后的处理	需要备用密钥或恢复方式	通常可以重新补办或更换 SIM 卡

TOTP 并不是绝对安全，但对于后台管理系统来说，通常比只使用用户名和密码更安全。

七、TOTP 在 ZFile 中的作用

在 ZFile 项目中，TOTP 主要用于管理员或用户登录时的双因素认证。

登录流程可以理解为：

输入用户名和密码
          ↓
系统验证密码是否正确
          ↓
要求输入 TOTP 动态验证码
          ↓
验证器 App 生成验证码
          ↓
系统验证验证码
          ↓
登录成功

项目中有专门的双因素认证接口，用于完成验证器绑定和验证码校验。例如：

生成双因素认证配置；
获取二维码或绑定信息；
验证用户输入的动态验证码；
登录时检查是否需要进行二次认证。

相关功能可以在源码的 AdminTwoFAController 和 TOTP 配置类中找到。

八、如何使用 TOTP

第一步：在系统中开启双因素认证

管理员进入系统安全设置，开启双因素认证功能。

具体设置名称可能因系统版本不同而有所区别，一般会包含“二次认证”“双因素认证”或“2FA”等字样。

第二步：生成绑定信息

系统会为账号生成一份 TOTP 密钥，并显示二维码。

这份二维码实际上是把密钥包装成了方便扫描的形式。

第三步：使用验证器扫描二维码

打开 Google Authenticator、Microsoft Authenticator 或其他支持 TOTP 的应用，添加新账号并扫描系统显示的二维码。

扫描完成后，应用会显示一个不断变化的 6 位验证码。

第四步：输入验证码完成绑定

将验证器当前显示的验证码输入系统，系统验证通过后，说明绑定成功。

第五步：重新登录测试

退出系统并重新登录。输入正确的用户名和密码后，系统会要求输入验证器中的动态验证码。

九、一个简单的使用例子

假设管理员账号已经绑定验证器。

当前验证器显示：

管理员登录 ZFile 时需要输入：

用户名：admin
密码：自己的登录密码
动态验证码：716204

如果在验证码即将变化时输入失败，可以等待下一组验证码出现后重新输入。验证码变化后，旧验证码通常就不能使用了。

十、TOTP 的优点

1. 增强账号安全

登录不再只依赖密码，即使密码被泄露，也增加了额外的验证步骤。

2. 不依赖短信

验证器应用通常可以离线生成验证码，出国、信号较差或暂时收不到短信时也能使用。

3. 成本较低

系统不需要为每次登录发送短信，适合后台管理系统和私有化部署项目。

4. 实现比较成熟

TOTP 被大量网站、服务器和企业系统使用，验证器应用也比较丰富。

十一、TOTP 的局限

1. 手机丢失可能影响登录

如果验证器只安装在一部手机上，而手机丢失或损坏，用户可能无法生成验证码。

2. 初次绑定需要保存密钥

二维码或密钥是恢复 TOTP 的重要信息。如果没有备用密钥，重新绑定可能需要管理员协助。

3. 依赖时间准确

如果服务器时间和手机时间相差太多，系统可能会认为验证码错误。

4. 不能代替密码安全

TOTP 是第二道防线，不代表密码可以设置得很简单。用户仍然需要使用长度足够、没有重复使用过的密码。

十二、使用时的安全注意事项

不要把 TOTP 二维码发给别人；
不要把密钥保存到公开的聊天群或代码仓库；
不要把动态验证码告诉陌生人；
尽量保存系统提供的备用恢复码；
更换手机前，先确认账号已经迁移到新的验证器；
服务器需要配置准确的系统时间；
管理员账号建议务必开启双因素认证；
如果系统支持，建议同时设置安全的登录入口和强密码。

十三、常见问题

1. 验证码一直提示错误怎么办

可以依次检查：

手机时间是否设置为自动同步；
服务器时间是否准确；
是否使用了正确的账号；
是否输入了当前最新的验证码；
是否误绑定了其他系统或其他账号。

2. 手机丢了怎么办

优先使用备用恢复码或备用验证器登录。如果没有恢复方式，需要由管理员关闭原来的双因素认证并重新绑定。

3. TOTP 验证码能不能重复使用

通常不建议重复使用。验证码只在短时间内有效，而且系统可能会记录已经使用过的验证码，避免重复验证。

4. 使用 TOTP 后还需要密码吗

通常仍然需要。TOTP 是对密码登录的补充，而不是完全替代密码。

5. TOTP 是不是 Redis

不是。TOTP 是一种动态验证码生成和验证标准；Redis 是一种数据存储和缓存工具。

在 ZFile 中，TOTP 负责生成和校验二次认证验证码，Redis 如果启用，可能用于保存登录会话或其他临时数据，两者解决的问题不同。

十四、总结

TOTP 是一种基于时间生成动态验证码的技术，主要用于双因素认证。

它的核心思想很简单：系统和验证器 App 保存同一份密钥，并根据当前时间生成相同的验证码。用户登录时，除了输入密码，还需要输入验证器 App 显示的动态验证码。

在 ZFile 中，TOTP 主要用于提高管理员登录安全性。它并不负责文件管理，也不负责文件预览，而是专门保护用户登录过程。

可以用下面这句话记住它：

TOTP 就是让账号登录从“一道密码门”，变成“密码加动态验证码的两道门”。