Newer
Older
gnexus-book / 10-systems / services / hard-panel.md

owner: gmikcon status: active last_reviewed: 2026-10-04 review_interval: 90d confidence: high

source_of_truth: deployment-verified

hard-panel (GHard Monitor)

Панель мониторинга серверов: приём метрик от агентов hard-monitor, SQLite, ивенты, алерты, веб-интерфейс (Vue 3 + gnexus-ui-kit + chart.js). С версии 2026-09-11 — мониторинг сетевых дисков (NFS-шары через os.statvfs). С версии 2026-10-04 (b6080d0, v1.30.0) — gnexus-auth (OAuth PKCE), health-чекер сервисов, журнал событий, интеграция с Gnexus Synapse, i18n (en/uk/ru), MCP-промпт agent_guide. С 40a8810 — персональные MCP-ключи.

  • Репозиторий: https://git.gnexus.space/root/hard-panel (ветка master)
  • Хост: VM service на hp-proliant-dl380-g6, адрес 192.168.1.176
  • SSH: root / пароль в gnexus-creds (секрет hard-panel (192.168.1.176)), также ubuntu с тем же паролем
  • ОС: Ubuntu 22.04.5 LTS, 4 GB RAM, 31 GB диск

Панель

  • Docker Compose: /opt/hard-panel/docker-compose.yml, контейнер ghard-panel
  • Порт: 8000 (HTTP, без TLS — доступ только из LAN)
  • Конфиг: /opt/hard-panel/.env (GHARD_ADMIN_TOKEN, GHARD_DATABASE_PATH=/data/hard-panel.db, GHARD_OFFLINE_MULTIPLIER=3)
  • Данные: docker volume panel-data (SQLite, WAL)
  • Health: http://192.168.1.176:8000/api/v1/health → {"status":"ok"}
  • UI: http://192.168.1.176:8000/ (без логина; после включения gnexus-auth — вход через OAuth PKCE)
  • API: http://192.168.1.176:8000/docs (OpenAPI)
  • MCP: http://192.168.1.176:8000/mcp (streamable HTTP; тулы panel_overview, server_details, server_history, services_overview, service_incidents, events_recent; промпт agent_guide — инструкции агенту)
  • MCP-ключи: страница /mcp-keys — выпуск и ревок персональных токенов mcp_* (plaintext показывается один раз, в БД sha256-хэш + хвост-хинт)
  • Логи: docker logs ghard-panel

Важно про GHARD_ADMIN_TOKEN

  • Веб-интерфейс не умеет подписывать запросы токеном (panel/frontend/src/api.js): если токен задан, UI получает 401 и показывает пустой список серверов.
  • В docker-compose.yml дефолт ${GHARD_ADMIN_TOKEN:-change-me} подставляет change-me даже при пустой переменной в .env. Локально исправлено на строгую форму ${GHARD_ADMIN_TOKEN-} (2026-09-10) — при git pull проверить, не вернулся ли старый синтаксис (проверено 2026-10-04 дважды, форма сохранена).
  • Текущее состояние: токен пустой (API и UI открыты, доступ только из LAN). Если панель когда-нибудь выйдет в интернет — задать токен и закрыть /mcp на reverse proxy.
  • Старый сгенерированный токен хранится в gnexus-creds (секрет hard-panel (192.168.1.176), поле admin_token) на случай, если токен снова включат.
  • С 40a8810 токен работает как супер-токен для /mcp (гард require_mcp): персональный Bearer mcp_* ИЛИ статический GHARD_ADMIN_TOKEN ИЛИ браузерная cookie-сессия gnexus-auth.

