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 提供的四类核心主机类型之一用于将来自接入域名的请求整体跳转到另一个目标域名。最常见的落地场景是网站更换域名后搜索引擎索引、外链或书签仍指向旧域名此时通过重定向主机把旧域名的流量无缝引导到新域名避免流量与 SEO 权重流失。读完本文你将掌握重定向主机的概念、Web 界面与 REST API 两种配置路径、全部字段的语义与取值范围、底层 Nginx 配置生成原理以及迁移/停用等运维要点。什么是重定向主机依据项目内置帮助文档 RedirectionHosts.md英文版重定向主机的核心定义是A Redirection Host will redirect requests from the incoming domain and push the viewer to another domain.即重定向主机接收来自接入域名的请求并将其“推送”到另一个域名。中文版帮助文档RedirectionHosts.md将其概括为“将接入域名的请求推送到另一个域名”。使用这种主机类型最常见的业务背景是网站更换了正式域名旧域名需要继续工作一段时间搜索引擎爬虫和外部站点仍缓存、引用着指向旧域名的链接需要在不丢失既有流量、不破坏既有 SEO 收录的情况下完成域名过渡。与代理主机Proxy Host不同重定向主机不转发流量到后端服务而是直接在 HTTP 层返回一个Location头让浏览器或客户端自行跳转到新地址。它的本质是一段非常轻量的return code scheme://domain指令。提示项目内置的同一份帮助文档还有多个语言版本例如 乌克兰语版、中文版内容一致可作为交叉参考。创建重定向主机Web 界面操作在 Nginx Proxy Manager 管理界面中进入Hosts → Redirection Hosts页面点击Add Redirection Host即可打开创建弹窗。前端弹窗实现位于 RedirectionHostModal.tsx表单分为Details详情、SSL、Advanced高级三个页签。Details 页签字段字段说明取值 / 默认值Domain Names接入域名即“从哪里跳转”。支持通配符与 DNS 通配符校验必填可多个Forward Scheme目标跳转协议auto默认、http、httpsForward Domain Name目标域名即“跳到哪去”占位符example.com长度校验 1~255 字符必填Forward HTTP Code跳转 HTTP 状态码300、301、302默认、303、307、308Preserve Path是否保留原路径布尔开关默认关闭Block Exploits是否启用常见漏洞拦截引用 _exploits.conf布尔开关默认关闭从源码看RedirectionHostModal.tsx 中各项默认值为forwardScheme: auto、forwardHttpCode: 301、preservePath: false、blockExploits: falseforwardDomainName通过validateString(1, 255)做必填与长度校验。其中forwardHttpCode下拉框在界面中提供的选项依次为 300、301、302、303、307、308见 RedirectionHostModal.tsx覆盖了 3xx 重定向族中除 304未修改不适合重定向场景之外的常用状态码。SSL 页签SSL Certificate选择该主机使用的证书也支持直接新建证书allowNewSSL 选项包括sslForced强制 HTTPS、http2SupportHTTP/2、hstsEnabled启用 HSTS、hstsSubdomainsHSTS 是否覆盖子域名由 SSLOptionsFields.tsx 渲染。Advanced 页签提供advancedConfig自定义 Nginx 配置片段由 NginxConfigField.tsx 渲染最终会原样注入到生成的 server 块中用于实现标准表单无法覆盖的特殊指令。关键字段的源码级解读forward_scheme从 $scheme 到 autoforward_scheme决定跳转 URL 使用哪种协议。它经历了一次演进迁移 20210210154702_redirection_scheme.js 首次引入该字段默认值曾为$scheme即跟随原始请求的协议迁移 20251111090000_redirect_auto_scheme.js 将其默认值改为auto并把存量$scheme值统一更新为auto。在 API 层forward_scheme只接受auto、http、https三个枚举值见 redirection-host-object.json。界面中选择http/https时即强制固定协议选择auto时在最新版本中由 Nginx 模板层面决定通常等价于沿用原始请求协议保证 HTTPS 站点不会跳到 HTTP。forward_http_code选择正确的状态码forward_http_code用于控制跳转的语义。数据库迁移 20210210154703_redirection_status_code.js 将其定义为integer类型、无符号、默认 302API 模式redirection-host-object.json规定其取值范围为 300~308示例值 302。实际选择建议301永久重定向域名永久更换、旧域名不再恢复时使用搜索引擎会更新索引302临时重定向界面默认迁移过渡期、旧域名可能恢复时使用搜索引擎保留旧索引303See Other适合 POST 后跳转到 GET 结果的场景307 / 308保留请求方法与请求体语义的重定向307为临时、308为永久适合表单提交、API 调用等对方法敏感的场景300Multiple Choices一般较少使用。preserve_path保留还是舍弃路径preserve_path决定是否把原始请求的路径$request_uri附加到目标域名之后。典型场景保留路径https://old.example.com/blog/post-1→https://new.example.com/blog/post-1适合新旧域名路径结构完全一致的情况不保留路径https://old.example.com/anything→https://new.example.com/适合只希望把首页或根域流量导过去、目标站路径结构不同的情况。域名唯一性校验创建或更新时后端会对domain_names中每一个域名调用internalHost.isHostnameTaken(...)检查是否已被其他主机占用占用则抛出ValidationErrorxxx is already in use见 internal/redirection-host.js。因此同一域名不能同时被代理主机、重定向主机等多类主机重复声明。Nginx 配置生成原理模板机制重定向主机的 Nginx 配置由 backend/templates/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 / { {% 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 %}关键点解读return指令跳转的本质是 Nginx 的return code url浏览器收到响应后根据Location头完成跳转路径保留preserve_path为真时在目标域名后拼接$request_uri含查询串的完整原始 URI否则仅返回裸域名自定义片段advanced_config注入位置在日志指令之后、默认location /之前适合补充自定义 location 或 rewrite 规则此外还支持通过include /data/nginx/custom/server_redirect[.]conf;加载用户自定义的 server 级配置方括号写法用于避免 Nginx 对缺失文件报错开关联动enabled为假时整段配置不输出即主机被禁用后配置文件内容为空同时后端会删除配置文件并 reload见下文。配置生命周期create / update / enable / disable / delete后端业务逻辑集中在 backend/internal/redirection-host.js创建create校验权限redirection_hosts:create→ 域名唯一性检查 → 写入redirection_host表 → 若certificate_id new则先快速签发证书再回填 → 调用internalNginx.configure(...)生成配置 → 写入审计日志action: createdobject_type: redirection-host更新update校验权限 → 域名占用检查排除自身 id→ 写入meta用于审计 →internalNginx.configure(...)重新生成配置启用enable将enabled置 1 并重新生成配置此前禁用时配置已被删除重新生成即恢复禁用disable将enabled置 0调用internalNginx.deleteConfig(redirection_host, row)删除配置文件并reload删除delete逻辑删除is_deleted: 1随后删除 Nginx 配置并 reload同时记录审计日志。每次配置变更后都会触发 Nginx reload使新配置即时生效配置生成成功与否会写入行记录的meta.nginx_online/meta.nginx_err字段见 redirection-host-object.json 的示例前端可据此展示健康状态。通过 REST API 管理重定向主机重定向主机的 REST 路由定义在 backend/routes/nginx/redirection_hosts.js基础路径为/api/nginx/redirection-hosts所有请求都需要 JWT 认证jwtdecode()中间件。可用接口如下方法路径作用成功状态码GET/api/nginx/redirection-hosts列出全部重定向主机支持expand、query参数200POST/api/nginx/redirection-hosts创建新重定向主机201GET/api/nginx/redirection-hosts/{host_id}获取单个主机支持expand200PUT/api/nginx/redirection-hosts/{host_id}更新主机200DELETE/api/nginx/redirection-hosts/{host_id}删除主机200POST/api/nginx/redirection-hosts/{host_id}/enable启用200POST/api/nginx/redirection-hosts/{host_id}/disable禁用200POST 与 PUT 的请求体由 OpenAPI 模式校验getValidationSchema(/nginx/redirection-hosts, post)等字段与上表一一对应expand支持certificate、owner等关联展开后端默认允许的展开关系见 backend/models/redirection_host.js 中的defaultExpand即证书与创建者。前端对应的 API 封装与数据 Hooks 位于 api/backend/createRedirectionHost.ts、api/backend/updateRedirectionHost.ts、api/backend/toggleRedirectionHost.ts 以及 hooks/useRedirectionHosts.ts 等文件UI 操作最终都通过这些接口与后端交互。一个创建请求的最小示例协议固定为 https、保留路径、301 永久跳转{ domain_names: [old.example.com], forward_scheme: https, forward_domain_name: new.example.com, forward_http_code: 301, preserve_path: true, block_exploits: true, certificate_id: 0, ssl_forced: true, http2_support: false, hsts_enabled: false, hsts_subdomains: false, advanced_config: , meta: {} }对应生成的 Nginx 关键指令为return 301 https://new.example.com$request_uri;数据模型与权限数据模型重定向主机对应数据库表redirection_hostORM 模型定义在 backend/models/redirection_host.js表名redirection_host类名RedirectionHost布尔字段is_deleted、enabled、preserve_path、ssl_forced、block_exploits、hsts_enabled、hsts_subdomains、http2_support入库时转 0/1出库时转布尔JSON 字段domain_names域名列表插入/更新时自动排序、meta存放 nginx 状态等元信息关联关系owner创建者关联user表、certificate关联certificate表且关联时均过滤已删除记录列表排序默认按domain_names排序。权限模型创建重定向主机需要redirection_hosts:create权限其权限定义在 backend/lib/access/redirection_hosts-create.json管理员roles#/definitions/admin拥有全部权限普通用户需要permission_redirection_hosts达到manage级别且角色为user。更新、删除、启停同理对应redirection_hosts:update、redirection_hosts:delete等权限。此外当用户的permission_visibility不是all时列表与详情查询只会返回owner_user_id等于当前用户的记录见 internal/redirection-host.js实现多用户环境下的数据隔离。典型实战场景与注意事项场景一网站域名永久迁移301 保留路径新老域名路径一一对应时推荐配置Forward Schemehttps或autoForward HTTP Code301Preserve Path开启效果http://old.example.com/product/123请求到达后返回301 Location: https://new.example.com/product/123搜索引擎据此把旧页面权重转移到新页面。场景二域名过渡期302如果旧域名短期内可能恢复、或还在并行运营请使用302临时跳转避免搜索引擎过早把旧域名索引注销。场景三仅导流首页新站点路径结构与旧站完全不同时关闭 Preserve Path所有旧域名请求一律跳到新站根路径或配合advanced_config写自定义 rewrite 规则。注意事项证书与 SSL如果接入域名本身需要提供 HTTPS 跳转服务请在 SSL 页签为该主机关联证书并启用sslForced否则浏览器在跳转前就可能出现证书告警域名冲突目标域名forward_domain_name不需要在 NPM 中登记但接入域名domain_names不能与其他主机代理、重定向、404 主机等重复通配符域名界面允许输入通配符域名*.example.com配合通配符证书可一次覆盖全部子域名的跳转审计追踪创建、更新、启用、禁用、删除均写入审计日志可在 Audit Log 页面回溯操作历史相关实现见 backend/internal/audit-log.js。总结重定向主机是 nginx-proxy-manager 中实现“域名换新、流量不丢”的标准方案前端表单提供友好的字段配置后端通过redirection_host.conf模板把它翻译成一行return指令并在创建、更新、启停、删除的完整生命周期中自动生成/删除配置、reload Nginx、记录审计日志。理解forward_scheme、forward_http_code、preserve_path三个核心字段的语义再结合 REST 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），仅供参考