Nginx Proxy Manager 重定向主机Redirection Host完全指南域名迁移场景下的 301/302 跳转配置与源码实现【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager本篇指南围绕 Nginx Proxy ManagerNPM中的**重定向主机Redirection Host**展开它负责把来自某个入站域名的请求整体重定向到另一个域名最常见的落地场景是网站更换域名后搜索引擎索引与外部引用链接仍指向旧域名。读完本文你将掌握重定向主机的适用场景、前端表单中每个配置项的含义与取值范围、后端生成的 Nginx 配置结构以及创建/启停/删除背后的完整调用链与权限模型可直接用于生产环境的域名迁移与 301/302 跳转治理。什么是重定向主机Redirection HostNginx Proxy Manager 的官方帮助文档对重定向主机给出了非常精炼的定义见 no/RedirectionHosts.md 与 en/RedirectionHosts.md重定向主机会将来自入站域名的请求重定向并把访问者推送到另一个域名。一句话概括它不做反向代理、不承载业务流量只负责“把 A 域名的访问者带到 B 域名”。重定向主机在 NPM 中是与代理主机Proxy Host、流Stream、404 主机Dead Host并列的第四类主机资源对应前端 pages/Nginx/RedirectionHosts 页面和后端redirection_host数据表见 backend/models/redirection_host.js。最常见的用途网站更换域名官方文档明确点出了这类主机的典型场景使用这种主机最常见的理由是你的网站更换了域名但搜索引擎或引用链接仍然指向旧域名。举例来说你的站点从old.example.com迁往new.example.com后搜索引擎收录的旧 URL 短期内不会全部更新其他网站、邮件、二维码、书签中遗留的旧链接依然有效直接访问旧域名根路径的用户需要一个“无缝过渡”。此时在 NPM 中创建一个重定向主机把old.example.com指向new.example.com就能让所有残留流量自动落到新域名同时通过合适的 HTTP 状态码如 301把“链接权重”传递给新地址避免 SEO 资产流失。核心配置项详解一个重定向主机由哪些字段构成重定向主机的完整字段集合可以从三处交叉印证前端编辑弹窗 frontend/src/modals/RedirectionHostModal.tsx 中的表单初始值API 对象定义 backend/schema/components/redirection-host-object.json数据模型 backend/models/redirection_host.js 中的布尔字段与 JSON 字段。Details详情页签配置项含义取值范围 / 默认值说明domain_names入站域名被重定向的旧域名任意合法域名支持通配符可配置多个保存后自动排序见 redirection_host.js前端组件DomainNamesField允许通配符域名isWildcardPermittedforward_scheme跳转目标使用的协议auto/http/httpsauto为默认值表示沿用请求本身的协议详见下文“auto 方案”小节forward_domain_name跳转目标域名新域名域名长度 1255前端校验见 RedirectionHostModal.tsx即用户最终被送往的地址forward_http_code重定向使用的 HTTP 状态码300/301/302/303/307/308默认301Schema 约束最小 300、最大 308见 redirection-host-object.jsonpreserve_path是否保留原路径布尔默认false开启后旧域名 URL 的路径部分会原样带到新域名block_exploits是否启用漏洞攻击拦截规则布尔默认false对应模板中的_exploits.conf引用SSL 页签配置项含义说明certificate_id绑定的 SSL 证书支持选择已有证书或直接创建新证书弹窗中allowNew后端将certificate_id为new的请求转换为自动签发见 redirection-host.jsssl_forced强制 HTTPS开启后 HTTP 请求会被强制跳转到 HTTPS对应模板中的_forced_ssl.confhttp2_support启用 HTTP/2布尔默认关闭hsts_enabled启用 HSTS 响应头布尔默认关闭hsts_subdomainsHSTS 是否包含子域名布尔默认关闭模型中将hsts_enabled、hsts_subdomains等一并列为布尔字段见 redirection_host.jsAdvanced高级页签配置项含义说明advanced_config自定义 Nginx 配置片段默认空字符串会以原样注入生成的 server 块见模板第 18 行创建时若未传该字段后端会补默认值见 redirection-host.js关于forward_scheme auto的来历早期版本中forward_scheme的默认值曾经是 Nginx 变量$scheme即“沿用请求协议”的字面写法而迁移脚本 20251111090000_redirect_auto_scheme.js 将默认值统一改成了语义更明确的auto并把存量数据中$scheme的记录迁移为auto。因此在当前版本中auto的含义就是“跟随访问者原始请求的协议”——请求是 HTTP 就跳 HTTP是 HTTPS 就跳 HTTPS避免因硬编码协议造成跳转后证书或协议不匹配的问题。底层原理重定向主机的 Nginx 配置是如何生成的NPM 后端采用模板引擎nunjucks 风格语法渲染每个主机的独立配置文件重定向主机的模板位于 backend/templates/redirection_host.conf。其核心逻辑如下server { {% include _listen.conf %} {% include _certificates.conf %} {% include _assets.conf %} {% include _exploits.conf %} {% include _hsts.conf %} {% include _forced_ssl.conf %} access_log /data/logs/redirection-host-{{ id }}_access.log standard; error_log /data/logs/redirection-host-{{ id }}_error.log warn; {{ advanced_config }} {% if use_default_location %} location / { {% include _hsts.conf %} {% if preserve_path 1 or preserve_path true %} return {{ forward_http_code }} {{ forward_scheme }}://{{ forward_domain_name }}$request_uri; {% else %} return {{ forward_http_code }} {{ forward_scheme }}://{{ forward_domain_name }}; {% endif %} } {% endif %} # Custom include /data/nginx/custom/server_redirect[.]conf; }这段模板揭示了几个关键实现事实跳转本质是return指令在location /中根据状态码forward_http_code直接返回重定向响应不经过任何上游代理路径保留由$request_uri决定当preserve_path开启时目标地址拼上$request_uri原始请求的完整 URI关闭时则只跳到目标域名根路径。例如保留路径301 https://new.example.com$request_uri→ 访问old.example.com/about会到达new.example.com/about不保留路径301 https://new.example.com→ 所有旧域名请求都落到new.example.com根路径目标协议直接写入模板forward_schemeauto/http/https被渲染进return的目标 URL自定义配置有独立注入点advanced_config插入 server 块同时预留/data/nginx/custom/server_redirect[.]conf文件引用用于在容器内追加手工配置SSL/HSTS 等能力复用公共模板_listen.conf监听端口与 HTTP/2、_certificates.conf证书路径、_forced_ssl.conf强制 HTTPS、_hsts.confHSTS 头与跳转等均为跨主机类型共享的片段目录见 backend/templates。从后端逻辑看主机启用时调用internalNginx.configure(redirectionHostModel, redirection_host, row)渲染并写入配置禁用或删除时调用internalNginx.deleteConfig(...)删除配置并执行internalNginx.reload()热加载见 backend/internal/redirection-host.js。后端实现创建、更新、启停与删除的完整调用链重定向主机的业务逻辑集中在 backend/internal/redirection-host.js对外通过 backend/routes/nginx/redirection_hosts.js 暴露 REST API。对外 API 一览方法路径功能GET/api/nginx/redirection-hosts列出全部重定向主机支持expand与query搜索POST/api/nginx/redirection-hosts创建新重定向主机GET/api/nginx/redirection-hosts/{id}获取单个主机详情PUT/api/nginx/redirection-hosts/{id}更新主机DELETE/api/nginx/redirection-hosts/{id}删除主机POST/api/nginx/redirection-hosts/{id}/enable启用主机POST/api/nginx/redirection-hosts/{id}/disable禁用主机所有路由均挂载jwtdecode()中间件进行身份认证请求体通过getValidationSchema(/nginx/redirection-hosts, ...)对应的 OpenAPI 校验见 redirection_hosts.js。创建流程createcreate 方法 的执行链可以拆解为五步权限校验access.can(redirection_hosts:create, data)域名占用检查对domain_names中的每个域名调用internalHost.isHostnameTaken()任何一个被占用即抛出ValidationError“xxx is already in use”避免与代理主机、其他重定向主机冲突数据落库写入redirection_host表并通过cleanSslHstsData规整 SSL/HSTS 字段快捷签发证书如果certificate_id传了new则调用internalCertificate.createQuickCertificate()自动申请证书并回填到主机生成 Nginx 配置调用internalNginx.configure()渲染模板最后写入审计日志action: createdobject_type: redirection-host。更新与启停updateL115-L220更新时同样做域名占用检查此时排除自身id可顺带快捷签发新证书随后patch数据库、重新configureNginx、写审计日志enableL318-L360把enabled置 1 并重新生成配置若已是启用状态会抛出“Host is already enabled”disableL369-L410把enabled置 0删除 Nginx 配置并reload()同时记录disabled审计日志deleteL273-L309采用软删除——仅把is_deleted置 1见 模型定义随后删除 Nginx 配置并重载。数据模型与关联RedirectionHost 模型 定义了redirection_host表的字段映射JSON 字段domain_names、meta其中meta.nginx_online/meta.nginx_err记录最后一次配置生成的健康状态见 schema 示例关联关系owner创建者owner_user_id→user.id与certificatecertificate_id→certificate.id支持expandcertificate,owner展开查询默认按domain_names升序排列。权限模型谁能创建和管理重定向主机重定向主机的权限定义在 backend/lib/access/redirection_hosts-create.jsonupdate 使用 redirection_hosts-update.json规则相同满足任一条件即可管理员角色roles#/definitions/admin普通用户user角色且拥有permission_redirection_hosts: manage级别的权限。此外可见性遵循“数据隔离”逻辑在get与getAll中如果当前用户的permission_visibility ! all查询会强制追加owner_user_id 当前用户条件见 redirection-host.js 与 L431-L433即普通用户只能看到自己创建的主机。前端通过 HasPermission.tsx 等组件控制按钮显隐Permissions 模块 中定义了permission_redirection_hosts的取值。操作入口与实战建议如何创建在 NPM 管理界面依次进入Hosts → Redirection Hosts点击新增按钮打开 RedirectionHostModal按上文“Details / SSL / Advanced”三个页签填写即可也可以通过POST /api/nginx/redirection-hosts以 JSON 方式创建参考 redirection_hosts-post.json 对应的请求结构。场景化配置建议域名迁移 SEO 传承forward_http_code选301永久重定向并开启preserve_path让旧站每个 URL 的权重完整传递到新站对应路径临时过渡页若只是短期告知访客迁移选302或307避免搜索引擎过早缓存新地址协议跟随forward_scheme保持auto配合ssl_forced强制 HTTPS 后HTTP 请求会先升到 HTTPS 再按 HTTPS 协议跳转链路更干净批量旧域名domain_names支持多个域名与通配符如*.old.example.com一个主机即可收敛整组旧域名注意域名全局唯一已被其他主机占用的域名无法重复绑定由创建流程的占用检查保证高级定制需要自定义跳转逻辑如按路径分流时使用 Advanced 页签的advanced_config或挂载/data/nginx/custom/server_redirect[.]conf文件。小结重定向主机是 Nginx Proxy Manager 中结构最简单、但域名迁移场景下不可或缺的一类资源前端表单暴露forward_scheme、forward_http_code、preserve_path、SSL/HSTS 等完整配置后端 redirection_host.conf 模板将其渲染为一条return指令redirection-host.js 负责域名唯一性校验、快捷证书签发、Nginx 配置生成与审计日志闭环。理解这三层实现你就能在更换域名时快速、安全地完成旧域名的 301/302 收敛让流量与 SEO 资产平稳过渡。【免费下载链接】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），仅供参考