故障排除

快速诊断

在深入研究具体问题之前，运行这些快速检查：

# 检查所有服务是否正在运行
docker compose ps

# 查看所有服务的最近日志
docker compose logs --tail=50

# 检查特定服务的健康状况
curl http://localhost:8080/health
curl http://localhost:8000/health  # LLM 服务

安装和设置问题

Docker Compose 启动失败

症状：

服务无法启动
退出代码错误
容器立即崩溃

常见原因：

1. Docker 守护进程未运行

检查：

docker info

解决方案：

# macOS
open -a Docker

# Linux
sudo systemctl start docker

# 验证
docker info

2. 端口冲突

检查正在使用的端口：

# 检查所有 Shannon 端口
lsof -i :8080  # Gateway
lsof -i :50051 # Agent Core
lsof -i :50052 # Orchestrator
lsof -i :8000  # LLM Service
lsof -i :5432  # PostgreSQL
lsof -i :6379  # Redis
lsof -i :6333  # Qdrant
lsof -i :7233  # Temporal

解决方案 - 终止冲突进程：

# 查找使用端口的进程
lsof -ti :8080

# 终止进程（macOS/Linux）
kill -9 $(lsof -ti :8080)

解决方案 - 更改 Shannon 端口：编辑 docker-compose.yml 以使用不同的端口：

gateway:
  ports:
    - "8081:8080"  # 使用 8081 而不是 8080

3. 系统资源不足

检查 Docker 资源：

docker system df
docker stats

解决方案 - 增加 Docker 资源：

macOS：Docker Desktop → Preferences → Resources
- RAM：最少 8GB（推荐 16GB）
- CPU：最少 4 核
- 磁盘：最少 20GB 可用空间

Linux：编辑 Docker 守护进程配置

sudo nano /etc/docker/daemon.json

{
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 64000,
      "Soft": 64000
    }
  }
}

4. 缺少 .env 文件

错误：WARNING: The OPENAI_API_KEY variable is not set解决方案：

# 从模板创建 .env
make setup

# 或手动创建
cp .env.example .env

# 添加您的 API 密钥
echo "OPENAI_API_KEY=sk-..." >> .env
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

5. Python WASI 解释器缺失

错误：python_wasi/bin/python3.11: No such file or directory解决方案：

# 下载并设置 Python WASI（20MB）
./scripts/setup_python_wasi.sh

# 验证安装
ls -lh python_wasi/bin/python3.11

API 和连接问题

401 未授权

症状：

HTTP 401 响应
“Unauthorized” 错误消息

诊断：

# 检查是否启用了认证
docker compose exec orchestrator env | grep GATEWAY_SKIP_AUTH

解决方案 1：禁用认证（开发环境）

编辑 .env：

GATEWAY_SKIP_AUTH=1  # 1 = 禁用，0 = 启用

重启：

docker compose restart gateway

测试：

curl http://localhost:8080/api/v1/tasks
# 应该无需 X-API-Key 头即可工作

解决方案 2：提供有效的 API 密钥（生产环境）

带 API 密钥的请求：

curl -H "X-API-Key: sk_test_123456" \
  http://localhost:8080/api/v1/tasks

Python SDK：

from shannon import ShannonClient

client = ShannonClient(
    base_url="http://localhost:8080",
    api_key="sk_test_123456"
)

连接被拒绝/服务不可用

症状：

connection refused
dial tcp: connect: connection refused
服务无响应

诊断：

# 检查服务状态
docker compose ps

# 检查特定服务日志
docker compose logs orchestrator --tail=50
docker compose logs agent-core --tail=50
docker compose logs llm-service --tail=50

# 测试端点
curl http://localhost:8080/health
curl http://localhost:50052  # 应该失败 - gRPC 不支持 HTTP GET

解决方案 1：服务未就绪

等待所有服务初始化：

# 观察日志直到服务准备就绪
docker compose logs -f

# 查找这些消息：
# orchestrator: "gRPC server listening on :50052"
# agent-core: "Server started on :50051"
# llm-service: "Uvicorn running on http://0.0.0.0:8000"
# gateway: "Gateway listening on :8080"

典型启动时间：30-60 秒

解决方案 2：服务崩溃

检查崩溃错误：

docker compose logs orchestrator | grep -i error
docker compose logs orchestrator | grep -i fatal

重启崩溃的服务：

docker compose restart orchestrator
docker compose restart agent-core
docker compose restart llm-service

如有需要完全重置：

docker compose down
docker compose up -d

解决方案 3：数据库连接失败

检查 PostgreSQL：

docker compose logs postgres --tail=20

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

解决方案：

# 重启数据库
docker compose restart postgres

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

任务停留在 RUNNING 或 QUEUED 状态

症状：

任务从不完成
状态保持 RUNNING 几个小时
没有进度更新

诊断：

# 检查 Temporal 工作流
docker compose logs temporal --tail=100

# 检查编排器 worker
docker compose logs orchestrator | grep -i workflow

# 在 Temporal UI 中查看任务
open http://localhost:8088

解决方案 1：LLM API 密钥无效或配额超限

检查 LLM 服务日志：

