Nginx Proxy Manager 重定向主机（Redirection Host）完全指南：域名迁移与 301/302 跳转实战

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 Manager 官方帮助文档（RedirectionHosts）展开，系统讲解"重定向主机"（Redirection Host）这一核心功能的原理、配置与底层实现。重定向主机用于将来自某个接入域名的请求整体重定向到另一个域名，最常见的应用场景是网站更换域名后，搜索引擎收录与外部反链仍指向旧域名，需要在不丢失流量与 SEO 权重的前提下平滑过渡。读完本文，你将掌握重定向主机的创建流程、五大核心配置项（目标域名、转发协议、HTTP 状态码、路径保留、SSL 选项）的取值与影响，并通过仓库源码理解跳转规则最终如何落成一段可执行的 Nginx 配置。

什么是重定向主机（Redirection Host）？

重定向主机是 Nginx Proxy Manager 提供的三类主机之一（另外两类是代理主机 Proxy Host 与 404 主机 Dead Host）。它的作用非常单一而明确：把从旧域名进入的请求"转交"给另一个域名。

官方帮助文档对其的定义是：

重定向主机将来自接入域名的请求重定向，并把访问者推送到另一个域名。

最典型的使用动机是：你的网站更换了域名，但搜索引擎收录的链接、其他站点上的外链、用户收藏夹里的书签仍然指向旧域名。此时如果直接放弃旧域名，流量与搜索权重都会流失；而通过重定向主机，访问旧域名old.example.com的用户会被自动带到新域名new.example.com，实现无缝过渡。

需要强调的是，重定向主机与代理主机（Proxy Host）有本质区别：代理主机是把请求转发给上游服务器并返回内容（浏览器地址栏不变），而重定向主机是让浏览器直接跳转到新地址（地址栏变化）。这也是为什么它在迁移场景下优先于代理主机被选用——搜索引擎会将 301 状态码解读为"永久移动"，从而把旧域名的权重传递给新域名。

创建重定向主机：核心配置项详解

在 Nginx Proxy Manager 管理界面左侧菜单进入Hosts → Redirection Hosts，点击Add Redirection Host即可打开创建弹窗。该表单由 RedirectionHostModal.tsx 实现，其初始值（L67-L85）完整反映了所有可配置字段。

必须配置的核心三项

创建重定向主机时，以下三项为必填（对应 API Schema 中的required数组）：

转发协议（forward_scheme）的取值由 redirection-host-object.json 约束为枚举auto、http、https三选一。其中auto是一个非常有用的选项：早期版本默认值为$scheme（跟随请求本身的协议），后来在迁移 20251111090000_redirect_auto_scheme.js 中把数据库列默认值统一改为auto，并将存量数据中的$scheme批量替换为auto。选择auto时，Nginx 会使用$scheme变量自动匹配请求当前的协议（HTTP 请求跳 HTTP，HTTPS 请求跳 HTTPS），避免硬编码协议带来的混合内容问题。

转发状态码（forward_http_code）的取值范围在 Schema 中被限定为 300～308 的整数。前端下拉框（RedirectionHostModal.tsx L229-L246）实际提供了 6 个选项：300、301、302、303、307、308。表单默认值为301（永久重定向），这也是 SEO 迁移场景的标准选择：

• 301 Moved Permanently：永久移动。搜索引擎会把旧 URL 的权重传递给新 URL，适合域名/站点整体迁移；
• 302 Found：临时重定向。权重不转移，适合临时活动页、A/B 测试等短期场景；
• 303 See Other：通常用于表单提交后跳转到结果页（GET 化）；
• 307/308：语义上等价于 302/301，但严格保留请求方法与请求体，适合 POST 等非 GET 请求的重定向场景。

可选配置：路径与安全选项

保留路径（preserve_path）是一个布尔开关，决定跳转时是否携带原始请求的 URI。其核心逻辑体现在 redirection_host.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 %}

• 开启时，old.example.com/blog/post-1会跳转到new.example.com/blog/post-1（通过$request_uri追加原始路径与查询参数）；
• 关闭时，无论访问旧域名的哪个路径，一律跳转到new.example.com根路径。

