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

# 配置故障排除

> 常见配置问题和解决方案

## 概述

本指南涵盖常见配置问题、如何诊断以及行之有效的解决方案。

## 快速诊断

### 检查环境变量

```bash theme={null}
# 查看服务的所有环境变量
docker compose exec orchestrator env | sort

# 检查特定变量
docker compose exec orchestrator env | grep MAX_COST_PER_REQUEST

# 检查变量是否已设置
docker compose exec orchestrator printenv MAX_COST_PER_REQUEST
```

### 验证配置文件

```bash theme={null}
# 检查配置文件是否存在
docker compose exec orchestrator ls -la ./config/

# 查看配置文件内容
docker compose exec orchestrator cat ./config/features.yaml

# 检查语法错误
docker compose exec orchestrator cat ./config/models.yaml | yq .
```

### 检查服务健康状态

```bash theme={null}
# Gateway 健康检查
curl http://localhost:8080/health

# Orchestrator 指标
curl http://localhost:2112/metrics

# Agent Core 健康检查
grpcurl -plaintext localhost:50051 list
```

## 常见问题

### 1. 服务无法启动

#### 缺少环境变量

**症状**:

* 服务立即崩溃
* 日志显示 "variable not set" 错误
* 容器以代码 1 退出

**诊断**:

```bash theme={null}
docker compose logs orchestrator | grep -i "not set\|missing\|required"
```

**解决方案**:

```bash theme={null}
# 检查 .env 文件是否存在
ls -la .env

# 验证必需的变量已设置
grep -E "OPENAI_API_KEY|POSTGRES" .env

# 如果缺失则从示例复制
cp .env.example .env
nano .env  # 填入必需的值

# 重启服务
docker compose restart
```

**必需变量**:

* 至少一个 LLM 提供商密钥 (OPENAI\_API\_KEY, ANTHROPIC\_API\_KEY 等)
* 数据库凭据 (POSTGRES\_\*)
* Redis 连接 (REDIS\_\*)

#### 无效的配置语法

**症状**:

* "Failed to parse config" 错误
* YAML 语法错误
* 服务启动失败

**诊断**:

```bash theme={null}
# 检查 YAML 语法
docker compose exec orchestrator cat ./config/features.yaml | yq .
```

**解决方案**:

```bash theme={null}
# 本地验证 YAML
yq eval ./config/features.yaml

# 检查常见问题
cat ./config/features.yaml | grep -E "^\s+- |^\w+:"

# 重置为默认值
cp ./config/features.yaml.example ./config/features.yaml
```

### 2. 身份认证失败

#### Gateway 返回 401 未授权

**症状**:

* 所有请求返回 401
* "Unauthorized" 错误
* API 密钥被拒绝

**诊断**:

```bash theme={null}
# 检查是否启用了身份认证
docker compose exec gateway env | grep GATEWAY_SKIP_AUTH

# 使用 curl 测试
curl -v http://localhost:8080/api/v1/tasks \
  -H "X-API-Key: sk_test_123456" 2>&1 | grep "401"
```

**解决方案 1**: 为开发环境禁用身份认证

```bash theme={null}
# 添加到 .env
GATEWAY_SKIP_AUTH=1

# 重启 gateway
docker compose restart gateway

# 测试
curl http://localhost:8080/api/v1/tasks
```

**解决方案 2**: 使用有效的 API 密钥

```bash theme={null}
# 在数据库中插入 API 密钥
docker compose exec postgres psql -U shannon -d shannon -c "
INSERT INTO auth.api_keys (key, user_id, tenant_id, name, enabled)
VALUES ('sk_test_123456', gen_random_uuid(), gen_random_uuid(), 'Test Key', true);
"

# 使用密钥测试
curl -H "X-API-Key: sk_test_123456" \
  http://localhost:8080/api/v1/tasks
```

#### JWT 密钥未设置

**症状**:

* "JWT secret not configured" 错误
* 身份认证中间件失败

