ProxmoxDash/README.md

# Proxmox CPU Dashboard

Локальная веб-панель CPU для Proxmox. Данные читаются напрямую из `/proc` и
`/sys`, без Proxmox API. Интерфейс обновляется каждые две секунды.

## Установка для новичка — скопируйте команды целиком

### Что потребуется

- сервер Proxmox VE с доступом в интернет или к `git.myown.center`;
- вход в консоль Proxmox под пользователем `root`;
- IP-адрес Proxmox в локальной сети;
- свободный TCP-порт `9105` между вашим компьютером и Proxmox.

Go, Node.js, Docker и отдельную базу данных устанавливать не нужно. Панель
поставляется готовым Linux-бинарником, а SQLite встроен внутрь.

### 1. Подключитесь к Proxmox

На своём компьютере откройте Terminal и выполните команду, заменив IP на адрес
своего Proxmox:

```bash
ssh root@192.168.0.10
```

Введите пароль `root`. Следующие команды выполняйте уже внутри Proxmox.

### 2. Установите панель

Скопируйте весь блок и вставьте его в консоль Proxmox:

```bash
apt-get update
apt-get install -y curl ca-certificates tar smartmontools iproute2 iputils-ping

cd /tmp
curl -fL \
  https://git.myown.center/maxim/ProxmoxDash/releases/download/latest/proxmox-dashboard-install-amd64.tar.gz \
  -o proxmox-dashboard-install-amd64.tar.gz

tar -xzf proxmox-dashboard-install-amd64.tar.gz
cd proxmox-dashboard-install
UPDATE_MODE=notify ./scripts/install.sh
```

Готово. Установщик сам:

- положит бинарник в `/usr/local/bin`;
- создаст локальную базу настроек и истории;
- установит systemd-службу;
- запустит панель;
- настроит ежедневную проверку новых версий;
- сохранит предыдущий бинарник при будущем обновлении.

### 3. Откройте панель

В браузере на своём компьютере откройте:

```text
http://192.168.0.10:9105
```

Замените `192.168.0.10` на IP своего Proxmox. Узнать адрес можно командой:

```bash
hostname -I
```

### 4. Проверьте, что всё работает

```bash
systemctl --no-pager --full status proxmox-cpu-dashboard.service
curl -I http://127.0.0.1:9105
```

В статусе службы должно быть `active (running)`, а локальная проверка должна
вернуть HTTP-ответ `200 OK`.

### Как обновлять

В режиме `notify`, установленном командами выше, откройте в панели
`Настройки → Обновления` и нажмите `Проверить и установить обновление`.

Если нужны полностью автоматические обновления, повторно запустите установщик:

```bash
cd /tmp/proxmox-dashboard-install
UPDATE_MODE=auto ./scripts/install.sh
```

### Если репозиторий станет приватным

Создайте в Gitea токен только для чтения репозитория и передайте его
установщику. Вместо текста `ВАШ_ТОКЕН` вставьте настоящий токен:

```bash
cd /tmp/proxmox-dashboard-install
GITEA_TOKEN='ВАШ_ТОКЕН' UPDATE_MODE=notify ./scripts/install.sh
```

Токен сохраняется на Proxmox с правами `0600` и не показывается в браузере.

### Если страница не открывается

Выполните на Proxmox:

```bash
systemctl restart proxmox-cpu-dashboard.service
systemctl --no-pager --full status proxmox-cpu-dashboard.service
journalctl -u proxmox-cpu-dashboard.service -n 100 --no-pager
ss -lntp | grep 9105
```

Проверьте, что используете правильный IP, порт `9105` доступен из локальной
сети, а firewall Proxmox не блокирует подключение. Панель пока не имеет
авторизации — не публикуйте порт `9105` напрямую в интернет.

---

Панель показывает:

