Bandwagong服务器部署2FAuth

2FAuth 是一款由 PHP (Laravel) 编写的自托管二步验证（2FA）管理工具。相比 Google Authenticator，它最大的优势在于数据完全掌握在自己手中，且支持 Web 端跨设备访问。

注意：该项目对文件权限和路径映射非常敏感。网上的旧教程（包括部分官方文档示例）容易导致 Permission denied 或 500 Server Error。

0. 环境准备

服务器系统：Debian 11/12 或 Ubuntu 20.04+
核心组件：Docker & Docker Compose

如果你的搬瓦工服务器是刚连上SSH客户端的话，请先执行下面的一键命令安装 Docker：

apt update && apt upgrade -y

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo systemctl enable --now docker

执行完上面的命令，再输入systemctl status docker 并回车。

看到Active: active 就说明docker已经成功安装并正在运行中了。

1. 建立目录与解决权限（这里很关键）

这是大部分人失败的原因：Docker 自动创建的目录属于 root 用户，而 2FAuth 容器内部使用 1000 (www-data) 用户，导致没有权限写入数据库。

我们需要先创建目录，并提前授权（四条命令从上到下依次输入）：

# 1. 创建项目根目录
mkdir -p /root/data/docker_data/2fauth

# 2. 创建核心数据目录
mkdir -p /root/data/docker_data/2fauth/data

# 3. 【核心步骤】修改权限
# 将 data 目录的所有权赋予容器内的用户（ID 1000）
# 如果不做这一步，容器会因无法生成数据库文件而无限重启
chown -R 1000:1000 /root/data/docker_data/2fauth/data

# 4. 进入项目目录
cd /root/data/docker_data/2fauth

2. 生成 APP_KEY

Laravel 框架必须有一个 32 位的密钥才能运行。在终端执行以下命令，复制输出的字符串（可以先复制到电脑的记事本上）：

openssl rand -base64 32

输出示例：base64:xgT+...（一长串字符）...=

3. 配置文件编写

我们需要创建两个文件：.env 和 docker-compose.yml。

第一步：创建 .env 文件

这里我们移除了容易引发冲突的数据库路径配置，直接使用容器默认值。

vim .env

粘贴以下内容（请务必替换你的 APP_KEY）：

# --- 基础配置 ---
APP_NAME=2FAuth
APP_ENV=production
APP_DEBUG=false
APP_URL=http://你的服务器IP:8000

# --- 密钥配置 (必须修改) ---
# 将第2步生成的 base64 字符串完整粘贴在这里
APP_KEY=base64:你刚刚生成的密钥

# --- 数据库配置 ---
# 仅保留连接类型，不要手动指定 DB_DATABASE 路径！
# 让容器自动使用默认的 /2fauth/database.sqlite
DB_CONNECTION=sqlite

第二步：创建 docker-compose.yml

vim docker-compose.yml

粘贴以下内容。注意：我们将整个 ./data 挂载到了容器的 /2fauth 目录，这样可以确保存储、日志和数据库都能正确持久化且互不冲突。

version: "3"
services:
  2fauth:
    image: 2fauth/2fauth:latest
    container_name: 2fauth
    restart: unless-stopped
    ports:
      - 8000:8000/tcp
    env_file: .env
    volumes:
      # 【核心修改】直接挂载应用根目录
      # 这样 database.sqlite 会自动生成在宿主机的 ./data 目录下
      - ./data:/2fauth

4. 启动服务

确认当前目录结构如下：

/2fauth
- .env
- docker-compose.yml
- /data (权限已改为 1000:1000)

执行启动命令：

docker compose up -d

5. 验证部署

查看实时日志：

docker compose logs -f

部署成功的标志：你需要耐心等待几秒钟，当你看到日志中出现密密麻麻的 Running migrations，并且包含 create_users_table、create_options_table 等字样，最后停在：

Application key set successfully.

这说明数据库初始化已经完成！

现在，打开浏览器访问 http://你的IP:8000，即可看到登录界面。点击 Register 注册你的第一个账号（自动成为管理员）。

完成后，需要给网站加上HTTPS进行访问的话，可以参考：如何搭建Nginx Proxy Manager并使用反向代理和远程桌面加速

index.php?title=Category:500 常见应用指南 — Application Guides