ESP32-C3打造轻量DNS广告拦截器

原创

黑鸟
黑鸟

黑鸟

2026年10月8日 23:41
广东

在小说阅读器读本章

去阅读

在公众号小说中沉浸阅读

有开发者利用成本仅 5 美元的 ESP32 芯片打造出一款体积小巧的 USB 广告拦截硬件设备。这款微型拦截加密狗能够加载多达 53.7 万个待拦截域名，硬件资源消耗控制得十分优秀，整套固件运行时只占用大约 50KB 的内存资源，在处理被屏蔽域名的 DNS 解析请求时，仅需 10 毫秒就能给出应答。

不同于常见依靠电脑、路由器完成广告过滤的方案，该设备作为独立外设，依托 ESP32 的运算能力，在极低硬件开销下承载了规模庞大的域名黑名单，在廉价微型硬件上实现高效的 DNS 广告与恶意域名拦截效果，展现出在嵌入式设备上做 DNS 过滤的巧妙实现思路。

提起家用网络广告拦截，很多人会想到Pi-hole这类方案。它们大多需要树莓派这类单板计算机支撑，不算低的硬件成本加上额外的摆放空间，让不少想尝试的人望而却步。

最近一款名为esp32-c3-adblock的开源项目(github/M-Abozaid/esp32-c3-adblock)，把完整的DNS（域名系统）广告拦截功能塞进了售价仅2美元的ESP32-C3开发板。不需要额外PSRAM（外置缓存），体积小到能直接插在路由器的USB口上，就能给整个家庭网络提供广告过滤能力。

核心创新 把拦截列表存进闪存而非内存

市面上多数ESP32 DNS拦截方案，都会把完整的域名字符串全部加载到内存运行。这种方式对内存容量要求很高，必须搭配带PSRAM的型号才能装下上万条规则，硬件成本直接涨到七八美元。

这个项目跳出了传统思路，它将所有待拦截的域名转换成固定长度的哈希值，按顺序排列后存储在板载闪存中。每次收到DNS查询时，直接通过二分查找在闪存里匹配哈希值，全程只占用约50KB运行内存，完全不需要PSRAM参与。

视频演示：

已关注

关注

重播 分享 赞

关闭

观看更多

更多

退出全屏

切换到竖屏全屏退出全屏

黑鸟已关注

分享视频

，时长00:24

0/0

00:00/00:24

切换到横屏模式

继续播放

[ ]

进度条，百分之0

播放

00:00

/

00:24

00:24

倍速

全屏

倍速播放中

0.5倍0.75倍1.0倍1.5倍2.0倍

超清流畅

继续观看

ESP32-C3打造轻量DNS广告拦截器

观看更多

转载

,

ESP32-C3打造轻量DNS广告拦截器

黑鸟已关注

分享点赞在看

已同步到看一看写下你的评论

视频详情

两种方案的核心参数差异可以参考下表：

表1传统内存存字符串方案与本项目闪存存哈希方案对比

图3两种存储方案的参数对比，哈希存闪存在成本、内存占用与冲突控制上全面占优

为什么选40位FNV-1a哈希

项目选用40位的FNV-1a（哈希算法）处理域名，每个域名转换后只占5字节的闪存空间。这个长度是针对4MB闪存的最优平衡点。

按照生日悖论的冲突概率计算，14.1万条域名时几乎不会出现哈希冲突，就算扩容到53.7万条，冲突也仅约1次，只会有极个别域名被误拦截。如果降到32位，虽然能节省20%的闪存空间，但25万条域名时就会出现约7次冲突，误拦截概率明显上升。升到64位又会每个域名多浪费3字节空间，对于家用场景来说完全属于性能过剩。

这种哈希存闪存的思路不止适用于ESP32-C3。放在16MB闪存的ESP32-S3上，用这种方式可以存储约270万条域名，远高于8MB PSRAM存字符串能承载的46.6万条。可以说在绝大多数场景下，闪存存哈希的方案都比内存存字符串的效率更高，ESP32-C3只是把这种优势体现得格外明显。

完整工作流程

设备收到DNS查询请求后，首先提取出请求的完整域名，计算出对应的FNV-1a哈希值，同时自动补全父级后缀进行匹配。接着在闪存的有序哈希表中执行二分查找，整个过程只需要约18次闪存读取。

