# 软路由+Pi-hole+PassWall 全能网络架构配置手册

## 1. 架构总览与流量逻辑

本手册旨在指导如何配置一套集广告拦截、科学上网、精准分流于一体的家庭网络环境。该环境由 iKuai（主路由）、iStoreOS（旁路由/PassWall）以及 CentOS 上的 Pi-hole（DNS 过滤）共同组成。

### 1.1 核心设备角色分配

| 设备名称 | IP 地址 | 核心职责 |
| :--- | :--- | :--- |
| **主路由 (iKuai)** | 10.10.10.253 | 拨号、流量出口、DHCP 分发、内网管理 |
| **旁路由 (iStoreOS)** | 10.10.10.252 | PassWall 科学上网、插件运行、分流处理 |
| **DNS 控制台 (Pi-hole)** | 10.10.10.14 | 全屋广告过滤、内网域名解析记录、DNS 查询审计 |

### 1.2 流量闭环逻辑

1.  **DNS 解析路径**：设备 -> **Pi-hole**（执行过滤） -> **PassWall**（执行分流） -> 运营商 DNS（国内）/ 远程 DNS（国外）。
2.  **网络数据路径**：设备 -> **iStoreOS**（旁路由网关） -> **iKuai**（主路由出口） -> 互联网。

---

## 2. 核心组件精细化配置

### 2.1 Pi-hole (Docker 部署)

由于 Pi-hole 运行在 Docker 容器中，必须处理跨网段权限问题，否则会导致设备无法解析 DNS 进而断网。

* **权限开启**：
    * 进入 `Settings` -> `DNS`。
    * 在 `Interface settings` 中勾选 **"Permit all origins"**。
    * *注：此操作允许来自局域网（10.10.10.x）的请求穿过 Docker 网桥被 Pi-hole 处理。*
* **上游转发**：
    * 在 `Upstream DNS Servers` 中只勾选或填写 **10.10.10.252**。
    * 确保所有经过过滤的请求都交给旁路由进行分流。

### 2.2 iKuai (主路由 DHCP 设置)

主路由负责告诉终端设备该去找谁。

* **DHCP 地址池设置**：
    * **网关**：10.10.10.252（让所有流量经过旁路由插件处理）。
    * **首选 DNS**：10.10.10.14（让所有 DNS 请求进入 Pi-hole 过滤）。
    * **备用 DNS**：**留空**（防止设备通过备用 DNS 绕过拦截）。

### 2.3 iStoreOS (PassWall 插件设置)

* **DNS 重定向**：建议开启。若追求 Pi-hole 后台统计精确到具体终端 IP，则可尝试关闭，但前提是 Pi-hole 的权限已按 2.1 节配置妥当。
* **过滤模式**：建议使用 `通过 UDP 请求 DNS` 以获得更快的响应速度。
* **远程 DNS**：推荐使用 `1.1.1.1` 或 `8.8.8.8`。

---

## 3. 多场景设备配置方案

不同的终端设备可以根据需求进行手动调整：

### 3.1 方案对比表

| 设备类型 | 配置方式 | 网关 (Gateway) | DNS (DNS Server) | 最终效果 |
| :--- | :--- | :--- | :--- | :--- |
| **普通终端 (手机/电视)** | DHCP (自动) | 10.10.10.252 | 10.10.10.14 | 自动去广告 + 科学上网 |
| **专业设备 (PC/NAS)** | 静态 IP (手动) | 10.10.10.252 | 10.10.10.14 | 确保在 Pi-hole 统计中永久固定 |
| **游戏主机 (PS5/Switch)** | 静态 IP (手动) | **10.10.10.253** | 223.5.5.5 | **直连主路由**，最低延迟，不经过插件 |

### 3.2 针对特定设备的调整方法

对于追求极致游戏延迟或不需要经过旁路由的设备，可以在设备网络设置中手动将网关修改为 `10.10.10.253`，DNS 修改为阿里 DNS (`223.5.5.5`)。

---

## 4. 故障排查与避坑指南 (FAQ)

* **Q: 为什么配置后完全无法上网？**
    * **检查 Pi-hole**：确认容器是否正常运行，且 `Permit all origins` 已勾选。
    * **检查 PassWall**：确认节点是否通畅。
* **Q: 为什么能上网但没有拦截广告？**
    * **缓存问题**：请清理终端设备的 DNS 缓存（如电脑执行 `ipconfig /flushdns`）。
    * **IPv6 干扰**：如果主路由开启了 IPv6，设备可能会通过 IPv6 DNS 绕过 Pi-hole。建议关闭主路由的 IPv6 DNS 指派。
* **Q: Pi-hole 后台看到的客户端全是 10.10.10.252？**
    * 这是因为 PassWall 开启了 DNS 重定向或做了 SNAT 伪装。如果想看到真实设备 IP，需在 PassWall 或防火墙规则中进行精细调整。

---

## 5. 常用维护命令

在 CentOS 宿主机中，你可以使用以下命令管理 Pi-hole 容器：

```bash
# 查看容器状态
docker ps | grep pihole

# 重启 Pi-hole 容器
docker restart <container_id>

# 查看 Pi-hole 实时日志
docker logs -f <container_id>
```

---
*本手册版本：V1.0*
*生成日期：2026-04-17*