2FAuth 8.0.3 配置参数详解
2FAuth 8.0.3 配置参数详解：.env 模板逐参数精讲，覆盖应用核心、日志缓存、四种数据库、邮件、API 限流、认证守卫与反向代理、WebAuthn/SSO、安全开关、用户偏好强制锁定及 Docker secrets 注入，含实测生效验证方法。
2FAuth 8.0.3 配置参数详解
本文是 2FAuth 专栏的配置篇。参数清单、默认值与取值语义均于 2026-10-24 从 8.0.3 官方 .env 模板与官方文档实查取得；核心参数行为在实测环境中逐项验证。文件组织与落地方式见《2FAuth 8.0.3 Docker Compose 部署指南》，本文只讲「每个参数是什么、怎么填、填错会怎样」。
一、配置模型总览
2FAuth 的全部服务端配置收敛在一个 .env 文件（部署篇中的 settings.env），由 Laravel dotenv 机制加载，官方文档站提供同名参考页（getting-started/config/env-vars）。三点全局规则先立此存照：
- 生效方式：修改
.env后重启应用进程生效，无热加载； - 特殊字面量：模板中大量参数写作
null——这是字符串「null」而非空值语义，表示「未启用/使用内置默认」，照抄即可，不要改成真的留空； - APP_ENV 语义：留
local即可；改production后多数控制台命令会追加二次确认；官方在模板中明文警告 Never set it to "testing"（绝不能设为 testing）。
另一类特殊参数是用户偏好的强制与锁定：以 USERPREF_ 前缀的环境变量可以把应用内用户设置统一覆盖（USERPREF_DEFAULT__*）或彻底锁死（USERPREF_LOCKED__*），详见第九节。
二、应用核心参数（APP_*）
| 参数 | 默认 | 说明 |
|---|---|---|
| APP_NAME | 2FAuth | 应用名称，影响界面标题；也是 WEBAUTHN_NAME 留空时的兜底值 |
| APP_ENV | local | 运行环境；production 使控制台命令要求确认；禁用 testing |
| APP_TIMEZONE | UTC | 全局时区，写入数据库的时间基准；运行中修改不会回写存量记录；用户可在应用内设置里覆盖个人时区 |
| APP_DEBUG | false | 错误页调试开关；生产必须 false，否则报错页泄露环境细节 |
| SITE_OWNER | mail@example.com | 管理员邮箱，填你自己的 |
| APP_KEY | 空 | 必设。数据库与会话的加密根键，精确 32 字符（base64: 前缀格式）；留空时 2fauth:install 或 key:generate 向导会代生成；换钥时旧钥必须移入 APP_PREVIOUS_KEYS，否则存量密文与访问令牌解不开 |
| APP_PREVIOUS_KEYS | 注释 | 历史密钥列表，轮换 APP_KEY 时承接旧钥 |
| APP_URL | http://localhost | 外部访问地址，必须与实际访问地址一致；WebAuthn 依赖它，错配即注册/登录失败 |
| APP_SUBDIRECTORY | 空 | 子路径部署：APP_URL=https://mydomain.org/2fa 时填 2fa；根路径部署留空 |
| ASSET_URL | 注释 | 静态资源走 CDN 时设置 CDN 地址 |
| IS_DEMO_APP | false | 演示模式：每小时重置全部内容并挂一个通用演示用户；生产环境严禁开启 |
| BROADCAST_DRIVER / QUEUE_DRIVER / REDIS_* / PUSHER_* / MIX_ENV | log/sync/… | 底层框架参数，官方模板标注「保持原样，除非你清楚自己在做什么」 |
实测提醒：APP_KEY 与 APP_URL 是部署事故率最高的两个参数——前者错了表现为会话异常/密文不可解，后者错了表现为 WebAuthn 全挂，两者都在部署篇排障节有对应案例。
三、日志与缓存
- LOG_CHANNEL（默认
daily）：日志落/storage/logs/，daily 模式保留 7 份按日轮转文件；可选errorlog、syslog、stderr、papertrail、slack，以及可组合多通道的stack； - LOG_LEVEL（默认
notice）：从轻到重debug, info, notice, warning, error, critical, alert, emergency；官方注释很直白——debug 会让日志又大又快，emergency 大概率什么都不记； - CACHE_DRIVER / SESSION_DRIVER（默认
file）：单机够用；追求性能官方点名可装 memcached；模板同时预留了 REDIS_HOST/REDIS_PASSWORD/REDIS_PORT（默认 127.0.0.1/null/6379）。
四、数据库参数（DB_*）
DB_CONNECTION 四选一：mysql | pgsql | sqlsrv | sqlite。官方模板给出三套示例：
# MySQL
DB_CONNECTION=mysql
DB_DATABASE=my_2fauth_DB_name
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USERNAME=my_2fauth_db_user
DB_PASSWORD=My_d8_S3cr3t
# SQLite（Linux）
DB_CONNECTION=sqlite
DB_DATABASE="path/to/your/database.sqlite"
# SQLite（Windows）
DB_CONNECTION=sqlite
DB_DATABASE="C:\\path\\to\\your\\database.sqlite"
实测环境为 MySQL 8.0：库名/用户名 2fauth，主机填数据库服务地址，口令独立强口令。官方镜像默认形态其实是 SQLite（零配置单文件，随 ./2fauth 数据目录一起备份）；SQLite 文件换成存量文件时注意属主与权限要匹配运行身份（官方要求 1000:1000）。
- MYSQL_ATTR_SSL_CA（空）：经 SSL 连接 MySQL 时指向根 CA 证书绝对路径，云数据库场景常用。
五、邮件参数（MAIL_*）
默认 MAIL_MAILER=log——邮件只写日志不外发，纯本地验证器场景够用。启用找回密码等邮件功能时切换 smtp 并填齐：MAIL_HOST/MAIL_PORT/MAIL_USERNAME/MAIL_PASSWORD/MAIL_ENCRYPTION/MAIL_FROM_NAME/MAIL_FROM_ADDRESS，官方要求每个可用设置都设值以避免异常。
- MAIL_VERIFY_SSL_PEER（默认
true）：SMTP 对端证书校验；官方 WARNING 原文——关掉是重大安全缺陷，除非你知道自己在做什么。
六、API 与限流
| 参数 | 默认 | 说明 |
|---|---|---|
| THROTTLE_API | 60 | 每 IP 每分钟 API 调用上限，触顶后该 IP 拒绝至分钟窗口翻页；设 null 关闭限流 |
| THROTTLE_API_DURING_IMPORT | 1000 | 导入功能专用的每分钟限额；THROTTLE_API 为 null 时此项无效 |
| LOGIN_THROTTLE | 5 | 每 IP 每分钟登录失败上限，触顶锁定至窗口结束；同时约束密码登录与 WebAuthn 登录 |
三个限流都是暴力破解/资源滥用的第一道闸，公网部署不建议放宽，加固取值见《2FAuth 8.0.3 安全加固指南》。
七、认证守卫与反向代理
- AUTHENTICATION_GUARD（默认
web-guard）：web-guard走 Laravel 内置认证；reverse-proxy-guard用于反向代理统一认证场景。官方 WARNING：代理守卫下 2FAuth 只认代理头、跳过一切内置认证检查——代理全权负责认证，头在即放行，所以代理侧必须配置严实； - AUTH_PROXY_HEADER_FOR_USER / AUTH_PROXY_HEADER_FOR_EMAIL（默认 null）：代理传递身份的头名（如
REMOTE_USER、REMOTE_EMAIL），仅 reverse-proxy-guard 时生效，名字以你的代理文档为准； - PROXY_LOGOUT_URL（默认 null）：代理认证下的自定义登出跳转地址；
- AUTHENTICATION_LOG_RETENTION（默认 365）：认证日志保留天数，超龄自动删除；
- OTP_LOG_RETENTION（默认 365）：OTP 生成日志保留天数，同上；
- TRUSTED_PROXIES（默认 null）：可信代理声明，
*信任任意代理，或逗号分隔的代理 IP 列表；不设时反代后看到的客户端 IP 全是代理地址，限流会误伤全体用户； - PROXY_FOR_OUTGOING_REQUESTS（默认 null）：出站请求（新版本检测、图标抓取）走代理，支持
http://username:password@192.168.16.1:10形式。
八、WebAuthn 与 SSO
WebAuthn（硬件安全密钥/平台认证器登录）
| 参数 | 默认 | 说明 |
|---|---|---|
| WEBAUTHN_NAME | 2FAuth | Relying Party 名称（即应用名）；留空回落 APP_NAME；官方注记勿设为 null |
| WEBAUTHN_ID | null | Relying Party ID，应等于站点域名（如 2fauth.example.com）；官方推荐保持 null 由设备内部推导 |
| WEBAUTHN_USER_VERIFICATION | preferred | 用户校验强度：required 永远要求（PIN/生物识别）；preferred 能验则验；discouraged 不要求（换取流畅） |
| WEBAUTHN_ICON | 已废弃 | 官方标注 [DEPRECATED]，不要再配 |
SSO（Socialite）：按需取消注释启用 OAuth 提供商——
- OpenID：
OPENID_AUTHORIZE_URL、OPENID_TOKEN_URL、OPENID_USERINFO_URL、OPENID_CLIENT_ID、OPENID_CLIENT_SECRET、OPENID_HTTP_VERIFY_SSL_PEER（true/false，也可填自签证书路径如 /path/to/cert.pem）； - GitHub：
GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET。
SSO 与注册管控组合可实现「仅 SSO 登录、关闭自助注册」的准入模型，属加固动作，配置联动见加固篇。
九、安全开关与用户偏好管控
三个出厂即开的安全开关（实测环境保持默认开启）：
- CONTENT_SECURITY_POLICY=true：启用内容安全策略，防 XSS 注入；
- BLOCK_OPTAUTH_IMAGELINK_FETCHING=true：禁止抓取 otpauth URI 中引用的图片资源，防盲 SSRF（应用被诱导向攻击者指定的 URL 发起后端请求）；
- PHP_MEMORY_LIMIT_TEMP_OVERRIDE=512：二维码识别是内存大户，此值仅在识别过程临时抬高内存上限（防
Allowed memory size exhausted），不影响其他处理的 PHP.ini 设定。
用户偏好强制/锁定（USERPREF_ 前缀）：
# 示例：全员默认浅色主题，并锁死不可改
USERPREF_DEFAULT__THEME=light
USERPREF_LOCKED__THEME=true
命名规则 USERPREF_DEFAULT__<键>（统一默认值）与 USERPREF_LOCKED__<键>（锁定不可改），可管控键的完整清单见官方文档 getting-started/config/user-preferences 页。多用户团队统一体验/关掉个性化入口时用。
十、Docker secrets：敏感参数 _FILE 注入
自 v6.0 起，敏感数据可用 Docker secrets 以 _FILE 后缀变量注入，运行时自动读入对应普通变量。官方支持的变量集：
APP_KEY_FILE、DB_DATABASE_FILE、DB_USERNAME_FILE、DB_PASSWORD_FILE、
DB_HOST_FILE、MAIL_USERNAME_FILE、MAIL_PASSWORD_FILE、REDIS_PASSWORD_FILE
官方 compose 用法摘录（secrets 以文件形式挂给服务，变量指向挂载路径）：
services:
2fauth:
environment:
APP_KEY_FILE: /run/secrets/app_key
secrets:
- app_key
secrets:
app_key:
file: ./app_key.txt
硬性互斥规则：同一参数的普通变量与 _FILE 版本只能设一个（如 APP_KEY 与 APP_KEY_FILE 同时存在，运行时直接报错）。密钥轮换、反代 TLS、注册管控等安全动作的完整清单收敛在加固篇。
十一、改完如何验证生效
实测流程三步：改 settings.env → 重启应用进程 → 探活 GET /up 返回 2FAuth up。分类预期：
- 时区/日志级/限流类：行为观察（日志文件名、触发限流后的 429）；
- APP_URL/子路径类：浏览器实际访问核对；
- APP_KEY 类：高危操作，务必先把旧钥写入 APP_PREVIOUS_KEYS，再验证历史账户验证码与登录令牌仍可用；
- USERPREF 锁定类：换一个普通用户账号确认偏好被锁。
十二、延伸阅读
- 部署落地与排障：《2FAuth 8.0.3 Docker Compose 部署指南》
- 安全参数的加固组合拳：《2FAuth 8.0.3 安全加固指南》
- 组件定位与同类对比：《2FAuth 8.0.3 介绍与选型指南》