Nginx Proxy Manager 404 Hosts 详解：用 404 主机优雅下线域名、通知搜索引擎并追踪流量-创锋一号

Nginx Proxy Manager 404 Hosts 详解：用 404 主机优雅下线域名、通知搜索引擎并追踪流量

【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager

404 Hosts（即 Dead Hosts / 404 主机）是 Nginx Proxy Manager 中一种专门用于向访问者返回 404 错误页的虚拟主机类型。当域名已被搜索引擎收录、但站点内容不再提供服务时，你可以用它提供更友好的错误响应、明确告知索引系统页面已不存在，并借助其独立访问日志追踪请求来源（Referrer）。本文以官方帮助文档为核心，结合仓库源码（后端实现、Nginx 模板、数据模型、REST API 与前端页面），完整讲解 404 Host 的定义、适用场景、创建流程、配置字段、底层 Nginx 生成逻辑与日志追踪方法。

什么是 404 Host？

按官方帮助文档（英文版、保加利亚语版）的定义：404 Host 本质上就是一种“只会展示 404 错误页”的主机配置。它不代理任何上游服务，也不做重定向，唯一的职责就是让访问该域名的所有请求得到 HTTP 404 响应。

该功能在源码中被称为dead-host（后端内部目录、API 路径、数据表与 Nginx 配置命名均使用该词），前端页面与 OpenAPI 规范中则统一以404 Hosts对外展示，例如：

后端实现：backend/internal/dead-host.js（增删改查、启用/禁用与 Nginx 配置编排）；
数据模型：backend/models/dead_host.js（dead_host表）；
REST 路由：backend/routes/nginx/dead_hosts.js（/api/nginx/dead-hosts）；
前端页面：frontend/src/pages/Nginx/DeadHosts/index.tsx（Hosts → 404 Hosts 菜单）。

官方文档给出的两大适用场景

依据帮助文档，404 Host 主要解决两类问题：

为被搜索引擎收录的域名提供更友好的错误页：当域名出现在搜索引擎索引中、但站点内容已下线时，直接返回“裸 404”会让访客体验不佳。通过 404 Host，你可以统一返回规范的 404 页面，保持站点下线状态的“整洁感”。
向搜索引擎索引器发出明确信号：404 Host 返回的是标准 HTTP 404 状态码，这能明确告知 Google、Bing 等爬虫“该域名下的页面已不再存在”，帮助其逐步从索引中移除失效页面，避免长期返回 200 而让搜索引擎保留陈旧快照。
附带优势——日志与 Referrer 追踪：文档特别强调，404 Host 的另一个价值在于记录所有命中的访问日志，并查看 Referrer（来源页）。这意味着你可以观察到哪些网站仍在向该已下线域名发外链、流量从何处涌来，为迁移、舆情与安全分析提供依据。这一点在后端实现中有直接支撑：404 Host 的 Nginx 配置会写入独立的access_log/error_log文件（详见下文“底层原理”一节）。

404 Host 与 Proxy Host / Redirection Host 的区别

从 Nginx Proxy Manager 的架构看，四类主机分别承担不同职责（后端内部模块位于 backend/internal/）：

主机类型	后端模块	核心行为
Proxy Host	proxy-host.js	反向代理，将请求转发到上游服务器
Redirection Host	redirection-host.js	返回 301/302 重定向到目标 URL
404 Host	dead-host.js	对域名下所有请求直接返回 HTTP 404
Stream	stream.js	TCP/UDP 四层流量转发（非 HTTP）

与 Proxy Host（需要配置 Forward Hostname / IP、Forward Port、Forward Scheme 等转发参数）和 Redirection Host（需要配置 Redirect URL）不同，404 Host不需要任何转发目标——它只有“域名 + SSL/HTTP 选项 + 可选高级配置”，本质上是一个“黑洞式”的终止节点。

如何创建 404 Host（操作指南）

通过前端界面创建：进入Hosts → 404 Hosts页面，点击右上角Add 404 Host按钮，在弹窗中填写配置后保存。仓库自带的前端页面入口见 frontend/src/pages/Nginx/DeadHosts/index.tsx，弹窗表单组件为 frontend/src/modals/DeadHostModal.tsx。下图是仓库文档中 404 Hosts 列表页的官方截图（浅色主题）：

列表中每个 404 Host 显示Source（域名与创建时间）、SSL（如 HTTP Only）与Status（Online）三列信息，右上角提供 “Add 404 Host” 按钮与搜索框。

字段说明：从 OpenAPI 规范看必填与可选配置