- изменение критичных SMART-счётчиков, результаты self-test и исчезновение дисков;
- realtime read/write IOPS, MB/s, latency, utilization и глубину очереди каждого диска;
- недельную историю IOPS/utilization и алерты при устойчивом I/O-давлении;
- вероятный источник I/O: VM/LXC, процесс хоста или активная backup/snapshot/migration-задача;
- отдельные пороги HDD, SATA SSD и NVMe с исключениями по имени или серийному номеру;
- недельные baseline-аномалии IOPS, latency, температуры, RAM, ZFS и длительности backup;
- корреляцию связанных событий в одну причинно-следственную цепочку;
- время первого появления и последнего наблюдения каждого уведомления;
- автоматический короткий SMART self-test раз в неделю для дисков без свежего теста;
- datasets, vdev-классы, ошибки read/write/checksum, scrub и ARC ZFS;
- доступность шлюза, DNS и интернета, packet loss, latency и внешний IP;
- тип, состояние, скорость, duplex и master сетевых интерфейсов;
- состояние связи с NUT/apcupsd, возраст батареи и расчётную автономность UPS;
- настраиваемый сценарий корректного выключения VM/LXC и Proxmox с безопасным dry-run;
- самоконтроль сборщика, записи истории, свободного места базы и systemd watchdog;

- модель и текущую загрузку CPU;
- количество сокетов, физических ядер и логических потоков;
- среднюю текущую частоту;
- load average за 1, 5 и 15 минут;
- uptime;
- доступные аппаратные температуры.
- использование RAM, доступную память, кэш, буферы и swap.
- заполнение системного диска `/`;
- список физических дисков, модель, серийный номер, SMART, температуру, наработку
  и доступные данные об износе;
- текущую скорость и суммарные счётчики сетевого трафика.
- состояние, заполнение, фрагментацию и scrub/resilver ZFS-пулов;
- состояние UPS через NUT или apcupsd, заряд, автономность, нагрузку и напряжение.
- состояние VM и LXC, CPU, память, выделенные ядра и uptime.
- IP-адреса VM через QEMU Guest Agent, автозапуск, storage, заполнение диска и
  суммарный сетевой трафик гостей;
- последнюю найденную резервную копию каждой VM/LXC, storage, размер и возраст.
- версию Proxmox, запущенное и последнее установленное ядро, доступные
  обновления, необходимость перезагрузки, последнее обновление системы,
  ближайшие backup и ZFS scrub.
- управляемый мониторинг HTTP/HTTPS, TCP и ping для homelab-сервисов: отклик,
  ожидаемый код и текст, TLS-сертификат, uptime за сутки и неделю;
- ошибки systemd и ядра за 24 часа, упавшие службы, ошибки и drops каждого
  сетевого интерфейса.
- snapshots VM/LXC с возрастом, описанием и доступным размером;
- последние задачи Proxmox: backup, start/stop, snapshot, migration, пользователь,
  длительность и результат;
- сравнение размера backup с предыдущей копией и ручную безопасную проверку
  читаемости локального архива или конфигурации PBS snapshot;
- карту homelab: Proxmox, VM/LXC, сервисы и используемые storage.

Через кнопку настроек можно скрывать неиспользуемые карточки и переключать
светлую или тёмную тему. Карточки можно переставлять перетаскиванием или
стрелками в настройках. Видимость, порядок и тема сохраняются локально в
браузере.

Центр уведомлений объединяет критические события, предупреждения и
информационные сообщения по CPU, памяти, storage, SMART, ZFS, UPS, VM/LXC и
резервным копиям. Критические события всегда отображаются первыми.

Во вкладке `Настройки → Почта` настраиваются SMTP-сервер, получатель и интервал
агрегированной сводки. Можно отдельно выбрать уровни важности и источники
событий — например, полностью исключить уведомления о резервных копиях. Там же
доступна отправка тестового письма. Поддерживаются STARTTLS (обычно порт 587) и
SMTP поверх TLS (порт 465).

Тема письма кодируется по MIME и корректно отображает кириллицу. Сам дайджест
оформлен как HTML-письмо и содержит только новые неподтверждённые события — уже
отправленные или принятые события повторно не рассылаются. В центре уведомлений
есть вкладки активных событий и 30-дневной истории. Кнопка `Принято` скрывает
событие из активных, не удаляя его из журнала; повторное возникновение проблемы
создаёт новое событие.

Критические события отправляются сразу, не ожидая очередной сводки. К ним
относятся недоступность сервиса, отказ SMART/ZFS/systemd, критический перегрев и
низкий заряд UPS. Переход UPS на батарею также отправляется немедленно. После
устранения уже отправленной проблемы приходит отдельное уведомление о
восстановлении.

