Docker-PiHole升级v6版本时数据库迁移故障分析与解决

问题现象

在Docker环境下运行的PiHole从较早版本升级到v6.0时，系统日志中出现关键错误信息：

SQLite3: duplicate column name: additional_info
ERROR: add_additional_info_column() failed!
Column additional_info not initialized, database not available

这表明在数据库架构升级过程中，系统尝试添加的additional_info字段已存在，导致长期数据库(long-term database)无法正常初始化。

技术背景

PiHole v6.0版本对底层数据库结构进行了重要更新：

1. 数据库版本从6升级到7
2. 新增additional_info文本字段用于扩展查询记录信息
3. 采用SQLite数据库存储长期查询数据

在Docker部署环境下，数据库文件通常挂载在/etc/pihole/目录下，名为pihole-FTL.db。当升级过程中检测到现有数据库时，系统会自动执行架构迁移脚本。

根本原因

该问题通常由以下两种情况导致：

1. 不完全升级：先前升级过程被中断，导致数据库处于不一致状态
2. 手动修改：用户或第三方工具修改过数据库结构
3. 版本冲突：不同版本的PiHole实例共享了同一个数据库文件

在本次案例中，错误明确显示系统尝试添加已存在的字段，表明数据库架构已部分升级但未完整标记。

解决方案

标准修复步骤

1. 停止正在运行的PiHole容器
2. 备份现有数据库文件：

   mv /path/to/pihole/pihole-FTL.db /path/to/pihole/pihole-FTL.db.bak
   

3. 重新启动容器，系统将自动创建新的数据库

数据保留方案（高级用户）

如需保留历史数据，可采用SQLite工具手动修复：

sqlite3 pihole-FTL.db
> ALTER TABLE queries RENAME COLUMN additional_info TO additional_info_old;
> .quit

然后正常启动容器完成升级。

预防措施

1. 定期备份：升级前备份/etc/pihole/目录
2. 版本检查：使用pihole -v确认各组件版本一致性
3. 隔离环境：测试环境验证升级过程
4. 监控日志：升级后检查FTL服务日志

总结

PiHole v6的数据库架构升级引入了新的字段要求，当遇到已有字段冲突时，最安全的解决方法是允许系统重建数据库。对于生产环境，建议建立定期备份机制，并在非高峰时段执行升级操作。Docker用户应特别注意volume挂载点的权限设置，确保PiHole服务账户有足够的读写权限。