# 部署指南

部署顺序见 **[doc/README.md](README.md)#部署顺序**：**第一步 中央服务器 → 第二步 边缘节点 → 第三步（可选）多用户与告警**。本文为各步的详细说明、检查清单与常见问题。

---

## 第一步：部署中央服务器

### 前置要求

- Docker 与 Docker Compose 已安装
- 根分区至少约 1GB 可用；数据目录所在分区至少约 2GB
- 端口未被占用：3000（Grafana）、9091（Prometheus）、8428（VictoriaMetrics）、9093（Alertmanager）
- 若需外网访问：防火墙开放上述端口

### 操作步骤

1. 进入目录并准备环境（可选）：
   ```bash
   cd central-server
   cp env.example .env    # 可选：修改端口、Traefik、网络等
   ```

2. 执行部署：
   ```bash
   bash deploy.sh
   ```

3. 等待约 15 秒后检查：
   ```bash
   docker compose ps
   ```

4. 验证访问：
   - Grafana: http://localhost:3000（默认 admin / admin123）
   - Prometheus: http://localhost:9091
   - VictoriaMetrics: http://localhost:8428
   - Alertmanager: http://localhost:9093

### 中央服务器检查清单

- [ ] Docker、Docker Compose 已安装
- [ ] 磁盘空间充足（根分区约 1GB+，数据分区约 2GB+）
- [ ] 端口 3000、9091、8428、9093 未被占用
- [ ] 需要时已开放防火墙
- [ ] 部署后能打开 Grafana、Prometheus

---

## 第二步：部署边缘节点

**前提**：第一步中央服务器已部署并正常运行（尤其 VictoriaMetrics 8428 可访问）。

### 前置要求

- Docker、Docker Compose 已安装
- `jq` 已安装（用于生成 JSON 配置）
- 边缘节点能访问中央服务器（能访问中央 IP:8428）
- 如需监控 ONVIF/网络设备：网络可达这些设备

### 情形 A：本机同机部署（中央与边缘在同一台机器）

```bash
cd edge-agent
bash run-edge-local.sh
```

脚本会自动将中央地址设为 `host.docker.internal:8428` 并执行部署。边缘 Prometheus UI：http://localhost:9092。

### 情形 B：边缘在另一台机器

1. 进入目录并配置中央地址：
   ```bash
   cd edge-agent
   cp env.example .env
   ```
   编辑 `.env`：
   - `CENTRAL_SERVER_HOST=` 中央服务器 IP 或域名
   - `CENTRAL_SERVER_PORT=8428`

2. 配置监控目标并生成配置：
   ```bash
   # 编辑 config/targets.csv（Ping / ONVIF），详见 TARGETS_CSV_GUIDE.md
   cd config && chmod +x *.sh && ./update-configs.sh && cd ..
   ```

3. 部署：
   ```bash
   bash deploy.sh
   ```

4. 验证：
   - 边缘 Prometheus: http://localhost:9092（或边缘机器 IP:9092）
   - 在中央 Grafana 中**选择数据源「VictoriaMetrics」**，查询如 `up{job="network-ping"}` 或 `up{region="workernode_1"}` 应能看到边缘数据

### 边缘节点检查清单

- [ ] 中央服务器已部署且 VictoriaMetrics 可访问（端口 8428）
- [ ] `.env` 中 `CENTRAL_SERVER_HOST`、`CENTRAL_SERVER_PORT` 正确
- [ ] `config/targets.csv` 已配置（或已生成 `onvif-targets.json`、`ping-targets.json`）
- [ ] 已执行 `config/update-configs.sh`
- [ ] 边缘能访问中央 8428 端口
- [ ] 部署后在 Grafana 的 VictoriaMetrics 数据源中能看到边缘指标

---

## 第三步（可选）：多用户与告警

- **Grafana 多用户**：在中央服务器上执行 `cd central-server/grafana && bash setup-users.sh`，然后按 [USER_MANAGEMENT.md](USER_MANAGEMENT.md) 配置组织、用户与数据源。
- **告警规则**：中央已内置 `alert_rules.yml`；如需调整见 [ALERT_RULES_EXPLANATION.md](ALERT_RULES_EXPLANATION.md)。
- **告警通知**：编辑 `central-server/alertmanager/alertmanager.yml` 配置接收端，见 [ALERTMANAGER_CONFIG.md](ALERTMANAGER_CONFIG.md)。

---

## 部署后验证

### 中央

- `docker compose ps` 中 prometheus-central、grafana、victoria-metrics、alertmanager 为 Up
- 能打开 Grafana、Prometheus、Alertmanager、VictoriaMetrics 的 Web 界面
- Grafana 中「Prometheus」数据源可查询到中央自身指标（如 `up`）

### 边缘

- `docker compose ps` 中 prometheus-edge、onvif-exporter、blackbox-exporter 为 Up
- 边缘 Prometheus http://localhost:9092/targets 中目标状态正常
- 中央 Grafana 中**选择数据源「VictoriaMetrics」**，能查到边缘相关指标（如 `up{job="network-ping"}`）

---

## 常见部署问题

### 端口冲突

- 现象：容器启动失败，提示端口已被占用。
- 处理：`netstat -tulpn | grep <端口>` 或 `ss -tulpn` 查看占用；修改对应 `docker-compose.yml` 端口映射或关闭占用进程。

### 磁盘空间不足

- 现象：拉镜像或启动失败。
- 处理：`df -h` 检查空间；`docker system prune -a --volumes` 清理（注意会删未用卷）；保证数据目录所在分区空间充足。

### 边缘无法连接中央

- 现象：边缘数据未出现在中央 Grafana 的 VictoriaMetrics 中。
- 处理：从边缘节点 `telnet <中央IP> 8428` 或 `curl -s -o /dev/null -w "%{http_code}" http://<中央IP>:8428/health`；检查防火墙与 `.env` 中 `CENTRAL_SERVER_HOST`、`CENTRAL_SERVER_PORT`。

### Grafana 中看不到边缘数据

- 确认在 Grafana 里选择的是**数据源「VictoriaMetrics」**，不是「Prometheus」（中央自抓数据在 Prometheus）。
- 确认边缘已部署且 remote_write 指向中央 8428；边缘 Prometheus 日志无推送错误。

---

## 相关文档

- 部署顺序总览：[README.md#部署顺序](README.md)
- 中央配置：[CENTRAL_SERVER_CONFIG.md](CENTRAL_SERVER_CONFIG.md)、[central-server/CONFIGURATION.md](../central-server/CONFIGURATION.md)
- 边缘配置与目标：[EDGE_NODE_SETUP.md](EDGE_NODE_SETUP.md)、[EDGE_AGENT_CONFIG.md](EDGE_AGENT_CONFIG.md)、[TARGETS_CSV_GUIDE.md](TARGETS_CSV_GUIDE.md)
- 架构：[ARCHITECTURE.md](ARCHITECTURE.md)
- 故障排查：[TROUBLESHOOTING.md](TROUBLESHOOTING.md)