Update 2026-10-04 21:30 (navi rei) — auth, ui-kit 1.0, health-чекер, Synapse

  • Обновление edb6cff..b6080d0 (19 коммитов, 44 файла +3897/−251), версия MCP serverInfo 1.30.0.
  • Новое: закрытие панели за gnexus-auth (OAuth PKCE, f52c853), gnexus-ui-kit 1.0 + тема Verdant + новый логотип (9625022, cd5b630), health-чекер сервисов — раздел «Сервисы», страницы сервисов с графиком и журналом недоступности (c6e8698, 19812b4, 5eef1bd), парсер самосвидетельства health-ответов по handbook spec §5 (fe202ff), журнал событий (fe6b21e), интеграция с Gnexus Synapse — этап 4 (fe6b21e), MCP: промпт agent_guide + тулы сервисов и журнала (fc0de93), i18n en/uk/ru + раздел Settings (b1a82e2), заметка сервера 184px + resize (af2cd8f), фиксы графиков/навигации/no-store (dfc511f, 50a9262, 9953bae, 84dfcfc).
  • Апстрим compose прокидывает все задокументированные env: GHARD_AUTH_* (BASE_URL, CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, WEBHOOK_SECRET, ALLOWLIST), GHARD_SHARE_INTERVAL, GHARD_HEALTH_INTERVAL/TIMEOUT, GHARD_SYNAPSE_URL/API_KEY/DEFAULT_SOURCE/TIMEOUT.
  • Конфликт stash pop в docker-compose.yml разрешён вручную: апстримный env-блок + локальные правки (строгая форма токена, 4 NAS-тома :slave). docker compose config валиден.
  • Бэкап БД до обновления: внутри volume /data — hard-panel.db.bak-preupdate-20261004-2127 (файловая копия) и hard-panel.db.bak-sqlite-20261004-2127 (консистентный sqlite3 backup API, 1.6 GB).
  • Миграции: новых таблиц нет как отдельного шага — схема создана/расширена при старте (oauth_states, sessions, users, services, service_samples, events на месте).
  • Проверено после обновления: /api/v1/health ok, флот 19/19 online, агенты инжестят 200 OK, MCP initialize OK (GHard Monitor 1.30.0, 6 тулов + промпт agent_guide), /mcp без auth 406, SPA 200 с i18n-строками, synapse reporter корректно disabled (GHARD_SYNAPSE_API_KEY не задан).
  • Известное ожидаемое поведение: /auth/login → 500 ConfigurationException: Invalid gnexus-auth base URL — GHARD_AUTH_BASE_URL ещё не задан; привязка к gnexus-auth — следующий этап (владелец).

Update 2026-10-04 23:55 (navi rei) — персональные MCP-ключи

  • Обновление b6080d0..40a8810 (4 коммита, 16 файлов +834/−19): 14007e0 feat: персональные MCP-ключи (канон handbook mcp.md); ca26b18 feat: страница «MCP-ключи» — выдача и ревок персональных токенов; 8b91999 docs: README — матрица доступа, API, ревок, блокировка; 40a8810 fix: кнопка «Выдать ключ» выровнена с полем ввода.
  • Миграции идемпотентные при старте: _try_alter добавил users.system_role (снейпшот роли gnexus-auth) и users.blocked (вебхук user.blocked/deleted/archived); CREATE TABLE IF NOT EXISTS mcp_tokens (user_id, name, user_email, system_role, token_hash UNIQUE, token_hint, created_at, last_used_at, revoked_at) — применены, схема проверена PRAGMA.
  • Гард /mcp заменён на require_mcp: персональный Bearer mcp_* (выпуск на /mcp-keys), статический GHARD_ADMIN_TOKEN (супер-токен), браузерная cookie-сессия gnexus-auth.
  • docker-compose.yml апстримом не тронут — stash pop без конфликта, локальные правки сохранены; .env.example без изменений.
  • Бэкап БД до обновления: /data/hard-panel.db.bak-sqlite-20261004-2155-premcp (1.6 GB, sqlite3 backup API, включает WAL).
  • Проверено после обновления: /api/v1/health ok, флот 19/19 online (транзиентный offline после рестарта восстановился за ~90с), агенты инжестят 200 OK, MCP initialize OK, /mcp-keys 200, synapse reporter disabled как раньше.

Агенты (fleet, 2026-10-04)

