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导读重定向主机Redirection Host是 Nginx Proxy Manager 内置的四大主机类型之一用于将来自某个接入域名的请求整体推送到另一个域名是网站更换域名、合并站点、规范化域名如统一 www 与非 www时最常用的工具。本文以仓库中 RedirectionHosts.md波兰语版 为骨架结合 redirection_host.conf 模板、redirection_host.js 内部实现、redirection_host.js 数据模型 以及 RedirectionHostModal.tsx 前端表单 等源码系统讲解重定向主机的概念、适用场景、UI 配置项、底层 Nginx 生成逻辑、REST API 调用方法与状态码选型帮助你在一键式管理界面之外真正理解重定向主机从填表到生效的完整链路。什么是重定向主机Redirection Host按官方帮助文档的定义重定向主机将来自接入域名的请求推送给访问者使其跳转到另一个域名。换句话说当用户访问old-domain.com时浏览器会被引导到new-domain.com其行为本质上就是 Nginx 的return code url指令。最典型的应用场景网站更换域名帮助文档明确指出使用这种主机最常见的原因是你的网站更换了域名但仍然有来自搜索引擎或外部引用referrer的链接指向旧域名。例如站点从example.com迁移到example.net但 Google、必应等搜索引擎索引里还留存大量example.com的旧链接第三方网站、邮件、名片、二维码中印着旧域名你希望旧域名的 SEO 权重301 跳转平滑过渡到新域名。此时无需在新服务器上重新搭建一套站点只需在 Nginx Proxy Manager 中为旧域名创建一个重定向主机指向新域名即可。访问旧链接的用户会在毫秒级被带到新地址既挽留了流量也保留了搜索引擎对旧链接的信任。与代理主机Proxy Host反向代理到后端服务不同重定向主机不转发流量到任何上游服务器而是直接由 Nginx 返回一个跳转响应与 404 主机Dead Host也不同它返回的是目标已搬迁的正向指引而非错误页。重定向主机的完整数据模型在深入操作之前先看后端如何持久化一条重定向主机记录。redirection_host.js 数据模型 对应数据库表redirection_host其 JSON 属性包含domain_names与meta两个字段同时通过boolFields列表将以下字段按布尔值读写字段类型含义domain_namesarray接入域名列表可多个自动排序forward_domain_namestring重定向目标域名forward_schemestring目标协议auto/http/httpsforward_http_codeinteger重定向状态码范围 300–308默认 302preserve_pathboolean是否保留原始请求路径certificate_idinteger绑定的 SSL 证书 IDssl_forcedboolean强制 HTTPShttp2_supportboolean启用 HTTP/2hsts_enabledboolean启用 HSTS 头hsts_subdomainsbooleanHSTS 是否覆盖子域名block_exploitsboolean屏蔽常见攻击特征advanced_configstring自定义 Nginx 配置片段enabledboolean是否启用owner_user_idinteger创建者用户 ID完整的字段约束见 redirection-host-object.json 的 OpenAPI Schema其中forward_scheme的枚举值即auto、http、httpsforward_http_code校验范围为 300–308。字段演进从$scheme到auto从迁移文件可以窥见该功能的历史演进20210210154702_redirection_scheme.js 新增forward_scheme字段默认值为 Nginx 变量$scheme跟随请求自身协议20210210154703_redirection_status_code.js 新增forward_http_code字段默认 30220251111090000_redirect_auto_scheme.js 将forward_scheme的默认值从$scheme改为auto并把存量$scheme数据统一升级为auto。这意味着当前版本中自动auto协议是推荐且默认的行为旧版$scheme语义已被auto取代二者在生成配置时都会被渲染为跟随请求协议的跳转。在管理界面中创建重定向主机前端创建/编辑入口是 RedirectionHostModal.tsx 弹窗界面分为 Details详情、SSL、Advanced高级三个 Tab。以下是每个字段的实操说明。Details 标签页Domain Names接入域名填写需要被跳转的旧域名支持通配符如*.old-domain.com可填多个。Forward Scheme目标协议下拉可选auto自动默认、http、https。选择auto时跳转协议与请求原始协议一致HTTP 请求跳 HTTPHTTPS 请求跳 HTTPS。Forward Domain Name目标域名跳转目标域名如new-domain.com。前端校验要求长度 1–255 个字符validateString(1, 255)。Forward HTTP Code重定向状态码下拉可选 300、301、302、303、307、308默认 301。前端默认值可见 RedirectionHostModal.tsx 的 initialValuesforwardScheme默认auto、forwardHttpCode默认301。Options 选项区Preserve Path保留路径开启后old.com/a/b会跳转到new.com/a/b原路径被完整带到目标地址关闭则一律跳到new.com根路径。Block Common Exploits屏蔽常见漏洞利用开启后 Nginx 会套用_exploits.conf中的规则过滤常见攻击特征。SSL 标签页SSL Certificate为该重定向主机绑定证书。如果目标域名即接入域名需要支持 HTTPS 访问就必须在此选择或新建证书allowNew允许直接新建。SSL Options包括ssl_forced强制 HTTPS把 80 端口请求 301 到 443、http2_supportHTTP/2、hsts_enabled与hsts_subdomainsHSTS 头与子域覆盖。Advanced 标签页Custom Nginx Configuration可输入任意 Nginx 指令片段渲染时会被原样注入到 server 块中见下文模板中的{{ advanced_config }}。底层原理Nginx 配置如何生成保存重定向主机后后端会调用internalNginx.configure(redirectionHostModel, redirection_host, row)生成对应的站点配置见 redirection-host.js 中create/update/enable流程渲染模板为 redirection_host.conf。该模板的核心逻辑如下{% if enabled %} 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; } {% endif %}几个关键点重定向指令location /块内的return指令就是跳转本体。preserve_path开启时追加 Nginx 内置变量$request_uri以携带完整原始路径关闭时只跳根路径。监听端口由 _listen.conf 模板 决定listen 80始终存在仅当绑定证书certificate非空时才追加listen 443 ssl并依据http2_support开关决定http2 on/off。日志分离每个主机拥有独立的redirection-host-{{ id }}_access.log与error_log便于按主机排查跳转问题。扩展点模板末尾include /data/nginx/custom/server_redirect[.]conf允许管理员放置服务器级自定义片段注意[.]写法确保该文件即使不存在也不会报错。禁用处理当enabled为假时整个 server 块不会渲染配置即被移除。一处易被忽略的细节forward_scheme的渲染模板中目标地址为{{ forward_scheme }}://{{ forward_domain_name }}。当用户在界面上选择auto时后端将其渲染为跟随请求协议的形式语义与旧版$scheme等价见 redirect_auto_scheme 迁移选择http或https则固定使用该协议适合强制将流量从 HTTP 跳往 HTTPS 目标的场景。状态码选型301、302、307、308 怎么选前端允许在 300、301、302、303、307、308 之间选择见 RedirectionHostModal.tsx 的选项列表这也是 OpenAPI Schema 中 300–308 范围约束的来源。常见选择建议状态码语义适用场景301永久重定向网站更换域名的首选搜索引擎会把旧域名的权重传递给新域名302临时重定向短期维护、A/B 测试、活动页跳转搜索引擎不更新索引目标303See Other通常配合 POST 请求把提交后结果重定向到 GET 页面307临时重定向保留方法与 302 类似但严格保留 HTTP 方法与请求体适合 API 场景308永久重定向保留方法与 301 类似但保留方法与请求体适合 API 永久迁移对于网站换了域名但旧链接仍被引用这一官方文档给出的核心场景默认的 301 是最佳选择它对浏览器与搜索引擎都声明这是永久迁移。通过 REST API 管理重定向主机重定向主机不仅能在 Web 界面操作还暴露了完整的 REST API路由定义在 routes/nginx/redirection_hosts.js方法路径说明GET/api/nginx/redirection-hosts列出全部重定向主机支持expand、query参数POST/api/nginx/redirection-hosts创建重定向主机GET/api/nginx/redirection-hosts/{host_id}获取单个主机详情PUT/api/nginx/redirection-hosts/{host_id}更新主机DELETE/api/nginx/redirection-hosts/{host_id}删除主机软删除置is_deleted 1POST/api/nginx/redirection-hosts/{host_id}/enable启用主机POST/api/nginx/redirection-hosts/{host_id}/disable禁用主机一个典型的创建请求体对应 redirection_hosts-create.json 请求校验 与 OpenAPI 约束{ domain_names: [old-domain.com, www.old-domain.com], forward_scheme: auto, forward_domain_name: new-domain.com, forward_http_code: 301, preserve_path: true, certificate_id: 0, ssl_forced: false, http2_support: false, hsts_enabled: false, block_exploits: false, advanced_config: , enabled: true }创建时若传certificate_id: new后端会走 internalRedirectionHost.create 中的快速证书签发流程先建主机再调internalCertificate.createQuickCertificate为该域名申请证书随后回填certificate_id并重新拉取带证书的完整对象。后端处理链路的关键约束从 internalRedirectionHost 的实现 可以看到创建/更新时的重要校验域名唯一性创建时逐个调用internalHost.isHostnameTaken(domain_name)检查接入域名是否已被其他主机代理主机、重定向主机、流等占用重复会抛出ValidationError[hostname] is already in use更新时通过传入thisData.id排除自身。权限校验所有操作都经过access.can(redirection_hosts:create|update|get|delete|list)权限闸门权限不足时非管理员只能操作自己创建的主机owner_user_id过滤见 get 与 getAll 中permission_visibility ! all分支。配置联动create/update/enable成功后都会触发 Nginx 配置重建disable/delete则删除对应配置文件并reload。审计日志每次创建、更新、启用、禁用、删除都会写入审计日志object_type: redirection-host管理员可在 Audit Log 页面追溯操作历史。前端渲染与真实使用流程在 Web 界面中重定向主机列表页位于Hosts → Redirection Hosts对应 pages/Nginx/RedirectionHosts 目录下的表格与包装组件。点击 Add Redirection Host 打开上述弹窗完整填写并保存后后端同步生成 Nginx 配置并重载几秒内跳转即生效。实际运维建议先在测试域名上用 302 验证跳转行为与路径保留效果确认无误后再改为 301 正式上线旧域名若同时承担邮件等非 Web 服务重定向主机只处理 HTTP(S) 流量不影响其他端口若旧域名需要 HTTPS 跳转务必在 SSL 标签页绑定有效证书否则 443 端口无法监听迁移完成后保留重定向主机一段时间通常建议 6–12 个月等待搜索引擎完成索引更新再考虑清理。总结重定向主机是 Nginx Proxy Manager 中实现域名搬迁的最直接手段一条记录、一次保存底层即渲染出包含return指令的 server 块。通过本文你可以看到它并非黑盒——redirection_host.conf 模板 定义了跳转指令的生成逻辑redirection-host.js 与 redirection_host.js 模型 定义了字段约束、权限与生命周期前端 RedirectionHostModal.tsx 与 REST 路由 则提供了两套等价的操作入口。无论是老站迁移、域名统一还是短期活动跳转理解这套机制后你都能在界面与 API 之间自如选择并准确预判生成的 Nginx 行为。【免费下载链接】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），仅供参考