From 641d27cc654f6865a3894814bf2337e3462ae0a2 Mon Sep 17 00:00:00 2001 From: energys Date: Thu, 24 Sep 2026 14:12:47 +0900 Subject: [PATCH] Add readme.md --- readme.md | 299 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 299 insertions(+) create mode 100644 readme.md diff --git a/readme.md b/readme.md new file mode 100644 index 0000000..7024705 --- /dev/null +++ b/readme.md @@ -0,0 +1,299 @@ +# ZONT Prometheus Exporter + +Экспортер метрик для устройств **ZONT** и **Mega SX** в формате, совместимом с **Prometheus**. Позволяет собирать данные о температуре, состоянии котла, уровне сигнала, охране и других параметрах через официальный API ZONT. + +## 📋 Возможности + +- 🔐 Аутентификация через официальный API ZONT (`my.zont.online/api`) +- 🌡️ Сбор температуры с проводных и радиодатчиков +- 🔥 Мониторинг работы котла (время работы, аварии) +- 📶 Уровень сигнала GSM/Wi-Fi +- 🛡️ Состояние охраны и сирены +- 🚗 Данные об автомобиле (ZTC): зажигание, двигатель, автозапуск +- 🐳 Готов к запуску в Docker +- ⚙️ Полностью настраивается через переменные окружения +- 🩺 Встроенный healthcheck + +## 🚀 Быстрый старт + +### 1. Клонирование проекта + +```bash +git clone <ваш-репозиторий>/zont-exporter.git +cd zont-exporter +``` + +### 2. Настройка окружения + +Создайте файл `.env` на основе примера и заполните своими данными: + +```bash +cp .env.example .env +nano .env +``` + +Пример содержимого `.env`: + +```env +ZONT_LOGIN=ваш_логин +ZONT_PASSWORD=ваш_пароль +ZONT_CLIENT_EMAIL=ваш@email.com +SCRAPE_INTERVAL=60 +EXPORTER_PORT=8000 +LOG_LEVEL=INFO +``` + +> ⚠️ **Важно**: `ZONT_CLIENT_EMAIL` — это контактный email, который вы указали при регистрации в ZONT. Он передаётся в заголовке `X-ZONT-Client` и используется производителем для связи с вами при изменениях в API. + +### 3. Запуск + +#### Вариант A: Docker Compose (рекомендуется) + +```bash +docker compose up -d --build +``` + +#### Вариант B: Docker build + run + +```bash +docker build -t zont-exporter:latest . + +docker run -d \ + --name zont-exporter \ + --restart unless-stopped \ + --env-file .env \ + -p 8000:8000 \ + zont-exporter:latest +``` + +#### Вариант C: Локальный запуск (без Docker) + +```bash +pip install -r requirements.txt +export $(cat .env | xargs) +python zont_exporter.py +``` + +### 4. Проверка работы + +```bash +# Логи +docker logs -f zont-exporter + +# Метрики +curl http://localhost:8000/metrics +``` + +В ответе вы должны увидеть метрики вида: + +``` +# HELP zont_temperature_celsius Температура с датчиков ZONT +# TYPE zont_temperature_celsius gauge +zont_temperature_celsius{device_id="1580",device_name="Дом",sensor_name="Кухня"} 22.5 + +# HELP zont_boiler_working Работает ли котел (1 - да, 0 - нет) +# TYPE zont_boiler_working gauge +zont_boiler_working{device_id="1580",device_name="Дом"} 1 +``` + +## 📊 Доступные метрики + +| Метрика | Тип | Описание | Метки | +|---|---|---|---| +| `zont_temperature_celsius` | Gauge | Температура с датчиков | `device_id`, `device_name`, `sensor_name` | +| `zont_boiler_working` | Gauge | Работа котла за последнюю минуту (1/0) | `device_id`, `device_name` | +| `zont_signal_level` | Gauge | Уровень сигнала GSM или Wi-Fi | `device_id`, `device_name`, `type` | +| `zont_guard_state` | Gauge | Состояние охраны (1 — включена, 0 — выключена) | `device_id`, `device_name` | + +## 🔗 Интеграция с Prometheus + +Добавьте job в ваш `prometheus.yml`: + +```yaml +scrape_configs: + - job_name: 'zont' + scrape_interval: 60s + static_configs: + - targets: ['zont-exporter:8000'] +``` + +Если Prometheus запущен на хосте (вне Docker), используйте `host.docker.internal` или IP вашего сервера: + +```yaml +scrape_configs: + - job_name: 'zont' + scrape_interval: 60s + static_configs: + - targets: ['host.docker.internal:8000'] +``` + +## 📈 Полный стек мониторинга + +Если у вас ещё нет Prometheus и Grafana, используйте готовый `docker-compose.yml`: + +```yaml +services: + zont-exporter: + build: . + container_name: zont-exporter + restart: unless-stopped + env_file: + - .env + networks: + - monitoring + + prometheus: + image: prom/prometheus:latest + container_name: prometheus + restart: unless-stopped + volumes: + - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro + - prometheus-data:/prometheus + ports: + - "9090:9090" + networks: + - monitoring + + grafana: + image: grafana/grafana:latest + container_name: grafana + restart: unless-stopped + volumes: + - grafana-data:/var/lib/grafana + ports: + - "3000:3000" + networks: + - monitoring + +networks: + monitoring: + driver: bridge + +volumes: + prometheus-data: + grafana-data: +``` + +После запуска: + +- **Prometheus**: http://localhost:9090 +- **Grafana**: http://localhost:3000 (логин/пароль по умолчанию: `admin`/`admin`) + +## ⚙️ Конфигурация + +Все параметры задаются через переменные окружения: + +| Переменная | Обязательна | По умолчанию | Описание | +|---|---|---|---| +| `ZONT_LOGIN` | ✅ | — | Логин от личного кабинета ZONT | +| `ZONT_PASSWORD` | ✅ | — | Пароль от личного кабинета ZONT | +| `ZONT_CLIENT_EMAIL` | ❌ | `exporter@localhost` | Контактный email (заголовок `X-ZONT-Client`) | +| `ZONT_API_URL` | ❌ | `https://my.zont.online/api` | Базовый URL API | +| `SCRAPE_INTERVAL` | ❌ | `60` | Интервал опроса в секундах | +| `EXPORTER_PORT` | ❌ | `8000` | Порт HTTP-сервера экспортера | +| `LOG_LEVEL` | ❌ | `INFO` | Уровень логирования (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | + +## 🐳 Сборка Docker-образа + +```bash +# Сборка +docker build -t zont-exporter:latest . + +# Запуск с проверкой переменных +docker run --rm --env-file .env zont-exporter:latest +``` + +### Healthcheck + +Docker автоматически проверяет доступность эндпоинта `/metrics` каждые 30 секунд. Если экспортер перестанет отвечать, контейнер будет помечен как `unhealthy`. + +Проверить статус: + +```bash +docker inspect --format='{{.State.Health.Status}}' zont-exporter +``` + +## 🔧 Расширение + +### Добавление новых метрик + +API ZONT предоставляет много данных. Чтобы добавить новую метрику, откройте `zont_exporter.py` и расширьте метод `collect()`: + +```python +# Пример: сбор пользовательских статусов (custom_controls_state) +custom_gauge = GaugeMetricFamily( + 'zont_custom_status', + 'Пользовательский статус', + labels=['device_id', 'device_name', 'status_id'] +) + +for device in devices: + custom_state = device.get('io', {}).get('custom_controls_state', {}) + for status_id, value in custom_state.items(): + custom_gauge.add_metric( + [str(device['id']), device['name'], str(status_id)], + value + ) + +yield custom_gauge +``` + +### Полезные разделы API + +Согласно [официальной документации](https://lk.zont-online.ru/api/docs/), для расширения доступны: + +- `last-boiler-state` — детальное состояние котла (OpenTherm, модуляция, давление) +- `custom_controls_state` — пользовательские статусы (ZTC-7xx, Mega SX) +- `ztc_state` — состояние контроллера (баланс SIM, напряжение, статус-флаги) +- `temperature` — история температур через `load_data` + +## 🐛 Отладка + +### Экспортер не запускается + +Проверьте логи: + +```bash +docker logs zont-exporter +``` + +Частые причины: + +- Не заданы `ZONT_LOGIN` или `ZONT_PASSWORD` +- Неверный логин/пароль +- Отсутствует доступ к `my.zont.online` + +### Метрики пустые + +- Убедитесь, что к вашему аккаунту ZONT привязаны устройства. +- Проверьте `ZONT_CLIENT_EMAIL` — некоторые методы требуют корректного контакта. +- Увеличьте `LOG_LEVEL=DEBUG` для детальной диагностики. + +### Проблемы с токеном + +Экспортер автоматически обновляет токен при получении `403`. Если проблема повторяется: + +- Убедитесь, что пароль не содержит спецсимволов, требующих экранирования. +- Проверьте, не отозван ли токен в личном кабинете ZONT. + +## 📚 Документация API ZONT + +- Официальная документация: https://lk.zont-online.ru/api/docs/ +- Облегчённое Widget API v3: https://my.zont.online/api/widget/v3 +- Сайт производителя: https://zont.online + +## 📄 Лицензия + +MIT + +## 🤝 Вклад + +Pull request'ы приветствуются. Для крупных изменений сначала откройте issue для обсуждения. + +--- + +**Полезные ссылки:** + +- [Prometheus](https://prometheus.io/) +- [Grafana](https://grafana.com/) +- [prometheus-client (Python)](https://github.com/prometheus/client_python) \ No newline at end of file