企业官网建设流程全解析

Nginx Proxy Manager 404 主机（Dead Host）完全指南：用途、配置与 Nginx 实现原理

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

404 主机（Dead Host / 404 Host）是 Nginx Proxy Manager 中一类特殊的主机：它不代理任何上游服务，只为指定域名返回标准的 404 页面。本文以仓库内 DeadHosts 帮助文档 为核心，结合后端路由、数据模型与 Nginx 配置模板源码，系统讲解 404 主机的设计意图、前端配置方式、REST API 调用与底层配置生成原理，帮助读者理解并正确使用这一功能来优雅处理失效域名与 SEO 场景。

什么是 404 主机

404ホストとは、単に404ページを表示するよう設定されたホストです。（404 主机就是被设置为仅显示 404 页面的主机。）

404 主机（代码中称为dead-host，OpenAPI 规范中标记为404 Host）是一种特殊的 Nginx 虚拟主机：它不转发请求到任何后端服务器，而是对所有命中该域名的请求直接返回 HTTP 404 状态码。从 Nginx Proxy Manager 的数据模型看，它与其他类型主机（代理主机、重定向主机、流）平级，但业务逻辑最简单——没有forward_host、forward_port等转发配置，只有域名与 SSL 相关的选项。

在管理界面左侧菜单的404 Hosts页面（路由对应前端 DeadHosts 列表页），你可以创建、编辑、启用/禁用和删除这类主机。创建后，Nginx 会为该域名生成一个仅返回 404 的 server 配置块。

为什么需要 404 主机

原文档给出了两个核心应用场景：

1. 为已失效的域名提供友好错误页

検索エンジンに登録されたドメインに分かりやすいエラーページを提供したい場合…（当域名已被搜索引擎收录，希望提供一个清晰易懂的错误页面时…）

当你的域名曾发布过内容并被搜索引擎收录，但页面已经不存在时，直接解析到不存在的服务器会返回晦涩的连接错误。通过 404 主机，可以让这些域名稳定地返回标准 HTTP 404 响应。

2. 明确告知搜索引擎索引器页面已不存在

検索エンジンのインデクサーにドメインページがもう存在しないことを伝えたい場合…（希望告诉搜索引擎索引器，该域名的页面已经不再存在时…）

对于爬虫而言，正确的 HTTP 状态码就是最明确的信号。返回 404 即告知索引器"此页面/域名已下线"，搜索引擎会据此从索引中逐步剔除该地址，避免继续抓取、也避免返回错误内容影响站点信誉。相比返回 200 的空页面（软 404），标准 404 状态码是 SEO 上更规范的做法。

3. 附加收益：访问日志追踪与来源分析

このホストを持つもう一つの利点は、アクセスログを追跡し、参照元を確認できることです。（拥有这种主机的另一个好处是：可以追踪访问日志，并确认访问来源 / 引用来源。）

即使页面已下线，仍可能有人在访问旧链接或外站仍在引用。404 主机让这类流量可观测——所有请求都会写入独立的访问日志，通过查看日志可以知道：还有谁在访问这个域名、从哪个来源（referrer）跳转过来。这在迁移站点、清理旧域名时非常实用。

如何创建和配置 404 主机

通过管理界面

在前端，创建入口是 DeadHostModal 弹窗，表单分为三个标签页：

• Details（详情）：核心字段为domainNames（域名列表），通过 DomainNamesField 录入，支持通配符域名；创建时也可直接选择"新证书"（certificateId传"new"），后端会自动签发。
• SSL：选择 SSL 证书（SSLCertificateField）以及 SSLOptionsFields 提供的选项——强制 SSL（ssl_forced）、HTTP/2 支持（http2_support）、HSTS 启用（hsts_enabled）与 HSTS 子域名（hsts_subdomains）。
• Advanced（高级）：可填入自定义 Nginx 配置片段（advanced_config），会被直接插入到生成的 server 块中。

通过 REST API

404 主机的全部操作都通过后端路由 dead_hosts.js 暴露，路径前缀为/api/nginx/dead-hosts。创建请求的完整载荷定义见 POST /nginx/dead-hosts 的 OpenAPI 定义，典型示例如下：

