2FAuth账户管理完全教程：从扫码导入到高级设置配置

【免费下载链接】2FAuth A Web app to manage your Two-Factor Authentication (2FA) accounts and generate their security codes 项目地址: https://gitcode.com/gh_mirrors/2f/2FAuth

2FAuth是一款强大的自托管双因素认证管理工具，让你能够集中管理所有2FA账户并生成安全代码。本教程将为你提供完整的2FAuth使用指南，从基础安装到高级功能配置，帮助你轻松管理双因素认证账户。

🚀 快速安装与部署指南

2FAuth支持多种部署方式，包括Docker、传统服务器安装等。最简单的部署方式是使用Docker Compose：

git clone https://gitcode.com/gh_mirrors/2f/2FAuth
cd 2FAuth
docker-compose up -d

对于传统服务器部署，项目提供了详细的Debian安装指南在docs/debian-setup.md。安装完成后，访问 http://localhost:8000 即可开始使用。

📱 账户导入与管理功能

扫码导入2FA账户

2FAuth最强大的功能之一是支持从多种格式导入2FA账户：

1. Google Authenticator QR码扫描 - 直接扫描应用中的二维码
2. Aegis Auth JSON导入 - 支持完整的Aegis备份文件
3. 2FAS Auth JSON导入 - 兼容2FAS应用的导出格式
4. 纯文本导入 - 手动输入账户信息

导入功能位于app/Services/Migrators/目录，支持多种迁移器：

• GoogleAuthMigrator.php - Google Authenticator迁移
• AegisMigrator.php - Aegis迁移
• TwoFASMigrator.php - 2FAS迁移

手动添加账户

除了扫码导入，你也可以通过高级表单手动添加账户：

1. 输入账户名称和服务商
2. 配置密钥（支持Base32编码）
3. 选择算法（SHA1/SHA256/SHA512）
4. 设置位数（6或8位）
5. 配置时间间隔（TOTP）或计数器（HOTP）

🔐 高级安全功能配置

数据加密保护

2FAuth支持数据库字段级加密，保护敏感数据。加密功能通过app/Models/Traits/CanEncryptField.php特性实现，确保即使数据库被泄露，2FA密钥也不会被轻易解密。

启用加密的方法：

1. 在.env文件中设置 ENCRYPTION_ENABLED=true
2. 备份APP_KEY值（非常重要！）
3. 重启应用使加密生效

WebAuthn无密码认证

2FAuth集成了WebAuthn支持，允许使用安全密钥（如Yubikey）进行登录：

• 安全密钥注册 - 通过app/Http/Controllers/Auth/WebAuthnRegisterController.php处理
• 无密码登录 - 使用app/Http/Controllers/Auth/WebAuthnLoginController.php
• 设备丢失恢复 - 通过app/Http/Controllers/Auth/WebAuthnDeviceLostController.php处理

自动注销机制

为增强安全性，2FAuth提供自动注销功能：

1. 基于不活动的自动注销 - 配置在config/session.php
2. 复制代码后自动注销 - 可在设置中启用
3. 自定义超时时间 - 根据安全需求调整

📊 账户组织与分组管理

创建和管理分组

使用分组功能可以更好地组织你的2FA账户：

// 分组管理位于 app/Http/Controllers/Api/v1/Controllers/GroupController.php
// 分组服务逻辑在 app/Services/GroupService.php

分组功能支持：

• 创建、编辑、删除分组
• 拖拽排序分组
• 批量分配账户到分组
• 分组级别的权限控制

批量操作功能

2FAuth提供强大的批量操作能力：

• 批量导入 - 一次导入多个账户
• 批量导出 - 导出所有或选中的账户
• 批量删除 - 快速清理不需要的账户
• 批量移动 - 将账户移动到不同分组

批量操作API位于app/Api/v1/Controllers/TwoFAccountController.php，支持多种批量请求格式。

⚙️ 高级设置与自定义

OAuth配置

2FAuth支持OAuth 2.0认证，配置位于config/auth.php：

1. 启用OAuth提供者
2. 配置客户端ID和密钥
3. 设置回调URL
4. 管理访问令牌

通知系统配置

系统支持多种通知方式：

• 邮件通知 - 失败登录、新设备登录等
• WebAuthn恢复通知 - 设备丢失时的恢复流程
• 测试邮件设置 - 验证邮件配置是否正确

通知类位于app/Notifications/目录，包括FailedLoginNotification.php和WebauthnRecoveryNotification.php等。

图标管理

2FAuth支持自定义服务图标：

1. 内置图标库 - 预置常用服务图标
2. 自定义图标上传 - 支持上传服务特定图标
3. 图标存储选项 - 可选择存储在数据库或文件系统

图标管理功能在app/Services/IconService.php和app/Services/IconStoreService.php中实现。

🔧 维护与故障排除

数据库维护命令

2FAuth提供多个维护命令：

# 修复服务字段加密
php artisan 2fauth:fix-service-field-encryption

# 清理孤立账户
php artisan 2fauth:fix-orphan-accounts

# 重置演示数据
php artisan 2fauth:reset-demo

# 清理认证日志
php artisan 2fauth:purge-auth-log

性能优化建议

1. 缓存配置 - 使用 php artisan config:cache
2. 路由缓存 - 生产环境启用路由缓存
3. 数据库优化 - 定期清理过期会话和日志
4. 图标存储优化 - 根据使用情况选择存储方式

常见问题解决

Q: 导入QR码失败怎么办？ A: 检查app/Services/QrCodeService.php日志，确保GD库已安装并支持图像处理。

Q: WebAuthn注册失败？ A: 验证config/webauthn.php配置，确保RP ID和来源设置正确。

Q: 加密数据无法解密？ A: 确认APP_KEY与加密时使用的密钥一致，备份文件位于.env。

📈 最佳实践与安全建议

安全配置建议

1. 启用HTTPS - 生产环境必须使用HTTPS
2. 定期备份 - 备份数据库和.env文件
3. 限制访问 - 使用防火墙限制访问IP
4. 监控日志 - 定期检查认证日志

数据备份策略

• 完整备份：数据库 + .env文件 + storage目录
• 增量备份：每日备份新增的2FA账户
• 测试恢复：定期测试备份文件的恢复能力

更新与升级

2FAuth遵循语义化版本控制，升级时注意：

1. 查看changelog.md了解变更
2. 备份当前数据和配置
3. 运行数据库迁移：php artisan migrate
4. 清理缓存：php artisan config:clear

🎯 总结

2FAuth作为一款功能完整的自托管2FA管理工具，提供了从基础账户管理到高级安全配置的全套解决方案。通过本教程，你应该能够：

✅ 成功部署2FAuth实例
✅ 导入和管理所有2FA账户
✅ 配置高级安全功能如WebAuthn
✅ 使用分组优化账户组织
✅ 实施最佳安全实践

无论是个人使用还是小型团队部署，2FAuth都能提供安全可靠的2FA管理体验。开始使用2FAuth，告别手机依赖，享受更便捷的双因素认证管理吧！ 🔐✨

【免费下载链接】2FAuth A Web app to manage your Two-Factor Authentication (2FA) accounts and generate their security codes 项目地址: https://gitcode.com/gh_mirrors/2f/2FAuth