Spaces:

lengfeng1360
/

AIstudioProxyAPI

Runtime error

File size: 9,268 Bytes

927965d

# 环境变量配置指南

本文档详细介绍如何使用 `.env` 文件来配置 AI Studio Proxy API 项目，实现统一的配置管理。

## 概述

项目采用基于 `.env` 文件的现代化配置管理系统，提供以下优势：

### 主要优势

- ✅ **版本更新无忧**: 一个 `git pull` 就完成更新，无需重新配置
- ✅ **配置集中管理**: 所有配置项统一在 `.env` 文件中，清晰明了
- ✅ **启动命令简化**: 无需复杂的命令行参数，一键启动
- ✅ **安全性**: `.env` 文件已被 `.gitignore` 忽略，不会泄露敏感配置
- ✅ **灵活性**: 支持不同环境的配置管理（开发、测试、生产）
- ✅ **Docker 兼容**: Docker 和本地环境使用相同的配置方式
- ✅ **模块化设计**: 配置项按功能分组，便于理解和维护

## 快速开始

### 1. 复制配置模板

```bash

cp .env.example .env

```

### 2. 编辑配置文件

根据您的需要修改 `.env` 文件中的配置项：

```bash

# 编辑配置文件

nano .env

# 或使用其他编辑器

code .env

```

### 3. 启动服务

配置完成后，启动变得非常简单：

```bash

# 图形界面启动（推荐新手）

python gui_launcher.py



# 命令行启动（推荐日常使用）

python launch_camoufox.py --headless



# 调试模式（首次设置或故障排除）

python launch_camoufox.py --debug

```

**就这么简单！** 无需复杂的命令行参数，所有配置都在 `.env` 文件中预设好了。

## 启动命令对比

### 使用 `.env` 配置前（复杂）

```bash

# 之前需要这样的复杂命令

python launch_camoufox.py --headless --server-port 2048 --stream-port 3120 --helper '' --internal-camoufox-proxy 'http://127.0.0.1:7890'

```

### 使用 `.env` 配置后（简单）

```bash

# 现在只需要这样

python launch_camoufox.py --headless

```

**配置一次，终身受益！** 所有复杂的参数都在 `.env` 文件中预设，启动命令变得极其简洁。

## 主要配置项

### 服务端口配置

```env

# FastAPI 服务端口

PORT=8000

DEFAULT_FASTAPI_PORT=2048

DEFAULT_CAMOUFOX_PORT=9222



# 流式代理服务配置

STREAM_PORT=3120

```

### 代理配置

```env

# HTTP/HTTPS 代理设置

HTTP_PROXY=http://127.0.0.1:7890

HTTPS_PROXY=http://127.0.0.1:7890



# 统一代理配置 (优先级更高)

UNIFIED_PROXY_CONFIG=http://127.0.0.1:7890



# 代理绕过列表

NO_PROXY=localhost;127.0.0.1;*.local

```

### 日志配置

```env

# 服务器日志级别

SERVER_LOG_LEVEL=INFO



# 启用调试日志

DEBUG_LOGS_ENABLED=false

TRACE_LOGS_ENABLED=false



# 是否重定向 print 输出到日志

SERVER_REDIRECT_PRINT=false

```

### 认证配置

```env

# 自动保存认证信息

AUTO_SAVE_AUTH=false



# 认证保存超时时间 (秒)

AUTH_SAVE_TIMEOUT=30



# 自动确认登录

AUTO_CONFIRM_LOGIN=true

```

### API 默认参数

```env

# 默认温度值 (0.0-2.0)

DEFAULT_TEMPERATURE=1.0



# 默认最大输出令牌数

DEFAULT_MAX_OUTPUT_TOKENS=65536



# 默认 Top-P 值 (0.0-1.0)

DEFAULT_TOP_P=0.95



# 默认停止序列 (JSON 数组格式)

DEFAULT_STOP_SEQUENCES=["用户:"]



# 是否在处理请求时自动打开并使用 "URL Context" 功能

# 参考: https://ai.google.dev/gemini-api/docs/url-context

ENABLE_URL_CONTEXT=true



# 是否默认启用 "指定思考预算" 功能 (true/false),不启用时模型一般将自行决定思考预算

# 当 API 请求中未提供 reasoning_effort 参数时,将使用此值。

ENABLE_THINKING_BUDGET=false



# "指定思考预算量" 的默认值 (token)

# 当 API 请求中未提供 reasoning_effort 参数时,将使用此值。

DEFAULT_THINKING_BUDGET=8192



# 是否默认启用 "Google Search" 功能 (true/false)

# 当 API 请求中未提供 tools 参数时，将使用此设置作为 Google Search 的默认开关状态。

ENABLE_GOOGLE_SEARCH=false

```

### 超时配置

```env

# 响应完成总超时时间 (毫秒)

RESPONSE_COMPLETION_TIMEOUT=300000



# 轮询间隔 (毫秒)

POLLING_INTERVAL=300

POLLING_INTERVAL_STREAM=180



# 静默超时 (毫秒)

SILENCE_TIMEOUT_MS=60000

```

### GUI 启动器配置

```env

# GUI 默认代理地址

GUI_DEFAULT_PROXY_ADDRESS=http://127.0.0.1:7890



# GUI 默认流式代理端口

GUI_DEFAULT_STREAM_PORT=3120



# GUI 默认 Helper 端点

GUI_DEFAULT_HELPER_ENDPOINT=

```

