Pi-hole 技能

通过 Pi-hole v6 API 控制您的 Pi-hole DNS 广告拦截器。

配置

在 Clawdbot 配置中设置 Pi-hole API 配置：

skills:
  entries:
    pihole:
      apiUrl: "https://pi-hole.local/api"  # v6 API 路径
      apiToken: "your-app-password-here"       # 从 Pi-hole 管理界面获取
      insecure: false                          # 若使用自签名证书，请设为 true

或者，设置环境变量：

export PIHOLE_API_URL="https://pi-hole.local/api"
export PIHOLE_API_TOKEN="your-app-password-here"
export PIHOLE_INSECURE="false"

获取 API 凭据

1. 在 http://pi-hole.local/admin 打开 Pi-hole 管理界面
2. 导航至 Settings > API
3. 生成一个应用密码（app password）
4. 将该密码用作 apiToken

功能特性

状态

• 获取当前 Pi-hole 状态（启用/禁用）
• 查看统计信息：已拦截查询数、今日查询总数、当前被拦截域名数、活跃客户端数
• 查看最近的查询活动

控制

• 启用/禁用：开启或关闭 Pi-hole
• 禁用 5 分钟：临时关闭广告拦截，持续较短时间
• 自定义时长禁用：设定具体的禁用时长（单位：分钟）

拦截分析

• 检查被拦截域名：查看指定时间窗口内被拦截的域名
• 显示最常被拦截域名：列出被拦截频率最高的域名

使用示例

# 检查 Pi-hole 状态
"pihole status"

# 关闭广告拦截
"pihole off"

# 开启广告拦截
"pihole on"

# 临时禁用 5 分钟（适用于需要加载广告的网站）
"pihole disable 5m"

# 禁用 30 分钟
"pihole disable 30"

# 查看过去 30 分钟内被拦截的内容
"pihole blocked"

# 查看过去 10 分钟（600 秒）内被拦截的域名
"pihole blocked 600"

# 显示统计信息
"pihole stats"

API 接口端点（Pi-hole v6）

认证

POST /api/auth
Content-Type: application/json
{"password":"your-app-password"}

响应：
{
  "session": {
    "sid": "session-token-here",
    "validity": 1800
  }
}

状态

GET /api/dns/blocking
Headers: sid: 

响应：
{
  "blocking": "enabled" | "disabled",
  "timer": 30  // 若已设定定时启用，则返回距重新启用的剩余秒数
}

启用/禁用

POST /api/dns/blocking
Headers: sid: 
Content-Type: application/json

启用：
{"blocking":true}

禁用：
{"blocking":false}

带定时禁用（单位：秒）：
{"blocking":false,"timer":300}

统计信息

GET /api/stats/summary
Headers: sid: 

响应：
{
  "queries": {
    "total": 233512,
    "blocked": 23496,
    "percent_blocked": 10.06
  },
  "gravity": {
    "domains_being_blocked": 165606
  },
  "clients": {
    "active": 45
  }
}

查询记录

GET /api/queries?start=-
Headers: sid: 

响应：
{
  "queries": [
    {
      "domain": "example.com",
      "status": "GRAVITY",
      "time": 1768363900,
      "type": "A"
    }
  ]
}

v5 与 v6 API 差异

Pi-hole v6 引入了重大的 API 变更：

重要提示： 域名白名单功能在 v6 API 中已移除。您必须通过 Pi-hole 管理界面（Admin UI）手动添加白名单。

SSL 证书

生产环境（有效证书）

{
  "apiUrl": "https://pi-hole.example.com/api",
  "apiToken": "...",
  "insecure": false
}

自签名证书 / 本地证书

{
  "apiUrl": "https://pi-hole.local/api",
  "apiToken": "...",
  "insecure": true
}

insecure 标志会在 curl 命令中添加 -k 参数，以跳过证书验证。

安全说明

• 会话令牌（session token）有效期为 30 分钟（1800 秒）
• API 密码通过 JSON 请求体发送，而非 URL 参数
• 所有请求均设有 30 秒超时限制
• 密钥不会出现在进程列表中（通过环境变量传入）

故障排查

"认证失败"

• 确认 apiToken 与 Pi-hole 中生成的应用密码一致
• 验证 apiUrl 是否正确（结尾必须为 /api）
• 确保 Pi-hole 可从当前网络访问

"无法确定状态"

• 检查 API URL 是否可正常访问
• 若使用 HTTPS 且为自签名证书，请设置 insecure: true
• 确认 API 密码输入无误

网络错误

• 确保 clawdbot 所在机器可访问 Pi-hole
• 检查防火墙规则是否允许 API 访问
• 确认 URL 协议类型（http 还是 https）

依赖要求

• Pi-hole v6 或更高版本
• 已在 Pi-hole 管理界面中生成应用密码（app password）
• 具备对 Pi-hole API 的网络访问权限
• curl 和 jq（大多数 Unix 系统已预装）