金融量化AI研究--Claude， Python

这里用来记录一些本人运用Claude编程的心得或笔记

导航

Clickhouse 数据库 docker部署经验

目录

官方仓库：
https://github.com/ClickHouse/ClickHouse.git

ClickHouse Docker 部署指南（群晖 NAS）

基于 ClickHouse 26.2.4.23 版本，在群晖 NAS Docker 环境中的部署经验总结。

环境信息

项目 值
NAS 型号 群晖 Synology
NAS IP 192.168.123.104
数据目录 /volume5/docker5/clickhouse/
镜像源 docker.1ms.run/（国内镜像加速）

端口说明

端口 用途
8123 HTTP 接口（REST API）
9000 Native TCP 接口（客户端连接）
9009 集群间通信
8080 Tabix Web 管理界面

最终有效的配置

目录结构

/volume5/docker5/clickhouse/
├── docker-compose.yml
├── config/
│   └── listen.xml          # 必需：允许外部访问
├── data/                   # 数据库文件
├── logs/                   # 日志文件
└── users/                  # 用户配置（自动生成）

docker-compose.yml

version: '3.8'

services:
  clickhouse-server:
    image: docker.1ms.run/clickhouse/clickhouse-server:latest
    container_name: clickhouse-server
    restart: always
    ports:
      - "8123:8123"
      - "9000:9000"
      - "9009:9009"
    environment:
      CLICKHOUSE_PASSWORD: your_password_here
      CLICKHOUSE_DB: quantix
      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
    volumes:
      - /volume5/docker5/clickhouse/data:/var/lib/clickhouse
      - /volume5/docker5/clickhouse/logs:/var/log/clickhouse-server
      - /volume5/docker5/clickhouse/config:/etc/clickhouse-server/config.d
      - /volume5/docker5/clickhouse/users:/etc/clickhouse-server/users.d
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8123/ping"]
      interval: 30s
      timeout: 10s
      retries: 3

  clickhouse-tabix:
    image: docker.1ms.run/spoonest/clickhouse-tabix-web-client:latest
    container_name: clickhouse-tabix
    restart: always
    ports:
      - "8080:80"
    depends_on:
      - clickhouse-server
    environment:
      CH_NAME: "Quantix ClickHouse"
      CH_HOST: "http://192.168.123.104:8123"
      CH_LOGIN: "default"
      CH_PASSWORD: "your_password_here"

config/listen.xml（关键配置文件）

<?xml version="1.0"?>
<clickhouse>
    <listen_host>0.0.0.0</listen_host>
</clickhouse>

必须创建此文件，否则 ClickHouse 默认只监听 localhost，无法从外部访问。

部署步骤

# 1. SSH 登录群晖
ssh admin@192.168.123.104

# 2. 创建目录结构
mkdir -p /volume5/docker5/clickhouse/{data,logs,config,users}

# 3. 创建 listen.xml 配置文件
cat > /volume5/docker5/clickhouse/config/listen.xml << 'EOF'
<?xml version="1.0"?>
<clickhouse>
    <listen_host>0.0.0.0</listen_host>
</clickhouse>
EOF


# 4. 设置正确的权限（ClickHouse 容器内 UID 是 101）
chown -R 101:101 /volume5/docker5/clickhouse/
chmod -R 755 /volume5/docker5/clickhouse/
chmod 644 /volume5/docker5/clickhouse/config/listen.xml

# 5. 创建 docker-compose.yml 并启动
cd /volume5/docker5/clickhouse
# (将上面的 docker-compose.yml 内容保存到此文件)
docker-compose up -d

# 6. 验证部署
docker logs clickhouse-server 2>&1 | tail -20

遇到的问题与解决方案

问题 1: 外部无法连接，Connection reset by peer

原因: ClickHouse 默认只监听 127.0.0.1 和 ::1（localhost），不接受外部连接。

解决方案: 创建 config/listen.xml 配置文件，设置 <listen_host>0.0.0.0</listen_host>

问题 2: 配置文件权限错误

错误信息:

Access to file denied: /etc/clickhouse-server/config.d/listen.xml

原因: 挂载的目录/文件权限不正确，ClickHouse 容器内的用户（UID 101）无法读取。

解决方案:

chown -R 101:101 /volume5/docker5/clickhouse/
chmod -R 755 /volume5/docker5/clickhouse/
chmod 644 /volume5/docker5/clickhouse/config/listen.xml

问题 3: 容器不断重启

原因:

  1. 配置文件与旧数据冲突
  2. 权限问题导致配置无法加载

解决方案:

# 停止容器
docker-compose down

# 清理旧数据（全新安装时）
rm -rf /volume5/docker5/clickhouse/data/*
rm -rf /volume5/docker5/clickhouse/logs/*

# 修复权限后重启
chown -R 101:101 /volume5/docker5/clickhouse/
docker-compose up -d

问题 4: 用户名设置误区

误区: 在环境变量中设置 CLICKHOUSE_USER: admin

正确做法:

  • ClickHouse 默认用户是 default
  • 只需设置 CLICKHOUSE_PASSWORD，密码会自动应用到 default 用户
  • 如需创建其他用户，应在数据库初始化后通过 SQL 创建

关键要点总结

1. 必须创建 listen.xml

官方 Docker 镜像默认只监听 localhost，必须手动创建配置文件启用外部访问：

<?xml version="1.0"?>
<clickhouse>
    <listen_host>0.0.0.0</listen_host>
</clickhouse>

2. 目录权限至关重要

目录 容器内路径 权限要求
data /var/lib/clickhouse UID 101 可读写
logs /var/log/clickhouse-server UID 101 可读写
config /etc/clickhouse-server/config.d UID 101 可读
users /etc/clickhouse-server/users.d UID 101 可读写

3. 环境变量说明

变量 作用 必需
CLICKHOUSE_PASSWORD 设置 default 用户密码，同时启用网络访问 ✅ 必需
CLICKHOUSE_DB 创建默认数据库 可选
CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT 允许访问管理功能 可选
CLICKHOUSE_USER ⚠️ 不推荐使用 避免使用

4. 官方文档要点

"the predefined user default doesn't have the network access unless the password is set"

设置 CLICKHOUSE_PASSWORD 后：

  1. 自动为 default 用户设置密码
  2. 自动启用网络访问（但仍需 listen.xml 配置）

连接测试

HTTP 接口测试

# Ping（无需认证）
curl 'http://192.168.123.104:8123/ping'

# 查询（使用 password 参数）
curl 'http://192.168.123.104:8123/?query=SELECT%20version()&password=your_password'

# 查询（使用 Basic Auth）
curl -u default:your_password 'http://192.168.123.104:8123/?query=SELECT%20version()'

Python 连接示例

import urllib.request

url = 'http://192.168.123.104:8123/?query=SELECT%20version()&password=your_password'
with urllib.request.urlopen(url, timeout=10) as response:
    print(response.read().decode())

容器内客户端测试

docker exec -it clickhouse-server clickhouse-client

项目集成配置

.env 文件

CLICKHOUSE_HOST=192.168.123.104
CLICKHOUSE_PORT=9000
CLICKHOUSE_HTTP_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your_password_here
CLICKHOUSE_DATABASE=quantix

连接字符串示例

# HTTP
http://default:your_password@192.168.123.104:8123/quantix

# TCP (Native)
tcp://default:your_password@192.168.123.104:9000/quantix

参考资源

更新记录

日期 版本 说明
2026-03-14 1.0 初始版本，基于群晖 NAS 部署经验

posted on 2026-03-14 21:44  chengjon  阅读(126)  评论(0)    收藏  举报