docker compose logs llm-service | grep -i "api key\|unauthorized\|quota"

解决方案：

# 验证 .env 中的 API 密钥
grep -E "OPENAI_API_KEY|ANTHROPIC_API_KEY" .env

# 测试 API 密钥
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# 使用有效密钥更新 .env
nano .env

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

解决方案 2：Temporal worker 死锁

重启 Temporal worker：

docker compose restart orchestrator

# 在 Temporal UI 中检查工作流
open http://localhost:8088
# 导航到 Workflows → 查找您的工作流 → 查看执行历史

强制终止工作流（最后手段）：

# 在 Temporal UI 中：Workflows → 选择工作流 → Terminate

解决方案 3：断路器打开

检查断路器状态：

docker compose logs orchestrator | grep -i "circuit"

断路器防止级联故障：

LLM 服务断路器
数据库断路器
Redis 断路器

解决方案 - 等待自动恢复（30-60 秒）或 重启服务：

docker compose restart orchestrator agent-core llm-service

预算和成本问题

预算超限错误

症状：

budget exceeded 错误
任务因成本限制错误而失败
HTTP 429（速率受限）需要付费

诊断：

# 检查预算配置
docker compose exec orchestrator env | grep BUDGET
docker compose exec orchestrator env | grep MAX_COST

解决方案 1：增加预算限制

编辑 .env：

MAX_COST_PER_REQUEST=1.00    # 从 0.50 增加
MAX_TOKENS_PER_REQUEST=20000  # 从 10000 增加

重启：

docker compose restart orchestrator llm-service

预算由服务端环境变量控制。SDK 不支持按请求设置预算参数。

解决方案 2：使用更简单的执行模式