Block Common Exploits（block_exploits）开启后会引入_exploits.conf模板，对常见漏洞扫描与攻击特征进行拦截，属于全局安全加固的一部分。

其余可选开关（SSL 相关）将在下一节详述。

SSL 与安全配置：证书、强制 HTTPS 与 HSTS

重定向主机的SSL标签页提供与代理主机一致的 HTTPS 能力，这些选项在 redirection-host-object.json 中均有定义：

• SSL Certificate（certificate_id）：为该主机绑定的 SSL 证书。值为0表示不使用证书；也可选择已有证书或新建证书（后端以certificate_id === "new"触发快速签发流程，见 internal/redirection-host.js L23-L27）；
• Force SSL（ssl_forced）：强制将 HTTP 请求 301 到 HTTPS；
• HTTP/2 Support（http2_support）：启用 HTTP/2 协议支持；
• HSTS Enabled（hsts_enabled）：启用 HSTS（HTTP Strict Transport Security）响应头；
• HSTS Subdomains（hsts_subdomains）：HSTS 头是否同时作用于所有子域名。

这些开关最终被渲染进 Nginx 配置的机制可以从模板结构看出：redirection_host.conf 依次 include 了_listen.conf、_certificates.conf、_assets.conf、_exploits.conf、_hsts.conf、_forced_ssl.conf等片段，其中：

• _forced_ssl.conf 在配置了证书且开启ssl_forced时，会读取全局trust_forwarded_proto设置并 include 官方force-ssl.conf片段实现 HTTP→HTTPS 跳转；
• _hsts.conf 只有在"配置了证书 + 开启 Force SSL + 开启 HSTS"三个条件同时满足时，才会输出add_header Strict-Transport-Security $hsts_header always;（63072000 秒 ≈ 2 年），HSTS 头是否覆盖子域名由hsts_subdomains决定，相关取值在模型层由 models/redirection_host.js L13-L22 中的boolFields数组负责数据库读写时布尔值转换。

注意：HSTS 头依赖$hsts_header映射，该映射由_hsts_map.conf片段在 server 块内定义，因此 HSTS 与 Force SSL 的开关是联动生效的。

高级配置与自定义 Nginx 指令

每个重定向主机都可以在Advanced标签页填写自定义 Nginx 配置（advanced_config字段）。在 redirection_host.conf 中，该字段的原始内容会原样注入到server块内、location块之前：

{{ advanced_config }}

这意味着你可以在这里添加自定义的server级指令，例如自定义响应头、限流（limit_req）、访问控制（allow/deny）等。此外模板末尾还保留了一个稳定的自定义入口：

# Custom include /data/nginx/custom/server_redirect[.]conf;

该 include 路径允许你放置全局共享的、所有重定向主机共用的 server 级自定义配置（文件名需匹配server_redirect.conf模式），与每个主机独立的advanced_config形成互补。

底层实现：从 API 请求到 Nginx 配置的完整链路

数据模型与持久化

重定向主机在数据库中对应redirection_host表，由 models/redirection_host.js 中的 Objection.js 模型管理。该模型值得注意的实现细节：

• domain_names与meta为 JSON 列（jsonAttributes），域名列表在插入与更新时都会自动排序（L39、L47），保证数据库与列表展示的一致性；
• 8 个布尔字段（is_deleted、enabled、preserve_path、ssl_forced、block_exploits、hsts_enabled、hsts_subdomains、http2_support）在读写数据库时自动完成 0/1 与 true/false 的转换（boolFields）；
• 模型预定义了owner（创建者）与certificate（证书）两个关联关系，列表与详情接口默认展开["certificate", "owner"]；
• 列表默认按域名 JSON 值排序（castJsonIfNeed("domain_names")ASC）。

REST API 与内部业务逻辑

后端通过 routes/nginx/redirection_hosts.js 暴露以下 REST 端点（均需 JWT 认证，并校验redirection_hosts相关权限，见 lib/access/redirection_hosts-create.json）：

业务逻辑集中在 internal/redirection-host.js，其关键流程可以概括为：

