2FAuth项目Docker容器化部署指南
2025-07-10 05:44:59作者：羿妍玫Ivan
项目概述
2FAuth是一款开源的二步验证(2FA)管理工具，可以帮助用户安全地存储和管理各类二步验证令牌。本文将详细介绍如何使用Docker容器化部署2FAuth应用。
容器特性
- 轻量级镜像：基于Alpine Linux构建的轻量级Docker镜像
- 多架构支持：兼容amd64、386、arm64、arm/v6和arm/v7多种CPU架构
- 安全运行：默认以非root用户(UID 1000)运行，提高安全性
- 数据持久化：使用SQLite数据库文件存储数据
部署准备
环境要求
- 已安装Docker引擎
- 主机上预留8000端口
目录准备
- 创建数据存储目录：
mkdir 2fauth
- 对于非Windows系统，需要设置正确的权限：
chown 1000:1000 2fauth
chmod 700 2fauth
容器运行
基础运行命令
docker run -it --rm -p 8000:8000/tcp \
-v /yourpath/2fauth:/2fauth 2fauth/2fauth \
-e AUTHENTICATION_GUARD=web-guard
参数说明：
-p 8000:8000/tcp：映射容器8000端口到主机-v /yourpath/2fauth:/2fauth：挂载数据目录-e AUTHENTICATION_GUARD=web-guard：解决认证问题
后台运行模式
将-it --rm替换为-d即可让容器在后台运行：
docker run -d -p 8000:8000/tcp \
-v /yourpath/2fauth:/2fauth 2fauth/2fauth
数据迁移
如果已有SQLite数据库文件，将其放置到挂载目录并设置权限：
mv your_database.sqlite /yourpath/2fauth/database.sqlite
chown 1000:1000 /yourpath/2fauth/database.sqlite
chmod 700 /yourpath/2fauth/database.sqlite
容器更新
- 首先备份数据库文件
- 拉取最新镜像：
docker pull 2fauth/2fauth
- 重启容器
自定义镜像构建
基础构建命令
docker build -t 2fauth/2fauth <仓库地址>
构建特定版本
docker build -t 2fauth/2fauth <仓库地址>#v3.0.0
自定义构建参数
支持以下构建参数：
| 参数名 | 默认值 | 说明 |
|---|---|---|
| UID | 1000 | 运行用户UID |
| GID | 1000 | 运行用户GID |
| PHP_VERSION | 8.2-buster | PHP版本 |
| COMPOSER_VERSION | 2.7 | Composer版本 |
示例：
docker build --build-arg UID=1001 --build-arg GID=1001 -t 2fauth/2fauth .
邮件配置
如需配置邮件功能，可使用以下环境变量：
-e MAIL_MAILER=SMTP \
-e MAIL_HOST=smtp.example.com \
-e MAIL_PORT=587 \
-e MAIL_USERNAME=your_email@example.com \
-e MAIL_PASSWORD=your_password \
-e MAIL_ENCRYPTION=TLS \
-e MAIL_FROM_NAME="2FAuth" \
-e MAIL_FROM_ADDRESS=your_email@example.com
技术实现细节
- 基础镜像：基于alpine:3.14构建，保持轻量
- 进程管理：使用进程管理器管理Nginx和PHP-FPM进程
- 目录结构：
/srv：存放应用代码/2fauth：用户数据目录
- 日志系统：
- Nginx和PHP-FPM日志输出到容器日志
- 应用日志存储在
/2fauth/storage/logs
最佳实践建议
- 定期备份
database.sqlite文件 - 生产环境建议使用后台运行模式(-d)
- 考虑使用docker-compose进行多容器管理
- 敏感配置(如邮件密码)建议使用Docker secrets管理
通过以上步骤，您可以轻松地在Docker环境中部署和管理2FAuth应用，享受安全便捷的二步验证管理服务。
