开源网络过滤工具librefang：DNS与代理混合部署实战指南

1. 项目概述一个开源网络过滤与内容管理工具最近在折腾家庭网络和自建服务时经常遇到一个核心需求如何在不依赖商业方案或复杂硬件的前提下对网络流量进行透明、高效且可定制的内容过滤与管理。无论是想给孩子一个更纯净的上网环境还是想在自建服务器上屏蔽掉恼人的广告和追踪器甚至是出于安全考虑拦截某些恶意域名这个需求都相当普遍。正是在这种背景下我深入研究了librefang/librefang这个项目。它不是一个简单的广告拦截器而是一个功能更为全面的、开源的网络内容过滤与重定向框架。简单来说librefang可以理解为你网络中的一个“智能交通警察”。所有经过它的网络请求比如访问一个网站、下载一个文件它都能根据你设定的规则进行检查。如果请求的域名或URL匹配了黑名单它可以直接“劝返”拦截如果匹配了白名单则放行甚至还能根据规则将请求重定向到你指定的另一个地址。这一切都是透明发生的对于终端用户比如家里的手机、电脑来说几乎无感你只需要将网络的DNS服务器指向运行librefang的设备即可。这个项目特别适合那些喜欢自己动手、对网络有一定了解同时又注重隐私和可控性的朋友。它避免了使用第三方闭源过滤服务可能带来的隐私泄露风险所有的规则和日志都掌握在你自己的手里。无论是部署在树莓派上打造一个家庭级的“安全网关”还是运行在云服务器上作为小型团队的内容策略执行点librefang都提供了一个轻量级但功能强大的基础。接下来我就结合自己的部署和调优经验把这个项目的里里外外、从原理到实操给大家拆解清楚。2. 核心架构与工作原理深度解析要玩转librefang首先得明白它到底是怎么工作的。它核心的运作模式是基于DNS过滤和HTTP/HTTPS代理的混合模式但以一种对用户极其友好的方式实现。2.1 DNS层面的拦截第一道防线librefang最基础也是最核心的功能是作为一个DNS服务器运行。当你的设备将DNS服务器设置为librefang的地址后所有域名解析请求都会先发到它这里。规则匹配librefang内部维护着多个规则集rule sets这些规则集本质上就是庞大的域名列表分门别类比如“广告域名”、“跟踪域名”、“恶意软件域名”、“成人内容域名”等。这些列表可以来自社区维护的项目如AdGuard Home列表、Steven Blacks hosts等也可以完全由你自己定义。决策与响应拦截如果请求解析的域名存在于任何一个启用的拦截规则集中librefang不会去查询真实的公共DNS如8.8.8.8而是直接返回一个特殊的IP地址通常是0.0.0.0或127.0.0.1。你的设备收到这个IP后就会认为这个域名无法访问从而达到了屏蔽的效果。这个过程速度极快因为根本不需要外网查询。放行如果域名不在任何拦截列表中librefang则会扮演一个“DNS转发器”的角色将查询请求转发给你配置的上游DNS服务器比如223.5.5.5或8.8.8.8获取到真实的IP地址后再返回给你的设备。注意纯DNS拦截有一个局限性它只能阻止域名解析。对于使用IP地址直接访问或者网站将广告资源托管在同一域名下的情况比如某些视频网站这种方法就失效了。这就需要第二道防线。2.2 HTTP/HTTPS代理过滤更精细的管控为了应对DNS拦截的不足librefang可以可选地部署为HTTP/HTTPS代理。你需要在你设备的网络设置中手动配置代理服务器地址为librefang。流量镜像与分析配置代理后设备所有的HTTP和HTTPS流量都会经由librefang转发。librefang能够看到流量的详细信息包括请求的完整URL路径例如https://example.com/ads/banner.jpg而不仅仅是域名。基于URL和内容的规则此时规则可以做得非常精细。你可以编写规则来拦截包含特定关键词的URL路径如/ads//tracker.js甚至可以基于返回内容的类型MIME type或内容本身进行过滤后者需要解密HTTPS即安装CA证书。重定向与修改代理模式更强大的地方在于它不仅能拦截还能修改。例如你可以将某个JavaScript文件的请求重定向到一个本地空白文件从而“无害化”处理某些脚本或者将请求重写到另一个你信任的镜像站点。两种模式如何协同在实际部署中通常推荐DNS过滤为主代理过滤为辅的策略。将librefang设为局域网默认DNS可以覆盖所有设备无感拦截大部分广告和恶意域名。对于少数需要深度过滤的特定设备如孩子的电脑再在其上单独配置代理指向librefang。这样既保证了管理的便捷性又满足了特殊场景下的精细控制需求。2.3 核心组件与数据流理解数据流能帮你更好地排查问题。一个典型的请求生命周期如下用户设备 - (DNS查询) - librefang DNS服务 - [规则匹配] - 拦截/转发上游DNS 用户设备 - (HTTP请求如配置了代理) - librefang 代理服务 - [规则匹配] - 拦截/修改/转发至目标网站librefang的服务通常包含以下几个核心组件DNS 服务器监听53端口或自定义端口处理UDP/TCP的DNS查询。HTTP/S 代理服务器监听某个端口如8080处理代理请求。规则引擎负责加载、解析和高速匹配海量规则。管理界面一个Web UI用于查看统计数据拦截数、查询数、管理规则列表、检查查询日志等。这是librefang用户体验好的关键。缓存对放行的DNS结果进行缓存大幅提升重复查询的响应速度。3. 从零开始部署与配置实战理论讲完我们动手把它跑起来。这里我以在Ubuntu Server 22.04上通过 Docker 部署为例这是目前最推荐的方式能避免复杂的依赖和环境问题。3.1 基础环境准备首先确保你的服务器已经安装了 Docker 和 Docker Compose。如果没有可以通过以下命令快速安装# 更新软件包索引 sudo apt-get update # 安装必要的依赖 sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common # 添加Docker官方GPG密钥 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # 添加Docker稳定版仓库 echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker引擎 sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io # 安装Docker Compose (以v2为例) sudo curl -L https://github.com/docker/compose/releases/download/v2.23.0/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose sudo chmod x /usr/local/bin/docker-compose3.2 编写Docker Compose配置文件我们不直接运行docker run命令而是使用docker-compose.yml文件来定义服务这样配置更清晰易于管理和维护。在你的工作目录例如~/librefang下创建docker-compose.yml文件version: 3.8 services: librefang: image: adguard/adguardhome:latest # 注意librefang的核心通常基于或类似AdGuard Home这里以AGH为例进行配置说明。实际请替换为librefang的官方镜像如果存在或构建方式。 container_name: librefang restart: unless-stopped ports: - 53:53/tcp # DNS over TCP - 53:53/udp # DNS over UDP (主要) - 67:67/udp # DHCP服务端口 (可选如果你想让librefang分配IP) - 68:68/udp # DHCP客户端端口 (可选) - 80:80/tcp # 管理界面HTTP (可选如果不用HTTPS) - 443:443/tcp # 管理界面HTTPS - 3000:3000/tcp # 初始配置端口 (首次安装访问) volumes: - ./work:/opt/adguardhome/work # 持久化工作数据配置、日志、缓存 - ./conf:/opt/adguardhome/conf # 持久化配置文件 cap_add: - NET_ADMIN # 允许进行网络管理操作对DNS/DHCP服务很重要 networks: - librefang-net networks: librefang-net: driver: bridge重要提示上面的配置示例使用了adguard/adguardhome镜像因为librefang作为一个具体的开源项目其公开的、可直接使用的Docker镜像可能不易查找或构建。在实际操作中你需要根据librefang项目的官方README确定正确的Docker镜像名或者学习如何从源码构建镜像。如果项目本身不提供镜像你可能需要自己编写Dockerfile。这里的关键是理解端口映射和数据持久化的思路。端口映射详解53:53这是核心将容器的DNS服务端口映射到主机这样局域网设备才能将主机IP设为DNS服务器。80:80/443:443Web管理界面。建议只映射443并配合反向代理如Nginx使用HTTPS更安全。3000:3000通常用于首次安装向导。安装完成后可以关闭此端口映射。67:67/udp/68:68/udp仅当你希望librefang同时承担局域网DHCP服务器时才需要。这可以让它自动给新设备分配IP并指定自身为DNS实现最无缝的体验但会与你现有的路由器DHCP冲突需谨慎选择。数据持久化volumes部分将容器内的目录挂载到主机确保配置、日志和缓存数据在容器重启后不会丢失。3.3 启动服务与初始化配置启动容器cd ~/librefang docker-compose up -d使用docker-compose logs -f librefang可以查看实时日志确认没有错误。完成初始化 打开浏览器访问http://你的服务器IP:3000。你会看到初始化向导。设置管理界面配置Web管理界面的监听地址通常0.0.0.0和端口如80和443注意不要和主机已有服务冲突。设置管理员账户创建登录用的用户名和密码。配置上游DNS这是关键一步。librefang需要向更上游的DNS服务器查询未被拦截的域名。你可以填写多个例如tls://dns.pub阿里云公共DNSDoThttps://doh.pub/dns-query阿里云公共DNSDoHtls://8.8.8.8Google DNSDoThttps://dns.google/dns-queryGoogle DNSDoH 建议至少配置一个DoT或DoH服务器这样从librefang到上游的查询也是加密的防止被窃听或篡改。设置客户端默认过滤规则可以启用一些内置的隐私保护、反跟踪列表。应用配置并登录完成初始化后服务会重启。之后你就需要通过你设置的端口如https://你的服务器IP来访问管理界面了。3.4 基础网络配置让设备使用你的过滤服务部署好服务只是第一步关键是让网络中的设备用它来解析DNS。方法一逐台设备手动配置推荐用于测试和少数设备进入你手机、电脑的网络设置将DNS服务器地址修改为运行librefang的服务器的IP地址。关闭并重新打开Wi-Fi或网络连接使其生效。方法二在路由器上配置一劳永逸登录你家路由器的管理后台通常是192.168.1.1或类似找到DHCP服务器设置页面。将“首选DNS服务器”和“备用DNS服务器”都设置为你的librefang服务器IP。保存并重启路由器。之后所有通过DHCP自动获取IP的设备都会自动使用你设置的DNS。实操心得在路由器上设置是最彻底的方法。但务必确保你的librefang服务器IP是静态的在路由器里做IP与MAC地址绑定否则服务器IP一变所有设备就上不了网了。另外修改后需要让设备重新连接Wi-Fi或重启以获取新的DNS配置。4. 核心功能配置与规则管理详解登录管理界面后你会发现功能区域主要分为仪表盘、过滤器、查询日志、设置等。我们重点看过滤规则和高级功能。4.1 理解与配置过滤规则列表这是librefang的“武器库”。在“过滤器” - “DNS封锁列表”中你可以添加和管理规则列表。列表类型AdGuard 简化列表语法最常用兼容性好。列表地址通常是一个URL指向一个包含大量规则行的文本文件。Hosts 文件传统的域名 IP格式librefang也能直接使用。域名列表每行一个纯域名适用于简单的拦截。添加经典规则列表 点击“添加阻止列表”输入名称和URL。一些经过验证的高质量列表包括AdGuard DNS 过滤器https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt(综合性强)Steven Blacks hostshttps://raw.githubusercontent.com/StevenBlack/hosts/master/hosts(专注于屏蔽广告、恶意软件)OISD 完整版https://big.oisd.nl/(非常全面但可能过于激进)Anti-ADhttps://anti-ad.net/easylist.txt(中文区优化较好)添加后记得点击列表右侧的“启用”开关并点击页面上方的“检查更新”按钮手动更新一次。自定义规则在“过滤器” - “自定义规则”中你可以添加针对特定情况的精确规则。||example.com^拦截example.com及其所有子域名。||example.com^放行example.com及其所有子域名白名单优先级高于黑名单。127.0.0.1 example.com使用Hosts语法将example.com指向本地等效拦截。/REGEX/使用正则表达式进行复杂匹配。注意事项不要一次性添加过多过于激进的列表可能导致误杀正常网站比如某些购物、银行网站的功能依赖特定域名。建议从1-2个主流列表开始观察几天查询日志将误拦截的域名添加到白名单自定义规则中使用再逐步添加更多列表。4.2 利用查询日志进行调优和问题排查“查询日志”页面是运维的核心。这里记录了所有经过librefang的DNS查询并清晰标注了结果是“已阻止”还是“已处理”。快速白名单如果你发现某个常用网站或App功能异常比如图片加载不出可以在此页面搜索相关域名。如果发现它被“已阻止”并且你确认它是正常的可以直接点击该条日志选择“放行此域名”系统会自动为你创建一条白名单规则。分析流量你可以看到哪些设备查询最频繁哪些域名最常被拦截。这有助于你了解网络行为甚至发现异常设备或软件。搜索与过滤支持按设备、域名、状态阻止/放行、时间进行筛选是定位问题的利器。4.3 高级功能DNS加密与家长控制启用DNS-over-HTTPS (DoH) / DNS-over-TLS (DoT) 在“设置” - “加密设置”中你可以为librefang本身开启加密DNS服务。这样局域网内的设备不仅可以享受过滤还能保证从设备到librefang服务器这段链路的DNS查询是加密的。你需要配置端口如DoH的443 DoT的853和证书可以使用自签名证书但设备需要信任更推荐使用Let‘s Encrypt等自动续签的证书。设置上游的加密DNS 如前所述在“设置” - “DNS设置”中将上游服务器设置为DoT或DoH地址保证从librefang到互联网的查询也是加密的形成端到端的隐私保护。家长控制与安全搜索安全搜索在“设置” - “家长控制”中可以强制开启Google、Bing、Yandex、YouTube等搜索引擎的“安全搜索”模式即使设备上没有设置也能生效。日程安排可以设置规则仅在特定时间段生效如工作日晚上10点到早上7点拦截所有游戏域名。按设备/客户端分组这是高级用法。你可以为不同的IP或客户端名称分配不同的过滤策略。比如给孩子的平板电脑应用更严格的“成人内容”过滤列表和作息时间限制而大人的电脑则使用相对宽松的规则。5. 性能调优、安全加固与高可用考量当服务稳定运行用户量增多后就需要考虑性能和安全了。5.1 性能调优要点硬件与系统librefang本身很轻量树莓派4B级别完全足够支撑一个家庭网络。瓶颈通常在I/O和内存。使用SSD存储日志和缓存能提升规则加载和查询速度。确保服务器有足够内存尤其是在加载了数十万条规则后。缓存配置在“设置” - “DNS设置”中调整缓存大小和生存时间TTL。增大缓存如从默认的4MB到64MB能显著提升重复域名查询的响应速度。但TTL不宜设置过长否则域名IP变更时更新会不及时。上游DNS选择选择延迟低、稳定性高的上游DNS。可以使用dig命令测试不同DNS服务器的响应速度。librefang支持配置多个上游并会自动选择最快的。规则列表精简定期审查规则列表。有些列表可能包含大量你根本不会访问的语种或地区的域名可以寻找更精准的列表替代或者使用“允许列表”模式只放行明确允许的域名其他全部拦截适用于高度受限环境。5.2 安全加固措施管理界面安全强制HTTPS务必启用管理界面的HTTPS并使用有效的证书如Let‘s Encrypt。修改默认端口不要使用3000、80、443等常见端口对外暴露管理界面。可以通过Docker映射到非标准端口如8443:443并通过防火墙限制访问来源IP。强密码与2FA设置强管理员密码如果librefang支持启用双因素认证。服务本身安全限制DNS服务访问在服务器防火墙如ufw中只允许局域网网段如192.168.1.0/24访问53端口。绝对不要将DNS端口暴露在公网否则可能被利用进行DNS放大攻击。定期更新无论是Docker镜像还是自编译版本定期更新到最新稳定版以获取安全补丁。日志管理DNS查询日志包含敏感信息。定期清理或关闭详细日志。在“设置” - “常规设置”中可以配置日志保留时长和大小限制。5.3 高可用与备份方案对于不能容忍服务中断的场景可以考虑高可用。主从热备部署两台librefang实例配置完全相同的规则。在路由器的DHCP设置中将主服务器IP设为“首选DNS”备用服务器IP设为“备用DNS”。当主服务器宕机时设备会自动切换到备用服务器。配置备份定期备份docker-compose.yml文件和挂载出来的work、conf目录。恢复时只需在新机器上放置这些文件重新docker-compose up -d即可。使用健康检查在Docker Compose文件中配置健康检查配合监控工具如PrometheusGrafana当服务异常时能及时告警。# 在docker-compose.yml的librefang服务下添加 healthcheck: test: [CMD, nslookup, -typeSOA, localhost, 127.0.0.1] interval: 30s timeout: 10s retries: 3 start_period: 40s6. 常见问题排查与实战技巧实录即使配置再仔细在实际运行中还是会遇到各种问题。这里记录几个我踩过的坑和解决方法。6.1 问题速查表问题现象可能原因排查步骤与解决方案所有设备都无法上网1.librefang服务未运行或崩溃。2. 服务器防火墙阻塞了53端口。3. 上游DNS配置错误或不可达。1.docker-compose ps查看状态docker-compose logs查看错误日志。2.sudo ufw status检查防火墙规则确保53端口对局域网开放。3. 在librefang管理界面“设置”-“DNS设置”中测试上游DNS或暂时换成223.5.5.5等知名公共DNS测试。部分网站访问慢或超时1. 上游DNS响应慢。2. 规则列表过多或某条规则匹配效率低。3. 缓存设置过小或TTL问题。1. 在“查询日志”中查看该域名的解析耗时。尝试更换更快的上游DNS。2. 暂时禁用部分规则列表观察是否改善。优化自定义规则避免过于宽泛的正则。3. 适当增大缓存大小。某个特定网站/App无法访问其他正常该网站/App的某个关键域名被规则列表误拦截。1. 在“查询日志”中搜索该网站主域名和相关子域名找到被“已阻止”的条目。2. 确认该域名是否必需可通过在电脑上临时修改DNS为114.114.114.114对比测试。3. 若确为误杀点击日志条目“放行此域名”或手动添加 管理界面无法访问1. 端口映射错误或服务未监听。2. 浏览器缓存或HTTPS证书问题。1.docker-compose ps确认端口映射netstat -tlnp查看主机端口监听情况。2. 尝试无痕模式访问或检查证书是否过期、不被信任。设备未使用librefang的DNS1. 设备网络配置未更新。2. 路由器DHCP未正确下发DNS。3. 设备硬编码了DNS如某些路由器、智能电视。1. 在设备上执行ipconfig /all(Win) 或cat /etc/resolv.conf(Linux) 检查实际使用的DNS。2. 重启设备网络或路由器。3. 对于硬编码设备可能需要在路由器层面通过防火墙规则将53端口的出站流量强制重定向到librefangDNAT但这需要较高网络权限。6.2 实战技巧与心得“先放行后收紧”策略初次部署时不要启用太多过滤列表。先运行1-2天在查询日志里观察你家网络的正常访问模式。然后逐步添加列表每次添加后观察1天及时处理误报。这样比一开始就严格拦截导致全家上网异常体验要好得多。善用客户端分组如果你有智能家居设备如IoT设备它们可能会频繁查询一些奇怪的域名。为这些设备的IP单独创建一个分组应用最宽松的规则甚至只做DNS转发不过滤可以避免它们因域名被拦而“失联”。定期更新规则列表广告和跟踪域名是不断变化的。虽然librefang可以设置自动更新但建议每周手动检查一下更新状态并关注社区讨论了解哪些列表维护活跃、误杀少。DNS-over-QUIC (DoQ) 尝试如果上游DNS支持DoQ可以尝试配置。这是一种更新的DNS加密协议理论上比DoT/DoH延迟更低、效率更高。在“上游DNS”中配置格式为quic://dns.example.com。与Pi-hole对比选择librefang在理念和功能上与知名的Pi-hole非常相似。两者都是优秀的自托管DNS过滤方案。选择哪个更多是个人偏好。librefang特别是其参考实现AdGuard Home的Web界面通常被认为更现代内置的DoH/DoT服务端配置更直观。Pi-hole的社区规则和生态可能更庞大一些。你甚至可以同时运行两者让一个作为另一个的上游实现双重过滤但复杂度也会增加。部署和维护这样一个网络基础设施组件最大的成就感来自于对自家网络流量的完全掌控和透明化。看着查询日志里那些被拦下的广告和追踪请求不仅提升了网页浏览速度更带来了一种隐私受到保护的踏实感。这个过程需要一些耐心去调优规则处理误报但一旦稳定下来它就会成为一个无声而强大的守护者在后台为你服务。