**解决方案**:

```bash theme={null}
# 生成安全密钥
JWT_SECRET=$(openssl rand -base64 32)

# 添加到 .env
echo "JWT_SECRET=$JWT_SECRET" >> .env

# 重启 gateway
docker compose restart gateway
```

### 3. 数据库连接问题

#### 无法连接到 PostgreSQL

**症状**:

* "connection refused" 错误
* "dial tcp: connect: connection refused"
* 服务启动时崩溃

**诊断**:

```bash theme={null}
# 检查 PostgreSQL 是否运行
docker compose ps postgres

# 检查 PostgreSQL 日志
docker compose logs postgres --tail=50

# 测试连接
docker compose exec postgres pg_isready -U shannon
```

**解决方案 1**: PostgreSQL 未启动

```bash theme={null}
# 启动 PostgreSQL
docker compose up -d postgres

# 等待就绪
docker compose exec postgres pg_isready -U shannon

# 重启依赖服务
docker compose restart gateway orchestrator
```

**解决方案 2**: 凭据错误

```bash theme={null}
# 验证 .env 设置
grep POSTGRES .env

# 应与 docker-compose.yml 匹配
docker compose exec postgres psql -U shannon -d shannon -c "SELECT 1;"

# 如果密码错误,更新 .env 并重启
docker compose down
docker compose up -d
```

**解决方案 3**: 端口冲突

```bash theme={null}
# 检查端口 5432 是否被占用
lsof -i :5432

# 如果冲突,在 .env 中更改端口
POSTGRES_PORT=5433

# 更新 docker-compose.yml
# 重启
docker compose down
docker compose up -d
```

#### 数据库架构未初始化

**症状**:

* "table does not exist" 错误
* "column not found" 错误
* 日志中的 SQL 错误

**解决方案**:

```bash theme={null}
# 运行迁移
docker compose exec orchestrator make migrate

# 或重置数据库 (⚠️ 破坏性操作)
docker compose down -v
docker compose up -d
```

### 4. Redis 连接问题

#### 无法连接到 Redis

**症状**:

* Redis "connection refused"
* 会话状态不持久
* 缓存未命中

**诊断**:

```bash theme={null}
# 检查 Redis 状态
docker compose ps redis

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

# 检查日志
docker compose logs redis --tail=20
```

**解决方案**:

```bash theme={null}
# 启动 Redis
docker compose up -d redis

# 测试连接
docker compose exec redis redis-cli ping
# 应返回: PONG

# 重启依赖服务
docker compose restart gateway orchestrator llm-service
```

#### Redis 认证失败

**症状**:

* "NOAUTH Authentication required"
* 连接正常但命令失败

**解决方案**:

```bash theme={null}
# 检查是否设置了密码
docker compose exec redis redis-cli CONFIG GET requirepass

# 如果需要密码,添加到 .env
REDIS_PASSWORD=your-password

# 或禁用认证 (仅开发环境)
docker compose exec redis redis-cli CONFIG SET requirepass ""

# 重启服务
docker compose restart
```

### 5. LLM 提供商问题

#### API 密钥无效或过期

**症状**:

* "Invalid API key" 错误
* LLM 提供商返回 401
* 任务立即失败

**诊断**:

```bash theme={null}
# 检查配置了哪个提供商
docker compose exec llm-service env | grep API_KEY

# 测试 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 "Content-Type: application/json" \
  -d '{"model":"claude-3-haiku-20240307","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'
```

**解决方案**:

```bash theme={null}
# 在 .env 中更新密钥
OPENAI_API_KEY=sk-...new-key...

# 重启 LLM 服务
docker compose restart llm-service

# 验证
docker compose logs llm-service | grep "API key"
```

#### 超出速率限制

**症状**:

* LLM 提供商返回 429 错误
* 日志中显示 "Rate limit exceeded"
* 任务超时或失败

**解决方案 1**: 等待速率限制重置

