企业官网建设流程全解析

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）

根据官方帮助文档的定义，访问列表向代理主机提供两类核心能力：

1. 特定客户端 IP 的黑名单（blacklist）与白名单（whitelist）：通过为每个 IP 地址（或地址段）指定allow/deny指令，精确控制哪些来源可以访问被代理的后端服务；
2. 基于 HTTP Basic 认证的身份校验：为一组「用户名 + 密码」建立凭据库，客户端访问代理主机时必须通过认证才能继续。

原文要点：访问列表为代理主机提供特定客户端 IP 的黑名单与白名单，并通过 Basic HTTP 认证实现身份校验。你可以在单个访问列表中配置多条客户端规则、多个用户名与密码，然后将该列表应用于一个或多个代理主机。这对没有内置认证机制的转发 Web 服务，或需要防范未知客户端访问的场景最为有用。

这种设计的关键在于可复用性：一次配置、多处挂载。运维人员不必为每个代理主机重复录入认证信息，只需维护一份访问列表，并在多个代理主机上引用它即可。

核心概念与数据模型

从数据库与后端源码看，访问列表由三张表共同支撑（见 models/access_list.js、models/access_list_auth.js、models/access_list_client.js）：

其中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（列表名称）

访问列表的名称，用于在管理界面中辨识。前端校验要求 1～255 个字符（见 AccessListModal.tsx）。

satisfy_any（满足任一 / 全部）

控制 IP 规则与 Basic 认证之间的组合逻辑，这是最容易踩坑的选项：

• 关闭（satisfy all，默认）：客户端必须同时满足 IP 白名单规则且通过 Basic 认证，才允许访问；
• 开启（satisfy any）：客户端只需满足任一条件即可放行——例如在白名单 IP 内可直接访问，或者虽不在白名单但提供了正确的用户名密码也能访问。

该开关直接映射到生成的 Nginx 配置中的satisfy any;/satisfy all;指令（见 templates/_access.conf）。需要特别说明的是：satisfy指令仅对allow/deny（IP 访问控制）与auth_basic（HTTP 认证）同时存在时才有意义；若列表中只配置了凭据或只配置了 IP 规则，则该选项不产生实际影响。

pass_auth（透传认证头）

控制 Basic 认证通过后，Authorization请求头是否继续转发给后端服务：

• 开启（默认，值为 1）：后端服务可以继续收到客户端的Authorization头，适合后端自身也依赖该头做身份识别的场景（例如将 Basic 凭据透传给上游应用）；
• 关闭（值为 0）：在认证通过后主动清空Authorization头（proxy_set_header Authorization "";），避免将敏感凭据泄露给上游。

对应的模板逻辑见 templates/_access.conf。

items（Basic 认证凭据）

一组「用户名 + 密码」对，构成 Basic 认证的凭据库。同一访问列表中可以配置多条凭据，任意一组通过校验即可（对应access_list_auth表）。密码在管理界面中会以脱敏形式展示：后端在返回数据时用maskItems方法将其替换为「首字符 + 星号」的提示串（见 internal/access-list.js），真实密码仅在创建或更新时提交一次。

clients（IP 访问规则）

一组「directive + address」规则对，构成 IP 黑白名单（对应access_list_client表）：

• directive：allow（放行）或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-MD5（apr1）格式的密码哈希，并逐行写入/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）：

创建与更新的请求体结构可参考 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 / deleted，object_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