Nginx Proxy Manager 代理服务（Proxy Host）完全指南：从转发原理到源码级配置

Nginx Proxy Manager 代理服务（Proxy Host）完全指南：从转发原理到源码级配置

【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager

代理服务（Proxy Host）是 Nginx Proxy Manager 中最核心、使用频率最高的功能模块：它把对外暴露的域名与后端的网络应用连接起来，并可选地提供 SSL 终止能力。本文以项目自带的帮助文档为主线，结合 backend/internal/proxy-host.js、backend/templates/proxy_host.conf 等源码与配置，深入讲解代理服务的概念、核心配置字段、Nginx 配置生成原理以及权限控制，帮助你彻底理解并熟练使用这一功能。

什么是代理服务（Proxy Host）？

代理服务是你想转发网络应用的主机。 代理服务可以为没有 SSL 服务的网络应用提供 SSL 服务（可选）。 代理服务是 Nginx 代理管理器的最常见用途之一。

这三句话概括了代理服务的全部本质，拆解开来是三个关键点：

1. 转发：代理服务是一个"入口主机"，它接收来自公网的请求，并把请求转发给后端的网络应用（源站）。这里的"主机"在 Nginx 层面体现为一个server配置块，监听指定的域名（server_name）。
2. SSL 终止：如果后端应用本身不支持 HTTPS（例如内网服务、开发环境服务），代理服务可以在 Nginx 这一层终结 TLS 加密，后端只收到明文的 HTTP 请求，从而"为没有 SSL 服务的网络应用提供 SSL 服务"。
3. 最常见的用途：无论是托管个人网站、反向代理内部工具，还是给 Docker 容器暴露 Web 服务，代理服务都是默认首选方案。

代理服务在 Nginx 层的落地

在源码层面，"转发"这一行为由 Nginx 的proxy_pass指令完成。容器内统一的代理配置位于 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;

其中$forward_scheme、$server、$port三个变量正是代理服务配置中的转发协议、转发主机、转发端口，它们在生成的 Nginx 配置中被显式赋值（详见下文第四节）。

代理服务的核心能力：转发与 SSL 终止

转发：四要素决定去向

一个代理服务要把请求送到正确的后端，需要四个要素，它们也是创建代理服务时必填的核心字段：

这些字段的定义可以在 API 模式定义 backend/schema/components/proxy-host-object.json 中找到，例如forward_host限制为 1～255 个字符，forward_port限制在 1～65535 的整数范围内。

SSL 终止：为后端"代劳"HTTPS

SSL 终止的流程是：客户端 → HTTPS → Nginx（代理服务）→ HTTP → 后端应用。代理服务通过certificate_id关联一张 SSL 证书（证书可在创建代理服务时一并自动签发，见下文第五节），然后由 Nginx 配置模板完成监听与证书装载。

在 backend/templates/_listen.conf 中可以看到监听端口的生成逻辑：

listen 80; {% if certificate -%} listen 443 ssl; {% endif %} server_name {{ domain_names | join: " " }}; {% if http2_support == 1 or http2_support == true %} http2 on; {% else -%} http2 off; {% endif %}

也就是说：只有关联了证书，才会监听 443 端口并启用 SSL；同时http2_support决定是否启用 HTTP/2。

而"强制 SSL"（把 HTTP 请求 301 跳转到 HTTPS）由 backend/templates/_forced_ssl.conf 控制：当配置了有效证书且ssl_forced开启时，会引入conf.d/include/force-ssl.conf实现跳转。

代理服务的关键配置字段详解

在 Nginx Proxy Manager 的代理服务编辑界面中，除了上述转发四要素，还有一系列可选项。结合 proxy-host-object.json 与数据模型 backend/models/proxy_host.js（其中boolFields定义了布尔字段列表），整理如下：

WebSocket 升级的模板实现

当allow_websocket_upgrade开启时，backend/templates/proxy_host.conf 会在server块和默认location /块中分别注入：

proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $http_connection; proxy_http_version 1.1;

这一能力让代理服务可以直接代理 WebSocket / SSE 类实时应用，无需额外手工配置。

代理服务如何生成 Nginx 配置：源码级原理

创建或更新一个代理服务后，Nginx Proxy Manager 并不会直接使用你的表单数据，而是经历一条完整的后端调用链（位于 backend/internal/proxy-host.js 的create/update方法）：

1. 权限校验：通过access.can("proxy_hosts:create" / "proxy_hosts:update", ...)检查当前用户是否有操作权限。
2. 域名冲突检测：对domain_names中每个域名调用internalHost.isHostnameTaken()，如果与其他主机（代理、重定向、流媒体等）重复，则抛出ValidationError，提示xxx is already in use。
3. 数据落库：将配置写入proxy_host表（模型见 backend/models/proxy_host.js，其中domain_names、meta、locations为 JSON 字段，布尔字段在读写时自动转换）。
4. 生成 Nginx 配置：调用internalNginx.configure(proxyHostModel, "proxy_host", row)，用 backend/templates/proxy_host.conf 渲染出对应域名的主机配置文件并执行nginx -t校验。
5. 审计日志：写入created/updated/enabled/disabled/deleted等操作记录（见 backend/internal/audit-log.js）。