```bash theme={null}
# 检查速率限制标头
docker compose logs llm-service | grep "rate"

# 典型重置时间: 大多数提供商为 60 秒
```

**解决方案 2**: 配置速率限制

```bash theme={null}
# 添加到 .env
RATE_LIMIT_REQUESTS=50  # 低于提供商限制
RATE_LIMIT_WINDOW=60

# 重启
docker compose restart llm-service
```

**解决方案 3**: 使用多个提供商

```bash theme={null}
# 在 models.yaml 中配置备用提供商
providers:
  - id: openai
    primary: true
  - id: anthropic
    fallback: true
```

#### 超出配额

**症状**:

* "insufficient\_quota" 错误
* "You exceeded your current quota"
* 所有 LLM 调用失败

**解决方案**:

```bash theme={null}
# 检查配额
# OpenAI: https://platform.openai.com/account/usage
# Anthropic: https://console.anthropic.com/settings/limits

# 添加额度或升级计划
# 或使用不同的提供商
OPENAI_API_KEY=
ANTHROPIC_API_KEY=sk-ant-...

# 重启
docker compose restart llm-service
```

### 6. 模型配置问题

#### 模型未找到

**症状**:

* "model not found" 错误
* "invalid model" 错误
* 任务因模型错误而失败

**诊断**:

```bash theme={null}
# 检查配置的模型
docker compose exec llm-service cat ./config/models.yaml | grep "id:"

# 检查环境变量
docker compose exec orchestrator env | grep MODEL
```

**解决方案**:

```bash theme={null}
# 在 .env 中使用有效的模型 ID
DEFAULT_MODEL_TIER=small
COMPLEXITY_MODEL_ID=gpt-5  # 验证此模型存在
DECOMPOSITION_MODEL_ID=claude-sonnet-4-5-20250929

# 或在 models.yaml 中配置
docker compose exec orchestrator cat ./config/models.yaml

# 重启
docker compose restart orchestrator llm-service
```

### 7. 预算和成本问题

#### 任务超出预算

**症状**:

* "Budget exceeded" 错误
* 任务因成本错误而失败
* 超出 `MAX_COST_PER_REQUEST`

**解决方案**:

```bash theme={null}
# 提高预算限制
# 在 .env 中:
MAX_COST_PER_REQUEST=1.00  # 从 0.50 提高
MAX_TOKENS_PER_REQUEST=20000  # 从 10000 提高

# 重启
docker compose restart orchestrator

# 或使用更便宜的模型
DEFAULT_MODEL_TIER=small  # 使用 GPT-5-nano 代替 GPT-5
```

#### 预算执行未生效

**症状**:

* 成本超出限制
* 没有预算错误

**诊断**:

```bash theme={null}
# 检查预算执行
docker compose exec orchestrator env | grep LLM_DISABLE_BUDGETS
```

**解决方案**:

```bash theme={null}
# 启用预算执行
LLM_DISABLE_BUDGETS=1  # Orchestrator 执行预算

# 设置限制
MAX_COST_PER_REQUEST=0.50
MAX_TOKENS_PER_REQUEST=10000

# 重启
docker compose restart orchestrator
```

### 8. 性能问题

#### 任务执行缓慢

**症状**:

* 任务耗时是预期的 2-3 倍
* 高延迟
* 超时

**诊断**:

```bash theme={null}
# 检查资源使用情况
docker stats

# 检查 worker 并发
docker compose exec orchestrator env | grep WORKER

# 检查工具并行度
docker compose exec orchestrator env | grep TOOL_PARALLELISM
```

**解决方案 1**: 提高并行度

```bash theme={null}
# 在 .env 中:
TOOL_PARALLELISM=10  # 从 5 提高
WORKER_ACT_CRITICAL=20  # 从 10 提高

# 重启
docker compose restart orchestrator
```

**解决方案 2**: 启用缓存