Агент hard-monitor установлен на все серверы home LAN. Все 19 серверов online (интервал 30 с):

Сервер на панели Хост IP Примечание
hard-panel-176 VM service 192.168.1.176 сама панель
navi VM navi 192.168.1.168 локальная машина Navi
gnbook VM gnbook 192.168.1.170
gnauth VM gnauth 192.168.1.167
gncreds VM gncreds 192.168.1.173
gnsynapse VM gnsynapse 192.168.1.172 добавлен 2026-10-04, панель id 46
gnexus-home VM gnexus-home 192.168.1.151 диск был 100%, почищен apt-кэш/журналы
nextcloud VM nextcloud 192.168.1.152
transmission VM transmission 192.168.1.154
files VM files 192.168.1.157
gitbucket VM gitbucket 192.168.1.156 Ubuntu 18.04, py3.6 — venv на python3.8 + python3.8-dev
ovpn VM ovpn 192.168.1.150
vmk VM vmk (tgbots) 192.168.1.178
jellyfin VM jellyfin 192.168.1.153
mine VM mine 192.168.1.160
fuckjira VM fuckjira 192.168.1.175
mctl VM mctl 192.168.1.169
home VM home 192.168.1.159
internal-proxy VM ovpn_reserv 192.168.1.226

Не охвачены (нет доступа или нецелевые):

  • 192.168.1.129 и 192.168.1.131 — неидентифицированные хосты, SSH с известными паролями отклонён (Permission denied). Добавить агента, когда появятся креды.
  • alex (192.168.105.195) — изолированная сеть 105.x, панель недостижима.
  • pfSense (.1), klipper (.102), gbook (ноут, offline), IoT-сеть 192.168.2.0/24 — не серверы.

Сетевые шары (Storage)

Панель умеет мониторить сетевые диски: пробер на хосте панели делает os.statvfs по зарегистрированным путям и пишет историю (таблица share_samples). Шара считается offline, если нет замера дольше max(share_interval*3, 180) секунд.

Текущие шары (добавлены 2026-09-11, все online):

Имя на панели NFS-экспорт Точка монтирования на .176 Заполнено
secraid5-jellyfin-storage 192.168.1.130:/mnt/secraid5/jellyfin_storage /mnt/nas/secraid5-jf ~89%
secraid5-jellyfin-cache 192.168.1.130:/mnt/secraid5/jellyfin_cache /mnt/nas/secraid5-cache ~0.1%
firstraid5 192.168.1.130:/mnt/firstraid5 /mnt/nas/firstraid5 ~90%
NetTera8 192.168.1.131:/mnt/NetTera8 /mnt/nas/nettera8 ~93%

Монтирование на .176: nfs-common, fstab-записи с _netdev,nofail,vers=3 (бэкап /root/fstab.backup). В контейнер шары проброшены bind-mount с propagation :slave в docker-compose.yml — хостовые NFS-монты автоматически видны внутри контейнера.

Как добавить новую шару (руководство)

  1. Смонтировать на хосте .176 (root):

    apt-get install -y nfs-common
    mkdir -p /mnt/nas/<имя>
    echo "192.168.1.XXX:/экспорт /mnt/nas/<имя> nfs defaults,_netdev,nofail,vers=3 0 0" >> /etc/fstab
    mount -a && df -h /mnt/nas/<имя>   # проверить
  2. Пробросить в контейнер: в /opt/hard-panel/docker-compose.yml в секцию volumes: сервиса panel добавить строку:

        - /mnt/nas/<имя>:/mnt/nas/<имя>:slave

    и пересоздать контейнер (порядок важен — обычный up -d --build падает с KeyError 'ContainerConfig' на старом docker-compose 1.29):

    cd /opt/hard-panel && docker-compose down && docker-compose up -d --build

    Проверка: curl http://localhost:8000/api/v1/health и curl -s http://localhost:8000/api/v1/servers | grep -c online (должно быть 19).

  3. Зарегистрировать шару в панели:

    curl -s -X POST http://192.168.1.176:8000/api/v1/shares \
      -H "Content-Type: application/json" \
      -d '{"name": "<имя>", "path": "/mnt/nas/<имя>"}'

    (если включён GHARD_ADMIN_TOKEN — добавить заголовок Authorization: Bearer <токен>; UI-путь: кнопка Add share в разделе Storage).

  4. Проверить замер: подождать ~1 минуту (интервал пробера), затем:

    curl -s http://192.168.1.176:8000/api/v1/shares | python3 -m json.tool

    Статус должен стать online, появятся total/used. Если offline — проверить, что шара смонтирована на хосте и видна в контейнере: docker exec ghard-panel stat -f /mnt/nas/<имя>.

