Docker Pi-hole项目WEB_PORT环境变量变更解析

背景介绍

Docker Pi-hole是一个基于Docker容器技术部署的Pi-hole网络广告拦截解决方案。在2025年2月的版本更新中，项目对部分环境变量命名进行了调整，其中WEB_PORT变量的变更影响了一些用户的现有配置。

关键变更内容

在Docker Pi-hole 2025.02.1版本中，项目团队对环境变量的命名规范进行了统一调整。原先用于指定Web管理界面端口的WEB_PORT环境变量已被弃用，取而代之的是新的标准化变量名FTLCONF_webserver_port。

技术影响分析

这一变更主要影响以下几类用户场景：

1. 使用docker run命令直接部署容器的用户
2. 使用docker-compose.yml文件配置部署的用户
3. 通过编排工具(如Kubernetes)管理Pi-hole实例的用户

对于已经使用WEB_PORT变量配置自定义端口的用户，升级到新版本后会出现Web界面默认监听8080端口的情况，而非之前配置的端口。

解决方案

用户需要将现有配置中的WEB_PORT变量替换为FTLCONF_webserver_port。以下是不同部署方式下的修改示例：

docker run命令方式：

# 旧命令
docker run -e WEB_PORT=8083 ...

# 新命令
docker run -e FTLCONF_webserver_port=8083 ...

docker-compose.yml方式：

# 旧配置
environment:
  - WEB_PORT=8083

# 新配置  
environment:
  - FTLCONF_webserver_port=8083

变更背后的技术考量

这一变量命名的调整主要是为了：

1. 统一环境变量命名规范，所有FTL相关配置都采用FTLCONF_前缀
2. 提高配置项的可读性和一致性
3. 为未来可能的配置扩展预留空间

最佳实践建议

1. 在升级前检查并备份现有配置
2. 更新自动化部署脚本中的变量名称
3. 考虑在过渡期同时设置新旧两个变量以确保兼容性
4. 定期查阅项目文档了解最新配置要求

总结

Docker Pi-hole项目对环境变量的标准化调整体现了项目维护的规范性。虽然这类变更可能带来短期的适配工作，但从长期来看有利于项目的可维护性和用户体验的一致性。建议用户关注项目的更新日志，及时调整自己的部署配置以适应这些改进。