企业官网建设流程全解析

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-manager

Proxy Host 是 Nginx Proxy Manager（NPM）中最核心、最常用的功能：它为你想转发到的某个 Web 服务提供一个统一的入站端点，并为没有内置 SSL 能力的内网服务提供可选的 SSL 终结（SSL Termination）。读完本文，你将理解 Proxy Host 的完整概念、全部可配置字段、创建与管理流程，以及它在后端如何被校验、落库并最终渲染为一份真实的 Nginx server 配置。

Proxy Host 是什么：入站端点与 SSL 终结

官方帮助文档对 Proxy Host 的定义非常精炼，可以拆解为三个要点（原文见 HelpDoc/tr/ProxyHosts.md 与英文版 HelpDoc/en/ProxyHosts.md）：

• 入站端点：Proxy Host 是"你想转发到的某个 Web 服务"在 Nginx 侧的入口。用户访问的域名与端口落在 NPM 上，由 NPM 决定把请求转发给后端的哪个服务。
• 可选的 SSL 终结：如果你的后端服务本身没有内置 SSL（例如内网裸 HTTP 应用、开发环境服务），Proxy Host 可以在 Nginx 这一层终结 HTTPS，对外暴露 443 加密流量、对内转发明文 HTTP，从而无需改造后端即可获得加密传输。
• 最常见的用途：在 NPM 的所有主机类型（Proxy Host、Redirection Host、Dead Host、Stream）中，Proxy Host 的使用频率最高，是部署 Web 应用、API 服务、内部工具的标准姿势。

从数据模型看，一条 Proxy Host 记录本质上由三部分构成（见 backend/schema/components/proxy-host-object.json）：

1. 入站侧：domain_names（对外域名列表）、ssl_forced（强制 HTTPS）、certificate_id（SSL 证书）、http2_support、hsts_enabled等；
2. 转发侧：forward_scheme（http/https）、forward_host（目标地址）、forward_port（目标端口），以及可选的按路径拆分的locations（自定义位置）；
3. 保护与增强：access_list_id（访问控制列表）、block_exploits（拦截常见攻击）、caching_enabled（缓存）、allow_websocket_upgrade（WebSocket 升级）、advanced_config（自定义 Nginx 片段）。

Proxy Host 核心配置参数详解

域名（Domain Names）

domain_names是 JSON 数组，可填写一个或多个域名，例如["app.example.com", "api.example.com"]。需要注意两点：

• 创建与更新时，后端会对每个域名调用internalHost.isHostnameTaken()做全局占用检查（见 backend/internal/proxy-host.js 的create流程），若域名已被其他主机占用，会直接抛出ValidationError: xxx is already in use；
• 数据模型在写入前会自动对域名排序（this.domain_names.sort()，见 backend/models/proxy_host.js 的$beforeInsert/$beforeUpdate），保证多域名记录的一致性。

转发目标（Forward Scheme / Host / Port）

这三个字段会被模板渲染为 Nginx 变量（见 backend/templates/proxy_host.conf）：

set $forward_scheme {{ forward_scheme }}; set $server "{{ forward_host }}"; set $port {{ forward_port }};

并最终在 docker/rootfs/etc/nginx/conf.d/include/proxy.conf 中通过proxy_pass $forward_scheme://$server:$port$request_uri;完成真实转发。该文件还统一设置了Host、X-Forwarded-Proto、X-Forwarded-For、X-Real-IP等标准反向代理头。

SSL 证书与强制 HTTPS