Массовый деплой (как сделано)

С хоста .176 (root): sshpass + скрипт /root/deploy-hard-monitor.sh (и /root/fix-remaining.sh для отставших). Логика: DELETE старой записи на панели → POST новой (ключ ghm_ показывается один раз) → scp файлов агента из /opt/hard-monitor-src → install.sh PANEL KEY 30 через sudo.

Грабли, проверенные на практике:

  • apt-get install python3-venv без apt-get update падает 404 на старых зеркалах — сначала update.
  • Ubuntu 18.04 (gitbucket): системный python3.6 не подходит (from __future__ import annotations, list[str]). Решение: apt-get install python3.8 python3.8-venv python3.8-dev, venv на python3.8, затем pip install psutil requests.
  • Если /tmp/hm создан root'ом до scp — Permission denied; создавать от пользователя или чистить.
  • Диск 100% (gnexus-home) ломает scp — apt-get clean + journalctl --vacuum-size=50M.
  • Свежие cloud-init VM (Ubuntu 22.04, gnsynapse 2026-10-04): нет python3.10-venv — apt-get update && apt-get install -y python3.10-venv перед install.sh, иначе venv не создаётся.

Обновление агента

Повторный запуск install.sh с теми же PANEL_URL/SERVER_KEY перезаписывает файлы и рестартует юнит (конфиг .env не трогается). Файлы агента: /opt/hard-monitor-src на .176.

История развёртывания

  • 2026-09-10: панель развёрнута (docker-compose build), агент установлен на сам хост, сервер hard-panel-176 online. Root-SSH на VM включён (PermitRootLogin yes, пароль задан).
  • 2026-09-10: UI показывал пустой список — причина: заданный GHARD_ADMIN_TOKEN, который UI не подписывает. Токен отключён, compose-дефолт исправлен на ${GHARD_ADMIN_TOKEN-}. Проверено: GET /api/v1/servers без токена отдаёт hard-panel-176 online.
  • 2026-09-10: массовый деплой агентов — 18/18 серверов online (16 VM DL380 + navi + панель). Скрипты: /root/deploy-hard-monitor.sh, /root/fix-remaining.sh на .176.
  • 2026-09-11: обновление панели до версии с мониторингом шар (git pull, edb6cff). Смонтированы 4 NFS-шары (secraid5-jf, secraid5-cache, firstraid5, nettera8), проброшены в контейнер с :slave, добавлены в мониторинг — все online.
  • 2026-10-04: добавлен сервер gnsynapse (192.168.1.172, панель id 46) — агент установлен через scp из /opt/hard-monitor-src + install.sh (navi rei). Флот 19/19 online.
  • 2026-10-04: крупное обновление панели edb6cff..b6080d0 (19 коммитов, v1.30.0): gnexus-auth (OAuth PKCE), ui-kit 1.0 Verdant, health-чекер сервисов, журнал событий, Synapse-интеграция, i18n, MCP agent_guide (navi rei). Бэкапы БД в volume; конфликт compose разрешён, локальные правки сохранены.
  • 2026-10-04: обновление b6080d0..40a8810 — персональные MCP-ключи: страница /mcp-keys, гард require_mcp, таблица mcp_tokens, миграции users (+system_role, +blocked) (navi rei). Бэкап снят, pull без конфликтов, флот 19/19.