1. 权限校验：通过access.can("redirection_hosts:create|update|get|delete")检查当前用户权限与可见范围（非all可见性下，非管理员只能操作owner_user_id为自身的记录）；
2. 域名占用检查：创建/更新时逐一对domain_names调用internalHost.isHostnameTaken()检查是否与其他主机冲突，若冲突直接抛出ValidationError（"xxx is already in use"）；
3. 数据清洗：调用internalHost.cleanSslHstsData()处理 SSL/HSTS 相关字段的联动默认值；advanced_config缺省时补空字符串；
4. 落库与审计：插入/更新redirection_host表，并同步写入审计日志（internalAuditLog.add，action 为created/updated/enabled/disabled/deleted）；
5. 渲染并应用 Nginx 配置：调用internalNginx.configure(redirectionHostModel, "redirection_host", row)使用 Jinja 模板 redirection_host.conf 渲染出该主机的独立 Nginx 配置文件；启用/删除时还会触发 Nginx 配置删除与reload。

以创建请求为例，API 文档中的完整 JSON 载荷（见 backend/schema/paths/nginx/redirection-hosts/post.json）如下：

{ "domain_names": ["test.example.com"], "forward_domain_name": "example.com", "forward_scheme": "auto", "forward_http_code": 301, "preserve_path": false, "block_exploits": false, "certificate_id": 0, "ssl_forced": false, "http2_support": false, "hsts_enabled": false, "hsts_subdomains": false, "advanced_config": "", "meta": {} }

其中仅有domain_names、forward_scheme、forward_http_code、forward_domain_name四项为必填，其余均可省略。

生成的 Nginx 配置结构

最终为每个重定向主机生成的配置以 redirection_host.conf 为骨架，核心跳转指令就是上面提到的return语句。完整结构大致如下（省略 include 片段细节）：

server { # listen / 证书 / 静态资源 / 安全加固等片段 access_log /data/logs/redirection-host-<id>_access.log standard; error_log /data/logs/redirection-host-<id>_error.log warn; <advanced_config 自定义配置> location / { # HSTS 片段（条件性输出） return 301 https://new.example.com$request_uri; # preserve_path 开启时 # 或 return 301 https://new.example.com; # preserve_path 关闭时 } # Custom include /data/nginx/custom/server_redirect[.]conf; }

启用（enable）与停用（disable）操作分别通过重新渲染配置 / 删除配置文件并 reload 生效，internal/redirection-host.js 中在状态变更后都会写入对应审计日志。

实际使用建议

1. 域名迁移首选 301 + preserve_path 开启：既能把旧域名的全部路径无缝映射到新域名对应路径，又能通过 301 状态码向搜索引擎传递权重；关闭 preserve_path 只适合"所有旧页面统一收拢到新站首页"的极简策略；
2. 协议选择优先auto：避免硬编码 http/https 造成的混合内容告警，同时兼容新旧访客的不同进入协议；
3. 临时活动页用 302：需要频繁改动的落地页应避免 301（浏览器与搜索引擎都会长期缓存），改用 302/307 更稳妥；
4. 创建前确认域名唯一：后端会在创建时校验域名占用，一个域名同时只能归属一个主机（代理/重定向/404/流式主机共用该约束），如遇 "is already in use" 提示需先停用或删除旧主机；
5. SSL 与 HSTS 联动：HSTS 只在"有证书 + Force SSL + HSTS 开启"时生效，且开启后浏览器会强制 HTTPS 访问 2 年，切换前请确保新域名 HTTPS 配置已就绪。

小结

重定向主机是 Nginx Proxy Manager 中结构最简单、但迁移场景价值最高的功能：从 UI 上看只是一张包含域名、协议、状态码、路径保留与 SSL 选项的表单，其背后却串联起 Objection.js 数据模型、REST API 权限体系、域名占用校验、审计日志以及 Jinja 模板渲染 Nginx 配置的完整链路。理解这层实现，不仅能让你在迁移场景中正确选择 301/302 与 preserve_path 的组合，也能在排查"重定向未生效/域名冲突"类问题时快速定位到 internal/redirection-host.js 与 redirection_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