如果匹配成功，就返回0.0.0.0地址，也就是把这个域名拉入sinkhole（沉洞拦截）。如果匹配失败，就把请求转发给上游DNS服务器，再把真实的解析结果回传给客户端。加上WiFi网络延迟，单次查询总耗时约10毫秒，完全不影响日常使用体验。

图2 DNS查询拦截流程，命中返回0.0.0.0进入沉洞拦截，未命中转发上游解析

硬件要求与外观设计

整个项目的硬件门槛非常低，任意一款ESP32-C3开发板都能正常运行，官方测试使用的是C3 SuperMini型号，只需要4MB闪存，不需要任何额外硬件。经典款ESP32开发板也可以编译运行对应固件。

硬件实物

ESP32-C3 SuperMini是一款尺寸极小的开发板，搭载RISC-V架构的单核处理器，自带2.4GHz WiFi和蓝牙5.0，板载4MB闪存，USB-C接口兼顾供电和程序烧录。整板尺寸只有22mm×18mm，比一枚硬币大不了多少。

图1 ESP32-C3 SuperMini开发板实物渲染，板载4MB闪存，USB-C接口兼顾供电与烧录

供电方面直接用稳定的USB源即可，比如普通手机充电器，或者路由器背后闲置的USB口。用一个USB-A转USB-C转接头，就能把它直接插在路由器上，不需要额外电源适配器，也不用额外找地方摆放。需要注意的是，劣质或松动的转接头在WiFi发射的瞬间可能让供电电压跌落，导致射频工作异常，尽量挑选质量可靠的转接头。

官方还提供了可3D打印的外壳模型，适配C3 SuperMini的尺寸。打印时不需要添加支撑，0.2mm层厚搭配15%的填充率就足够使用。设计上有几个细节需要注意，天线端不要用实心塑料包裹，也不要靠近金属物件，否则会大幅降低WiFi信号强度。开发板待机时温度在45到55摄氏度之间，外壳需要预留通风口保证散热。

刷机与初始配置

项目基于PlatformIO（嵌入式开发平台）开发，第一次使用需要用USB线连接电脑烧录固件，完成之后所有更新都可以通过WiFi OTA（空中升级），不用再插线。

准备工作

首先需要安装最新版PlatformIO，可以直接使用VSCode的PlatformIO插件，也可以通过pip在虚拟环境中安装。注意Linux发行版自带的platformio软件包版本通常偏旧，容易出现属性报错，建议使用官方渠道的最新版本。

接下来复制源码中的密钥模板文件，修改对应的配置项。WiFi名称和密码可以暂时保留占位符，后续可以通过设备自带的配网网页设置。但WEB\_USER、WEB\_PASS和OTA\_PASS这三项必须改成自己的内容，它们分别对应网页后台的管理密码和固件OTA升级的密码，是保护设备安全的核心屏障。

然后运行工具目录下的build\_blocklist.py脚本，生成拦截列表的哈希文件。默认使用StevenBlack基础列表加Hagezi Light规则，包含约10万条拦截条目，对WhatsApp等社交软件的兼容性较好，不容易出现误拦截。

最后依次执行固件烧写和文件系统烧写命令，把主程序和拦截列表写入开发板。启动后可以通过串口监视器查看设备分配到的IP地址，也可以直接在浏览器访问c3adblock.local打开管理后台。

免刷写WiFi配置

如果没有提前在配置文件里写WiFi密码也没关系。设备启动后如果连不上已知网络，会自动开启一个名为C3-AdBlock-XXXX的开放热点，同时启动captive portal（强制配网门户）。用手机连接这个热点，在弹出的页面里选择家里的WiFi，输入密码就能完成配网。

后续要更换网络的话，可以在后台点击Forget WiFi按钮，或者上电时按住BOOT按键，设备就会重新进入配网模式。

自定义规则与OTA升级

设备的所有管理功能都集成在网页后台中，不需要再连接电脑操作。

自定义拦截列表

项目支持多种格式的规则源，包括标准hosts文件、每行一个域名的纯文本列表，还有AdGuard基础规则。被拦截的域名会同时拦截它的所有子域名，正则、通配符这类哈希列表无法支持的高级规则会被自动跳过并统计数量。

