> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shannon.run/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置参考

> Shannon 的完整环境变量和配置选项

## 概述

Shannon 通过**环境变量**和 **YAML 配置文件**进行配置。本指南记录了所有可用的配置选项。

## 配置文件

Shannon 使用多种配置方式：

1. **`.env` 文件**：环境变量（本文档）
2. **`config/features.yaml`**：功能标志和开关
3. **`config/models.yaml`**：LLM 模型定义和定价
4. **Docker Compose**：服务编排和网络配置

### 设置

```bash theme={null}
# 从模板创建 .env 文件
cp .env.example .env

# 编辑您的配置值
nano .env

# 应用更改
docker compose down
docker compose up -d
```

***

## 核心运行时

所有部署的基本变量。

| 变量             | 类型      | 默认值                   | 描述                           |
| -------------- | ------- | --------------------- | ---------------------------- |
| `ENVIRONMENT`  | string  | `dev`                 | 运行时环境：`dev`、`staging`、`prod` |
| `DEBUG`        | boolean | `false`               | 启用调试日志                       |
| `SERVICE_NAME` | string  | `shannon-llm-service` | 日志和指标的服务标识符                  |

**示例**：

```bash theme={null}
ENVIRONMENT=prod
DEBUG=false
SERVICE_NAME=shannon-production
```

***

## LLM 提供商 API 密钥

**至少必须配置一个提供商。**

| 变量                  | 提供商                | 必需  | 格式           |
| ------------------- | ------------------ | --- | ------------ |
| `OPENAI_API_KEY`    | OpenAI             | 条件性 | `sk-...`     |
| `ANTHROPIC_API_KEY` | Anthropic (Claude) | 条件性 | `sk-ant-...` |
| `GOOGLE_API_KEY`    | Google (Gemini)    | 条件性 | `AIza...`    |
| `GROQ_API_KEY`      | Groq               | 否   | `gsk_...`    |
| `XAI_API_KEY`       | xAI (Grok)         | 否   | Custom       |
| `DEEPSEEK_API_KEY`  | DeepSeek           | 否   | Custom       |
| `QWEN_API_KEY`      | Qwen               | 否   | Custom       |
| `MISTRAL_API_KEY`   | Mistral            | 否   | Custom       |
| `ZAI_API_KEY`       | ZAI                | 否   | Custom       |

**AWS Bedrock 配置**：

| 变量                      | 默认值         | 描述                 |
| ----------------------- | ----------- | ------------------ |
| `AWS_ACCESS_KEY_ID`     | -           | Bedrock 的 AWS 访问密钥 |
| `AWS_SECRET_ACCESS_KEY` | -           | AWS 密钥             |
| `AWS_REGION`            | `us-east-1` | AWS 区域             |

**示例**：

```bash theme={null}
OPENAI_API_KEY=sk-proj-abc123...
ANTHROPIC_API_KEY=sk-ant-xyz789...
AWS_REGION=us-west-2
```

**测试 API 密钥**：

```bash theme={null}
# 测试 OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# 测试 Anthropic
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-3-sonnet-20240229","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'
```

***

## 网络搜索提供商

可选但**强烈推荐**用于研究和数据收集任务。

| 变量                    | 类型     | 默认值       | 选项                                                   |
| --------------------- | ------ | --------- | ---------------------------------------------------- |
| `WEB_SEARCH_PROVIDER` | string | `serpapi` | `google`、`serper`、`serpapi`、`bing`、`exa`、`firecrawl` |

**提供商特定密钥**：

