> ## 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 时的常见问题和解决方案

## 快速诊断

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

```bash theme={null}
# 检查所有服务是否正在运行
docker compose ps

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

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

## 安装和设置问题

### Docker Compose 启动失败

**症状**：

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

**常见原因**：

<AccordionGroup>
  <Accordion title="1. Docker 守护进程未运行">
    **检查**：

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

    **解决方案**：

    ```bash theme={null}
    # macOS
    open -a Docker

    # Linux
    sudo systemctl start docker

    # 验证
    docker info
    ```
  </Accordion>

  <Accordion title="2. 端口冲突">
    **检查正在使用的端口**：

    ```bash theme={null}
    # 检查所有 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
    ```

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

    ```bash theme={null}
    # 查找使用端口的进程
    lsof -ti :8080

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

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

    ```yaml theme={null}
    gateway:
      ports:
        - "8081:8080"  # 使用 8081 而不是 8080
    ```
  </Accordion>

  <Accordion title="3. 系统资源不足">
    **检查 Docker 资源**：

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

    **解决方案 - 增加 Docker 资源**：

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

    * **Linux**：编辑 Docker 守护进程配置
      ```bash theme={null}
      sudo nano /etc/docker/daemon.json
      ```
      ```json theme={null}
      {
        "default-ulimits": {
          "nofile": {
            "Name": "nofile",
            "Hard": 64000,
            "Soft": 64000
          }
        }
      }
      ```
  </Accordion>

  <Accordion title="4. 缺少 .env 文件">
    **错误**：`WARNING: The OPENAI_API_KEY variable is not set`

    **解决方案**：

    ```bash theme={null}
    # 从模板创建 .env
    make setup

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

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

  <Accordion title="5. Python WASI 解释器缺失">
    **错误**：`python_wasi/bin/python3.11: No such file or directory`

    **解决方案**：

    ```bash theme={null}
    # 下载并设置 Python WASI（20MB）
    ./scripts/setup_python_wasi.sh

    # 验证安装
    ls -lh python_wasi/bin/python3.11
    ```
  </Accordion>
</AccordionGroup>

## API 和连接问题

### 401 未授权

**症状**：

* HTTP 401 响应
* "Unauthorized" 错误消息

**诊断**：

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

<AccordionGroup>
  <Accordion title="解决方案 1：禁用认证（开发环境）">
    **编辑 `.env`**：

    ```bash theme={null}
    GATEWAY_SKIP_AUTH=1  # 1 = 禁用，0 = 启用
    ```

    **重启**：

    ```bash theme={null}
    docker compose restart gateway
    ```

    **测试**：

    ```bash theme={null}
    curl http://localhost:8080/api/v1/tasks
    # 应该无需 X-API-Key 头即可工作
    ```
  </Accordion>

  <Accordion title="解决方案 2：提供有效的 API 密钥（生产环境）">
    **带 API 密钥的请求**：

    ```bash theme={null}
    curl -H "X-API-Key: sk_test_123456" \
      http://localhost:8080/api/v1/tasks
    ```

    **Python SDK**：

    ```python theme={null}
    from shannon import ShannonClient

    client = ShannonClient(
        base_url="http://localhost:8080",
        api_key="sk_test_123456"
    )
    ```
  </Accordion>
</AccordionGroup>

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

**症状**：

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

**诊断**：

```bash theme={null}
# 检查服务状态
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
```

<AccordionGroup>
  <Accordion title="解决方案 1：服务未就绪">
    **等待所有服务初始化**：

    ```bash theme={null}
    # 观察日志直到服务准备就绪
    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 秒
  </Accordion>

  <Accordion title="解决方案 2：服务崩溃">
    **检查崩溃错误**：

    ```bash theme={null}
    docker compose logs orchestrator | grep -i error
    docker compose logs orchestrator | grep -i fatal
    ```

    **重启崩溃的服务**：

    ```bash theme={null}
    docker compose restart orchestrator
    docker compose restart agent-core
    docker compose restart llm-service
    ```

    **如有需要完全重置**：

    ```bash theme={null}
    docker compose down
    docker compose up -d
    ```
  </Accordion>

  <Accordion title="解决方案 3：数据库连接失败">
    **检查 PostgreSQL**：

    ```bash theme={null}
    docker compose logs postgres --tail=20

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

    **解决方案**：

    ```bash theme={null}
    # 重启数据库
    docker compose restart postgres

    # 等待它准备就绪
    docker compose exec postgres pg_isready -U shannon
    ```
  </Accordion>
</AccordionGroup>

### 任务停留在 RUNNING 或 QUEUED 状态

**症状**：

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

**诊断**：

```bash theme={null}
# 检查 Temporal 工作流
docker compose logs temporal --tail=100

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

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

