From 9cfc1b2c97bebb28c66fb22fbe81a391779172e6 Mon Sep 17 00:00:00 2001 From: zenfun Date: Sat, 3 Jan 2026 16:52:23 +0800 Subject: [PATCH] docs(config): document new internal auth and balancer variables Update .env.example with new configuration options: - EZ_INTERNAL_ALLOW_ANON for controlling anonymous internal access - EZ_BALANCER_ENABLE_TEST_KEYS for testing auth bypass - EZ_BALANCER_TRUSTED_PROXIES for real IP resolution Add security configuration section to README explaining internal endpoint authentication logic and default behaviors. --- .env.example | 9 +++++++++ README.md | 9 +++++++++ 2 files changed, 18 insertions(+) diff --git a/.env.example b/.env.example index 95a3187..00aa724 100644 --- a/.env.example +++ b/.env.example @@ -8,6 +8,9 @@ EZ_REDIS_PASSWORD= EZ_REDIS_DB=0 EZ_ADMIN_TOKEN=admin123 EZ_INTERNAL_STATS_TOKEN=internal123 +# 是否允许匿名访问 /internal/* 端点（仅限开发/测试环境，生产环境应设为 false） +# 默认 false：空 token 且未配置 EZ_INTERNAL_STATS_TOKEN 时返回 401 +EZ_INTERNAL_ALLOW_ANON=false EZ_CORS_ALLOW_ORIGINS=* # 日志保留策略（单位：天 / 条数） EZ_LOG_RETENTION_DAYS=30 @@ -31,6 +34,12 @@ LOG_POSTGRES_DB=ezapi_logs # Data Plane EZ_BALANCER_PORT=8081 +# 是否允许 sk-test* 前缀的测试 Token 绕过鉴权（仅限开发/测试环境） +EZ_BALANCER_ENABLE_TEST_KEYS=false +# 可信反向代理 IP/CIDR 列表（逗号分隔），用于正确解析客户端 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= EZ_BALANCER_LOG_SINK_ENABLED=false EZ_BALANCER_LOG_SINK_BASE_URL=http://ez-api:8080 EZ_BALANCER_LOG_SINK_TIMEOUT_SECONDS=3 diff --git a/README.md b/README.md index 908b4cd..8a16cae 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,15 @@ EZ-API 是“控制平面”，负责管理事实来源 (Source of Truth)。 | `EZ_MODEL_REGISTRY_CACHE_DIR` | `./data/model-registry` | 模型注册表缓存目录。 | | `EZ_QUOTA_RESET_INTERVAL_SECONDS` | `300` | 配额重置间隔。 | | `EZ_INTERNAL_STATS_TOKEN` | `` | 内部统计回写鉴权 token。 | +| `EZ_INTERNAL_ALLOW_ANON` | `false` | 允许匿名访问 `/internal/*` 端点（仅限开发/测试）。 | + +### 安全配置说明 + +**内部端点认证 (`/internal/*`)** + +- 默认情况下，`/internal/*` 端点需要 `X-Internal-Token` 头与 `EZ_INTERNAL_STATS_TOKEN` 匹配。 +- 如果 `EZ_INTERNAL_STATS_TOKEN` 为空且 `EZ_INTERNAL_ALLOW_ANON=false`（默认），所有内部端点请求将返回 401。 +- 仅在开发/测试环境设置 `EZ_INTERNAL_ALLOW_ANON=true` 以允许匿名访问。 配置读取优先级：环境变量 > 配置文件 > 默认值。通过 [Viper](https://github.com/spf13/viper) 支持 `./config.yaml`（或 `./config/config.yaml`），也可用 `EZ_CONFIG_FILE` 指定路径。示例：