使用Docker Compose部署2FAuth双因素认证系统指南

项目概述

2FAuth是一个开源的二步验证(2FA)管理工具，允许用户集中管理所有双因素认证令牌。本文将详细介绍如何使用Docker Compose快速部署2FAuth系统。

系统要求

在开始部署前，请确保您的系统满足以下要求：

• 已安装Docker和Docker Compose
• 8000端口未被占用
• 至少100MB可用磁盘空间

部署步骤详解

1. 准备docker-compose.yml文件

创建或编辑docker-compose.yml文件，内容如下：

version: "3"
services:
  2fauth:
    image: 2fauth/2fauth
    container_name: 2fauth
    volumes:
      - ./2fauth:/2fauth
    ports:
      - 8000:8000/tcp
    environment:
      - APP_NAME=2FAuth
      - APP_ENV=local
      - APP_TIMEZONE=UTC
      - APP_DEBUG=false
      - SITE_OWNER=mail@example.com
      - APP_KEY=SomeRandomStringOf32CharsExactly
      - APP_URL=http://localhost
      - IS_DEMO_APP=false
      - LOG_CHANNEL=daily
      - LOG_LEVEL=notice
      - DB_DATABASE="/srv/database/database.sqlite"
      - CACHE_DRIVER=file
      - SESSION_DRIVER=file
      - MAIL_MAILER=log
      - THROTTLE_API=60
      - LOGIN_THROTTLE=5
      - AUTHENTICATION_GUARD=web-guard
      - WEBAUTHN_NAME=2FAuth
      - WEBAUTHN_USER_VERIFICATION=preferred

2. 关键配置说明

基础配置

• APP_NAME: 应用显示名称，可根据需要修改
• APP_ENV: 环境设置，生产环境应改为"production"
• APP_KEY: 32位随机字符串，用于加密数据，务必保密

数据库配置

2FAuth默认使用SQLite数据库，数据文件将保存在挂载的卷中：

volumes:
  - ./2fauth:/2fauth

安全配置

• LOGIN_THROTTLE: 每分钟允许的失败登录尝试次数(默认为5次)
• THROTTLE_API: 每分钟允许的API调用次数(默认为60次)
• WEBAUTHN_USER_VERIFICATION: WebAuthn验证级别(preferred为推荐设置)

邮件配置

默认配置为日志记录模式(MAIL_MAILER=log)，如需实际发送邮件，需配置SMTP相关参数：

- MAIL_MAILER=smtp
- MAIL_HOST=your.smtp.server
- MAIL_PORT=587
- MAIL_USERNAME=your_username
- MAIL_PASSWORD=your_password
- MAIL_ENCRYPTION=tls

3. 启动容器

执行以下命令启动服务：

docker-compose up -d

4. 访问系统

服务启动后，可通过以下URL访问：

http://localhost:8000

高级配置选项

WebAuthn配置

WebAuthn是2FAuth支持的现代认证方式，相关配置包括：

• WEBAUTHN_ID: 依赖方ID，通常为域名
• WEBAUTHN_USER_VERIFICATION: 用户验证要求级别

反向代理配置

如需在反向代理后运行，需设置：

- AUTHENTICATION_GUARD=reverse-proxy-guard
- AUTH_PROXY_HEADER_FOR_USER=REMOTE_USER
- AUTH_PROXY_HEADER_FOR_EMAIL=REMOTE_EMAIL

内容安全策略

启用CSP可增强安全性：

- CONTENT_SECURITY_POLICY=true

维护与升级

数据备份

所有数据存储在挂载的卷中，定期备份./2fauth目录即可。

升级版本

1. 停止当前容器
2. 拉取新镜像
3. 重新启动容器

docker-compose down
docker-compose pull
docker-compose up -d

常见问题解决

1. WebAuthn不工作：确保APP_URL配置正确且可访问
2. 性能问题：可考虑将CACHE_DRIVER改为redis
3. 登录问题：检查LOGIN_THROTTLE设置是否过低

通过以上步骤，您应该能够成功部署并配置2FAuth系统，为您的账户安全提供额外的保护层。