Пороги уведомлений сохраняются в SQLite и настраиваются через вкладку
`Настройки → Уведомления`. Панель раз в минуту сохраняет историю CPU,
температуры, памяти, swap, сети, storage, ZFS, UPS и гостей. Данные старше семи
дней удаляются автоматически. В подробных окнах карточек текущие показатели и
история разделены на вкладки. Для графиков можно выбрать последний час, 24 часа
или 7 дней, а точные значения и время отображаются при наведении.

База данных по умолчанию находится здесь:

```text
/var/lib/proxmox-dashboard/dashboard.db
```

Готовые версии для Linux публикуются в разделе Releases репозитория. Бинарник
не требует установки Go или системной библиотеки SQLite.

Проверка обновлений выполняется отдельным systemd-таймером раз в сутки. Статус
виден во вкладке `Настройки → Обновления` и в центре уведомлений. Доступны два
режима: `notify` только сообщает о новой версии, `auto` скачивает её, сохраняет
предыдущий бинарник как резервный и перезапускает панель. В режиме `notify`
обновление можно запустить кнопкой `Проверить и установить обновление` в
настройках. Запрос выполняет отдельная системная служба.

На главном экране находятся компактные карточки CPU, памяти, диска и сети.
Нажатие на карточку открывает подробные показатели.

## Быстрый запуск

Скопируйте `dist/proxmox-cpu-dashboard-linux-amd64` на Proxmox, затем:

```bash
chmod +x proxmox-cpu-dashboard-linux-amd64
./proxmox-cpu-dashboard-linux-amd64
```

## Установка на сервер и обновления

Скачайте из Releases архив `proxmox-dashboard-install-amd64.tar.gz`, распакуйте
его на Proxmox и запустите от root:

```bash
tar -xzf proxmox-dashboard-install-amd64.tar.gz
cd proxmox-dashboard-install
UPDATE_MODE=notify ./scripts/install.sh
```

Для полностью автоматических обновлений используйте `UPDATE_MODE=auto`.
Приватному репозиторию нужен read-only API-токен Gitea:

```bash
GITEA_TOKEN='read-only-token' UPDATE_MODE=auto ./scripts/install.sh
```

Токен сохраняется с правами `0600` в `/etc/proxmox-dashboard/update.env`.
Проверить обновления вручную можно командой:

```bash
systemctl start proxmox-dashboard-update.service
systemctl status proxmox-dashboard-update.service
```

Откройте:

```text
http://192.168.0.10:9105
```

## Установка как службы

```bash
install -m 0755 proxmox-cpu-dashboard-linux-amd64 /usr/local/bin/proxmox-cpu-dashboard
install -m 0644 proxmox-cpu-dashboard.service /etc/systemd/system/proxmox-cpu-dashboard.service
systemctl daemon-reload
systemctl enable --now proxmox-cpu-dashboard
systemctl status proxmox-cpu-dashboard
```

По умолчанию панель слушает порт `9105` на всех интерфейсах. Другой адрес можно
задать переменной `DASHBOARD_ADDR`, например `127.0.0.1:9105`.

На веб-сервере пока нет авторизации. Не открывайте порт `9105` в интернет.

Для SMART-метрик на Proxmox должен быть установлен пакет `smartmontools`:

```bash
apt update
apt install -y smartmontools
```

Без него список дисков и их паспортные данные продолжат отображаться, а SMART
будет отмечен как недоступный.

Проверить исходные SMART-данные вручную:

```bash
smartctl -x /dev/sda
smartctl -x -j /dev/sda
smartctl -x /dev/nvme0n1
```

У HDD обычно нет показателя износа в процентах. Для NVMe используется
`Percentage Used`, а для SATA SSD — поддерживаемые накопителем атрибуты ресурса.
Если производитель не публикует такой атрибут, панель корректно показывает `—`.

## UPS

Панель автоматически пробует получить данные через NUT (`upsc`), затем через
`apcaccess`. Для проверки NUT:

```bash
upsc -l
upsc ИМЯ_UPS
```

Для проверки apcupsd:

```bash
apcaccess status
```

## API

