Distributed-Prometheus/doc/TROUBLESHOOTING.md

故障排查指南

常见问题及解决方案

1. 边缘节点 ONVIF Exporter 镜像

问题：需要监控 ONVIF 摄像头，但原镜像 ghcr.io/atiek/onvif-exporter 不存在或拉取失败

说明：该镜像在公共 registry 不存在，且暂无可直接替代的公开 ONVIF→Prometheus 镜像。

建议：采用替代方案，详见 ONVIF_ALTERNATIVES.md：

1. 摄像头支持 SNMP：使用 prom/snmp-exporter（Docker Hub 有镜像），按设备 MIB 配置后由边缘 Prometheus 抓取。
2. 已用 Frigate NVR：直接抓 Frigate 的 http://<frigate>:5000/api/metrics。
3. 仅需在线/可达性：用现有 Blackbox Exporter 对摄像头 IP 做 Ping 或 HTTP/TCP 探测。
4. 必须用 ONVIF：自建 exporter 镜像（如基于 Go 的 gonvif/onvif 库），在 .env 中设置 ONVIF_EXPORTER_IMAGE=你的镜像:tag，并执行 docker compose --profile onvif up -d。

---

2. 服务启动失败

问题：容器无法启动

检查步骤：

# 1. 查看容器状态
docker compose ps

# 2. 查看容器日志
docker compose logs <服务名>

# 3. 检查端口占用
netstat -tulpn | grep <端口>

常见原因：

• 端口被占用
• 配置文件语法错误
• 磁盘空间不足
• 权限问题

解决方案：

• 修改端口映射或停止占用端口的服务
• 检查配置文件语法
• 清理磁盘空间
• 检查文件权限

---

3. 数据未推送到中央服务器

问题：边缘节点数据未出现在中央服务器

如何确认是否已写入远程（remote_write 是否成功）：

• 重要：若边缘和中央是不同机器（例如边缘 192.168.2.106、中央 192.168.1.10），则 .env 里必须填中央服务器的 IP 或域名，不能填 host.docker.internal（在边缘机上该主机名指向边缘自己，VictoriaMetrics 不在边缘上，导致无法写入）。本机同机部署时才用 host.docker.internal。

1. 在边缘 Prometheus 看推送指标
   打开边缘 Prometheus 的 Graph 页面（如 http://<边缘IP>:9092/graph），执行：

   • prometheus_remote_storage_succeeded_samples_total — 成功写入远程的样本数（有增长说明在推送）。
   • prometheus_remote_storage_failed_samples_total — 失败的样本数（若持续增加说明推送失败，需看日志）。
   • prometheus_remote_storage_queue_length — 待发送队列长度（长时间很大说明推送跟不上或失败）。

2. 在中央直接查 VictoriaMetrics
   在中央服务器上执行（或浏览器访问）：

   curl -u 'vm_read:change-me-strong-read' -sG 'http://localhost:18428/api/v1/series' --data-urlencode 'match[]=probe_success{job="network-ping"}'
   

   • 若返回 "data":[] 表示还没有收到边缘数据（可能是网络不通、刚启动未到抓取周期、或 remote_write 失败）。
   • 若 data 里有元素（带 __name__、job、region 等），说明边缘数据已写入中央。

3. 在 Grafana 用 VictoriaMetrics 数据源
   数据源选 VictoriaMetrics，查询例如：

   • probe_success{job="network-ping", region="workernode_1"}
     有曲线即表示远程写入且可查询。

检查步骤：

# 1. 检查边缘节点 Prometheus
curl http://localhost:9092/api/v1/query?query=up

# 2. 检查网络连通性
ping <中央服务器IP>
telnet <中央服务器IP> 18428

# 3. 检查环境变量
cat edge-agent/.env

# 4. 查看边缘节点日志
docker compose logs prometheus-edge

常见原因：

• 中央服务器地址配置错误
• 网络不通
• 防火墙阻止
• VictoriaMetrics 服务未运行

解决方案：

• 检查 .env 文件中的 CENTRAL_SERVER_HOST
• 测试网络连通性
• 检查防火墙规则
• 确认中央服务器 VictoriaMetrics 正常运行

---

4. 告警规则未激活

问题：告警规则显示为 inactive

检查步骤：

# 1. 在 Prometheus 中查询指标
# 访问 http://localhost:9091
# 查询: up{job="onvif-devices"}
# 查询: probe_success{job="network-ping"}

# 2. 检查告警规则文件
cat central-server/config/prometheus/alert_rules.yml

# 3. 检查 Prometheus 配置
cat central-server/config/prometheus/prometheus.yml

常见原因：

• 指标不存在（边缘节点未推送数据）
• 告警规则表达式错误
• 告警规则文件未加载

解决方案：

• 部署边缘节点并配置监控目标
• 检查告警规则表达式
• 确认 config/prometheus/prometheus.yml 中引用了 alert_rules.yml
• 重启 Prometheus 容器

---

4. Grafana 无法查询数据

问题：Grafana 中查询不到数据

检查步骤：

# 1. 检查数据源配置
# 访问 Grafana: http://localhost:3000
# 进入: Configuration -> Data Sources

# 2. 测试数据源连接
# 在数据源配置页面点击 "Test" 按钮

