diff --git a/.env.example b/.env.example index acf14200..9b6d4b42 100644 --- a/.env.example +++ b/.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 diff --git a/README.md b/README.md index f4112d03..88000e5b 100644 --- a/README.md +++ b/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: diff --git a/config.example.yaml b/config.example.yaml index 3e5ccff7..2da01191 100644 --- a/config.example.yaml +++ b/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: diff --git a/docker/clickhouse/config.d/performance.xml b/config/clickhouse/performance.xml similarity index 100% rename from docker/clickhouse/config.d/performance.xml rename to config/clickhouse/performance.xml diff --git a/docker-compose.yaml b/docker-compose.yaml index 3ac6264d..736308c4 100644 --- a/docker-compose.yaml +++ b/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 diff --git a/docker/clickhouse/config.d/listen.xml b/docker/clickhouse/config.d/listen.xml deleted file mode 100644 index ae111ee0..00000000 --- a/docker/clickhouse/config.d/listen.xml +++ /dev/null @@ -1,5 +0,0 @@ - - - - 0.0.0.0 - diff --git a/docs/changelog/index.md b/docs/changelog/index.md index 777b145d..3c5324a4 100644 --- a/docs/changelog/index.md +++ b/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` 以便宿主机访问映射端口。 -- 同步 `.env.example` 与 `config.example.yaml`：ClickHouse 小规格连接池默认、compose 端口/启用变量说明，密码占位与 compose 默认一致。 +- Docker ClickHouse：`performance.xml` 下调 merge free-entry 阈值以兼容小 `background_pool`（避免 25.x 启动 Code 36）。 ## [v3.1.1] - 2026-07-06 diff --git a/docs/deployment/server.md b/docs/deployment/server.md index 1668c777..8cd2fc14 100644 --- a/docs/deployment/server.md +++ b/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 - -volumes: - openflare_uploads: - openflare_postgres_data: - openflare_redis_data: - openflare_clickhouse_data: + # 仅含 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: + 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. 构建管理端前端 diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md index 709027aa..03a79a7c 100644 --- a/docs/guide/quick-start.md +++ b/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 diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index d5f3deb2..4d231cab 100644 --- a/docs/reference/configuration.md +++ b/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 路径 | 对应覆盖环境变量 | 作用说明 | 默认值 |