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 中用于保护 Proxy Host 的核心安全机制它通过客户端 IP 黑/白名单与Basic HTTP Authentication基本认证两种手段为没有内置认证能力的转发服务提供访问控制。本文将基于本仓库的官方帮助文档frontend/src/locale/src/HelpDoc/hu/AccessLists.md结合后端模型、Nginx 模板与前端表单源码系统讲解访问列表的组成、配置项、底层实现原理及实战操作步骤帮助你为任意一个或多个代理主机快速建立可复用的访问控制策略。什么是访问列表根据官方帮助文档的定义访问列表为指定的客户端 IP 地址提供黑名单blacklist或白名单whitelist同时通过 Basic HTTP Authentication 为 Proxy Host 提供认证能力。一条访问列表可以同时包含三类规则认证凭据Auth Items一组用户名与密码供 Basic Auth 校验使用客户端规则Client Rules针对特定 IP 地址的allow允许或deny拒绝指令匹配策略Satisfy当同时配置了认证与 IP 规则时决定是满足任一条件即放行还是全部满足才放行。你可以为单条访问列表配置多个客户端规则、多个用户名和密码然后将这条列表应用到一个或多个 Proxy Host上。这意味着认证与 IP 限制可以被集中定义、多处复用而不是在每个主机上重复配置。从数据模型看这一设计体现得十分清晰access_list表通过itemsbackend/models/access_list_auth.js 对应的access_list_auth表保存 Basic Auth 凭据通过clientsbackend/models/access_list_client.js 对应的access_list_client表保存 IP 规则并通过proxy_hosts关系关联到使用该列表的代理主机backend/models/access_list.js。典型应用场景官方文档明确指出访问列表最适用于两类场景转发到没有内置认证机制的后端服务例如某些自建应用、内部工具没有登录体系直接在公网暴露存在风险。此时通过 Basic Auth 在 Nginx 层加一道认证无需改动后端应用代码。防止未知客户端访问通过 IP 黑白名单只允许可信来源如公司出口 IP、家庭固定 IP访问或封禁恶意来源地址。这两种能力可以叠加使用例如仅允许指定 IP 段且必须通过 Basic Auth 认证。核心配置项详解在 Nginx Proxy Manager 的 Web 界面Access Lists 页面 → Add Access List中一条访问列表包含以下配置项。这些字段的完整定义可在 OpenAPI Schema backend/schema/components/access-list-object.json 与前端类型定义 frontend/src/api/backend/models.ts 中查到。列表基本信息字段类型说明namestring访问列表的名称用于在界面中区分不同列表例如My Access Listsatisfy_anyboolean匹配策略开关。true表示任一规则满足即放行satisfy anyfalse表示全部规则满足才放行satisfy all默认示例值为truepass_authboolean是否向后端传递认证头。false表示剥离Authorization头默认true表示透传其中satisfy_any与pass_auth在后端模型 backend/models/access_list.js 中被显式声明为布尔字段satisfy_any、pass_auth并会在数据库读写时进行布尔与整数的自动转换。认证凭据Basic Auth Items每个凭据包含两个字段Username登录用户名同一列表内不能重复前端在 AccessListModal.tsx 中有去重校验Password登录密码。编辑已存在的列表时密码字段留空表示保留原密码不修改后端 backend/internal/access-list.js 中会区分空密码保留与有密码新增两种逻辑。客户端规则Client Rules每条规则包含两个字段Directiveallow允许或deny拒绝对应 Nginx 的allow/deny指令AddressIP 地址或网段支持1.2.3.4、1.2.3.0/24等 Nginx 兼容格式。前端表单 AccessClientFields.tsx 中默认新增的规则是allow 空地址且会在规则列表末尾自动追加一条不可删除的deny allfrontend/src/components/Form/AccessClientFields.tsx。这正体现了白名单思路先显式允许可信来源其余全部拒绝。实战操作步骤第一步创建访问列表登录 Nginx Proxy Manager 管理界面进入左侧菜单Access Lists点击Add Access List打开编辑弹窗对应前端组件 AccessListModal.tsx填写列表名称在Authorization区块添加一个或多个用户名/密码对应组件 BasicAuthFields.tsx在Access区块添加客户端 IP 规则对应组件 AccessClientFields.tsx系统会自动追加deny all兜底规则按需开启Satisfy Any与Pass Auth开关保存。若未填写任何凭据与客户端规则前端会提示至少需要一条认证或客户端规则frontend/src/modals/AccessListModal.tsx。第二步将访问列表应用到 Proxy Host进入Hosts → Proxy Hosts编辑或新建目标代理主机在Access List下拉框中选择刚创建的列表保存后Nginx 配置会自动重新生成并热重载。从后端实现看保存访问列表后会触发相关主机的配置重新生成backend/internal/access-list.js新增、更新、删除访问列表都会调用internalNginx.bulkGenerateConfigs/internalNginx.reload()backend/internal/access-list.js因此修改即刻生效无需手动重启。第三步验证效果访问被保护的域名浏览器会弹出 Basic Auth 登录框使用列表中的用户名/密码可正常访问从未被允许的 IP 访问将收到 403 Forbidden可在/data/logs/proxy-host-id_access.log中查看对应主机的访问日志见 backend/templates/proxy_host.conf。底层原理从数据库到 Nginx 配置数据存储结构访问列表涉及三张数据表表字段作用access_listid、name、satisfy_any、pass_auth、owner_user_id、is_deleted列表主表保存元信息access_list_authaccess_list_id、username、passwordBasic Auth 凭据密码以 APR1openssl passwd -apr1格式哈希存储access_list_clientaccess_list_id、address、directiveIP 黑白名单规则凭据表与客户端表的建表迁移分别见 backend/migrations/20200410143839_access_list_client.js 及同批次的access_list_auth迁移。主模型 backend/models/access_list.js 通过 Objection.js 的HasManyRelation关联items与clients并通过proxy_hosts反向关联使用该列表的代理主机。凭据文件的生成当访问列表创建或更新时后端会执行build流程backend/internal/access-list.js删除旧的凭据文件/data/access/list_id创建空文件对每个用户名调用openssl passwd -apr1生成 APR1 哈希追加写入用户名:哈希格式的行。这个文件就是 Nginxauth_basic_user_file指令指向的 htpasswd 文件。删除访问列表时该文件也会被同步删除backend/internal/access-list.js避免遗留孤儿文件。Nginx 模板如何消费访问列表代理主机的 Nginx 配置由 backend/templates/proxy_host.conf 生成其中通过{% include _access.conf %}引入访问控制片段backend/templates/proxy_host.conf。核心模板 backend/templates/_access.conf 的逻辑如下Basic Auth 生效若列表存在且包含认证凭据则生成auth_basic Authorization required; auth_basic_user_file /data/access/{{ access_list_id }};若pass_auth为 false还会追加proxy_set_header Authorization ;将认证头剥离避免后端收到无关的Authorization头。IP 规则生效若列表包含客户端规则则逐条渲染allow/deny指令并在末尾追加deny all;allow 192.168.1.0/24; deny all;指令的渲染由 Liquid 过滤器nginxAccessRule完成backend/lib/utils.js它把directive与address拼接为合法的 Nginx 语句。匹配策略根据satisfy_any输出satisfy any;或satisfy all;决定 Basic Auth 与 IP 规则之间的逻辑关系。权限与安全细节密码掩码API 返回访问列表时密码字段会被替换为掩码提示hint形如a*******防止明文泄露backend/internal/access-list.js可见性控制非管理员用户只能看到自己创建的列表按owner_user_id过滤backend/internal/access-list.js创建列表需要access_lists:create等权限backend/lib/access/access_lists-create.json删除联动删除列表时所有引用该列表的代理主机的access_list_id会被重置为 0即解除保护并自动重新生成配置backend/internal/access-list.js。最佳实践建议优先使用白名单模式利用系统自动追加的deny all只放行明确的可信 IP确需封禁个别来源时再使用deny规则。内网服务必配 Basic Auth对没有内置登录的后端应用在 Nginx 层加一道认证是最低成本的安全兜底。合理选择 Satisfy 策略若希望IP 在白名单内或通过认证即放行开启Satisfy Any若要求必须同时满足 IP 白名单与认证通过则关闭该开关默认satisfy all语义。注意 Pass Auth 的影响默认会剥离Authorization头。如果你的后端服务本身也需要读取 Basic Auth 凭据例如自建网关需开启Pass Auth透传。用独立列表管理同类主机一条列表可被多个 Proxy Host 复用将相同安全策略的主机绑定到同一列表便于集中维护与审计。总结访问列表把IP 黑白名单与Basic HTTP Authentication两种防护能力封装为可复用的策略单元一条列表可服务多个 Proxy Host。通过本仓库的源码可以看到其底层实现非常直接凭据被哈希后写入/data/access/id的 htpasswd 文件IP 规则被渲染为 Nginx 的allow/deny指令再由satisfy any/all决定两者组合逻辑任何变更都会自动触发代理配置重新生成与热重载。掌握这一机制你就可以为无认证的后端服务快速构建可靠的访问防线。【免费下载链接】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 中用于保护 Proxy Host 的核心安全机制它通过客户端 IP 黑/白名单与Basic HTTP Authentication基本认证两种手段为没有内置认证能力的转发服务提供访问控制。本文将基于本仓库的官方帮助文档frontend/src/locale/src/HelpDoc/hu/AccessLists.md结合后端模型、Nginx 模板与前端表单源码系统讲解访问列表的组成、配置项、底层实现原理及实战操作步骤帮助你为任意一个或多个代理主机快速建立可复用的访问控制策略。什么是访问列表根据官方帮助文档的定义访问列表为指定的客户端 IP 地址提供黑名单blacklist或白名单whitelist同时通过 Basic HTTP Authentication 为 Proxy Host 提供认证能力。一条访问列表可以同时包含三类规则认证凭据Auth Items一组用户名与密码供 Basic Auth 校验使用客户端规则Client Rules针对特定 IP 地址的allow允许或deny拒绝指令匹配策略Satisfy当同时配置了认证与 IP 规则时决定是满足任一条件即放行还是全部满足才放行。你可以为单条访问列表配置多个客户端规则、多个用户名和密码然后将这条列表应用到一个或多个 Proxy Host上。这意味着认证与 IP 限制可以被集中定义、多处复用而不是在每个主机上重复配置。从数据模型看这一设计体现得十分清晰access_list表通过itemsbackend/models/access_list_auth.js 对应的access_list_auth表保存 Basic Auth 凭据通过clientsbackend/models/access_list_client.js 对应的access_list_client表保存 IP 规则并通过proxy_hosts关系关联到使用该列表的代理主机backend/models/access_list.js。典型应用场景官方文档明确指出访问列表最适用于两类场景转发到没有内置认证机制的后端服务例如某些自建应用、内部工具没有登录体系直接在公网暴露存在风险。此时通过 Basic Auth 在 Nginx 层加一道认证无需改动后端应用代码。防止未知客户端访问通过 IP 黑白名单只允许可信来源如公司出口 IP、家庭固定 IP访问或封禁恶意来源地址。这两种能力可以叠加使用例如仅允许指定 IP 段且必须通过 Basic Auth 认证。核心配置项详解在 Nginx Proxy Manager 的 Web 界面Access Lists 页面 → Add Access List中一条访问列表包含以下配置项。这些字段的完整定义可在 OpenAPI Schema backend/schema/components/access-list-object.json 与前端类型定义 frontend/src/api/backend/models.ts 中查到。列表基本信息字段类型说明namestring访问列表的名称用于在界面中区分不同列表例如My Access Listsatisfy_anyboolean匹配策略开关。true表示任一规则满足即放行satisfy anyfalse表示全部规则满足才放行satisfy all默认示例值为truepass_authboolean是否向后端传递认证头。false表示剥离Authorization头默认true表示透传其中satisfy_any与pass_auth在后端模型 backend/models/access_list.js 中被显式声明为布尔字段satisfy_any、pass_auth并会在数据库读写时进行布尔与整数的自动转换。认证凭据Basic Auth Items每个凭据包含两个字段Username登录用户名同一列表内不能重复前端在 AccessListModal.tsx 中有去重校验Password登录密码。编辑已存在的列表时密码字段留空表示保留原密码不修改后端 backend/internal/access-list.js 中会区分空密码保留与有密码新增两种逻辑。客户端规则Client Rules每条规则包含两个字段Directiveallow允许或deny拒绝对应 Nginx 的allow/deny指令AddressIP 地址或网段支持1.2.3.4、1.2.3.0/24等 Nginx 兼容格式。前端表单 AccessClientFields.tsx 中默认新增的规则是allow 空地址且会在规则列表末尾自动追加一条不可删除的deny allfrontend/src/components/Form/AccessClientFields.tsx。这正体现了白名单思路先显式允许可信来源其余全部拒绝。实战操作步骤第一步创建访问列表登录 Nginx Proxy Manager 管理界面进入左侧菜单Access Lists点击Add Access List打开编辑弹窗对应前端组件 AccessListModal.tsx填写列表名称在Authorization区块添加一个或多个用户名/密码对应组件 BasicAuthFields.tsx在Access区块添加客户端 IP 规则对应组件 AccessClientFields.tsx系统会自动追加deny all兜底规则按需开启Satisfy Any与Pass Auth开关保存。若未填写任何凭据与客户端规则前端会提示至少需要一条认证或客户端规则frontend/src/modals/AccessListModal.tsx。第二步将访问列表应用到 Proxy Host进入Hosts → Proxy Hosts编辑或新建目标代理主机在Access List下拉框中选择刚创建的列表保存后Nginx 配置会自动重新生成并热重载。从后端实现看保存访问列表后会触发相关主机的配置重新生成backend/internal/access-list.js新增、更新、删除访问列表都会调用internalNginx.bulkGenerateConfigs/internalNginx.reload()backend/internal/access-list.js因此修改即刻生效无需手动重启。第三步验证效果访问被保护的域名浏览器会弹出 Basic Auth 登录框使用列表中的用户名/密码可正常访问从未被允许的 IP 访问将收到 403 Forbidden可在/data/logs/proxy-host-id_access.log中查看对应主机的访问日志见 backend/templates/proxy_host.conf。底层原理从数据库到 Nginx 配置数据存储结构访问列表涉及三张数据表表字段作用access_listid、name、satisfy_any、pass_auth、owner_user_id、is_deleted列表主表保存元信息access_list_authaccess_list_id、username、passwordBasic Auth 凭据密码以 APR1openssl passwd -apr1格式哈希存储access_list_clientaccess_list_id、address、directiveIP 黑白名单规则凭据表与客户端表的建表迁移分别见 backend/migrations/20200410143839_access_list_client.js 及同批次的access_list_auth迁移。主模型 backend/models/access_list.js 通过 Objection.js 的HasManyRelation关联items与clients并通过proxy_hosts反向关联使用该列表的代理主机。凭据文件的生成当访问列表创建或更新时后端会执行build流程backend/internal/access-list.js删除旧的凭据文件/data/access/list_id创建空文件对每个用户名调用openssl passwd -apr1生成 APR1 哈希追加写入用户名:哈希格式的行。这个文件就是 Nginxauth_basic_user_file指令指向的 htpasswd 文件。删除访问列表时该文件也会被同步删除backend/internal/access-list.js避免遗留孤儿文件。Nginx 模板如何消费访问列表代理主机的 Nginx 配置由 backend/templates/proxy_host.conf 生成其中通过{% include _access.conf %}引入访问控制片段backend/templates/proxy_host.conf。核心模板 backend/templates/_access.conf 的逻辑如下Basic Auth 生效若列表存在且包含认证凭据则生成auth_basic Authorization required; auth_basic_user_file /data/access/{{ access_list_id }};若pass_auth为 false还会追加proxy_set_header Authorization ;将认证头剥离避免后端收到无关的Authorization头。IP 规则生效若列表包含客户端规则则逐条渲染allow/deny指令并在末尾追加deny all;allow 192.168.1.0/24; deny all;指令的渲染由 Liquid 过滤器nginxAccessRule完成backend/lib/utils.js它把directive与address拼接为合法的 Nginx 语句。匹配策略根据satisfy_any输出satisfy any;或satisfy all;决定 Basic Auth 与 IP 规则之间的逻辑关系。权限与安全细节密码掩码API 返回访问列表时密码字段会被替换为掩码提示hint形如a*******防止明文泄露backend/internal/access-list.js可见性控制非管理员用户只能看到自己创建的列表按owner_user_id过滤backend/internal/access-list.js创建列表需要access_lists:create等权限backend/lib/access/access_lists-create.json删除联动删除列表时所有引用该列表的代理主机的access_list_id会被重置为 0即解除保护并自动重新生成配置backend/internal/access-list.js。最佳实践建议优先使用白名单模式利用系统自动追加的deny all只放行明确的可信 IP确需封禁个别来源时再使用deny规则。内网服务必配 Basic Auth对没有内置登录的后端应用在 Nginx 层加一道认证是最低成本的安全兜底。合理选择 Satisfy 策略若希望IP 在白名单内或通过认证即放行开启Satisfy Any若要求必须同时满足 IP 白名单与认证通过则关闭该开关默认satisfy all语义。注意 Pass Auth 的影响默认会剥离Authorization头。如果你的后端服务本身也需要读取 Basic Auth 凭据例如自建网关需开启Pass Auth透传。用独立列表管理同类主机一条列表可被多个 Proxy Host 复用将相同安全策略的主机绑定到同一列表便于集中维护与审计。总结访问列表把IP 黑白名单与Basic HTTP Authentication两种防护能力封装为可复用的策略单元一条列表可服务多个 Proxy Host。通过本仓库的源码可以看到其底层实现非常直接凭据被哈希后写入/data/access/id的 htpasswd 文件IP 规则被渲染为 Nginx 的allow/deny指令再由satisfy any/all决定两者组合逻辑任何变更都会自动触发代理配置重新生成与热重载。掌握这一机制你就可以为无认证的后端服务快速构建可靠的访问防线。【免费下载链接】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），仅供参考
