Pi-hole Control

# Pi-hole Skill

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

## 设置

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

```yaml skills: entries: pihole: apiUrl: "https://pi-hole.local/api" # v6 API path apiToken: "your-app-password-here" # Get from Pi-hole Admin insecure: false # Set to true for self-signed certs ```

或者，设置环境变量： ```bash 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 分钟**：在短时间内临时禁用广告拦截 - **自定义时长禁用**：设置特定的禁用时间（以分钟为单位）

### 拦截分析 - **查看被拦截域名**：查看在特定时间窗口内被拦截的域名 - **显示最常被拦截**：最常被拦截的域名

## 使用示例

``` # Check Pi-hole status "pihole status"

# Turn off ad blocking "pihole off"

# Turn on ad blocking "pihole on"

# Disable for 5 minutes (for a site that needs ads) "pihole disable 5m"

# Disable for 30 minutes "pihole disable 30"

# See what was blocked in the last 30 minutes "pihole blocked"

# See blocked domains in last 10 minutes (600 seconds) "pihole blocked 600"

# Show statistics "pihole stats" ```

## API 端点 (Pi-hole v6)

### 身份验证 ``` POST /api/auth Content-Type: application/json {"password":"your-app-password"}

Response: { "session": { "sid": "session-token-here", "validity": 1800 } } ```

### 状态 ``` GET /api/dns/blocking Headers: sid: <session-token>

Response: { "blocking": "enabled" | "disabled", "timer": 30 // seconds until re-enable (if disabled with timer) } ```

### 启用/禁用 ``` POST /api/dns/blocking Headers: sid: <session-token> Content-Type: application/json

Enable: {"blocking":true}

Disable: {"blocking":false}

Disable with timer (seconds): {"blocking":false,"timer":300} ```

### 统计数据 ``` GET /api/stats/summary Headers: sid: <session-token>

Response: { "queries": { "total": 233512, "blocked": 23496, "percent_blocked": 10.06 }, "gravity": { "domains_being_blocked": 165606 }, "clients": { "active": 45 } } ```

### 查询 ``` GET /api/queries?start=-<seconds> Headers: sid: <session-token>

Response: { "queries": [ { "domain": "example.com", "status": "GRAVITY", "time": 1768363900, "type": "A" } ] } ```

## v5 与 v6 API 变更

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

| 功能 | v5 API | v6 API | |---------|----------|----------| | 基础 URL | `/admin/api.php` | `/api` | | 身份验证 | URL/Header 中的 Token | 基于会话 | | 状态 | `?status` | `/api/dns/blocking` | | 统计数据 | `?summaryRaw` | `/api/stats/summary` | | 查询 | `?recentBlocked` | `/api/queries` | | 白名单 | 通过 API 支持 | **无法通过 API 使用** |

**重要提示：** 域名白名单不再通过 v6 API 提供。您必须通过 Pi-hole 管理界面将域名加入白名单。

## SSL 证书

### 生产环境 (有效证书) ```yaml { "apiUrl": "https://pi-hole.example.com/api", "apiToken": "...", "insecure": false } ```

### 自签名/本地证书 ```yaml { "apiUrl": "https://pi-hole.local/api", "apiToken": "...", "insecure": true } ```

`insecure` 标志会为 curl 添加 `-k` 选项，以绕过证书验证。

## 安全说明

- 会话令牌在 30 分钟（1800 秒）后过期 - API 密码在 JSON 主体中发送，而非 URL - 所有请求均有 30 秒超时 - 令牌在进程列表中不可见（通过环境变量传递）

## 故障排除

### "Failed to authenticate"（身份验证失败） - 检查 `apiToken` 是否与您的 Pi-hole 应用密码匹配 - 验证 `apiUrl` 是否正确（必须以 `/api` 结尾） - 确保 Pi-hole 可以从您的网络访问

### "Could not determine status"（无法确定状态） - 检查 API URL 是否可达 - 如果使用带有自签名证书的 HTTPS，请设置 `insecure: true` - 验证 API 密码是否正确

### 网络错误 - 确保 clawdbot 的主机可以访问 Pi-hole - 检查防火墙规则是否允许 API 访问 - 验证 URL 协议（http 与 https）

## 系统要求

- Pi-hole v6 或更高版本 - 在 Pi-hole 管理界面生成的应用密码 - 对 Pi-hole API 的网络访问权限 - `curl`、`jq`（大多数 Unix 系统上已安装）