故障排除

故障排除

服务启动问题

Server 启动失败

现象：运行 ./server 报错

排查步骤：

1. 检查端口占用：lsof -i :3333

2. 检查数据库连接：确认 PostgreSQL/SQLite 可访问

3. 检查配置文件：确认 config.yaml 格式正确

4. 查看日志：cat server.log

前端页面空白

解决方案：

# 重启前端
pkill -f vite
cd web && nohup npm run dev -- --host 0.0.0.0 > /tmp/vite.log 2>&1 &

API 返回 "Authentication required"

解决方案：重启 Server 或重新登录获取新 Token。

Agent 问题

Agent 无法连接 Server

排查步骤：

1. 检查网络连通性：ping <server-ip>

2. 检查端口可访问：telnet <server-ip> 3333

3. 确认 EXTENDER_URL 配置正确

4. 查看 Agent 日志

GPU 未被检测到

排查步骤：

1. 确认 GPU 驱动已安装：nvidia-smi（NVIDIA）/ hy-smi（海光）/ 对应检测工具

2. 确认检测工具在 PATH 中

3. 查看 Agent 日志中的检测过程

4. 检查是否有权限问题

Agent 心跳超时

可能原因：

• 网络不稳定
• Agent 进程被 kill
• Server 端口不可达

推理服务问题

推理服务一直 pending

可能原因：

• 节点不在线：GET /api/v1/nodes 查看节点状态
• GPU 类型不匹配：服务指定了 GPU 类型但节点没有
• GPU 显存不足：节点剩余显存不够
• 推理引擎镜像拉取失败：检查网络和镜像仓库

GPU OOM（显存不足）

解决方案：

• 使用更小的模型
• 使用量化模型（AWQ、GPTQ、GGUF）
• 使用张量并行分布到多 GPU
• 减小上下文长度：--max-model-len

推理速度慢

排查步骤：

1. 检查 GPU 利用率：nvidia-smi

2. 确认 GPU 未被其他任务抢占

3. 检查是否有显存交换

4. 考虑使用 vLLM 引擎（PagedAttention 优化）

5. 多副本部署 + 负载均衡

数据库问题

"context deadline exceeded"

解决方案：

./fix-database.sh

此脚本会清理数据库连接和锁。

数据库连接超时

排查步骤：

1. 检查 PostgreSQL 服务状态

2. 检查连接数配置

3. 检查网络延迟

调度问题

任务不被调度

可能原因：

• 没有符合条件的节点（GPU 类型/显存/状态）
• 调度器插件配置问题
• 所有 GPU 都被占用

排查方法：

# 查看节点 GPU 状态
curl http://localhost:3333/api/v1/nodes

# 查看待调度任务
curl http://localhost:3333/api/v1/tasks?status=pending

# 查看调度器配置
curl http://localhost:3333/api/v1/scheduler/config

常用命令

# 查看服务状态
./manage-services.sh status

# 重启服务
./manage-services.sh restart all

# 查看 Agent 日志
journalctl -u heteroflow-agent --since "10 minutes ago"

# 清理僵尸容器
docker ps | grep task- | awk ''{print $1}'' | xargs docker rm -f