diff --git a/.env.example b/.env.example
index f1432ea..5101c0f 100644
--- a/.env.example
+++ b/.env.example
@@ -1,3 +1,8 @@
+# ==============================================================================
+# EZ-API 配置文件示例
+# 默认值已针对生产环境优化，开发环境可按需调整
+# ==============================================================================
+
 # ==============================================================================
 # Control Plane (ez-api) 配置
 # ==============================================================================
@@ -6,28 +11,44 @@
 EZ_API_PORT=8080
 
 # PostgreSQL 主库连接字符串
+# 生产环境：使用强密码和 SSL 连接
+# 开发环境：可使用本地默认配置
 EZ_PG_DSN=host=postgres user=postgres password=postgres dbname=ezapi port=5432 sslmode=disable
 
 # 日志库 DSN（可选）；留空将使用主库写日志
-# 适用于日志量大、需要独立扩展日志存储的场景
+# 生产环境：建议配置独立日志库，避免日志 I/O 影响主库性能
+# 开发环境：留空即可
 EZ_LOG_PG_DSN=
 
 # Redis 连接配置（用于配置快照、实时计数、Feature Flags）
 EZ_REDIS_ADDR=redis:6379
+# 生产环境：必须设置强密码
+# 开发环境：可留空
 EZ_REDIS_PASSWORD=
 EZ_REDIS_DB=0
 
+# ------------------------------------------------------------------------------
+# 鉴权配置
+# ------------------------------------------------------------------------------
+
 # 管理员 Token，用于访问 /admin/* 端点
+# 生产环境：必须设置强随机 Token（建议 32+ 字符）
+# 开发环境：可使用简单值
 EZ_ADMIN_TOKEN=admin123
 
 # 内部统计回写鉴权 Token，用于 Balancer 调用 /internal/stats/flush
+# 生产环境：必须设置强随机 Token，与 EZ_BALANCER_STATS_FLUSH_TOKEN 保持一致
+# 开发环境：可使用简单值
 EZ_INTERNAL_STATS_TOKEN=internal123
 
-# 是否允许匿名访问 /internal/* 端点（仅限开发/测试环境）
-# 默认 false：空 token 且未配置 EZ_INTERNAL_STATS_TOKEN 时返回 401
+# 是否允许匿名访问 /internal/* 端点
+# 生产环境：必须为 false（默认），空 token 时返回 401
+# 开发环境：可设为 true 方便调试
 EZ_INTERNAL_ALLOW_ANON=false
 
-# 允许的 CORS Origin 列表（逗号分隔，* 表示允许所有）
+# 允许的 CORS Origin 列表（逗号分隔）
+# 生产环境：应指定具体域名，如 https://dashboard.example.com
+# 开发环境：可使用 * 允许所有
 EZ_CORS_ALLOW_ORIGINS=*
 
 # ------------------------------------------------------------------------------
@@ -35,12 +56,18 @@ EZ_CORS_ALLOW_ORIGINS=*
 # ------------------------------------------------------------------------------
 
 # 日志保留天数（超过此天数的日志会被清理）
+# 生产环境：根据合规要求设置，建议 30-90 天
+# 开发环境：可设置较短周期
 EZ_LOG_RETENTION_DAYS=30
 
 # 日志最大记录数（超过此数量的旧日志会被清理）
+# 生产环境：根据存储容量设置
+# 开发环境：可设置较小值
 EZ_LOG_MAX_RECORDS=1000000
 
 # 日志分区策略：off（不分区）、month（按月）、day（按天）
+# 生产环境：建议 month 或 day，便于归档和清理
+# 开发环境：off 即可
 EZ_LOG_PARTITIONING=off
 
 # 日志缓冲队列容量
@@ -57,6 +84,8 @@ EZ_LOG_FLUSH_MS=1000
 # ------------------------------------------------------------------------------
 
 # 是否启用 outbox 重试机制（Redis 同步失败时自动重试）
+# 生产环境：建议启用（默认），确保配置同步可靠性
+# 开发环境：可关闭简化调试
 EZ_SYNC_OUTBOX_ENABLED=true
 
 # outbox 重试间隔（秒）