<AccordionGroup>
  <Accordion title="解决方案 1：LLM API 密钥无效或配额超限">
    **检查 LLM 服务日志**：

    ```bash theme={null}
    docker compose logs llm-service | grep -i "api key\|unauthorized\|quota"
    ```

    **解决方案**：

    ```bash theme={null}
    # 验证 .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
    ```
  </Accordion>

  <Accordion title="解决方案 2：Temporal worker 死锁">
    **重启 Temporal worker**：

    ```bash theme={null}
    docker compose restart orchestrator

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

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

    ```bash theme={null}
    # 在 Temporal UI 中：Workflows → 选择工作流 → Terminate
    ```
  </Accordion>

  <Accordion title="解决方案 3：断路器打开">
    **检查断路器状态**：

    ```bash theme={null}
    docker compose logs orchestrator | grep -i "circuit"
    ```

    **断路器防止级联故障**：

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

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

    ```bash theme={null}
    docker compose restart orchestrator agent-core llm-service
    ```
  </Accordion>
</AccordionGroup>

## 预算和成本问题

### 预算超限错误

**症状**：

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

**诊断**：

```bash theme={null}
# 检查预算配置
docker compose exec orchestrator env | grep BUDGET
docker compose exec orchestrator env | grep MAX_COST
```

<AccordionGroup>
  <Accordion title="解决方案 1：增加预算限制">
    **编辑 `.env`**：

    ```bash theme={null}
    MAX_COST_PER_REQUEST=1.00    # 从 0.50 增加
    MAX_TOKENS_PER_REQUEST=20000  # 从 10000 增加
    ```

    **重启**：

    ```bash theme={null}
    docker compose restart orchestrator llm-service
    ```

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

  <Accordion title="解决方案 2：使用更简单的执行模式">
    ```python theme={null}
    # 而不是高级模式
    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+
  </Accordion>

  <Accordion title="解决方案 3：禁用预算强制执行（仅限开发）">
    **⚠️ 警告**：仅用于开发/测试

    **编辑 `.env`**：

    ```bash theme={null}
    LLM_DISABLE_BUDGETS=1  # 禁用预算检查
    ```

    **重启**：

    ```bash theme={null}
    docker compose restart orchestrator llm-service
    ```
  </Accordion>
</AccordionGroup>

## 性能问题

### 响应时间慢

**症状**：

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

**诊断**：

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

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

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

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

<AccordionGroup>
  <Accordion title="解决方案 1：CPU/内存不足">
    **检查资源**：

    ```bash theme={null}
    docker stats
    # 查找 CPU > 80% 或内存接近限制
    ```

    **增加 Docker 资源**：

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

    **在 `.env` 中调整 worker 并发性**：

    ```bash theme={null}
    WORKER_ACT_CRITICAL=5   # 从 10 减少
    WORKER_WF_CRITICAL=3     # 从 5 减少
    TOOL_PARALLELISM=2       # 从 5 减少
    ```
  </Accordion>

  <Accordion title="解决方案 2：冷启动/缓存未命中">
    **第一个请求总是较慢**（10-30秒）

    **后续请求使用缓存**：

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

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

    ```bash theme={null}
    curl -X POST http://localhost:8080/api/v1/tasks \
      -H "Content-Type: application/json" \
      -d '{"query": "Hello"}'
    ```
  </Accordion>

  <Accordion title="解决方案 3：数据库连接池耗尽">
    **在 `.env` 中增加池大小**：

    ```bash theme={null}
    DB_MAX_OPEN_CONNS=50    # 从 25 增加
    DB_MAX_IDLE_CONNS=10    # 从 5 增加
    ```

    **重启**：

    ```bash theme={null}
    docker compose restart orchestrator
    ```
  </Accordion>
</AccordionGroup>

## 令牌（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 使用率高

**诊断**：

```bash theme={null}
docker stats

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

<AccordionGroup>
  <Accordion title="解决方案：减少缓存大小">
    **编辑 `config/shannon.yaml`** 或 **设置环境变量**：

    ```bash theme={null}
    # 减少会话缓存
    SESSION_CACHE_SIZE=5000  # 从 10000

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

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

    **重启**：

    ```bash theme={null}
    docker compose restart orchestrator agent-core
    ```
  </Accordion>
</AccordionGroup>

## 数据和状态问题

### 会话未持久化

**症状**：

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

**诊断**：

```bash theme={null}
# 检查 Redis 连接
docker compose exec orchestrator nc -zv redis 6379

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

<AccordionGroup>
  <Accordion title="解决方案 1：Redis 连接失败">
    **检查 Redis 状态**：

    ```bash theme={null}
    docker compose ps redis
    docker compose logs redis --tail=20
    ```

    **重启 Redis**：

    ```bash theme={null}
    docker compose restart redis
    ```

    **测试连接**：

    ```bash theme={null}
    docker compose exec redis redis-cli ping
    # 应该返回 "PONG"
    ```
  </Accordion>

  <Accordion title="解决方案 2：会话过期（TTL）">
    **会话默认在 30 天后过期**

    **在 `.env` 中增加 TTL**：

    ```bash theme={null}
    REDIS_TTL_SECONDS=7776000  # 90 天
    ```

    **检查会话过期**：

    ```bash theme={null}
    docker compose exec redis redis-cli TTL "session:YOUR_SESSION_ID"
    # 返回到期前的秒数，或 -1 表示无过期
    ```
  </Accordion>

  <Accordion title="解决方案 3：使用不同的会话 ID">
    **验证会话 ID 一致性**：

    ```python theme={null}
    # 第一个任务
    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  # ← 必须匹配！
    )
    ```
  </Accordion>
</AccordionGroup>

### 数据库迁移错误

**症状**：

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

**解决方案**：

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

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

## 调试工具

### 查看日志

```bash theme={null}
# 所有服务
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](http://localhost:8088)

**功能**：

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

**使用**：

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

### Prometheus 指标

```bash theme={null}
# 编排器指标
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 后使用监控面板查看指标（参见监控概念）

## 获取帮助

<CardGroup cols={2}>
  <Card title="安装指南" icon="download" href="/cn/quickstart/installation">
    详细的设置说明
  </Card>

  <Card title="API 文档" icon="book" href="/cn/api/overview">
    完整的 API 参考
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/Kocoro-lab/Shannon/issues">
    报告错误或请求功能
  </Card>
</CardGroup>

## 快速参考命令

```bash theme={null}
# 健康检查
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"
```