Repository navigation
User Guide
本页介绍主程序的网页操作。尚未部署时，先完成快速开始；已有验证器的数据可通过导入与导出迁移。
在需要两步验证的网站中开启“身份验证器”验证，取得该网站提供的二维码或 Base32 密钥，然后打开自己的 2FA 实例，点击右下角的悬浮按钮。
| 方式 | 操作 |
|---|---|
| 摄像头扫描 | 选择“扫描二维码”，允许摄像头权限，对准网站显示的二维码 |
| 二维码图片 | 在“扫描二维码”弹窗中点击“选择图片”，或将图片拖入该弹窗 |
| 剪贴板截图 | 在“扫描二维码”弹窗中点击“粘贴截图”，桌面端也可用 Ctrl+V
|
| 手动添加 | 选择“手动添加”，输入服务名称、账户名称和网站提供的 Base32 密钥 |
扫描普通 TOTP / HOTP 二维码会识别服务、账户及验证码参数（HOTP 包括计数器）并直接保存；Google Authenticator 的迁移二维码会打开“Google Authenticator 导入”预览，确认后批量导入。识别结束后核对列表中的账户，不要重复添加同一二维码。图片过小、模糊或被裁掉边缘时，可换用原图或手动输入。
1.12.0 之前的版本扫描普通 otpauth://hotp/ 二维码（包括摄像头、图片、粘贴与拖拽）时会误存为 TOTP，显示的验证码不对。这样添加的账户，请编辑后在“高级设置 (可选)”中把类型改为 HOTP，并按来源填写计数器、位数和算法，或删除后重新扫码；不要使用误存期间显示的验证码。
添加完成后，把当前验证码填回原网站，完成网站自己的绑定确认。只在本项目中保存密钥，并不等于已在网站上启用两步验证。网站给出的恢复码也应另行保存，本项目不会替网站生成恢复码。
大多数网站使用默认的 TOTP / 6 位 / 30 秒 / SHA1。高级设置应按来源网站的要求填写，修改显示名称通常不需要更改这些参数。
| 参数 | 支持范围及含义 |
|---|---|
| 类型 | TOTP 按时间变化；HOTP 按计数器变化 |
| 位数 | 6 位或 8 位 |
| 算法 | SHA1、SHA256、SHA512 |
| TOTP 周期 | 新增时可选 30、60、120 秒 |
| HOTP 计数器 | 大于或等于 0 的安全整数，应与目标网站同步 |
密钥应使用 Base32 字符。不要把登录密码、恢复码或当前的六位验证码填入密钥框。当前支持范围不包含 Steam Guard 等专用验证码格式。
TOTP： 点击卡片上的当前验证码即可复制。倒计时结束后自动换码；卡片右侧较小的数字是下一周期的验证码，点击可复制，须到下一周期才有效。临近到期时可以等刷新后再填入网站。网页在后台自动向实例校时，主页不再显示校时状态或“重新校时”按钮。验证码持续无效时，先确认设备的自动日期时间已开启，再联网刷新。
HOTP： 卡片显示 [HOTP] 和计数器，不显示时间倒计时。点击验证码会复制当前值，并向服务器申请推进计数器，因此需要网络和有效登录。离线时会阻止这项复制操作。不要为了观察而连续点击，以免计数器超前。
HOTP 的剪贴板写入与服务器计数器更新是两项操作。如果提示“验证码已复制，但本地计数器同步失败”“验证码未复制，计数器状态已重新对账”或“复制失败，HOTP 计数器已安全推进”，应先重新加载账户并核对提示，再决定是否使用或重新生成；不要假定报错就表示计数器没有改变。多个设备共用 HOTP 时尤其要避免同时操作。计数器回滚的部署注意事项见升级与回滚。
顶部搜索框可以按服务名称、账户名称或邮箱筛选。点击“显示与排序”可选择：
| 显示方式 | 排序方式 |
|---|---|
| 智能聚合 | 按服务家族自动聚合；分组名称可 A–Z / Z–A；组内可按最早添加、最晚添加或账户名称排序 |
| 全部平铺 | 所有匹配账户在同一列表；可按添加顺序、服务名称或账户名称排序 |
智能聚合基于内置的服务识别规则，只有一个账户的服务归入“其他服务”分组；它不是可自由创建的文件夹或标签系统。同一服务的名称写法尽量一致，账户名称用于区分个人、工作等不同登录身份。显示方式和排序偏好保存在当前浏览器，清除站点数据后需要重新设置。
在“设置 → 偏好设置 → 默认显示方式”中，可选择“记住上次选择”“智能聚合”或“全部平铺”，选中后立即生效。默认选项为“记住上次选择”；没有历史选择时使用智能聚合。固定为智能聚合或全部平铺后，仍可从“显示与排序”临时切换，刷新或重新打开时回到固定方式；改回“记住上次选择”会沿用当前视图。该设置不在设备之间同步。
首次显示账户时就会应用本浏览器保存的视图和排序，包括从缓存加载账户的离线首屏。
点击卡片右上角 ⋮ 打开账户操作菜单。
| 操作 | 用途与注意事项 |
|---|---|
| 编辑 | 修改服务名、账户名、密钥及高级参数；保存后核对验证码是否仍与原网站一致 |
| 二维码 | 将该账户导入其他兼容验证器；二维码内含原始密钥 |
| 复制 URI | 复制 otpauth:// 配置，包含密钥与生成参数 |
| 复制链接 | 生成公开 OTP 页的链接，链接本身带有密钥；其访问不要求管理登录 |
| 删除 | 经确认后从当前实例删除账户，不会关闭原网站的两步验证 |
二维码、URI 和公开网页链接都应按原始密钥保管，不要放入公开 issue、聊天群或截图。公开 OTP 页的工作方式见接口参考，安全边界见安全说明。
如果首页提示有无效或不支持的记录被隐藏，可展开查看原因；有可识别 ID 的记录可以删除。普通批量导出不包含这些隐藏记录，导出窗口会提示数量。需要保留或分析原始数据时，先使用备份与还原，不要直接删掉无法显示的记录。
悬浮菜单除扫描二维码和手动添加外，还提供批量导入、批量导出、备份与还原、实用工具箱和系统设置。系统设置分为账户安全、同步设置和偏好设置三页。
- 账户安全： 修改管理密码、退出登录。
- 偏好设置： 切换语言、浅色/深色/跟随系统主题、验证码交接动效、默认显示方式、默认导出格式，以及登录有效期（1–365 天，之后登录或自动续期时采用新值；现有令牌的到期时间不会被直接改写）。
- 同步设置： 管理 WebDAV、S3、OneDrive、Google Drive 备份目标，见远程存储。
- 备份保留数量（偏好设置）： 调整保留份数，0 表示不限制。默认导出格式也决定之后新建备份的格式，见备份与还原。
- 安装到桌面（偏好设置）： 浏览器支持时安装为独立应用，见PWA 与离线使用。
- 实用工具箱： 提供二维码生成/解码、Base32、密钥检查/生成、时间戳等辅助功能。随机生成密钥不会自动为某个外部网站创建两步验证绑定。
界面支持多种语言，可跟随浏览器或手动选择，具体语言代码见配置参考。浏览器语言不受支持时回退为英文。功能入口的翻译可能不同，页面结构保持一致。
退出登录会立即清空当前页面的账户和本地账户列表缓存，并尝试注销服务器会话。断网时仍能清除本地显示，但服务器注销是否成功应以提示为准。未同步的操作和扩展独立缓存有各自的生命周期，详见PWA和浏览器扩展。
从 v1.13.1 起，主页面的功能弹窗统一支持点击弹窗外部空白处、按 Esc、点击 × 或取消退出；点击弹窗内部不会关闭。从弹窗内部拖到外部松手也不会误触关闭。
- 没有未保存内容： 直接关闭，包括尚未填写的表单和纯展示弹窗。
- 有未保存内容： 手动添加、编辑账户、批量导入、云存储配置等表单先询问是否放弃；选择“继续编辑”会保留输入、文件或待导入内容。确认放弃后才关闭。
-
多层弹窗： 每次只处理最上层。在“放弃未保存的内容？”确认框中按
Esc或点击外部，等同于“继续编辑”，不会连带关闭底层表单。 - 系统设置： 关闭前先等待最新的自动保存完成；保存成功且无其他未提交内容时直接关闭。保存失败或密码表单尚未提交时，先确认是否放弃；等待超过 5 秒仍无法确认保存结果时，可选择关闭或继续编辑，详见保存结果尚未确认。
右下角“+”菜单本身仍可通过点击外部或 Esc 收起。关闭弹窗与收起菜单是两种不同操作。
| 现象 | 先检查什么 |
|---|---|
| 验证码一直错误 | 服务和账户是否选对；设备时间；位数、周期、算法；HOTP 计数器 |
| 扫码后没有账户 | 图片清晰度、二维码类型、导入预览中的错误和不支持参数 |
| 手机上看不到新添加的数据 | 是否打开同一实例；是否在线；是否还有“未同步更改” |
| 网页与扩展账户不一致 | 扩展连接的实例地址、网页登录状态和离线缓存同步状态 |
| 删除后无法登录原网站 | 用原网站恢复码或其账户恢复流程；本项目删除不会替原网站关闭 2FA |
更多问题见常见问题。