• 证书绑定：certificate_id关联一个证书记录；_certificates.conf模板会根据证书提供方渲染不同路径——Let's Encrypt 证书指向/etc/letsencrypt/live/npm-{{ certificate_id }}/...，自定义证书指向/data/custom_ssl/npm-{{ certificate_id }}/...（见 backend/templates/_certificates.conf）。
• 强制 HTTPS：ssl_forced开启后，模板会引入force-ssl.conf，将 80 端口请求 301 重定向到 HTTPS；结合trust_forwarded_proto（信任反向代理传递的协议头）可正确处理处于多级代理后方的场景（见 backend/templates/_forced_ssl.conf）。
• HSTS：hsts_enabled与hsts_subdomains控制Strict-Transport-Security响应头（有效期 63072000 秒即两年），仅在已绑定证书且强制 SSL 时生效（见 backend/templates/_hsts.conf 与 _hsts_map.conf）。
• HTTP/2：http2_support控制http2 on|off指令（见 backend/templates/_listen.conf）。

监听与 WebSocket

_listen.conf模板生成实际监听行为（见 backend/templates/_listen.conf）：

• 始终listen 80（IPv6 可配置）；
• 仅当绑定证书时才额外listen 443 ssl；
• server_name由domain_names以空格拼接而成。

allow_websocket_upgrade开启后，模板会注入proxy_set_header Upgrade $http_upgrade、Connection $http_connection与proxy_http_version 1.1，从而支持 WebSocket 长连接；该指令在 server 块和默认location /块中都会生成（见 backend/templates/proxy_host.conf）。

访问控制（Access List）

access_list_id关联一条访问列表，_access.conf模板会据此生成认证与 IP 规则（见 backend/templates/_access.conf）：

• 若访问列表包含授权凭据（items），则启用auth_basic，密码文件位于/data/access/{{ access_list_id }}；
• 若包含客户端 IP 规则（clients），则逐条渲染allow/deny规则并在末尾deny all；
• 通过satisfy any|all控制凭据与 IP 规则是"任一满足"还是"全部满足"。

自定义位置与高级配置

• locations：数组，允许按 URL 路径（如/app）将请求转发到与默认目标不同的后端，每个元素可独立指定forward_scheme、forward_host、forward_port、forward_path与advanced_config；
• advanced_config：一段自由填写的 Nginx 配置片段，渲染时会直接嵌入 server 块（{{ advanced_config }}位置，见 backend/templates/proxy_host.conf），用于实现代理模板无法覆盖的定制需求。

其他布尔开关

数据模型将以下字段统一按布尔/整型互转处理（见 backend/models/proxy_host.js 的boolFields）：ssl_forced、caching_enabled、block_exploits、allow_websocket_upgrade、http2_support、enabled、hsts_enabled、hsts_subdomains、trust_forwarded_proto。其中block_exploits会引入block-exploits.conf拦截常见扫描与攻击流量，caching_enabled启用缓存相关配置。

创建与管理 Proxy Host：前端流程

在 NPM 管理界面左侧菜单进入 "Hosts → Proxy Hosts"，点击 "Add Proxy Host"（对应前端实现 frontend/src/modals/ProxyHostModal.tsx）即可打开创建表单，典型填写步骤为：

1. Domain Names：输入一个或多个对外域名；
2. Forward Hostname / IP：填写后端服务地址；
3. Forward Port：填写后端服务端口；
4. Websockets Support：按需开启 WebSocket 升级；
5. Block Common Exploits：建议开启以拦截常见攻击；
6. Access List：如需认证或 IP 白名单则选择已有访问列表；
7. SSL 标签页：选择 "Request a new SSL Certificate"（Let's Encrypt 自动签发）或已有证书，并决定是否 Force SSL、启用 HTTP/2 与 HSTS；
8. Advanced 标签页：可按路径添加 Custom locations，或在 "Custom Nginx Configuration" 中粘贴自定义片段。

保存后，后端会依次执行域名占用校验 → 写入数据库（必要时先快速签发证书）→ 调用internalNginx.configure()重新生成 Nginx 配置（若配置失败，记录会带上nginx_online/nginx_err等 meta 信息）→ 写入审计日志（见 backend/internal/proxy-host.js 的create方法）。全程可在 Audit Log 页面查看 "created / updated / enabled / disabled / deleted" 事件记录。

从源码看 Proxy Host 的生命周期