# 3. 检查 Prometheus 是否运行
docker compose ps prometheus-central

# 4. 直接在 Prometheus 查询
curl http://localhost:9091/api/v1/query?query=up

常见原因：

• 数据源 URL 配置错误
• Prometheus 服务未运行
• 网络问题（容器间通信）

解决方案：

• 检查数据源 URL（应为 http://prometheus-central:9090）
• 重启 Prometheus 容器
• 检查 Docker 网络配置

---

5. 磁盘空间不足

问题：容器启动失败，提示空间不足

检查步骤：

# 1. 检查磁盘空间
df -h

# 2. 检查 Docker 数据目录
du -sh /storage/docker
du -sh /storage/containerd

# 3. 检查应用数据目录
du -sh /storage/prometheus-data
du -sh /storage/grafana-data
du -sh /storage/victoria-metrics-data

解决方案：

• 清理 Docker 资源：docker system prune -a --volumes
• 清理系统日志：journalctl --vacuum-time=3d
• 清理包缓存：dnf clean all 或 apt-get clean
• 确保数据存储在 /storage 分区

---

6. 端口冲突

问题：容器启动失败，端口已被占用

检查步骤：

# 1. 检查端口占用
netstat -tulpn | grep <端口>
# 或
ss -tulpn | grep <端口>

# 2. 查看占用端口的进程
lsof -i :<端口>

解决方案：

• 停止占用端口的服务
• 或修改 docker-compose.yml 中的端口映射
• 常见端口冲突：
  • 9090 - cockpit（已改为 9091）
  • 9092 - 边缘节点 Prometheus

---

7. 配置文件语法错误

问题：容器启动失败，提示配置错误

检查步骤：

# 1. 检查 Prometheus 配置
docker exec prometheus-central promtool check config /etc/prometheus/prometheus.yml

# 2. 检查 Alertmanager 配置
docker exec alertmanager amtool check-config /etc/alertmanager/alertmanager.yml

# 3. 检查 JSON 配置文件
jq . config/*.json

解决方案：

• 修复配置文件语法错误
• 验证 YAML 格式（注意缩进）
• 验证 JSON 格式

---

8. 权限问题

问题：容器无法写入数据目录

检查步骤：

# 1. 检查目录权限
ls -ld /storage/prometheus-data
ls -ld /storage/grafana-data

# 2. 检查容器用户
docker exec prometheus-central id
docker exec grafana id

解决方案：

# Prometheus 数据目录
chmod 777 /storage/prometheus-data

# Grafana 数据目录（UID 472）
chown -R 472:472 /storage/grafana-data

# VictoriaMetrics 数据目录
chmod 777 /storage/victoria-metrics-data

---

9. 网络问题

问题：容器间无法通信

检查步骤：

# 1. 检查 Docker 网络
docker network ls
docker network inspect <网络名>

# 2. 测试容器间连通性
docker exec prometheus-central ping victoria-metrics
docker exec grafana ping prometheus-central

解决方案：

• 确保所有容器在同一 Docker 网络中
• 检查 docker-compose.yml 中的网络配置
• 重启所有容器

---

10. 镜像拉取失败

问题：docker compose pull 失败

常见原因：

• 网络连接问题
• Docker Hub 速率限制
• 镜像不存在

解决方案：

• 配置 Docker 镜像加速器
• 检查网络连接
• 使用国内镜像源
• 稍后重试

---

日志查看命令

查看所有服务日志

docker compose logs -f

查看特定服务日志

docker compose logs -f prometheus-central
docker compose logs -f grafana
docker compose logs -f alertmanager
docker compose logs -f victoria-metrics

查看最近 100 行日志

docker compose logs --tail=100

---

性能问题排查

高 CPU 使用率

检查：

# 查看容器资源使用
docker stats

# 检查 Prometheus 抓取目标数量
# 访问 http://localhost:9091/targets

解决：

• 减少抓取间隔
• 减少监控目标数量
• 增加资源限制

高内存使用率

检查：

docker stats

解决：

• 减少数据保留时间
• 减少抓取目标
• 增加内存限制

---

数据问题排查

数据丢失

检查：

# 检查数据目录
ls -lh /storage/prometheus-data
ls -lh /storage/victoria-metrics-data

# 检查数据保留配置
grep retention config/prometheus/prometheus.yml

解决：

• 检查数据保留时间配置
• 检查磁盘空间
• 检查数据目录权限

数据不一致

检查：

• 在 Prometheus 和 VictoriaMetrics 中查询相同指标
• 检查时间范围
• 检查标签匹配

---

获取帮助

如果以上方法无法解决问题：

1. 查看详细日志：

   docker compose logs --tail=200 > logs.txt
   

2. 收集系统信息：

   docker info > docker-info.txt
   docker compose ps > services-status.txt
   df -h > disk-usage.txt
   

3. 检查配置文件：

   • 验证所有配置文件语法
   • 检查环境变量
   • 检查网络配置

---

相关文档

• 部署指南：doc/DEPLOYMENT_GUIDE.md
• 中央服务器配置：doc/CENTRAL_SERVER_CONFIG.md
• 边缘节点配置：doc/EDGE_AGENT_CONFIG.md
• 系统架构：doc/ARCHITECTURE.md