环境变量配置
提示：从 v2.x 起，所有 API Key 都可以在 设置 → 通用 → API Keys 中按用户配置（AES-256-GCM 加密存储），优先级高于环境变量。环境变量主要用于初次部署或 fallback。
11.1 必需配置（至少一个）
本小节适用于 DeepAgents / API 路径。Codex / Cursor 套餐日常对话与内部 Service 不要求额外 LLM API Key；配置方法见 4.12。独立搜索、语音等附加 API 能力仍需各自配置。
| 变量 | 说明 |
|---|---|
ANTHROPIC_API_KEY | Anthropic API 密钥（Claude 系列） |
OPENAI_API_KEY | OpenAI API 密钥（GPT + 多媒体生成） |
也可配置 BEDROCK_API_KEY / BEDROCK_REGION、OPENROUTER_API_KEY 或 SILICONFLOW_API_KEY。硅基流动与 OpenRouter 模型需在设置页白名单中启用，可通过 OPENROUTER_BASE_URL / SILICONFLOW_BASE_URL 覆盖端点；示例见 .env.example。这些 API 凭据与 Codex / Cursor 供应商登录相互独立。
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/）。
Cloudflare R2 的 S3_ENDPOINT_URL 使用 https://<ACCOUNT_ID>.r2.cloudflarestorage.com。region 留空时 R2 自动使用 auto，其余使用 us-east-1；S3_CHECKSUM_MODE=auto 对自定义端点使用 when_required，需要路径寻址的兼容服务可配置 S3_ADDRESSING_STYLE=path。浏览器直接 fetch 签名 URL 时需配置桶 CORS，完整 R2 示例见 .env.example。
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 |
11.10 可选供应商运行引擎
以 .env.example 为配置入口。设置 JELLYFISH_RUNTIME_ENABLED=1、JELLYFISH_RUNTIME_ACCESS_MODE=trusted_shared、JELLYFISH_RUNTIME_BACKEND=local、UVICORN_WORKERS=1，要求 macOS / Linux，CLI 安装在后端执行环境内。Docker 可分别配置固定构建参数 JELLYFISH_CODEX_CLI_VERSION=0.154.0、JELLYFISH_CURSOR_CLI_VERSION=2026.09.15-d2fe57e，重建应用容器后重新加载 Nginx。这些版本有安装验证，不代表完整生产验收。
部署方通过 python3 launcher.py --superadmin-key 查看主机 key（Docker 用 docker compose exec openjellyfish python launcher.py --superadmin-key），在 /superadmin 输入后登录供应商并向已有 admin 授权模型。JELLYFISH_OWNER_USER_ID 已废弃；供应商登录与 Jellyfish API Key 相互独立。
运行数据默认位于 data/runtime，Docker 通过 /app/data 持久化。备份时同时保留数据库、凭据 vault 和加密密钥。主机管理 key 默认位于本机 config/superadmin.key 或 Docker /app/data/superadmin.key；自定义 JELLYFISH_SUPERADMIN_KEY_FILE 时必须给后端与 key CLI 提供相同的进程环境变量。local 后端只面向可信团队；把整套应用放进 Docker 不等于每租户容器隔离。