# 2fa

**Repository Path**: wjn6/2fa-new

## Basic Information

- **Project Name**: 2fa
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-20
- **Last Updated**: 2025-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 多用户2FA管理系统

一个安全、易用的双因素认证（2FA）管理网页应用，为用户提供集中管理多个账户2FA令牌的解决方案。

## ✨ 主要特性

### 🎯 核心功能
- ✅ **完整的用户系统**：注册、登录、权限管理
- ✅ **2FA令牌管理**：创建、编辑、删除、分类、搜索
- ✅ **TOTP验证码生成**：实时生成6/8位验证码
- ✅ **令牌备注功能**：为每个令牌添加详细说明（最大1000字符）
- ✅ **收藏和排序**：快速访问常用令牌
- ✅ **管理员面板**：用户管理、系统监控、日志审计

### 🔐 安全保障
- 🔒 AES-256端到端加密
- 🔑 PBKDF2密钥派生
- 🛡️ bcrypt密码哈希
- 🔐 JWT认证 + HttpOnly Cookie
- 👁️ 设备指纹识别
- 📝 完整审计日志
- 🚨 登录失败限制和账户锁定

### 📊 管理功能
- 👥 两级权限系统（管理员/用户）
- 📈 系统统计和监控
- 📋 用户管理（禁用、解锁、删除）
- 💬 用户备注（管理员专用）
- 🔍 全局日志查看
- 💾 数据库优化工具

### 🎨 用户体验
- 🌓 深色模式
- 📱 响应式设计
- ⌨️ 键盘快捷键
- 🔍 强大的搜索和筛选
- 📦 批量操作
- 📤 导入导出（支持多种格式）

## 🚀 快速开始

### 前提条件

```bash
Node.js >= 18.0.0
npm >= 9.0.0
SQLite >= 3.35.0
```

### 安装步骤

#### 1. 克隆项目

```bash
git clone https://github.com/yourusername/2fa-manager.git
cd 2fa-manager
```

#### 2. 安装依赖

```bash
# 安装根目录依赖
npm install

# 安装后端依赖
cd backend
npm install

# 安装前端依赖
cd ../frontend
npm install
```

#### 3. 配置环境变量

```bash
# 复制环境变量模板
cd backend
cp env.example .env

# 编辑 .env 文件，至少修改以下配置：
# - JWT_SECRET（生产环境必须修改！）
# - INITIAL_ADMIN_PASSWORD（初始管理员密码）
```

#### 4. 初始化数据库

```bash
cd backend

# 生成Prisma Client
npm run db:generate

# 运行数据库迁移
npm run migrate

# 系统会在首次启动时自动创建初始管理员
# 或者手动创建：
npm run create-admin
```

#### 5. 启动开发服务器

```bash
# 在项目根目录，同时启动前后端
npm run dev

# 或分别启动
# 后端
cd backend && npm run dev

# 前端（新终端）
cd frontend && npm run dev
```

#### 6. 访问应用

```
前端地址: http://localhost:3000
后端API: http://localhost:5000
管理员面板: http://localhost:3000/admin

默认管理员账户：
用户名: admin
邮箱: admin@example.com
密码: ChangeMe123!（请立即修改！）
```

## 📁 项目结构

```
2fa-manager/
├── backend/                 # Node.js 后端
│   ├── prisma/
│   │   └── schema.prisma   # 数据库模型
│   ├── src/
│   │   ├── config/         # 配置文件
│   │   ├── middleware/     # 中间件
│   │   ├── routes/         # API路由
│   │   ├── services/       # 业务逻辑
│   │   ├── utils/          # 工具函数
│   │   └── index.js        # 入口文件
│   ├── scripts/            # 脚本工具
│   └── package.json
│
├── frontend/               # Vue 3 前端
│   ├── src/
│   │   ├── assets/        # 静态资源
│   │   ├── components/    # 组件
│   │   ├── views/         # 页面
│   │   ├── router/        # 路由
│   │   ├── store/         # Pinia状态管理
│   │   ├── api/           # API接口
│   │   └── utils/         # 工具函数
│   └── package.json
│
├── data/                  # SQLite数据库文件
├── backups/              # 备份目录
├── docker-compose.yml
└── README.md
```

## 🔧 常用命令

### 开发

```bash
npm run dev              # 启动开发服务器（前后端）
npm run dev:backend      # 仅启动后端
npm run dev:frontend     # 仅启动前端
```

### 数据库

```bash
npm run migrate          # 运行迁移
npm run db:generate      # 生成Prisma Client
npm run db:studio        # 打开Prisma Studio
npm run db:push          # 推送schema到数据库
```

### 管理

```bash
npm run create-admin     # 创建管理员账户
npm run backup           # 备份数据库
```

