esp32-c3-adblock自定义黑名单操作全解：添加、删除与200条上限说明
【免费下载链接】esp32-c3-adblockPi-hole-class DNS ad-blocker on a $2 ESP32-C3 (no PSRAM): 537k domains as 40-bit FNV-1a hashes in flash, binary-searched. UDP DNS sinkhole + web dashboard. https://youtube.com/shorts/RaxszOUMi8E?feature=share项目地址: https://gitcode.com/GitHub_Trending/es/esp32-c3-adblock
esp32-c3-adblock 是一款跑在 2 美元 ESP32-C3 小板上的DNS 广告拦截器（Pi-hole 风格）：内置约 53.7 万个广告域名哈希，通过 UDP 解析劫持（sinkhole）让广告请求返回 0.0.0.0。除了内置的大黑名单，它还提供了一个自定义黑名单功能——你可以在 Web 面板里随时添加、删除自己指定的域名，最多支持200 条，且断电不丢失。本文带你完整掌握自定义黑名单的添加、删除操作和 200 条上限背后的细节。
🧩 自定义黑名单是什么？
设备里其实有"两份"拦截名单：
| 名单 | 存储位置 | 容量 | 更新方式 |
|---|---|---|---|
| 内置黑名单（hash 表） | flash 分区blocklist.bin | 最高约 53.7 万域名 | 上传 bin 文件 / 远程定时拉取 |
| 自定义黑名单 | LittleFS 中的custom.txt | 最多 200 条 | Web 面板即时增删 |
自定义黑名单适合"内置名单没覆盖到的广告源"或"我个人想屏蔽的站点"。它的核心实现在 src/main.cpp，上限常量定义为：
MAX_CUSTOM = 200——这是硬上限，超出后新域名会被直接拒绝- 每条记录保存"域名 + 40 位 FNV-1a 哈希"，查询时逐条线性比对，200 条对响应速度几乎无影响
➕ 向自定义黑名单添加域名（3 步完成）
- 打开面板：浏览器访问
http://c3adblock.local（首次操作需输入 secrets.example.h 中设置的WEB_USER/WEB_PASS账号密码） - 找到CUSTOM BLOCKED DOMAINS区域（面板 HTML 见 src/page.h），在输入框填入域名，例如
ads.example.com - 点击Block domain按钮，成功后域名立即出现在下方列表中
添加时固件会自动做几件"善后"处理（见addCustom()，src/main.cpp）：
- ✅自动去空格、转小写——
Ads.Example.COM和ads.example.com视为同一个 - ✅自动剥离
www.前缀——填www.badads.net实际存入badads.net - ✅必须包含一个点——纯单词（如
baidu）会被拒绝 - ✅拒绝重复——已存在的域名再次添加会静默失败，不会占第二个名额
- ✅立即写入 flash——
saveCustom()马上落盘，重启不丢
💡 小贴士：屏蔽一个父域会连带屏蔽它的所有子域。添加badads.net后，img.badads.net、a.b.badads.net的查询也都会被拦截，这比逐个添加子域省名额得多。
🗑️ 从自定义黑名单删除域名
- 在CUSTOM BLOCKED DOMAINS列表中找到目标域名，点击右侧remove按钮即可
- 列表为空时显示 "none yet"，说明自定义区已清空
删除同样即时生效并自动保存到 flash。如果之前是"误加"导致某个网站打不开（比如父域屏蔽误伤了子域），remove 一下、刷新浏览器 DNS 缓存后就会恢复访问。
🔢 200 条上限说明：为什么是这个数？能突破吗？
为什么是 200？
200 条是 RAM 预算下的工程折中：每条记录需要保存一个String域名和 8 字节哈希，存放在 src/main.cpp 的静态数组里。整个固件只占用约50 KB RAM，把自定义区控制在 200 条可以让内存占用几乎可以忽略，同时线性扫描 200 条的耗时远小于一次 flash 读取。
触发上限后的行为
- 第 201 条添加会静默失败（
numCustom >= MAX_CUSTOM时直接返回），面板列表仍显示 200 条 - 解决方法：先删除不再需要的域名，腾出名额再添加
真的需要超过 200 条怎么办？
把域名写进构建源，重新生成内置黑名单：
- 用 tools/build_blocklist.py 把域名混入 hosts 文件或纯域名列表，构建出新的
blocklist.bin - 在面板BLOCKLIST → Upload上传（注意：4MB flash 开启固件 OTA 后，内置名单约 25 万域名封顶）
⚠️ 注意：内置黑名单与自定义黑名单是独立存储的，上传新的
blocklist.bin不会清空你的自定义域名。
❓ 常见问题（避坑指南）
Q1：为什么我加了域名，还是没被拦截？
先检查设备是否暂停了拦截（面板顶部 "Pause" 状态）。另外有个容易忽略的点：如果 flash 中的blocklist.bin丢失或未加载（哈希数为 0），设备会"fail-open"直接放行所有查询，此时自定义域名也暂时失效——重新上传一份 blocklist 即可恢复。
Q2：添加操作需要密码，是必须的吗？
是的。/addblock、/unblock属于状态变更接口，需要HTTP Basic Auth + 自定义请求头双重校验（见 src/main.cpp），防止局域网内其他设备或网页偷偷篡改你的黑名单。用面板自带按钮操作时会自动带上这些凭证，无需手动处理。
Q3：设备重启后自定义域名还在吗？
在。启动时loadCustom()会从 LittleFS 读取custom.txt恢复到内存，最多恢复 200 条，无需重新配置。
📌 关键文件速查
- 主程序与 200 条上限：src/main.cpp
- 面板界面（CUSTOM BLOCKED DOMAINS 区域）：src/page.h
- 账号密码模板（
WEB_USER/WEB_PASS）：src/secrets.example.h - 自建大名单构建脚本：tools/build_blocklist.py
一句话总结：200 条自定义域名足够覆盖个人屏蔽需求；日常增删都在c3adblock.local面板上两下鼠标搞定，超过 200 条就把它们并入blocklist.bin走内置名单通道。
【免费下载链接】esp32-c3-adblockPi-hole-class DNS ad-blocker on a $2 ESP32-C3 (no PSRAM): 537k domains as 40-bit FNV-1a hashes in flash, binary-searched. UDP DNS sinkhole + web dashboard. https://youtube.com/shorts/RaxszOUMi8E?feature=share项目地址: https://gitcode.com/GitHub_Trending/es/esp32-c3-adblock
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
