搬瓦工 VPS 部署 2FAuth 教程：Docker 自托管二步验证管理器

2FAuth 是一款可以自托管的二步验证（2FA）管理工具，基于 PHP Laravel 开发，可以把验证码数据保存在自己的 VPS 或服务器中，并通过 Web 页面访问。和常见手机验证器 App 相比，2FAuth 的主要区别是数据由自己管理，迁移、备份和跨设备访问都可以放在自己的服务器环境中完成。

本文使用搬瓦工 VPS 的 Debian 12 系统，通过 Docker 和 Docker Compose 部署 2FAuth。部署过程中要处理好 data 目录权限、APP_KEY、SQLite 数据库持久化和后续访问安全，否则容易遇到 Permission denied、500 错误或数据无法保存的问题。

2FAuth 保存的是二步验证密钥，不建议长期使用公网 HTTP 地址访问。文中的 http://服务器IP:8000 只用于安装和测试，准备正式使用前，建议绑定域名并配置 HTTPS。

一、准备工作与系统检查

本次测试环境如下：

• VPS：搬瓦工 VPS
• 系统：Debian GNU/Linux 12 bookworm
• 架构：x86_64
• 部署方式：Docker Compose
• 访问端口：8000

登录 SSH 后，先确认系统版本和 CPU 架构：

cat /etc/os-release
uname -m
apt update

如果系统显示 Debian 12，架构显示 x86_64，并且 apt update 可以正常读取软件源，就可以继续安装 Docker。

通过 SSH 查看搬瓦工 VPS 系统版本、架构，并确认 Debian 12 软件源可正常更新。

如果系统提示有软件包可以升级，可以先执行：

apt upgrade -y

如果升级过程中更新了 Linux 内核，建议重启一次 VPS：

reboot

重新登录 SSH 后，可以查看当前内核版本：

uname -r

二、安装 Docker 和 Docker Compose

先安装添加 Docker 官方软件源需要用到的基础组件：

apt install -y ca-certificates curl gnupg

然后创建 keyrings 目录，并下载 Docker GPG key：

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

继续添加 Docker 官方 Debian 软件源：

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" > /etc/apt/sources.list.d/docker.list
apt update

如果输出中出现 download.docker.com/linux/debian bookworm，说明 Docker 软件源已经添加成功。

接着安装 Docker Engine 和 Docker Compose 插件：

apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

安装完成后，分别检查 Docker 和 Docker Compose 版本：

docker --version
docker compose version

命令输出如下：

Docker version 29.5.3, build d1c06ef
Docker Compose version v5.1.4

在搬瓦工 VPS 上检查 Docker 与 Docker Compose 版本，确认后续可用 Docker Compose 部署 2FAuth。

再检查 Docker 服务是否正在运行：

systemctl is-active docker

如果返回：

active

说明 Docker 服务已经启动。也可以使用下面的命令查看完整状态：

systemctl status docker --no-pager

检查 Docker 服务状态，确认 Docker 已启动并设置为开机自启。

Docker 和 Docker Compose 安装完成后，这台 VPS 后续也可以继续部署其他自托管应用。如果你还想搭建自动化工作流，可以参考 搬瓦工 VPS 部署 n8n 教程，用同类 Docker 环境接入 DeepSeek 和 n8n。

三、创建 2FAuth 数据目录并设置权限

2FAuth 的 Docker 容器内部使用 UID/GID 为 1000:1000 的用户运行。如果宿主机数据目录由 root 创建但没有修改权限，容器可能无法写入 SQLite 数据库，后续就容易遇到权限报错或容器反复重启。

先创建 2FAuth 项目目录和数据目录：

mkdir -p /root/data/docker_data/2fauth/data
cd /root/data/docker_data/2fauth
pwd
ls -ld /root/data/docker_data/2fauth /root/data/docker_data/2fauth/data

刚创建完成时，目录通常属于 root root：

drwxr-xr-x 3 root root 4096 ... /root/data/docker_data/2fauth
drwxr-xr-x 2 root root 4096 ... /root/data/docker_data/2fauth/data