主模板proxy_host.conf的核心结构如下（已简化）：

server { set $forward_scheme {{ forward_scheme }}; set $server "{{ forward_host }}"; set $port {{ forward_port }}; # 监听、证书、HSTS、强制 SSL、缓存、攻击拦截等（按需 include） access_log /data/logs/proxy-host-{{ id }}_access.log proxy; error_log /data/logs/proxy-host-{{ id }}_error.log warn; {{ advanced_config }} {{ locations }} location / { # 访问控制、HSTS、WebSocket 升级 include conf.d/include/proxy.conf; # 真正的 proxy_pass 转发 } # 自定义 include /data/nginx/custom/server_proxy[.]conf; }

可以看到：转发变量$forward_scheme、$server、$port在此被赋值，最终由proxy.conf中的proxy_pass $forward_scheme://$server:$port$request_uri;完成实际转发；而advanced_config、locations则被直接渲染进server块，实现"高级配置"与"自定义路径"能力。同时# Custom注释还揭示了另一个扩展点：管理员可以把自定义配置放到/data/nginx/custom/server_proxy.conf，该文件会被自动 include 进每个代理服务。

创建代理服务的两种方式：界面与 API

界面操作（Web UI）

在仪表盘左侧菜单进入Hosts → Proxy Hosts，点击Add Proxy Host打开创建表单（表单组件见 frontend/src/modals/ProxyHostModal.tsx），填写：

1. Domain Names：要代理的域名（支持通配符，如*.example.com）。
2. Forward Hostname / IP + Forward Port + Scheme：后端地址与协议。
3. SSL 选项卡：选择已有证书或选择 "Request a new SSL Certificate" 自动申请（HTTP 或 DNS 验证）。
4. 高级选项卡：WebSocket 支持、访问列表、HSTS、高级配置等。

保存后即可在列表页看到新主机，Nginx 配置随之生成并热加载。

API 方式

代理服务的完整 REST 接口定义在 backend/routes/nginx/proxy_hosts.js，请求体模式位于 backend/schema/paths/nginx/proxy-hosts/post.json。一个典型的创建请求体：

{ "domain_names": ["app.example.com"], "forward_scheme": "http", "forward_host": "127.0.0.1", "forward_port": 8080, "access_list_id": 0, "certificate_id": 0, "ssl_forced": false, "caching_enabled": false, "block_exploits": false, "allow_websocket_upgrade": true, "http2_support": false, "hsts_enabled": false, "hsts_subdomains": false, "advanced_config": "", "meta": { "letsencrypt_agree": false }, "locations": [], "enabled": true }

值得注意的一个细节：当certificate_id传入字符串"new"时（源码中const createCertificate = thisData.certificate_id === "new"），后端会在保存主机后调用internalCertificate.createQuickCertificate()自动签发证书，并把新证书 ID 回填到主机上——这正是界面中"同时申请证书"选项的底层实现。

启停与删除

每个代理服务都支持enable / disable操作：启用时重新生成 Nginx 配置，禁用时删除配置并执行nginx reload（见 proxy-host.js 中的enable/disable）。删除则是软删除（is_deleted: 1），同时删除对应 Nginx 配置并 reload。

权限与多用户支持

代理服务支持细粒度的权限控制。后端通过 backend/lib/access/proxy_hosts-create.json、proxy_hosts-update.json、proxy_hosts-get.json、proxy_hosts-list.json、proxy_hosts-delete.json等文件定义各操作的权限要求：

• 管理员（admin 角色）拥有全部操作权限；
• 普通用户需要拥有permission_proxy_hosts权限，其中创建 / 更新 / 删除要求manage级权限，查看 / 列表只需view级权限。

此外，非管理员用户在查询时还会按owner_user_id过滤，只能看到自己创建的代理服务（见get/getAll中的permission_visibility !== "all"分支），从而实现多用户环境下的数据隔离。审计日志则会记录每次创建、更新、启停与删除的完整元数据。

代理服务与其它主机类型的区别

在 Nginx Proxy Manager 中，"主机"不止代理服务一种，理解它们的差异有助于正确选型：

代理服务是唯一面向HTTP(S) 应用、同时提供证书管理与 SSL 终止的通用型主机；如果你的需求是"把一个 Web 服务安全地暴露到公网"，它始终是首选方案。

小结

代理服务（Proxy Host）是 Nginx Proxy Manager 的核心模块，它以"域名 + 转发目标 + 可选证书"的简洁模型，把复杂的 Nginxserver/location/proxy_pass配置封装成可视化操作。理解其背后 proxy_host.conf 模板的渲染机制、proxy_pass变量的赋值链路，以及 backend/internal/proxy-host.js 中域名校验、快速签发证书、权限与审计的完整流程，将帮助你更准确地配置代理服务，也能在遇到问题时快速定位根因。

【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager