Bandwagong伺服器部署2FAuth

2FAuth 是一款由 PHP (Laravel) 編寫的自託管二步驗證（2FA）管理工具。相比 Google Authenticator，它最大的優勢在於數據完全掌握在自己手中，且支持 Web 端跨設備訪問。

⚠️ 注意：該項目對文件權限和路徑映射非常敏感。網上的舊教程（包括部分官方文檔示例）容易導致 Permission denied 或 500 Server Error。

0. 環境準備

• 伺服器系統：Debian 11/12 或 Ubuntu 20.04+
• 核心組件：Docker & Docker Compose

如果你是新拿到手的 VPS，請先執行下面的一鍵命令安裝 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並使用反向代理和遠程桌面加速