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 能力的内网服务提供可选的 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入站侧domain_names对外域名列表、ssl_forced强制 HTTPS、certificate_idSSL 证书、http2_support、hsts_enabled等转发侧forward_schemehttp/https、forward_host目标地址、forward_port目标端口以及可选的按路径拆分的locations自定义位置保护与增强access_list_id访问控制列表、block_exploits拦截常见攻击、caching_enabled缓存、allow_websocket_upgradeWebSocket 升级、advanced_config自定义 Nginx 片段。Proxy Host 核心配置参数详解域名Domain Namesdomain_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字段类型约束示例说明forward_schemestring枚举http/httpshttp转发到后端时使用的协议forward_hoststring1255 字符127.0.0.1或10.0.0.5后端服务地址支持 IP 或主机名forward_portinteger1655358080后端服务端口这三个字段会被模板渲染为 Nginx 变量见 backend/templates/proxy_host.confset $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模板会根据证书提供方渲染不同路径——Lets Encrypt 证书指向/etc/letsencrypt/live/npm-{{ certificate_id }}/...自定义证书指向/data/custom_ssl/npm-{{ certificate_id }}/...见 backend/templates/_certificates.conf。强制 HTTPSssl_forced开启后模板会引入force-ssl.conf将 80 端口请求 301 重定向到 HTTPS结合trust_forwarded_proto信任反向代理传递的协议头可正确处理处于多级代理后方的场景见 backend/templates/_forced_ssl.conf。HSTShsts_enabled与hsts_subdomains控制Strict-Transport-Security响应头有效期 63072000 秒即两年仅在已绑定证书且强制 SSL 时生效见 backend/templates/_hsts.conf 与 _hsts_map.conf。HTTP/2http2_support控制http2 on|off指令见 backend/templates/_listen.conf。监听与 WebSocket_listen.conf模板生成实际监听行为见 backend/templates/_listen.conf始终listen 80IPv6 可配置仅当绑定证书时才额外listen 443 sslserver_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 Listaccess_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_configadvanced_config一段自由填写的 Nginx 配置片段渲染时会直接嵌入 server 块{{ advanced_config }}位置见 backend/templates/proxy_host.conf用于实现代理模板无法覆盖的定制需求。其他布尔开关数据模型将以下字段统一按布尔/整型互转处理见 backend/models/proxy_host.js 的boolFieldsssl_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即可打开创建表单典型填写步骤为Domain Names输入一个或多个对外域名Forward Hostname / IP填写后端服务地址Forward Port填写后端服务端口Websockets Support按需开启 WebSocket 升级Block Common Exploits建议开启以拦截常见攻击Access List如需认证或 IP 白名单则选择已有访问列表SSL 标签页选择 Request a new SSL CertificateLets Encrypt 自动签发或已有证书并决定是否 Force SSL、启用 HTTP/2 与 HSTSAdvanced 标签页可按路径添加 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()走 Lets 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 / disableenable会重新生成并应用 Nginx 配置disable则调用internalNginx.deleteConfig()删除配置并reload()两种操作都会写审计日志。delete采用软删除is_deleted: 1随后删除 Nginx 配置并 reload。对应的 REST 端点定义在 backend/routes/nginx/proxy_hosts.js方法路径说明GET/api/nginx/proxy-hosts列出全部支持expand、queryPOST/api/nginx/proxy-hosts创建GET/api/nginx/proxy-hosts/{id}获取单个PUT/api/nginx/proxy-hosts/{id}更新DELETE/api/nginx/proxy-hosts/{id}删除POST/api/nginx/proxy-hosts/{id}/enable启用POST/api/nginx/proxy-hosts/{id}/disable禁用一个符合 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.idaccess_list访问列表access_list_id→access_list.id可再展开clients与itemscertificateSSL 证书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; # Lets 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考