企业官网建设流程全解析

• 云原生
• 运维
• 后端
• 容器编排

Nextcloud All-in-One（AIO）官方仓库通过社区容器机制提供开箱即用的 Pi-hole 广告拦截器集成：只需在 AIO 界面勾选启用，系统便会自动拉取并配置pihole/pihole容器，同时把 Web 管理面板、DNS 端口 53 和备份流程一并打通。读完本文，你将掌握 Pi-hole 容器在 AIO 中的启用方法、pi-hole.json各项配置参数的底层含义、端口冲突排查技巧，以及如何把整条家庭网络的 DNS 查询交给 Pi-hole 接管。

社区容器与 Pi-hole 的定位

在 community-containers/readme.md 中，AIO 官方将社区容器定义为"专为 AIO 构建、用于快速扩展额外功能"的容器集合。从 v11 版本开始，社区容器的启停管理已完全集成到 AIO 的 Web 界面（界面最下方的 Community Containers 区块）。Pi-hole 属于其中 "Security & Network"（安全与网络）类别的社区容器，在界面中显示名为Pi-hole。

与内置容器不同，社区容器由社区维护（Pi-hole 的维护者为 szaimen），AIO 官方在 community-containers.twig 中明确提示：启用前必须逐一阅读对应容器的文档，因为部分容器彼此不兼容，盲目全开可能破坏整个 AIO 栈的启动。Pi-hole 正是这类"有兼容性约束"的典型代表。

如何将 Pi-hole 添加到 AIO 栈

通过 AIO 界面启用（推荐）

1. 登录 AIO 管理界面，滚动到底部的Community Containers区块；
2. 在容器列表中勾选Pi-hole（勾选前请务必先阅读其文档）；
3. 点击Save changes保存。注意：界面仅在容器全部停止时允许修改选项，且社区容器的修改不会自动保存，必须手动点击保存按钮；
4. 回到主界面启动全部容器，AIO 会自动完成pihole/pihole镜像的拉取与容器编排。

界面背后，AIO 的配置存储依赖 ConfigurationManager.php 中的aio_community_containers配置项（以空格分隔的容器标识列表）。被启用的社区容器会在启动编排时被动态并入容器定义。

从仓库定位定义文件

Pi-hole 容器的一切行为都声明在 community-containers/pi-hole/pi-hole.json 中，这是 AIO 运行时读取的唯一数据源；community-containers/pi-hole/readme.md 则提供了该容器的使用说明与注意事项。如果你希望为其他社区容器编写定义，可参考 containers-schema.json 中的 JSON Schema 校验规则，以及内置容器的完整定义 containers.json。

深入解析 pi-hole.json 容器定义

pi-hole.json采用aio_services_v1结构声明了一个名为nextcloud-aio-pihole的服务。逐字段拆解如下：

端口映射：TCP/UDP 53 与 8573

"ports": [ { "ip_binding": "", "port_number": "53", "protocol": "tcp" }, { "ip_binding": "", "port_number": "53", "protocol": "udp" }, { "ip_binding": "", "port_number": "8573", "protocol": "tcp" } ]

• 53/tcp 与 53/udp：DNS 服务端口，ip_binding为空表示绑定主机所有网卡，这正是"仅限家庭网络"警告的技术根源——端口 53 一旦暴露到公网，Pi-hole 就会被任何网络上的设备当作公开 DNS 递归服务器使用；
• 8573/tcp：Web 管理面板端口，与internal_port对应。

AIO 在运行时通过 ContainerDefinitionFetcher.php 将 ports 字段解析为ContainerPorts集合，再交由 Docker 编排创建端口绑定。

环境变量：自动配置的四个关键项

"environment": [ "TZ=%TIMEZONE%", "FTLCONF_webserver_api_password=%PIHOLE_WEBPASSWORD%", "FTLCONF_dns_listeningMode=all", "FTLCONF_webserver_port=8573" ]

• TZ=%TIMEZONE%：时区由 AIO 全局配置注入（占位符替换机制）；
• FTLCONF_webserver_api_password=%PIHOLE_WEBPASSWORD%：管理面板的 API 密码，由 AIO 自动生成；
• FTLCONF_dns_listeningMode=all：让 DNS 服务监听所有网络接口（家庭局域网内各设备均可查询）；
• FTLCONF_webserver_port=8573：将 Pi-hole 的 Web 服务固定在 8573 端口，与端口映射保持一致。

这些%大写%占位符会在容器启动时由 AIO 运行时解析，其机制与 AioVariables.php 及 ContainerEnvironmentVariables.php 中的变量处理逻辑一致。

数据卷与备份集成

"volumes": [ { "source": "nextcloud_aio_pihole", "destination": "/etc/pihole", "writeable": true }, { "source": "nextcloud_aio_pihole_dnsmasq", "destination": "/etc/dnsmasq.d", "writeable": true } ], "backup_volumes": [ "nextcloud_aio_pihole", "nextcloud_aio_pihole_dnsmasq" ]

• nextcloud_aio_pihole挂载到/etc/pihole：存放 Pi-hole 的核心配置（广告列表、白名单、本地 DNS 记录等）；
• nextcloud_aio_pihole_dnsmasq挂载到/etc/dnsmasq.d：存放 dnsmasq 扩展配置；
• backup_volumes显式声明这两个卷自动纳入 AIO 的备份方案——这正是原文档强调"Pi-hole 数据会自动包含在 AIO 备份中"的底层实现依据。

密码的秘密管理机制

"ui_secret": "PIHOLE_WEBPASSWORD", "secrets": [ "PIHOLE_WEBPASSWORD" ]

