docs(docker): use ./config/clickhouse for CH performance mount

Move performance.xml to config/clickhouse and mount the directory to
/etc/clickhouse-server/config.d; update docs and compose paths.

.env.example

@@ -66,6 +66,7 @@ CLICKHOUSE_NAME=openflare
 # CLICKHOUSE_NATIVE_PORT=9000
 # 客户端连接池 / block 缓冲在 config.yaml 的 clickhouse.* 中配置
 # （小规格默认 max_idle_conn=8, max_open_conn=16, block_buffer_size=32）
+#
 
 # ─── 日志 ──────────────────────────────────────────────────────────────────────
 LOG_LEVEL=info

README.md

@@ -72,6 +72,11 @@ OpenFlare 是开源 CDN 编排与边缘安全平台。它支持反向代理、
 # 下载环境变量模板并创建 .env 文件
 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 配置）
+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
 ```
 
 ```yaml
@@ -131,15 +136,21 @@ services:
       CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}
       CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
       TZ: ${TZ:-Asia/Shanghai}
+    ulimits:
+      nofile:
+        soft: 262144
+        hard: 262144
     volumes:
       - openflare_clickhouse_data:/var/lib/clickhouse
+      # 目录内仅 performance.xml；不要放 listen 配置
+      - ./config/clickhouse:/etc/clickhouse-server/config.d:ro
     healthcheck:
       test: ["CMD", "clickhouse-client", "--user", "${CLICKHOUSE_USERNAME:-default}", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
       interval: 10s
       timeout: 5s
       retries: 5
       start_period: 15s
-      
+
 volumes:
     openflare_uploads:
     openflare_postgres_data:

config.example.yaml

@@ -100,12 +100,6 @@ otel:
 
 # ─── ClickHouse (required) ──────────────────────────────────────────────────────
 # Analytics / observability OLAP store. Telemetry writes are best-effort (async batch).
-# Client pool defaults target small control-plane hosts (e.g. 3c6g). Raise only if
-# concurrent analytics queries and writers regularly exhaust the pool.
-# Docker: host mapping defaults CLICKHOUSE_NATIVE_PORT=9000 / HTTP=8123; set
-# docker/clickhouse/config.d listen_host so published ports are reachable.
-# Env overrides: CLICKHOUSE_ENABLED, CLICKHOUSE_HOST, CLICKHOUSE_USERNAME,
-# CLICKHOUSE_PASSWORD, CLICKHOUSE_NAME (see .env.example).
 clickhouse:
   enabled: true
   hosts:

docker-compose.yaml

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

docker/clickhouse/config.d/listen.xml

@@ -1,5 +0,0 @@
-<?xml version="1.0"?>
-<!-- Allow Docker published ports to reach native/HTTP interfaces (IPv4). -->
-<clickhouse>
-    <listen_host>0.0.0.0</listen_host>
-</clickhouse>

docs/changelog/index.md

@@ -27,8 +27,7 @@ sidebar: false
 - model 层通过 hooks 写入 CH，去除对 `chwriter` 的直接依赖。
 - Dashboard 每节点最新指标改为 `LIMIT 1 BY node_id`；新增 metric/openresty 小时预聚合表与读路径优先 rollup。
 - 小规格默认连接池下调；`async_insert_busy_timeout` 调至 2s；`of_node_traffic_hourly` 增加 30 天 TTL，UV 改为峰值窗口估计并修正前端文案。
-- Docker ClickHouse：`performance.xml` 下调 merge free-entry 阈值以兼容小 `background_pool`（避免 25.x 启动 Code 36）；增加 `listen_host=0.0.0.0` 以便宿主机访问映射端口。
+- Docker ClickHouse：`performance.xml` 下调 merge free-entry 阈值以兼容小 `background_pool`（避免 25.x 启动 Code 36）。
-- 同步 `.env.example` 与 `config.example.yaml`：ClickHouse 小规格连接池默认、compose 端口/启用变量说明，密码占位与 compose 默认一致。
 
 ## [v3.1.1] - 2026-07-06
 

docs/deployment/server.md

@@ -8,6 +8,30 @@ OpenFlare Server 是 Gin + GORM 单体控制面，负责管理端 UI、管理 AP
 > **关于外部依赖**：
 > OpenFlare 系统内建了对后台异步任务（Asynq 框架）及海量节点日志分析与度量指标（观测面板）的支持。因此，**无论采用何种部署模式，系统都必须依赖 Redis（或 Valkey）与 ClickHouse 的运行**。各个部署方案的主要差异在于主关系型数据库的选择（SQLite vs PostgreSQL）以及是否启用链路追踪服务（Jaeger）。
 
+> [!TIP]
+> **ClickHouse 服务端性能配置（推荐挂载）**  
+> 控制面常见为小规格主机（如 3c6g）。仓库提供的 `performance.xml` 会收紧后台 merge/mutation 线程池，避免默认配置在小机器上静置 CPU 偏高或 ClickHouse 25.x 启动校验失败。  
+> 将本地目录 `./config/clickhouse` 挂载到容器 `/etc/clickhouse-server/config.d`。  
+> **目录内只放 `performance.xml`，不要放入任何 listen 相关配置**（监听地址沿用官方镜像默认即可）。
+
+部署前将配置拉到本地：
+
+```bash
+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
+```
+
+在 ClickHouse 服务的 `volumes` 中增加（与数据卷并列）：
+
+```yaml
+volumes:
+  - ./data/clickhouse_data:/var/lib/clickhouse   # 或 named volume
+  - ./config/clickhouse:/etc/clickhouse-server/config.d:ro
+```
+
+修改 `performance.xml` 后需 `docker compose restart clickhouse` 才生效。
+
 ---
 
 ## 方式一：Docker 部署 (推荐)
@@ -71,10 +95,16 @@ services:
       CLICKHOUSE_PASSWORD: 123456
       CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
       TZ: Asia/Shanghai
+    ulimits:
+      nofile:
+        soft: 262144
+        hard: 262144
     volumes:
       - ./data/clickhouse_data:/var/lib/clickhouse
+      # 仅含 performance.xml 的目录；不要在此目录放 listen 配置
+      - ./config/clickhouse:/etc/clickhouse-server/config.d:ro
     healthcheck:
-      test: ["CMD", "clickhouse-client", "--query", "SELECT 1"]
+      test: ["CMD", "clickhouse-client", "--user", "default", "--password", "123456", "--query", "SELECT 1"]
       interval: 10s
       timeout: 5s
       retries: 5
@@ -84,6 +114,9 @@ services:
 运行启动命令：
 
 ```bash
+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
 docker compose up -d
 ```
 
@@ -154,8 +187,14 @@ services:
       CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}
       CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
       TZ: ${TZ:-Asia/Shanghai}
