用户指南 · 11
环境变量配置
提示：从 v2.x 起，所有 API Key 都可以在 设置 → 通用 → API Keys 中按用户配置（AES-256-GCM 加密存储），优先级高于环境变量。环境变量主要用于初次部署或 fallback。
11.1 必需配置（至少一个）
| 变量 | 说明 |
|---|---|
ANTHROPIC_API_KEY | Anthropic API 密钥（Claude 系列） |
OPENAI_API_KEY | OpenAI API 密钥（GPT + 多媒体生成） |
11.2 Provider 端点覆盖
| 变量 | 说明 |
|---|---|
ANTHROPIC_BASE_URL | 自定义 Anthropic API 端点 |
OPENAI_BASE_URL | 自定义 OpenAI API 端点 |
11.3 按能力覆盖
当某项能力需要使用与主 Provider 不同的 API Key 或端点时：
| 能力 | Key 变量 | URL 变量 |
|---|---|---|
| 图片生成 | IMAGE_API_KEY | IMAGE_BASE_URL |
| TTS 语音 | TTS_API_KEY | TTS_BASE_URL |
| 视频生成 | VIDEO_API_KEY | VIDEO_BASE_URL |
| 实时语音 S2S | S2S_API_KEY | S2S_BASE_URL |
| 语音转写 STT | STT_API_KEY | STT_BASE_URL |
11.4 联网工具
| 变量 | 说明 |
|---|---|
CLOUDSWAY_SEARCH_KEY | CloudsWay 搜索 API（优先使用） |
CLOUDSWAY_READ_URL | CloudsWay 网页抓取端点（可选覆盖） |
CLOUDSWAY_SEARCH_URL | CloudsWay 搜索端点（可选覆盖） |
TAVILY_API_KEY | Tavily 搜索 API（备选） |
11.5 S3 存储（可选）
| 变量 | 说明 |
|---|---|
STORAGE_BACKEND | local（默认）或 s3 |
S3_BUCKET | S3 桶名称 |
S3_REGION | S3 区域 |
S3_ENDPOINT_URL | 自定义端点（MinIO/R2/OSS） |
S3_ACCESS_KEY_ID | S3 访问密钥 |
S3_SECRET_ACCESS_KEY | S3 秘密密钥 |
S3_PREFIX | S3 key 前缀（可选） |
注意：JSON 配置文件（users.json、conversations 等）目前仍走本地盘。S3 模式仅托管文件系统层（
docs/、scripts/、generated/、soul/）。
11.6 加密 Master Key
| 变量 | 说明 |
|---|---|
ENCRYPTION_KEY | per-admin API Key 的 AES-256-GCM master key（不设则首次启动自动生成 data/encryption.key） |
生产环境强烈建议显式设置
ENCRYPTION_KEY并妥善备份，否则 master key 文件丢失将导致所有用户的 API Key 无法解密。
11.7 脚本沙箱调优
| 变量 | 默认值 | 说明 |
|---|---|---|
SCRIPT_CONCURRENCY | 4 | 全局并发脚本数 |
SCRIPT_QUEUE_TIMEOUT | 180 | 排队超时（秒） |
11.8 端口配置
| 变量 | 默认 | 说明 |
|---|---|---|
BACKEND_PORT | 8000 | FastAPI 端口（Docker 用） |
FRONTEND_PORT | 3000 | Express/Vite 端口 |
API_TARGET | http://localhost:8000 | Express 代理目标 |
11.9 可观测性
| 变量 | 说明 |
|---|---|
LANGFUSE_SECRET_KEY | Langfuse 密钥 |
LANGFUSE_PUBLIC_KEY | Langfuse 公钥 |
LANGFUSE_HOST | Langfuse 服务地址 |
LANGCHAIN_TRACING_V2 | 启用 LangSmith |
LANGCHAIN_API_KEY | LangSmith API Key |