```bash theme={null}
# 在 .env 中:
ENABLE_CACHE=true
CACHE_SIMILARITY_THRESHOLD=0.95

# 重启
docker compose restart llm-service
```

**解决方案 3**: 优化模型选择

```bash theme={null}
# 使用更快的模型
DEFAULT_MODEL_TIER=small  # GPT-5-nano 比 GPT-5 快 10 倍
```

#### 高内存使用

**症状**:

* OOM 错误
* 容器重启
* 高交换区使用

**诊断**:

```bash theme={null}
docker stats
```

**解决方案**:

```bash theme={null}
# 减少缓存大小
HISTORY_WINDOW_MESSAGES=25  # 从 50 减少
STREAMING_RING_CAPACITY=500  # 从 1000 减少

# 限制工具并行度
TOOL_PARALLELISM=3  # 从 5 减少

# 重启
docker compose restart
```

### 9. 流式传输问题

#### SSE 连接断开

**症状**:

* SSE 流断开连接
* 事件在任务执行中途停止
* "Connection closed" 错误

**解决方案 1**: 增加超时时间

```bash theme={null}
# 在 nginx/proxy 配置中:
proxy_read_timeout 600s;
proxy_connect_timeout 600s;

# 在 gateway 的 docker-compose.yml 中:
GATEWAY_READ_TIMEOUT=600
```

**解决方案 2**: 处理重连

```python theme={null}
# 客户端重连
while True:
    try:
        for event in stream_events(task_id):
            process(event)
        break  # 任务完成
    except ConnectionError:
        time.sleep(2)  # 等待并重试
```

#### 未收到事件

**症状**:

* 流中没有事件
* 空的 SSE 响应
* 流连接但没有数据

**诊断**:

```bash theme={null}
# 检查是否正在创建事件
docker compose exec postgres psql -U shannon -d shannon -c "
SELECT COUNT(*) FROM event_logs WHERE workflow_id = 'task_abc123';
"

# 检查 Redis 流
docker compose exec redis redis-cli XLEN "stream:task_abc123"
```

**解决方案**:

```bash theme={null}
# 验证管理服务器正在运行
docker compose ps orchestrator

# 检查管理服务器端点
curl http://localhost:8081/health

# 重启 orchestrator
docker compose restart orchestrator
```

### 10. 工具执行问题

#### Python 代码执行失败

**症状**:

* "WASI interpreter not found"
* Python 代码工具失败
* 沙箱错误

**解决方案**:

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

# 或手动下载
wget https://github.com/vmware-labs/webassembly-language-runtimes/releases/download/python%2F3.11.4%2B20230908-ba7c2cf/python-3.11.4.wasm
mkdir -p ./wasm-interpreters
mv python-3.11.4.wasm ./wasm-interpreters/

# 在 .env 中验证路径
PYTHON_WASI_WASM_PATH=./wasm-interpreters/python-3.11.4.wasm

# 重启
docker compose restart agent-core llm-service
```

#### 工具超时

**症状**:

* "Tool execution timeout" 错误
* 工具无限期挂起
* WASI 超时错误

**解决方案**:

```bash theme={null}
# 增加超时时间
WASI_TIMEOUT_SECONDS=120  # 从 60 提高
ENFORCE_TIMEOUT_SECONDS=180  # 从 90 提高

# 重启
docker compose restart agent-core
```

## 配置验证

### 验证所有设置

```bash theme={null}
#!/bin/bash

echo "=== Shannon 配置验证 ==="

# 检查 .env 文件
if [ ! -f .env ]; then
  echo "❌ .env 文件未找到"
  exit 1
fi
echo "✓ .env 文件存在"

# 检查必需的变量
required_vars=(
  "POSTGRES_HOST"
  "REDIS_HOST"
  "TEMPORAL_HOST"
)

for var in "${required_vars[@]}"; do
  if grep -q "^${var}=" .env; then
    echo "✓ $var 已设置"
  else
    echo "❌ $var 缺失"
  fi
done