- `GET /api/cpu` — один JSON-снимок.
- `GET /api/system` — единый JSON-снимок CPU и памяти.
- `GET /api/events` — поток метрик SSE с интервалом две секунды.
- `GET/POST/PUT/DELETE /api/services` — управление проверками сервисов.
- `GET /api/services/history` — семидневная история доступности и отклика.
- `GET/PUT/DELETE /api/settings/maintenance` — состояние, запуск и досрочное завершение плановых работ.
- `GET/DELETE /api/agents` — подключённые гостевые агенты.
- `POST /api/agents/enrollment-token` — одноразовый токен регистрации на 15 минут.

## Maintenance-режим

Во вкладке `Настройки → Maintenance` можно на заданное время отключить все
алерты либо выбрать конкретные сервисы и VM/LXC. Подавленные события не
отправляются по почте и не отображаются как активные, но сохраняются в истории
с причиной плановых работ. После окончания окна обычный мониторинг включается
автоматически.

## Агенты VM и LXC

Read-only агент показывает состояние Linux внутри VM/LXC: CPU, load average,
память, корневой раздел, uptime, ОС, ядро, IP-адреса, systemd-службы, доступные
APT-обновления и необходимость перезагрузки. Для Docker отображаются контейнеры,
health-check, число перезапусков, CPU и память. Агент сам подключается к Dashboard
каждые 10 секунд; открывать входящий порт внутри гостевой системы не нужно.

В подробностях агента systemd-службы разделяются на системные, установленные
дополнительно и локальные unit-файлы. Для каждой службы показываются пакет и путь
unit-файла, время запуска, число перезапусков, последний exit code, память и
накопленное CPU-время, когда соответствующий accounting доступен в systemd.

Расширенная диагностика агента включает последние сообщения проблемных служб,
`Requires`/`After`, PID, команду запуска и слушающие порты; выявляет частые
рестарты, OOM-kill и процессы в D-state. Отдельно отображаются top процессов по
CPU и RAM с накопленным I/O, swap, PSI pressure, все постоянные файловые системы,
их заполнение и использование inode.

Панель «Диагностика homelab» и карта сопоставляют известные IP и порты с VM/LXC,
агентом, systemd-службой или Docker-контейнером и настроенной HTTP/TCP-проверкой.
Связи по PID и порту считаются подтверждёнными; совпадения только по названию
помечаются как предположение.

Для сложных reverse proxy и Docker-сетей в управлении сервисами можно сохранить
ручную связь `сервис → агент/VMID → systemd/Docker/процесс → порт`. Она имеет
приоритет над автоматическим определением и используется для группировки
связанных уведомлений по первопричине.

Dashboard хранит семь дней истории CPU, RAM, swap, PSI и файловых систем каждого
агента. Из подробностей агента доступны только заранее разрешённые действия:
перезапуск известной systemd-службы или Docker-контейнера, `reset-failed` и
обновление списка пакетов. Агент не принимает произвольные shell-команды; каждое
действие требует подтверждения в браузере и сохраняется в журнале управления.

Откройте `Настройки → Агенты`, укажите адрес Dashboard, доступный из VM/LXC, и
VMID. Кнопка создаст готовую команду установки. Одноразовый токен действует 15
минут и после регистрации заменяется индивидуальным секретом агента.

После однократной установки агент обновляется автоматически вслед за Dashboard.
Центральный сервер отдаёт агенту собственный бинарник и SHA-256; агент проверяет
контрольную сумму, атомарно заменяет файл и перезапускается через systemd. Если
агент был удалён из Dashboard, повторная команда с новым токеном автоматически
выполнит новую регистрацию.

В первой версии агент не выполняет команды и не перезапускает службы или
контейнеры. Для чтения Docker ему требуется доступ к `/var/run/docker.sock`,
поэтому служба устанавливается от root. Сам Dashboard пока не имеет
авторизации: используйте локальную сеть или HTTPS через доверенный reverse
proxy и не публикуйте агентские API напрямую в интернет.

Полностью удалить агент из VM/LXC:

```bash
curl -fsSL https://git.myown.center/maxim/ProxmoxDash/raw/branch/main/scripts/uninstall-agent.sh | sh
```

Оформление, пороги, почта и обновления Dashboard находятся в обычных настройках.
Рабочие инструменты — сервисы, агенты, плановые работы и UPS-сценарий — вынесены
в отдельный раздел `Управление` в шапке Dashboard.

## Сборка

```bash
go test ./...
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o proxmox-cpu-dashboard .
```