Nginx Proxy Manager 通信规则Access Lists完全指南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 提供黑名单/白名单过滤又能通过 HTTP 基本认证Basic HTTP Authentication为转发服务加上一层登录校验。本文将围绕该功能从概念、UI 配置、数据模型到 Nginx 配置生成原理逐一拆解并结合本仓库源码后端模型、内部逻辑、Liquid 模板与前端表单给出可验证的实战依据。什么是通信规则Access List按照官方帮助文档frontend/src/locale/src/HelpDoc/zh/AccessLists.md的定义通信规则为Proxy Host提供特定客户端 IP 地址的黑名单或白名单同时提供基于HTTP 基本认证Basic HTTP Authentication的访问认证你可以为一个通信规则配置多个客户端规则IP 规则和多组用户名/密码然后将这个规则批量应用到一个或多个 Proxy Host上。它最有用的场景是后端转发服务本身没有内置认证机制或者你希望将某些未知客户端挡在门外。例如内网运维面板、未带登录态的个人工具站、临时对外开放的测试环境等都可以通过通信规则在 Nginx 入口层统一收口而不必改动业务应用代码。核心能力拆解两种防线通信规则在 Nginx 层实际生成两套相互独立又可叠加的防线防线实现机制作用对象IP 黑白名单Nginxallow/deny指令按顺序匹配最后兜底deny all客户端来源地址用户名/密码认证auth_basicauth_basic_user_filehtpasswd 文件请求的Authorization头在 backend/templates/_access.conf 模板中可以看到两者的真实输出形态{% if access_list_id 0 %} {% if access_list.items.length 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 %} {% endif %} {% if access_list.clients.length 0 %} # Access Rules: {{ access_list.clients | size }} total {% for client in access_list.clients %} {{client | nginxAccessRule}} {% endfor %} deny all; {% endif %} # Access checks must... {% if access_list.satisfy_any 1 or access_list.satisfy_any true %} satisfy any; {% else %} satisfy all; {% endif %} {% endif %}模板揭示了几个关键点认证文件路径固定为/data/access/access_list_id与后端getFilename()见下文一致pass_auth决定是否向上游转发 Basic Auth 凭据当pass_auth关闭时会追加proxy_set_header Authorization ;抹掉认证头避免业务后端拿到无意义的凭据IP 规则列表之后固定追加deny all;即“默认拒绝只放行你显式 allow 的地址”这正是白名单语义的落地方式satisfy any/all控制两类防线的关系satisfy any表示“IP 通过或认证通过”即可进入satisfy all表示必须“IP 通过且认证通过”才允许访问。{{client | nginxAccessRule}}这个 Liquid 过滤器定义在 backend/lib/utils.js逻辑极简——把directive和address拼成allow address;或deny address;renderEngine.registerFilter(nginxAccessRule, (v) { if (typeof v.directive ! undefined typeof v.address ! undefined v.directive v.address) { return ${v.directive} ${v.address};; } return ; });也就是说规则地址的写法遵循 Nginxallow/deny指令的语法支持单个 IP 或网段如 CIDR 形式。一个规则包含哪些配置项从前端模型 frontend/src/api/backend/models.ts 可以看出Access List 的主体结构为export interface AccessList { id?: number; name: string; satisfyAny: boolean; // 满足任一条件即可 passAuth: boolean; // 是否透传 Authorization 头 proxyHostCount?: number; owner?: User; items?: AccessListItem[]; // 认证用户列表 clients?: AccessListClient[]; // IP 规则列表 } export interface AccessListItem { username: string; password: string; hint?: string; } export type AccessListClient { address: string; directive: allow | deny; };对应后端access_list表backend/models/access_list.js核心字段含义如下字段类型含义namestring规则名称用于在代理主机表单中标识satisfy_anybooleantrue 满足任一条件即可anyfalse 必须全部满足allpass_authbooleantrue 将 Basic Auth 凭据继续转发给上游false 在上游前清空Authorization头items子表access_list_auth认证用户名/密码集合clients子表access_list_clientIP 黑白名单规则集合directiveaddress注意satisfy_any、pass_auth两个布尔字段在数据库中以 0/1 存储由模型的boolFields在读写时自动转换见 backend/models/access_list.js。实战操作在 UI 中创建通信规则创建/编辑入口在Access Lists页面前端由 frontend/src/modals/AccessListModal.tsx 实现表单分为三个页签1. Details详情Name名称必填长度 1255前端校验见validateString(1, 255)Satisfy Any开关对应satisfyAnyPass Auth开关对应passAuth。2. Authorizations认证用户对应 frontend/src/components/Form/BasicAuthFields.tsx逐行添加用户名 密码可添加多组。编辑已有规则时密码框会显示••••••••占位说明后端不会回传明文密码——密码在后端被掩码处理maskItems仅返回hint提示。3. RulesIP 规则对应 frontend/src/components/Form/AccessClientFields.tsx每行由directiveallow / deny address地址组成规则按从上到下的顺序匹配界面文案会提示“规则按顺序匹配”最后一行固定显示一条不可编辑的deny all确保未匹配到的客户端被默认拒绝。前端提交时会做两层校验AccessListModal.tsxitems与clients至少其一非空否则报错error.access.at-least-oneitems中的用户名不得重复否则报错error.access.duplicate-usernames。数据模型与底层存储表结构与关联Access List 在后端由三张表 两张关联表组成见 backend/models/access_list.js 的relationMappingsaccess_list规则主表含owner_user_id归属用户access_list_auth认证用户子表access_list_id→username/passwordaccess_list_clientIP 规则子表access_list_id→directive/address由迁移 backend/migrations/20200410143839_access_list_client.js 引入proxy_host代理主机通过access_list_id外键引用规则一个规则可被多个主机引用user规则所有者。后端内部逻辑集中在 backend/internal/access-list.js提供create/update/get/getAll/delete/build等方法并在创建、更新、删除时自动触发代理主机配置重生成与 Nginx reload创建写入主表与子表后若该规则已被主机引用则bulkGenerateConfigs(proxy_host, ...)更新先删除旧子表数据再按需插入密码留空表示“保留原密码不修改”随后重新生成配置并reload()删除将引用该规则的主机access_list_id置 0、重新生成配置、删除 htpasswd 文件并 reload。htpasswd 文件如何生成build()方法backend/internal/access-list.js会删除并重建/data/access/id文件对每个用户名调用openssl passwd -apr1 password生成Apache MD5APR1格式的密码哈希以username:hash形式逐行追加写入 htpasswd 文件。utils.execFile(openssl, [passwd, -apr1, item.password]) .then((res) { fs.appendFileSync(htpasswdFile, ${item.username}:${res}\n, { encoding: utf8 }); })这就是auth_basic_user_file /data/access/id能生效的根本原因。而maskItems()同上文件 backend/internal/access-list.js则在所有 API 返回中把password置空、仅保留hint首字符 星号避免明文密码泄露到前端或审计日志。将规则应用到代理主机创建好通信规则后在Proxy Host的编辑表单中选择该规则即可生效一个规则可复用于多个主机。代理主机是 Nginx Proxy Manager 中最常见的转发形态其模型backend/models/proxy_host.js通过access_list_id与规则关联。实际请求链路为客户端 → Nginx 监听端口Proxy Host 的 server 块 → 命中 access_list_access.conf 片段被 include 进 proxy_host 配置 → 通过 IP 规则 Basic Auth 双重校验satisfy any/all 决定关系 → 反向代理转发到上游服务由于规则变更会自动触发引用主机的配置重生成并 reload因此同一套黑白名单/账号体系可以一次配置、多处复用这正是文档所说“为单个规则配置多个客户规则、用户名和密码然后应用于一个或多个代理主机”的实现方式。API 与权限控制通信规则通过 REST API 暴露路径前缀/nginx/access-lists见 backend/routes/nginx/access_lists.js支持GET列表/单个、POST创建、PUT更新、DELETE删除对应的 OpenAPI 定义位于 backend/schema/paths/nginx/access-lists/ 与 backend/lib/access/access_lists-*.json 系列文件。权限方面创建规则要求access_lists:create权限且访问控制要求用户具备permission_access_lists: manage角色见 backend/lib/access/access_lists-create.json。在get/getAll中若当前用户的permission_visibility不是all查询会追加access_list.owner_user_id 当前用户过滤backend/internal/access-list.js即普通用户只能看到和管理自己创建的规则管理员才可见全部。最佳实践与注意事项明确“any 还是 all”只想挡恶意 IP、其余访问者直接放行用satisfy any既限定来源又要求登录用satisfy all白名单场景记得保留兜底deny all模板会在规则列表末尾自动追加deny all界面上的最后一行灰色不可编辑就是它的可视化呈现规则顺序敏感Nginxallow/deny按声明顺序匹配多条规则请把更精确的放前面pass_auth与上游兼容性如果上游服务也需要 Basic Auth 凭据请开启pass_auth如果上游只是普通 Web 服务保持关闭可避免多余请求头删除规则前先确认引用删除被主机引用的规则会自动把这些主机的access_list_id置 0访问控制失效操作前应评估影响面密码不回显编辑已有规则时密码留空即表示保留原密码这正是update()中“空密码不修改”分支backend/internal/access-list.js的设计意图。总结通信规则Access List是 Nginx Proxy Manager 在 Nginx 入口层提供的一套轻量级访问控制方案一条规则内可同时承载IP 黑白名单与多账号 Basic Auth 认证通过satisfy any/all灵活组合再以“一规则多主机”的方式批量复用。其能力边界、配置字段与联动行为均可在本仓库的后端模型、_access.conf模板与前端表单代码中得到验证适合为缺乏认证机制的内网服务或对外暴露的站点快速加上第一道防线。【免费下载链接】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），仅供参考