配置参考 - Shannon

概述

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

配置文件

Shannon 使用多种配置方式：

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

设置

# 从模板创建 .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`	日志和指标的服务标识符

示例：

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 区域

示例：

OPENAI_API_KEY=sk-proj-abc123...
ANTHROPIC_API_KEY=sk-ant-xyz789...
AWS_REGION=us-west-2

测试 API 密钥：

# 测试 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	`google`	`google`、`serper`、`bing`、`exa`、`firecrawl`

提供商特定密钥：

变量	提供商	获取密钥地址
`GOOGLE_SEARCH_API_KEY`	Google	Google Cloud Console
`GOOGLE_SEARCH_ENGINE_ID`	Google	Programmable Search Engine
`SERPER_API_KEY`	Serper	serper.dev
`BING_API_KEY`	Bing	Azure Portal
`EXA_API_KEY`	Exa	exa.ai
`FIRECRAWL_API_KEY`	Firecrawl	firecrawl.dev

示例：

WEB_SEARCH_PROVIDER=google
GOOGLE_SEARCH_API_KEY=AIzaSyAbc123...
GOOGLE_SEARCH_ENGINE_ID=0123456789abcdef

数据存储

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 端口

示例：

# 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-20250514`	任务分解模型
`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	-	每个任务的令牌限制

示例 - 成本优化：

DEFAULT_MODEL_TIER=small
MAX_COST_PER_REQUEST=0.10
MAX_TOKENS_PER_REQUEST=5000
TEMPERATURE=0.5

示例 - 高质量：

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 控制

示例：

ENABLE_CACHE=true
CACHE_SIMILARITY_THRESHOLD=0.98  # 更高 = 更精确的匹配
RATE_LIMIT_REQUESTS=200
RATE_LIMIT_WINDOW=60

工具执行和工作流控制

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

变量	类型	默认值	范围	描述
`TOOL_PARALLELISM`	integer	`5`	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`	打开断路器前的最小请求数

性能调优：

# 高吞吐量
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	`7200`	审批等待超时（2 小时）
`JWT_SECRET`	string	`development-only-secret-change-in-production`	JWT 签名密钥（⚠️ 在生产环境中更改）
`GATEWAY_SKIP_AUTH`	integer	`1`	`1`=禁用认证，`0`=启用认证

安全最佳实践：

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

开发设置：

# 快速迭代（⚠️ 不适用于生产环境）
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`	每次运行的执行超时

设置：

# 下载 Python WASI 解释器（20MB）
./scripts/setup_python_wasi.sh

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

调优：

# 严格限制（基本脚本）
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	`3`	重试次数

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`	成本到令牌的转换

示例 - 受限：

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

示例 - 生产可观测性：

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 请求超时

性能调优：

# 高负载
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

配置配置文件

开发配置文件

# .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

预发布配置文件

# .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)

生产配置文件

# .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

热重载支持

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

# 编辑 .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）
❌ 数据库凭证
❌ 服务端点

验证和测试

验证配置

# 检查加载的环境变量
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

配置调试

# 查看服务日志
docker compose logs orchestrator | grep -i "config\|environment"

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

# 验证 YAML 语法
docker compose config

安全检查清单

生产部署检查清单

安装

初始设置指南

故障排除

常见配置问题

成本控制

预算管理

监控

可观测性设置

入门指南

核心概念

指南

​概述

​配置文件

​设置

​核心运行时

​LLM 提供商 API 密钥

​网络搜索提供商

​数据存储

​PostgreSQL

​Redis

​Qdrant（向量数据库）

​服务端点

​模型路由和预算

​缓存和速率限制

​工具执行和工作流控制

​审批和安全

​Python WASI 沙箱

​OpenAPI 和 MCP 集成

​OpenAPI 工具

​MCP（模型上下文协议）

​可观测性和遥测

​高级编排器控制

​Worker 并发

​事件和断路器设置

​杂项

​配置配置文件

​开发配置文件

​预发布配置文件

​生产配置文件

​热重载支持

​验证和测试

​验证配置

​配置调试

​安全检查清单

​相关主题

安装