Nginx Proxy Manager 代理主机Proxy Host完全指南从入站端点、SSL 终止到 Nginx 配置生成【免费下载链接】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 最核心、最常用的功能模块它定义了一个 Web 服务的入站端点incoming endpoint将公网流量按域名规则转发到内网或本机的上游服务并为不具备原生 SSL 能力的服务提供可选的SSL 终止SSL termination。阅读完本文你将掌握代理主机的完整概念、前端表单每个字段的准确含义、底层 API 数据契约以及它如何被翻译成一份可运行的 Nginx 配置从而能在实际部署中独立完成从新增代理主机到排障调优的完整闭环。什么是代理主机按照官方帮助文档的定义见 frontend/src/locale/src/HelpDoc/fr/ProxyHosts.md 及对应的英文版 frontend/src/locale/src/HelpDoc/en/ProxyHosts.md代理主机是你希望转发forward的某个 Web 服务的入站端点。也就是说它定义了从哪个域名进来、转发到哪台主机的哪个端口这条完整链路。它为不原生支持 SSL 的服务提供可选的 SSL 终止。你的上游服务可以继续跑在纯 HTTP 上由 Nginx Proxy Manager 在边缘统一终结 TLS再以 HTTP 或 HTTPS 转发给后端从而省去在每个服务里各自配置证书的负担。代理主机是 Nginx Proxy Manager 最常用的场景。日常的给某个内网 Web 应用绑一个域名并配上 HTTPS 证书这类需求几乎全部落在代理主机这个功能上。需要说明的是这里的代理在实现上就是 Nginx 的proxy_pass反向代理客户端与 NPM 之间建立连接NPM 再把请求转发给上游服务并将响应原路返回。代理主机的数据模型一份配置的骨架在仓库中代理主机的持久化模型定义于 backend/models/proxy_host.js对应数据库表proxy_host。从模型与 backend/schema/components/proxy-host-object.json 中的 API 对象定义可以看出一条代理主机记录包含以下核心字段字段类型/取值含义domain_namesstring[]该主机对外服务的域名列表支持通配符写入数据库前会自动排序去重forward_schemehttp/https转发到上游服务时使用的协议forward_hoststring上游服务的主机地址IP 或域名如127.0.0.1forward_portinteger1~65535上游服务端口如8080certificate_idinteger绑定的 SSL 证书 ID可为空ssl_forcedboolean是否强制 HTTPSHTTP 请求自动 301 跳转 HTTPScaching_enabledboolean是否启用静态资源缓存block_exploitsboolean是否拦截常见攻击特征exploit 过滤allow_websocket_upgradeboolean是否允许 WebSocket 升级对所有路径生效http2_supportboolean是否启用 HTTP/2hsts_enabled/hsts_subdomainsboolean是否启用 HSTS、是否覆盖子域trust_forwarded_protoboolean是否信任上游转发过来的协议头access_list_idinteger关联的访问控制列表认证 IP 规则locationsarray自定义路径级别的转发规则自定义位置advanced_configstring追加到 server 块的 Nginx 高级配置片段enabledboolean主机是否启用metaobject运行元数据例如nginx_online、nginx_err注意模型里的boolFields列表如ssl_forced、caching_enabled、block_exploits等它们在 API 层表现为布尔值落库时会被转换为整数读取时再转回布尔这正是前端开关控件与后端数据库之间的桥接机制。从前端表单看一个代理主机的完整配置项代理主机的创建与编辑界面位于 frontend/src/modals/ProxyHostModal.tsx表单分为四个标签页与数据模型一一对应Details 页转发目标与基础选项Domain Names输入要绑定的域名支持通配符如*.example.com。保存时后端会逐一对每个域名执行占用检查isHostnameTaken如果已被其他主机占用会直接抛错拒绝。Forward Scheme / Host / Port上游协议http/https、上游地址、上游端口三者构成转发目标三元组。Access List可选的访问控制列表用于给该主机附加 HTTP Basic 认证或来源 IP 白/黑名单。Options 开关Cache Assetscaching_enabled对静态资源启用缓存Block Common Exploitsblock_exploits拦截常见攻击特征Websockets Supportallow_websocket_upgrade允许 WebSocket 升级。Custom Locations 页路径级路由用于同一域名、不同路径转发到不同后端的场景例如/app转发到 A 服务、/api转发到 B 服务。每条自定义位置包含path、forward_scheme、forward_host、forward_port并可选的forward_path改写转发路径与advanced_config该 location 块内的附加配置详见 backend/schema/components/proxy-host-object.json。SSL 页证书与传输安全SSL Certificate选择一个已存在的证书或选择新建由 NPM 自动签发对应certificate_id new的快速签发逻辑。SSL 选项由 frontend/src/components/Form/SSLOptionsFields.tsx 渲染Force SSLssl_forced强制跳转 HTTPSHTTP/2 Supporthttp2_supportHSTS Enabled / HSTS Subdomains启用严格传输安全头Trust forwarded prototrust_forwarded_proto信任转发协议头用于正确识别上游是 HTTP 还是 HTTPS。Advanced 页Nginx 高级配置advanced_config文本域内容会被原样注入到生成的 Nginx server 块中模板中位于{{ advanced_config }}位置适合补充缓存规则、自定义响应头等模板未覆盖的逻辑。底层原理代理主机如何变成 Nginx 配置模板驱动生成后端在保存代理主机后会调用internalNginx.configure(proxyHostModel, proxy_host, row)见 backend/internal/proxy-host.js 的 create/update 流程渲染 backend/templates/proxy_host.conf 生成实际的 server 配置。模板核心逻辑如下server { set $forward_scheme {{ forward_scheme }}; set $server {{ forward_host }}; set $port {{ forward_port }}; # 监听 80/443、证书、缓存、exploit 过滤、HSTS、强制 SSL、WebSocket 升级… {{ advanced_config }} {{ locations }} location / { … include conf.d/include/proxy.conf; } }其中关键片段由多个子模板按条件拼装_listen.conf监听 80 端口若绑定了证书则追加监听 443 sslserver_name由domain_names以空格连接根据http2_support开关http2 on/off。_certificates.confLets Encrypt 证书引用/etc/letsencrypt/live/npm-cert_id/自定义证书引用/data/custom_ssl/npm-cert_id/。_forced_ssl.confssl_forced开启时引入force-ssl.conf实现 HTTP→HTTPS 跳转同时根据trust_forwarded_proto设置标记变量。_hsts.conf 与 _hsts_map.confHSTS 头通过map $scheme $hsts_header生成max-age63072000两年hsts_subdomains开启时附加includeSubDomains与preload。_assets.conf / _exploits.conf分别对应缓存与攻击拦截开关引入assets.conf/block-exploits.conf。_access.conf当绑定访问列表时写入auth_basic认证凭据文件位于/data/access/id与基于客户端的allow/deny规则并用satisfy any/all控制认证与 IP 规则的组合逻辑pass_auth关闭时还会清空转发的Authorization头。真正的转发动作默认的location /转发动作由 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 / forward_host / forward_port三个字段被绑定为 Nginx 变量并用于proxy_pass同时注入X-Forwarded-*头以保留客户端真实来源。若开启 WebSocket 升级模板还会追加Upgrade/Connection头并设置proxy_http_version 1.1。通过 REST API 管理代理主机代理主机的全部 REST 路由定义在 backend/routes/nginx/proxy_hosts.js前缀为/api/nginx/proxy-hosts方法路径说明GET/api/nginx/proxy-hosts列出全部代理主机支持expand关联展开与query按域名搜索参数POST/api/nginx/proxy-hosts创建代理主机GET/api/nginx/proxy-hosts/:host_id获取单个代理主机PUT/api/nginx/proxy-hosts/:host_id更新代理主机DELETE/api/nginx/proxy-hosts/:host_id删除代理主机POST/api/nginx/proxy-hosts/:host_id/enable启用代理主机POST/api/nginx/proxy-hosts/:host_id/disable禁用代理主机请求体在进入内部逻辑前会经过 JSON Schema 校验getValidationSchema(/nginx/proxy-hosts, post)字段约束与 backend/schema/components/proxy-host-object.json 一致。创建时若certificate_id传new后端会走internalCertificate.createQuickCertificate自动签发证书并把certificate_id回填到主机记录上见 backend/internal/proxy-host.js 的 create 流程。以创建为例一份最小可用的请求体为{ domain_names: [app.example.com], forward_scheme: http, forward_host: 192.168.1.10, forward_port: 8080, certificate_id: 0, ssl_forced: false, caching_enabled: false, block_exploits: false, allow_websocket_upgrade: false, http2_support: false, hsts_enabled: false, locations: [], advanced_config: }生命周期与权限控制创建时的域名唯一性校验create流程会先对domain_names中的每个域名调用internalHost.isHostnameTaken检查占用情况任一域名已被占用即抛出ValidationError杜绝同一个域名被多个主机重复绑定backend/internal/proxy-host.js。更新时同样会做此检查但会排除当前主机自身。启用/禁用/删除启用enable将enabled置 1重新生成 Nginx 配置internalNginx.configure并记录enabled审计事件禁用disable将enabled置 0删除该主机对应的 Nginx 配置并reload记录disabled审计事件删除delete软删除is_deleted 1删除配置并 reload记录deleted审计事件。整个生命周期都通过 backend/internal/audit-log.js 写入审计日志便于事后追溯谁在何时做了什么变更。权限模型代理主机相关的权限点包括proxy_hosts:create、proxy_hosts:list、proxy_hosts:get、proxy_hosts:update、proxy_hosts:delete。从 backend/lib/access/proxy_hosts-create.json 与 backend/lib/access/proxy_hosts-list.json 可以看出管理员角色直接放行普通user角色则需要具备对应的permission_proxy_hosts权限。此外非管理员查询时还会根据permission_visibility做数据隔离——若可见性不是all则只能看到owner_user_id等于当前用户的记录backend/internal/proxy-host.js。实战建议与排查思路SSL 终止是代理主机的核心价值上游服务保持纯 HTTP把证书与 HTTPS 集中交给 NPM 管理需要强制跳转时开启 Force SSL需要浏览器安全策略时开启 HSTS注意 HSTS 一旦开启并生效浏览器会强制 HTTPS 访问调试时需谨慎。区分转发协议与监听协议forward_scheme只决定 NPM → 上游这段链路用 http 还是 https客户端 → NPM 这一段由证书与 Force SSL 决定。WebSocket 应用如实时推送、在线终端记得开启 WebSockets Support否则升级握手会被代理打断。多路径服务使用 Custom Locations 按路径拆分转发需要精确控制某段路径时可借助该 location 的advanced_config。域名冲突创建/更新时后端会校验域名唯一性若提示域名已被占用需先确认是否已被其他代理主机、重定向主机或流式主机使用isHostnameTaken会跨主机类型检查。排障入口每台代理主机在生成配置时同时配置了独立的访问日志/data/logs/proxy-host-id_access.log与错误日志/data/logs/proxy-host-id_error.log见 backend/templates/proxy_host.conf并可通过meta.nginx_online观察 Nginx 配置是否生效修改配置后若页面报 Nginx 错误优先查看对应 id 的错误日志。小结代理主机是 Nginx Proxy Manager 的日常主力它把入站端点 SSL 终止这两个核心概念落地为一套从前端表单、REST API、数据模型到 Nginx 模板渲染的完整闭环。理解了本文涉及的字段语义、模板拼装逻辑与生命周期管理你不仅能用好界面还能直接通过 API 自动化管理代理主机并在出现问题时顺着 backend/templates/proxy_host.conf 与 docker/rootfs/etc/nginx/conf.d/include/proxy.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），仅供参考