PIHOLE_WEBPASSWORD是 Pi-hole 管理员的随机密码。AIO 在解析容器定义时（见 ContainerDefinitionFetcher.php）会把secrets中的每个密钥注册进配置管理器（ConfigurationManager.php 的registerSecret），并在首次使用时生成随机值；ui_secret则将该密钥关联到容器 Web 界面，使 AIO 能在容器旁显示这个管理密码。因此你无需手动设置密码，登录 Pi-hole 面板时直接查看 AIO 界面中该容器旁展示的 admin key 即可。

部署前必须确认的约束与冲突

原文档用多条 Notes 划定了 Pi-hole 容器的使用边界，这些约束全部可以映射到上面的容器定义中：

1. 只允许运行在家庭网络，禁止部署在公网 VPS

由于ip_binding为空、端口 53 直接绑定全部网卡，一旦部署在公网服务器上，Pi-hole 就会成为任何人都可访问的开放 DNS 解析器，存在被滥用为 DNS 放大攻击源的风险。因此该容器只适用于路由器背后的家庭局域网。

2. 与 dnsmasq 社区容器不兼容

Pi-hole 与 dnsmasq 社区容器 都需要占用主机端口 53（dnsmasq 的定义见 dnsmasq.json，其internal_port为host），两者同时启用必然导致端口冲突、容器无法启动。同一时间只能启用其中一个。

3. 确保主机 53 端口空闲

启用前先执行以下命令确认没有其他 DNS 服务占用端口：

sudo netstat -tulpn | grep 53

如果输出显示已有进程监听 53 端口（例如系统自带的 systemd-resolved 或已运行的 dnsmasq），必须先停止或禁用该服务，否则 Pi-hole 容器将无法绑定端口而启动失败。

4. DHCP 功能已被禁用

Pi-hole 自带的 DHCP 服务器功能在该容器中不会启用，避免与家庭路由器或网络上既有 DHCP 服务产生冲突。需要分配 IP 时请继续使用路由器自身的 DHCP。

部署后的三步接线：让设备真正用上 Pi-hole

容器启动后，按照原文档的指引完成以下配置即可让整条家庭网络生效：

第一步：登录管理面板完成初始化配置

在浏览器中访问：

http://ip.address.of.this.server:8573/admin

用 AIO 界面中该容器旁边显示的 admin key 登录。在这里你可以配置 Pi-hole 的广告拦截策略、添加本地 DNS 记录（例如把内部服务的域名解析到局域网 IP）。

第二步：配置路由器，让客户端走 Pi-hole 解析

进入家庭路由器的管理界面，把 DHCP 下发的 DNS 服务器地址改为运行 AIO 的那台服务器 IP（即 Pi-hole 容器的宿主地址）。这样局域网内所有设备都会自动向 Pi-hole 发起 DNS 查询，实现全网络广告拦截。

第三步（可选）：让 Docker 守护进程也使用 Pi-hole

编辑/etc/docker/daemon.json，加入 DNS 配置：

{ "dns": [ "ip.address.of.this.server", "8.8.8.8" ] }

保存后重启 Docker 服务（sudo systemctl restart docker）即可生效。这样 AIO 所在主机上的其他容器在解析域名时，也会优先通过 Pi-hole 完成查询，保证包括 Nextcloud 自身在内的容器流量同样经过广告过滤。8.8.8.8作为兜底上游，避免 Pi-hole 出现故障时容器完全无法解析。

移除 Pi-hole 容器与清理残留数据

当不再需要 Pi-hole 时，可以直接在 AIO 界面的 Community Containers 区块取消勾选并保存，然后停止并移除容器。若希望彻底清理服务器上的残留，按 community-containers/readme.md 的指引依次执行：

# 1. 删除容器实例（容器名按实际调整） sudo docker rm nextcloud-aio-pihole # 2. 清理不再使用的镜像 sudo docker image prune -a # 3. 查看并删除对应的持久化数据卷 sudo docker volume ls sudo docker volume rm nextcloud_aio_pihole nextcloud_aio_pihole_dnsmasq

执行第 3 步前务必确认卷名确实对应 Pi-hole（即nextcloud_aio_pihole与nextcloud_aio_pihole_dnsmasq），因为删除数据卷会永久丢失其内的 Pi-hole 配置与统计历史。如果没有服务器的 CLI 访问权限，也可以借助 container-management 社区容器在 Web 会话中执行这些 Docker 命令。

容器定义在 AIO 运行时的加载原理

从源码层面看，Pi-hole 之所以能"即勾即用"，依赖的是 ContainerDefinitionFetcher.php 的合并机制：运行时根据aio_community_containers配置，逐一读取community-containers/<名称>/<名称>.json，并通过array_merge_recursive将其与内置的containers.json定义合并，随后统一解析端口、卷、环境变量、依赖与密钥。因此，任何社区容器（包括 Pi-hole）的启用、启动编排、健康检查与备份，走的都是与内置容器完全相同的代码路径——这也解释了为什么 Pi-hole 的数据能够无缝融入 AIO 的备份方案。

需要留意的是，该合并逻辑同样会校验容器间的依赖关系：当某个已启用的社区容器依赖了未启用的其他社区容器时，相关依赖会被跳过（ContainerDefinitionFetcher.php）。Pi-hole 本身未声明depends_on，它只依赖宿主机的 53 端口可用，因此部署成败的关键仍在于端口冲突的排查。

小结

Pi-hole 社区容器为 Nextcloud All-in-One 用户提供了"一行勾选、全自动配置"的广告拦截方案：AIO 负责镜像拉取、端口绑定、密码生成与数据备份，你只需要完成路由器与 Docker 守护进程的 DNS 指向即可全网络生效。牢记三条红线——仅限家庭网络、不与 dnsmasq 同开、启用前检查 53 端口占用——就能稳定运行这套 DNS 广告拦截体系。

• 云原生
• 运维
• 后端
• 容器编排