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 ManagerNPM中最核心、最常用的功能模块它为需要对外转发的 Web 服务提供一个统一入口端点并能在边缘完成可选的 SSL 终结让原本不支持 HTTPS 的后端服务也能以安全协议对外提供访问。阅读本文后你将完整掌握 Proxy Host 的概念、字段含义、创建流程以及它从一条数据库记录到一段真实 Nginx 配置的底层生成链路。什么是 Proxy HostWeb 服务的入口端点按照仓库内置帮助文档 es/ProxyHosts.md英文版见 en/ProxyHosts.md的定义Proxy Host 是你要转发的某个 Web 服务的入口端点incoming endpoint。理解这句话需要拆开两个关键词入口端点incoming endpoint对外部客户端而言Proxy Host 是一个可以被访问的地址通常表现为「域名 端口80/443」。客户端只需要访问这个地址无需关心背后真正的服务部署在哪台机器、哪个端口。转发forwardNPM 接收请求后将其按规则转发到实际提供服务的后端forward host、forward port。转发本身是反向代理的经典动作——请求先到达 Nginx 边缘再被代理到上游服务。在源码层面每一个 Proxy Host 最终都会对应一个 Nginxserver配置块。模板 backend/templates/proxy_host.conf 清晰地展示了这一结构模板通过set $forward_scheme、set $server、set $port三个变量定义转发目标再通过include conf.d/include/proxy.conf完成实际的proxy_pass动作server { set $forward_scheme {{ forward_scheme }}; set $server {{ forward_host }}; set $port {{ forward_port }}; # ... 监听、证书、安全头、强制 SSL 等片段 ... location / { # Proxy! include conf.d/include/proxy.conf; } }其中 docker/rootfs/etc/nginx/conf.d/include/proxy.conf 负责真正把请求转发出去并补全一组标准的转发头add_header X-Served-By $host; proxy_set_header Host $host; proxy_set_header X-Forwarded-Scheme $x_forwarded_scheme; proxy_set_header X-Forwarded-Proto $x_forwarded_proto; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Real-IP $remote_addr; proxy_pass $forward_scheme://$server:$port$request_uri;可见「入口端点 转发目标」正是 Proxy Host 的全部本质一个对外可见的地址域名加上一个内部可达的转发目标协议 主机 端口。为什么需要 SSL 终结让没有 HTTPS 能力的后端服务安全对外帮助文档的第二句点出了 Proxy Host 最关键的增值能力它为你的服务提供可选的 SSL 终结SSL termination——即使该服务本身没有内置 SSL 支持。什么是 SSL 终结SSL 终结TLS 终止指在边缘代理即 NPM 所在的 Nginx上完成 HTTPS 握手、解密流量然后把解密后的明文 HTTP 请求转发给后端。这样带来的收益很直接后端服务无需自行配置证书与私钥可以用纯 HTTP 运行客户端与 NPM 之间的流量全程加密杜绝明文传输证书的签发、续期、轮换集中在一个位置统一管理运维成本大大降低。源码中的 SSL 实现链路SSL 终结能力在 NPM 中由三个模板片段协作完成监听端口模板 backend/templates/_listen.conf 根据是否绑定了证书决定是否开启 443 端口监听。有证书时生成listen 443 ssl;含 IPv6 变体并支持通过http2_support开关启用http2 on;。证书挂载模板 backend/templates/_certificates.conf 区分证书来源——由 Lets Encrypt 签发的证书使用/etc/letsencrypt/live/npm-{{ certificate_id }}/fullchain.pem与privkey.pem同时引入letsencrypt-acme-challenge.conf保证续期挑战可被 Nginx 响应自定义上传的证书则读取/data/custom_ssl/npm-{{ certificate_id }}/下的同名文件。强制跳转模板 backend/templates/_forced_ssl.conf 在开启ssl_forced后引入force-ssl.conf把访问 80 端口的 HTTP 请求 301 跳转到 HTTPS并可通过trust_forwarded_proto决定是否信任反向代理传入的X-Forwarded-Proto头。关键提醒可选optional文档措辞是「可选的 SSL 终结」——这是 Proxy Host 区别于强制 HTTPS 的重要设计certificate_id与ssl_forced均为可选字段默认值0/false。你不绑定证书、不强制跳转时NPM 会生成一个纯 HTTP 的 80 端口server块依旧可以完成转发。从 backend/schema/components/proxy-host-object.json 可见certificate_id属于普通可选属性而ssl_forced的默认行为由数据库层控制。因此Proxy Host 可以灵活覆盖三种形态形态certificate_idssl_forced效果纯 HTTP0false仅监听 80转发明文流量HTTPS HTTP 并存证书 IDfalse80/443 都可访问强制 HTTPS证书 IDtrue访问 80 自动跳转 443为什么 Proxy Host 是 NPM 最常见的用途帮助文档的第三句给出了定位结论Proxy Hosts 是 Nginx Proxy Manager 最常见的用途。这一定位可以从 NPM 的同类功能对比中看出端倪。仓库前端将 Nginx 相关能力划分为四类见 frontend/src/pages/Nginx 目录结构功能定位数据模型Proxy Hosts将 HTTP/HTTPS 请求反向代理到后端 Web 服务最常用backend/models/proxy_host.jsRedirection Hosts域名级 301/302 重定向不转发流量backend/models/redirection_host.jsDead Hosts对无效域名返回 404占位保护backend/models/dead_host.jsStreams四层 TCP/UDP 端口转发不涉及 HTTPbackend/models/stream.js绝大多数互联网应用的对外形态都是「HTTP/HTTPS 之上的 Web 服务」——静态站点、前端应用、REST API、管理后台、媒体服务——它们恰好都属于 Proxy Host 的覆盖范围。相比之下Redirection Host 只解决跳转Dead Host 只解决兜底 404Stream 只解决非 HTTP 的四层转发适用面都窄得多。这也解释了为什么前端 Proxy Hosts 列表页frontend/src/pages/Nginx/ProxyHosts/TableWrapper.tsx会内置搜索框按域名、转发主机与端口过滤并且把「添加」按钮放在最显眼的位置——它是用户每天打交道最多的对象。Proxy Host 的完整数据模型核心字段全解要真正用好 Proxy Host需要吃透它的全部字段。后端 OpenAPI 定义 backend/schema/components/proxy-host-object.json 给出了权威清单前端类型声明 frontend/src/api/backend/models.tsProxyHost接口与之对应。字段可按职责分为四组1. 核心转发字段创建时必填创建 Proxy Host 时OpenAPI 定义backend/schema/paths/nginx/proxy-hosts/post.json要求以下四个字段字段类型说明domain_namesstring[]对外域名列表一个 Proxy Host 可绑定多个域名如[app.example.com]forward_schemestring转发协议枚举http/https即「后端自己用的是哪种协议」forward_hoststring转发目标主机IP 或主机名长度 1255forward_portinteger转发目标端口范围 165535schema 自带的最小示例POST /api/nginx/proxy-hosts的 requestBody example{ domain_names: [test.example.com], forward_scheme: http, forward_host: 127.0.0.1, forward_port: 8080 }2. SSL 相关字段字段类型默认说明certificate_idinteger0关联证书值为new时会在创建流程中快速签发新证书见下文ssl_forcedbooleanfalse强制跳转 HTTPShsts_enabledbooleanfalse启用 HSTSHTTP Strict Transport Security响应头hsts_subdomainsbooleanfalseHSTS 是否覆盖子域名trust_forwarded_protobooleanfalse是否信任X-Forwarded-Proto头放在更靠前的反代之后时使用3. 性能与安全字段字段类型默认说明http2_supportbooleanfalse443 上启用 HTTP/2block_exploitsbooleanfalse引入_exploits.conf拦截常见漏洞扫描路径caching_enabledbooleanfalse启用缓存引入_assets.conf静态资源缓存规则allow_websocket_upgradebooleanfalse为所有路径添加 WebSocket 升级头模板中会输出Upgrade/Connection头并指定proxy_http_version 1.14. 访问控制与高级字段字段类型说明access_list_idinteger关联访问列表Access List用于 IP 黑白名单与 Basic Auth 鉴权advanced_configstring插入到 server 块顶部的自定义 Nginx 配置默认空字符串locationsarray自定义 location 列表每条含path、forward_scheme、forward_host、forward_port可选forward_path与advanced_configenabledboolean是否启用该 Proxy Hostmetaobject元信息如{ nginx_online: true, nginx_err: null }在数据库层backend/models/proxy_host.js 维护了一张布尔字段白名单ssl_forced、caching_enabled、block_exploits、allow_websocket_upgrade、http2_support、enabled、hsts_enabled、hsts_subdomains、trust_forwarded_proto等负责在 JS 布尔值与数据库整型之间自动转换并通过domain_names.sort()保证域名始终以排序后的形式存储。模型还声明了三条关系owner创建者用户、access_list访问列表及其客户端/条目、certificate证书这也是列表接口默认展开defaultExpand的三个对象。创建 Proxy Host从表单到 Nginx 配置的完整链路下面沿「前端 → API → 内部服务 → Nginx 配置」四层完整走一遍 Proxy Host 的创建过程。第一步前端表单前端入口在 frontend/src/pages/Nginx/ProxyHosts/TableWrapper.tsx 的「添加」按钮点击后弹出 frontend/src/modals/ProxyHostModal.tsx。该模态框按选项卡组织字段Details域名、转发协议/主机/端口、访问列表、缓存等、SSL证书选择、强制 HTTPS、HSTS、Custom locations自定义路径转发、Advanced高级配置与 WebSocket。表单通过 Formik 管理提交时统一走useSetProxyHost新建与编辑复用同一套逻辑。第二步API 层表单提交后调用POST /api/nginx/proxy-hosts新建或PUT /api/nginx/proxy-hosts/{id}更新路由实现在 backend/routes/nginx/proxy_hosts.js。所有请求先经 JWT 中间件鉴权再经 schema 校验该路由还提供GET /api/nginx/proxy-hosts/{id}/enable与/disable两个切换启停的接口。第三步内部服务逻辑路由将数据交给 backend/internal/proxy-host.js 的create方法其核心流程为权限检查通过access.can(proxy_hosts:create, data)校验当前用户角色权限权限规则定义见 backend/lib/access/proxy_hosts-create.jsonadmin 角色或持有proxy_hosts.manage权限的用户可创建域名占用检查对domain_names中每个域名调用internalHost.isHostnameTaken一旦与已有 Proxy/Redirection/Dead Host 冲突即抛出ValidationError报错文案为 is already in use——这就是同一个域名无法被两个主机重复绑定的底层保证数据清洗与落库设置owner_user_id、清理 SSL/HSTS 相关脏数据、为缺失的advanced_config补空字符串然后insertAndFetch写入proxy_host表可选快速签发证书如果前端传入了certificate_id: new会先创建主机记录再调用internalCertificate.createQuickCertificate为该域名快速申请 Lets Encrypt 证书最后回填certificate_id生成并重载 Nginx 配置记录落库后调用内部 Nginx 服务重新生成对应站点的配置文件并 reload使新配置立即生效。第四步配置生成配置由 backend/templates/proxy_host.conf 渲染。渲染时按需引入监听、证书、HSTS、强制 SSL、WebSocket 升级头等片段advanced_config与自定义locations模板 backend/templates/_location.conf也会被嵌入其中。最终生成的站点文件会写入 Nginx 的 conf.d 目录访问日志落盘到/data/logs/proxy-host-{{ id }}_access.log、错误日志到/data/logs/proxy-host-{{ id }}_error.log均按主机 ID 隔离模板底部还会include /data/nginx/custom/server_proxy[.]conf允许用户以文件方式注入每个 Proxy Host 专属的额外配置。自定义 location一个域名多条转发规则除了默认的location /整站转发Proxy Host 还支持按路径细分转发目标——这就是locations字段的用武之地。例如同一个域名下/app转发到 A 服务、其余路径转发到 B 服务schema 中给出的示例结构如下{ path: /app, forward_scheme: http, forward_host: example.com, forward_port: 80 }每个自定义 location 渲染为独立的 Nginx location 块模板 backend/templates/_location.conf其中会补全proxy_set_header Host $host、X-Forwarded-*系列头并同样支持挂载访问控制、资源缓存、漏洞拦截、强制 SSL 与 WebSocket 升级片段location 级advanced_config会先于其他指令输出供用户精细调优。是否使用默认location /则由模板顶部的use_default_location开关控制两者可以同时存在实现「默认整站转发 个别路径单独分流」。常见使用场景与注意事项围绕上述机制以下场景与坑点值得留意WebSocket 应用如在线协作、实时推送必须开启allow_websocket_upgrade模板才会输出proxy_set_header Upgrade $http_upgrade;、proxy_set_header Connection $http_connection;与proxy_http_version 1.1;否则升级请求会被当作普通 HTTP 处理导致连接失败。域名冲突同一个域名含子域名只能归属一个主机Proxy/Redirection/Dead 全局唯一创建时会提前校验重复绑定直接报错。强制 HTTPS 组合拳ssl_forcedhsts_enabled可让浏览器强制使用 HTTPS 访问若 NPM 前方还有一层反向代理如 CDN应同时打开trust_forwarded_proto否则 Nginx 无法正确识别原始请求协议可能导致跳转判断失真。纯内网服务暴露如果后端服务没有认证能力可以在 Proxy Host 上挂载 Access Listaccess_list_id实现 IP 白名单或 Basic Auth 两道防线相关客户端规则定义见 frontend/src/api/backend/models.ts 的AccessListClient支持allow/deny指令。证书选型对外提供 HTTPS 时优先选择 Lets Encrypt 证书由 backend/certbot 模块与 backend/templates/_certificates.conf 的自动续期链路支撑已有外部签发的通配符证书则走「Custom」上传通道。调试入口主机创建后若转发异常优先查看/data/logs/proxy-host-{id}_error.log与该主机的meta.nginx_err字段前端列表也会展示 Nginx 在线状态与错误信息。小结Proxy Host 是 Nginx Proxy Manager 中最常用、也最灵活的一类对象它以「域名 转发目标」的极简模型定义了 Web 服务的对外入口在边缘提供可选的 SSL 终结能力让任何后端服务都能快速获得安全、规范的对外访问方式。理解它的本质入口端点、核心能力SSL 终结与定位最常用功能再结合proxy_host数据模型、OpenAPI 定义与四层创建链路你就掌握了 NPM 反向代理的基石后续无论配置 Redirection Host、Dead Host 还是 Stream都能举一反三。延伸阅读仓库内资源backend/templates/proxy_host.confProxy Host 的 Nginx 配置主模板backend/internal/proxy-host.js创建/更新/启停/删除的内部业务逻辑backend/routes/nginx/proxy_hosts.jsREST API 路由backend/schema/components/proxy-host-object.json字段的权威 OpenAPI 定义frontend/src/modals/ProxyHostModal.tsx前端创建/编辑表单frontend/src/pages/Nginx/ProxyHosts/TableWrapper.tsxProxy Hosts 列表页帮助文档es/ProxyHosts.md西班牙语、en/ProxyHosts.md英语【免费下载链接】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），仅供参考