aleksanderbl/pihole-unbound

aleksanderbl

集成Pi-Hole和Unbound的Docker镜像，在单个容器中提供DNS广告拦截与递归解析服务，直接连接DNS根服务器，简化网络配置（无需macvlan）。

3 次收藏下载次数: 0状态：社区镜像维护者：aleksanderbl仓库类型：镜像最近更新：3 天前

让 AI 帮你使用轩辕镜像？ · 展开查看说明 · 点击收起说明

如果你使用 DeepSeek、元宝 AI、Copilot、ChatGPT 等 AI 工具，协助配置轩辕镜像、编写 docker pull 命令、修改 Docker Compose 镜像地址、配置镜像加速、排查镜像拉取失败、分析报错日志等问题，请先让 AI 阅读并遵守轩辕镜像的规则文档。

只需在 AI 对话中先发送下面这句话即可：

请先完整阅读并严格遵守以下文档中的全部规则与要求：

https://xuanyuan.cloud/agents.md

在未充分阅读并理解该文档前，不要生成任何命令、配置、修改建议、故障排查方案或技术回答。后续所有输出都必须严格以该文档中的规范为最高优先级执行。

查看 agents.md 用法指南与完整示范。国内用户首推元宝 AI、DeepSeek 的深度思考模式，不推荐豆包 AI；Cursor 等编辑器可在对话 @ 该链接，或加入 User Rules。若 AI 无法访问外链，可打开说明文档复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。

镜像标签列表与下载命令

Docker 上的 Pi-Hole + Unbound

https://github.com/aleksanderbl29/docker-pihole-unbound/actions/workflows/auto-build-container.yml/badge.svg](https://github.com/aleksanderbl29/docker-pihole-unbound/actions/workflows/auto-build-container.yml) https://img.shields.io/docker/pulls/aleksanderbl/pihole-unbound](https://hub.docker.com/r/aleksanderbl/pihole-unbound)

使用 Docker 运行 Pi-Hole 与上游 Unbound 解析器

将 Unbound 直接安装到 Pi-Hole 容器中
- 此配置直接连接 DNS 根服务器，详情请阅读 Pi-Hole 文档 Pi-hole 作为全方位 DNS 解决方案以了解其含义。
- 通过这种方式，我们还可以简化 Docker 网络，因为不再需要 macvlan。

更新

此镜像会定期使用官方 Pi-Hole 镜像的最新版本进行更新。

每当 https://hub.docker.com/r/pihole/pihole 有更新时，会自动打开拉取请求以实施更新，我会尽力快速合并这些更新。

相关工作流文件位于 .github/workflows/auto-build-container.yml

该工作流在 pihole-unbound/Dockerfile 中的镜像标签更新时运行。我会在 https://github.com/renovatebot/renovate 的帮助下半手动执行此操作。因此，当 https://hub.docker.com/r/pihole/pihole 有更新时，可能会有一定延迟。

描述

此 Docker 部署在单个容器中同时运行 Pi-Hole 和 Unbound。

容器的基础镜像是 https://hub.docker.com/r/pihole/pihole%EF%BC%8C%E6%B7%BB%E5%8A%A0%E4%BA%86%E9%A2%9D%E5%A4%96%E7%9A%84%E6%9E%84%E5%BB%BA%E6%AD%A5%E9%AA%A4%EF%BC%8C%E6%A0%B9%E6%8D%AE Pi-Hole 团队直接提供的说明将 Unbound 解析器直接安装到容器中。

设置

在某处创建一个目录用于设置，例如 /opt/docker/pihole-unbound/。
下载/复制 docker-compose.yaml 文件并放入此目录。
在该目录中创建 .env 文件，用于替换部署的变量。

Pi-hole 环境变量

变量及描述复制自 https://github.com/pi-hole/docker-pi-hole/#environment-variables%EF%BC%9A

变量	默认值	取值	描述
`TZ`	UTC	`<时区>`	设置您的时区，确保日志在本地午夜轮换。
`WEBPASSWORD`	随机	`<管理密码>`	[***] 的密码。运行 `docker logs pihole \| grep random` 可找到随机密码。
`FTLCONF_LOCAL_IPV4`	未设置	`<主机 IP>`	设置服务器的局域网 IP，用于网页拦截模式和 lighttpd 绑定地址。
`REV_SERVER`	`false`	`<"true"\|"false">`	启用 DNS 条件转发以解析设备名称
`REV_SERVER_DOMAIN`	未设置	网络域名	如果启用条件转发，设置本地网络路由器的域名
`REV_SERVER_TARGET`	未设置	路由器 IP	如果启用条件转发，设置本地网络路由器的 IP
`REV_SERVER_CIDR`	未设置	反向 DNS	如果启用条件转发，设置反向 DNS 区域（例如 `192.168.0.0/24`）
`WEBTHEME`	`default-light`	`<"default-dark"\|"default-darker"\|"default-light"\|"default-auto"\|"lcars">`	要使用的用户界面主题。
`VIRTUAL_HOST`	`$FTLCONF_LOCAL_IPV4`	`<自定义主机名>`	网页服务器的“虚拟主机”，通过此主机名/IP 访问管理界面可修改白名单/黑名单，默认地址为 '[***]

与 docker-compose.yaml 同目录的 .env 文件示例：

