ClickHouse Operator 中最新版本 ClickHouse 启动问题分析与解决方案

问题背景

在 ClickHouse 生态系统中，ClickHouse Operator 是一个用于在 Kubernetes 上部署和管理 ClickHouse 集群的重要工具。近期，用户在使用 ClickHouse Operator 时遇到了一个关键问题：当尝试运行最新版本（2025年2月4日发布）的 ClickHouse 时，Pod 无法正常启动，出现文件系统只读错误。

问题现象

用户在使用 ClickHouse Operator 部署 ClickHouse 集群时，如果指定了以下版本的 ClickHouse 镜像：

• 25.1.3.23
• 24.12.4.49
• 24.11.4.45
• 24.8.13.16
• 24.3.16.16
• 或 latest 标签

Pod 启动时会报错：

/entrypoint.sh: neither CLICKHOUSE_USER nor CLICKHOUSE_PASSWORD is set, disabling network access for user 'default'
/entrypoint.sh: line 135: /etc/clickhouse-server/users.d/default-user.xml: Read-only file system

问题根源

这个问题源于 ClickHouse 核心项目中的一个变更，该变更影响了默认用户的网络访问权限设置逻辑。具体来说，当没有设置 CLICKHOUSE_USER 或 CLICKHOUSE_PASSWORD 环境变量时，entrypoint.sh 脚本会尝试修改默认用户的网络访问权限，但由于 Kubernetes 的安全限制，/etc/clickhouse-server/users.d/ 目录是只读的，导致修改失败。

解决方案

临时解决方案

1. 使用不受影响的版本
   暂时回退到已知可用的版本，如 25.1.2.3 或 23.8 版本。

2. 跳过用户设置
   在 Pod 模板中添加环境变量，跳过用户设置步骤：

   env:
   - name: CLICKHOUSE_SKIP_USER_SETUP
     value: "1"
   

3. 自定义网络访问权限
   通过配置文件显式设置默认用户的网络访问权限：

   configuration:
     files:
       users.d/default_allow_network_access.xml: |
         <clickhouse>
           <users>
             <default>
               <networks replace="1">
                 <ip>127.0.0.1</ip>
                 <!-- 添加您的Pod CIDR -->
                 <ip>X.X.X.X/Y</ip>
                 <!-- 添加您的Service CIDR -->
                 <ip>X.X.X.X/Y</ip>
               </networks>
             </default>
           </users>
         </clickhouse>
   

4. 绕过entrypoint.sh
   直接指定启动命令，不使用默认的entrypoint.sh：

   command:
   - /bin/bash
   - -c
   - /usr/bin/clickhouse-server --config-file=/etc/clickhouse-server/config.xml
   

永久解决方案

ClickHouse Operator 团队已经在 0.24.4 版本中修复了这个问题。建议用户升级到最新版本的 Operator 以获得完整的兼容性支持。

最佳实践建议

1. 版本控制
   在生产环境中，避免使用 latest 标签，而是明确指定已知稳定的版本号。

2. 安全配置
   即使解决了启动问题，也应确保正确配置用户权限和网络访问控制，遵循最小权限原则。

3. 监控升级
   在升级 ClickHouse 或 Operator 版本前，先在测试环境验证兼容性。

4. 资源规划
   确保为 ClickHouse 容器分配足够的资源，特别是当处理大量数据时。

总结

这次事件展示了基础设施组件间依赖关系的重要性。作为 ClickHouse 管理员，理解底层机制和保持对上游变更的关注至关重要。通过采用上述解决方案，用户可以顺利地在 Kubernetes 环境中部署最新版本的 ClickHouse，同时保持系统的安全性和稳定性。