95a09fd9d8
- 增加中央与边缘完整配置和部署脚本 - 引入 VictoriaMetrics 数据源与 remote_write 故障排查说明 - 新增 edge-agent 配置脚本、ONVIF 自建 exporter 与 ping 监控示例 Co-authored-by: Cursor <cursoragent@cursor.com>
141 lines
6.3 KiB
Markdown
141 lines
6.3 KiB
Markdown
# 项目缺陷分析
|
||
|
||
基于 README、central-server 及相关文档的审查结果。
|
||
|
||
---
|
||
|
||
## 一、严重缺陷
|
||
|
||
### 1. Grafana 无法展示边缘节点数据（数据源缺失）【已修复】
|
||
|
||
**现象**：边缘节点通过 remote_write 将指标推送到 **VictoriaMetrics**，此前 Grafana 仅配置了 **Prometheus** 数据源。
|
||
|
||
**数据流与配置顺序**：
|
||
- **边缘主动上报**：边缘节点上的 Prometheus/Agent 配置了 `remote_write` 指向中央服务器的 VictoriaMetrics（`http://中央IP:8428/api/v1/write`），会主动推送指标到中央。
|
||
- **必须先配置边缘**：只有在边缘节点里配置好“中央服务器地址 + 8428 端口”并启动后，数据才会出现在 VictoriaMetrics 中；中央仅提供接收端，不会去拉边缘。
|
||
- **Grafana 看到边缘数据**：中央已增加 **VictoriaMetrics** 数据源（`grafana/provisioning/datasources/victoriametrics.yml`）后，在 Grafana 中选用 “VictoriaMetrics” 数据源即可查询这些上报上来的边缘数据；无需再配“边缘数据”本身，只需边缘按文档配置上报。
|
||
|
||
**已做修改**：
|
||
- 在 `grafana/provisioning/datasources/` 中新增 **victoriametrics.yml**，数据源 URL 为 `http://victoria-metrics:8428`。
|
||
- 边缘数据可见的前提：边缘已配置并运行，且 remote_write 指向本中央 VM（参见 `doc/EDGE_NODE_SETUP.md`、`doc/EDGE_AGENT_CONFIG.md`）。
|
||
|
||
---
|
||
|
||
### 2. docker-compose 网络名未设置默认值导致部署失败
|
||
|
||
**现象**：`docker-compose.yml` 中默认网络名为 `${NETWORK_NAME}`，未提供默认值。
|
||
|
||
```yaml
|
||
networks:
|
||
default:
|
||
name: ${NETWORK_NAME}
|
||
```
|
||
|
||
**依据**：`deploy.sh` 只 export 了部分变量，**未 export `NETWORK_NAME`**。若用户“使用默认配置”且没有 `.env`（脚本提示“未找到 .env 和 env.example”时），`NETWORK_NAME` 为空，Compose 会使用空字符串作为网络名，可能导致创建失败或行为异常。
|
||
|
||
**建议**：
|
||
- 在 `deploy.sh` 中为 `NETWORK_NAME` 设置默认值并 export，例如：
|
||
`NETWORK_NAME=${NETWORK_NAME:-central_default}` 或与 Traefik 一致时 `NETWORK_NAME=${NETWORK_NAME:-traefik}`
|
||
- 或在 `docker-compose.yml` 中写为：`name: ${NETWORK_NAME:-central_default}`
|
||
|
||
---
|
||
|
||
### 3. VictoriaMetrics 容器内监听端口与映射不一致
|
||
|
||
**现象**：容器内通过环境变量改变监听端口，与端口映射不一致。
|
||
|
||
**依据**（`docker-compose.yml`）：
|
||
|
||
```yaml
|
||
ports:
|
||
- "${VICTORIAMETRICS_PORT:-8428}:8428"
|
||
command:
|
||
- "--httpListenAddr=:${VICTORIAMETRICS_PORT:-8428}"
|
||
```
|
||
|
||
- 端口映射为「主机 `${VICTORIAMETRICS_PORT}` → 容器 **8428**」
|
||
- 若用户设置 `VICTORIAMETRICS_PORT=8430`，容器会监听 **8430**，而映射期望容器监听 **8428**，导致主机 8430 无法正确访问服务。
|
||
|
||
**建议**：容器内应固定监听 8428，仅用环境变量控制主机端口。例如：
|
||
|
||
```yaml
|
||
command:
|
||
- "--httpListenAddr=:8428"
|
||
```
|
||
|
||
---
|
||
|
||
## 二、中等问题
|
||
|
||
### 4. Alertmanager Webhook 在容器内不可达
|
||
|
||
**现象**：`alertmanager/alertmanager.yml` 中 webhook 为 `http://127.0.0.1:5001/`。
|
||
|
||
在容器内 `127.0.0.1` 指向 Alertmanager 自身，无法访问宿主机上的 webhook 服务，告警无法送达。
|
||
|
||
**建议**：
|
||
- Linux 下可使用 `http://host.docker.internal:5001/`（若 Docker 支持）
|
||
- 或使用宿主机在 Docker 网桥上的 IP，并在文档中说明需替换为实际地址
|
||
|
||
---
|
||
|
||
### 5. 默认启用 Traefik 且为示例域名，不利于“快速开始”
|
||
|
||
**现象**：`env.example` 中 `TRAEFIK_ENABLED=true`，且域名为 `grafana.example.com` 等。README 的“快速开始”是 `http://localhost:3000`。
|
||
|
||
**结果**：新用户若直接 `cp env.example .env` 并部署，会默认走 Traefik + 示例域名，本地浏览器无法用 localhost 访问，与文档体验不一致。
|
||
|
||
**建议**：
|
||
- `env.example` 中默认设为 `TRAEFIK_ENABLED=false`，便于本地快速开始
|
||
- 或在 README/CONFIGURATION 中明确写：本地试用请将 `TRAEFIK_ENABLED=false`，并说明 Traefik 为可选
|
||
|
||
---
|
||
|
||
### 6. 部署脚本未导出 NETWORK_NAME
|
||
|
||
**现象**：`deploy.sh` 中通过 `set -a; source .env` 可导出 .env 中的变量，但若没有 .env，或 .env 中未写 `NETWORK_NAME`，则 Compose 收到的 `NETWORK_NAME` 可能为空。
|
||
|
||
**建议**：在 deploy.sh 的“设置默认值”或 export 段落中显式设置并 export：
|
||
|
||
```bash
|
||
NETWORK_NAME=${NETWORK_NAME:-traefik}
|
||
export NETWORK_NAME
|
||
```
|
||
|
||
与第 2 点一起修复，可避免无 .env 或漏配时的部署问题。
|
||
|
||
---
|
||
|
||
## 三、文档/一致性问题
|
||
|
||
### 7. 架构文档与实现不一致
|
||
|
||
**现象**：`doc/ARCHITECTURE.md` 描述“Prometheus 从 VictoriaMetrics 读取数据”，但当前 `prometheus.yml` 仅有 **remote_write** 到 VictoriaMetrics，没有 **remote_read**。
|
||
|
||
**建议**：修改文档为“Prometheus 将本地抓取数据 remote_write 到 VictoriaMetrics；边缘数据仅存在于 VictoriaMetrics”，并说明 Grafana 如需查边缘数据应使用 VictoriaMetrics 数据源（与第 1 点修复一致）。
|
||
|
||
---
|
||
|
||
### 8. 示例密码与安全建议不一致
|
||
|
||
**现象**：README 和配置中默认管理员密码为 `admin123`，CONFIGURATION.md 建议“首次部署后请立即修改”“生产环境必须修改”。
|
||
|
||
**建议**：在 README 快速开始处增加一句：“默认密码仅用于首次登录，生产环境请立即修改”，并在部署成功输出中再次提醒。
|
||
|
||
---
|
||
|
||
## 四、小结
|
||
|
||
| 优先级 | 缺陷 | 建议 |
|
||
|--------|------|------|
|
||
| ~~高~~ | ~~Grafana 缺少 VictoriaMetrics 数据源~~ | ✅ 已增加 `victoriametrics.yml`；边缘需先配置 remote_write 指向中央 VM |
|
||
| 高 | Compose 网络名无默认值 | 为 NETWORK_NAME 设默认并 export |
|
||
| 高 | VictoriaMetrics 容器监听端口与端口映射不一致 | 容器内固定监听 8428 |
|
||
| 中 | Alertmanager webhook 127.0.0.1 在容器内无效 | 改为 host.docker.internal 或宿主机 IP并文档说明 |
|
||
| 中 | 默认启用 Traefik + 示例域名 | 默认关闭 Traefik 或文档明确本地试用步骤 |
|
||
| 中 | deploy 未导出 NETWORK_NAME | 在 deploy.sh 中设置并 export |
|
||
| 低 | 架构文档与实现不符 | 更新 ARCHITECTURE.md |
|
||
| 低 | 默认密码与安全建议 | 在 README 和部署输出中强调修改密码 |
|
||
|
||
以上为当前发现的主要缺陷与改进建议，优先修复前三条可显著提升部署成功率和“边缘+中央”统一监控的可用性。
|