Distributed-Prometheus/doc/TROUBLESHOOTING.md

# 故障排查指南

## 常见问题及解决方案

### 1. 边缘节点 ONVIF Exporter 镜像

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

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

**建议**：采用替代方案，详见 **[ONVIF_ALTERNATIVES.md](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. 服务启动失败

#### 问题：容器无法启动

**检查步骤**：
```bash
# 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**  
   在**中央服务器**上执行（或浏览器访问）：
   ```bash
   curl -sG 'http://localhost:8428/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"}`  
   有曲线即表示远程写入且可查询。

**检查步骤**：
```bash
# 1. 检查边缘节点 Prometheus
curl http://localhost:9092/api/v1/query?query=up

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

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

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

**常见原因**：
- 中央服务器地址配置错误
- 网络不通
- 防火墙阻止
- VictoriaMetrics 服务未运行

**解决方案**：
- 检查 `.env` 文件中的 `CENTRAL_SERVER_HOST`
- 测试网络连通性
- 检查防火墙规则
- 确认中央服务器 VictoriaMetrics 正常运行

---

### 4. 告警规则未激活

#### 问题：告警规则显示为 inactive

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

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

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

**常见原因**：
- 指标不存在（边缘节点未推送数据）
- 告警规则表达式错误
- 告警规则文件未加载

**解决方案**：
- 部署边缘节点并配置监控目标
- 检查告警规则表达式
- 确认 `prometheus.yml` 中引用了 `alert_rules.yml`
- 重启 Prometheus 容器

---

### 4. Grafana 无法查询数据

#### 问题：Grafana 中查询不到数据

**检查步骤**：
```bash
# 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. 磁盘空间不足

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

**检查步骤**：
```bash
# 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. 端口冲突

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

**检查步骤**：
```bash
# 1. 检查端口占用
netstat -tulpn | grep <端口>
# 或
ss -tulpn | grep <端口>

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

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

---

### 7. 配置文件语法错误

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

**检查步骤**：
```bash
# 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. 权限问题

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

**检查步骤**：
```bash
# 1. 检查目录权限
ls -ld /storage/prometheus-data
ls -ld /storage/grafana-data

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

**解决方案**：
```bash
# Prometheus 数据目录
chmod 777 /storage/prometheus-data

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

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

---

### 9. 网络问题

#### 问题：容器间无法通信

**检查步骤**：
```bash
# 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 镜像加速器
- 检查网络连接
- 使用国内镜像源
- 稍后重试

---

## 日志查看命令

### 查看所有服务日志
```bash
docker compose logs -f
```

### 查看特定服务日志
```bash
docker compose logs -f prometheus-central
docker compose logs -f grafana
docker compose logs -f alertmanager
docker compose logs -f victoria-metrics
```

### 查看最近 100 行日志
```bash
docker compose logs --tail=100
```

---

## 性能问题排查

### 高 CPU 使用率

**检查**：
```bash
# 查看容器资源使用
docker stats

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

**解决**：
- 减少抓取间隔
- 减少监控目标数量
- 增加资源限制

### 高内存使用率

**检查**：
```bash
docker stats
```

**解决**：
- 减少数据保留时间
- 减少抓取目标
- 增加内存限制

---

## 数据问题排查

### 数据丢失

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

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

**解决**：
- 检查数据保留时间配置
- 检查磁盘空间
- 检查数据目录权限

### 数据不一致

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

---

## 获取帮助

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

1. **查看详细日志**：
   ```bash
   docker compose logs --tail=200 > logs.txt
   ```

2. **收集系统信息**：
   ```bash
   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`