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

- 增加中央与边缘完整配置和部署脚本
- 引入 VictoriaMetrics 数据源与 remote_write 故障排查说明
- 新增 edge-agent 配置脚本、ONVIF 自建 exporter 与 ping 监控示例

Co-authored-by: Cursor <cursoragent@cursor.com>

doc/PROJECT_DEFECTS.md

@@ -0,0 +1,140 @@
+# 项目缺陷分析
+
+基于 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 和部署输出中强调修改密码 |
+
+以上为当前发现的主要缺陷与改进建议，优先修复前三条可显著提升部署成功率和“边缘+中央”统一监控的可用性。