ClickHouse Docker 部署文档

# ClickHouse Docker 部署文档

本文档介绍如何使用 **Docker** 或 **Docker Compose** 快速部署 ClickHouse 数据库，并进行基础配置与验证。
[ClickHouse 官方文档](https://clickhouse.com/docs/zh)
[ClickHouse 最新版本地址](https://github.com/ClickHouse/ClickHouse/releases)

---

## 拉取 ClickHouse 镜像
从官方镜像仓库拉取最新版：

```
docker pull clickhouse/clickhouse-server:latest
docker pull clickhouse/clickhouse-server:25.8.11.66
```
镜像地址：https://hub.docker.com/r/clickhouse/clickhouse-server

## 复制配置到指定的配置目录
```
# 对应的目录安装需要指定
mkdir -p /wzxy/clickhouse/conf

docker run --rm clickhouse/clickhouse-server:25.8.11.66 \
  bash -c "cd /etc/clickhouse-server && tar -cf - ." | tar -xf - -C /wzxy/clickhouse/conf
```

## 运行ClickHouse 镜像

```
docker run -d \
  --name clickhouse \
  --restart=always \
  --cpus=8 \
  --memory=16g \
  --ulimit nofile=262144:262144 \
  -p 8123:8123 \
  -p 9000:9000 \
  -p 9004:9004 \
  -v /wzxy/clickhouse/data:/var/lib/clickhouse \
  -v /wzxy/clickhouse/logs:/var/log/clickhouse-server \
  -v /wzxy/clickhouse/conf:/etc/clickhouse-server \
  -v /etc/localtime:/etc/localtime:ro \
  clickhouse/clickhouse-server:25.8.11.66

docker run -d \
  --name clickhouse \
  --restart=always \
  --cpus=8 \
  --memory=16g \
  --ulimit nofile=262144:262144 \
  -p 8123:8123 \ 
  -p 9000:9000 \ 
  -p 9004:9004 \
  -v /wzxy/clickhouse/data:/var/lib/clickhouse \
  -v /wzxy/clickhouse/logs:/var/log/clickhouse-server \
  -v /wzxy/clickhouse/conf:/etc/clickhouse-server \
  -v /etc/localtime:/etc/localtime:ro \
  clickhouse/clickhouse-server:25.8.11.66

```
参数说明：

| 参数                                                    | 说明                                       |
| ----------------------------------------------------- | ---------------------------------------- |
| `--name clickhouse`                                   | 容器名称，方便管理和查看容器状态                         |
| `-p 8123:8123`                                        | HTTP 接口端口，可通过浏览器访问或 REST API 连接          |
| `-p 9000:9000`                                        | TCP 客户端端口，用于 ClickHouse 客户端、JDBC/ODBC 连接 |
| `-p 9009:9009`                                        | 集群内部通信端口（复制/集群节点使用），非集群可忽略               |
| `-v /wzxy/clickhouse/data:/var/lib/clickhouse`        | 数据目录持久化，保证容器重启或删除不会丢失数据                  |
| `-v /wzxy/clickhouse/logs:/var/log/clickhouse-server` | 日志目录持久化，方便查看和备份日志                        |
| `-v /wzxy/clickhouse/conf:/etc/clickhouse-server`     | 配置文件持久化，可自定义 `config.xml`、`users.xml` 等  |
| `-v /etc/localtime:/etc/localtime:ro`                 | 同步宿主机时间到容器，保证日志时间正确                      |
| `--restart=always`                                    | 容器异常退出或宿主机重启时自动启动                        |
| `--cpus=8`                                            | 根据宿主机总核数分配 50%-70% 给 ClickHouse，避免占满宿主机                 |
| `--memory=16g`                                        | 50%-70% 宿主机总内存，保证其他服务运行正常                 |
| `--ulimit nofile=262144:262144`                       | 提升文件描述符上限，支持高并发查询和大表访问                   |

## 配置文件介绍
| 文件/目录          | 作用说明                                                                 | 使用建议/备注 |
|------------------|----------------------------------------------------------------------|--------------|
| `config.xml`      | ClickHouse 主配置文件，包含服务器端口、日志目录、数据目录、内存限制、网络配置、集群设置等 | 修改此文件可以调整全局配置，例如 HTTP/TCP 端口、路径、默认内存等；生产环境建议备份原文件再修改 |
| `users.xml`       | 用户和权限配置文件，定义 ClickHouse 用户、密码、角色、访问权限、资源限制等            | 可以添加或修改用户及访问权限；如果使用 LDAP、Kerberos 等认证，也会在这里配置 |
| `config.d/`       | 额外的配置目录，允许将配置拆分成多个小文件，例如 `storage.xml`、`zookeeper.xml` 等 | 便于模块化配置，避免修改 `config.xml` 直接冲突；支持动态加载和覆盖配置 |
| `users.d/`        | 额外的用户配置目录，允许将用户配置拆分成多个文件                           | 便于管理多个用户和角色，支持按环境或项目拆分用户配置；优先级高于 `users.xml` |

### config.xml介绍
```
<yandex>
    
    <listen_host>::</listen_host>        
    <listen_host>0.0.0.0</listen_host>   
    <listen_try>1</listen_try>

<http_port>8123</http_port>

<tcp_port>9000</tcp_port>

<interserver_http_port>9009</interserver_http_port>

<path>/var/lib/clickhouse/</path>    
    <tmp_path>/var/lib/clickhouse/tmp/</tmp_path>

<logger>
        
        <level>information</level>
        
        <log>/var/log/clickhouse-server/clickhouse-server.log</log>
        
        <errorlog>/var/log/clickhouse-server/clickhouse-server.err.log</errorlog>
        
        <size>500M</size>
        
        <count>10</count>
    </logger>

<max_memory_usage>8000000000</max_memory_usage> 
    <mark_cache_size>2147483648</mark_cache_size>  
    <uncompressed_cache_size>4294967296</uncompressed_cache_size> 
    <max_threads>8</max_threads>

<merge_tree>
        <max_part_size>1073741824</max_part_size> 
    </merge_tree>

<compression>
        <case>
            <min_part_size>1048576</min_part_size> 
            <method>LZ4</method>                  
        </case>
    </compression>

</yandex>

```
### users.xml配置
users.d目录下，例如建立admin用户，则在该目录下建立admin.xml文件
```
<clickhouse>
  <users>
    <admin>
      <password>cxClickHouse@12!</password>
      <networks>
        <ip>::/0</ip>
        <ip>0.0.0.0</ip>
      </networks>
      <profile>default</profile>
      <quota>default</quota>
      <access_management>1</access_management>
    </admin>
  </users>
</clickhouse>
```

## 验证

```
# 进入容器内部
docker exec -it clickhouse bash

# 清空 access 缓存  
rm -rf /var/lib/clickhouse/access/*

# 容器内部登录 default
clickhouse-client -u default

clickhouse-client -u admin --password AdminPass@2025

# 验证用户列表：
SELECT name FROM system.users;

```

## 客户端连接方式
| 工具                        | 连接地址                                                 | 端口   | 协议   |
| ------------------------- | ---------------------------------------------------- | ---- | ---- |
| 浏览器                       | [http://localhost:8123](http://localhost:8123)       | 8123 | HTTP |
| clickhouse-client         | localhost                                            | 9000 | TCP  |
| Python（clickhouse-driver） | `clickhouse://admin:admin123@localhost:9000/default` | TCP  |      |
| Grafana                   | [http://localhost:8123](http://localhost:8123)       | 8123 | HTTP |