配置故障排除

概述

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

快速诊断

检查环境变量

# 查看服务的所有环境变量
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

验证配置文件

# 检查配置文件是否存在
docker compose exec orchestrator ls -la ./config/

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

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

检查服务健康状态

# Gateway 健康检查
curl http://localhost:8080/health

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

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

常见问题

1. 服务无法启动

缺少环境变量

症状:

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

诊断:

docker compose logs orchestrator | grep -i "not set\|missing\|required"

解决方案:

# 检查 .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 语法错误
服务启动失败

诊断:

# 检查 YAML 语法
docker compose exec orchestrator cat ./config/features.yaml | yq .

解决方案:

# 本地验证 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 密钥被拒绝

诊断:

# 检查是否启用了身份认证
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: 为开发环境禁用身份认证

# 添加到 .env
GATEWAY_SKIP_AUTH=1

# 重启 gateway
docker compose restart gateway

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

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

# 在数据库中插入 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” 错误
身份认证中间件失败

解决方案:

# 生成安全密钥
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”
服务启动时崩溃

诊断:

# 检查 PostgreSQL 是否运行
docker compose ps postgres

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

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

解决方案 1: PostgreSQL 未启动

# 启动 PostgreSQL
docker compose up -d postgres

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

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

解决方案 2: 凭据错误

# 验证 .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: 端口冲突

# 检查端口 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 错误

解决方案:

# 运行迁移
docker compose exec orchestrator make migrate

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

4. Redis 连接问题

无法连接到 Redis

症状:

Redis “connection refused”
会话状态不持久
缓存未命中

诊断:

# 检查 Redis 状态
docker compose ps redis

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

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

解决方案:

# 启动 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”
连接正常但命令失败

解决方案:

# 检查是否设置了密码
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
任务立即失败

诊断:

# 检查配置了哪个提供商
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"}]}'

解决方案:

# 在 .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: 等待速率限制重置

# 检查速率限制标头
docker compose logs llm-service | grep "rate"

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

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

# 添加到 .env
RATE_LIMIT_REQUESTS=50  # 低于提供商限制
RATE_LIMIT_WINDOW=60

# 重启
docker compose restart llm-service

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

# 在 models.yaml 中配置备用提供商
providers:
  - id: openai
    primary: true
  - id: anthropic
    fallback: true

超出配额

症状:

“insufficient_quota” 错误
“You exceeded your current quota”
所有 LLM 调用失败

解决方案:

# 检查配额
# 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” 错误
任务因模型错误而失败

诊断:

# 检查配置的模型
docker compose exec llm-service cat ./config/models.yaml | grep "id:"

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

解决方案:

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

解决方案:

# 提高预算限制
# 在 .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

预算执行未生效

症状:

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

诊断:

# 检查预算执行
docker compose exec orchestrator env | grep LLM_DISABLE_BUDGETS

解决方案:

# 启用预算执行
LLM_DISABLE_BUDGETS=1  # Orchestrator 执行预算

# 设置限制
MAX_COST_PER_REQUEST=0.50
MAX_TOKENS_PER_REQUEST=10000

# 重启
docker compose restart orchestrator

8. 性能问题

任务执行缓慢

症状:

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

诊断:

# 检查资源使用情况
docker stats

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

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

解决方案 1: 提高并行度

# 在 .env 中:
TOOL_PARALLELISM=10  # 从 5 提高
WORKER_ACT_CRITICAL=20  # 从 10 提高

# 重启
docker compose restart orchestrator

解决方案 2: 启用缓存

# 在 .env 中:
ENABLE_CACHE=true
CACHE_SIMILARITY_THRESHOLD=0.95

# 重启
docker compose restart llm-service

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

# 使用更快的模型
DEFAULT_MODEL_TIER=small  # GPT-5-nano 比 GPT-5 快 10 倍

高内存使用

症状:

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

诊断:

docker stats

解决方案:

