nginx-proxy-manager 404 HostDead Host完全指南用途、配置与底层实现原理【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-managernginx-proxy-manager 提供了一种被称为404 Host错误页面主机的特殊主机类型它不转发任何流量而是让指定域名统一返回 HTTP 404 错误页。本指南基于仓库内的用户文档frontend/src/locale/src/HelpDoc/uk/DeadHosts.md以及 英文版展开并结合后端源码与 Nginx 模板完整讲解 404 Host 的概念、适用场景、配置字段、生命周期管理与底层实现帮助你正确利用它治理失效域名、优化搜索引擎收录并借助日志追踪访客来源。什么是 404 Host404 Host代码中又称 Dead Host是一个只展示 404 错误页面、不做任何反向代理的主机配置。当用户访问被该主机覆盖的域名时Nginx 直接返回404 Not Found状态码与默认错误页而不是转发到某个后端服务。从用户文档中文版的表述看它的定位非常朴素错误页面是一个简单的主机设置显示错误页面。换句话说它和 Proxy Host反向代理、Redirection Host重定向的最大区别在于它没有 upstream、没有转发目标只有返回 404这一种行为。你可以把任意数量的域名挂在同一个 404 Host 下让它们全部返回 404。典型使用场景根据文档描述404 Host 主要解决两类问题为已失效的域名提供更友好的 404 页面当你的域名被搜索引擎收录后如果站点下线、页面整体迁移或服务停止用户直接访问会看到一个简陋甚至报错的页面。404 Host 能让这些域名返回标准、干净的 404 页面体验更规范。明确告知搜索引擎索引器页面已不存在搜索引擎爬虫search indexers依赖 HTTP 状态码判断页面状态。通过 404 Host 让失效域名返回404 Not Found等于向爬虫发出明确信号该域名下的页面已不存在应将其从索引中移除避免收录失效内容。跟踪访问日志与访客来源referrer文档特别强调拥有这种主机的另一个好处是可以跟踪点击它的日志并查看访问来源。由于 404 Host 会生成独立的访问日志文件见下文 Nginx 模板中的dead-host-{{ id }}_access.log你可以从日志中观察有哪些人/哪些来源仍在访问已失效的域名——这常被用来评估旧链接还剩多少外部引用。核心配置字段404 Host 的数据由数据库表dead_host承载其建表语句见 backend/migrations/20180618015850_initial.jsAPI 对象结构定义见 backend/schema/components/dead-host-object.json。核心字段如下字段类型说明idinteger主键自增domain_namesjson该 404 Host 覆盖的域名列表可多个certificate_idinteger关联的 SSL 证书 ID默认为 0即无证书ssl_forcedinteger是否强制 HTTPS默认 0hsts_enabledinteger是否启用 HSTS 头由后续迁移补充hsts_subdomainsintegerHSTS 是否覆盖子域名http2_supportinteger是否启用 HTTP/2advanced_configtext自定义 Nginx 配置片段默认空字符串enabledinteger是否启用该主机metajson附加元数据owner_user_idinteger创建者所有者用户 IDis_deletedinteger软删除标记默认 0在对象模型 backend/models/dead_host.js 中布尔型字段is_deleted、ssl_forced、http2_support、enabled、hsts_enabled、hsts_subdomains会在数据库存取时自动与 0/1 整数互相转换domain_names与meta为 JSON 字段插入前会自动排序domain_names。模型还声明了与userowner和certificate的关系映射因此 API 返回时可以通过expandcertificate,owner联查证书与所有者信息。创建 404 Host界面操作Nginx → 404 Hosts在 Web 界面左侧菜单的Nginx → 404 Hosts页面点击添加 404 Host即可创建需要填写域名Domain Names支持一次填写多个域名格式如example.com与www.example.comSSL 选项可关联已有证书或选择新建证书后端会自动签发同时可勾选 Force SSL、HTTP/2 Support、HSTS 等选项自定义 Nginx 配置Advanced可注入额外的 Nginx 配置片段启用状态创建后默认为启用。底层校验逻辑创建操作在 backend/internal/dead-host.js 中执行关键步骤包括权限校验调用access.can(dead_hosts:create, data)非管理员需要拥有permission_dead_hosts的 manage 权限见 backend/lib/access/dead_hosts-create.json域名占用检查对每个域名调用internalHost.isHostnameTaken()若已被其他主机占用则抛出ValidationError例如example.com is already in use数据清洗通过internalHost.cleanSslHstsData()规整 SSL/HSTS 字段未提供advanced_config时补空字符串插入数据库并写审计日志记录action: created、object_type: dead-host到审计日志可选自动签发证书若选择新建证书certificate_id new调用internalCertificate.createQuickCertificate()创建 Lets Encrypt 证书并回填生成 Nginx 配置调用internalNginx.configure(deadHostModel, dead_host, freshRow)渲染配置并 reload。生成的 Nginx 配置模板404 Host 的 Nginx 配置由模板 backend/templates/dead_host.conf 渲染生成。其核心逻辑为当enabled为真时生成一个server块通过_listen.conf、_certificates.conf、_hsts.conf、_forced_ssl.conf等子模板注入监听端口、证书、HSTS 与强制 HTTPS 相关配置独立的访问日志access_log /data/logs/dead-host-{{ id }}_access.log standard;与error_log /data/logs/dead-host-{{ id }}_error.log warn;—— 这正是文档所说的跟踪点击日志、查看访问来源的实现基础当use_default_location为真时生成location / { return 404; }作为默认返回 404 的位置支持通过advanced_config注入自定义配置并include /data/nginx/custom/server_dead[.]conf;加载自定义片段。简单来说这个模板除了返回 404 什么也不做但由于 SSL、HSTS、强制 HTTPS 等选项依旧生效它在安全语义上与其他主机类型保持一致的体验。生命周期管理启用 / 禁用 / 更新 / 删除404 Host 的完整生命周期都在 backend/internal/dead-host.js 中实现并通过路由 backend/routes/nginx/dead_hosts.js 暴露为 REST API操作API 端点说明列表GET /api/nginx/dead-hosts支持expand与query搜索参数详情GET /api/nginx/dead-hosts/:id支持expandcertificate,owner创建POST /api/nginx/dead-hosts返回 201更新PUT /api/nginx/dead-hosts/:id更新前同样会做域名占用检查排除自身见 dead-host.js删除DELETE /api/nginx/dead-hosts/:id软删除is_deleted 1删除 Nginx 配置并 reload启用POST /api/nginx/dead-hosts/:id/enable恢复配置并 reload禁用POST /api/nginx/dead-hosts/:id/disable移除配置并 reload几个值得注意的实现细节软删除删除操作不会物理删除记录而是将is_deleted置为 1见 dead-host.js所有查询默认过滤is_deleted 0禁用时不写配置更新时若主机处于禁用状态直接返回而不生成 Nginx 配置dead-host.js避免浪费资源审计日志贯穿全流程创建、更新、删除、启用、禁用都会写入internalAuditLog.add()操作历史可在审计日志页面查看便于追踪 404 Host 的变更来源状态幂等保护对已启用主机再次enable、或对已禁用主机再次disable会抛出ValidationErrorHost is already enabled/disabled。权限与可见性404 Host 遵循 nginx-proxy-manager 统一的对象权限模型管理员admin 角色可以查看和管理所有 404 Host普通用户需要permission_dead_hosts权限且只能看到/管理owner_user_id是自己的主机见 dead-host.js 与getAll中的可见性过滤 backend/internal/dead-host.js。也就是说如果你在一个多用户实例中为不同团队划分域名每个团队只能操作自己名下的 404 Host互不干扰。与 Dashboard 报表的联动404 Host 的数量也会计入仪表盘报表。在 backend/internal/dead-host.js 中实现的getCount(user_id, visibility)会被报表逻辑调用用于统计当前实例或对当前用户可见范围内的 404 Host 数量并同样遵循可见性过滤。这意味着你在 Dashboard 上看到的404 Hosts计数与你的权限范围严格一致。小结404 HostDead Host是 nginx-proxy-manager 中专门用于让域名统一返回 404 错误页的主机类型适合失效域名友好降级、告知搜索引擎移除索引、以及借助独立访问日志追踪访客来源它不支持反向代理核心行为由 backend/templates/dead_host.conf 中的return 404决定同时完整支持 SSL、强制 HTTPS、HSTS、HTTP/2 与自定义 Nginx 配置创建、更新、启用、禁用、删除均通过 backend/routes/nginx/dead_hosts.js 提供的 REST API 完成全部操作写入审计日志删除采用软删除禁用状态下不生成 Nginx 配置数据层由dead_host表承载backend/migrations/20180618015850_initial.js权限模型与 Dashboard 统计均已接入统一的对象可见性体系。如果你正在处理一批已失效的旧域名或者希望优雅地下线不再维护的站点404 Host 是最简单直接的答案——在界面上添加域名、绑定证书、启用即可剩下的状态码语义与日志追踪都由 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考