| 变量                        | 提供商       | 获取密钥地址                                                                     |
| ------------------------- | --------- | -------------------------------------------------------------------------- |
| `GOOGLE_SEARCH_API_KEY`   | Google    | [Google Cloud Console](https://console.cloud.google.com/)                  |
| `GOOGLE_SEARCH_ENGINE_ID` | Google    | [Programmable Search Engine](https://programmablesearchengine.google.com/) |
| `SERPER_API_KEY`          | Serper    | [serper.dev](https://serper.dev)                                           |
| `BING_API_KEY`            | Bing      | [Azure Portal](https://portal.azure.com/)                                  |
| `EXA_API_KEY`             | Exa       | [exa.ai](https://exa.ai)                                                   |
| `FIRECRAWL_API_KEY`       | Firecrawl | [firecrawl.dev](https://firecrawl.dev)                                     |

**示例**：

```bash theme={null}
WEB_SEARCH_PROVIDER=serpapi
SERPAPI_API_KEY=your-serpapi-key
```

***

## 数据存储

PostgreSQL、Redis 和 Qdrant 的配置。

### PostgreSQL

| 变量                  | 类型      | 默认值        | 描述                                       |
| ------------------- | ------- | ---------- | ---------------------------------------- |
| `POSTGRES_HOST`     | string  | `postgres` | 数据库主机名                                   |
| `POSTGRES_PORT`     | integer | `5432`     | 数据库端口                                    |
| `POSTGRES_DB`       | string  | `shannon`  | 数据库名称                                    |
| `POSTGRES_USER`     | string  | `shannon`  | 数据库用户名                                   |
| `POSTGRES_PASSWORD` | string  | `shannon`  | 数据库密码                                    |
| `POSTGRES_SSLMODE`  | string  | `disable`  | SSL 模式：`disable`、`require`、`verify-full` |
| `DB_MAX_OPEN_CONNS` | integer | `25`       | 最大打开连接数                                  |
| `DB_MAX_IDLE_CONNS` | integer | `5`        | 最大空闲连接数                                  |

### Redis

| 变量                  | 类型      | 默认值                  | 描述                  |
| ------------------- | ------- | -------------------- | ------------------- |
| `REDIS_HOST`        | string  | `redis`              | Redis 主机名           |
| `REDIS_PORT`        | integer | `6379`               | Redis 端口            |
| `REDIS_PASSWORD`    | string  | ` `                  | Redis 密码（空 = 无认证）   |
| `REDIS_TTL_SECONDS` | integer | `3600`               | 缓存项的默认 TTL（1 小时）    |
| `REDIS_ADDR`        | string  | `redis:6379`         | Redis 地址（host:port） |
| `REDIS_URL`         | string  | `redis://redis:6379` | Redis 连接 URL        |
| `LLM_REDIS_URL`     | string  | -                    | LLM 缓存专用 Redis（可选）  |

### Qdrant（向量数据库）

| 变量            | 类型      | 默认值                  | 描述             |
| ------------- | ------- | -------------------- | -------------- |
| `QDRANT_URL`  | string  | `http://qdrant:6333` | Qdrant HTTP 端点 |
| `QDRANT_HOST` | string  | `qdrant`             | Qdrant 主机名     |
| `QDRANT_PORT` | integer | `6333`               | Qdrant 端口      |

**示例**：

```bash theme={null}
# PostgreSQL
POSTGRES_HOST=db.example.com
POSTGRES_PORT=5432
POSTGRES_PASSWORD=secure_password_here

# Redis（带认证）
REDIS_HOST=redis.example.com
REDIS_PASSWORD=redis_password_here
REDIS_TTL_SECONDS=7200  # 2 小时

# Qdrant
QDRANT_URL=http://vector-db.example.com:6333
```

***

## 服务端点

内部服务通信的 URL。

| 变量                     | 默认值                               | 描述                    |
| ---------------------- | --------------------------------- | --------------------- |
| `TEMPORAL_HOST`        | `temporal:7233`                   | Temporal 工作流引擎        |
| `LLM_SERVICE_URL`      | `http://llm-service:8000`         | Python LLM 服务 HTTP 端点 |
| `AGENT_CORE_ADDR`      | `agent-core:50051`                | Rust 代理核心 gRPC 端点     |
| `ADMIN_SERVER`         | `http://orchestrator:8081`        | 编排器管理 API             |
| `ORCHESTRATOR_GRPC`    | `orchestrator:50052`              | 编排器 gRPC 端点           |
| `EVENTS_INGEST_URL`    | `http://orchestrator:8081/events` | 事件摄取端点                |
| `EVENTS_AUTH_TOKEN`    | -                                 | 事件摄取认证令牌              |
| `APPROVALS_AUTH_TOKEN` | -                                 | 审批 webhook 认证令牌       |

**配置文件路径**：

| 变量                   | 默认值                      | 描述      |
| -------------------- | ------------------------ | ------- |
| `CONFIG_PATH`        | `./config/features.yaml` | 功能标志配置  |
| `MODELS_CONFIG_PATH` | `./config/models.yaml`   | 模型定义和定价 |

***

## 模型路由和预算

控制 LLM 选择、令牌限制和成本管理。

| 变量                              | 类型      | 默认值                          | 描述                                |
| ------------------------------- | ------- | ---------------------------- | --------------------------------- |
| `DEFAULT_MODEL_TIER`            | string  | `small`                      | 默认模型大小：`small`、`medium`、`large`   |
| `COMPLEXITY_MODEL_ID`           | string  | `gpt-5`                      | 复杂度分析模型                           |
| `DECOMPOSITION_MODEL_ID`        | string  | `claude-sonnet-4-5-20250929` | 任务分解模型                            |
| `MAX_TOKENS`                    | integer | `2000`                       | 默认最大输出令牌数                         |
| `TEMPERATURE`                   | float   | `0.7`                        | 默认采样温度（0.0-1.0）                   |
| `MAX_TOKENS_PER_REQUEST`        | integer | `10000`                      | 每个 API 请求的最大令牌数                   |
| `MAX_COST_PER_REQUEST`          | float   | `0.50`                       | 每个请求的最大成本（美元）                     |
| `LLM_DISABLE_BUDGETS`           | integer | `1`                          | `1` = 编排器管理预算，`0` = 在 LLM 服务中强制执行 |
| `HISTORY_WINDOW_MESSAGES`       | integer | `50`                         | 包含的历史消息数量                         |
| `HISTORY_WINDOW_DEBUG_MESSAGES` | integer | `75`                         | 调试模式下的历史消息数                       |
| `WORKFLOW_SYNTH_BYPASS_SINGLE`  | boolean | `true`                       | 跳过单结果任务的合成                        |
| `TOKEN_BUDGET_PER_AGENT`        | integer | -                            | 每个代理的令牌限制                         |
| `TOKEN_BUDGET_PER_TASK`         | integer | -                            | 每个任务的令牌限制                         |

**示例 - 成本优化**：

```bash theme={null}
DEFAULT_MODEL_TIER=small
MAX_COST_PER_REQUEST=0.10
MAX_TOKENS_PER_REQUEST=5000
TEMPERATURE=0.5
```

**示例 - 高质量**：

```bash theme={null}
DEFAULT_MODEL_TIER=large
MAX_COST_PER_REQUEST=2.00
MAX_TOKENS_PER_REQUEST=50000
TEMPERATURE=0.7
```

***

## 缓存和速率限制

通过缓存和速率限制进行性能和成本优化。

| 变量                           | 类型      | 默认值    | 描述               |
| ---------------------------- | ------- | ------ | ---------------- |
| `ENABLE_CACHE`               | boolean | `true` | 启用 LLM 响应缓存      |
| `CACHE_SIMILARITY_THRESHOLD` | float   | `0.95` | 语义相似度阈值（0.0-1.0） |
| `RATE_LIMIT_REQUESTS`        | integer | `100`  | 每个时间窗口的请求数       |
| `RATE_LIMIT_WINDOW`          | integer | `60`   | 速率限制窗口（秒）        |
| `WEB_SEARCH_RATE_LIMIT`      | integer | `120`  | 每分钟网络搜索请求数       |
| `CALCULATOR_RATE_LIMIT`      | integer | `2000` | 每分钟计算器工具请求数      |
| `PYTHON_EXECUTOR_RATE_LIMIT` | integer | `60`   | 每分钟 Python 执行请求数 |
| `PARTIAL_CHUNK_CHARS`        | integer | `512`  | 流式传输块大小（字符）      |

**缓存行为**：

* 响应按**语义相似度**缓存
* 缓存键：SHA256 哈希（提示 + 模型 + 温度）
* TTL：由 `REDIS_TTL_SECONDS` 控制

**示例**：

```bash theme={null}
ENABLE_CACHE=true
CACHE_SIMILARITY_THRESHOLD=0.98  # 更高 = 更精确的匹配
RATE_LIMIT_REQUESTS=200
RATE_LIMIT_WINDOW=60
```

***

## 工具执行和工作流控制

微调并行性、超时和执行行为。

| 变量                          | 类型      | 默认值     | 范围      | 描述                 |
| --------------------------- | ------- | ------- | ------- | ------------------ |
| `TOOL_PARALLELISM`          | integer | `1`     | 1-10    | 并发工具执行数（1=顺序）      |
| `ENABLE_TOOL_SELECTION`     | integer | `1`     | 0,1     | `1`=自动工具选择，`0`=仅手动 |
| `PRIORITY_QUEUES`           | string  | `off`   | on/off  | 启用基于优先级的任务队列       |
| `STREAMING_RING_CAPACITY`   | integer | `1000`  | -       | 事件流缓冲区大小           |
| `COMPRESSION_TRIGGER_RATIO` | float   | `0.75`  | 0.0-1.0 | 上下文压缩触发阈值          |
| `COMPRESSION_TARGET_RATIO`  | float   | `0.375` | 0.0-1.0 | 目标压缩比率             |
| `ENFORCE_TIMEOUT_SECONDS`   | integer | `90`    | -       | 操作的硬超时             |
| `ENFORCE_MAX_TOKENS`        | integer | `32768` | -       | 绝对最大令牌数            |
| `ENFORCE_RATE_RPS`          | integer | `20`    | -       | 每秒请求数限制            |

**断路器设置**：

| 变量                           | 类型      | 默认值   | 描述             |
| ---------------------------- | ------- | ----- | -------------- |
| `ENFORCE_CB_ERROR_THRESHOLD` | float   | `0.5` | 打开断路器的错误率（50%） |
| `ENFORCE_CB_WINDOW_SECONDS`  | integer | `30`  | 错误率的滑动窗口       |
| `ENFORCE_CB_MIN_REQUESTS`    | integer | `20`  | 打开断路器前的最小请求数   |

**性能调优**：

```bash theme={null}
# 高吞吐量
TOOL_PARALLELISM=10
ENFORCE_RATE_RPS=50

# 保守/低资源
TOOL_PARALLELISM=2
ENFORCE_RATE_RPS=10
```

***

## 审批和安全

人工参与和认证设置。

| 变量                              | 类型      | 默认值                                            | 描述                        |
| ------------------------------- | ------- | ---------------------------------------------- | ------------------------- |
| `APPROVAL_ENABLED`              | boolean | `false`                                        | 启用人工审批工作流                 |
| `APPROVAL_COMPLEXITY_THRESHOLD` | float   | `0.5`                                          | 需要审批的复杂度分数（0.0-1.0）       |
| `APPROVAL_DANGEROUS_TOOLS`      | string  | `file_system,code_execution`                   | 需要审批的工具（逗号分隔）             |
| `APPROVAL_TIMEOUT_SECONDS`      | integer | `1800`                                         | 审批等待超时（30 分钟）             |
| `JWT_SECRET`                    | string  | `development-only-secret-change-in-production` | JWT 签名密钥（⚠️ **在生产环境中更改**） |
| `GATEWAY_SKIP_AUTH`             | integer | `1`                                            | `1`=禁用认证，`0`=启用认证         |

**安全最佳实践**：

```bash theme={null}
# 生产设置
APPROVAL_ENABLED=true
APPROVAL_DANGEROUS_TOOLS=file_system,code_execution,shell,network_access
JWT_SECRET=$(openssl rand -base64 64)
GATEWAY_SKIP_AUTH=0
```

**开发设置**：

```bash theme={null}
# 快速迭代（⚠️ 不适用于生产环境）
APPROVAL_ENABLED=false
GATEWAY_SKIP_AUTH=1
```

***

## Python WASI 沙箱

安全的 Python 代码执行环境。

| 变量                            | 类型      | 默认值                                      | 描述                |
| ----------------------------- | ------- | ---------------------------------------- | ----------------- |
| `PYTHON_WASI_WASM_PATH`       | string  | `./wasm-interpreters/python-3.11.4.wasm` | Python WASI 解释器路径 |
| `PYTHON_WASI_SESSION_TIMEOUT` | integer | `3600`                                   | 会话超时（秒）           |
| `WASI_MEMORY_LIMIT_MB`        | integer | `512`                                    | 每次执行的内存限制（MB）     |
| `WASI_TIMEOUT_SECONDS`        | integer | `60`                                     | 每次运行的执行超时         |

**设置**：

```bash theme={null}
# 下载 Python WASI 解释器（20MB）
./scripts/setup_python_wasi.sh

# 验证
ls -lh wasm-interpreters/python-3.11.4.wasm
```

**调优**：

```bash theme={null}
# 严格限制（基本脚本）
WASI_MEMORY_LIMIT_MB=256
WASI_TIMEOUT_SECONDS=30

# 宽松限制（数据处理）
WASI_MEMORY_LIMIT_MB=1024
WASI_TIMEOUT_SECONDS=300
```

***

## OpenAPI 和 MCP 集成

外部工具和 API 集成设置。

### OpenAPI 工具

| 变量                        | 类型      | 默认值       | 描述                   |
| ------------------------- | ------- | --------- | -------------------- |
| `OPENAPI_ALLOWED_DOMAINS` | string  | `*`       | 允许的域名（`*` 或逗号分隔）     |
| `OPENAPI_MAX_SPEC_SIZE`   | integer | `5242880` | 最大 OpenAPI 规范大小（5MB） |
| `OPENAPI_FETCH_TIMEOUT`   | integer | `30`      | 规范获取超时（秒）            |
| `OPENAPI_RETRIES`         | integer | `2`       | 重试次数                 |

### MCP（模型上下文协议）

| 变量                        | 类型      | 默认值        | 描述            |
| ------------------------- | ------- | ---------- | ------------- |
| `MCP_ALLOWED_DOMAINS`     | string  | `*`        | 允许的 MCP 域名    |
| `MCP_MAX_RESPONSE_BYTES`  | integer | `10485760` | 最大响应大小（10MB）  |
| `MCP_RETRIES`             | integer | `3`        | 重试次数          |
| `MCP_TIMEOUT_SECONDS`     | integer | `10`       | 请求超时          |
| `MCP_REGISTER_TOKEN`      | string  | -          | 注册认证令牌        |
| `MCP_RATE_LIMIT_DEFAULT`  | integer | `60`       | 默认速率限制（请求/分钟） |
| `MCP_CB_FAILURES`         | integer | `5`        | 断路器失败阈值       |
| `MCP_CB_RECOVERY_SECONDS` | integer | `60`       | 断路器恢复时间       |
| `MCP_COST_TO_TOKENS`      | integer | `0`        | 成本到令牌的转换      |

**示例 - 受限**：

```bash theme={null}
OPENAPI_ALLOWED_DOMAINS=api.example.com,api.partner.com
MCP_ALLOWED_DOMAINS=mcp.trusted.com
MCP_REGISTER_TOKEN=secret_token_here
```

***

## 可观测性和遥测

指标、跟踪和日志配置。

| 变量                            | 类型      | 默认值                   | 描述                    |
| ----------------------------- | ------- | --------------------- | --------------------- |
| `OTEL_SERVICE_NAME`           | string  | `shannon-llm-service` | OpenTelemetry 服务名称    |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | string  | `localhost:4317`      | OTLP 端点               |
| `OTEL_ENABLED`                | boolean | `false`               | 启用 OpenTelemetry 追踪   |
| `LOG_FORMAT`                  | string  | `plain`               | 日志格式：`plain` 或 `json` |
| `METRICS_PORT`                | integer | `2112`                | Prometheus 指标端口       |

**Prometheus 端点**：

* 编排器：`http://localhost:2112/metrics`
* 代理核心：`http://localhost:2113/metrics`
* LLM 服务：`http://localhost:8000/metrics`

**示例 - 生产可观测性**：

```bash theme={null}
OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=otel-collector:4317
LOG_FORMAT=json
METRICS_PORT=2112
```

***

## 高级编排器控制

Temporal worker 和编排器行为的底层调优。

### Worker 并发

| 变量                    | 类型      | 默认值  | 描述                         |
| --------------------- | ------- | ---- | -------------------------- |
| `WORKER_ACT`          | integer | -    | Activity worker 并发数（所有优先级） |
| `WORKER_WF`           | integer | -    | Workflow worker 并发数（所有优先级） |
| `WORKER_ACT_CRITICAL` | integer | `10` | 关键优先级 activity worker 数    |
| `WORKER_WF_CRITICAL`  | integer | `5`  | 关键优先级 workflow worker 数    |
| `WORKER_ACT_HIGH`     | integer | -    | 高优先级 activity worker 数     |
| `WORKER_WF_HIGH`      | integer | -    | 高优先级 workflow worker 数     |
| `WORKER_ACT_NORMAL`   | integer | -    | 正常优先级 activity worker 数    |
| `WORKER_WF_NORMAL`    | integer | -    | 正常优先级 workflow worker 数    |
| `WORKER_ACT_LOW`      | integer | -    | 低优先级 activity worker 数     |
| `WORKER_WF_LOW`       | integer | -    | 低优先级 workflow worker 数     |

### 事件和断路器设置

| 变量                           | 类型      | 默认值     | 描述          |
| ---------------------------- | ------- | ------- | ----------- |
| `EVENTLOG_BATCH_SIZE`        | integer | `100`   | 事件批处理大小     |
| `EVENTLOG_BATCH_INTERVAL_MS` | integer | `100`   | 事件批处理间隔（毫秒） |
| `RATE_LIMIT_INTERVAL_MS`     | integer | `60000` | 速率限制窗口（毫秒）  |
| `BACKPRESSURE_THRESHOLD`     | integer | -       | 背压触发阈值      |
| `MAX_BACKPRESSURE_DELAY_MS`  | integer | -       | 最大背压延迟      |
| `CIRCUIT_FAILURE_THRESHOLD`  | integer | -       | 断路器失败计数     |
| `CIRCUIT_HALF_OPEN_REQUESTS` | integer | -       | 半开状态测试请求数   |
| `CIRCUIT_RESET_TIMEOUT_MS`   | integer | -       | 断路器重置超时     |
| `LLM_TIMEOUT_SECONDS`        | integer | `120`   | LLM 请求超时    |

**性能调优**：

```bash theme={null}
# 高负载
WORKER_ACT_CRITICAL=20
WORKER_WF_CRITICAL=10
EVENTLOG_BATCH_SIZE=500

# 低资源
WORKER_ACT_CRITICAL=5
WORKER_WF_CRITICAL=3
EVENTLOG_BATCH_SIZE=50
```

***

## 杂项

其他配置选项。

| 变量                          | 类型      | 默认值           | 描述                   |
| --------------------------- | ------- | ------------- | -------------------- |
| `SHANNON_WORKSPACE`         | string  | `./workspace` | 文件操作的工作空间目录          |
| `SEED_DATA`                 | boolean | `false`       | 启动时在 Qdrant 中填充示例数据  |
| `AGENT_TIMEOUT_SECONDS`     | integer | `600`         | 每个代理执行的最大运行时间（10 分钟） |
| `TEMPLATE_FALLBACK_ENABLED` | boolean | `false`       | 如果模板执行失败则回退到 AI      |

***

## 配置配置文件

### 开发配置文件

```bash theme={null}
# .env.dev
ENVIRONMENT=dev
DEBUG=true
GATEWAY_SKIP_AUTH=1
APPROVAL_ENABLED=false
LOG_FORMAT=plain
MAX_COST_PER_REQUEST=0.10
LLM_DISABLE_BUDGETS=1
OTEL_ENABLED=false
```

### 预发布配置文件

```bash theme={null}
# .env.staging
ENVIRONMENT=staging
DEBUG=false
GATEWAY_SKIP_AUTH=0
APPROVAL_ENABLED=true
LOG_FORMAT=json
MAX_COST_PER_REQUEST=1.00
LLM_DISABLE_BUDGETS=0
OTEL_ENABLED=true
JWT_SECRET=$(openssl rand -base64 64)
```

### 生产配置文件

```bash theme={null}
# .env.prod
ENVIRONMENT=prod
DEBUG=false
GATEWAY_SKIP_AUTH=0
APPROVAL_ENABLED=true
APPROVAL_DANGEROUS_TOOLS=file_system,code_execution,shell,network_access
LOG_FORMAT=json
MAX_COST_PER_REQUEST=2.00
LLM_DISABLE_BUDGETS=0
OTEL_ENABLED=true
JWT_SECRET=$(openssl rand -base64 64)
POSTGRES_SSLMODE=require
REDIS_PASSWORD=secure_password
# 添加强密码并限制域名
OPENAPI_ALLOWED_DOMAINS=api.trusted.com
MCP_ALLOWED_DOMAINS=mcp.trusted.com
```

***

## 热重载支持

大多数配置更改需要重启服务：

```bash theme={null}
# 编辑 .env 后
docker compose restart orchestrator
docker compose restart agent-core
docker compose restart llm-service
docker compose restart gateway
```

**自动重载的服务**：

* ✅ 功能标志（`config/features.yaml`）
* ✅ 模型配置（`config/models.yaml`）

**需要重启的服务**：

* ❌ 环境变量（`.env`）
* ❌ 数据库凭证
* ❌ 服务端点

***

## 验证和测试

### 验证配置

```bash theme={null}
# 检查加载的环境变量
docker compose exec orchestrator env | sort

# 测试数据库连接
docker compose exec postgres psql -U shannon -d shannon -c "SELECT 1;"

# 测试 Redis 连接
docker compose exec redis redis-cli ping

# 测试 API 端点
curl http://localhost:8080/health
curl http://localhost:8000/health
```

### 配置调试

```bash theme={null}
# 查看服务日志
docker compose logs orchestrator | grep -i "config\|environment"

# 检查错误
docker compose logs orchestrator | grep -i "error\|warning"

# 验证 YAML 语法
docker compose config
```

***

## 安全检查清单

<AccordionGroup>
  <Accordion title="生产部署检查清单">
    * [ ] 将 `JWT_SECRET` 更改为强随机值
    * [ ] 启用认证（`GATEWAY_SKIP_AUTH=0`）
    * [ ] 设置强数据库密码
    * [ ] 启用 Redis 认证
    * [ ] 为 PostgreSQL 使用 SSL（`POSTGRES_SSLMODE=require`）
    * [ ] 启用审批（`APPROVAL_ENABLED=true`）
    * [ ] 限制 `OPENAPI_ALLOWED_DOMAINS`
    * [ ] 限制 `MCP_ALLOWED_DOMAINS`
    * [ ] 启用结构化日志（`LOG_FORMAT=json`）
    * [ ] 设置监控（`OTEL_ENABLED=true`）
    * [ ] 适当配置预算限制
    * [ ] 根据负载审查 worker 并发性
    * [ ] 安全备份 `.env` 文件
  </Accordion>
</AccordionGroup>

***

## 相关主题

<CardGroup cols={2}>
  <Card title="安装" icon="download" href="/cn/quickstart/installation">
    初始设置指南
  </Card>

  <Card title="故障排除" icon="wrench" href="/cn/quickstart/troubleshooting">
    常见配置问题
  </Card>

  <Card title="成本控制" icon="dollar" href="/cn/quickstart/concepts/cost-control">
    预算管理
  </Card>

  <Card title="监控" icon="chart-line" href="/cn/quickstart/concepts/monitoring">
    可观测性设置
  </Card>
</CardGroup>