深入解析anudeepND/whitelist项目中的白名单管理脚本

脚本概述

anudeepND/whitelist项目提供了一个Python脚本(whitelist.py)，用于自动化管理Pi-hole广告拦截系统的白名单。这个脚本能够从远程仓库获取预定义的安全域名列表，并将其整合到Pi-hole的配置中，同时处理各种特殊情况，如新旧域名列表的对比、用户自定义白名单与系统白名单的冲突等。

核心功能解析

1. 远程白名单获取

脚本通过fetch_whitelist_url()函数从指定URL获取白名单内容：

def fetch_whitelist_url(url):
    headers = {'User-Agent': 'Mozilla/5.0...'}
    try:
        response = urlopen(Request(url, headers=headers))
        response = response.read().decode('UTF-8').replace('\r\n', '\n')
        return '\n'.join(x.strip() for x in response.splitlines())
    except HTTPError as e:
        print('[X] HTTP Error:', e.code, 'whilst fetching', url)
        exit(1)

该函数使用标准urllib库进行HTTP请求，并添加了用户代理头以避免被某些服务器拒绝。错误处理机制确保在获取失败时脚本能够优雅退出。

2. Pi-hole版本适配

脚本能够自动检测并适配不同版本的Pi-hole：

• 新版Pi-hole(5.0+): 使用SQLite数据库(gravity.db)存储白名单
• 旧版Pi-hole: 使用传统的文本文件(whitelist.txt)存储白名单

if os.path.isfile(gravity_db_location) and os.path.getsize(gravity_db_location) > 0:
    db_exists = True
    print('[i] Pi-Hole Gravity database found')
else:
    print('[i] Legacy Pi-hole detected (Version older than 5.0)')

3. 智能白名单管理

对于新版Pi-hole，脚本执行以下智能操作：

1. 识别现有白名单：查找已由脚本添加的域名(通过特殊注释标记)
2. 用户自定义检查：识别用户手动添加但与脚本域名重叠的条目
3. 过期域名清理：移除脚本之前添加但新版本中不再包含的域名
4. 新域名添加：添加当前版本中存在但系统中缺失的域名

# 检查数据库中已由脚本添加的域名
gravityScript_before = cursor.execute("SELECT * FROM domainlist WHERE type = 0 AND comment LIKE '%qjz9zk%'")

# 检查用户添加但与脚本域名重叠的条目
user_add = cursor.execute("SELECT * FROM domainlist WHERE type = 0 AND comment NOT LIKE '%qjz9zk%'")

# 移除旧版脚本添加但新版不再包含的域名
sql_delete = "DELETE FROM domainlist WHERE type = 0 AND id = '{}'".format(INgravityNOTnewList[z][0])

# 添加新域名
sql_add = "INSERT OR IGNORE INTO domainlist (type, domain, enabled, comment) VALUES {}".format(nW[sql_index])

4. Docker环境支持

脚本提供了对Docker环境下Pi-hole的特殊处理：

def restart_pihole(docker):
    if docker is True:
        subprocess.call("docker exec -it pihole pihole restartdns reload",
                      shell=True, stdout=subprocess.DEVNULL)
    else:
        subprocess.call(['pihole', '-g'], stdout=subprocess.DEVNULL)

使用指南

基本用法

1. 确保系统已安装Python 3
2. 下载whitelist.py脚本
3. 运行脚本(需要root权限)：

sudo python3 whitelist.py

可选参数

• -d 或 --dir: 指定Pi-hole的etc目录路径(默认为/etc/pihole)
• -D 或 --docker: 标记是否在Docker环境中运行Pi-hole

示例：

sudo python3 whitelist.py -d /custom/pihole/path -D

技术亮点

1. 原子性操作：脚本确保所有数据库操作要么完全成功，要么完全失败，避免中间状态
2. 最小权限原则：脚本会检查是否有足够的写入权限，避免因权限不足导致部分失败
3. 详细日志：提供详细的执行过程输出，方便问题排查
4. 智能冲突解决：妥善处理用户自定义白名单与系统白名单的冲突
5. 版本兼容性：自动适配不同Pi-hole版本

最佳实践建议

1. 定期执行：建议设置cron任务定期执行此脚本，保持白名单更新
2. 备份配置：在执行前备份Pi-hole配置，特别是gravity.db文件
3. 监控变更：关注脚本输出，了解每次执行添加/删除了哪些域名
4. 自定义扩展：可以通过修改远程URL使用自定义白名单源

总结

anudeepND/whitelist项目的这个Python脚本为Pi-hole用户提供了强大而灵活的白名单管理工具。它通过自动化处理繁琐的白名单更新工作，同时保持对用户自定义设置的尊重，是维护高效广告拦截系统的重要辅助工具。无论是普通用户还是高级用户，都能从中受益，获得更顺畅的网络浏览体验。