全栈 2FA 认证器
TOTP/HOTP 管理 · 加密存储 · 离线可用 · 多格式导入导出
Neo 是一个全栈 TOTP/HOTP 认证器，基于 Next.js 15 + Cloudflare D1 构建。采用 MVVM 架构，ViewModel 完全解耦视图层，所有密钥操作通过 Server Actions 在服务端完成，数据库按用户隔离。支持 PWA 离线使用、18+ 格式导入导出、AES-GCM 256-bit 加密存储。
┌─────────────┐ ┌──────────────┐ ┌────────────────┐
│ View │ → │ ViewModel │ → │ Server Action │
│ (React) │ │ (hooks) │ │ (use server) │
└─────────────┘ └──────────────┘ └───────┬────────┘
│
┌──────────▼──────────┐
│ ScopedDB (D1) │
│ per-user isolation │
└─────────────────────┘
- OTP 引擎 — TOTP/HOTP 生成，支持 SHA-1/256/512 算法，6/8 位验证码，纯 Web Crypto API 实现
- 密钥管理 — CRUD + 批量导入（≤100 条）+ 重复检测
- 加密存储 — AES-GCM 256-bit 加密，格式
v1:<iv>:<ciphertext>，支持按账户独立加密 - 导入导出 — 18+ 导入格式，17+ 导出格式（Aegis, andOTP, 2FAS, Bitwarden, Google Authenticator 等）
- 备份系统 — 事件驱动（5 分钟防抖）+ 定时任务（每日 UTC 16:00，hash 去重），保留最近 100 份
- PWA — Service Worker (Serwist)，离线队列 (IndexedDB)，Background Sync，协议处理器 (
web+otpauth://) - 限流 — 滑动窗口 + 固定窗口，5 种预设策略
- Favicon 代理 — 瀑布式查询 4 个来源（兼容 Google 不可用的地区）
- 认证 — NextAuth v5 + Google OAuth，
ALLOWED_EMAILS白名单 - 国际化 — 英文 / 简体中文，客户端切换
- QR 编解码 — 二维码编码与解码
- Base32 编解码 — Base32 编码与解码
- 密钥强度检查 — 评估 OTP 密钥安全性
- 随机密钥生成 — 生成符合规范的随机密钥
- TOTP 时间步可视化 — 实时展示 TOTP 时间步进度
# 克隆仓库
git clone https://github.com/nocoo/neo.git
cd neo
# 安装依赖
bun install
# 配置环境变量
cp .env.example .env.local
# 启动开发服务器（端口 7026）
bun run dev| 命令 | 说明 |
|---|---|
bun run dev |
启动开发服务器（Turbopack，端口 7026） |
bun run build |
生产构建 |
bun run start |
启动生产服务器 |
bun run lint |
ESLint 检查（--max-warnings=0） |
bun run typecheck |
TypeScript 类型检查（tsc --noEmit） |
bun run test:run |
运行全部 Vitest 测试 |
bun run test:unit |
仅单元测试 |
bun run test:unit:coverage |
单元测试 + 覆盖率报告 |
bun run test:api |
API E2E 测试 |
bun run test:e2e:pw |
Playwright E2E 测试 |
bun run test:security |
安全扫描（osv-scanner + gitleaks） |
neo/
├── actions/ # Server Actions（secrets, backup, settings, dashboard）
├── app/ # Next.js App Router 页面和 API 路由
├── components/ # React 组件（视图 + UI 基础组件）
├── contexts/ # React Context providers
├── hooks/ # 自定义 React hooks
├── i18n/ # 国际化（en, zh-CN）
├── lib/ # 核心库（db, auth, PWA, logger）
├── models/ # 领域模型、类型和常量
├── viewmodels/ # ViewModel hooks（业务逻辑桥接层）
├── worker/ # Cloudflare Worker 边缘任务
├── tests/ # Vitest + Playwright 测试套件
├── drizzle/ # 数据库迁移文件
├── docs/ # 项目文档
└── scripts/ # 构建与工具脚本
| 层 | 技术 |
|---|---|
| 框架 | Next.js 15 (App Router, Turbopack) |
| 运行时 | Bun |
| UI | React 19 + shadcn/ui + Tailwind CSS 3 |
| 数据库 | Cloudflare D1 (HTTP API) + Drizzle ORM |
| 认证 | NextAuth v5 + Google OAuth |
| PWA | Serwist 9 |
| Worker | Cloudflare Workers（Quick OTP, Favicon, Cron） |
| 测试 | Vitest 4 (976 tests) + Playwright (40 E2E specs) |
- Bun >= 1.0
- Cloudflare D1 数据库（HTTP API 访问）
- Google OAuth 凭证
bun install
bun run dev| 变量 | 说明 |
|---|---|
AUTH_SECRET |
NextAuth 签名密钥 |
AUTH_GOOGLE_ID |
Google OAuth Client ID |
AUTH_GOOGLE_SECRET |
Google OAuth Client Secret |
AUTH_URL |
应用 URL |
ALLOWED_EMAILS |
逗号分隔的允许邮箱列表 |
CF_API_TOKEN |
Cloudflare API Token |
CF_ACCOUNT_ID |
Cloudflare Account ID |
CF_D1_DATABASE_ID |
D1 数据库 ID |
ENCRYPTION_KEY |
AES-GCM 256-bit 密钥（可选） |
SENTRY_DSN |
Sentry 错误追踪（可选） |
项目包含多阶段 Dockerfile，针对 Railway 优化：
docker build -t neo .
docker run -p 7026:7026 --env-file .env neo边缘 Worker 独立处理轻量任务：
cd worker
bun install
bun run dev # 本地开发（端口 8787）
bun run deploy # 部署到 Cloudflare六维质量体系（L1+L2+L3+G1+G2+D1），详见 docs/04-quality-system-upgrade.md。
| 维度 | 工具 | Hook | 状态 |
|---|---|---|---|
| L1 单元/组件 | Vitest（925 tests，95%+ 覆盖率） | pre-commit | ✅ |
| L2 集成/API | Vitest（51 API E2E tests） | pre-push | ✅ |
| L3 系统/E2E | Playwright（40 specs） | manual/CI | ✅ |
| G1 静态分析 | tsc --noEmit + ESLint --max-warnings=0 |
pre-commit | ✅ |
| G2 安全 | osv-scanner + gitleaks | pre-push | ✅ |
| D1 测试隔离 | neo-db-test（Cloudflare D1） |
— | N/A |
Tier: S — 全维度绿灯（N/A 视为绿灯）。
bun run test:run # L1 + L2 全部测试
bun run test:e2e:pw # L3 Playwright E2E
bun run lint && bun run typecheck # G1 静态分析
bun run test:security # G2 安全扫描| # | 文档 | 说明 |
|---|---|---|
| 01 | Modernization Plan | 现代化改造：目标、架构、测试策略、提交计划 |
| 02 | Backup Consolidation | 四套备份子系统统一为加密归档 → Backy webhook 流程 |
| 03 | Test Coverage Improvement | 测试基础设施升级至四层标准 |
| 04 | Quality System Upgrade | 四层测试 → 六维质量体系（L1/L2/L3+G1/G2+D1） |
| 05 | Quality System V2 Upgrade | 重审计：L2 mock→真实 HTTP + D1 三层验证 |
MIT © 2026