创建 2FAuth 数据目录后查看权限，确认 data 目录初始归属为 root root。

接着把 data 目录的所有权改成 1000:1000：

chown -R 1000:1000 /root/data/docker_data/2fauth/data
ls -ldn /root/data/docker_data/2fauth/data

看到类似下面的结果，说明权限已经处理完成：

drwxr-xr-x 2 1000 1000 4096 ... /root/data/docker_data/2fauth/data

将 2FAuth 的 data 目录所有权改为 1000:1000，确保容器可以写入数据库文件。

四、配置 .env 环境变量和 APP_KEY

2FAuth 运行前需要配置 APP_KEY。这个值用于 Laravel 应用加密，不能公开展示，也不要发给他人。

下面这组命令会自动生成新的 APP_KEY，并写入 .env 文件。执行时会提示输入服务器公网 IP，输入你的搬瓦工 VPS IP 后回车即可。

cd /root/data/docker_data/2fauth

APP_KEY=$(docker run --rm --entrypoint /usr/bin/php 2fauth/2fauth:latest artisan key:generate --show)

read -p "请输入服务器公网IP: " SERVER_IP

cat > .env <<EOF
APP_NAME=2FAuth
APP_ENV=production
APP_DEBUG=false
APP_URL=http://${SERVER_IP}:8000
APP_KEY=${APP_KEY}
DB_CONNECTION=sqlite
EOF

chmod 600 .env

grep -E '^(APP_NAME|APP_ENV|APP_DEBUG|APP_URL|DB_CONNECTION)=' .env
grep '^APP_KEY=base64:' .env >/dev/null && echo "APP_KEY 已写入 .env"

命令执行完成后，正常情况下会看到类似下面的输出：

APP_NAME=2FAuth
APP_ENV=production
APP_DEBUG=false
APP_URL=http://你的服务器IP:8000
DB_CONNECTION=sqlite
APP_KEY 已写入 .env

创建 2FAuth 的 .env 配置文件，并确认 APP_KEY 已成功写入。

五、编写 docker-compose.yml 配置文件

继续在 /root/data/docker_data/2fauth 目录下创建 Docker Compose 配置文件：

cd /root/data/docker_data/2fauth

cat > docker-compose.yml <<'EOF'
services:
  2fauth:
    image: 2fauth/2fauth:latest
    container_name: 2fauth
    restart: unless-stopped
    ports:
      - "8000:8000"
    env_file:
      - .env
    volumes:
      - ./data:/2fauth
EOF

cat docker-compose.yml

这里的关键配置是：

• ports：把宿主机的 8000 端口映射到容器 8000 端口。
• env_file：读取当前目录下的 .env 配置文件。
• volumes：把宿主机 ./data 目录挂载到容器内 /2fauth。

创建 2FAuth 的 docker-compose.yml 文件，配置容器名称、端口映射、环境变量文件和数据目录挂载。

启动前可以再检查一下当前目录结构和权限：

cd /root/data/docker_data/2fauth
ls -la
ls -ldn data

正常情况下，应能看到 .env、docker-compose.yml 和 data 目录，其中 .env 权限为 600，data 目录归属为 1000:1000。

六、启动 2FAuth Docker 容器

确认配置文件和目录权限没有问题后，启动 2FAuth：

docker compose up -d

如果输出类似下面这样，说明容器已经创建并启动：

[+] up 2/2
 ✔ Network 2fauth_default Created
 ✔ Container 2fauth       Started

执行 docker compose up -d 后，2FAuth 网络创建完成，容器成功启动。

接着查看容器运行状态：

docker compose ps

正常情况下，可以看到 2fauth 容器处于 Up 状态，并且端口已经映射：

0.0.0.0:8000->8000/tcp

检查 2FAuth 容器状态，确认容器已启动并监听 8000 端口。

七、检查 2FAuth 初始化状态和数据库文件

容器启动后，先查看应用初始化日志，确认数据库是否创建成功：

docker compose logs --tail=120 2fauth