backend/internal/proxy-host.js 封装了 Proxy Host 的全部业务逻辑，主要方法如下：

• create：先做权限校验（proxy_hosts:create）与域名占用检查；若certificate_id === "new"，则调用internalCertificate.createQuickCertificate()走 Let's Encrypt 快速签发流程并回填证书 ID；落库后重新拉取（expand 证书、属主、访问列表）并调用internalNginx.configure(proxyHostModel, "proxy_host", row)生成配置，最后写审计日志。
• update：同样做域名占用检查（排除自身，isHostnameTaken(domain_name, "proxy", thisData.id)）、可快速签发新证书；若主机处于禁用状态则跳过 Nginx 配置，仅更新数据库。
• get / getAll：默认过滤is_deleted = 0；支持expand关联拉取与query域名模糊搜索；非管理员（权限可见性非all）只能看到自己名下（owner_user_id）的主机。
• enable / disable：enable会重新生成并应用 Nginx 配置；disable则调用internalNginx.deleteConfig()删除配置并reload()，两种操作都会写审计日志。
• delete：采用软删除（is_deleted: 1），随后删除 Nginx 配置并 reload。

对应的 REST 端点定义在 backend/routes/nginx/proxy_hosts.js：

一个符合 schema 的最小创建请求体示例（字段约束见 backend/schema/components/proxy-host-object.json）：

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

数据模型与关联关系

proxy_host表由 backend/models/proxy_host.js 定义，jsonAttributes为["domain_names", "meta", "locations"]，即这三个字段以 JSON 形式存储。通过 Objection.js 关系映射，Proxy Host 关联了三类对象：

• owner：属主用户（owner_user_id→user.id）；
• access_list：访问列表（access_list_id→access_list.id，可再展开clients与items）；
• certificate：SSL 证书（certificate_id→certificate.id）。

默认展开图"[owner,access_list.[clients,items],certificate]"表明，接口返回的 Proxy Host 对象通常会携带完整的属主、访问列表与证书详情，前端表格（frontend/src/pages/Nginx/ProxyHosts/Table.tsx）据此展示域名、状态、SSL 等列。

生成的 Nginx 配置全貌

综合上述模板，一个开启全部常见选项的 Proxy Host 最终渲染出的 server 块结构如下（由 backend/templates/proxy_host.conf 及其 include 串联而成）：

server { set $forward_scheme http; set $server "10.0.0.5"; set $port 8080; listen 80; listen 443 ssl; # 绑定证书后 server_name app.example.com; http2 on; # Let's Encrypt / Custom SSL 证书路径 # Force SSL 301 重定向（ssl_forced） # HSTS 响应头（hsts_enabled） # WebSocket 升级头（allow_websocket_upgrade） access_log /data/logs/proxy-host-1_access.log proxy; error_log /data/logs/proxy-host-1_error.log warn; # advanced_config 自定义片段 location / { # auth_basic / allow、deny 规则（access_list） # WebSocket 升级头 include conf.d/include/proxy.conf; # proxy_pass 与转发头 } # Custom include /data/nginx/custom/server_proxy[.]conf; }

同时，每个 Proxy Host 拥有独立的访问日志与错误日志（/data/logs/proxy-host-{id}_access.log/_error.log），便于按主机排查问题。这些 Nginx 配置的生成、写入与 reload 均由 backend/internal/nginx.js 统一调度，保证配置变更即时生效且失败可控。

总结

Proxy Host 是 Nginx Proxy Manager 的基石功能：它以"域名 + 转发目标 + 可选证书"的最小模型，把复杂的反向代理、SSL 终结、WebSocket、访问控制与自定义 Nginx 片段封装成可视化配置。理解其字段语义与后端渲染链路，既能帮助你正确配置生产环境，也能在遇到"域名被占用""配置未生效""WebSocket 连接失败"等问题时快速定位到对应代码与模板（backend/internal/proxy-host.js、backend/templates/proxy_host.conf），实现从界面操作到底层原理的贯通。

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