Nginx Proxy Manager 中的 Proxy Host：入口端点、SSL 终止与反向代理配置全解析

Nginx Proxy Manager 中的 Proxy Host入口端点、SSL 终止与反向代理配置全解析【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-managerProxy Host代理主机是 Nginx Proxy Manager 中最核心、使用最频繁的资源类型它是你想转发的外部 Web 服务进入 Nginx 的入口端点incoming endpoint。本文从官方文档对 Proxy Host 的定义出发结合当前仓库的后端实现、数据库模型与 Nginx 模板源码讲透 Proxy Host 的本质、它如何为不具备 SSL 能力的后端服务提供可选的 SSL 终止SSL termination以及一个 Proxy Host 从创建到生成 Nginx 配置的完整链路。读完本文你将能够理解 Nginx Proxy Manager 中 域名 → Proxy Host → 后端服务 这条转发链路是如何工作的并掌握 Proxy Host 各配置项在底层产生的实际效果。什么是 Proxy Host按项目内置帮助文档爱尔兰语版、英语版的定义Proxy Host 是你想转发的 Web 服务在 Nginx 上的入口端点。它本质上是一条反向代理规则外部客户端通过域名server_name访问 Nginx 的 80/443 端口Nginx 根据域名匹配到对应的 Proxy Host再将请求转发到由forward_host与forward_port指定的上游服务。文档同时强调两点关键性质可选的 SSL 终止Proxy Host 可以为那些本身没有内置 SSL 支持的后端服务提供 HTTPS 能力。SSL 证书加载、HTTPS 监听、解密都发生在 Nginx 这一侧后端服务只需要继续提供普通的 HTTP 服务即可。最常见的用途在 Nginx Proxy Manager 提供的所有主机类型Proxy Host、Redirection Host、Dead Host、Stream中Proxy Host 是日常使用最广泛的——它解决了如何用统一的域名和 HTTPS 对外暴露多个内部 Web 应用这一核心问题。对应地项目的前端帮助文档zh/ProxyHosts.md将其译为代理服务代理服务是你想转发网络应用的主机可为没有 SSL 服务的网络应用提供 SSL 服务可选。Proxy Host 在数据层的落盘一张专门的数据库表Proxy Host 在后端对应一个独立的数据库表proxy_host。从初始数据库迁移脚本可以看到其完整表结构CREATE TABLE proxy_host ( id INTEGER PRIMARY KEY, created_on DATETIME NOT NULL, modified_on DATETIME NOT NULL, owner_user_id INTEGER NOT NULL, -- 属主用户 is_deleted INTEGER NOT NULL DEFAULT 0, -- 软删除标记 domain_names JSON NOT NULL, -- 绑定的域名列表可多个 forward_ip VARCHAR NOT NULL, -- 上游主机地址forward_host forward_port INTEGER NOT NULL, -- 上游端口 access_list_id INTEGER NOT NULL DEFAULT 0, -- 访问控制列表 certificate_id INTEGER NOT NULL DEFAULT 0, -- SSL 证书 ssl_forced INTEGER NOT NULL DEFAULT 0, -- 强制 HTTPS caching_enabled INTEGER NOT NULL DEFAULT 0, -- 缓存 block_exploits INTEGER NOT NULL DEFAULT 0, -- 拦截常见攻击 advanced_config TEXT NOT NULL DEFAULT , -- 高级 Nginx 配置 meta JSON NOT NULL -- 扩展元数据 );由此表可见入口端点的三个核心要素在数据层就是三组字段对外入口domain_names一个 Proxy Host 可以绑定多个域名多个域名共用同一条转发规则对内出口forward_ipforward_port上游服务地址SSL 能力certificate_idssl_forced决定是否终止 TLS、是否强制跳转 HTTPS。对应的 Objection.js 模型位于 backend/models/proxy_host.js它通过relationMappings声明了三个关联关系owner属主用户、access_list访问控制列表、certificateSSL 证书并通过boolFields数组在读写数据库时自动完成 0/1 与true/false的互转。同时后续迁移还为proxy_host表补充了http2_support20181113041458_http2_support.js、hsts_enabled等字段这些都在前端表单的 SSL 标签页中体现。在界面上创建一个 Proxy Host四个标签页前端创建/编辑 Proxy Host 的入口是 frontend/src/modals/ProxyHostModal.tsx其表单按四个标签页组织完整覆盖了入口端点 SSL 终止的全部配置项标签页字段含义默认值DetailsdomainNames绑定的域名列表[]DetailsforwardScheme上游协议http/httpshttpDetailsforwardHost上游主机 IP/域名空DetailsforwardPort上游端口空DetailsaccessListId访问控制列表0DetailscachingEnabled启用缓存falseDetailsblockExploits拦截常见攻击falseDetailsallowWebsocketUpgrade允许 WebSocket 升级falseLocationslocations自定义 location 规则[]SSLcertificateIdSSL 证书0表示不启用0SSLsslForced强制跳转 HTTPSfalseSSLhttp2Support启用 HTTP/2falseSSLhstsEnabled启用 HSTSfalseSSLhstsSubdomainsHSTS 覆盖子域名falseSSLtrustForwardedProto信任X-Forwarded-ProtofalseAdvancedadvancedConfig追加的原始 Nginx 配置其中的forwardSchemeforwardHostforwardPort即文档所说想转发的 Web 服务Nginx 收到请求后按该协议与地址把请求代理到上游而certificateId、sslForced等 SSL 标签页字段正是为没有 SSL 能力的服务提供可选的 SSL 终止这一特性的界面入口。域名、证书、访问控制列表等还分别由 DomainNamesField.tsx、SSLCertificateField.tsx、SSLOptionsFields.tsx 等组件渲染。创建 Proxy Host 的后端链路校验 → 入库 → 生成 Nginx 配置从源码层面看创建一个 Proxy Host 的完整调用链位于 backend/internal/proxy-host.js 的create()方法共分五个阶段权限校验access.can(proxy_hosts:create, thisData)检查当前用户是否拥有创建权限权限定义见 backend/lib/access/proxy_hosts-create.json需要proxy_hosts的manage权限或 admin 角色。域名占用检查遍历domain_names逐个调用internalHost.isHostnameTaken()与已有记录比对防止同一域名被多个主机占用重复绑定会被拒绝并抛出ValidationError。数据清洗与入库通过internalHost.cleanSslHstsData()规范化 SSL/HSTS 字段advanced_config缺省时补空字符串然后proxyHostModel.query().insertAndFetch(thisData)写入数据库。快速签发证书前端可以选择certificate_id new来要求创建主机的同时一键申请 Lets Encrypt 证书此时后端会调用internalCertificate.createQuickCertificate()完成快速签发再回填certificate_id。生成 Nginx 配置并审计调用internalNginx.configure(proxyHostModel, proxy_host, row)渲染 Nginx 配置最后写入一条action: created的审计日志backend/internal/audit-log.js。创建之后的日常操作同样走这套配置生成机制update()更新数据后若主机处于启用状态则重新configureenable()重新生成配置disable()与delete()则调用internalNginx.deleteConfig()删除配置并internalNginx.reload()重载 Nginx。也就是说界面上每一次对 Proxy Host 的增删改启用禁用最终都会反映为 Nginx 配置文件的生成与重载。SSL 终止在 Nginx 层的实现从证书到监听再到强制跳转Proxy Host 的可选 SSL 终止由三个 Nginx 子模板协作完成它们被主模板逐段 include 进最终生成的 server 块。1. 监听 443 与证书加载_listen.conf _certificates.conf_listen.conf负责监听端口与 server_namelisten 80; listen [::]:80; {% if certificate -%} listen 443 ssl; # 存在证书时才监听 443 listen [::]:443 ssl; {% endif %} server_name {{ domain_names | join: }}; {% if http2_support %} http2 on; {% else %} http2 off; {% endif %}_certificates.conf负责挂载证书文件且按证书来源区分两种路径{% if certificate and certificate_id 0 -%} {% if certificate.provider letsencrypt %} # Lets Encrypt SSL ssl_certificate /etc/letsencrypt/live/npm-{{ certificate_id }}/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/npm-{{ certificate_id }}/privkey.pem; {% else %} # Custom SSL用户上传的自定义证书 ssl_certificate /data/custom_ssl/npm-{{ certificate_id }}/fullchain.pem; ssl_certificate_key /data/custom_ssl/npm-{{ certificate_id }}/privkey.pem; {% endif %} {% endif %}这正是为没有 SSL 能力的内网服务提供 HTTPS的实现原理TLS 握手与加解密全部在 Nginx 侧完成上游服务只收到明文 HTTP 请求。用户只需在 SSL 标签页选择一个证书自建 Lets Encrypt 证书或上传的自定义证书无需改动后端服务本身。2. 强制 HTTPS_forced_ssl.conf当存在证书且开启了ssl_forced时模板会设置$trust_forwarded_proto变量并引入force-ssl.conf实现 HTTP 请求 301 跳转到 HTTPS{% if certificate and certificate_id 0 -%} {% if ssl_forced 1 or ssl_forced true %} set $trust_forwarded_proto T; include conf.d/include/force-ssl.conf; {% endif %} {% endif %}注意ssl_forced依赖certificate的存在——没有证书就无从强制 HTTPS这也是为什么该选项默认关闭。3. HSTS 与 WebSocket 支持_hsts.conf / proxy_host.conf启用hsts_enabled时模板会为响应追加Strict-Transport-Security头可选覆盖子域名启用allow_websocket_upgrade时则注入 WebSocket 升级所需的三个指令proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $http_connection; proxy_http_version 1.1;这两类能力都封装在 proxy_host.conf 主模板中按字段条件化输出。生成出的最终 server 块一份完整的 Proxy Host 配置综合以上子模板一个启用了证书的 Proxy Host 最终会渲染为类似下面的 server 块主模板见 backend/templates/proxy_host.confserver { set $forward_scheme http; # 由 forwardScheme 决定 set $server 192.168.1.10; # 由 forwardHost 决定 set $port 8080; # 由 forwardPort 决定 listen 80; listen [::]:80; listen 443 ssl; # 存在证书时 listen [::]:443 ssl; server_name app.example.com; ssl_certificate /etc/letsencrypt/live/npm-1/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/npm-1/privkey.pem; # 缓存 / 攻击拦截 / HSTS / 强制 SSL 等可选块 # ... location / { # 访问控制_access.conf # 反向代理核心include conf.d/include/proxy.conf; proxy_pass $forward_scheme://$server:$port; } # 自定义 location 与高级配置{{ locations }} / {{ advanced_config }} include /data/nginx/custom/server_proxy[.]conf; }从中可以看到入口端点的完整含义server_name是入口的匹配键location /内的proxy_pass封装在 docker/rootfs/etc/nginx/conf.d/include/proxy.conf负责把请求转发给上游SSL 相关的listen 443 ssl、ssl_certificate、ssl_forced则共同构成了可选的 SSL 终止层。每个 Proxy Host 还有独立的访问日志与错误日志文件/data/logs/proxy-host-{{ id }}_access.log便于单独排障。权限、审计与常见操作Proxy Host 的使用还涉及权限体系与审计追踪权限后端按操作拆分权限点如proxy_hosts:create、proxy_hosts:update、proxy_hosts:delete、proxy_hosts:list等前端组件配合HasPermissionfrontend/src/components/HasPermission.tsx控制按钮显隐普通用户只能看到/操作自己名下的主机permission_visibility ! all时按owner_user_id过滤。审计create/update/delete/enable/disable每次操作都会写入审计日志object_type: proxy-host可在Audit Log页面回溯谁在什么时间做了什么改动相关列表接口见 frontend/src/api/backend/getAuditLogs.ts。API 层面Proxy Host 的增删改查、启停均有对应 REST 接口与 OpenAPI 描述例如 backend/lib/access/proxy_hosts-create.json权限、backend/lib/access/proxy_hosts-get.json查看前端 API 封装位于 frontend/src/api/backend/如 createProxyHost.ts、toggleProxyHost.ts。测试验证Cypress 端到端测试对 Proxy Host 的创建、转发、SSL 等行为做了完整覆盖见 test/cypress/e2e/api/ProxyHosts.cy.js。总结一句话概括 Proxy Host它是 Nginx Proxy Manager 里域名入口 反向代理 可选 SSL 终止三位一体的核心资源也是该项目最常见的应用方式。在数据层它是一张proxy_host表在界面层它是四个标签页的表单在 Nginx 层它最终渲染为一个包含server_name、listen 443 ssl、ssl_certificate与proxy_pass的 server 块。理解了这三层映射你就掌握了 Nginx Proxy Manager 反向代理与 HTTPS 终止的全部关键机制可以据此规划自己的域名转发方案。【免费下载链接】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），仅供参考