Nginx UI 認證設定完整指南：IP 白名單、失敗封鎖與安全會話時長配置解析

后端前端运维MCP 服务【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址https://gitcode.com/gh_mirrors/ngi/nginx-ui点击查看免费下载Nginx UI 自 v2.0.0-beta.26 起可以在設定檔的auth區段集中管理授權與登入安全策略包括 IP 白名單、可信反向代理、登入失敗封鎖以及雙重驗證安全會話的有效期。本篇指南以 docs/zh_TW/guide/config-auth.md 為主體並結合倉庫中的設定定義與中介層原始碼逐項說明每個參數的格式、預設值、生效規則與底層實現協助你在部署後正確加固 Nginx UI 的登入入口。設定檔中的 auth 區段從 v2.0.0-beta.26 版本開始你可以在設定檔app.ini的auth區段設定授權選項。所有欄位皆定義在 settings/auth.go 的Auth結構中並在啟動時載入到全域的AuthSettingstype 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 }由結構定義可以看出幾點實作細節IPWhiteList與TrustedProxies都是字串陣列帶有ini:,,allowshadow標記代表同一個 key 可以在 INI 設定檔中重複出現多次每次一行形成一個清單項目binding:dive,ip|cidr則在載入時驗證每一項必須是合法的 IP 或 CIDR。兩個欄位都帶有protected:true表示透過 API 讀取設定時會以遮蔽redacted形式回傳避免白名單與代理位址這類敏感資訊被直接暴露。BanThresholdMinutes、MaxAttempts、SecureSessionTimeoutMinutes為整數且binding:min1要求最小值為 1。預設值集中在AuthSettings變數中BanThresholdMinutes: 10、MaxAttempts: 10、SecureSessionTimeoutMinutes: DefaultSecureSessionTimeoutMinutes即 10。IPWhiteList僅允許指定來源存取格式與範例類型string可重複多行範例10.0.0.1[auth] IPWhiteList 10.0.0.1 IPWhiteList 10.0.0.2 IPWhiteList 2001:0000:130F:0000:0000:09C0:876A:130B行為規則預設情況若未設定IPWhiteList所有 IP 位址都允許存取 Nginx UI。設定之後只有清單中的 IP 位址以及127.0.0.1的使用者可以存取 Nginx UI其他來源會收到403 Forbidden錯誤。原始碼層面的運作方式IP 白名單的檢查由中介層 internal/middleware/ip_whitelist.go 的IPWhiteList()完成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() } }從程式碼可以確認三個要點白名單為空即全放行只要IPWhiteList長度為 0中介層直接c.Next()不攔截任何請求。本機位址恆可存取127.0.0.1與::1無論是否在清單中都會被放行這確保管理員從本機操作不會被意外鎖在門外。命中即 403其餘位址必須精確命中清單lo.Contains比對否則以AbortWithStatus(http.StatusForbidden)直接中斷請求鏈。該中介層的掛載位置在 router/routers.go 與 router/routers_embed.go分別套用在 API 路由群組與內嵌靜態資源路由上對應的測試覆蓋見 internal/middleware/ip_whitelist_test.go。注意此處比對的是c.ClientIP()而該值會受到下方TrustedProxies設定的影響。若 Nginx UI 位於反向代理之後請務必一併設定TrustedProxies否則代理轉發的真實用戶 IP 無法被正確解析。TrustedProxies可信反向代理X-Forwarded-For / X-Real-IP格式與範例類型string可重複多行範例127.0.0.1[auth] TrustedProxies 127.0.0.1 TrustedProxies ::1 TrustedProxies 10.0.0.0/8行為規則TrustedProxies控制哪些直接與 Nginx UI 建立連線的代理 IP 位址或 CIDR 區段被允許提供X-Forwarded-For與X-Real-IP請求頭。未位於反向代理後方時請保持此設定為空。官方 Docker 映像只會自動信任其內建的 loopback Nginx 代理127.0.0.1與::1。自訂反向代理必須將代理位址明確加入清單且修改設定後必須重新啟動應用程式才會生效。安全警告絕對不要使用0.0.0.0/0或::/0否則任何來源都能偽造X-Forwarded-For等同於繞過 IP 白名單與存取控制。原始碼層面的運作方式該設定在啟動階段由 router/client_ip.go 的configureTrustedProxies套用至 Gin 引擎var bundledNginxTrustedProxies []string{127.0.0.1, ::1} func trustedProxiesForCurrentTopology() []string { trustedProxies : slices.Clone(settings.AuthSettings.TrustedProxies) if !helper.ShouldManageBundledNginx() { return trustedProxies } for _, trustedProxy : range bundledNginxTrustedProxies { if !slices.Contains(trustedProxies, trustedProxy) { trustedProxies append(trustedProxies, trustedProxy) } } return trustedProxies } func configureTrustedProxies(engine *gin.Engine) error { return engine.SetTrustedProxies(trustedProxiesForCurrentTopology()) }程式碼揭示的關鍵行為當 Nginx UI 管理內建 NginxShouldManageBundledNginx()為真時127.0.0.1與::1會被自動合併進信任清單——這正是官方 Docker 映像內建 loopback 代理的來源。當改為管理外部 Nginx 時信任清單完全取自TrustedProxies設定不做自動追加。設定會在路由初始化時router/routers.go 中呼叫configureTrustedProxies一次性套用因此修改後需要重啟程序才會生效這與文件說明一致。非法網路位址如not-a-network會在啟動時被SetTrustedProxies拒絕相關測試見 router/client_ip_test.go。BanThresholdMinutes 與 MaxAttempts登入失敗自動封鎖參數定義BanThresholdMinutes類型int預設10。MaxAttempts類型int預設10。預設行為如果使用者在 10 分鐘內登入失敗 10 次該 IP 將被禁止登入 10 分鐘。兩個參數的預設值組合等價於「10 分鐘內 10 次失敗」的規則。原始碼層面的運作方式封鎖機制實作於 api/user/auth.go 的Login與 internal/user/login.go 的BanIP登入前檢查api/user/auth.go先查詢BanIP表中是否存在「未過期ExpiredAt now且嘗試次數達標Attempts MaxAttempts」的記錄命中即回傳429 Too Many Requests錯誤碼ErrMaxAttempts 4291。失敗累計internal/user/login.go登入失敗密碼錯誤、2FA 驗證失敗等時呼叫BanIP(clientIP)——若該 IP 無記錄或已過期則新建記錄Attempts設為 1、ExpiredAt設為now BanThresholdMinutes*60秒若記錄仍有效則累加Attempts。失敗後延遲登入失敗後會隨機睡眠 09 秒再回傳錯誤用於減緩暴力破解的節奏。成功後清除登入成功時會刪除該 IP 的封鎖記錄。換句話說MaxAttempts控制「幾次失敗開始封鎖」BanThresholdMinutes同時控制「統計失敗的時間窗」與「封鎖持續時間」兩件事。要調整策略例如「5 分鐘內 5 次失敗就鎖 30 分鐘」可以設定[auth] BanThresholdMinutes 30 MaxAttempts 5對應的測試覆蓋見 internal/user/login_ban_test.go。提醒BanThresholdMinutes與MaxAttempts均為全域設定封鎖對象是 IP 而非帳號共享出口 IP 的內網環境如 NAT 後方可能導致多人互相影響請依實際部署環境調整合適的閾值。SecureSessionTimeoutMinutes雙重驗證安全會話時長類型int預設10此參數控制一次成功的 TOTP 或 passkey 驗證可以授權受保護操作多久以分鐘計。需要特別區分的是它不會改變正常登入 session 的生命週期數值必須為正整數缺失、為 0 或負數時一律使用 10 分鐘預設值。在原始碼中預設值由settings/auth.go的DefaultSecureSessionTimeoutMinutes 10定義安全 session 的存放與查詢實作於 internal/user/secure_session.go以進程內記憶體快取為基礎重啟後所有已驗證 session 立即失效時長由SecureSessionDuration()提供。登入時回傳的SecureSessionTTL即來自該時長見 api/user/auth.go 的Login。相關行為測試見 internal/user/secure_session_test.go。若你的安全策略要求更嚴格可縮短至例如 5 分鐘若希望減少 2FA 驗證頻率可適度調大但請權衡安全性。[auth] SecureSessionTimeoutMinutes 5透過環境變數覆寫設定auth區段的參數除了寫入設定檔也可以透過環境變數覆寫。依照 docs/zh_TW/guide/env.md 的對應表設定項環境變數IPWhiteListNGINX_UI_AUTH_IP_WHITE_LISTBanThresholdMinutesNGINX_UI_AUTH_BAN_THRESHOLD_MINUTESMaxAttemptsNGINX_UI_AUTH_MAX_ATTEMPTS例如在容器環境中可以這樣注入NGINX_UI_AUTH_IP_WHITE_LIST10.0.0.1,10.0.0.2 NGINX_UI_AUTH_BAN_THRESHOLD_MINUTES30 NGINX_UI_AUTH_MAX_ATTEMPTS5完整的 auth 區段範例綜合以上參數一個完整且具備基本防護能力的auth區段如下[auth] # 僅允許指定來源存取留空則全部放行127.0.0.1 / ::1 永遠允許 IPWhiteList 10.0.0.1 IPWhiteList 10.0.0.2 # 位於反向代理後方時列出可信代理的 IP 或 CIDR不得使用 0.0.0.0/0、::/0 TrustedProxies 127.0.0.1 TrustedProxies ::1 TrustedProxies 10.0.0.0/8 # 登入失敗封鎖統計時間窗與封鎖時長分鐘 BanThresholdMinutes 10 # 時間窗內允許的最大失敗次數 MaxAttempts 10 # TOTP / passkey 驗證後安全會話的有效分鐘數 SecureSessionTimeoutMinutes 10常見問題與注意事項修改設定後何時生效多數設定如TrustedProxies、IPWhiteList在啟動階段套用修改設定檔後需要重啟 Nginx UIBanThresholdMinutes、MaxAttempts、SecureSessionTimeoutMinutes屬於動態讀取的執行時期設定但建議同樣重啟以確保一致行為。設定了白名單卻連不上請確認請求來源是精確命中清單的 IP並檢查是否位於代理後方而導致ClientIP()取得的是代理位址——此時需要同時設定TrustedProxies。為什麼不能設TrustedProxies 0.0.0.0/0這會讓任何來源的X-Forwarded-For都被採信攻擊者可偽造來源 IP徹底瓦解白名單與封鎖機制的有效性。環境變數與設定檔衝突時以誰為準環境變數用於覆寫設定檔值以NGINX_UI_AUTH_*前綴的變數可直接對應auth區段各欄位詳細對照請參考 docs/zh_TW/guide/env.md。總結auth區段是 Nginx UI 登入安全的第一道防線IPWhiteList控制「誰能進來」TrustedProxies確保反向代理環境下真實 IP 能被正確解析BanThresholdMinutes與MaxAttempts聯手抵禦暴力破解而SecureSessionTimeoutMinutes則縮短 2FA 驗證後的受保護操作窗口。透過設定檔或環境變數組合以上參數並配合重啟驗證即可為你的 Nginx UI 建立一套可執行的存取控制與登入防護策略。赞分享后端前端运维MCP 服务【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址https://gitcode.com/gh_mirrors/ngi/nginx-ui点击查看免费下载相关推荐Coil圖像請求頭部認證Token與Cookie設置Coil圖像請求頭部認證Token與Cookie設置 在移動應用開發中圖像加載經常需要處理認證問題例如通過Token或Cookie驗證用戶身份。Coil作移动开发图像处理缓存抽象Voyager タイムライン完全ガイド — 長い会話を一筋の「線」に変える時間旅行ナビゲーションVoyager タイムライン完全ガイド — 長い会話を一筋の「線」に変える時間旅行ナビゲーション 長い会話は迷宮です。上へ下へとスクロールし、方向を見失ってしまAI 应用前端JumpServer PAM 資產帳號密碼查詢 API 實戰指南基於 cURL 與 HTTP Signature 簽名認證JumpServer PAM 資產帳號密碼查詢 API 實戰指南基於 cURL 與 HTTP Signature 簽名認證 導讀 本文以 JumpServer后端认证鉴权运维网络安全上一篇解放双手AALC你的《Limbus Company》终极自动化助手完全指南下一篇基于OpenCV-Python的高精度指针式仪表智能视觉检测系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考