如果日志中出现下面这些内容，说明 2FAuth 已经完成数据库初始化：

/2fauth/database.sqlite does not exist, we create it
INFO  Preparing database.
INFO  Running migrations.
create_users_table ... DONE
create_options_table ... DONE
create_twofaccounts_table ... DONE
INFO  Encryption keys generated successfully.

日志里如果出现 Client secret，不用复制或保存这类内容。确认 Running migrations 和多项 DONE 后，继续检查宿主机 data 目录是否已经生成数据库文件：

cd /root/data/docker_data/2fauth
ls -la data

正常情况下，可以看到：

database.sqlite
installed
storage

其中 database.sqlite 是 2FAuth 的 SQLite 数据库文件，后续备份时需要重点备份它。

检查 2FAuth 的 data 目录，确认 database.sqlite 已生成并持久化保存。

八、访问 2FAuth 登录页面

先在 VPS 内部测试 2FAuth 是否有响应：

curl -I http://127.0.0.1:8000

如果返回：

HTTP/1.1 200 OK

说明 2FAuth 的 Web 服务已经正常响应。

这条命令的输出中可能包含 Set-Cookie。这是临时会话信息，看到 HTTP/1.1 200 OK 就可以继续下一步。

然后在浏览器中访问：

http://你的服务器IP:8000

如果能看到 2FAuth 登录页面，说明部署已经完成。页面底部有 Register 注册入口，可以注册第一个账号。

浏览器访问服务器 8000 端口后，成功打开 2FAuth 登录页面。

九、安全与备份建议

2FAuth 保存的是二步验证密钥，部署成功后不要只停留在“能打开页面”。

如果准备长期使用 2FAuth，建议先把 VPS 的基础安全做好，包括 SSH 密钥登录、防火墙规则和异常登录防护。相关操作可以参考 搬瓦工 VPS 安全加固教程，先把服务器入口保护好，再继续保存二步验证密钥。

准备长期使用前，建议处理下面几件事：

• 不要长期使用 HTTP 裸 IP 访问，建议绑定域名并配置 HTTPS。
• 如果后续改成域名和 HTTPS 访问，需要同步修改 .env 里的 APP_URL，然后重启容器。
• 不要公开 .env 文件内容，尤其是 APP_KEY。
• 不要把 Client secret、Set-Cookie、账号邮箱、恢复码或二维码发给他人。
• 定期备份 /root/data/docker_data/2fauth/data/database.sqlite。
• 不要随意修改 APP_KEY，否则可能导致原有加密数据无法读取。

除了备份 database.sqlite，VPS 本身也建议保留快照或灾难恢复方案。2FAuth 这类服务一旦丢失数据库，恢复成本会很高，可以参考 搬瓦工 VM 数据保险教程，提前规划快照、备份和故障恢复流程。

如果后续需要停止 2FAuth，可以在项目目录执行：

cd /root/data/docker_data/2fauth
docker compose down

如果需要重新启动：

cd /root/data/docker_data/2fauth
docker compose up -d

如果需要查看运行状态：

cd /root/data/docker_data/2fauth
docker compose ps

如果需要查看日志：

cd /root/data/docker_data/2fauth
docker compose logs --tail=120 2fauth

十、总结

到这里，2FAuth 已经可以在搬瓦工 VPS 上正常运行。教程使用 Debian 12 系统，先安装 Docker 和 Docker Compose，再创建 2FAuth 数据目录，提前把 data 目录权限改为 1000:1000，然后创建 .env 和 docker-compose.yml 文件，最后启动容器并检查日志、数据库文件和浏览器访问结果。

部署 2FAuth 时，最容易出问题的是目录权限和数据持久化。只要 data 目录权限正确，database.sqlite 能正常生成到宿主机目录，后续重启容器或更新镜像时，2FAuth 的数据就不会因为容器删除而丢失。

部署完成后，http://服务器IP:8000 可以用于测试访问。准备长期保存二步验证密钥时，建议先配置 HTTPS，再注册账号和导入验证码。