搬瓦工 VPS Authelia 双因素认证网关部署教程

Authelia 是一款轻量级的开源认证和授权服务器，专为反向代理场景设计。它可以为 Nginx、Traefik、HAProxy 等反向代理后面的所有 Web 应用提供统一的登录门户和双因素认证（2FA），支持 TOTP（基于时间的一次性密码）和 WebAuthn（硬件安全密钥）。与 Keycloak 相比，Authelia 更轻量，资源占用更少，非常适合个人和小团队使用。

一、Authelia 核心特性

单点登录（SSO）：一次登录即可访问所有受保护的应用。
多因素认证：支持 TOTP、WebAuthn（FIDO2）和 Duo Push。
细粒度访问控制：可按域名、路径、用户组设置不同的认证级别。
密码重置：支持通过邮件重置密码。
会话管理：支持 Cookie 和 Header 两种会话方式。
资源消耗低：通常只需 50-100MB 内存。

二、Docker Compose 部署

2.1 创建项目目录

mkdir -p /opt/authelia/{config,data}
cd /opt/authelia

2.2 生成密钥

# 生成 JWT 密钥
openssl rand -hex 32

# 生成会话密钥
openssl rand -hex 32

# 生成存储加密密钥
openssl rand -hex 32

2.3 创建用户数据库

cat > /opt/authelia/config/users_database.yml <<'EOF'
users:
  admin:
    displayname: "Admin User"
    password: "$argon2id$v=19$m=65536,t=3,p=4$hash_here"
    email: admin@example.com
    groups:
      - admins
      - developers
  user1:
    displayname: "Normal User"
    password: "$argon2id$v=19$m=65536,t=3,p=4$hash_here"
    email: user1@example.com
    groups:
      - users
EOF

使用以下命令生成密码哈希：

docker run --rm authelia/authelia:latest authelia crypto hash generate argon2 --password 'YourPassword123'

2.4 创建 Authelia 配置文件

cat > /opt/authelia/config/configuration.yml <<'EOF'
server:
  address: 'tcp://0.0.0.0:9091'

log:
  level: info

jwt_secret: your_jwt_secret_here

default_redirection_url: https://home.example.com

totp:
  issuer: example.com
  period: 30
  digits: 6

webauthn:
  disable: false
  display_name: Authelia
  attestation_conveyance_preference: indirect
  user_verification: preferred
  timeout: 60s

authentication_backend:
  file:
    path: /config/users_database.yml
    password:
      algorithm: argon2id
      iterations: 3
      memory: 65536
      parallelism: 4
      salt_length: 16

access_control:
  default_policy: deny
  rules:
    - domain: public.example.com
      policy: bypass
    - domain: "*.example.com"
      policy: one_factor
    - domain: admin.example.com
      policy: two_factor
      subject:
        - "group:admins"
    - domain: secure.example.com
      policy: two_factor

session:
  name: authelia_session
  secret: your_session_secret_here
  expiration: 3600
  inactivity: 300
  remember_me: 2592000
  cookies:
    - domain: example.com
      authelia_url: https://auth.example.com

storage:
  encryption_key: your_storage_encryption_key_here
  local:
    path: /data/db.sqlite3

notifier:
  smtp:
    address: 'smtp://smtp.gmail.com:587'
    username: your_email@gmail.com
    password: your_app_password
    sender: "Authelia "
EOF

2.5 Docker Compose 文件

cat > /opt/authelia/docker-compose.yml <<'EOF'
version: '3.8'

services:
  authelia:
    image: authelia/authelia:latest
    container_name: authelia
    restart: always
    ports:
      - "9091:9091"
    volumes:
      - ./config:/config
      - ./data:/data
    environment:
      TZ: Asia/Shanghai
EOF

2.6 启动服务

cd /opt/authelia
docker compose up -d
docker logs -f authelia

三、Nginx 集成配置

3.1 Authelia 认证端点

# /etc/nginx/snippets/authelia-location.conf
location /authelia {
    internal;
    set $upstream_authelia http://127.0.0.1:9091/api/authz/auth-request;
    proxy_pass $upstream_authelia;
    proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
    proxy_set_header X-Forwarded-Method $request_method;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Forwarded-URI $request_uri;
    proxy_set_header Content-Length "";
    proxy_pass_request_body off;
}

3.2 受保护应用的 Nginx 配置

server {
    listen 443 ssl http2;
    server_name app.example.com;

    ssl_certificate /etc/letsencrypt/live/app.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;

    include /etc/nginx/snippets/authelia-location.conf;

    location / {
        auth_request /authelia;
        auth_request_set $target_url $scheme://$http_host$request_uri;
        auth_request_set $user $upstream_http_remote_user;
        auth_request_set $groups $upstream_http_remote_groups;
        auth_request_set $name $upstream_http_remote_name;
        auth_request_set $email $upstream_http_remote_email;
        error_page 401 =302 https://auth.example.com/?rd=$target_url;

        proxy_set_header Remote-User $user;
        proxy_set_header Remote-Groups $groups;
        proxy_set_header Remote-Name $name;
        proxy_set_header Remote-Email $email;

        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

四、访问控制策略说明

bypass：无需认证，直接访问。适合公开页面。
one_factor：仅需用户名和密码。适合普通应用。
two_factor：需要用户名密码加 TOTP 或 WebAuthn。适合敏感应用。
deny：拒绝访问。

五、配置 TOTP 双因素认证

用户首次登录后访问 Authelia 门户页面，在设置中注册 TOTP 设备。扫描二维码后，后续登录需要输入 6 位验证码。推荐使用 Google Authenticator、Authy 或 Bitwarden 的内置 TOTP 功能。

六、故障排查

# 查看 Authelia 日志
docker logs authelia

# 检查配置文件语法
docker run --rm -v /opt/authelia/config:/config authelia/authelia:latest authelia validate-configuration --config /config/configuration.yml

# 测试认证端点
curl -I http://127.0.0.1:9091/api/health

总结

Authelia 是搬瓦工 VPS 上轻量级认证网关的理想选择，资源消耗低但功能齐全。通过合理配置访问控制策略，可以为不同敏感级别的应用设置不同的认证要求。配合 Nginx Proxy Manager 或手动配置 Nginx，即可保护所有 Web 服务。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的折扣，通过 bwh81.net 进入官网购买。