diff --git a/.env.example b/.env.example
index 059a2c48..acf14200 100644
--- a/.env.example
+++ b/.env.example
@@ -1,7 +1,8 @@
 # ──────────────────────────────────────────────────────────────────────────────
 # openflare — 环境变量配置模板
 # 复制此文件为 .env 并填入实际值:  cp .env.example .env
-# 环境变量优先级高于 config.yaml / config.docker.yaml
+# 环境变量优先级高于 config.yaml
+# docker compose 会读取本文件（env_file: .env）并替换 compose 中的 ${VAR}
 # ──────────────────────────────────────────────────────────────────────────────
 
 # ─── 时区 ─────────────────────────────────────────────────────────────────────
@@ -22,11 +23,12 @@ APP_SESSION_HTTP_ONLY=true
 # HTTPS 部署时设为 true，HTTP 环境必须为 false
 APP_SESSION_SECURE=true
 
-# ─── 数据库 ────────────────────────────────────────────────────────────────────
+# ─── 数据库（PostgreSQL）──────────────────────────────────────────────────────
 # 设置 DB_HOST 后自动启用 PostgreSQL，也可通过 DB_ENABLED 显式控制
 # DB_ENABLED=false 时使用 SQLite 作为后备数据库
 DB_ENABLED=true
 # SQLITE_PATH=./data/openflare.db
+# compose 内应用连服务名；本机直连 Docker 映射端口时用 127.0.0.1
 DB_HOST=postgres
 DB_PORT=5432
 DB_USERNAME=openflare
@@ -38,7 +40,7 @@ DB_TIMEZONE=Asia/Shanghai
 # DB_MAX_IDLE_CONN=16
 # DB_MAX_OPEN_CONN=128
 
-# ─── Redis ─────────────────────────────────────────────────────────────────────
+# ─── Redis / Valkey ────────────────────────────────────────────────────────────
 # 设置 REDIS_ADDR 后自动启用，也可通过 REDIS_ENABLED 显式控制
 REDIS_ENABLED=true
 REDIS_ADDR=redis:6379
@@ -47,12 +49,23 @@ REDIS_ADDR=redis:6379
 # REDIS_DB=0
 REDIS_KEY_PREFIX=openflare:
 # REDIS_POOL_SIZE=100
+# compose 宿主机映射端口（仅 docker-compose 使用）
+# REDIS_PORT=6379
 
-# ─── ClickHouse（必需）────────────────────────────────────────────────────
+# ─── ClickHouse（必需）────────────────────────────────────────────────────────
+# CLICKHOUSE_HOST 设置后会自动启用；测试环境可显式 CLICKHOUSE_ENABLED=true 做 live 联调
+CLICKHOUSE_ENABLED=true
+# compose 内：clickhouse:9000；本机连映射端口：127.0.0.1:9000
 CLICKHOUSE_HOST=clickhouse:9000
 CLICKHOUSE_USERNAME=default
+# 须与 compose clickhouse 服务密码一致（首次初始化后改密码需清 data/clickhouse_data）
 CLICKHOUSE_PASSWORD=replace-with-clickhouse-password
 CLICKHOUSE_NAME=openflare
+# compose 宿主机映射端口（仅 docker-compose 使用）
+# CLICKHOUSE_HTTP_PORT=8123
+# CLICKHOUSE_NATIVE_PORT=9000
+# 客户端连接池 / block 缓冲在 config.yaml 的 clickhouse.* 中配置
+# （小规格默认 max_idle_conn=8, max_open_conn=16, block_buffer_size=32）
 
 # ─── 日志 ──────────────────────────────────────────────────────────────────────
 LOG_LEVEL=info
@@ -67,6 +80,11 @@ OTEL_EXPORTER_OTLP_INSECURE=true
 OTEL_SAMPLING_RATE=0.0
 # 全局 Tracer 命名空间，默认为 github.com/Rain-kl/OpenFlare
 # OTEL_TRACER_NAME=github.com/Rain-kl/OpenFlare
+# compose 可选端口覆盖
+# JAEGER_VERSION=2.19.0
+# JAEGER_UI_PORT=16686
+# JAEGER_OTLP_GRPC_PORT=4317
+# JAEGER_OTLP_HTTP_PORT=4318
 
 # ─── Worker ────────────────────────────────────────────────────────────────────
 # WORKER_CONCURRENCY=20
diff --git a/config.example.yaml b/config.example.yaml
index b34a702b..3e5ccff7 100644
--- a/config.example.yaml
+++ b/config.example.yaml
@@ -99,17 +99,24 @@ otel:
 
 
 # ─── ClickHouse (required) ──────────────────────────────────────────────────────
-# Client pool sized for small control-plane hosts (e.g. 3c6g). Raise only if
+# 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:
-    - "127.0.0.1:9000"
+    - "127.0.0.1:9000"        # compose 内应用可用 clickhouse:9000（经 CLICKHOUSE_HOST）
   username: "default"
-  password: "123456"
+  password: "replace-with-clickhouse-password"  # 与 .env / compose CLICKHOUSE_PASSWORD 一致
   database: "openflare"
   max_idle_conn: 8            # keep warm sockets low to save client + server RAM
   max_open_conn: 16           # cap concurrent native sessions on modest CH boxes
   conn_max_lifetime: 3600
   dial_timeout: 5
   block_buffer_size: 32       # rows buffered per block; 32 is enough for our batch sizes
+  # Runtime client also enables async_insert (wait_for_async_insert=1, busy_timeout≈2s)
+  # in internal/db/clickhouse.go — not configured via YAML.
diff --git a/docs/changelog/index.md b/docs/changelog/index.md
index 120eb396..777b145d 100644
--- a/docs/changelog/index.md
+++ b/docs/changelog/index.md
@@ -28,6 +28,7 @@ sidebar: false
 - 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 默认一致。
 
 ## [v3.1.1] - 2026-07-06