fix(docker): preserve clickhouse listener config

README.md

@@ -73,7 +73,7 @@ OpenFlare 是开源 CDN 编排与边缘安全平台。它支持反向代理、
 curl -o .env.example https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/.env.example
 cp .env.example .env
 
-# ClickHouse 服务端：curl performance.xml 到 ./config/clickhouse，整目录挂载到 config.d（不要放 listen 配置）
+# ClickHouse 服务端：curl performance.xml 到 ./config/clickhouse，并以单文件方式挂载到 config.d
 mkdir -p ./config/clickhouse
 curl -fsSL -o ./config/clickhouse/performance.xml \
   https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/config/clickhouse/performance.xml
@@ -142,7 +142,7 @@ services:
         hard: 262144
     volumes:
       - openflare_clickhouse_data:/var/lib/clickhouse
-      - ./config/clickhouse:/etc/clickhouse-server/config.d:ro
+      - ./config/clickhouse/performance.xml:/etc/clickhouse-server/config.d/performance.xml:ro
     healthcheck:
       test: ["CMD", "clickhouse-client", "--user", "${CLICKHOUSE_USERNAME:-default}", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
       interval: 10s

docker-compose.yaml

@@ -88,7 +88,7 @@ services:
       - "9000:9000"
     volumes:
       - ./data/clickhouse_data:/var/lib/clickhouse
-      - ./config/clickhouse:/etc/clickhouse-server/config.d:ro
+      - ./config/clickhouse/performance.xml:/etc/clickhouse-server/config.d/performance.xml:ro
     healthcheck:
       test: ["CMD", "clickhouse-client", "--user", "${CLICKHOUSE_USERNAME:-default}", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
       interval: 10s

docs/changelog/index.md

@@ -21,6 +21,10 @@ sidebar: false
 
 ## [unreleased]
 
+### 修复
+
+- Docker ClickHouse 性能配置改为单文件挂载，避免覆盖镜像内置的 Docker 网络监听配置，导致宿主机无法通过 8123/9000 访问服务。
+
 ## [v3.1.2] - 2026-07-10
 
 ### 修复

docs/deployment/server.md

@@ -11,8 +11,7 @@ OpenFlare Server 是 Gin + GORM 单体控制面，负责管理端 UI、管理 AP
 > [!TIP]
 > **ClickHouse 服务端性能配置（推荐挂载）**  
 > 控制面常见为小规格主机（如 3c6g）。仓库提供的 `performance.xml` 会收紧后台 merge/mutation 线程池，避免默认配置在小机器上静置 CPU 偏高或 ClickHouse 25.x 启动校验失败。  
-> 将本地目录 `./config/clickhouse` 挂载到容器 `/etc/clickhouse-server/config.d`。  
-> **目录内只放 `performance.xml`，不要放入任何 listen 相关配置**（监听地址沿用官方镜像默认即可）。
+> 将本地 `./config/clickhouse/performance.xml` 以单文件方式挂载到容器 `/etc/clickhouse-server/config.d/performance.xml`，以保留官方镜像内置的 Docker 网络监听配置。
 
 部署前将配置拉到本地：
 
@@ -27,7 +26,7 @@ curl -fsSL -o ./config/clickhouse/performance.xml \
 ```yaml
 volumes:
   - ./data/clickhouse_data:/var/lib/clickhouse   # 或 named volume
-  - ./config/clickhouse:/etc/clickhouse-server/config.d:ro
+  - ./config/clickhouse/performance.xml:/etc/clickhouse-server/config.d/performance.xml:ro
 ```
 
 修改 `performance.xml` 后需 `docker compose restart clickhouse` 才生效。
@@ -101,7 +100,7 @@ services:
         hard: 262144
     volumes:
       - ./data/clickhouse_data:/var/lib/clickhouse
-      - ./config/clickhouse:/etc/clickhouse-server/config.d:ro
+      - ./config/clickhouse/performance.xml:/etc/clickhouse-server/config.d/performance.xml:ro
     healthcheck:
       test: ["CMD", "clickhouse-client", "--user", "default", "--password", "123456", "--query", "SELECT 1"]
       interval: 10s
@@ -192,7 +191,7 @@ services:
         hard: 262144
     volumes:
       - openflare_clickhouse_data:/var/lib/clickhouse
-      - ./config/clickhouse:/etc/clickhouse-server/config.d:ro
+      - ./config/clickhouse/performance.xml:/etc/clickhouse-server/config.d/performance.xml:ro
     healthcheck:
       test: ["CMD", "clickhouse-client", "--user", "${CLICKHOUSE_USERNAME:-default}", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
       interval: 10s
@@ -310,7 +309,7 @@ services:
         hard: 262144
     volumes:
       - openflare_clickhouse_data:/var/lib/clickhouse
-      - ./config/clickhouse:/etc/clickhouse-server/config.d:ro
+      - ./config/clickhouse/performance.xml:/etc/clickhouse-server/config.d/performance.xml:ro
     healthcheck:
       test: ["CMD", "clickhouse-client", "--user", "${CLICKHOUSE_USERNAME:-default}", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
       interval: 10s

docs/guide/quick-start.md

@@ -30,7 +30,7 @@ Agent 统一通过 OpenResty 二进制控制运行时。本地部署需要节点
 
 为了保证异步任务队列（Asynq 框架）及可观测流量看板功能完整运行，快速开始推荐采用 **PostgreSQL + Redis + ClickHouse** 经典单机版编排。
 
-先拉取 ClickHouse 服务端性能配置到 `./config/clickhouse`（目录内**仅**放 `performance.xml`，不要放 listen 配置）：
+先拉取 ClickHouse 服务端性能配置到 `./config/clickhouse`，并以单文件方式挂载：
 
 ```bash
 mkdir -p ./config/clickhouse
@@ -115,7 +115,7 @@ services:
         hard: 262144
     volumes:
       - openflare_clickhouse_data:/var/lib/clickhouse
-      - ./config/clickhouse:/etc/clickhouse-server/config.d:ro
+      - ./config/clickhouse/performance.xml:/etc/clickhouse-server/config.d/performance.xml:ro
     healthcheck:
       test: ["CMD", "clickhouse-client", "--user", "default", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
       interval: 10s

docs/reference/configuration.md

@@ -100,7 +100,7 @@ Server 的所有核心基础配置定义在 `config.yaml` 中，且均支持环
 
 ### 4. ClickHouse 配置 (`clickhouse:`)
 
-> **说明**：下列为 OpenFlare **客户端**连接参数。ClickHouse **服务端**小规格调优：将 `performance.xml` curl 到 `./config/clickhouse/`，compose 挂载 `./config/clickhouse:/etc/clickhouse-server/config.d:ro`（目录内不要放 listen 配置），详见 [启动 Server](../deployment/server.md)。
+> **说明**：下列为 OpenFlare **客户端**连接参数。ClickHouse **服务端**小规格调优：将 `performance.xml` curl 到 `./config/clickhouse/`，再以单文件方式挂载至容器的 `config.d/performance.xml`，详见 [启动 Server](../deployment/server.md)。
 
 | 配置文件 YAML 路径 | 对应覆盖环境变量 | 作用说明 | 默认值 |
 | --- | --- | --- | --- |