完全指南:域名迁移与 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数组配置项字段名说明示例域名domain_names需要被重定向的接入域名可同时填写多个[old.example.com]转发协议forward_scheme目标域名使用的协议auto/http/https转发状态码forward_http_code重定向返回的 HTTP 状态码301默认/302目标域名forward_domain_name跳转目标域名new.example.com转发协议forward_scheme的取值由 redirection-host-object.json 约束为枚举auto、http、https三选一。其中auto是一个非常有用的选项早期版本默认值为$scheme跟随请求本身的协议后来在迁移 20251111090000_redirect_auto_scheme.js 中把数据库列默认值统一改为auto并将存量数据中的$scheme批量替换为auto。选择auto时Nginx 会使用$scheme变量自动匹配请求当前的协议HTTP 请求跳 HTTPHTTPS 请求跳 HTTPS避免硬编码协议带来的混合内容问题。转发状态码forward_http_code的取值范围在 Schema 中被限定为 300308 的整数。前端下拉框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 Exploitsblock_exploits开启后会引入_exploits.conf模板对常见漏洞扫描与攻击特征进行拦截属于全局安全加固的一部分。其余可选开关SSL 相关将在下一节详述。SSL 与安全配置证书、强制 HTTPS 与 HSTS重定向主机的SSL标签页提供与代理主机一致的 HTTPS 能力这些选项在 redirection-host-object.json 中均有定义SSL Certificatecertificate_id为该主机绑定的 SSL 证书。值为0表示不使用证书也可选择已有证书或新建证书后端以certificate_id new触发快速签发流程见 internal/redirection-host.js L23-L27Force SSLssl_forced强制将 HTTP 请求 301 到 HTTPSHTTP/2 Supporthttp2_support启用 HTTP/2 协议支持HSTS Enabledhsts_enabled启用 HSTSHTTP Strict Transport Security响应头HSTS Subdomainshsts_subdomainsHSTS 头是否同时作用于所有子域名。这些开关最终被渲染进 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方法路径功能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停用主机业务逻辑集中在 internal/redirection-host.js其关键流程可以概括为权限校验通过access.can(redirection_hosts:create|update|get|delete)检查当前用户权限与可见范围非all可见性下非管理员只能操作owner_user_id为自身的记录域名占用检查创建/更新时逐一对domain_names调用internalHost.isHostnameTaken()检查是否与其他主机冲突若冲突直接抛出ValidationErrorxxx is already in use数据清洗调用internalHost.cleanSslHstsData()处理 SSL/HSTS 相关字段的联动默认值advanced_config缺省时补空字符串落库与审计插入/更新redirection_host表并同步写入审计日志internalAuditLog.addaction 为created/updated/enabled/disabled/deleted渲染并应用 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 中在状态变更后都会写入对应审计日志。实际使用建议域名迁移首选 301 preserve_path 开启既能把旧域名的全部路径无缝映射到新域名对应路径又能通过 301 状态码向搜索引擎传递权重关闭 preserve_path 只适合所有旧页面统一收拢到新站首页的极简策略协议选择优先auto避免硬编码 http/https 造成的混合内容告警同时兼容新旧访客的不同进入协议临时活动页用 302需要频繁改动的落地页应避免 301浏览器与搜索引擎都会长期缓存改用 302/307 更稳妥创建前确认域名唯一后端会在创建时校验域名占用一个域名同时只能归属一个主机代理/重定向/404/流式主机共用该约束如遇 is already in use 提示需先停用或删除旧主机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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考