创建 404 Host 的请求体由 OpenAPI 规范定义（backend/schema/paths/nginx/dead-hosts/post.json），字段如下：

字段	必填	说明
`domain_names`	是	该 404 Host 绑定的域名数组，如`["test.example.com"]`
`certificate_id`	否	关联的 SSL 证书 ID；传`0`表示不启用 HTTPS（HTTP Only）
`ssl_forced`	否	是否强制跳转 HTTPS
`hsts_enabled`	否	是否启用 HSTS（HTTP 严格传输安全）响应头
`hsts_subdomains`	否	HSTS 是否作用于子域名
`http2_support`	否	是否启用 HTTP/2
`advanced_config`	否	注入到 server 块中的自定义 Nginx 配置（默认空字符串）
`meta`	否	附加元数据对象（默认`{}`）

官方示例请求体（post.json）：

{ "domain_names": ["test.example.com"], "certificate_id": 0, "ssl_forced": false, "advanced_config": "", "http2_support": false, "hsts_enabled": false, "hsts_subdomains": false, "meta": {} }

成功创建后返回 201，响应体为 dead-host-object.json 定义的完整对象，其中enabled默认true（创建即生效），并附带certificate与owner关联信息。

底层原理：404 Host 如何生成 Nginx 配置

核心 Nginx 模板

每个 404 Host 由 Nginx 配置文件模板 backend/templates/dead_host.conf 渲染生成。其关键逻辑是：在location /中直接return 404;，让所有命中该 server 的请求都收到 404 响应：

