尧图网站建设 
Nginx Proxy Manager 访问列表Access List完全指南IP 黑白名单与 Basic Auth 认证实战【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager访问列表Access List是 Nginx Proxy Manager 中面向反向代理主机的一站式访问控制方案它把「特定客户端 IP 的黑名单 / 白名单」与「基于 HTTP Basic 认证的用户名密码校验」合并在一个可复用的配置单元里随后可以绑定到一个或多个代理主机Proxy Host上。读完本文你将掌握访问列表的核心概念、字段含义、底层 Nginx 配置生成原理、Web 界面与 REST API 的完整操作方式以及它在保护无内置认证机制的服务时的最佳实践。本文以仓库中的官方帮助文档 AccessLists.md 为骨架结合后端源码与模板实现进行深度展开。什么是访问列表Access List根据官方帮助文档的定义访问列表向代理主机提供两类核心能力特定客户端 IP 的黑名单blacklist与白名单whitelist通过为每个 IP 地址或地址段指定allow/deny指令精确控制哪些来源可以访问被代理的后端服务基于 HTTP Basic 认证的身份校验为一组「用户名 密码」建立凭据库客户端访问代理主机时必须通过认证才能继续。原文要点访问列表为代理主机提供特定客户端 IP 的黑名单与白名单并通过 Basic HTTP 认证实现身份校验。你可以在单个访问列表中配置多条客户端规则、多个用户名与密码然后将该列表应用于一个或多个代理主机。这对没有内置认证机制的转发 Web 服务或需要防范未知客户端访问的场景最为有用。这种设计的关键在于可复用性一次配置、多处挂载。运维人员不必为每个代理主机重复录入认证信息只需维护一份访问列表并在多个代理主机上引用它即可。核心概念与数据模型从数据库与后端源码看访问列表由三张表共同支撑见 models/access_list.js、models/access_list_auth.js、models/access_list_client.js表名作用关键字段access_list访问列表本体id、name、satisfy_any、pass_auth、owner_user_id、is_deletedaccess_list_authBasic 认证凭据itemsaccess_list_id、username、passwordaccess_list_clientIP 访问规则clientsaccess_list_id、address、directive其中access_list_auth通过access_list_id与列表关联一个列表可含多条凭据access_list_client同样通过access_list_id关联一个列表可含多条allow/deny规则access_list还通过proxy_host.access_list_id与代理主机表建立一对多关联这正是「一个列表绑定多个代理主机」的实现基础见 models/access_list.js 中的items、clients、proxy_hosts关系映射。satisfy_any与pass_auth是布尔字段在数据库中分别由迁移 20200410143839_access_list_client.js新增satify_any默认 0和 20201014143841_pass_auth.js新增pass_auth默认 1引入模型层通过 helpers.js 的布尔转换逻辑在读写时自动完成 0/1 与true/false的互转。关键配置项详解在 Web 界面的访问列表编辑弹窗AccessListModal.tsx中表单被划分为「详情 / 认证 / 规则」三个页签对应以下核心配置项name列表名称访问列表的名称用于在管理界面中辨识。前端校验要求 1255 个字符见 AccessListModal.tsx。satisfy_any满足任一 / 全部控制 IP 规则与 Basic 认证之间的组合逻辑这是最容易踩坑的选项关闭satisfy all默认客户端必须同时满足 IP 白名单规则且通过 Basic 认证才允许访问开启satisfy any客户端只需满足任一条件即可放行——例如在白名单 IP 内可直接访问或者虽不在白名单但提供了正确的用户名密码也能访问。该开关直接映射到生成的 Nginx 配置中的satisfy any;/satisfy all;指令见 templates/_access.conf。需要特别说明的是satisfy指令仅对allow/denyIP 访问控制与auth_basicHTTP 认证同时存在时才有意义若列表中只配置了凭据或只配置了 IP 规则则该选项不产生实际影响。pass_auth透传认证头控制 Basic 认证通过后Authorization请求头是否继续转发给后端服务开启默认值为 1后端服务可以继续收到客户端的Authorization头适合后端自身也依赖该头做身份识别的场景例如将 Basic 凭据透传给上游应用关闭值为 0在认证通过后主动清空Authorization头proxy_set_header Authorization ;避免将敏感凭据泄露给上游。对应的模板逻辑见 templates/_access.conf。itemsBasic 认证凭据一组「用户名 密码」对构成 Basic 认证的凭据库。同一访问列表中可以配置多条凭据任意一组通过校验即可对应access_list_auth表。密码在管理界面中会以脱敏形式展示后端在返回数据时用maskItems方法将其替换为「首字符 星号」的提示串见 internal/access-list.js真实密码仅在创建或更新时提交一次。clientsIP 访问规则一组「directive address」规则对构成 IP 黑白名单对应access_list_client表directiveallow放行或deny拒绝address目标 IP 或地址段例如192.168.1.10、10.0.0.0/8。规则按书写顺序自上而下匹配匹配到第一条即生效列表末尾固定追加一条不可编辑的deny all见 AccessClientFields.tsx这与 Nginx 的访问控制语义完全一致。Web 界面操作流程在 Nginx Proxy Manager 管理后台中访问列表的完整使用流程如下第一步创建访问列表进入「Access Lists」页面点击新建按钮打开弹窗填写列表名称并根据需要切换Satisfy Any与Pass Auth两个开关见 AccessListModal.tsx。第二步配置认证凭据切换到「Authorizations」页签通过 BasicAuthFields.tsx 添加一组或多组用户名与密码。若目标服务没有内置认证机制这是为其「套上」身份校验的最直接方式。第三步配置 IP 规则切换到「Rules」页签通过 AccessClientFields.tsx 按顺序添加allow/deny规则并填写 IP 地址。界面提示规则按顺序生效且最后一条恒为deny all。第四步应用到代理主机进入某个代理主机的编辑页面在访问列表字段中选择刚创建的列表并保存。前端提交时会把items与clients分别精简为「username/password」与「directive/address」结构后发送到后端见 AccessListModal.tsx后端随后自动重新生成相关代理主机的 Nginx 配置并重载。创建时必须保证「认证凭据」与「IP 规则」至少配置一项否则前端会提示错误error.access.at-least-one见 AccessListModal.tsx同时用户名不可重复。底层原理配置如何生成并生效访问列表的完整生效链路分为「凭据文件生成」与「Nginx 配置渲染」两步。htpasswd 凭据文件生成后端在创建或更新访问列表时会调用 internal/access-list.js 的build方法先删除旧文件再为每条凭据执行openssl passwd -apr1生成 APACHE-MD5apr1格式的密码哈希并逐行写入/data/access/{列表ID}文件username:hashed_password格式。该文件即 Nginxauth_basic_user_file指令引用的凭据库。删除访问列表时对应的凭据文件也会被同步清理见 internal/access-list.js。Nginx 配置模板渲染代理主机的 Nginx 配置模板 templates/proxy_host.conf 在默认location /块中引入 templates/_access.conf其渲染逻辑如下# 仅当列表被引用且包含凭据时启用 Basic 认证 auth_basic Authorization required; auth_basic_user_file /data/access/{{ access_list_id }}; # pass_auth 关闭时清空认证头 proxy_set_header Authorization ; # 按顺序输出每条 allow/deny 规则最后追加 deny all allow 192.168.1.10; deny 10.0.0.0/8; deny all; # 组合逻辑satisfy any / satisfy all其中每条规则由 lib/utils.js 注册的 Liquid 过滤器nginxAccessRule拼装为directive address;形式。规则末尾的deny all由模板本身固定追加见 templates/_access.conf。配置再生成与热重载访问列表的每次增删改都会触发级联操作见 internal/access-list.js创建 / 更新重新获取引用该列表的所有代理主机调用internalNginx.bulkGenerateConfigs(proxy_host, ...)重新生成其配置再执行internalNginx.reload()热重载删除先将引用该列表的所有代理主机的access_list_id置为 0即解除绑定再重新生成配置、重载 Nginx最后删除凭据文件并写入审计日志。因此访问列表的任何变更都会即时生效无需手动干预 Nginx。通过 REST API 管理访问列表除了 Web 界面访问列表也提供完整的 REST API路由定义见 routes/nginx/access_lists.js方法路径说明GET/api/nginx/access-lists获取全部访问列表支持expand与query按名称模糊搜索参数POST/api/nginx/access-lists创建访问列表返回 201GET/api/nginx/access-lists/:list_id获取单个访问列表详情支持expand参数PUT/api/nginx/access-lists/:list_id更新访问列表名称、凭据、规则等DELETE/api/nginx/access-lists/:list_id删除访问列表并解绑其代理主机创建与更新的请求体结构可参考 OpenAPI 组件定义 access-list-object.json{ name: My Access List, satisfy_any: true, pass_auth: false, items: [ { username: admin, password: secret } ], clients: [ { directive: allow, address: 192.168.1.10 }, { directive: deny, address: 10.0.0.0/8 } ] }前端对应的 API 封装位于 frontend/src/api/backend如createAccessList.ts、updateAccessList.ts、getAccessLists.ts等可通过expand参数按需加载关联的owner、items、clients与proxy_hosts数据。权限控制访问列表的操作权限由角色与细粒度权限共同约束定义见 backend/lib/access 下的access_lists-*.json拥有admin角色的用户可直接管理所有访问列表普通user角色用户需要具备permission_access_lists权限——查看view可执行get/list管理manage可执行create/update/delete当用户的权限可见性permission_visibility不是all时后端查询会自动限定owner_user_id为当前用户即普通用户只能看到和管理自己创建的列表见 internal/access-list.js。每一次创建、更新、删除操作都会写入审计日志action: created / updated / deletedobject_type: access-list便于事后追溯。典型场景与使用建议结合官方文档的定位与源码行为推荐以下实践为无认证的后端服务加锁诸如内部状态页、管理后台、未做鉴权的 API 等直接暴露给公网的服务为其代理主机挂载一个只含凭据的访问列表即可快速补上身份校验避免自行改造应用内网白名单仅允许办公网段访问时配置一条allow 10.0.0.0/8规则列表末尾自动deny all并保持Satisfy Any关闭即可实现严格的来源限定白名单 认证双保险保持默认的satisfy all让客户端同时通过 IP 校验与 Basic 认证适合安全要求较高的场景灵活兜底开启Satisfy Any后白名单外用户仍可通过正确凭据访问适合「优先放行内网、外部凭据访问」的混合策略保护后端凭据若上游服务不应接触 Basic 凭据关闭Pass Auth让认证信息在 Nginx 层即被消费。总结访问列表是 Nginx Proxy Manager 中「一次配置、多处复用」的访问控制单元将 IP 黑白名单allow/deny与 HTTP Basic 认证用户名密码统一封装并通过satisfy_any、pass_auth两个开关灵活组合。其底层由access_list/access_list_auth/access_list_client三张表驱动后端自动生成 apr1 格式的 htpasswd 凭据文件与 Nginx 访问控制指令并在每次变更后自动重载生效。无论是通过 Web 界面还是 REST API你都可以快速为任意数量的代理主机套上可靠的访问防线。更多细节可继续阅读官方帮助文档、后端实现、Nginx 模板、前端表单组件。【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Nginx Proxy Manager 访问列表（Access List）完全指南：IP 黑白名单与 Basic Auth 认证实战
Nginx Proxy Manager 访问列表Access List完全指南IP 黑白名单与 Basic Auth 认证实战【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager访问列表Access List是 Nginx Proxy Manager 中面向反向代理主机的一站式访问控制方案它把「特定客户端 IP 的黑名单 / 白名单」与「基于 HTTP Basic 认证的用户名密码校验」合并在一个可复用的配置单元里随后可以绑定到一个或多个代理主机Proxy Host上。读完本文你将掌握访问列表的核心概念、字段含义、底层 Nginx 配置生成原理、Web 界面与 REST API 的完整操作方式以及它在保护无内置认证机制的服务时的最佳实践。本文以仓库中的官方帮助文档 AccessLists.md 为骨架结合后端源码与模板实现进行深度展开。什么是访问列表Access List根据官方帮助文档的定义访问列表向代理主机提供两类核心能力特定客户端 IP 的黑名单blacklist与白名单whitelist通过为每个 IP 地址或地址段指定allow/deny指令精确控制哪些来源可以访问被代理的后端服务基于 HTTP Basic 认证的身份校验为一组「用户名 密码」建立凭据库客户端访问代理主机时必须通过认证才能继续。原文要点访问列表为代理主机提供特定客户端 IP 的黑名单与白名单并通过 Basic HTTP 认证实现身份校验。你可以在单个访问列表中配置多条客户端规则、多个用户名与密码然后将该列表应用于一个或多个代理主机。这对没有内置认证机制的转发 Web 服务或需要防范未知客户端访问的场景最为有用。这种设计的关键在于可复用性一次配置、多处挂载。运维人员不必为每个代理主机重复录入认证信息只需维护一份访问列表并在多个代理主机上引用它即可。核心概念与数据模型从数据库与后端源码看访问列表由三张表共同支撑见 models/access_list.js、models/access_list_auth.js、models/access_list_client.js表名作用关键字段access_list访问列表本体id、name、satisfy_any、pass_auth、owner_user_id、is_deletedaccess_list_authBasic 认证凭据itemsaccess_list_id、username、passwordaccess_list_clientIP 访问规则clientsaccess_list_id、address、directive其中access_list_auth通过access_list_id与列表关联一个列表可含多条凭据access_list_client同样通过access_list_id关联一个列表可含多条allow/deny规则access_list还通过proxy_host.access_list_id与代理主机表建立一对多关联这正是「一个列表绑定多个代理主机」的实现基础见 models/access_list.js 中的items、clients、proxy_hosts关系映射。satisfy_any与pass_auth是布尔字段在数据库中分别由迁移 20200410143839_access_list_client.js新增satify_any默认 0和 20201014143841_pass_auth.js新增pass_auth默认 1引入模型层通过 helpers.js 的布尔转换逻辑在读写时自动完成 0/1 与true/false的互转。关键配置项详解在 Web 界面的访问列表编辑弹窗AccessListModal.tsx中表单被划分为「详情 / 认证 / 规则」三个页签对应以下核心配置项name列表名称访问列表的名称用于在管理界面中辨识。前端校验要求 1255 个字符见 AccessListModal.tsx。satisfy_any满足任一 / 全部控制 IP 规则与 Basic 认证之间的组合逻辑这是最容易踩坑的选项关闭satisfy all默认客户端必须同时满足 IP 白名单规则且通过 Basic 认证才允许访问开启satisfy any客户端只需满足任一条件即可放行——例如在白名单 IP 内可直接访问或者虽不在白名单但提供了正确的用户名密码也能访问。该开关直接映射到生成的 Nginx 配置中的satisfy any;/satisfy all;指令见 templates/_access.conf。需要特别说明的是satisfy指令仅对allow/denyIP 访问控制与auth_basicHTTP 认证同时存在时才有意义若列表中只配置了凭据或只配置了 IP 规则则该选项不产生实际影响。pass_auth透传认证头控制 Basic 认证通过后Authorization请求头是否继续转发给后端服务开启默认值为 1后端服务可以继续收到客户端的Authorization头适合后端自身也依赖该头做身份识别的场景例如将 Basic 凭据透传给上游应用关闭值为 0在认证通过后主动清空Authorization头proxy_set_header Authorization ;避免将敏感凭据泄露给上游。对应的模板逻辑见 templates/_access.conf。itemsBasic 认证凭据一组「用户名 密码」对构成 Basic 认证的凭据库。同一访问列表中可以配置多条凭据任意一组通过校验即可对应access_list_auth表。密码在管理界面中会以脱敏形式展示后端在返回数据时用maskItems方法将其替换为「首字符 星号」的提示串见 internal/access-list.js真实密码仅在创建或更新时提交一次。clientsIP 访问规则一组「directive address」规则对构成 IP 黑白名单对应access_list_client表directiveallow放行或deny拒绝address目标 IP 或地址段例如192.168.1.10、10.0.0.0/8。规则按书写顺序自上而下匹配匹配到第一条即生效列表末尾固定追加一条不可编辑的deny all见 AccessClientFields.tsx这与 Nginx 的访问控制语义完全一致。Web 界面操作流程在 Nginx Proxy Manager 管理后台中访问列表的完整使用流程如下第一步创建访问列表进入「Access Lists」页面点击新建按钮打开弹窗填写列表名称并根据需要切换Satisfy Any与Pass Auth两个开关见 AccessListModal.tsx。第二步配置认证凭据切换到「Authorizations」页签通过 BasicAuthFields.tsx 添加一组或多组用户名与密码。若目标服务没有内置认证机制这是为其「套上」身份校验的最直接方式。第三步配置 IP 规则切换到「Rules」页签通过 AccessClientFields.tsx 按顺序添加allow/deny规则并填写 IP 地址。界面提示规则按顺序生效且最后一条恒为deny all。第四步应用到代理主机进入某个代理主机的编辑页面在访问列表字段中选择刚创建的列表并保存。前端提交时会把items与clients分别精简为「username/password」与「directive/address」结构后发送到后端见 AccessListModal.tsx后端随后自动重新生成相关代理主机的 Nginx 配置并重载。创建时必须保证「认证凭据」与「IP 规则」至少配置一项否则前端会提示错误error.access.at-least-one见 AccessListModal.tsx同时用户名不可重复。底层原理配置如何生成并生效访问列表的完整生效链路分为「凭据文件生成」与「Nginx 配置渲染」两步。htpasswd 凭据文件生成后端在创建或更新访问列表时会调用 internal/access-list.js 的build方法先删除旧文件再为每条凭据执行openssl passwd -apr1生成 APACHE-MD5apr1格式的密码哈希并逐行写入/data/access/{列表ID}文件username:hashed_password格式。该文件即 Nginxauth_basic_user_file指令引用的凭据库。删除访问列表时对应的凭据文件也会被同步清理见 internal/access-list.js。Nginx 配置模板渲染代理主机的 Nginx 配置模板 templates/proxy_host.conf 在默认location /块中引入 templates/_access.conf其渲染逻辑如下# 仅当列表被引用且包含凭据时启用 Basic 认证 auth_basic Authorization required; auth_basic_user_file /data/access/{{ access_list_id }}; # pass_auth 关闭时清空认证头 proxy_set_header Authorization ; # 按顺序输出每条 allow/deny 规则最后追加 deny all allow 192.168.1.10; deny 10.0.0.0/8; deny all; # 组合逻辑satisfy any / satisfy all其中每条规则由 lib/utils.js 注册的 Liquid 过滤器nginxAccessRule拼装为directive address;形式。规则末尾的deny all由模板本身固定追加见 templates/_access.conf。配置再生成与热重载访问列表的每次增删改都会触发级联操作见 internal/access-list.js创建 / 更新重新获取引用该列表的所有代理主机调用internalNginx.bulkGenerateConfigs(proxy_host, ...)重新生成其配置再执行internalNginx.reload()热重载删除先将引用该列表的所有代理主机的access_list_id置为 0即解除绑定再重新生成配置、重载 Nginx最后删除凭据文件并写入审计日志。因此访问列表的任何变更都会即时生效无需手动干预 Nginx。通过 REST API 管理访问列表除了 Web 界面访问列表也提供完整的 REST API路由定义见 routes/nginx/access_lists.js方法路径说明GET/api/nginx/access-lists获取全部访问列表支持expand与query按名称模糊搜索参数POST/api/nginx/access-lists创建访问列表返回 201GET/api/nginx/access-lists/:list_id获取单个访问列表详情支持expand参数PUT/api/nginx/access-lists/:list_id更新访问列表名称、凭据、规则等DELETE/api/nginx/access-lists/:list_id删除访问列表并解绑其代理主机创建与更新的请求体结构可参考 OpenAPI 组件定义 access-list-object.json{ name: My Access List, satisfy_any: true, pass_auth: false, items: [ { username: admin, password: secret } ], clients: [ { directive: allow, address: 192.168.1.10 }, { directive: deny, address: 10.0.0.0/8 } ] }前端对应的 API 封装位于 frontend/src/api/backend如createAccessList.ts、updateAccessList.ts、getAccessLists.ts等可通过expand参数按需加载关联的owner、items、clients与proxy_hosts数据。权限控制访问列表的操作权限由角色与细粒度权限共同约束定义见 backend/lib/access 下的access_lists-*.json拥有admin角色的用户可直接管理所有访问列表普通user角色用户需要具备permission_access_lists权限——查看view可执行get/list管理manage可执行create/update/delete当用户的权限可见性permission_visibility不是all时后端查询会自动限定owner_user_id为当前用户即普通用户只能看到和管理自己创建的列表见 internal/access-list.js。每一次创建、更新、删除操作都会写入审计日志action: created / updated / deletedobject_type: access-list便于事后追溯。典型场景与使用建议结合官方文档的定位与源码行为推荐以下实践为无认证的后端服务加锁诸如内部状态页、管理后台、未做鉴权的 API 等直接暴露给公网的服务为其代理主机挂载一个只含凭据的访问列表即可快速补上身份校验避免自行改造应用内网白名单仅允许办公网段访问时配置一条allow 10.0.0.0/8规则列表末尾自动deny all并保持Satisfy Any关闭即可实现严格的来源限定白名单 认证双保险保持默认的satisfy all让客户端同时通过 IP 校验与 Basic 认证适合安全要求较高的场景灵活兜底开启Satisfy Any后白名单外用户仍可通过正确凭据访问适合「优先放行内网、外部凭据访问」的混合策略保护后端凭据若上游服务不应接触 Basic 凭据关闭Pass Auth让认证信息在 Nginx 层即被消费。总结访问列表是 Nginx Proxy Manager 中「一次配置、多处复用」的访问控制单元将 IP 黑白名单allow/deny与 HTTP Basic 认证用户名密码统一封装并通过satisfy_any、pass_auth两个开关灵活组合。其底层由access_list/access_list_auth/access_list_client三张表驱动后端自动生成 apr1 格式的 htpasswd 凭据文件与 Nginx 访问控制指令并在每次变更后自动重载生效。无论是通过 Web 界面还是 REST API你都可以快速为任意数量的代理主机套上可靠的访问防线。更多细节可继续阅读官方帮助文档、后端实现、Nginx 模板、前端表单组件。【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考