# 减少缓存大小
HISTORY_WINDOW_MESSAGES=25  # 从 50 减少
STREAMING_RING_CAPACITY=500  # 从 1000 减少

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

# 重启
docker compose restart

9. 流式传输问题

SSE 连接断开

症状:

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

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

# 在 nginx/proxy 配置中:
proxy_read_timeout 600s;
proxy_connect_timeout 600s;

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

解决方案 2: 处理重连

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

未收到事件

症状:

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

诊断:

# 检查是否正在创建事件
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"

解决方案:

# 验证管理服务器正在运行
docker compose ps orchestrator

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

# 重启 orchestrator
docker compose restart orchestrator

10. 工具执行问题

Python 代码执行失败

症状:

“WASI interpreter not found”
Python 代码工具失败
沙箱错误

解决方案:

# 下载 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 超时错误

解决方案:

# 增加超时时间
WASI_TIMEOUT_SECONDS=120  # 从 60 提高
ENFORCE_TIMEOUT_SECONDS=180  # 从 90 提高

# 重启
docker compose restart agent-core

配置验证

验证所有设置

#!/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. 使用特定环境的配置

# 开发环境
.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. 记录自定义设置

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

3. 版本控制

# .gitignore
.env
.env.local

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

4. 定期验证

# 添加到 CI/CD
./scripts/validate-config.sh

5. 监控配置

# 跟踪配置更改
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

获取帮助

如果问题持续存在:

收集日志:
```
docker compose logs > shannon-logs.txt
```

导出配置:

docker compose exec orchestrator env | grep -v API_KEY > config.txt

查看 GitHub issues: https://github.com/Kocoro-lab/Shannon/issues

环境变量

完整变量参考

Docker Compose

Docker 部署指南

故障排除

通用故障排除

性能调优

性能优化

Documentation Index

​概述

​快速诊断

​检查环境变量

​验证配置文件

​检查服务健康状态

​常见问题

​1. 服务无法启动

​缺少环境变量

​无效的配置语法

​2. 身份认证失败

​Gateway 返回 401 未授权

​JWT 密钥未设置

​3. 数据库连接问题

​无法连接到 PostgreSQL

​数据库架构未初始化

​4. Redis 连接问题

​无法连接到 Redis

​Redis 认证失败

​5. LLM 提供商问题

​API 密钥无效或过期

​超出速率限制

​超出配额

​6. 模型配置问题

​模型未找到

​7. 预算和成本问题

​任务超出预算

​预算执行未生效

​8. 性能问题

​任务执行缓慢

​高内存使用

​9. 流式传输问题

​SSE 连接断开

​未收到事件

​10. 工具执行问题

​Python 代码执行失败

​工具超时

​配置验证

​验证所有设置

​最佳实践

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

​2. 记录自定义设置

​3. 版本控制

​4. 定期验证

​5. 监控配置

​快速修复检查清单

​获取帮助

​相关文档

环境变量

Docker Compose

故障排除

性能调优

概述

快速诊断

检查环境变量

验证配置文件

检查服务健康状态

常见问题

1. 服务无法启动

缺少环境变量

无效的配置语法

2. 身份认证失败

Gateway 返回 401 未授权

JWT 密钥未设置

3. 数据库连接问题

无法连接到 PostgreSQL

数据库架构未初始化

4. Redis 连接问题

无法连接到 Redis

Redis 认证失败

5. LLM 提供商问题

API 密钥无效或过期

超出速率限制

超出配额

6. 模型配置问题

模型未找到

7. 预算和成本问题

任务超出预算

预算执行未生效

8. 性能问题

任务执行缓慢

高内存使用

9. 流式传输问题

SSE 连接断开

未收到事件

10. 工具执行问题

Python 代码执行失败

工具超时

配置验证

验证所有设置

最佳实践

1. 使用特定环境的配置

2. 记录自定义设置

3. 版本控制

4. 定期验证

5. 监控配置

快速修复检查清单

获取帮助

相关文档