Plausible社区版升级至v3.0.1后Clickhouse连接问题解析

在将Plausible社区版从v2.1.5升级到v3.0.1版本时，用户可能会遇到Clickhouse数据库连接失败的问题。本文将深入分析问题原因并提供完整的解决方案。

问题现象

升级后，Plausible主容器无法连接到Clickhouse数据库，错误提示显示"Authentication failed: password is incorrect"。当用户回退到旧版docker-compose.yml配置时，系统又能正常工作。

根本原因分析

新版本Plausible(v3.0.1)使用了Clickhouse 24.12版本，而旧版(v2.1.5)使用的是Clickhouse 24.3版本。新版本Clickhouse对用户认证机制进行了调整，导致默认的认证方式不兼容。

解决方案

第一步：解决认证问题

在docker-compose.yml文件中为plausible_events_db服务添加环境变量：

environment:
  - CLICKHOUSE_SKIP_USER_SETUP=1

这个设置会跳过Clickhouse默认用户设置过程，使用容器内已有的用户配置。

第二步：处理数据库迁移问题

解决认证问题后，可能会遇到数据库迁移错误，提示"Wrong column name. Cannot find column scroll_depth to drop"。这是因为新版本尝试删除不存在的列。

解决方案是：

1. 确保Clickhouse容器完全停止并删除旧数据卷
2. 重新创建全新的Clickhouse数据库实例
3. 让Plausible从头开始初始化数据库结构

完整配置示例

以下是经过验证可用的docker-compose.yml关键部分配置：

plausible_events_db:
  image: clickhouse/clickhouse-server:24.12-alpine
  environment:
    - CLICKHOUSE_SKIP_USER_SETUP=1
  volumes:
    - event-data:/var/lib/clickhouse
  ulimits:
    nofile:
      soft: 262144
      hard: 262144

升级最佳实践

1. 在升级前备份所有重要数据
2. 先在一个测试环境中验证升级过程
3. 仔细阅读版本变更说明，特别是数据库相关的变更
4. 考虑使用全新的数据卷而不是复用旧数据卷

总结

Plausible社区版v3.0.1与Clickhouse新版本的集成需要特别注意认证配置。通过正确设置CLICKHOUSE_SKIP_USER_SETUP环境变量，可以解决大部分连接问题。对于数据库迁移错误，建议采用全新初始化方式而非尝试迁移旧数据结构。