uBlockDNS 客户端

uBlockDNS 客户端是一个独立项目，与 uBlock Origin 或其维护者无任何关联、背书或从属关系。

uBlockDNS 客户端为您的整个设备提供 DNS 级别的广告和跟踪器拦截。它使用社区维护的过滤列表（如 EasyList 和 EasyPrivacy），在 DNS 层应用过滤，因此应用、浏览器和后台服务都能被覆盖，无需为每个浏览器安装扩展。

网站： ublockdns.com

uBlockDNS 客户端适用于桌面和服务端环境，您只需一个安装点即可获得全系统保护，并通过 uBlockDNS 控制面板进行远程配置。

亮点

针对浏览器、应用和后台流量的全系统 DNS 过滤
与 uBlockDNS 服务建立加密的 DNS-over-HTTPS 上游连接
从控制面板实时更新过滤列表和自定义规则
本地服务模型，支持状态检查和服务的命令管理
跨平台支持 macOS、Linux、Windows 10+ 和 FreeBSD

安装

在 ublockdns.com 创建一个免费账户，然后按照控制面板中的设置指南操作。该指南涵盖所有受支持的平台，并提供可复制粘贴的命令和分步说明。

macOS 和 Linux 的快速安装：

curl -sSfL https://ublockdns.com/install.sh | sh -s -- <profile-id>

使用 -L 参数，以便 curl 能跟随托管安装脚本上的 Cloudflare 重定向。

安装过程中，系统可能会提示您输入 Mac 或 Linux 管理员密码，以更新系统 DNS 设置。

验证安装脚本校验和（Linux）：

curl -sSfLO https://ublockdns.com/install.sh
curl -sSfLO https://github.com/ugzv/ublockdnsclient/releases/latest/download/SCRIPT_SHA256SUMS
grep " install.sh$" SCRIPT_SHA256SUMS | sha256sum -c -
sh install.sh <profile-id>

Windows 10 或更高版本（以管理员身份运行 PowerShell）：

irm https://ublockdns.com/install?id=<profile-id> | iex

控制面板使用此引导流程。它会从 /install-script 下载安装程序，从而避免可能破坏直接 /install.ps1 下载的 Cloudflare 重定向问题。

已发布的 Windows 安装程序和二进制文件要求 Windows 10 或更高版本。不支持 Windows 7、Windows 8 和 Windows 8.1。

验证安装脚本校验和（PowerShell）：

iwr https://ublockdns.com/install-script -OutFile install.ps1
iwr https://github.com/ugzv/ublockdnsclient/releases/latest/download/SCRIPT_SHA256SUMS -OutFile SCRIPT_SHA256SUMS
$expected = (Select-String -Path .\SCRIPT_SHA256SUMS -Pattern " install.ps1$").Line.Split()[0].ToLower()
$actual = (Get-FileHash .\install.ps1 -Algorithm SHA256).Hash.ToLower()
if ($actual -ne $expected) { throw "install.ps1 checksum mismatch" }
powershell -ExecutionPolicy Bypass -File .\install.ps1 -ProfileId <profile-id>

发布页面上也提供 Windows GUI 安装程序（.exe）。

更新

服务每天自动更新；发布版本在应用前会通过 uBlockDNS 签名密钥进行验证。如需退出自动更新，可在服务环境中设置 UBLOCKDNS_NO_AUTOUPDATE=1，或使用 sudo ublockdns upgrade 手动更新。

自动更新适用于 macOS、Windows 和 Linux。在 FreeBSD 上，rc.d 不会重启已退出的服务，因此客户端不会在那里自行更新；请使用 sudo ublockdns upgrade。客户端会在启动时记录其当前所处的模式。

没有 upgrade 命令的旧版本：重新运行一次安装命令，自动更新便会接管。

卸载

macOS 和 Linux：

sudo ublockdns uninstall

Windows（以管理员身份运行 PowerShell）：

& "$env:ProgramFiles\uBlockDNS\ublockdns.exe" uninstall

开头的 & 是必需的。没有它，PowerShell 会将带引号的路径视为普通字符串，并报告 Unexpected token 'uninstall'。

卸载会停止服务并恢复您之前的 DNS 设置。二进制文件会保留在磁盘上；如果您不再需要它，请手动删除。之后运行 ublockdns status 以确认系统 DNS 不再指向 127.0.0.1。

其他平台

控制面板设置指南还涵盖 Chrome、Firefox、iOS、Android 和路由器。这些平台直接使用 DNS-over-HTTPS，不需要此客户端。

支持的架构

linux/amd64、linux/arm64、linux/armv7、darwin/amd64、darwin/arm64、windows/amd64、windows/arm64、freebsd/amd64

用法

ublockdns install   -profile <profile-id>   安装为系统服务
ublockdns uninstall                          移除服务并恢复 DNS
ublockdns start                              启动服务
ublockdns stop                               停止服务
ublockdns status                             显示服务状态和就绪详情
ublockdns status -json                       显示机器可读状态，包含 ready_code 和 probe_error
ublockdns wait-ready -timeout 45s            等待服务和 DNS 激活
ublockdns wait-ready -timeout 45s -json      输出机器可读的就绪状态，供自动化使用
ublockdns upgrade                            更新到最新版本并重启服务
ublockdns version                            打印版本

从控制面板管理您的过滤列表、自定义规则和查询日志。CLI 刻意保持精简：安装本地服务、验证其健康状态，然后让控制面板处理策略变更。

工作原理

客户端在 127.0.0.1:53 上运行本地 DNS 代理，并在 IPv6 可用时运行于 [::1]:53。它通过加密的 DNS-over-HTTPS 将所有查询转发到 uBlockDNS 服务。该服务根据您为配置文件启用的过滤列表和自定义规则评估每个查询，然后返回正常的 DNS 应答或拦截响应。

当您在控制面板中更新过滤列表或自定义规则时，客户端会实时接收这些更改并自动刷新本地 DNS 缓存，以便新决策快速生效。

从源码构建

需要 Go 1.25 或更高版本。

go build -o ublockdns .
sudo ./ublockdns install -profile <profile-id>

反馈和问题

发现 bug 或有建议？提交 issue。

对于拦截问题（广告漏过或网站被误拦截），请先检查您在控制面板中启用了哪些过滤列表。uBlockDNS 使用社区维护的列表，无法控制其内容。

安全

请通过 GitHub Security Advisories 私下报告安全漏洞。请勿针对安全问题提交公开 issue。

有关信任模型详情、开发透明度和当前审计状态，请参阅 SECURITY.md。

许可证

MIT

ublockdnsclient v0.3.1

分类