DNSBox

为基于 IP 的主机名提供 DNS 和 HTTPS

通过 *.dnsbox.io 访问公网 HTTP 服务，或在自己的私有网络中运行 DNSBox。

v0.5.2 提供的功能

从 v0.4.x 升级？替换现有安装之前，请先按照迁移指南操作。 迁移指南

使用公共服务

无需注册账户或域名。后端必须使用允许访问的公网 IP，并在 80 端口上运行 DNSBox 可以访问的 HTTP 服务。

将 198.51.100.20 替换为服务器的公网 IPv4 地址：

https://198-51-100-20.dnsbox.io

DNS 将主机名解析到 DNSBox 代理。代理终止 HTTPS 连接，再通过 HTTP 将请求转发到主机名中编码的 IP 地址。它不会在你的服务器上安装证书。

Let's Encrypt 通过 DNS-01 验证主机名。证书签发给该主机名，而非裸 IP 地址。首次 TLS 连接可能需要等待证书签发，因此耗时较长。

浏览器与 DNSBox 之间使用 HTTPS。DNSBox 与后端之间使用 HTTP。支持升级为 WebSocket 连接。

IPv6 后端可编码为 2a01-4f8-c17-b8f--1.dnsbox.io。一个连字符代表一个冒号，两个连字符代表 ::。

先检查 DNS 解析，再检查 HTTPS。请使用你自己的、可访问的 HTTP 后端进行测试：

dig +short 198-51-100-20.dnsbox.io
curl -v https://198-51-100-20.dnsbox.io/

DNS 响应返回的是代理地址。TLS 连接有效与后端 HTTP 响应成功是两项独立的检查。

在私有网络中运行

本地 TLS 模式无需公网 DNS、端口转发或互联网连接。DNSBox 会创建自己的证书颁发机构（CA），客户端必须信任该 CA。

示例：DNSBox 位于 192.168.1.2，HTTP 后端位于 192.168.1.0/24 网段：

./dnsboxd --domain=home.arpa --ip=192.168.1.2 \
  --tls-mode=local --allowed-cidrs=192.168.1.0/24 \
  --dns-listen=192.168.1.2:53 --https-listen=192.168.1.2:443 \
  --data-dir=/var/lib/dnsbox

在局域网 DNS 解析器上，仅将 home.arpa 区域的查询转发到 192.168.1.2。DNSBox 是其区域的权威服务器，不是通用的递归解析器。

先签发一个本地证书以创建 CA，再将 /var/lib/dnsbox/ca/root.crt 安装到每个客户端的受信任 CA 存储中。请妥善保密 root.pem。部署指南中提供了初始化命令。

如果后端地址为 192.168.1.50，请打开 https://192-168-1-50.home.arpa。局域网客户端需要能够访问 DNSBox 的 DNS 和 HTTPS 端口；DNSBox 需要能够访问后端的 HTTP 端口。

私有网络设置

自行部署并使用 Let's Encrypt

使用你控制的域名或子域名，并将其 DNS 区域委派给 DNSBox 域名服务器。一个节点即可提供该区域的服务，多个节点则可提供冗余。

进行公网 DNS-01 验证时，需要允许入站 UDP 53 和 TCP 53、出站 HTTPS 以及 DNS 解析。无需开放入站 80 端口。443 端口只需对预期使用服务的客户端可达。

只要 DNS-01 验证可在公网完成，私有网络中的 HTTP 后端也能使用公开受信任的主机名证书。请通过 --allowed-cidrs 明确允许这些后端，并为客户端配置 DNS 和路由。

使用多个节点时，请在每个节点上配置相同的域名服务器列表和记录，并为验证数据复制配置双向 TLS。只有所有已配置的对等节点确认收到验证数据后，证书签发才会继续。

提供 Linux、macOS 和 Windows 的发行包。安装程序支持 --no-systemd，可手动启动或使用其他进程管理工具。安装程序不会禁用系统 DNS 解析器。

安装与集群配置

为 ocserv 和其他服务提供证书

公共服务不会导出其私钥。如果你的服务需要证书文件，请自行部署 DNSBox，并将你控制的 DNS 区域委派给它。

使用该区域下包含编码 IP 地址的主机名运行 --issue。DNSBox 会将 PEM 证书链和私钥写入 <data-dir>/certs，然后退出。通过 ACME 签发证书时会提供 DNS 服务，但不会占用 HTTPS 端口 443。

通过显式 A/AAAA 记录，将该主机名直接指向你的服务。对于 ocserv，请配置 server-cert 和 server-key。DNSBox 的 HTTP 代理不实现 OpenConnect 或 DTLS。

请安排证书续期，并在文件更改后让服务重新加载。一次性命令退出后不会继续续期证书。不要让两个 DNSBox 进程同时使用同一个数据目录。

证书导出示例

常见问题

可以通过公共服务访问私有 IP 吗？

不可以。公共代理仅用于允许访问的公网后端。如需使用私有地址，请运行自己的实例，并明确配置 CIDR 允许列表。

IP 地址更改后会怎样？

IP 是主机名的一部分。请为新 IP 使用新主机名；仍使用旧主机名的客户端会继续访问旧地址。

DNSBox 能证明后端 IP 的所有权吗？

DNS-01 证明的是对 DNS 主机名的控制权，并不验证后端 IP 或其所提供内容的所有权。

证书会自动续期吗？

运行中的 DNSBox 服务会为其管理的证书续期。导出的证书需要安排续期流程，并让使用它们的服务重新加载。

如果后端离线会怎样？

DNS 和 TLS 可能仍能正常工作，但代理无法返回应用内容。请检查后端的 HTTP 监听服务、防火墙和网络可达性。

在哪里报告问题？

请在 GitHub 上提交 issue，附上 DNSBox 版本、部署模式和相关错误信息。提交前请移除私钥、令牌和其他机密信息。

GitHub 问题反馈

技术参考

配置参考

源代码