ez-api/.env.example

# ==============================================================================
# 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（可选）；留空将使用主库写日志
# 适用于日志量大、需要独立扩展日志存储的场景
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：空 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（按天）
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（留空则使用相对路径，适合反向代理部署）
# 示例: EZ_SWAGGER_HOST=api.example.com 或 EZ_SWAGGER_HOST=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
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
EZ_BALANCER_TRUSTED_PROXIES=

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

# 是否启用日志上报
# 默认关闭：Balancer 设计为无状态代理，可独立运行；启用后会将请求日志 HTTP 回写到 ez-api
# 生产环境建议启用，以便在 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）
# ------------------------------------------------------------------------------

# 是否启用实时计数回写
# 默认关闭：启用后 Balancer 会定期将 Token/Master 用量统计回写到 ez-api 数据库
# 生产环境建议启用，以便支持配额管理和用量报表
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: default, openai, compatible, anthropic, claude, google
EZ_BALANCER_TIMEOUT_BY_PROVIDER={"default":30,"openai":40,"compatible":40,"anthropic":50,"claude":50,"google":60}