@@ -73,11 +102,12 @@ EZ_SYNC_OUTBOX_MAX_RETRIES=10
 # ------------------------------------------------------------------------------
 
 # Swagger UI Host（留空则使用相对路径，适合反向代理部署）
-# 示例: EZ_SWAGGER_HOST=api.example.com 或 EZ_SWAGGER_HOST=localhost:8080
+# 生产环境：建议配置实际域名，如 api.example.com
+# 开发环境：留空或设为 localhost:8080
 EZ_SWAGGER_HOST=
 
 # ------------------------------------------------------------------------------
-# 独立日志库（docker-compose log-postgres，可选）
+# 独立日志库配置（docker-compose log-postgres，可选）
 # ------------------------------------------------------------------------------
 
 LOG_POSTGRES_USER=postgres
@@ -95,14 +125,16 @@ EZ_BALANCER_PORT=8081
 # 鉴权与安全配置
 # ------------------------------------------------------------------------------
 
-# 是否允许 sk-test* 前缀的测试 Token 绕过鉴权（仅限开发/测试环境）
-# 生产环境必须设为 false
+# 是否允许 sk-test* 前缀的测试 Token 绕过鉴权
+# 生产环境：必须为 false（默认），禁止测试 Token
+# 开发环境：可设为 true 方便调试
 EZ_BALANCER_ENABLE_TEST_KEYS=false
 
 # 可信反向代理 IP/CIDR 列表（逗号分隔）
 # 用于在反向代理后正确解析客户端真实 IP，支持 IP 白名单/黑名单功能
 # 仅当 RemoteAddr 命中可信代理时才信任 X-Real-IP 和 X-Forwarded-For 头
-# 示例: EZ_BALANCER_TRUSTED_PROXIES=10.0.0.0/8,192.168.1.1
+# 生产环境：必须配置为实际代理 IP，如 10.0.0.0/8,192.168.1.1
+# 开发环境：可留空（直连场景）
 EZ_BALANCER_TRUSTED_PROXIES=
 
 # ------------------------------------------------------------------------------
@@ -110,9 +142,9 @@ EZ_BALANCER_TRUSTED_PROXIES=
 # ------------------------------------------------------------------------------
 
 # 是否启用日志上报
-# 默认关闭：Balancer 设计为无状态代理，可独立运行；启用后会将请求日志 HTTP 回写到 ez-api
-# 生产环境建议启用，以便在 Control Plane 统一查看请求日志和用量统计
-EZ_BALANCER_LOG_SINK_ENABLED=false
+# 生产环境：建议启用，以便在 Control Plane 统一查看请求日志
+# 开发环境：可关闭（Balancer 可独立运行）
+EZ_BALANCER_LOG_SINK_ENABLED=true
 
 # 日志上报目标地址（ez-api）
 EZ_BALANCER_LOG_SINK_BASE_URL=http://ez-api:8080
@@ -125,14 +157,16 @@ EZ_BALANCER_LOG_SINK_TIMEOUT_SECONDS=3
 # ------------------------------------------------------------------------------
 
 # 是否启用实时计数回写
-# 默认关闭：启用后 Balancer 会定期将 Token/Master 用量统计回写到 ez-api 数据库
-# 生产环境建议启用，以便支持配额管理和用量报表
-EZ_BALANCER_STATS_FLUSH_ENABLED=false
+# 生产环境：建议启用，以支持配额管理和用量报表
+# 开发环境：可关闭（Balancer 可独立运行）
+EZ_BALANCER_STATS_FLUSH_ENABLED=true
 
 # 计数回写目标地址（ez-api）
 EZ_BALANCER_STATS_FLUSH_BASE_URL=http://ez-api:8080
 
 # 计数回写鉴权 Token（需与 EZ_INTERNAL_STATS_TOKEN 一致）
+# 生产环境：必须设置强随机 Token
+# 开发环境：可使用简单值
 EZ_BALANCER_STATS_FLUSH_TOKEN=internal123
 
 # 计数回写间隔（秒）