完善中央与边缘部署、远程写入与监控文档

- 增加中央与边缘完整配置和部署脚本 - 引入 VictoriaMetrics 数据源与 remote_write 故障排查说明 - 新增 edge-agent 配置脚本、ONVIF 自建 exporter 与 ping 监控示例 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-25 04:24:40 -05:00
parent 9e37f79a36
commit 95a09fd9d8
52 changed files with 5978 additions and 0 deletions
--- a/doc/TROUBLESHOOTING.md
+++ b/doc/TROUBLESHOOTING.md
@@ -0,0 +1,422 @@
+# 故障排查指南
+
+## 常见问题及解决方案
+
+### 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`