### 构建

```bash
npm run build            # 构建生产版本
npm run start            # 启动生产服务器
```

## 🐳 Docker 部署

```bash
# 构建并启动
docker-compose up -d

# 查看日志
docker-compose logs -f

# 创建管理员
docker-compose exec backend npm run create-admin

# 停止服务
docker-compose down
```

## 📖 API 文档

### 认证相关

```
POST   /api/v1/auth/register          # 用户注册
POST   /api/v1/auth/login             # 用户登录
POST   /api/v1/auth/logout            # 用户登出
POST   /api/v1/auth/refresh           # 刷新Token
GET    /api/v1/auth/me                # 获取当前用户
PUT    /api/v1/auth/password          # 修改密码
GET    /api/v1/auth/sessions          # 获取活跃会话
```

### 令牌管理

```
GET    /api/v1/tokens                 # 获取所有令牌
POST   /api/v1/tokens                 # 创建令牌
GET    /api/v1/tokens/:id             # 获取单个令牌
PUT    /api/v1/tokens/:id             # 更新令牌
DELETE /api/v1/tokens/:id             # 删除令牌
POST   /api/v1/tokens/:id/generate    # 生成验证码
GET    /api/v1/tokens/favorites       # 收藏的令牌
GET    /api/v1/tokens/recent          # 最近使用
POST   /api/v1/tokens/batch-delete    # 批量删除
```

### 管理员接口

```
GET    /api/v1/admin/users            # 获取用户列表
GET    /api/v1/admin/users/:id        # 获取用户详情
PUT    /api/v1/admin/users/:id        # 更新用户
DELETE /api/v1/admin/users/:id        # 删除用户
PATCH  /api/v1/admin/users/:id/disable # 禁用用户
GET    /api/v1/admin/stats            # 系统统计
GET    /api/v1/admin/logs             # 审计日志
```

## 🛠️ 技术栈

### 后端
- **框架**: Fastify
- **数据库**: SQLite 3
- **ORM**: Prisma
- **认证**: JWT + bcrypt
- **加密**: AES-256-GCM
- **2FA**: otpauth

### 前端
- **框架**: Vue 3
- **UI库**: TinyVue (OpenTiny)
- **状态管理**: Pinia
- **路由**: Vue Router
- **构建工具**: Vite
- **2FA库**: otpauth

## 🔒 安全最佳实践

### 生产环境部署前

1. ✅ 修改 `JWT_SECRET` 为至少32位随机字符串
2. ✅ 修改初始管理员密码
3. ✅ 启用 HTTPS
4. ✅ 配置防火墙规则
5. ✅ 定期备份数据库
6. ✅ 更新依赖包（`npm audit fix`）
7. ✅ 启用数据库加密（SQLCipher）
8. ✅ 配置日志轮转
9. ✅ 设置监控告警

### 用户使用建议

1. 🔐 使用强密码（至少8位，包含大小写字母和数字）
2. 🔑 启用自己的账户2FA
3. 📝 为重要令牌添加详细备注
4. 💾 定期导出备份
5. 🚨 发现异常登录立即修改密码

## ❓ 常见问题

### 数据库锁定错误

```bash
# 删除WAL文件
rm data/2fa.db-shm
rm data/2fa.db-wal
```

### 忘记管理员密码

```bash
# 重新创建管理员账户
npm run create-admin
```

### 数据库迁移失败

```bash
# 重置数据库（警告：会删除所有数据）
npm run migrate:reset
```

## 📝 开发指南

### Git 提交规范

```
feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式
refactor: 重构
test: 测试
chore: 构建/工具
```

### 代码规范

- 使用 ESLint + Prettier
- 提交前运行 lint 检查
- 编写单元测试
- 添加有意义的注释

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🙏 致谢

- [Fastify](https://fastify.io/) - 高性能Web框架
- [Prisma](https://www.prisma.io/) - 现代化ORM
- [Vue.js](https://vuejs.org/) - 渐进式JavaScript框架
- [TinyVue](https://opentiny.design/) - 企业级UI组件库
- [OTPAuth](https://github.com/hectorm/otpauth) - TOTP/HOTP库

## 📧 联系方式

- 项目地址: https://github.com/yourusername/2fa-manager
- 问题反馈: [GitHub Issues](https://github.com/yourusername/2fa-manager/issues)
- 邮箱: support@example.com

---

**⚠️ 重要提示**: 本系统涉及敏感的认证信息，请务必：
1. 使用强密码
2. 定期备份数据
3. 不要在公共网络环境下使用
4. 生产环境必须启用HTTPS
5. 妥善保管数据库文件

**文档版本**: 1.0  
**最后更新**: 2025-10-27