+    ulimits:
+      nofile:
+        soft: 262144
+        hard: 262144
     volumes:
       - openflare_clickhouse_data:/var/lib/clickhouse
+      # 仅含 performance.xml 的目录；不要在此目录放 listen 配置
+      - ./config/clickhouse:/etc/clickhouse-server/config.d:ro
     healthcheck:
       test: ["CMD", "clickhouse-client", "--user", "${CLICKHOUSE_USERNAME:-default}", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
       interval: 10s
@@ -173,6 +212,9 @@ volumes:
 创建对应的 `.env` 文件来配置系统环境变量（可复制并修改根目录下的 `.env.example`）：
 
 ```bash
+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
 curl -o .env.example https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/.env.example
 cp .env.example .env
 # 编辑 .env 文件，填入对应的数据库、Redis、ClickHouse 连接地址、密码与 APP_SESSION_SECRET
@@ -264,25 +306,34 @@ services:
       CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}
       CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
       TZ: ${TZ:-Asia/Shanghai}
+    ulimits:
+      nofile:
+        soft: 262144
+        hard: 262144
     volumes:
       - openflare_clickhouse_data:/var/lib/clickhouse
-
+      # 仅含 performance.xml 的目录；不要在此目录放 listen 配置
-volumes:
+      - ./config/clickhouse:/etc/clickhouse-server/config.d:ro
-  openflare_uploads:
-  openflare_postgres_data:
-  openflare_redis_data:
-  openflare_clickhouse_data:
     healthcheck:
       test: ["CMD", "clickhouse-client", "--user", "${CLICKHOUSE_USERNAME:-default}", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
       interval: 10s
       timeout: 5s
       retries: 5
       start_period: 15s
+
+volumes:
+  openflare_uploads:
+  openflare_postgres_data:
+  openflare_redis_data:
+  openflare_clickhouse_data:
 ```
 
 启动并验证：
 
 ```bash
+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
 curl -o .env.example https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/.env.example
 cp .env.example .env
 # 编辑 .env 文件并确保设置好 APP_SESSION_SECRET 密码
@@ -304,7 +355,7 @@ docker compose up -d
 | Go | `1.25+` |
 | Node.js | `18+` |
 | pnpm | 推荐通过 `corepack enable` 使用项目声明的 pnpm |
-| 外部服务 | 必须在本地或远端运行 Redis (Valkey) 和 ClickHouse 实例 |
+| 外部服务 | 必须在本地或远端运行 Redis (Valkey) 和 ClickHouse 实例；ClickHouse 建议挂载仓库提供的 `performance.xml`（见上文「ClickHouse 服务端性能配置」） |
 
 ### 1. 构建管理端前端
 

docs/guide/quick-start.md

@@ -30,6 +30,14 @@ Agent 统一通过 OpenResty 二进制控制运行时。本地部署需要节点
 
 为了保证异步任务队列（Asynq 框架）及可观测流量看板功能完整运行，快速开始推荐采用 **PostgreSQL + Redis + ClickHouse** 经典单机版编排。
 
+先拉取 ClickHouse 服务端性能配置到 `./config/clickhouse`（目录内**仅**放 `performance.xml`，不要放 listen 配置）：
+
+```bash
+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
+```
+
 在空目录中创建 `docker-compose.yaml`：
 
 ```yaml
@@ -54,9 +62,9 @@ services:
       DB_PASSWORD: "${DB_PASSWORD:-replace-with-strong-password}"
       DB_NAME: "${DB_NAME:-openflare}"
       REDIS_ENABLED: "true"
-      REDIS_ADDRS: "redis:6379"
+      REDIS_ADDR: "redis:6379"
       CLICKHOUSE_ENABLED: "true"
-      CLICKHOUSE_HOSTS: "clickhouse:9000"
+      CLICKHOUSE_HOST: "clickhouse:9000"
     depends_on:
       postgres:
         condition: service_healthy
@@ -101,10 +109,16 @@ services:
       CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}
       CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
       TZ: Asia/Shanghai
