后端前端运维MCP 服务【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址https://gitcode.com/gh_mirrors/ngi/nginx-ui点击查看免费下载本指南系统讲解 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.gotype Auth struct { IPWhiteList []string json:ip_white_list ... TrustedProxies []string json:trusted_proxies ... BanThresholdMinutes int json:ban_threshold_minutes binding:min1 MaxAttempts int json:max_attempts binding:min1 SecureSessionTimeoutMinutes int json:secure_session_timeout_minutes binding:min1 }其中BanThresholdMinutes、MaxAttempts的默认值均为10SecureSessionTimeoutMinutes默认值同样为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 位于反向代理之后而未正确配置TrustedProxiesClientIP()取到的可能是代理地址而非真实客户端地址导致白名单判定失准。因此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当检测到正在管理内置 NginxShouldManageBundledNginx()时自动把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。SecureSessionTimeoutMinutesTOTP/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-uiYet another WebUI for Nginx项目地址https://gitcode.com/gh_mirrors/ngi/nginx-ui点击查看免费下载相关推荐Guns安全策略配置指南密码策略、黑白名单、登录保护终极教程Guns安全策略配置指南密码策略、黑白名单、登录保护终极教程 Guns是一个现代化的Java应用开发框架基于主流技术Spring Boot3 Vue3Nginx访问控制终极指南快速配置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），仅供参考