# 检查至少一个 LLM 提供商
if grep -qE "^(OPENAI|ANTHROPIC|GOOGLE)_API_KEY=.+" .env; then
  echo "✓ LLM 提供商已配置"
else
  echo "❌ 未设置 LLM 提供商 API 密钥"
fi

# 检查服务是否运行
echo ""
echo "=== 服务健康状态 ==="
services=("postgres" "redis" "temporal" "qdrant" "orchestrator" "agent-core" "llm-service" "gateway")

for service in "${services[@]}"; do
  if docker compose ps | grep -q "$service.*running"; then
    echo "✓ $service 正在运行"
  else
    echo "❌ $service 未运行"
  fi
done

echo ""
echo "=== 端点测试 ==="

# 测试 Gateway
if curl -f -s http://localhost:8080/health > /dev/null; then
  echo "✓ Gateway 健康检查通过"
else
  echo "❌ Gateway 健康检查失败"
fi

# 测试 Orchestrator 指标
if curl -f -s http://localhost:2112/metrics > /dev/null; then
  echo "✓ Orchestrator 指标可用"
else
  echo "❌ Orchestrator 指标失败"
fi

echo ""
echo "=== 配置验证完成 ==="
```

## 最佳实践

### 1. 使用特定环境的配置

```bash theme={null}
# 开发环境
.env.development
ENVIRONMENT=dev
DEBUG=true
GATEWAY_SKIP_AUTH=1

# 生产环境
.env.production
ENVIRONMENT=prod
DEBUG=false
GATEWAY_SKIP_AUTH=0
JWT_SECRET=<secure-secret>
```

### 2. 记录自定义设置

```bash theme={null}
# 在 .env 中添加注释
# 用于高流量 API 的自定义速率限制
RATE_LIMIT_REQUESTS=500  # 为企业级增加
```

### 3. 版本控制

```bash theme={null}
# .gitignore
.env
.env.local

# 提交模板
.env.example
.env.template
```

### 4. 定期验证

```bash theme={null}
# 添加到 CI/CD
./scripts/validate-config.sh
```

### 5. 监控配置

```bash theme={null}
# 跟踪配置更改
git diff .env.example

# 关键更改时发出警报
# 在生产环境中监控环境变量
```

## 快速修复检查清单

当出现问题时,按顺序尝试以下方法:

* [ ] 重启所有服务: `docker compose restart`
* [ ] 检查日志: `docker compose logs --tail=50`
* [ ] 验证 .env 文件存在且包含必需变量
* [ ] 测试数据库连接: `docker compose exec postgres pg_isready`
* [ ] 测试 Redis: `docker compose exec redis redis-cli ping`
* [ ] 验证至少设置了一个 LLM API 密钥
* [ ] 检查磁盘空间: `df -h`
* [ ] 检查内存: `docker stats`
* [ ] 完全重置 (最后手段): `docker compose down -v && docker compose up -d`

## 获取帮助

如果问题持续存在:

1. **收集日志**:
   ```bash theme={null}
   docker compose logs > shannon-logs.txt
   ```

2. **导出配置**:
   ```bash theme={null}
   docker compose exec orchestrator env | grep -v API_KEY > config.txt
   ```

3. **查看 GitHub issues**: [https://github.com/Kocoro-lab/Shannon/issues](https://github.com/Kocoro-lab/Shannon/issues)

## 相关文档

<CardGroup cols={2}>
  <Card title="环境变量" icon="gear" href="/cn/deployment/environment-variables">
    完整变量参考
  </Card>

  <Card title="Docker Compose" icon="docker" href="/cn/deployment/docker-compose">
    Docker 部署指南
  </Card>

  <Card title="故障排除" icon="wrench" href="/cn/quickstart/troubleshooting">
    通用故障排除
  </Card>

  <Card title="性能调优" icon="gauge" href="/cn/deployment/performance-tuning">
    性能优化
  </Card>
</CardGroup>