# 而不是高级模式
client.submit_task(query="...", # 自动选择模式)

# Advanced → Standard → Simple（最便宜）

成本比较：

Simple：1 次 LLM 调用，$0.01-0.05
Standard：3-5 次 LLM 调用，$0.05-0.20
Advanced：10+ 次 LLM 调用，$0.20-1.00+

解决方案 3：禁用预算强制执行（仅限开发）

⚠️ 警告：仅用于开发/测试编辑 .env：

LLM_DISABLE_BUDGETS=1  # 禁用预算检查

重启：

docker compose restart orchestrator llm-service

性能问题

响应时间慢

症状：

任务耗时比预期长 2-3 倍
高延迟
超时

诊断：

# 检查资源使用情况
docker stats

# 检查慢查询
docker compose logs postgres | grep "duration:"

# 检查 Redis 延迟
docker compose exec redis redis-cli --latency

# 检查 Qdrant 性能
curl http://localhost:6333/metrics

解决方案 1：CPU/内存不足

检查资源：

docker stats
# 查找 CPU > 80% 或内存接近限制

增加 Docker 资源：

macOS：Docker Desktop → Resources → 将 RAM 增加到 16GB，CPU 增加到 6
Linux：更强大的机器或减少并发工作流

在 .env 中调整 worker 并发性：

WORKER_ACT_CRITICAL=5   # 从 10 减少
WORKER_WF_CRITICAL=3     # 从 5 减少
TOOL_PARALLELISM=2       # 从 5 减少

解决方案 2：冷启动/缓存未命中

第一个请求总是较慢（10-30秒）后续请求使用缓存：

LLM 响应缓存（Redis）
会话上下文缓存
工具结果缓存

解决方案：使用测试请求预热

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello"}'

解决方案 3：数据库连接池耗尽

在 .env 中增加池大小：

DB_MAX_OPEN_CONNS=50    # 从 25 增加
DB_MAX_IDLE_CONNS=10    # 从 5 增加

重启：

docker compose restart orchestrator

令牌（tokens）> 0，但结果为空

症状：

日志或数据库显示补全 completion_tokens > 0，但最终 result 文本为空。
复杂问题没有输出，而简单问题正常。

原因：

部分 GPT‑5 聊天响应以结构化分片返回内容，而不是纯字符串。旧解析可能遗漏这些文本。已通过将 GPT‑5 模型路由到 Responses API，并为聊天响应添加内容规范化来修复。

修复（Shannon ≥ 2025‑11‑05）：

LLM 服务将 GPT‑5 模型路由至 Responses API，并优先使用 output_text。
聊天提供商在返回列表内容时，会将文本分片合并为字符串。
从旧版本升级时，请重启 LLM 服务以清除缓存的空响应。

验证：

重新运行较长的多段落提示，result 长度应 > 0，且会话历史应包含助手消息。

高内存使用

症状：

OOM（内存不足）错误
容器重启
Swap 使用率高

诊断：

docker stats

# 检查会话缓存大小
docker compose logs orchestrator | grep "session.*cache"

解决方案：减少缓存大小

编辑 config/shannon.yaml 或 设置环境变量：

# 减少会话缓存
SESSION_CACHE_SIZE=5000  # 从 10000

# 减少历史记录
SESSION_MAX_HISTORY=250  # 从 500

# 减少 LRU 缓存
TOOL_CACHE_SIZE=1000     # 从 5000

重启：

docker compose restart orchestrator agent-core

数据和状态问题

会话未持久化

症状：

请求之间丢失会话上下文
代理不记得以前的任务

诊断：

# 检查 Redis 连接
docker compose exec orchestrator nc -zv redis 6379

# 检查会话数据
docker compose exec redis redis-cli KEYS "session:*"

解决方案 1：Redis 连接失败

检查 Redis 状态：

docker compose ps redis
docker compose logs redis --tail=20

重启 Redis：

docker compose restart redis

测试连接：

docker compose exec redis redis-cli ping
# 应该返回 "PONG"

解决方案 2：会话过期（TTL）

会话默认在 30 天后过期在 .env 中增加 TTL：

REDIS_TTL_SECONDS=7776000  # 90 天

检查会话过期：

docker compose exec redis redis-cli TTL "session:YOUR_SESSION_ID"
# 返回到期前的秒数，或 -1 表示无过期

解决方案 3：使用不同的会话 ID

验证会话 ID 一致性：

# 第一个任务
handle1 = client.submit_task("Load data")
session_id = handle1.session_id
print(f"Session: {session_id}")

# 后续任务必须使用相同的 session_id
handle2 = client.submit_task(
    "Analyze data",
    session_id=session_id  # ← 必须匹配！
)

数据库迁移错误

症状：

表不存在错误
找不到列错误
架构版本不匹配

解决方案：

# 运行迁移
docker compose exec orchestrator make migrate

# 或重置数据库（⚠️ 破坏性操作）
docker compose down -v  # 删除卷
docker compose up -d

调试工具

查看日志

# 所有服务
docker compose logs -f

# 特定服务
docker compose logs -f orchestrator
docker compose logs -f agent-core
docker compose logs -f llm-service

# 最后 N 行
docker compose logs --tail=100 orchestrator

# 搜索日志
docker compose logs orchestrator | grep -i error
docker compose logs orchestrator | grep "task_id=YOUR_TASK_ID"

Temporal UI

访问：http://localhost:8088 功能：

查看所有工作流
查看执行历史
重放失败的工作流
终止卡住的工作流
时间旅行调试

使用：

导航到 Workflows
按工作流 ID（任务 ID）搜索
查看执行历史以查看失败的位置
检查 Activity 日志以获取详细错误

Prometheus 指标

# 编排器指标
curl http://localhost:2112/metrics

# 代理核心指标
curl http://localhost:2113/metrics

# LLM 服务指标
curl http://localhost:8000/metrics

关键指标：

tasks_submitted_total
tasks_completed_total
tasks_failed_total
llm_requests_total
circuit_breaker_state

实时监控

若需要实时查看任务执行：

使用 Shannon 桌面应用（运行视图和运行详情）查看实时事件流
部署 Prometheus/Grafana 后使用监控面板查看指标（参见监控概念）

获取帮助

安装指南

详细的设置说明

API 文档

完整的 API 参考

GitHub Issues

报告错误或请求功能

快速参考命令

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

# 服务状态
docker compose ps
docker stats

# 重启服务
docker compose restart orchestrator
docker compose restart agent-core
docker compose restart llm-service

# 查看日志
docker compose logs -f orchestrator

# 完全重置
docker compose down -v
docker compose up -d

# 数据库访问
docker compose exec postgres psql -U shannon -d shannon

# Redis CLI
docker compose exec redis redis-cli

# 检查环境
docker compose exec orchestrator env | grep -E "OPENAI|ANTHROPIC"

入门指南

核心概念

指南

快速诊断

安装和设置问题

Docker Compose 启动失败

API 和连接问题

401 未授权

连接被拒绝/服务不可用

任务停留在 RUNNING 或 QUEUED 状态

预算和成本问题

预算超限错误

性能问题

响应时间慢

令牌（tokens）> 0，但结果为空

高内存使用

数据和状态问题

会话未持久化

数据库迁移错误

调试工具

查看日志

Temporal UI

Prometheus 指标

实时监控

获取帮助

安装指南

API 文档

GitHub Issues

快速参考命令

​快速诊断

​安装和设置问题

​Docker Compose 启动失败

​API 和连接问题

​401 未授权

​连接被拒绝/服务不可用

​任务停留在 RUNNING 或 QUEUED 状态

​预算和成本问题

​预算超限错误

​性能问题

​响应时间慢

​令牌（tokens）> 0，但结果为空

​高内存使用

​数据和状态问题

​会话未持久化

​数据库迁移错误

​调试工具

​查看日志

​Temporal UI

​Prometheus 指标

​实时监控

​获取帮助

安装指南

API 文档

GitHub Issues

​快速参考命令

快速诊断

安装和设置问题

Docker Compose 启动失败

API 和连接问题

401 未授权

连接被拒绝/服务不可用

任务停留在 RUNNING 或 QUEUED 状态

预算和成本问题

预算超限错误

性能问题

响应时间慢

令牌（tokens）> 0，但结果为空

高内存使用

数据和状态问题

会话未持久化

数据库迁移错误

调试工具

查看日志

Temporal UI

Prometheus 指标

实时监控

获取帮助

快速参考命令