企业官网建设流程全解析

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（NPM）中的**重定向主机（Redirection Host）**展开：它负责把来自某个入站域名的请求整体重定向到另一个域名，最常见的落地场景是网站更换域名后，搜索引擎索引与外部引用链接仍指向旧域名。读完本文，你将掌握重定向主机的适用场景、前端表单中每个配置项的含义与取值范围、后端生成的 Nginx 配置结构，以及创建/启停/删除背后的完整调用链与权限模型，可直接用于生产环境的域名迁移与 301/302 跳转治理。

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

Nginx 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 资产流失。

核心配置项详解：一个重定向主机由哪些字段构成

重定向主机的完整字段集合，可以从三处交叉印证：

1. 前端编辑弹窗 frontend/src/modals/RedirectionHostModal.tsx 中的表单初始值；
2. API 对象定义 backend/schema/components/redirection-host-object.json；
3. 数据模型 backend/models/redirection_host.js 中的布尔字段与 JSON 字段。

Details（详情）页签

SSL 页签

Advanced（高级）页签

关于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_scheme（auto/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.conf（HSTS 头与跳转）等均为跨主机类型共享的片段，目录见 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 一览

所有路由均挂载jwtdecode()中间件进行身份认证，请求体通过getValidationSchema("/nginx/redirection-hosts", ...)对应的 OpenAPI 校验（见 redirection_hosts.js）。

创建流程（create）

create 方法 的执行链可以拆解为五步：

1. 权限校验：access.can("redirection_hosts:create", data)；
2. 域名占用检查：对domain_names中的每个域名调用internalHost.isHostnameTaken()，任何一个被占用即抛出ValidationError（“xxx is already in use”），避免与代理主机、其他重定向主机冲突；
3. 数据落库：写入redirection_host表，并通过cleanSslHstsData规整 SSL/HSTS 字段；
4. 快捷签发证书：如果certificate_id传了"new"，则调用internalCertificate.createQuickCertificate()自动申请证书并回填到主机；
5. 生成 Nginx 配置：调用internalNginx.configure()渲染模板，最后写入审计日志（action: "created"，object_type: "redirection-host"）。

更新与启停

• update（L115-L220）：更新时同样做域名占用检查（此时排除自身id），可顺带快捷签发新证书，随后patch数据库、重新configureNginx、写审计日志；
• enable（L318-L360）：把enabled置 1 并重新生成配置；若已是启用状态会抛出“Host is already enabled”；
• disable（L369-L410）：把enabled置 0，删除 Nginx 配置并reload()，同时记录disabled审计日志；
• delete（L273-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）与certificate（certificate_id→certificate.id），支持expand=certificate,owner展开；
• 查询默认按domain_names升序排列。

权限模型：谁能创建和管理重定向主机

重定向主机的权限定义在 backend/lib/access/redirection_hosts-create.json（update 使用 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 对应的请求结构）。

场景化配置建议

1. 域名迁移 + SEO 传承：forward_http_code选301（永久重定向），并开启preserve_path，让旧站每个 URL 的权重完整传递到新站对应路径；
2. 临时过渡页：若只是短期告知访客迁移，选302或307，避免搜索引擎过早缓存新地址；
3. 协议跟随：forward_scheme保持auto，配合ssl_forced强制 HTTPS 后，HTTP 请求会先升到 HTTPS 再按 HTTPS 协议跳转，链路更干净；
4. 批量旧域名：domain_names支持多个域名与通配符（如*.old.example.com），一个主机即可收敛整组旧域名；注意域名全局唯一，已被其他主机占用的域名无法重复绑定（由创建流程的占用检查保证）；
5. 高级定制：需要自定义跳转逻辑（如按路径分流）时，使用 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