### 脚本注入配置 v3.0 🆕

```env

# 是否启用油猴脚本注入功能

ENABLE_SCRIPT_INJECTION=true



# 油猴脚本文件路径（相对于项目根目录）

# 模型数据直接从此脚本文件中解析，无需额外配置文件

USERSCRIPT_PATH=browser_utils/more_modles.js

```

**脚本注入功能 v3.0 重大升级**：
- **🚀 Playwright 原生拦截**: 使用 Playwright 路由拦截，100% 可靠性
- **🔄 双重保障机制**: 网络拦截 + 脚本注入，确保万无一失
- **📝 直接脚本解析**: 从油猴脚本中自动解析模型列表，无需配置文件
- **🔗 前后端同步**: 前端和后端使用相同的模型数据源
- **⚙️ 零配置维护**: 脚本更新时自动获取新的模型列表
- **🔄 自动适配**: 油猴脚本更新时无需手动更新配置

**与 v1.x 的主要区别**：
- 移除了 `MODEL_CONFIG_PATH` 配置项（已废弃）
- 不再需要手动维护模型配置文件
- 工作机制从"配置文件 + 脚本注入"改为"直接脚本解析 + 网络拦截"

详细使用方法请参见 [脚本注入指南](script_injection_guide.md)。

## 配置优先级

配置项的优先级顺序（从高到低）：

1. **命令行参数** - 直接传递给程序的参数
2. **环境变量** - 系统环境变量或 `.env` 文件中的变量
3. **默认值** - 代码中定义的默认值

## 常见配置场景

### 场景 1：使用代理

```env

# 启用代理

HTTP_PROXY=http://127.0.0.1:7890

HTTPS_PROXY=http://127.0.0.1:7890



# GUI 中也使用相同代理

GUI_DEFAULT_PROXY_ADDRESS=http://127.0.0.1:7890

```

### 场景 2：调试模式

```env

# 启用详细日志

DEBUG_LOGS_ENABLED=true

TRACE_LOGS_ENABLED=true

SERVER_LOG_LEVEL=DEBUG

SERVER_REDIRECT_PRINT=true

```

### 场景 3：生产环境

```env

# 生产环境配置

SERVER_LOG_LEVEL=WARNING

DEBUG_LOGS_ENABLED=false

TRACE_LOGS_ENABLED=false



# 更长的超时时间

RESPONSE_COMPLETION_TIMEOUT=600000

SILENCE_TIMEOUT_MS=120000

```

### 场景 4：自定义端口

```env

# 避免端口冲突

DEFAULT_FASTAPI_PORT=3048

DEFAULT_CAMOUFOX_PORT=9223

STREAM_PORT=3121

```

### 场景 5：启用脚本注入 v3.0 🆕

```env

# 启用脚本注入功能 v3.0

ENABLE_SCRIPT_INJECTION=true



# 使用自定义脚本（模型数据直接从脚本解析）

USERSCRIPT_PATH=browser_utils/my_custom_script.js



# 调试模式查看注入效果

DEBUG_LOGS_ENABLED=true



# 流式代理配置（与脚本注入配合使用）

STREAM_PORT=3120

```

**v3.0 脚本注入优势**：
- 使用 Playwright 原生网络拦截，无时序问题
- 前后端模型数据100%同步
- 零配置维护，脚本更新自动生效

## 配置优先级

项目采用分层配置系统，按以下优先级顺序确定最终配置：

1. **命令行参数** (最高优先级)
   ```bash

   # 命令行参数会覆盖 .env 文件中的设置

   python launch_camoufox.py --headless --server-port 3048

   ```

2. **`.env` 文件配置** (推荐)
   ```env

   # .env 文件中的配置

   DEFAULT_FASTAPI_PORT=2048

   ```

3. **系统环境变量** (最低优先级)
   ```bash

   # 系统环境变量

   export DEFAULT_FASTAPI_PORT=2048

   ```

### 使用建议

- **日常使用**: 在 `.env` 文件中配置所有常用设置
- **临时调整**: 使用命令行参数进行临时覆盖，无需修改 `.env` 文件
- **CI/CD 环境**: 可以通过系统环境变量进行配置

## 注意事项

### 1. 文件安全

- `.env` 文件已被 `.gitignore` 忽略，不会被提交到版本控制
- 请勿在 `.env.example` 中包含真实的敏感信息
- 如需分享配置，请复制并清理敏感信息后再分享

### 2. 格式要求

- 环境变量名区分大小写
- 布尔值使用 `true`/`false`
- 数组使用 JSON 格式：`["item1", "item2"]`
- 字符串值如包含特殊字符，请使用引号

### 3. 重启生效

修改 `.env` 文件后需要重启服务才能生效。

### 4. 验证配置

启动服务时，日志会显示加载的配置信息，可以通过日志验证配置是否正确。

## 故障排除

### 配置未生效

1. 检查 `.env` 文件是否在项目根目录
2. 检查环境变量名是否正确（区分大小写）
3. 检查值的格式是否正确
4. 重启服务

### 代理配置问题

1. 确认代理服务器地址和端口正确
2. 检查代理服务器是否正常运行
3. 验证网络连接

### 端口冲突

1. 检查端口是否被其他程序占用
2. 使用 GUI 启动器的端口检查功能
3. 修改为其他可用端口

## 更多信息

- [安装指南](installation-guide.md)
- [高级配置](advanced-configuration.md)
- [故障排除](troubleshooting.md)