+    ulimits:
+      nofile:
+        soft: 262144
+        hard: 262144
     volumes:
       - openflare_clickhouse_data:/var/lib/clickhouse
+      # 目录内仅 performance.xml；不要放 listen 配置
+      - ./config/clickhouse:/etc/clickhouse-server/config.d:ro
     healthcheck:
-      test: ["CMD", "clickhouse-client", "--user", "${CLICKHOUSE_USERNAME:-default}", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
+      test: ["CMD", "clickhouse-client", "--user", "default", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
       interval: 10s
       timeout: 5s
       retries: 5

docs/reference/configuration.md

@@ -99,13 +99,21 @@ Server 的所有核心基础配置定义在 `config.yaml` 中，且均支持环
 | `redis.pool_size` | `REDIS_POOL_SIZE` | Redis 连接池大小 | `100` |
 
 ### 4. ClickHouse 配置 (`clickhouse:`)
+
+> **说明**：下列为 OpenFlare **客户端**连接参数。ClickHouse **服务端**小规格调优：将 `performance.xml` curl 到 `./config/clickhouse/`，compose 挂载 `./config/clickhouse:/etc/clickhouse-server/config.d:ro`（目录内不要放 listen 配置），详见 [启动 Server](../deployment/server.md)。
+
 | 配置文件 YAML 路径 | 对应覆盖环境变量 | 作用说明 | 默认值 |
 | --- | --- | --- | --- |
 | `clickhouse.enabled` | `CLICKHOUSE_ENABLED` | 是否启用 ClickHouse。**系统节点指标与访问日志在此进行海量写入** | `true` |
 | `clickhouse.hosts` | `CLICKHOUSE_HOST` | ClickHouse 集群连接地址数组（环境变量仅设置单地址） | `["127.0.0.1:9000"]` |
 | `clickhouse.username` | `CLICKHOUSE_USERNAME` | ClickHouse 账号用户名 | `default` |
-| `clickhouse.password` | `CLICKHOUSE_PASSWORD` | ClickHouse 密码 | `123456` |
+| `clickhouse.password` | `CLICKHOUSE_PASSWORD` | ClickHouse 密码 | `replace-with-clickhouse-password` |
 | `clickhouse.database` | `CLICKHOUSE_NAME` | ClickHouse 存储的数据库名称 | `openflare` |
+| `clickhouse.max_idle_conn` | - | 客户端空闲连接数（小规格默认偏低） | `8` |
+| `clickhouse.max_open_conn` | - | 客户端最大打开连接数 | `16` |
+| `clickhouse.conn_max_lifetime` | - | 连接最大存活时间（秒） | `3600` |
+| `clickhouse.dial_timeout` | - | 建连超时（秒） | `5` |
+| `clickhouse.block_buffer_size` | - | 原生协议 block 缓冲行数 | `32` |
 
 ### 5. 系统日志配置 (`log:`)
 | 配置文件 YAML 路径 | 对应覆盖环境变量 | 作用说明 | 默认值 |