docs(config): improve .env.example organization and docs

Reorganize configuration variables into logical sections with clear
headers and detailed comments to enhance readability. Add missing log
buffering settings (EZ_LOG_QUEUE, EZ_LOG_BATCH_SIZE, EZ_LOG_FLUSH_MS)
and expand descriptions for authentication and network options.

.env.example

@@ -1,53 +1,149 @@
-# Control Plane
+# ==============================================================================
+# Control Plane (ez-api) 配置
+# ==============================================================================
+
+# 服务监听端口
 EZ_API_PORT=8080
+
+# PostgreSQL 主库连接字符串
 EZ_PG_DSN=host=postgres user=postgres password=postgres dbname=ezapi port=5432 sslmode=disable
-# 日志库 DSN（可选）；默认不创建独立 log DB，留空将使用主库写日志
+
+# 日志库 DSN（可选）；留空将使用主库写日志
+# 适用于日志量大、需要独立扩展日志存储的场景
 EZ_LOG_PG_DSN=
+
+# Redis 连接配置（用于配置快照、实时计数、Feature Flags）
 EZ_REDIS_ADDR=redis:6379
 EZ_REDIS_PASSWORD=
 EZ_REDIS_DB=0
+
+# 管理员 Token，用于访问 /admin/* 端点
 EZ_ADMIN_TOKEN=admin123
+
+# 内部统计回写鉴权 Token，用于 Balancer 调用 /internal/stats/flush
 EZ_INTERNAL_STATS_TOKEN=internal123
-# 是否允许匿名访问 /internal/* 端点（仅限开发/测试环境，生产环境应设为 false）
+
+# 是否允许匿名访问 /internal/* 端点（仅限开发/测试环境）
 # 默认 false：空 token 且未配置 EZ_INTERNAL_STATS_TOKEN 时返回 401
 EZ_INTERNAL_ALLOW_ANON=false
+
+# 允许的 CORS Origin 列表（逗号分隔，* 表示允许所有）
 EZ_CORS_ALLOW_ORIGINS=*
-# 日志保留策略（单位：天 / 条数）
+
+# ------------------------------------------------------------------------------
+# 日志配置
+# ------------------------------------------------------------------------------
+
+# 日志保留天数（超过此天数的日志会被清理）
 EZ_LOG_RETENTION_DAYS=30
+
+# 日志最大记录数（超过此数量的旧日志会被清理）
 EZ_LOG_MAX_RECORDS=1000000
-# 日志分区（off/month/day）
+
+# 日志分区策略：off（不分区）、month（按月）、day（按天）
 EZ_LOG_PARTITIONING=off
-# 同步可靠性（CP -> Redis outbox）
+
+# 日志缓冲队列容量
+EZ_LOG_QUEUE=10000
+
+# 单次 DB 写入日志数
+EZ_LOG_BATCH_SIZE=10
+
+# 日志批量刷新间隔（毫秒）
+EZ_LOG_FLUSH_MS=1000
+
+# ------------------------------------------------------------------------------
+# 同步可靠性配置（Control Plane -> Redis outbox）
+# ------------------------------------------------------------------------------
+
+# 是否启用 outbox 重试机制（Redis 同步失败时自动重试）
 EZ_SYNC_OUTBOX_ENABLED=true
+
+# outbox 重试间隔（秒）
 EZ_SYNC_OUTBOX_INTERVAL_SECONDS=5
+
+# outbox 单次处理数量
 EZ_SYNC_OUTBOX_BATCH_SIZE=200
+
+# outbox 最大重试次数
 EZ_SYNC_OUTBOX_MAX_RETRIES=10
 
-# Swagger UI Host (留空则使用相对路径，适合反向代理部署)
+# ------------------------------------------------------------------------------
+# Swagger UI 配置
+# ------------------------------------------------------------------------------
+
+# Swagger UI Host（留空则使用相对路径，适合反向代理部署）
 # 示例: EZ_SWAGGER_HOST=api.example.com 或 EZ_SWAGGER_HOST=localhost:8080
 EZ_SWAGGER_HOST=
 
-# Log DB (docker-compose log-postgres，可选；默认不启用独立日志库)
+# ------------------------------------------------------------------------------
+# 独立日志库（docker-compose log-postgres，可选）
+# ------------------------------------------------------------------------------
+
 LOG_POSTGRES_USER=postgres
 LOG_POSTGRES_PASSWORD=postgres
 LOG_POSTGRES_DB=ezapi_logs
 
-# Data Plane
+# ==============================================================================
+# Data Plane (balancer) 配置
+# ==============================================================================
+
+# 服务监听端口
 EZ_BALANCER_PORT=8081
+
+# ------------------------------------------------------------------------------
+# 鉴权与安全配置
+# ------------------------------------------------------------------------------
+
 # 是否允许 sk-test* 前缀的测试 Token 绕过鉴权（仅限开发/测试环境）
+# 生产环境必须设为 false
 EZ_BALANCER_ENABLE_TEST_KEYS=false
-# 可信反向代理 IP/CIDR 列表（逗号分隔），用于正确解析客户端 IP
+
+# 可信反向代理 IP/CIDR 列表（逗号分隔）
+# 用于在反向代理后正确解析客户端真实 IP，支持 IP 白名单/黑名单功能
 # 仅当 RemoteAddr 命中可信代理时才信任 X-Real-IP 和 X-Forwarded-For 头
 # 示例: EZ_BALANCER_TRUSTED_PROXIES=10.0.0.0/8,192.168.1.1
 EZ_BALANCER_TRUSTED_PROXIES=
+
+# ------------------------------------------------------------------------------
+# 日志上报配置（Balancer -> Control Plane）
+# ------------------------------------------------------------------------------
+
+# 是否启用日志上报
 EZ_BALANCER_LOG_SINK_ENABLED=false
+
+# 日志上报目标地址（ez-api）
 EZ_BALANCER_LOG_SINK_BASE_URL=http://ez-api:8080
+
+# 日志上报超时（秒）
 EZ_BALANCER_LOG_SINK_TIMEOUT_SECONDS=3
+
+# ------------------------------------------------------------------------------
+# 实时计数回写配置（Balancer -> Control Plane）
+# ------------------------------------------------------------------------------
+
+# 是否启用实时计数回写
 EZ_BALANCER_STATS_FLUSH_ENABLED=false
+
+# 计数回写目标地址（ez-api）
 EZ_BALANCER_STATS_FLUSH_BASE_URL=http://ez-api:8080
+
+# 计数回写鉴权 Token（需与 EZ_INTERNAL_STATS_TOKEN 一致）
 EZ_BALANCER_STATS_FLUSH_TOKEN=internal123
+
+# 计数回写间隔（秒）
 EZ_BALANCER_STATS_FLUSH_INTERVAL_SECONDS=300
+
+# 计数回写批次大小
 EZ_BALANCER_STATS_FLUSH_BATCH_SIZE=200
+
+# 计数回写超时（秒）
 EZ_BALANCER_STATS_FLUSH_TIMEOUT_SECONDS=5
-# 按 provider type 配置非流式请求超时（秒，JSON）
+
+# ------------------------------------------------------------------------------
+# 上游请求配置
+# ------------------------------------------------------------------------------
+
+# 按 provider type 配置非流式请求超时（秒，JSON 格式）
+# 支持的 provider type: default, openai, compatible, anthropic, claude, google
 EZ_BALANCER_TIMEOUT_BY_PROVIDER={"default":30,"openai":40,"compatible":40,"anthropic":50,"claude":50,"google":60}