后端前端运维MCP 服务【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址https://gitcode.com/gh_mirrors/ngi/nginx-ui点击查看免费下载本文以 Nginx UI 配置文件的[auth]段为核心系统讲解从 v2.0.0-beta.26 起引入的授权选项IP 白名单IPWhiteList与登录失败封禁BanThresholdMinutes、MaxAttempts。结合仓库源码你将理解这三项配置的生效链路、边界行为本机回环豁免、代理场景、IPv6、失败计数与解封机制并掌握通过配置文件与NGINX_UI_AUTH_*环境变量两种方式完成安全加固的完整方案。一、[auth]配置段概览从 v2.0.0-beta.26 版本开始Nginx UI 支持在配置文件的auth段设置授权选项。该段对应的 Go 结构体定义在 settings/auth.go源码结构如下type Auth struct { IPWhiteList []string json:ip_white_list binding:omitempty,dive,ip|redacted ini:,,allowshadow protected:true TrustedProxies []string json:trusted_proxies binding:omitempty,dive,ip|cidr|redacted ini:,,allowshadow protected:true BanThresholdMinutes int json:ban_threshold_minutes binding:min1 MaxAttempts int json:max_attempts binding:min1 SecureSessionTimeoutMinutes int json:secure_session_timeout_minutes binding:min1 }从源码可以看出[auth]段不仅包含文档中列出的三项还包含TrustedProxies受信代理列表与SecureSessionTimeoutMinutes安全会话超时时间默认值 10 分钟定义于同一文件的DefaultSecureSessionTimeoutMinutes常量两个相邻安全选项。它们共同构成 Nginx UI 的认证入口防护体系。其中IPWhiteList为字符串数组支持重复键声明ini:,,allowshadow表示同名键可多次出现每次追加一个元素这正是配置示例中多次书写IPWhiteList的语法依据BanThresholdMinutes、MaxAttempts均要求最小值 1binding:min1不允许配置为 0 或负数。该配置段在 settings/settings.go 中注册为auth节sections.Set(auth, AuthSettings)并可通过环境变量覆盖见后文第五节。二、IPWhiteList访问来源 IP 白名单2.1 配置语法类型string可重复声明形成白名单列表示例10.0.0.1支持 IPv4 与 IPv6如2001:0000:130F:0000:0000:09C0:876A:130B[auth] IPWhiteList 10.0.0.1 IPWhiteList 10.0.0.2 IPWhiteList 2001:0000:130F:0000:0000:09C0:876A:130B2.2 行为规则与回环豁免默认情况下如果没有设置IPWhiteList所有 IP 地址都允许访问 Nginx UI。一旦设置了白名单只有白名单内的 IP 与127.0.0.1可以访问 Nginx UI其余来源将收到403 Forbidden错误白名单为空时视为未启用放行所有 IP。该逻辑实现在 internal/middleware/ip_whitelist.go核心代码如下func IPWhiteList() gin.HandlerFunc { return func(c *gin.Context) { clientIP : c.ClientIP() if len(settings.AuthSettings.IPWhiteList) 0 || clientIP 127.0.0.1 || clientIP ::1 { c.Next() return } if !lo.Contains(settings.AuthSettings.IPWhiteList, clientIP) { c.AbortWithStatus(http.StatusForbidden) return } c.Next() } }值得注意的细节回环豁免同时覆盖 IPv4 与 IPv6代码同时判断了127.0.0.1与::1。换言之本机访问无论走 IPv4 还是 IPv6 回环地址始终被放行即使它们未出现在白名单中。文档只提到127.0.0.1源码证明::1同样享有豁免——这在启用 IPv6 的本机环境中非常重要。白名单精确匹配使用lo.Contains进行列表精确匹配不会做 CIDR 网段匹配。如果需要放行整个网段必须在[auth]段逐一列出该网段内的每个 IP或结合反向代理统一出口 IP 的策略。若需要 CIDR 能力可关注TrustedProxies字段其 binding 校验为ip|cidr它用于声明可信的反向代理来源从而让c.ClientIP()正确解析经代理转发后的真实客户端 IP。2.3 白名单中间件的挂载位置IPWhiteList中间件在 router/routers.go 中被挂载到 API 路由组根节点上root : r.Group(/api, middleware.IPWhiteList())这意味着白名单约束作用于整个/api前缀下的全部接口——无论是登录接口还是业务接口均受其管辖。这是访问控制的第一道闸门在认证登录鉴权之前生效。2.4 测试用例对行为边界的印证internal/middleware/ip_whitelist_test.go 中的测试精确刻画了白名单的边界行为值得运维人员关注代理场景当请求来自受信代理trustedProxies[127.0.0.1]且X-Forwarded-For头携带198.51.100.20时白名单只放行198.51.100.20而放行203.0.113.20则返回 403 —— 说明白名单判定的是经ClientIP()解析后的真实客户端 IP而非 TCP 对端地址伪造头防护当不存在受信代理时客户端直接伪造X-Forwarded-For: 203.0.113.20也无法绕过白名单返回 403即伪造的转发头不会被信任异常输入失败关闭当远程地址无法解析为合法 IP 时白名单判定为拒绝403遵循失败关闭fail-closed的安全原则回环兼容127.0.0.1与[::1]在未配置受信代理的情况下直接放行204 No Content。因此如果你在反向代理Nginx、Caddy 等后面部署 Nginx UI请务必同时配置TrustedProxies指向代理服务器地址否则ClientIP()取到的是代理地址白名单可能无法按预期匹配真实客户端 IP。三、登录失败封禁机制BanThresholdMinutes 与 MaxAttempts3.1 参数说明参数类型默认值语义BanThresholdMinutesint10失败计数与封禁的有效时间窗口分钟MaxAttemptsint10触发封禁所需的累计失败次数阈值默认行为如果用户在10 分钟内登录失败10 次该用户来源 IP 将被禁止登录10 分钟。源码层面的默认值定义于 settings/auth.go 的初始化逻辑var AuthSettings Auth{ BanThresholdMinutes: 10, MaxAttempts: 10, SecureSessionTimeoutMinutes: DefaultSecureSessionTimeoutMinutes, }同时在 settings/settings.go 的Init中做了一次兜底校验若配置值小于等于 0则回退为默认值 10if AuthSettings.BanThresholdMinutes 0 { AuthSettings.BanThresholdMinutes 10 } if AuthSettings.MaxAttempts 0 { AuthSettings.MaxAttempts 10 }注意这里只对 0的情况兜底而结构体 binding 校验要求min1因此合法取值区间为1及以上的正整数。若需更严苛的安全策略可将两者调低如BanThresholdMinutes 5、MaxAttempts 3即5 分钟内失败 3 次即封禁 5 分钟。3.2 计数与封禁的实现链路封禁记录使用数据库表ban_ips对应模型 model/ban_ip.go通过 query/ban_ips.gen.go 生成的 GORM 查询对象操作。核心逻辑在 internal/user/login.gofunc BanIP(ip string) { b : query.BanIP banIP, err : b.Where(b.IP.Eq(ip)).First() if err ! nil || banIP.ExpiredAt time.Now().Unix() { _ b.Create(model.BanIP{ IP: ip, Attempts: 1, ExpiredAt: time.Now().Unix() int64(settings.AuthSettings.BanThresholdMinutes*60), }) return } _, _ b.Where(b.IP.Eq(ip)).UpdateSimple(b.Attempts.Add(1)) }其工作机制可归纳为按 IP 查询封禁记录若不存在该记录或记录已过期ExpiredAt now则新建一条记录Attempts 1过期时间 当前时间 BanThresholdMinutes分钟换算为秒若记录仍有效则将Attempts累加 1。在 api/user/auth.go 的Login处理器中登录失败密码错误、2FA 缺失或校验失败等都会调用user.BanIP(clientIP)。而在登录入口处会先做封禁检查banIP, _ : b.Where(b.IP.Eq(clientIP), b.ExpiredAt.Gte(time.Now().Unix()), b.Attempts.Gte(settings.AuthSettings.MaxAttempts), ).Count() if banIP 0 { c.JSON(http.StatusTooManyRequests, LoginResponse{ Message: Max attempts, Code: ErrMaxAttempts, // 4291 }) return }即当某 IP 存在未过期且失败次数 ≥ MaxAttempts的记录时登录请求直接返回429 Too Many Requests业务错误码4291常量ErrMaxAttempts。登录成功后该 IP 的封禁记录会被清除// login success, clear banned record _, _ b.Where(b.IP.Eq(clientIP)).Delete()3.3 封禁的粒度与观察维度按 IP 独立计数封禁记录以 IP 为键不同来源 IP 的失败计数互不影响。这一行为由 internal/user/login_ban_test.go 中的TestBanIPKeepsDifferentClientBucketsSeparate测试直接验证对198.51.100.10与203.0.113.20分别调用BanIP后两条记录的Attempts各自独立分别为 2 和 1互不干扰。窗口滑动特性一旦超过BanThresholdMinutes旧记录即视为过期下一次失败会重建记录并从 1 重新计数。因此不存在永久封禁——封禁是周期性的。额外的人为延迟登录失败后服务端会追加一个 010 秒的随机休眠time.Sleep(random * time.Second)见 api/user/auth.go进一步抬高暴力破解的时间成本。3.4 被封禁 IP 的管理接口api/settings/auth.go 提供了两个管理接口GET查询当前封禁的 IP 列表GetBanLoginIP先清理已过期的封禁记录再返回满足ExpiredAt now Attempts MaxAttempts的记录删除指定被封禁的 IPRemoveBannedIP管理员可手动解除误封。即当某个合法用户因多次输错密码被临时封禁时管理员无需等待BanThresholdMinutes到期可以通过管理接口立即解除封禁。四、完整配置示例与生效方式4.1 配置文件示例将上述配置组合到 Nginx UI 的配置文件默认为app.ini具体路径与加载方式见 config-app.md[auth] # 仅允许以下 IP 访问可重复声明未配置时放行所有 IP IPWhiteList 10.0.0.1 IPWhiteList 10.0.0.2 IPWhiteList 2001:0000:130F:0000:0000:09C0:876A:130B # 5 分钟内累计失败 5 次则封禁该 IP 5 分钟 BanThresholdMinutes 5 MaxAttempts 5 # 可选反向代理场景下声明受信代理保证 ClientIP() 取到真实客户端地址 TrustedProxies 127.0.0.1配置保存后服务重启或通过管理端保存设置时settings.Save()会将结构体回写到 ini 文件并重新加载settings.Reload()实现热更新。4.2 环境变量方式Docker / systemd 部署由于 settings/settings.go 中envPrefixMap将AUTH映射到AuthSettings且环境变量前缀为NGINX_UI_因此 docs/zh_CN/guide/env.md 列出的对应关系如下配置项环境变量IPWhiteListNGINX_UI_AUTH_IP_WHITE_LISTBanThresholdMinutesNGINX_UI_AUTH_BAN_THRESHOLD_MINUTESMaxAttemptsNGINX_UI_AUTH_MAX_ATTEMPTSDocker 部署示例docker run -d \ -e NGINX_UI_AUTH_IP_WHITE_LIST10.0.0.1 \ -e NGINX_UI_AUTH_BAN_THRESHOLD_MINUTES5 \ -e NGINX_UI_AUTH_MAX_ATTEMPTS5 \ -p 9000:9000 \ uozi/nginx-ui:latest提示IPWhiteList为数组类型若需多个 IP请参考 docs/zh_CN/guide/env.md 中数组类配置的写法逗号分隔或重复声明视版本而定。五、安全建议与注意事项白名单与反向代理IPWhiteList判定的是c.ClientIP()的解析结果。在 Nginx/Caddy 反向代理之后部署时务必配置TrustedProxies指向代理地址否则所有请求都会显示为代理 IP白名单要么全部放行、要么全部拒绝。这一点已由ip_whitelist_test.go中的代理与伪造头用例明确验证。回环豁免是设计行为127.0.0.1与::1始终可访问即使未列入白名单。这意味着限制来源无法阻止本机进程访问请确保运行 Nginx UI 的主机本身是可信的。封禁是 IP 粒度的临时策略它是暴力破解的减速带而非访问控制手段。对于高安全要求的部署应结合强密码、2FA见 api/user/auth.go 中的 OTP/Passkey 登录链路与防火墙规则共同使用。调参权衡MaxAttempts过小、BanThresholdMinutes过大可能造成合法用户因输入错误被长时间拒之门外反之则防护力度不足。建议按实际部署环境调整并借助封禁列表管理接口及时处理误封。配置边界BanThresholdMinutes与MaxAttempts必须为不小于 1 的整数 0的值会在初始化时被强制回退为 10。六、小结[auth]段的三项核心配置为 Nginx UI 提供了两道基础防线IPWhiteList在 API 路由最外层按来源 IP 进行访问控制支持 IPv4/IPv6、回环豁免、失败关闭BanThresholdMinutes与MaxAttempts则在登录入口按 IP 累计失败次数并实施周期性封禁429 Too Many Requests配合封禁管理接口可随时解除误封。结合TrustedProxies、环境变量注入与源码级行为边界代理解析、IPv6 回环、独立计数桶你可以在 Docker、systemd 与反向代理等各类部署形态下完成一次完整、可验证的登录安全加固。如需进一步了解配置文件整体结构与环境变量全量清单可参阅 config-app.md 与 env.md。赞分享后端前端运维MCP 服务【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址https://gitcode.com/gh_mirrors/ngi/nginx-ui点击查看免费下载相关推荐Nginx UI Auth 配置指南IP 白名单、可信代理与登录安全策略Nginx UI Auth 配置指南IP 白名单、可信代理与登录安全策略 本指南系统讲解 Nginx UI 从 v2.0.0 beta.26 起引入的 aut后端前端运维MCP 服务Nginx访问控制终极指南快速配置IP白名单与Basic Auth认证Nginx访问控制终极指南快速配置IP白名单与Basic Auth认证 Nginx作为高性能的Web服务器和反向代理其访问控制功能是保护网站安全的重要手段。文档教程技术博客Nginx UI 認證設定完整指南IP 白名單、失敗封鎖與安全會話時長配置解析Nginx UI 認證設定完整指南IP 白名單、失敗封鎖與安全會話時長配置解析 Nginx UI 自 v2.0.0 beta.26 起可以在設定檔的 aut后端前端运维MCP 服务上一篇Lumafly基础教程一键启用、禁用与更新MOD的8个实用技巧下一篇ROCm 6.4.1 正式发布Radeon 9070 系列获得官方支持升级前注意这几点创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考