- 后端
- 前端
- 运维
- MCP 服务
【免费下载链接】nginx-ui
Yet another WebUI for Nginx
本指南系统讲解 Nginx UI 从 v2.0.0-beta.26 起引入的auth配置段（见 docs/guide/config-auth.md），涵盖 IP 白名单、可信反向代理、登录失败封禁、TOTP/Passkey 安全会话超时等五个核心配置项。读完本文，你将掌握如何通过app.ini（或环境变量）精确控制访问来源、代理链信任边界与暴力破解防护策略，并结合源码理解每个参数的实际生效链路。
配置段概览
从 v2.0.0-beta.26 开始，Nginx UI 允许在配置文件的auth段集中管理授权与安全相关的设置。对应的数据结构定义在 settings/auth.go：
type Auth struct { IPWhiteList []string `json:"ip_white_list" ...` TrustedProxies []string `json:"trusted_proxies" ...` BanThresholdMinutes int `json:"ban_threshold_minutes" binding:"min=1"` MaxAttempts int `json:"max_attempts" binding:"min=1"` SecureSessionTimeoutMinutes int `json:"secure_session_timeout_minutes" binding:"min=1"` }其中BanThresholdMinutes、MaxAttempts的默认值均为10，SecureSessionTimeoutMinutes默认值同样为10（常量DefaultSecureSessionTimeoutMinutes）。所有配置项均可在配置文件中写入，也可通过对应的 JSON 键经由 API 修改。
IPWhiteList：控制哪些来源可以访问
- 类型：
string - 示例：
10.0.0.1 - 支持 IPv4 与 IPv6 字面量，可重复出现以配置多个地址
[auth] IPWhiteList = 10.0.0.1 IPWhiteList = 10.0.0.2 IPWhiteList = 2001:0000:130F:0000:0000:09C0:876A:130B行为语义
- 默认（不配置）：所有 IP 地址都允许访问 Nginx UI。
- 一旦配置：只有列表内的 IP 以及
127.0.0.1可以访问 Nginx UI，其余来源一律收到403 Forbidden。
从源码实现看，该策略由中间件 internal/middleware/ip_whitelist.go 强制执行：当IPWhiteList为空时直接放行；客户端 IP 为127.0.0.1或::1（本机回环）时同样放行——这保证了管理员通过本机访问管理界面永远不会被误伤；否则若客户端 IP 不在白名单内，则调用c.AbortWithStatus(http.StatusForbidden)直接中断请求。
前置依赖
白名单判断依赖c.ClientIP()，其取值受TrustedProxies影响：如果 Nginx UI 位于反向代理之后而未正确配置TrustedProxies，ClientIP()取到的可能是代理地址而非真实客户端地址，导致白名单判定失准。因此IP 白名单与可信代理应成对配置。
TrustedProxies：定义可信代理链边界
- 类型：
string - 示例：
127.0.0.1 - 支持 IP 与 CIDR 网段，可重复出现
[auth] TrustedProxies = 127.0.0.1 TrustedProxies = ::1 TrustedProxies = 10.0.0.0/8行为语义
TrustedProxies决定哪些直连代理 IP（或 CIDR）可以携带X-Forwarded-For与X-Real-IP头参与客户端真实 IP 的推导：
- 未处于反向代理之后：保持为空即可。
- 官方 Docker 镜像：会自动信任其内置的 loopback Nginx 代理（
127.0.0.1与::1），无需手动配置。 - 自定义反向代理：必须显式列出代理地址，修改后需重启应用。
- 安全红线：严禁使用
0.0.0.0/0或::/0，否则任意来源都能伪造转发头，彻底破坏 IP 白名单与审计的可靠性。
源码实现
router/client_ip.go 展示了该逻辑：trustedProxiesForCurrentTopology()会克隆用户配置的TrustedProxies；当检测到正在管理内置 Nginx（ShouldManageBundledNginx()）时，自动把127.0.0.1、::1追加进信任列表，随后通过engine.SetTrustedProxies(...)交给 Gin 框架计算客户端 IP。也就是说，“官方镜像自动信任内置 loopback 代理”这一行为在代码层面是显式实现的，而自定义代理必须由用户显式声明。
BanThresholdMinutes 与 MaxAttempts：登录暴力破解防护
两个参数共同构成登录失败封禁策略：
- BanThresholdMinutes（类型：
int，默认：10）：封禁的时间窗口。 - MaxAttempts（类型：
int，默认：10）：窗口内允许的最大失败次数。
默认行为：如果用户在 10 分钟内连续登录失败 10 次，该用户（IP）将被封禁 10 分钟。
源码链路
- 失败计数与过期：登录失败时调用 internal/user/login.go 的
BanIP(ip)。若该 IP 尚无封禁记录或记录已过期，则以当前时间 +BanThresholdMinutes*60秒作为ExpiredAt新建记录；否则对Attempts加一。 - 入口拦截：登录接口 api/user/auth.go 在开始处理前查询
BanIP表，若存在未过期且Attempts >= MaxAttempts的记录，直接返回 HTTP429 Too Many Requests与错误码ErrMaxAttempts (4291)，并加锁串行化登录请求（sync.Mutex），防止并发绕过。 - 成功清账：登录成功后删除该 IP 的封禁记录（见同文件第 117-118 行）。
- 封禁名单管理：封禁中的 IP 列表可由管理员通过 api/settings/auth.go 提供的
GetBanLoginIP（查询当前生效的封禁 IP）与RemoveBannedIP（手动解除封禁）接口查看和清理。
从测试用例（如 internal/user/login_ban_test.go）可以确认该策略按“窗口内失败次数达到阈值即封禁”的规则运行。实际部署中建议结合日志观察误封情况，必要时调大MaxAttempts或缩短BanThresholdMinutes。
SecureSessionTimeoutMinutes：TOTP/Passkey 二次验证的有效期
- 类型：
int - 默认：
10
行为语义
该参数控制一次成功的 TOTP 或 Passkey 验证后，被授权的受保护操作（如敏感设置变更）可以持续多少分钟，即“安全会话”的有效时长：
- 不影响正常登录会话的生命周期：普通登录 token 的有效期由其他机制管理，此参数只作用于二次验证授权窗口。
- 取值约束：必须是正数；缺失、为 0 或负数时回退到 10 分钟默认值。
源码实现
internal/user/otp.go 中：
configuredSecureSessionDuration()读取SecureSessionTimeoutMinutes，当minutes <= 0或超过maxSecureSessionTimeoutMinutes上限时返回默认 10 分钟。- 登录接口在用户开启 2FA 且验证通过后，通过
SetSecureSessionID(u.ID)生成会话 ID，并在响应中返回secure_session_id与secure_session_ttl（秒），供前端在敏感操作时提交验证（见 api/user/auth.go）。
同时，internal/user/secure_session.go、internal/user/secure_session_test.go等文件提供了该机制的存储实现与回归测试，确保默认值回退逻辑（缺失/零/负数）与正向取值均符合预期。
配置方式与生效前提
auth段配置写入 Nginx UI 的配置文件（app.ini）后，修改TrustedProxies必须重启应用；其余参数在应用运行期间可通过“设置”界面实时调整并持久化。- 配置项同时支持环境变量覆盖（详见 docs/guide/env.md），适合容器化部署时注入。
- 从 docs/zh_CN/guide/config-auth.md 可查看本指南的中文版本。
配置示例：组合一个安全的公网部署
综合上述配置，一个典型的公网部署示例如下：
[auth] ; 仅允许公司出口 IP 与 IPv6 地址访问 IPWhiteList = 10.0.0.1 IPWhiteList = 2001:0000:130F:0000:0000:09C0:876A:130B ; 前置 Nginx 反代的真实地址（务必精确，禁止 0.0.0.0/0） TrustedProxies = 127.0.0.1 TrustedProxies = 192.168.1.10 ; 登录安全策略：5 分钟内失败 5 次则封禁 15 分钟 MaxAttempts = 5 BanThresholdMinutes = 15 ; 二次验证授权窗口 30 分钟 SecureSessionTimeoutMinutes = 30配置时请记住三条要点：白名单与可信代理必须协同配置；代理信任边界宁小勿大（绝不用0.0.0.0/0与::/0）；登录封禁参数需根据真实误封日志调整，以避免合法用户被短暂锁定。
- 后端
- 前端
- 运维
- MCP 服务
【免费下载链接】nginx-ui
Yet another WebUI for Nginx
相关推荐
Guns安全策略配置指南：密码策略、黑白名单、登录保护终极教程
Guns安全策略配置指南：密码策略、黑白名单、登录保护终极教程 Guns是一个现代化的Java应用开发框架，基于主流技术Spring Boot3 + Vue3
Nginx访问控制终极指南：快速配置IP白名单与Basic Auth认证
Nginx访问控制终极指南：快速配置IP白名单与Basic Auth认证 Nginx作为高性能的Web服务器和反向代理，其访问控制功能是保护网站安全的重要手段。
文档教程技术博客Nginx Proxy Manager 访问列表（Access List）完全指南：IP 黑白名单与 Basic Auth 配置实战
Nginx Proxy Manager 访问列表（Access List）完全指南：IP 黑白名单与 Basic Auth 配置实战 导读 访问列表（Acces
后端API网关
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