如果需要放行某个域名，可以用对应的白名单规则解除拦截，但只能解除这个域名本身的拦截，无法在已经被拦截的父域名下单独放行子域名。如果配置的规则源无法正常下载，构建脚本会直接停止而不是静默生成不完整的列表，避免出现规则缺失的情况。

升级功能

拦截列表支持两种更新方式，既可以直接在后台上传本地编译好的blocklist.bin文件，也可以设置远程自动更新地址，设备会按照固定周期拉取最新的规则文件。官方通过GitHub Actions每周一自动构建最新的默认列表，只需要把对应地址填入设置，设备就能自动保持规则更新。

固件同样支持OTA升级，在后台上传编译好的firmware.bin文件，设备校验通过后就会自动重启进入新系统。也可以在命令行通过WiFi直接推送固件，不需要靠近设备。

这里需要注意闪存分区的取舍。4MB总闪存如果开启双分区支持固件OTA，剩下给拦截列表的空间约1.3MB，最多能存储25万条左右的域名。如果想要使用53.7万条的终极拦截列表，就要切换到单分区方案，放弃固件OTA的功能。用户可以根据自己的需求在partitions.csv文件中调整分区配置。

安全设计细节

项目在接口安全上做了不少针对性设计，没有把管理接口完全暴露在局域网中。

网页后台的首页和统计接口是公开只读的，所有人都能查看运行状态。但所有会修改设备状态的接口都需要HTTP Basic Auth认证，包括添加删除拦截规则、重置WiFi配置、上传拦截列表、升级固件这些操作。网络OTA升级也需要单独的密码验证，避免被恶意篡改固件。

针对常见的CSRF（跨站请求伪造）攻击，所有修改操作的接口都要求携带自定义的X-Requested-With: c3-adblock请求头。普通的图片标签、自动提交表单都无法携带这个请求头，也就没法跨站触发设备操作。这也是为什么重置WiFi不能直接通过访问链接实现，必须在后台页面点击对应按钮。

后台渲染自定义拦截域名时会做HTML转义处理，避免恶意域名里包含的脚本代码在浏览器中执行，堵住了XSS（跨站脚本）漏洞的风险路径。

当然也要客观看待它的安全边界。设备使用的是普通HTTP协议，没有运行TLS加密服务，Basic Auth的凭证是以base64编码传输而非加密传输。这个防护等级主要针对局域网内的普通未授权访问，适合可信的家庭网络环境。如果是开放的公共网络，存在被嗅探凭证的可能性。

另外如果一直使用默认的占位密码，设备会在串口日志和后台首页打出警告提醒，但依然可以正常运行。接入不信任的网络环境前，一定要记得修改成自己的密码。

使用方法与避坑指南

使用时只需要把设备的DNS地址改成ESP32-C3的IP，就能让整个设备的流量都经过广告拦截。也可以把它设为二级DNS，放在主DNS后面作为补充过滤。

可以用dig命令测试效果，向设备IP查询广告域名会返回0.0.0.0，说明拦截生效。查询正常网站则会返回真实的IP地址，和直接访问没有区别。

实际使用中有几个容易踩的坑需要注意。

Linux系统中默认开启的ModemManager服务，会自动识别并占用/dev/ttyACM0串口设备，还会触发开发板复位，导致串口无法正常使用。解决方法是添加一条udev规则，让系统忽略这个设备，避免被ModemManager接管。

开发板的USB串口控制台，会在主机端连接之前吞掉早期的启动日志。如果需要查看完整启动信息，可以在代码中添加等待串口连接的逻辑。

DNS客户端通常会在请求中附带EDNS OPT记录，拦截的回复包必须严格按照规范，只包含问题段和回答段，否则会被客户端判定为格式错误的报文。

esp32-c3-adblock是一个把嵌入式硬件性能压榨到极致的创意项目，用极低的成本实现了家用DNS广告拦截的核心功能。它不需要复杂的动手能力，几块钱的开发板加几条简单命令，就能搭出一套可用的全屋广告过滤系统。

对于喜欢折腾的数码爱好者来说，这不仅是一个高性价比的实用工具，也提供了在资源受限的嵌入式设备上运行网络服务的新思路。在保证核心体验的前提下，用巧妙的设计大幅降低硬件门槛，正是开源项目最有魅力的地方。