KaaS

简体中文

English

简体中文

English

Appearance

故障排查 ​

本页列出使用 KaaS 时可能遇到的常见问题，以及对应的原因分析和解决步骤。

LLM 连接失败 ​

表现： 编译立即失败并报连接错误；日志中出现 LLM request failed 或超时信息。

可能原因：

  • API Key 不正确或未设置
  • base_url 配置错误
  • 网络问题（防火墙、代理、DNS）

解决步骤：

  1. 确认环境变量已正确设置：

    bash
    echo $KAAS_LLM_API_KEY
echo $KAAS_LLM_BASE_URL

  2. 直接测试 LLM 端点连通性：

    bash
    curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $KAAS_LLM_API_KEY" \
  "$KAAS_LLM_BASE_URL/models"

    返回 200 表示端点可达。

  3. 如果处于代理环境，确保 HTTP_PROXY / HTTPS_PROXY 已配置。

  4. 检查 API Key 是否已过期或达到速率限制。

编译卡住 / 无进度 ​

表现： 编译过程似乎挂起；长时间没有新文章生成。

可能原因：

  • 熔断器触发（LLM 连续失败次数过多）
  • Worker 租约过期（等待 LLM 响应超时）
  • LLM 端点响应极慢

解决步骤：

  1. 检查后端日志中的熔断器信息：

    bash
    docker logs kaas-backend 2>&1 | grep -i "circuit"

  2. 如果熔断器已触发，它会在冷却期结束后自动恢复。可调整相关参数：

    toml
    [compiler]
cb_failure_threshold = 5   # 触发熔断前的失败次数
cb_cooldown_sec = 60       # 恢复前的冷却秒数

  3. 验证 LLM 端点仍然可用（参见 LLM 连接失败）。

  4. 如果 Worker 已超时，重启编译：

    bash
    kaas compile --resume

MCP 连接被拒绝 ​

表现： MCP 客户端无法连接 KaaS；报 connection refused 错误。

可能原因：

  • KAAS_MCP_ENABLED 环境变量未设置为 true
  • 端口配置错误或未暴露
  • 客户端与服务端 Token 不匹配

解决步骤：

  1. 确认 MCP 已启用：

    bash
    export KAAS_MCP_ENABLED=true

  2. 验证 MCP 端口已正确映射（默认 8081）：

    bash
    # Docker 环境
docker ps --format "table {{.Ports}}" | grep kaas

  3. 测试 MCP 端点：

    bash
    curl -v http://localhost:8081/health

  4. 确认客户端 Token 与 KaaS 配置一致：

    bash
    echo $KAAS_MCP_TOKEN

    MCP 客户端配置中的 Token 必须与此值完全匹配。

Docker 容器无法启动 ​

表现： docker compose up 立即退出或容器反复重启。

可能原因：

  • 端口冲突（其他服务占用了 8080 或 8081 端口）
  • 缺少必需的环境变量
  • 挂载卷权限问题

解决步骤：

  1. 查看容器日志定位具体错误：

    bash
    docker logs kaas-backend

  2. 检查端口冲突：

    bash
    lsof -i :8080
lsof -i :8081

    如果端口被占用，停止占用进程或在 docker-compose.yml 中修改 KaaS 的端口映射。

  3. 确保所有必需环境变量已设置，至少包括：

    bash
    KAAS_LLM_API_KEY=your-key
KAAS_LLM_BASE_URL=https://api.openai.com/v1

  4. 验证数据目录权限：

    bash
    ls -la ./data/
# 目录需要对容器用户（UID 1000）可写
chmod -R 755 ./data/

编译完成但 Wiki 为空 ​

表现： 编译报告成功但 Wiki 中没有文章；知识库条目为零。

可能原因：

  • 源内容太短，无法提取有意义的知识
  • kb_dir 路径配置错误
  • 编译实际上静默失败（部分失败）

解决步骤：

  1. 通过状态页或 API 检查编译结果：

    bash
    curl http://localhost:8080/api/v1/status

  2. 验证数据目录包含已生成的 Markdown 文件：

    bash
    ls ./data/*.md 2>/dev/null | wc -l

  3. 检查后端日志中的提取警告：

    bash
    docker logs kaas-backend 2>&1 | grep -i "skip\|empty\|too short"

  4. 确认配置中 kb_dir 指向正确的源目录：

    toml
    [compiler]
kb_dir = "./data"

  5. 如果源文档非常短（< 100 字符），KaaS 可能会跳过它们。考虑合并小文档。

聊天返回"未找到相关文章" ​

表现： 聊天界面返回"No relevant articles found"，即使查询的主题应该已被覆盖。

可能原因：

  • Wiki 尚未编译
  • 主索引缺失或损坏
  • 查询过于模糊，或使用了与源材料不同的术语

解决步骤：

  1. 确认编译已成功完成：

    bash
    curl http://localhost:8080/api/v1/status
# 查看 "compilation_status": "completed"

  2. 验证数据目录有 Markdown 文件和主索引：

    bash
    ls ./data/*.md
ls ./data/master-index*

  3. 如果索引缺失，重新执行编译：

    bash
    kaas compile

  4. 尝试更具体的查询，使用源文档中直接出现的术语。

编译性能缓慢 ​

表现： 编译时间远超预期；进度非常慢但未卡住。

可能原因：

  • 使用本地 LLM 时模型对硬件来说太大或太慢
  • 提取 Worker 数量配置过少
  • 到 LLM API 的网络延迟过高

解决步骤：

  1. 增加 Worker 数量：

    toml
    [compiler]
extract_workers = 4   # 默认为 2；根据 API 速率限制适当增加

  2. 如果使用远程 API，检查延迟：

    bash
    time curl -s -o /dev/null "$KAAS_LLM_BASE_URL/models"

  3. 考虑使用更快或更小的模型进行提取：

    toml
    [llm]
model = "gpt-4o-mini"   # 提取任务中比 gpt-4o 更快

  4. 如果运行本地 LLM，确保有足够的 GPU 显存，模型无需过度交换。

  5. 编译期间监控系统资源：

    bash
    docker stats kaas-backend