2025必看：docker-pi-hole v6重大更新！从2024.07.0迁移避坑指南

【免费下载链接】docker-pi-hole Pi-hole in a docker container 项目地址: https://gitcode.com/gh_mirrors/do/docker-pi-hole

如果你还在手动升级Docker容器导致Pi-hole配置丢失？或者被v6版本的环境变量变更搞得晕头转向？本文将系统梳理docker-pi-hole从2024.07.0及更早版本迁移到2025.02.0+的完整流程，包含兼容性处理、配置迁移和常见问题解决方案。读完本文你将能够：掌握v6版本核心变更点、完成现有配置无痛迁移、解决90%的升级后功能异常问题。

版本变更核心要点

为什么必须迁移到v6？

docker-pi-hole v6基于Pi-hole v6重构，带来三大核心改进：更高效的DNS解析引擎、全新的配置系统和增强的容器安全性。但从2024.07.0及更早版本升级将面临不可逆的配置变更，必须提前做好数据备份。

[!CAUTION] 用v6镜像替换任何v5镜像（2024.07.0及更早版本）将导致配置文件更新，这些更改无法回滚。升级前务必备份./etc-pihole/目录。

关键变更清单

变更类型	v5版本	v6版本	影响范围
环境变量	WEBPASSWORD	FTLCONF_webserver_api_password	所有使用默认密码配置的用户
配置文件	/etc/pihole/pihole-FTL.conf	/etc/pihole/pihole.toml	自定义DNS设置的用户
数据卷	强制要求/etc-dnsmasq.d	默认不启用，需显式配置	使用自定义dnsmasq规则的用户
权限系统	依赖--privileged标志	需显式添加CAP capabilities	所有使用DHCP功能的用户

迁移准备工作

环境检查清单

在开始迁移前，请确认当前环境是否满足以下条件：

1. Docker Engine版本≥20.10.0，Docker Compose版本≥v2.0.0
2. 已停止并备份现有容器：

   docker stop pihole
   docker cp pihole:/etc/pihole ./pihole-backup
   

3. 已拉取最新v6镜像：

   docker pull pihole/pihole:latest
   

必备文件备份

文件路径	用途	备份方式
./etc-pihole/	核心配置和数据库	cp -r ./etc-pihole ./etc-pihole-backup
./etc-dnsmasq.d/	自定义DNS规则	cp -r ./etc-dnsmasq.d ./etc-dnsmasq.d-backup
docker-compose.yml	容器编排配置	cp docker-compose.yml docker-compose-v5.yml

配置文件迁移详解

环境变量转换

v6版本采用全新的环境变量命名规范，所有配置项统一前缀为FTLCONF_，并使用下划线代替点分隔符。以下是常用变量的转换对照表：

v5环境变量	v6对应变量	示例值
WEBPASSWORD	FTLCONF_webserver_api_password	correct horse battery staple
DNS1/DNS2	FTLCONF_dns_upstreams	114.114.114.114;223.5.5.5
DNSMASQ_LISTENING	FTLCONF_dns_listeningMode	all

完整的环境变量映射请参考官方文档：Docker升级指南

docker-compose.yml重构

以下是从v5到v6的docker-compose配置文件转换示例：

v5版本配置片段：

services:
  pihole:
    image: pihole/pihole:2024.07.0
    environment:
      - WEBPASSWORD=mysecretpassword
      - DNS1=8.8.8.8
      - DNS2=8.8.4.4
    volumes:
      - ./etc-pihole:/etc/pihole
      - ./etc-dnsmasq.d:/etc/dnsmasq.d
    cap_add:
      - NET_ADMIN

v6版本配置片段：

services:
  pihole:
    image: pihole/pihole:latest  # 自动拉取v6版本
    environment:
      - FTLCONF_webserver_api_password=mysecretpassword
      - FTLCONF_dns_upstreams=8.8.8.8;8.8.4.4
      - FTLCONF_dns_listeningMode=all
      - FTLCONF_misc_etc_dnsmasq_d=true  # 仅当需要加载自定义dnsmasq规则时添加
    volumes:
      - ./etc-pihole:/etc/pihole
      # 仅当需要加载自定义dnsmasq规则时保留以下行
      - ./etc-dnsmasq.d:/etc/dnsmasq.d
    cap_add:
      - NET_ADMIN  # DHCP功能必需
      - SYS_NICE   # 可选，提升FTL进程优先级

