ez-api/.env.example

# ==============================================================================
# EZ-API 配置文件示例
# 默认值已针对生产环境优化，开发环境可按需调整
# ==============================================================================

# ==============================================================================
# Control Plane (ez-api) 配置
# ==============================================================================

# 服务监听端口
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 时返回 401
# 开发环境：可设为 true 方便调试
EZ_INTERNAL_ALLOW_ANON=false

# 允许的 CORS Origin 列表（逗号分隔）
# 生产环境：应指定具体域名，如 https://dashboard.example.com
# 开发环境：可使用 * 允许所有
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

# 日志缓冲队列容量
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 配置
# ------------------------------------------------------------------------------

# Swagger UI Host（留空则使用相对路径，适合反向代理部署）
# 生产环境：建议配置实际域名，如 api.example.com
# 开发环境：留空或设为 localhost:8080
EZ_SWAGGER_HOST=

# ------------------------------------------------------------------------------
# 独立日志库配置（docker-compose log-postgres，可选）
# ------------------------------------------------------------------------------

LOG_POSTGRES_USER=postgres
LOG_POSTGRES_PASSWORD=postgres
LOG_POSTGRES_DB=ezapi_logs

# ==============================================================================
# Data Plane (balancer) 配置
# ==============================================================================

# 服务监听端口
EZ_BALANCER_PORT=8081

# ------------------------------------------------------------------------------
# 鉴权与安全配置
# ------------------------------------------------------------------------------

# 是否允许 sk-test* 前缀的测试 Token 绕过鉴权
# 生产环境：必须为 false（默认），禁止测试 Token
# 开发环境：可设为 true 方便调试
EZ_BALANCER_ENABLE_TEST_KEYS=false

# 可信反向代理 IP/CIDR 列表（逗号分隔）
# 用于在反向代理后正确解析客户端真实 IP，支持 IP 白名单/黑名单功能
# 仅当 RemoteAddr 命中可信代理时才信任代理头（CF-Connecting-IP, Ali-CDN-Real-IP, X-Real-IP, X-Forwarded-For）
#
# 支持的 CDN 头（按优先级）：
#   1. CF-Connecting-IP (Cloudflare)
#   2. Ali-CDN-Real-IP (阿里云 CDN)
#   3. X-Real-IP
#   4. X-Forwarded-For
#
# 生产环境：必须配置为实际代理 IP
# 开发环境：可留空（直连场景）
#
# Cloudflare IP 段（截至 2025-01，请定期检查 https://www.cloudflare.com/ips/）
# IPv4: 173.245.48.0/20,103.21.244.0/22,103.22.200.0/22,103.31.4.0/22,141.101.64.0/18,108.162.192.0/18,190.93.240.0/20,188.114.96.0/20,197.234.240.0/22,198.41.128.0/17,162.158.0.0/15,104.16.0.0/13,104.24.0.0/14,172.64.0.0/13,131.0.72.0/22
# IPv6: 2400:cb00::/32,2606:4700::/32,2803:f800::/32,2405:b500::/32,2405:8100::/32,2a06:98c0::/29,2c0f:f248::/32
#
# 阿里云 CDN（节点 IP 动态变化，建议通过阿里云控制台获取或使用 Ali-CDN-Real-IP 头）
#
EZ_BALANCER_TRUSTED_PROXIES=

# ------------------------------------------------------------------------------
# 日志上报配置（Balancer -> Control Plane）
# ------------------------------------------------------------------------------

# 是否启用日志上报
# 生产环境：建议启用，以便在 Control Plane 统一查看请求日志
# 开发环境：可关闭（Balancer 可独立运行）
EZ_BALANCER_LOG_SINK_ENABLED=true

# 日志上报目标地址（ez-api）
EZ_BALANCER_LOG_SINK_BASE_URL=http://ez-api:8080

# 日志上报超时（秒）
EZ_BALANCER_LOG_SINK_TIMEOUT_SECONDS=3

# ------------------------------------------------------------------------------
# 实时计数回写配置（Balancer -> Control Plane）
# ------------------------------------------------------------------------------

# 是否启用实时计数回写
# 生产环境：建议启用，以支持配额管理和用量报表
# 开发环境：可关闭（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

# 计数回写间隔（秒）
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: default, openai, compatible, anthropic, claude, google
EZ_BALANCER_TIMEOUT_BY_PROVIDER={"default":30,"openai":40,"compatible":40,"anthropic":50,"claude":50,"google":60}