POST /api/nginx/dead-hosts { "domain_names": ["test.example.com"], "certificate_id": 0, "ssl_forced": false, "advanced_config": "", "http2_support": false, "hsts_enabled": false, "hsts_subdomains": false, "meta": {} }

其中domain_names为必填项，其余字段均可选。创建成功后返回 201，响应体结构见 dead-host-object.json，包含id、owner_user_id、enabled、certificate、owner等完整信息。接口权限由 dead_hosts-create.json 等权限定义控制（要求dead_hosts.manage权限）。

底层实现：一个 404 主机的 Nginx 配置是怎么生成的

数据模型

数据库表dead_host对应模型 dead_host.js，核心字段包括：

模型通过relationMappings关联了owner（创建用户）与certificate（证书），并定义了boolFields在数据库整数与 JS 布尔值之间自动转换。

配置模板

核心在于模板文件 dead_host.conf。创建/更新主机时，后端 dead-host.js 会调用internalNginx.configure(deadHostModel, "dead_host", row)（见create流程）用该模板渲染出实际的 Nginx server 块。模板逻辑如下：

{% 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 %}

从模板可以提炼出 404 主机的几个实现要点：

• 核心动作是return 404;：在默认 location 中直接返回 404 状态码，不连接任何上游。
• 完整的 SSL 支持：_listen.conf负责 80/443 监听端口，_certificates.conf注入证书路径，_forced_ssl.conf处理 HTTP→HTTPS 跳转，与代理主机的 SSL 能力完全一致。
• 独立的日志文件：每个 404 主机拥有独立的access_log（/data/logs/dead-host-{id}_access.log）与error_log，这正是原文档所说"追踪访问日志、查看引用来源"的落点——日志中记录的referer字段可用于来源分析。
• 扩展点：advanced_config会原样插入 server 块；此外还可以通过自定义文件/data/nginx/custom/server_dead[.]conf追加配置（方括号写法保证仅匹配该精确文件名）。
• 禁用即不生成：模板外层{% if enabled %}保证禁用的主机不会残留任何 Nginx 配置。

生命周期：启用 / 禁用 / 删除

在 dead-host.js 中，每个操作都遵循"校验权限 → 操作数据库 → 重配/重载 Nginx → 写审计日志"的流程：

• 启用（enable）：enabled置 1 后调用internalNginx.configure重新生成配置（L255-L285附近）；若主机已启用会抛出ValidationError("Host is already enabled")。
• 禁用（disable）：enabled置 0 后调用internalNginx.deleteConfig("dead_host", row)删除配置并reload()（L294-L322附近）。
• 删除（delete）：并非物理删除，而是将is_deleted置 1 实现软删除，同时删除 Nginx 配置并重载（L223-L246附近）。
• 域名冲突检查：创建与更新时都会调用internalHost.isHostnameTaken逐域名校验，防止与代理主机等其他类型的主机抢占同一域名（L30-L45）。

所有变更同时会写入审计日志（action 分别为created/updated/deleted/enabled/disabled，object_type 为dead-host），可在管理界面的审计日志中回溯每次操作。

常见使用建议

• 域名下线迁移：站点迁移或关闭后，把旧域名建成 404 主机，让 SEO 平滑过渡；配合访问日志观察残留流量与来源，决定何时彻底停止解析。
• 配合通配符域名：domain_names支持通配符（前端字段isWildcardPermitted允许），可一个主机覆盖*.example.com的所有未定义子域。
• 需要 HTTPS 时记得配置证书：若ssl_forced为 true，务必绑定有效证书（可选用"新建证书"自动签发），否则浏览器会报证书错误。
• 高级配置按需使用：默认行为对所有路径返回 404；如需对特定路径做特殊处理（如返回其他状态码、临时重定向到新站），可在高级配置中补充location规则。

总结

404 主机（Dead Host）是 Nginx Proxy Manager 中"轻量而实用"的一类主机：以最小的配置成本，为失效域名提供标准的 HTTP 404 响应，兼顾搜索引擎索引清理与访问日志追踪。从数据模型、REST API 到 dead_host.conf 模板，它的实现链路清晰完整——理解它，也就理解了 Nginx Proxy Manager 中所有主机类型共通的"数据库记录 + 模板渲染 + 配置重载"工作模式。

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