Instill VDP 故障排除手册：常见问题及解决方案
项目地址: https://gitcode.com/gh_mirrors/vd/vdp Instill VDP（GitHub 加速计划）是一款全栈 AI 基础设施工具，用于数据、模型和管道编排，旨在简化构建多功能 AI 优先应用程序的各个方面。本手册将帮助新手和普通用户快速解决使用过程中遇到的常见问题，让你的 AI 项目部署和运行更加顺畅。
一、安装部署问题
1.1 容器启动失败
问题描述：使用 docker-compose up -d 命令启动服务时，部分容器出现 Exited (1) 状态。
解决方案：
- 检查容器日志：
docker logs <容器名称>，查看具体错误信息。 - 确保端口未被占用：使用
netstat -tuln检查 50051、8080 等默认端口是否被其他服务占用。 - 重启 Docker 服务：
sudo systemctl restart docker后重新尝试部署。
1.2 Helm 安装报错
问题描述：执行 helm install vdp ./charts/core 时提示依赖项缺失。
解决方案：
- 更新 Helm 仓库：
helm repo update - 安装缺失的依赖：
helm dependency build ./charts/core - 检查
Chart.lock文件是否存在，若不存在可删除charts/core目录后重新克隆仓库：git clone https://gitcode.com/gh_mirrors/vd/vdp
二、服务访问问题
2.1 API 网关无法访问
问题描述：访问 http://localhost:8080 时显示 "Connection refused"。
解决方案：
- 检查 API 网关部署状态：
kubectl get pods -n vdp，确保api-gatewaypod 处于Running状态。 - 查看服务配置：检查
charts/core/templates/api-gateway/service.yaml中的端口映射是否正确。 - 检查 ingress 规则：确认
charts/core/templates/api-gateway/ingress.yaml配置是否符合你的网络环境。
2.2 控制台界面空白
问题描述：访问控制台页面后显示空白，浏览器控制台提示资源加载失败。
解决方案：
- 清除浏览器缓存后刷新页面。
- 检查
console服务日志：kubectl logs -n vdp <console-pod-name> - 确认
configs/compose/grafana/datasources/all.yml中的数据源配置正确指向 API 服务。
三、数据与存储问题
3.1 数据库连接失败
问题描述：服务启动时提示数据库连接超时。
解决方案：
- 检查数据库服务状态：
kubectl get pods -n vdp | grep database - 验证数据库凭证：确认
charts/core/templates/database/secret.yaml中的用户名和密码与应用配置一致。 - 检查 PVC 状态：
kubectl get pvc -n vdp，确保数据库持久卷已正确挂载。
3.2 模型文件上传失败
问题描述：通过控制台上传模型文件时进度条卡住或提示 "Upload failed"。
解决方案：
- 检查文件大小：确保上传的模型文件未超过
configs/compose/registry/config.yml中设置的大小限制。 - 查看 registry 服务日志：
docker logs vdp-registry-1 - 清理临时文件：删除
integration-test/models/目录下的无效缓存文件后重试。
四、监控与日志问题
4.1 Grafana 仪表盘无数据
问题描述：Grafana 中显示 "No data points"，无法查看系统监控指标。
解决方案：
- 检查 Prometheus 服务状态：
kubectl get pods -n vdp | grep prometheus - 验证数据源配置：确保
configs/compose/grafana/datasources/all.yml中的 Prometheus 地址可访问。 - 导入默认仪表盘：重新导入
charts/core/grafana-dashboards/ray/default_grafana_dashboard.json等仪表盘文件。
4.2 日志收集异常
问题描述：Loki 未收集到服务日志，Tempo 无法追踪分布式链路。
解决方案：
- 检查 Otel Collector 配置：
configs/compose/otel-collector/config.yml中的 exporter 配置是否正确。 - 重启监控组件：
docker-compose -f docker-compose-observe.yml restart - 验证服务日志路径：确认应用服务的日志输出路径与
configs/compose/loki/config.yml中配置的路径一致。
五、高级故障排除技巧
5.1 查看系统状态
使用以下命令快速检查整体服务状态：
# 查看所有容器状态
docker-compose ps
# 查看 Kubernetes 资源状态
kubectl get all -n vdp
# 检查服务健康检查端点
curl http://localhost:8080/health
5.2 收集故障报告
当遇到复杂问题需要社区支持时，可运行以下脚本收集系统信息：
# 生成系统诊断报告
make diagnose > vdp-diagnose-$(date +%Y%m%d).txt
报告文件将包含关键配置、日志片段和资源状态，便于问题定位。
六、常见错误代码速查表
| 错误代码 | 可能原因 | 解决方案 |
|---|---|---|
| 503 Service Unavailable | 依赖服务未启动 | 检查 model-backend 和 pipeline-backend 服务状态 |
| 401 Unauthorized | 认证令牌过期 | 删除 ~/.vdp/token 文件后重新登录 |
| 404 Not Found | API 路径错误 | 参考 schema/api-tasks.json 确认接口路径 |
| E001 | 模型格式不支持 | 检查模型文件是否符合 integration-test/models/inventory.json 定义的规范 |
如果以上解决方案仍无法解决你的问题，建议查阅项目的官方文档或提交 issue 获取进一步支持。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