{% include "_header_comment.conf" %} {% if enabled %} {% include "_hsts_map.conf" %} server { {% include "_listen.conf" %} {% include "_certificates.conf" %} {% include "_hsts.conf" %} {% include "_forced_ssl.conf" %} access_log /data/logs/dead-host-{{ id }}_access.log standard; error_log /data/logs/dead-host-{{ id }}_error.log warn; {{ advanced_config }} {% if use_default_location %} location / { {% include "_hsts.conf" %} return 404; } {% endif %} # Custom include /data/nginx/custom/server_dead[.]conf; } {% endif %}

模板要点解读：

return 404;是 404 Host 的行为核心，位于默认location /中，对根路径及未匹配其他 location 的请求生效；
独立日志文件：每个 404 Host 生成独立的访问日志/data/logs/dead-host-{{ id }}_access.log与错误日志/data/logs/dead-host-{{ id }}_error.log——这正是官方文档所说“查看命中的日志与 Referrer”的实现基础。Nginx 的 standard 格式默认记录$http_referer，配合访问日志即可分析流量来源；
{{ advanced_config }}注入点：用户在界面填写的自定义 Nginx 配置（Advanced 选项卡）会原样渲染进 server 块，可自定义错误页、追加 location、控制缓存等；
自定义文件扩展点：include /data/nginx/custom/server_dead[.]conf;允许运维在容器内放置额外的 server 级自定义配置，方括号写法确保只匹配该精确文件名而不误匹配前缀文件；
SSL 能力完整保留：模板引入了_listen.conf、_certificates.conf、_hsts.conf、_forced_ssl.conf等公共片段（见 backend/templates/），因此 404 Host 同样支持 HTTPS、HSTS 与强制 HTTPS 跳转，可用于“HTTPS 站点下线后仍以 443 返回 404”的场景；
{% if enabled %}门控：主机被禁用时整个 server 块不生成，配置被移除（见下文“启用/禁用”）。

后端生成与刷新流程

后端 backend/internal/dead-host.js 在每次创建、更新、启用后都会调用internalNginx.configure(deadHostModel, "dead_host", row)（backend/internal/nginx.js 负责模板渲染、落盘与nginx -t校验并 reload），保证配置与数据库状态实时同步：

创建：先校验域名唯一性（internalHost.isHostnameTaken），入库后写入审计日志（internalAuditLog.add，object_type: "dead-host"），再生成 Nginx 配置；
更新：同样先做域名占用检查（isHostnameTaken(domainName, "dead", data.id)，排除自身），更新行记录后重新生成配置；若主机处于禁用状态则跳过配置生成（见 backend/internal/dead-host.js）；
删除：软删除（is_deleted = 1），同时调用internalNginx.deleteConfig("dead_host", row)删除配置文件并 reload；
启用/禁用：enable将enabled置 1 并重新生成配置；disable置 0、删除配置文件并 reload。

所有操作均写入审计日志（action 为created/updated/deleted/enabled/disabled），可在前端 Audit Log 页面回溯，例如查看某个 404 Host 何时被创建或停用。

数据模型与权限控制

数据库表dead_host由 backend/models/dead_host.js 定义，domain_names与meta为 JSON 字段，布尔字段（is_deleted、ssl_forced、http2_support、enabled、hsts_enabled、hsts_subdomains）在数据库中以 0/1 存储、API 层自动转换为布尔值；模型关联了owner（属主用户）与certificate（SSL 证书，均排除已删除记录）。

权限层面，创建 404 Host 需要dead_hosts:manage权限或 admin 角色（见 backend/lib/access/dead_hosts-create.json），查看/编辑/删除分别对应dead_hosts:get/update/delete/list等操作；当用户的permission_visibility不为all时，只能看到自己（owner_user_id）创建的主机（backend/internal/dead-host.js）。前端页面入口 frontend/src/pages/Nginx/DeadHosts/index.tsx 同样通过HasPermission组件按DEAD_HOSTS权限控制可见性。

REST API 一览

404 Host 的完整 REST 接口由 backend/routes/nginx/dead_hosts.js 提供，前缀为/api/nginx/dead-hosts：

方法与路径	功能
`GET /api/nginx/dead-hosts`	列出全部 404 Host，支持`expand`与`query`（按域名模糊搜索）参数
`POST /api/nginx/dead-hosts`	创建 404 Host（返回 201）
`GET /api/nginx/dead-hosts/:host_id`	获取单个 404 Host
`PUT /api/nginx/dead-hosts/:host_id`	更新 404 Host
`DELETE /api/nginx/dead-hosts/:host_id`	删除 404 Host（软删除并移除 Nginx 配置）
`POST /api/nginx/dead-hosts/:host_id/enable`	启用（生成 Nginx 配置）
`POST /api/nginx/dead-hosts/:host_id/disable`	禁用（移除 Nginx 配置并 reload）

所有请求均需携带 Bearer Token（JWT），接口定义与dead_hosts.manage等权限要求见 backend/schema/paths/nginx/dead-hosts/ 目录下的 OpenAPI 文件。例如启用接口定义在 backend/schema/paths/nginx/dead-hosts/hostID/enable/post.json。

进阶用法：结合日志与高级配置

1. 流量与 Referrer 追踪

创建 404 Host 后，访问该域名的请求会写入/data/logs/dead-host-<id>_access.log。在 Docker 部署中，该目录对应容器数据卷data/logs，可进入容器查看：

docker exec -it nginx-proxy-manager sh tail -f /data/logs/dead-host-1_access.log

日志中的$http_referer字段即来源页面，可用于回答“谁还在链接这个已下线的域名”。此能力在 backend/templates/dead_host.conf 中有直接实现依据。

2. 自定义 404 错误页

若希望返回带品牌信息的 404 页面而非纯文本，可在 404 Host 的Advanced选项卡中注入自定义配置（写入advanced_config，渲染于 server 块内），例如：

error_page 404 /custom_404.html; location = /custom_404.html { root /data/nginx/custom; internal; }

将custom_404.html放入容器/data/nginx/custom/目录即可生效（仓库内置的自定义配置文件目录约定可参考 docker/rootfs/etc/nginx/conf.d/include/ 中的公共片段用法）。

3. 域名迁移与搜索引擎降权场景

整站下线：为所有历史域名创建 404 Host，搜索引擎将逐步清除索引；
配合 HTTPS：绑定证书并开启ssl_forced，让 443 端口也统一返回 404，避免访客看到证书/连接错误；
记录审计：所有创建、更新、删除、启用/禁用动作都会进入 Audit Log（backend/internal/audit-log.js 记录，object_type: "dead-host"），便于团队审计。

小结

404 Host 是 Nginx Proxy Manager 中实现“域名优雅下线”的标准手段：它不需要任何上游转发目标，仅通过生成包含return 404;的 Nginx server 配置，为搜索引擎收录过的域名提供规范的 404 响应、友好的错误提示，并通过独立的dead-host-<id>_access.log访问日志持续追踪请求与 Referrer。配合 SSL 证书、HSTS、强制 HTTPS 与 Advanced 自定义配置，你可以把“已死域名”也管理得井井有条——这正是该项目“简单而强大”设计哲学在边界场景中的一个缩影。

延伸阅读：本文引用的帮助文档原文见 frontend/src/locale/src/HelpDoc/en/DeadHosts.md（及多语言版本如 frontend/src/locale/src/HelpDoc/zh/DeadHosts.md），核心实现与接口定义可分别参阅 backend/internal/dead-host.js、backend/templates/dead_host.conf 与 backend/schema/paths/nginx/dead-hosts/。

【免费下载链接】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），仅供参考

企业官网建设流程全解析