特殊场景处理

1. 使用DHCP服务的用户

若在v5中启用了DHCP功能，v6配置需添加额外的capabilities和端口映射：

ports:
  - "67:67/udp"  # DHCP服务端口
cap_add:
  - NET_ADMIN    # 必需，用于DHCP地址分配
  - NET_RAW      # 必需，处理DHCPv6请求

2. 使用自定义dnsmasq规则的用户

v6默认不再自动加载/etc/dnsmasq.d/目录下的配置文件，需通过环境变量显式启用：

environment:
  - FTLCONF_misc_etc_dnsmasq_d=true
volumes:
  - ./etc-dnsmasq.d:/etc/dnsmasq.d

迁移操作步骤

标准迁移流程

1. 停止并移除旧容器：

   docker rm -f pihole
   

2. 创建新的docker-compose.yml： 基于examples/docker-compose-caddy-proxy.yml模板，更新环境变量和卷配置。

3. 启动新容器：

   docker compose up -d
   

4. 验证迁移结果：

   # 检查容器状态
   docker ps | grep pihole
   
   # 验证DNS解析功能
   dig @localhost pi.hole
   
   # 检查Web界面是否可访问
   curl -I http://localhost/admin
   

常见问题排查

问题1：容器启动后立即退出

可能原因：环境变量配置错误，特别是FTLCONF_webserver_api_password未设置或格式不正确。

解决方案：检查日志获取详细错误信息：

docker logs pihole

确保密码只包含字母、数字和特殊字符（!@#$%^&*等），长度至少8位。

问题2：DNS解析失败，Web界面无法访问

可能原因：端口冲突或网络模式配置错误。

解决方案：

• 检查53端口是否被其他服务占用：ss -tulpn | grep :53
• 确认FTLCONF_dns_listeningMode设置为all（桥接网络模式）或local（host网络模式）

问题3：DHCP服务无法分配IP地址

可能原因：缺少必要的capabilities或网络模式不正确。

解决方案：确保配置中包含：

cap_add:
  - NET_ADMIN
  - NET_RAW
network_mode: "host"  # 推荐DHCP场景使用host网络

迁移后优化建议

性能调优配置

对于高负载环境，建议添加以下优化配置到pihole.toml：

[dns]
cache_size = 100000
dns_forward_max = 500

[webserver]
http_threads = 4

安全加固措施

1. 限制Web界面访问来源： 在Caddyfile中配置IP白名单：

   pi.hole {
     @allowed {
       remote_ip 192.168.1.0/24 10.0.0.0/8
     }
     reverse_proxy @allowed pihole:80
   }
   

2. 使用Docker Secrets管理密码（适用于Swarm环境）：

   environment:
     - WEBPASSWORD_FILE=/run/secrets/pihole_password
   secrets:
     - pihole_password
   

迁移验证清单

完成迁移后，请通过以下检查确认系统功能正常：

•  Web管理界面可访问（http://pi.hole/admin）
•  仪表盘显示广告拦截统计数据
•  客户端设备能正常解析DNS
•  自定义黑名单/白名单规则生效
•  DHCP服务（如使用）能正常分配IP
•  系统日志无持续错误（src/start.sh脚本输出）

参考资源

• 官方迁移文档：Docker升级指南
• 环境变量配置参考：src/start.sh
• 示例配置文件：examples/
• 故障排除指南：test/TESTING.md

通过以上步骤，你已成功将docker-pi-hole从v5迁移到v6版本。如有其他问题，请查阅项目README.md或提交issue到GitHub仓库。

【免费下载链接】docker-pi-hole Pi-hole in a docker container 项目地址: https://gitcode.com/gh_mirrors/do/docker-pi-hole