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 ManagerNPM中用于管控代理主机Proxy Host入口流量的核心安全机制通过客户端 IP 地址的黑名单/白名单规则配合基于 Basic HTTP Authentication 的用户名密码认证为一层不设防的上游 Web 服务提供独立于应用自身的访问控制。本文以官方帮助文档为主线结合本项目后端源码access-list.js、模型定义、Nginx 模板与 OpenAPI 定义完整讲解访问列表的概念、配置项、创建流程、底层实现原理以及真实可用的 API 调用示例帮助你为每个代理主机量身定制访问策略。什么是访问列表根据官方文档AccessLists.md的定义访问列表允许你创建一份针对客户端 IP 地址的黑名单或白名单同时通过Basic HTTP AuthenticationHTTP 基本认证为代理主机提供用户名/密码级别的认证能力。其核心特征包括一份列表多种规则单个访问列表内可以同时配置多条“客户端client规则”和多个“用户名 密码”组合一对多复用同一份访问列表可以被应用到一个或多个代理主机上规则集中维护、统一生效典型适用场景被代理的 Web 服务自身没有内置认证机制或者你希望拦截未知客户端、将访问范围限制在可信网络内。官方文档特别指出这类防护most useful for forwarded web services that do not have authentication mechanisms built in对没有内置认证机制的转发 Web 服务最为有用——这正是反向代理场景下最常见的痛点内网服务裸奔在公网不想也无法修改应用代码此时在 NPM 这一层做访问控制是最轻量的解法。访问列表的三类核心配置访问列表的配置由三个维度组成它们在数据模型access_list.js、access_list_auth.js、access_list_client.js与 OpenAPI 请求体createAccessList中均有完整对应配置维度字段说明基本属性name列表名称必填如My Access List认证用户items数组每项包含username与password用于 Basic Auth 登录客户端规则clients数组每项包含directiveallow/deny与addressIP 或 CIDR 网段匹配模式satisfy_anytrue表示任一规则满足即放行satisfy any;false表示所有规则必须满足satisfy all;认证透传pass_authfalse时后端会清空Authorization请求头proxy_set_header Authorization ;默认true透传从数据库迁移记录可以确认字段的演进历史客户端规则由 20200410143839_access_list_client.js 引入同时新增satify_any字段而pass_auth由 20201014143841_pass_auth.js 在 2020 年加入默认值为1即默认透传认证信息。创建访问列表前端表单与 API 请求前端操作路径在 Web 界面中进入Access Lists访问列表页面点击新建即可配置填写名称、添加若干客户端规则选择Allow或Deny指令并输入 IP/CIDR 地址、添加若干用户名密码条目。前端提交时会把clients精简为directive与address两个字段见 AccessListModal.tsx与后端期望的数据结构完全一致。完整 API 请求示例以下 POST 请求创建一份同时具备 IP 白名单与 Basic Auth 的访问列表示例取自 post.json 的官方 examplePOST /api/nginx/access-lists Content-Type: application/json Authorization: Bearer token { name: My Access List, satisfy_any: true, pass_auth: false, items: [ { username: admin, password: pass } ], clients: [ { directive: allow, address: 192.168.0.0/24 } ] }请求体 schema 的完整字段均通过$ref引用公共定义name字符串必填列表名称satisfy_any布尔值匹配模式pass_auth布尔值是否把认证头透传给上游items认证用户数组access_items元素为{ username, password }clients客户端规则数组access_clients元素为{ directive, address }。服务端创建流程路由 access_lists.js 将 POST 请求交给internalAccessList.createaccess-list.js其内部执行顺序为权限校验access.can(access_lists:create)插入access_list主记录name、satisfy_any、pass_auth、owner_user_id并行插入所有items到access_list_auth表串行插入所有clients到access_list_client表重新拉取完整数据含owner/items/clients/proxy_hosts扩展调用internalAccessList.build生成 htpasswd 文件若该列表已被代理主机引用proxy_host_count 0触发bulkGenerateConfigs重新生成这些主机的 Nginx 配置写入审计日志action: created并返回脱敏后的结果。底层实现原理从数据库到 Nginx 配置数据模型三表结构访问列表在数据库中由三张表协作完成表模型文件职责access_listaccess_list.js列表主表持有name、satisfy_any、pass_auth、owner_user_id布尔字段在读写数据库时自动与 0/1 互转access_list_authaccess_list_auth.js认证用户表每行一个username/password组合access_list_clientaccess_list_client.js客户端规则表每行一个directiveaddress主表通过 Objection.js 的关系映射关联三张子表itemsHasMany →access_list_auth、clientsHasMany →access_list_client、proxy_hostsHasMany →proxy_host以access_list_id关联。需要说明的是虽然文档称其为黑名单或白名单但clients表中的directive字段实际支持allow与deny两种取值且同一列表内可以混合使用多条规则。htpasswd 文件生成build方法access-list.js负责把认证用户写入/data/access/list_id文件删除旧文件并创建空文件对每个用户调用openssl passwd -apr1 password生成APR1Apache MD5格式的密码哈希以用户名:哈希的格式逐行追加写入。写入完成后该文件路径会被模板中的auth_basic_user_file指令引用供 Nginx 的 Basic Auth 校验使用。该目录/data/access/位于 NPM 容器的持久化数据卷内。Nginx 配置模板代理主机的 Nginx 配置通过 proxy_host.conf 引入 _access.conf当access_list_id 0时生成如下关键配置# Authorization auth_basic Authorization required; auth_basic_user_file /data/access/{{ access_list_id }}; {% if access_list.pass_auth 0 or access_list.pass_auth false %} proxy_set_header Authorization ; {% endif %} # Access Rules: {{ access_list.clients | size }} total {% for client in access_list.clients %} {{client | nginxAccessRule}} {% endfor %} deny all; # Access checks must... satisfy any;逐行解读auth_basic/auth_basic_user_file启用 HTTP 基本认证并指向对应 htpasswd 文件仅当items非空时生成proxy_set_header Authorization ;当pass_auth false时清空转发给上游的认证头避免把 Basic Auth 凭据泄露给后端应用当pass_auth true时则透传可配合后端自身的认证体系使用客户端规则循环nginxAccessRule过滤器utils.js把{ directive, address }渲染为allow 192.168.0.0/24;这类标准 nginx 指令当存在客户端规则时模板末尾会追加deny all;作为兜底即白名单模式默认拒绝一切未列出的来源satisfy any;/satisfy all;由satisfy_any决定认证与 IP 规则之间的组合逻辑。satisfy any表示通过 IP 规则或认证其一即可satisfy all表示必须同时通过 IP 规则且通过认证。实际语义为任一any满足即放行全部all必须满足才放行。更新与删除的联动效应更新access-list.jsitems采用重建策略——带密码的条目直接重插password为空字符串的条目视为保留但不改密加入itemsToKeep删除时用NOT IN排除clients则整体删除后按新数组重建忽略空address。保存后若存在引用该列表的代理主机会重新生成配置并nginx.reload()热重载。删除access-list.js软删除主记录is_deleted 1同时把引用它的所有代理主机的access_list_id置为0即解绑重新生成这些主机的配置并 reload最后删除对应的/data/access/idhtpasswd 文件。密码安全API 响应的脱敏处理出于安全考虑后端在返回访问列表数据时会对密码做**脱敏masking**处理。maskItems方法access-list.js会将每个items条目的password置空并生成一个hint字段——取原密码首字符加一串*长度与原密码一致作为提示。例如密码apple会返回hint: a****、password: 。这意味着通过 API 读取列表永远拿不到明文密码前端编辑时看到的是hint只有重新输入新密码才能更新。实战配置建议结合模板语义与源码行为给出以下可直接落地的配置思路纯白名单场景只配置客户端规则如allow 10.0.0.0/8不配置认证用户。模板会自动追加deny all;实现仅内网可访问纯认证场景只配置用户名密码不配置客户端规则。此时只有auth_basic生效所有访客都需登录IP 或密码双通道设置satisfy_any: true同时配置内网白名单与认证用户——内网 IP 免登录直达公网用户需凭密码访问IP 且密码强校验设置satisfy_any: false要求客户端 IP 命中规则并且通过认证才放行适合对敏感管理后台做双重防护隐藏上游认证信息若不希望 Basic Auth 凭据到达后端服务例如后端会把Authorization头写入日志将pass_auth设为false。注意Basic Auth 的凭据以 Base64 编码传输仅在 HTTPS 加持下才是安全的。生产环境务必通过 NPM 为对应域名启用 SSL 证书否则用户名密码存在明文泄露风险。小结访问列表是 Nginx Proxy Manager 在代理层提供的一站式访问控制方案clients负责 IP 维度的放行/拦截支持allow/deny与 CIDRitems负责基于 htpasswd 文件的 Basic Auth 身份认证satisfy_any决定二者的组合逻辑pass_auth控制认证头的透传。从数据库三表结构、openssl passwd -apr1哈希生成到 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），仅供参考 
长河君 · 2026/9/11 12:21:10 · 阅读 1.2k 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 ManagerNPM中用于管控代理主机Proxy Host入口流量的核心安全机制通过客户端 IP 地址的黑名单/白名单规则配合基于 Basic HTTP Authentication 的用户名密码认证为一层不设防的上游 Web 服务提供独立于应用自身的访问控制。本文以官方帮助文档为主线结合本项目后端源码access-list.js、模型定义、Nginx 模板与 OpenAPI 定义完整讲解访问列表的概念、配置项、创建流程、底层实现原理以及真实可用的 API 调用示例帮助你为每个代理主机量身定制访问策略。什么是访问列表根据官方文档AccessLists.md的定义访问列表允许你创建一份针对客户端 IP 地址的黑名单或白名单同时通过Basic HTTP AuthenticationHTTP 基本认证为代理主机提供用户名/密码级别的认证能力。其核心特征包括一份列表多种规则单个访问列表内可以同时配置多条“客户端client规则”和多个“用户名 密码”组合一对多复用同一份访问列表可以被应用到一个或多个代理主机上规则集中维护、统一生效典型适用场景被代理的 Web 服务自身没有内置认证机制或者你希望拦截未知客户端、将访问范围限制在可信网络内。官方文档特别指出这类防护most useful for forwarded web services that do not have authentication mechanisms built in对没有内置认证机制的转发 Web 服务最为有用——这正是反向代理场景下最常见的痛点内网服务裸奔在公网不想也无法修改应用代码此时在 NPM 这一层做访问控制是最轻量的解法。访问列表的三类核心配置访问列表的配置由三个维度组成它们在数据模型access_list.js、access_list_auth.js、access_list_client.js与 OpenAPI 请求体createAccessList中均有完整对应配置维度字段说明基本属性name列表名称必填如My Access List认证用户items数组每项包含username与password用于 Basic Auth 登录客户端规则clients数组每项包含directiveallow/deny与addressIP 或 CIDR 网段匹配模式satisfy_anytrue表示任一规则满足即放行satisfy any;false表示所有规则必须满足satisfy all;认证透传pass_authfalse时后端会清空Authorization请求头proxy_set_header Authorization ;默认true透传从数据库迁移记录可以确认字段的演进历史客户端规则由 20200410143839_access_list_client.js 引入同时新增satify_any字段而pass_auth由 20201014143841_pass_auth.js 在 2020 年加入默认值为1即默认透传认证信息。创建访问列表前端表单与 API 请求前端操作路径在 Web 界面中进入Access Lists访问列表页面点击新建即可配置填写名称、添加若干客户端规则选择Allow或Deny指令并输入 IP/CIDR 地址、添加若干用户名密码条目。前端提交时会把clients精简为directive与address两个字段见 AccessListModal.tsx与后端期望的数据结构完全一致。完整 API 请求示例以下 POST 请求创建一份同时具备 IP 白名单与 Basic Auth 的访问列表示例取自 post.json 的官方 examplePOST /api/nginx/access-lists Content-Type: application/json Authorization: Bearer token { name: My Access List, satisfy_any: true, pass_auth: false, items: [ { username: admin, password: pass } ], clients: [ { directive: allow, address: 192.168.0.0/24 } ] }请求体 schema 的完整字段均通过$ref引用公共定义name字符串必填列表名称satisfy_any布尔值匹配模式pass_auth布尔值是否把认证头透传给上游items认证用户数组access_items元素为{ username, password }clients客户端规则数组access_clients元素为{ directive, address }。服务端创建流程路由 access_lists.js 将 POST 请求交给internalAccessList.createaccess-list.js其内部执行顺序为权限校验access.can(access_lists:create)插入access_list主记录name、satisfy_any、pass_auth、owner_user_id并行插入所有items到access_list_auth表串行插入所有clients到access_list_client表重新拉取完整数据含owner/items/clients/proxy_hosts扩展调用internalAccessList.build生成 htpasswd 文件若该列表已被代理主机引用proxy_host_count 0触发bulkGenerateConfigs重新生成这些主机的 Nginx 配置写入审计日志action: created并返回脱敏后的结果。底层实现原理从数据库到 Nginx 配置数据模型三表结构访问列表在数据库中由三张表协作完成表模型文件职责access_listaccess_list.js列表主表持有name、satisfy_any、pass_auth、owner_user_id布尔字段在读写数据库时自动与 0/1 互转access_list_authaccess_list_auth.js认证用户表每行一个username/password组合access_list_clientaccess_list_client.js客户端规则表每行一个directiveaddress主表通过 Objection.js 的关系映射关联三张子表itemsHasMany →access_list_auth、clientsHasMany →access_list_client、proxy_hostsHasMany →proxy_host以access_list_id关联。需要说明的是虽然文档称其为黑名单或白名单但clients表中的directive字段实际支持allow与deny两种取值且同一列表内可以混合使用多条规则。htpasswd 文件生成build方法access-list.js负责把认证用户写入/data/access/list_id文件删除旧文件并创建空文件对每个用户调用openssl passwd -apr1 password生成APR1Apache MD5格式的密码哈希以用户名:哈希的格式逐行追加写入。写入完成后该文件路径会被模板中的auth_basic_user_file指令引用供 Nginx 的 Basic Auth 校验使用。该目录/data/access/位于 NPM 容器的持久化数据卷内。Nginx 配置模板代理主机的 Nginx 配置通过 proxy_host.conf 引入 _access.conf当access_list_id 0时生成如下关键配置# Authorization auth_basic Authorization required; auth_basic_user_file /data/access/{{ access_list_id }}; {% if access_list.pass_auth 0 or access_list.pass_auth false %} proxy_set_header Authorization ; {% endif %} # Access Rules: {{ access_list.clients | size }} total {% for client in access_list.clients %} {{client | nginxAccessRule}} {% endfor %} deny all; # Access checks must... satisfy any;逐行解读auth_basic/auth_basic_user_file启用 HTTP 基本认证并指向对应 htpasswd 文件仅当items非空时生成proxy_set_header Authorization ;当pass_auth false时清空转发给上游的认证头避免把 Basic Auth 凭据泄露给后端应用当pass_auth true时则透传可配合后端自身的认证体系使用客户端规则循环nginxAccessRule过滤器utils.js把{ directive, address }渲染为allow 192.168.0.0/24;这类标准 nginx 指令当存在客户端规则时模板末尾会追加deny all;作为兜底即白名单模式默认拒绝一切未列出的来源satisfy any;/satisfy all;由satisfy_any决定认证与 IP 规则之间的组合逻辑。satisfy any表示通过 IP 规则或认证其一即可satisfy all表示必须同时通过 IP 规则且通过认证。实际语义为任一any满足即放行全部all必须满足才放行。更新与删除的联动效应更新access-list.jsitems采用重建策略——带密码的条目直接重插password为空字符串的条目视为保留但不改密加入itemsToKeep删除时用NOT IN排除clients则整体删除后按新数组重建忽略空address。保存后若存在引用该列表的代理主机会重新生成配置并nginx.reload()热重载。删除access-list.js软删除主记录is_deleted 1同时把引用它的所有代理主机的access_list_id置为0即解绑重新生成这些主机的配置并 reload最后删除对应的/data/access/idhtpasswd 文件。密码安全API 响应的脱敏处理出于安全考虑后端在返回访问列表数据时会对密码做**脱敏masking**处理。maskItems方法access-list.js会将每个items条目的password置空并生成一个hint字段——取原密码首字符加一串*长度与原密码一致作为提示。例如密码apple会返回hint: a****、password: 。这意味着通过 API 读取列表永远拿不到明文密码前端编辑时看到的是hint只有重新输入新密码才能更新。实战配置建议结合模板语义与源码行为给出以下可直接落地的配置思路纯白名单场景只配置客户端规则如allow 10.0.0.0/8不配置认证用户。模板会自动追加deny all;实现仅内网可访问纯认证场景只配置用户名密码不配置客户端规则。此时只有auth_basic生效所有访客都需登录IP 或密码双通道设置satisfy_any: true同时配置内网白名单与认证用户——内网 IP 免登录直达公网用户需凭密码访问IP 且密码强校验设置satisfy_any: false要求客户端 IP 命中规则并且通过认证才放行适合对敏感管理后台做双重防护隐藏上游认证信息若不希望 Basic Auth 凭据到达后端服务例如后端会把Authorization头写入日志将pass_auth设为false。注意Basic Auth 的凭据以 Base64 编码传输仅在 HTTPS 加持下才是安全的。生产环境务必通过 NPM 为对应域名启用 SSL 证书否则用户名密码存在明文泄露风险。小结访问列表是 Nginx Proxy Manager 在代理层提供的一站式访问控制方案clients负责 IP 维度的放行/拦截支持allow/deny与 CIDRitems负责基于 htpasswd 文件的 Basic Auth 身份认证satisfy_any决定二者的组合逻辑pass_auth控制认证头的透传。从数据库三表结构、openssl passwd -apr1哈希生成到 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），仅供参考