Pi-hole Gravity数据库模板解析：理解广告过滤系统的核心架构

前言

Pi-hole作为一款优秀的网络广告拦截工具，其核心功能依赖于名为"Gravity"的数据库系统。本文将深入解析Gravity数据库模板的结构设计，帮助用户理解Pi-hole如何高效管理广告过滤规则、白名单、黑名单等关键数据。

Gravity数据库概述

Gravity数据库是Pi-hole的核心组件，采用SQLite数据库引擎实现。它负责存储和管理以下关键信息：

• 广告域名列表
• 白名单/黑名单规则
• 客户端分组配置
• 广告列表源信息
• 正则表达式过滤规则

核心表结构解析

1. 分组管理表(group)

分组系统是Pi-hole实现精细化控制的基础：

CREATE TABLE "group"
(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    enabled BOOLEAN NOT NULL DEFAULT 1,
    name TEXT UNIQUE NOT NULL,
    date_added INTEGER NOT NULL DEFAULT (cast(strftime('%s', 'now') as int)),
    date_modified INTEGER NOT NULL DEFAULT (cast(strftime('%s', 'now') as int)),
    description TEXT
);

• 系统默认创建ID为0的"Default"组
• 支持启用/禁用状态控制
• 记录创建和修改时间戳
• 提供描述字段用于备注

2. 域名列表表(domainlist)

这是管理白名单和黑名单的核心表：

CREATE TABLE domainlist
(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    type INTEGER NOT NULL DEFAULT 0,
    domain TEXT NOT NULL,
    enabled BOOLEAN NOT NULL DEFAULT 1,
    date_added INTEGER NOT NULL DEFAULT (cast(strftime('%s', 'now') as int)),
    date_modified INTEGER NOT NULL DEFAULT (cast(strftime('%s', 'now') as int)),
    comment TEXT,
    UNIQUE(domain, type)
);

• type字段区分规则类型：
  • 0: 白名单
  • 1: 黑名单
  • 2: 正则表达式白名单
  • 3: 正则表达式黑名单
• 域名和类型组合必须唯一
• 支持添加备注信息

3. 广告列表表(adlist)

管理外部广告列表源的核心表：

CREATE TABLE adlist
(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    address TEXT NOT NULL,
    enabled BOOLEAN NOT NULL DEFAULT 1,
    date_added INTEGER NOT NULL DEFAULT (cast(strftime('%s', 'now') as int)),
    date_modified INTEGER NOT NULL DEFAULT (cast(strftime('%s', 'now') as int)),
    comment TEXT,
    date_updated INTEGER,
    number INTEGER NOT NULL DEFAULT 0,
    invalid_domains INTEGER NOT NULL DEFAULT 0,
    status INTEGER NOT NULL DEFAULT 0,
    abp_entries INTEGER NOT NULL DEFAULT 0,
    type INTEGER NOT NULL DEFAULT 0,
    UNIQUE(address, type)
);

• 记录广告列表源的URL地址
• 跟踪列表更新状态和时间
• 统计有效/无效域名数量
• 支持ABP(Adblock Plus)格式条目统计

4. 关联关系表

Pi-hole通过多个关联表实现复杂的分组管理：

• adlist_by_group: 广告列表与分组的关联
• domainlist_by_group: 域名列表与分组的关联
• client_by_group: 客户端与分组的关联

这些关联表实现了多对多关系，允许一个资源属于多个组。

视图系统设计

Pi-hole创建了多个视图简化数据查询：

1. 过滤规则视图：

   • vw_whitelist: 有效白名单视图
   • vw_blacklist: 有效黑名单视图
   • vw_regex_whitelist: 正则白名单视图
   • vw_regex_blacklist: 正则黑名单视图

2. 广告过滤视图：

   • vw_gravity: 有效广告域名视图
   • vw_antigravity: 特殊处理的反广告域名视图

3. 广告列表视图：

   • vw_adlist: 有效广告列表源视图

这些视图自动过滤已禁用的条目，提供干净的数据访问接口。

触发器机制

数据库设计了完善的触发器系统维护数据完整性：

1. 自动更新时间戳：

   • 当广告列表、客户端或域名列表更新时，自动更新修改时间

2. 自动关联默认组：

   • 新添加的域名、客户端或广告列表自动关联到默认组

3. 级联删除处理：

   • 删除主表记录时自动清理关联表中的对应关系

4. 默认组保护：

   • 确保默认组(0)始终存在，防止意外删除

数据库版本管理

info表存储了关键的数据库元信息：

CREATE TABLE info
(
    property TEXT PRIMARY KEY,
    value TEXT NOT NULL
);

INSERT INTO "info" VALUES('version','19');
INSERT INTO "info" VALUES('gravity_restored','false');

• version: 数据库结构版本
• gravity_restored: 标识是否从备份恢复

实际应用建议

1. 自定义过滤规则：

   • 通过domainlist表添加自定义白名单/黑名单
   • 合理使用正则表达式类型实现复杂匹配

2. 分组管理策略：

   • 为不同设备/用户创建独立分组
   • 通过关联表实现灵活的规则分配

3. 广告列表维护：

   • 定期检查adlist表中的更新状态
   • 关注无效域名数量，优化广告列表源

4. 性能优化：

   • 利用视图系统查询有效数据
   • 避免直接操作基础表

总结

Pi-hole的Gravity数据库设计体现了精良的架构思想，通过合理的表结构、完善的关联关系和自动化触发器，实现了高效稳定的广告过滤管理。理解这套数据库结构有助于用户更好地定制和管理自己的Pi-hole实例，实现更精准的广告拦截效果。