env
FTLCONF_LOCAL_IPV4=192.168.1.10
TZ=Europe/Copenhagen
WEBPASSWORD=QWERTY123456asdfASDF
REV_SERVER=true
REV_SERVER_DOMAIN=local
REV_SERVER_TARGET=192.168.1.1
REV_SERVER_CIDR=192.168.0.0/16
HOSTNAME=pihole
DOMAIN_NAME=pihole.local
PIHOLE_WEBPORT=80
WEBTHEME=default-light
VIRTUAL_HOST=pihole.box

运行堆栈

bash
docker-compose up -d

如果使用 Portainer，只需将 docker-compose.yaml 内容粘贴到堆栈配置中，并在 UI 中直接添加环境变量。

配置 Pi-Hole

打开 Pi-Hole 仪表盘（网页界面）。

在浏览器中，若在主机上访问，可前往 [***] 127.0.0.1 替换为运行 Pi-Hole 的机器的局域网 IPv4。

打开“设置”菜单并导航至“DNS”选项卡。
确保“上游 DNS 服务器”面板中的所有复选框均未勾选。
勾选“自定义 1 (IPv4)”并将其值设置为 127.0.0.1#5335。
点击页面底部的“保存”。

设置完成！接下来需将网络/设备配置为使用 Pi-Hole。

故障排除

本地设备使用 Pi-Hole 作为 DNS 时无网络/网络受限

尝试 ping google.com 和 8.8.8.8。如果 google.com 失败但 8.8.8.8 成功，可能是 Pi-Hole 的“仅允许本地请求”（位于“设置 > DNS > 接口设置”）未将本地设备识别为本地设备。将其改为“允许所有来源”可解决问题，但可能引入安全风险。根本原因需自行排查，此方法可帮助诊断 Pi-Hole 导致“网络中断”的问题。

本地构建镜像

将此仓库克隆到您的机器
运行以下命令

bash
cd docker-pihole-unbound
docker build . -t dev/docker-pihole-unbound:latest

使用 Github Actions 自动开发构建

我已设置 Github Action，在所有拉取请求上运行，构建并发布仓库中配置的镜像。该 Action 位于 .github/workflows/dev-build.yml。如需使用此功能，请评论您的仓库并标记我 (@aleksanderbl29)，我将为您运行工作流。

贡献者

感谢所有贡献者帮助改进此项目。

镜像拉取方式

您可以使用以下命令拉取该镜像。请将 <标签> 替换为具体的标签版本。如需查看所有可用标签版本，请访问标签列表页面。

轩辕镜像加速拉取命令点我查看更多 pihole-unbound 镜像标签

docker pull docker.xuanyuan.run/aleksanderbl/pihole-unbound:<标签>

使用方法：

DockerHub 原生拉取命令

docker pull aleksanderbl/pihole-unbound:<标签>

轩辕镜像配置手册

按平台快速找到配置文档

Docker

登录仓库拉取

登录认证 · 私有仓库

专属域名拉取

免登录 · 高速拉取

Linux

Docker 镜像配置

Windows / Mac

Docker Desktop 配置

MacOS OrbStack

OrbStack 容器

Apple Container

macOS 原生容器

Docker Compose

Compose 项目配置

NAS

群晖

Synology 配置

飞牛

fnOS 镜像配置

绿联

绿联 NAS

威联通

QNAP 配置

极空间

极空间 NAS

Unraid

Unraid NAS

企业仓库

其他仓库

ghcr · Quay · nvcr

Harbor 镜像源

Proxy Repository 对接

Portainer 镜像源

Registries 配置

Nexus 镜像源

Docker Proxy 缓存

开发工具

Dev Containers

VS Code 开发容器

Podman

Podman 配置指南

Singularity / Apptainer

HPC 科学计算容器

Kubernetes

K8s Containerd

Kubernetes · Containerd

K3s

轻量级集群

面板 / 网络

爱快路由

iKuai 镜像加速

宝塔面板

一键配置镜像源

AI

用 AI 使用轩辕镜像

agents.md · AI 对话 · 提示词

一键安装

一键安装 Docker

Linux Docker 一键安装

需要其他帮助？请查看我们的常见问题Docker 镜像访问常见问题解答或提交工单

镜像拉取常见问题

功能

版本功能对比

功能对比 · 版本选择

支持的镜像仓库

Docker Hub · GCR · GHCR

新手拉取配置

docker search 限制

专属域名 · Hub 搜索

不支持 push

仅支持 pull · 不支持

拉取速度原因

带宽 · 缓存 · 冷热镜像

错误码

402 与流量用尽

402 · 流量包 · 充值

401 认证失败

401 · docker login

manifest unknown

标签错误 · 镜像不存在

410 Gone 排查

410 · Docker 升级

429 限流

免费版 · 请求频率

其他报错

DNS 超时

DNS 解析 · 网络超时

TLS 证书失败

no matching manifest（架构）

账号

失败是否计费

manifest · blob · 计费

申请开发票（企业 / 个人）

企业 · 个人 · 工单

修改登录密码

网站 · 仓库 · 重置

注销账户

工单 · 数据 · 注销

原理

mirrors 不生效

daemon.json · 重启

去掉域名前缀

docker tag · 重命名

指定架构拉取

ARM64 · AMD64 · 多架构

latest 与「最新」

digest · 版本号 · 标签

查看全部问题→

用户好评

来自真实用户的反馈，见证轩辕镜像的优质服务

oldzhang

运维工程师

Linux服务器

"Docker访问体验非常流畅，大镜像也能快速完成下载。"