docs(litellm): 添加环境变量配置说明和DashScope兼容项注释

- 在 .env.example 和 .env.production.example 中添加 DashScope API
  相关变量的可选兼容项注释
- 更新 compose.yaml 中的注释，说明固定常量保留在 compose 内部，
  环境变量通过白名单方式注入容器的机制
- 在 litellm.md 文档中补充环境变量说明，包括 DashScope
  API 兼容项的使用场景
- 添加关于 --env-file 和 environment 白名单工作原理的详细说明，
  解释如何避免无关变量注入容器

Author: mudssky

ai/gateway/litellm/.env.example

@@ -10,3 +10,6 @@ NEWAPI_KEY=sk-newapi-dev-xxxx
 LITELLM_MASTER_KEY=sk-litellm-123456
 # LiteLLM 元数据数据库；未显式设置时 compose 会使用默认本地 PostgreSQL 地址。
 DATABASE_URL=postgresql://postgres:12345678@host.docker.internal:5432/litellm
+# 可选兼容项：如果后续切回 `qwen.yaml` 这类百炼配置，再补这些变量即可。
+# DASHSCOPE_API_KEY=sk-dashscope-dev-xxxx
+# DASHSCOPE_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1

ai/gateway/litellm/.env.production.example

@@ -10,3 +10,6 @@ NEWAPI_KEY=sk-newapi-prod-change-me
 LITELLM_MASTER_KEY=sk-litellm-prod-change-me
 # 生产环境建议使用独立数据库账号，并限制到最小权限。
 DATABASE_URL=postgresql://litellm:change-me@postgres.internal:5432/litellm
+# 可选兼容项：如果生产环境仍需切换到 DashScope / qwen.yaml，再提供这些变量。
+# DASHSCOPE_API_KEY=sk-dashscope-prod-change-me
+# DASHSCOPE_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1

ai/gateway/litellm/compose.yaml

@@ -6,19 +6,22 @@ services:
     ports:
       - "${LITELLM_HOST_PORT:-34000}:4000"
     environment:
+      # 固定容器常量保留在 compose 内部，避免每个环境都重复维护这类不变值。
       # LiteLLM 官方镜像会把 PORT 透传给内部 uvicorn 启动参数，未显式设置时会报错。
       PORT: "4000"
       # 当前镜像需要显式提供配置文件路径；仅挂载 /app/config.yaml 并不会自动加载 model_list。
       CONFIG_FILE_PATH: "/app/config.yaml"
+      # 下面这些值统一由 `--env-file .env.local` 提供，再通过白名单方式注入容器。
+      # 这样可以避免把 `.env.local` 中与 LiteLLM 无关的变量一并注入容器。
       # 通过 compose 插值保留当前默认数据库地址；start.ps1 会在存在 .env.local 时传入 --env-file 以支持本地覆盖。
       DATABASE_URL: ${DATABASE_URL:-postgresql://postgres:12345678@host.docker.internal:5432/litellm}
       # 当前本地配置走 NewAPI OpenAI 兼容接口；变量必须显式注入容器，LiteLLM 才能解析 os.environ/...。
       NEWAPI_API_BASE: ${NEWAPI_API_BASE:-}
       NEWAPI_KEY: ${NEWAPI_KEY:-}
+      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY:-}
       # 保留旧变量，避免切回 qwen.yaml 等历史配置时还要额外补环境变量。
       DASHSCOPE_API_KEY: ${DASHSCOPE_API_KEY:-}
       DASHSCOPE_API_BASE: ${DASHSCOPE_API_BASE:-https://dashscope.aliyuncs.com/compatible-mode/v1}
-      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY:-}
     volumes:
       - ./litellm.local.yaml:/app/config.yaml:ro
     extra_hosts:

ai/gateway/litellm/litellm.md

@@ -12,6 +12,8 @@
 - `.env.production.example`：生产环境变量示例。
 - `.env.local`：本地私有环境变量，保存 `NEWAPI_API_BASE`、`NEWAPI_KEY`、`LITELLM_MASTER_KEY`、可选 `DATABASE_URL`。
 
+固定常量如 `PORT=4000`、`CONFIG_FILE_PATH=/app/config.yaml` 保留在 `compose.yaml` 内部；环境差异值建议集中在 `.env.local`，再通过 `start.ps1` 追加的 `--env-file` 和 `compose.yaml` 的 `environment` 白名单注入到容器。
+
 ## 环境变量
 
 建议先在 `ai/gateway/litellm/.env.local` 中配置以下值：
@@ -33,6 +35,7 @@ DATABASE_URL=postgresql://postgres:12345678@host.docker.internal:5432/litellm
 - `NEWAPI_KEY`：LiteLLM 转发到 NewAPI 时使用的上游密钥。
 - `LITELLM_MASTER_KEY`：LiteLLM Proxy 对外暴露的网关密钥。
 - `DATABASE_URL`：LiteLLM 的数据库连接串；如果未配置，会回退到默认的宿主机 PostgreSQL 地址。
+- `DASHSCOPE_API_KEY` / `DASHSCOPE_API_BASE`：可选兼容项；只有切回 `qwen.yaml` 或其他百炼配置时才需要提供。
 
 如果你想准备生产环境变量，可直接复制 `./.env.production.example` 再按实际环境改值。
 
@@ -53,6 +56,11 @@ docker compose --env-file ai/gateway/litellm/.env.local `
   up -d
 ```
 
+说明：
+
+- 这里保留 `--env-file`，而不是把 `.env.local` 改成 `env_file` 主方案，是因为它同时负责 compose 插值，例如 `image`、`ports`、`environment` 中的 `${...}`。
+- `compose.yaml` 里的 `environment` 继续采用白名单注入，这样 `.env.local` 中与 LiteLLM 无关的变量不会自动进入容器。
+
 ## 常用命令
 
 ```powershell