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 的重定向主机Redirection Host功能为核心完整讲解其工作原理、配置字段、Web 界面与 REST API 两种创建方式以及底层 Nginx 配置生成机制。读完本文你将掌握如何在域名更换、站点合并等场景下用重定向主机把旧域名的流量平滑迁移到新域名并能结合源码理解preserve_path 保留路径auto 转发协议等选项的真实行为。什么是重定向主机Redirection Host根据仓库内置帮助文档 frontend/src/locale/src/HelpDoc/ga/RedirectionHosts.md 的定义Redirection Host重定向主机会将来自入站域名的请求重定向redirect到另一个域名。它与代理主机Proxy Host的关键区别在于代理主机是转发并响应请求而重定向主机是告诉浏览器去别的地方——Nginx 会直接返回一个 3xx 状态码让浏览器重新发起对目标域名的请求。因此在 backend/templates/redirection_host.conf 中核心逻辑只是简短的return指令而不涉及proxy_pass反向代理。最常见的适用场景原文档明确指出重定向主机的头号用途最常见的使用场景是你的网站更换了域名但搜索引擎索引或外部引用链接仍然指向旧域名。例如站点从old-domain.com迁移到new-domain.com后搜索引擎Google、Bing 等索引库中仍保留旧域名的大量收录链接其他站点、论坛、邮件签名中的链接仍指向旧域名老用户收藏夹里存的是旧域名。此时为旧域名创建一条重定向主机将所有请求 301 永久跳转到新域名既能保住 SEO 权重301 会传递绝大部分链接权重又能让所有旧链接无感落地到新站点。除域名更换外域名合并、站点下线后引流到替代站点、主域名跳转到www子域名等场景也适用。重定向主机的核心配置字段仓库通过 backend/schema/components/redirection-host-object.json 定义了重定向主机的完整数据模型结合 frontend/src/modals/RedirectionHostModal.tsx 中的前端表单可以梳理出以下核心配置项字段类型说明可选值 / 默认值domain_namesstring[]入站域名监听哪些域名支持通配符必填多个域名逗号分隔forward_domain_namestring跳转目标域名必填如example.comforward_schemestring跳转使用的协议auto默认/http/httpsforward_http_codeinteger重定向 HTTP 状态码300~308前端默认301preserve_pathboolean是否保留原始 URL 路径false默认certificate_idinteger绑定的 SSL 证书 ID0表示不启用 HTTPS0默认ssl_forcedboolean强制 HTTPS需要证书falsehttp2_supportboolean是否启用 HTTP/2falsehsts_enabledboolean是否启用 HSTS需要证书且强制 SSLfalsehsts_subdomainsbooleanHSTS 是否覆盖子域名falseblock_exploitsboolean是否启用漏洞攻击拦截规则falseadvanced_configstring注入到 server 块的额外 Nginx 配置空字符串enabledboolean是否启用该主机true其中几个关键字段值得展开说明forward_http_codeschema 中限定minimum: 300, maximum: 308前端下拉框提供300、301、302、303、307、308六个选项。SEO 场景下永久迁移用301临时迁移用302。forward_scheme的auto值这是较新版本引入的默认值。旧版本该字段默认是 Nginx 变量$scheme即跟随入站请求的协议。迁移脚本 backend/migrations/20251111090000_redirect_auto_scheme.js 将列默认值改为auto并把历史数据中的$scheme统一更新为auto。而在配置生成阶段见 backend/internal/nginx.js后端会把既不是http也不是https的forward_scheme归一化为$scheme再写入模板——所以auto的实际效果就是与入站请求同协议保证 HTTPS 请求跳转到 HTTPS、HTTP 请求跳转到 HTTP避免协议降级。preserve_path决定跳转时是否把原路径带过去详见下文模板分析。方式一通过 Web 管理界面创建在登录 nginx-proxy-manager 管理面板后进入Hosts → Redirection Hosts页面点击Add Redirection Host即可打开创建弹窗对应组件 frontend/src/modals/RedirectionHostModal.tsx。弹窗分为三个标签页Details详情页填写入站域名、跳转目标域名、协议与状态码、以及两个开关选项Domain Names入站域名需要跳转的旧域名可填写多个多个域名会同时生效Forward Domain Name跳转目标域名前端校验其长度 1~255 字符placeholder 示例为example.comForward Schemeauto/http/https三选一默认autoForward HTTP Code默认301Preserve Path保留路径开启后https://old.example.com/blog/post-1会跳转到https://new.example.com/blog/post-1关闭则一律跳到目标域名根路径Block Common Exploits拦截常见攻击开启后引入 backend/templates/_exploits.conf 中的拦截规则。SSL 页选择证书、是否强制 SSL、是否启用 HTTP/2 与 HSTS含 HSTS 子域名选项。如果入站域名尚未申请证书可以直接在证书下拉框中选择新建allowNew后端会自动走证书快速签发流程。Advanced高级页提供advanced_config文本框内容会原样注入到生成的 Nginx server 块中用于添加模板未覆盖的指令。方式二通过 REST API 创建curl 示例重定向主机的 REST 接口由 backend/routes/nginx/redirection_hosts.js 注册完整路由为GET /api/nginx/redirection-hosts—— 列出全部重定向主机POST /api/nginx/redirection-hosts—— 新建返回 201GET /api/nginx/redirection-hosts/:host_id—— 查询单个PUT /api/nginx/redirection-hosts/:host_id—— 更新DELETE /api/nginx/redirection-hosts/:host_id—— 删除POST /api/nginx/redirection-hosts/:host_id/enable、.../disable—— 启用 / 禁用参考 OpenAPI 文档 backend/schema/paths/nginx/redirection-hosts/post.json 中的请求示例创建一个旧域名永久跳转到新域名的重定向主机curl -X POST https://your-npm-host/api/nginx/redirection-hosts \ -H Authorization: Bearer your-token \ -H Content-Type: application/json \ -d { domain_names: [old-domain.com, www.old-domain.com], forward_domain_name: new-domain.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: {} }注意该接口需要redirection_hosts.manage权限对应的 Bearer Token创建时请求体中的必填字段仅为domain_names、forward_scheme、forward_http_code、forward_domain_name四项其余字段可省略后端与数据库会自动填充默认值。创建成功后返回的 201 响应示例见同一文件会包含完整的 Redirection Host 对象id、created_on、owner_user_id、enabled、certificate、owner等字段其中owner是创建者用户信息meta记录 Nginx 重载后的状态如nginx_online、nginx_err。底层原理Nginx 配置是如何生成的创建或更新重定向主机后后端调用 backend/internal/nginx.js 的configure方法基于 Jinja 模板 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;从中可以确认以下实现细节跳转指令是returnpreserve_path开启时返回目标 URL 拼接$request_uri保留原始路径与查询参数关闭时只返回目标域名根路径。这正是保留路径开关在源码层面的全部差异。forward_scheme归一化模板渲染前backend/internal/nginx.js 会把auto等非http/https值改写为$scheme因此最终生成的指令形如return 301 $scheme://new-domain.com;Nginx 会依据入站请求的协议自动决定 http 或 https。监听与证书backend/templates/_listen.conf 根据是否绑定证书决定是否监听443 ssl并写入server_name多个入站域名以空格连接与http2 on/offbackend/templates/_certificates.conf 根据证书 providerLets Encrypt 或自定义引入对应的ssl_certificate路径。安全增强ssl_forced开启时backend/templates/_forced_ssl.conf 引入force-ssl.conf将所有 HTTP 请求 301 到 HTTPShsts_enabled时 backend/templates/_hsts.conf 追加Strict-Transport-Security响应头有效期 63072000 秒即 2 年。自定义扩展点advanced_config注入到 server 块内部同时支持管理员手工放置/data/nginx/custom/server_redirect[.]conf文件实现更精细的 location 定制模板中以# Custom注释标出。生命周期管理启用、禁用、删除与审计重定向主机的完整生命周期在 backend/internal/redirection-host.js 中实现全部操作都带有权限校验redirection_hosts:create/update/delete/list和审计日志记录创建create先逐个校验入站域名是否被其他主机占用internalHost.isHostnameTaken冲突直接抛ValidationError再写入数据库若请求中certificate_id为字符串new会自动调用internalCertificate.createQuickCertificate快速签发证书并回填最后重新拉取数据、生成 Nginx 配置并写入审计日志object_type: redirection-hostaction: created。更新update同样先做域名占用检查会排除自身 id修改后重新生成 Nginx 配置。启用 / 禁用enable / disable仅翻转enabled字段。启用时重新生成配置禁用时调用internalNginx.deleteConfig删除配置文件并reload()同时记录enabled/disabled审计动作。删除delete采用软删除——数据库中仅将is_deleted置 1见 backend/models/redirection_host.js 中的布尔字段定义随后删除 Nginx 配置并重载。数据模型方面重定向主机存储在redirection_host表关联字段owner_user_id属主用户与certificate_id证书domain_names和meta是 JSON 列布尔字段enabled、preserve_path、ssl_forced、block_exploits、hsts_enabled、hsts_subdomains、http2_support在数据库中以 0/1 存储、API 层自动转换。这些定义都可在 backend/models/redirection_host.js 中核实。常见问题与注意事项301 与 302 怎么选域名永久更换、希望转移 SEO 权重用301临时迁移、后续可能改回旧域名用302或307。要不要开启 preserve_path如果新旧站点 URL 结构完全一致只是域名变了建议开启保证每个旧文章页都能精确跳转到对应新文章页如果新站点路径已重构则应关闭统一跳转到首页再由新站点做引导。证书与强制 HTTPS如果旧域名仍可能有 HTTPS 请求建议为入站域名绑定证书可通过 Lets Encrypt 申请并开启ssl_forced避免出现跳转目标强制 HTTPS、但跳转来源却是明文 HTTP的中间降级。域名占用冲突同一入站域名不能被重定向主机与代理主机、流等重复占用创建时后端会做全局校验并返回xxx is already in use错误这点从 backend/internal/redirection-host.js 的 create 流程可以确认。版本兼容forward_scheme的auto默认值是较新版本的行为对应迁移 backend/migrations/20251111090000_redirect_auto_scheme.js旧版本创建的记录值为$scheme在升级后会自动迁移为auto无需手工修改。小结重定向主机是 nginx-proxy-manager 中结构最简单、但迁移场景价值极高的一类主机一条return 3xx规则即可完成整站域名的无缝切换。通过本文你可以看到从 帮助文档 的概念定义到前端表单、REST API、数据模型再到最终渲染出的 Nginx server 块整条链路在仓库中环环相扣、有据可查——无论是通过界面点几下完成迁移还是用 API 脚本批量处理大批旧域名都能做到精确可控。【免费下载链接】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），仅供参考