# 🔐 2FA

基于 Cloudflare Workers 的两步验证密钥管理系统。免费部署、全球加速、支持 PWA 离线使用。

<!-- README_LANGUAGE_NAV_START -->

**[简体中文](README.md)** · [繁體中文](README_TC.md) · [English](README_EN.md) · [日本語](README_JA.md) · [한국어](README_KO.md) ·
[Deutsch](README_DE.md) · [Français](README_FR.md) · [Español](README_ES.md) · [Português (Brasil)](README_PT_BR.md) · [Italiano](README_IT.md) ·
[Русский](README_RU.md) · [Türkçe](README_TR.md) · [Bahasa Indonesia](README_ID.md) · [Tiếng Việt](README_VI.md) · [ไทย](README_TH.md)

<!-- README_LANGUAGE_NAV_END -->

![Version](https://img.shields.io/badge/version-1.10.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Platform](https://img.shields.io/badge/platform-Cloudflare%20Workers-orange)

**主要特性：** TOTP/HOTP 验证码自动生成 · 二维码扫描/图片识别/粘贴截图/拖拽图片添加密钥 · AES-GCM 256 位加密存储 · 从 Google Authenticator、Aegis、2FAS、Bitwarden 等应用批量导入 · 多格式导出（TXT/JSON/CSV/HTML/Google 迁移二维码） · 自动备份与还原 · WebDAV/S3/OneDrive/Google Drive 远程备份同步 · 账户安全/同步/偏好设置 · 项目全模块 15 语支持（自动检测 / 手动切换） · 浅色/深色/跟随系统主题 · Fluent 2 风格响应式界面

网页、浏览器扩展、首次设置、公开 OTP 页面、接口提示及备份文档统一支持：简体中文、繁體中文、English、日本語、한국어、Deutsch、Français、Español、Português (Brasil)、Italiano、Русский、Türkçe、Bahasa Indonesia、Tiếng Việt、ไทย。界面可跟随浏览器或手动选择，未支持的浏览器语言回退英文；不同语言导出的 CSV/HTML 备份可相互导入。

## 🧩 浏览器扩展

安装「2FA 验证助手」：**[Chrome 应用商店](https://chromewebstore.google.com/detail/2fa-%E9%AA%8C%E8%AF%81%E5%8A%A9%E6%89%8B/lifeiloiefdlbohelpjajdbopeocalhl)** · **[Microsoft Edge 商店](https://microsoftedge.microsoft.com/addons/detail/kmchncmoddhdlbpfoejeahdjhieghklm)** · **[Firefox 附加组件商店](https://addons.mozilla.org/zh-CN/firefox/addon/2fa-%E9%AA%8C%E8%AF%81%E5%8A%A9%E6%89%8B/)**。

请使用对应浏览器打开安装链接。安装后，在扩展设置中填写自己的 2FA 实例地址，并在同一浏览器中登录实例，即可查看、复制和填充 TOTP 验证码；自动填充需在目标验证页面单独开启并授权。扩展需配合已部署的本项目使用，界面支持上述 15 种语言。Firefox 需使用 153 及以上桌面版本的普通标签页，不支持容器标签页、隐私窗口或 Android。

[安装与使用指南](docs/BROWSER_EXTENSION.md) · [Chrome / Edge 隐私政策](extension/PRIVACY.md) · [Firefox 隐私政策](extension/PRIVACY_FIREFOX.md)

## 📸 截图预览

|                    桌面端                     |                    平板端                    |                    手机端                    |
| :-------------------------------------------: | :------------------------------------------: | :------------------------------------------: |
| ![桌面端](docs/images/screenshot-desktop.png) | ![平板端](docs/images/screenshot-tablet.png) | ![手机端](docs/images/screenshot-mobile.png) |

## 🚀 快速部署

### 在线体验

访问演示站点（密码 `2fa-Demo.`）：**[https://2fa-dev.wzf.workers.dev](https://2fa-dev.wzf.workers.dev)**

### 一键部署（推荐）

[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/wuzf/2fa)

> 推荐一键部署；所有用户统一通过 **Sync Upstream** 原地升级，禁止通过删除 Worker、删除仓库或重装方式升级。

1. 点击上方按钮，使用 GitHub 登录并授权
2. 登录 Cloudflare 账户，点击 **Deploy** 等待部署完成（KV 存储自动创建）
3. 打开 Cloudflare 给你的 Workers 链接，**设置管理密码**即可开始使用

> Git 自动构建会直接使用仓库中的 `wrangler.toml` 部署；当前配置已显式声明 `SECRETS_KV`，Wrangler 会在首次部署时自动创建所需 KV，并在后续部署中继续复用当前 Worker 已绑定的资源。
> 如果你在 Cloudflare Dashboard 中手动配置 Git 构建命令，**部署命令请使用 `npm run deploy`，不要直接写 `npx wrangler deploy`**，这样会保留项目里的版本注入流程，并和仓库默认部署入口保持一致。

#### 推荐：启用数据加密

部署后，在 **Cloudflare Dashboard → Worker → Settings → Variables** 中添加 Secret `ENCRYPTION_KEY`：

```bash
# 生成加密密钥（任选一种）
openssl rand -base64 32
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
```

> `ENCRYPTION_KEY` 是解密现有数据的主密钥。**推荐设置**，前提是你会把原始值立即保存到密码管理器、离线备份或其他安全位置。
>
> 如果你无法确保保存原值，**宁可暂时不设置，也不要设置后丢失**：
>
> - 设置后：密钥列表、自动备份、WebDAV/S3/OneDrive/Google Drive 凭据都会加密存储
> - 丢失后：Cloudflare 不会再次显示原值，已有加密数据和加密备份将无法读取或恢复
> - 当前程序行为：检测到已有加密数据但缺少 `ENCRYPTION_KEY` 时，会直接锁定读取和修改，避免误覆盖旧数据

#### 版本更新

一键部署生成的是独立仓库（非 Fork），升级统一使用 **Sync Upstream** 工作流原地完成。

> ⚠️ **升级前务必先备份数据**：在执行版本更新前，请先通过 **批量导出** 或 **还原配置 → 导出备份** 将当前数据导出到本地，以防操作失败导致数据丢失。

1. 打开一键部署时在你 GitHub 上生成的 2fa 仓库
2. 进入 **Actions** → **Sync Upstream**
3. 点击 **Run workflow**，上游分支保持默认的 `main`，发起一次新运行
4. 等待同步完成及 Cloudflare 自动部署，之后刷新应用即可

工作流会自动保留你当前仓库里的 Worker 名称、KV 绑定和常见部署配置，并重新部署**同一个 Worker**。仓库中已有的工作流文件也会保留。

> **没有 Sync Upstream 入口时**：一键部署创建的仓库可能不包含工作流。此时才需要在自己的仓库中新增 `.github/workflows/sync-upstream.yml`，内容复制自上游文件：<https://github.com/wuzf/2fa/blob/main/.github/workflows/sync-upstream.yml>，并提交一次。之后按上面步骤升级。

> **之前因 `without workflows permission` 升级失败**：修复发布到上游 `main` 后，已有自动合并部署配置步骤的 **Sync Upstream** 可以直接按上面步骤升级，无需修改 YAML 或配置 PAT。请选择 `main` 发起新运行，不要选择不含修复的旧版本标签。其他情况见[升级故障排查](docs/DEPLOYMENT.md#升级故障排查)。

这种方式不会动现有 Worker、KV 绑定或 Secrets。**如果你已经设置了 `ENCRYPTION_KEY`，升级时无需重新填写；如果你没设置，也照样用这套流程升级。**

> ⚠️ `ENCRYPTION_KEY` 是解密现有数据的主密钥，请务必在首次创建时保存到密码管理器。Cloudflare Secret 保存后不会再次显示原值；正常升级不需要重新填写，但如果你把它删了又没保存原值，已有加密数据将无法恢复。

> ⚠️ **回滚到 1.8.0 之前的版本**：1.8.0 起 HOTP 计数器的递增单独存储，回滚前需要先调用一次压实接口把计数器写回主数据，否则 HOTP 计数器会退回到升级时的值。步骤见[回滚到 1.8.0 之前的版本](docs/DEPLOYMENT.md#回滚到-180-之前的版本)。只用 TOTP 的部署不受影响。

#### 如果你想检查合并结果

`Sync Upstream` 的设计目标是始终在**同一仓库、同一 Worker**上完成升级。现在工作流会自动合并 `wrangler.toml`，并在摘要中展示与上游的差异，便于你确认哪些值来自本地部署配置：

1. 在 GitHub Actions 的运行摘要里查看 `wrangler.toml` diff
2. 打开当前仓库里的 `wrangler.toml`
3. 确认 Worker 名称、KV 绑定、路由和现有部署设置仍然正确
4. 如果你自己维护了非常特殊的 `wrangler.toml` 配置，再按需要补充提交

> 如果 Cloudflare 没有自动开始重新部署，也是在 **Deployments** 页面重新部署当前仓库的最新提交，而不是删除后重装。

## 📖 使用指南

### 添加密钥

点击右下角 **➕** 悬浮按钮：

- **扫二维码** — 摄像头扫描 2FA 二维码，自动填入
- **选择图片** — 上传二维码截图，自动识别
- **粘贴截图** — Ctrl+V 粘贴剪贴板中的二维码截图（适合无摄像头的 PC 用户）
- **拖拽图片** — 直接将二维码图片拖入弹窗，自动识别
- **手动添加** — 输入服务名称和 Base32 密钥（可展开高级设置调整位数/周期/算法）

### 日常使用

- **复制验证码**：直接点击验证码数字
- **管理密钥**：点击卡片右上角 **⋯** → 查看二维码 / 复制 URI / 复制网页链接 / 编辑 / 删除
- **搜索**：顶部搜索框按服务名或账户名实时搜索
- **智能聚合**：默认按服务家族自动聚合，同一服务的多个账户归在一起，也可切换为全部平铺
- **排序**：按添加时间或名称排序
- **主题**：悬浮按钮 → **设置 → 偏好设置 → 主题模式**，选择浅色、深色或跟随系统

### 批量导入

点击悬浮按钮 → **📥 批量导入**，支持文件导入或文本粘贴。

**兼容格式：**

| 来源                   | 格式                                    |
| ---------------------- | --------------------------------------- |
| 通用                   | `otpauth://` URI 文本（TXT）、CSV、HTML |
| Google Authenticator   | 迁移二维码（`otpauth-migration://`）    |
| Aegis                  | JSON 导出文件                           |
| 2FAS                   | `.2fas` 导出文件                        |
| Bitwarden              | JSON、Authenticator CSV 导出文件        |
| LastPass Authenticator | JSON 导出文件                           |
| andOTP                 | JSON 导出文件                           |
| Ente Auth              | 导出文件                                |

### 批量导出

点击悬浮按钮 → **📤 批量导出**，支持 TXT、JSON、CSV、HTML 格式，以及生成 **Google Authenticator 迁移二维码**（可直接扫码导入）。
标准 TXT / JSON / CSV / HTML 导出在在线时优先使用统一后端格式；离线或请求体过大时会自动回退到本地兼容导出，继续保证 PWA 可用性。

### 备份与还原

系统自动备份（数据变化后自动触发 + 每天定时检查），保留最近 100 个备份（可在设置中调整）。
新创建的备份文件格式会跟随 **设置 → 默认导出格式**；远程自动备份也会使用相同的扩展名（`txt` / `json` / `csv` / `html`）。

点击悬浮按钮 → **🔄 还原配置** 查看备份列表、预览内容、还原或导出；也可以上传从 WebDAV/S3/OneDrive/Google Drive 下载的 `backup_*.(txt|json|csv|html)` 文件进行预览和恢复。

#### 远程备份

支持将备份同步到远程存储，数据变更时自动推送，可配置多个备份目标：

- **WebDAV** — 支持标准 WebDAV 协议的网盘或自建服务（⚠️ 不支持经 Cloudflare 代理的服务如坚果云，会触发 520 回环错误）
- **S3 兼容存储** — 支持 AWS S3、Cloudflare R2、MinIO、阿里云 OSS 等 S3 兼容服务
- **OneDrive** — 通过 Microsoft OAuth 授权后，将备份写入 OneDrive 应用专用目录下的子路径
- **Google Drive** — 通过 Google OAuth 授权后，将备份写入 Google Drive 指定目录

在 **设置 → 同步设置** 中添加和管理远程备份目标。

远程备份保存的是应用生成的同一份备份内容。若创建备份时已配置 `ENCRYPTION_KEY`，远程文件内容也是加密密文；恢复时需在 Worker 中保留同一个 `ENCRYPTION_KEY`。

详细配置步骤见：[网盘备份配置指南](docs/CLOUD_DRIVE_SETUP.md)

### 设置

点击悬浮按钮 → **⚙️ 设置**：

- **修改密码** — 更改管理密码
- **主题模式** — 选择浅色、深色或跟随系统
- **验证码交接动效** — 关闭或选择流转、翻牌、聚光动效
- **登录有效期** — 自定义 JWT 过期时间
- **默认导出格式** — 控制导出按钮默认格式，也用于新建备份文件和远程自动备份的文件扩展名
- **备份保留数量** — 调整自动备份保留份数
- **远程备份** — 配置 WebDAV/S3/OneDrive/Google Drive 备份目标
- **退出登录** — 一键清除当前会话 Cookie 与本地缓存，离线/服务端故障时仍能本地登出

### 安装为手机应用（PWA）

- **iOS**：Safari 打开 → 分享按钮 → 添加到主屏幕
- **Android**：Chrome 打开 → 菜单（⋮）→ 添加到主屏幕

安装后可像原生应用一样全屏使用，支持离线访问。

### Chrome / Edge / Firefox 验证码辅助填充

在目标网站点击扩展选择账户，或按 `Ctrl+Shift+U` 填入已绑定账户的当前 TOTP。按页面授权后，可自动检测验证码框并填充；多个账户匹配时显示选择面板。支持单框和 6/8 格输入，不主动提交表单。

扩展使用网页登录会话，支持明确启用离线缓存，均无需保持主网页打开。网页登录模式在后台临时读取密钥，离线模式则在本机保留独立密钥缓存，断网后仍可取码。种子不传给弹窗或目标网站，离线缓存没有额外密码加密。支持开放 Shadow DOM 与同源 iframe；暂不支持 HOTP、跨域 iframe、关闭的 Shadow DOM 或隐私模式。

详见[安装与使用指南](docs/BROWSER_EXTENSION.md)、[Chrome / Edge 隐私说明](extension/PRIVACY.md)及[Firefox 隐私说明](extension/PRIVACY_FIREFOX.md)。

## 🔒 安全

- **密码**：PBKDF2-SHA256（100,000 次迭代）加盐哈希，JWT 存储在 HttpOnly + Secure + SameSite=Strict Cookie 中
- **数据加密**：配置 `ENCRYPTION_KEY` 后所有密钥、备份以及 WebDAV/S3/OneDrive/Google Drive 凭据使用 AES-GCM 256 位加密；请务必保存原始密钥，丢失后无法解密已有数据
- **传输**：全程 HTTPS，TLS 1.2+
- **隐私**：OTP 在客户端生成，不收集使用数据，完全开源
- **登录有效期**：默认 30 天，可在设置中自定义，活跃使用自动续期（剩余 < 7 天时自动延长）

## 🔗 公开 OTP API

无需登录，通过 URL 直接生成验证码：

```
https://your-worker.workers.dev/otp/YOUR_SECRET_KEY
https://your-worker.workers.dev/otp/YOUR_SECRET_KEY?digits=8&period=60
https://your-worker.workers.dev/otp/YOUR_SECRET_KEY?type=hotp&counter=5
```

参数：`type`（totp/hotp）、`digits`（6/8）、`period`（30/60/120）、`algorithm`（sha1/sha256/sha512）、`counter`（HOTP 用）

TOTP 网页同时显示当前和下一个验证码，均可点击复制，到期后原地更新。HOTP 网页显示链接中指定计数器的验证码，复制不会推进计数器。

## 📚 更多文档

| 文档                                          | 说明                                               |
| --------------------------------------------- | -------------------------------------------------- |
| [部署指南](docs/DEPLOYMENT.md)                | 手动部署、KV 配置、Secrets 管理                    |
| [网盘备份配置指南](docs/CLOUD_DRIVE_SETUP.md) | OneDrive / Google Drive 中文配置步骤与简化设计建议 |
| [API 参考](docs/API_REFERENCE.md)             | 完整 API 端点文档                                  |
| [架构设计](docs/ARCHITECTURE.md)              | 系统架构与技术实现                                 |
| [开发指南](docs/DEVELOPMENT.md)               | 本地开发、测试、代码规范                           |
| [PWA 指南](docs/PWA_GUIDE.md)                 | PWA 安装与离线功能                                 |
| [浏览器扩展指南](docs/BROWSER_EXTENSION.md)   | Chrome / Edge / Firefox 扩展安装、使用与权限       |

## 🤝 参与贡献

欢迎提交 [Issue](https://github.com/wuzf/2fa/issues) 和 [Pull Request](https://github.com/wuzf/2fa/pulls)。开发相关请参考 [开发指南](docs/DEVELOPMENT.md)。

## 📄 许可证

[MIT License](LICENSE)

## 🌟 Star History

<p align="center">
  <a href="https://github.com/wuzf/2fa/tree/star-history">
    <img alt="Star History Chart" src="https://raw.githubusercontent.com/wuzf/2fa/refs/heads/star-history/star-history.svg" />
  </a>
</p>

---

<div align="center">

**如果这个项目对您有帮助，请给一个 ⭐**

Made with ❤️ by [wuzf](https://github.com/wuzf)

</div>