Skip to content

Latest commit

 

History

History
434 lines (322 loc) · 17.9 KB

implementation_plan.md

File metadata and controls

434 lines (322 loc) · 17.9 KB

План разработки Local Ops Board

Цель

Добавить в локальное Go-приложение панель контроля важных сервисов, endpoints и почтовой инфраструктуры домена. Приложение хранит сервисы локально в SQLite, позволяет запускать проверки доступности и показывает краткое состояние системы через веб-интерфейс.

Основной URL интерфейса:

http://localhost:8080/uptime

Технологии

  • Go 1.27;
  • Gin;
  • SQLite через modernc.org/sqlite;
  • vanilla JavaScript;
  • HTML/CSS без frontend bundler;
  • локальный запуск без облачной синхронизации.
  • production-доступ через Cloudflare Access;
  • deployment через systemd, Nginx и GitHub Actions.

Реализованный MVP

Модель сервиса

Сервис содержит:

  • название;
  • URL;
  • тип проверки: http, smtp, imap, pop3, mysql, redis, rabbitmq или postgres;
  • окружение: production, staging или development;
  • описание;
  • теги;
  • признак включённой проверки;
  • даты создания и изменения;
  • последнюю проверку.

Dashboard

Dashboard показывает:

  • общее количество сервисов;
  • количество работающих сервисов;
  • количество сервисов с проблемами;
  • количество недоступных сервисов.

Проверка доступности

Ручная проверка endpoint:

  • используется GET;
  • timeout — 10 секунд;
  • учитываются HTTP status и response time;
  • коды 2xx и 3xx считаются успешными;
  • 4xx, 5xx, timeout и сетевые ошибки считаются проблемой или недоступностью;
  • результат сохраняется в историю.

Для защищённых вариантов TLS определяется схемой URL: https, smtps, imaps, pop3s, rediss или amqps. Для MySQL используется параметр tls=true, для PostgreSQL — sslmode=require.

CRUD API

GET    /api/v1/dashboard
GET    /api/v1/services
POST   /api/v1/services
PUT    /api/v1/services/:id
DELETE /api/v1/services/:id
POST   /api/v1/services/:id/check
GET    /api/v1/services/:id/checks

Веб-интерфейс

Реализованы:

  • список сервисов;
  • добавление;
  • редактирование;
  • удаление;
  • проверка одного сервиса;
  • проверка всех включённых сервисов;
  • статусные badges;
  • response time;
  • теги;
  • ссылка на существующий SnippetBook из Ops Board.

SQLite

Автоматически создаются таблицы:

  • services;
  • service_checks.

Существующие таблицы SnippetBook сохраняются и не удаляются.

Следующий этап: автоматический мониторинг

Статус: реализовано.

Добавлено:

  • background worker с context.Context;
  • graceful shutdown по SIGINT/SIGTERM;
  • автоматическая проверка только включённых сервисов;
  • единый checker для ручных и автоматических проверок;
  • индивидуальный интервал проверки для каждого сервиса;
  • немедленная первая проверка после создания сервиса;
  • ограничение истории проверок;
  • настройки через админку;
  • хранение настроек в SQLite;
  • автоматическое заполнение отсутствующих настроек defaults при старте;
  • динамическое применение новых настроек worker-ом без ENV и пересборки.

Дефолтные значения:

services.check_interval=30s
check_timeout=10s
check_history_limit=500

Timeout и размер истории изменяются через страницу Настройки мониторинга в /uptime/settings, а интервал изменяется в форме каждого сервиса. Worker динамически применяет значения. Некорректные значения отклоняются API.

Этап: SSL-сертификаты

Статус: реализовано.

Для TLS-сервисов реализовать:

  • проверку TLS handshake;
  • дату окончания сертификата;
  • количество дней до окончания;
  • предупреждение о скором истечении;
  • отображение certificate issuer и hostname;
  • отдельный статус TLS error.

Реализация хранит TLS-метаданные в service_checks, выполняет отдельный TLS handshake для всех защищённых URL (https, smtps, imaps, pop3s, rediss, amqps) и показывает предупреждение при сроке действия 21 день или меньше.

Проверки протоколов подключаются через единый checker registry: SMTP/IMAP/POP3 проверяют greeting, Redis выполняет PING, MySQL/PostgreSQL — Ping и SELECT 1, RabbitMQ — AMQP handshake.

Проверку сертификата выполнять отдельно от HTTP GET, чтобы различать:

  • недоступный endpoint;
  • ошибку TLS;
  • истекающий сертификат;
  • рабочий endpoint.

Этап: Runbooks

Статус: реализовано.

Добавить Markdown-инструкции для каждого сервиса:

  • создание;
  • редактирование;
  • preview;
  • безопасный рендеринг;
  • хранение Markdown source;
  • отображение статьи на странице сервиса.

API:

GET    /api/v1/services/:id/runbooks
POST   /api/v1/services/:id/runbooks
PUT    /api/v1/runbooks/:id
DELETE /api/v1/runbooks/:id
POST   /api/v1/runbooks/preview

Markdown должен:

  • экранировать raw HTML;
  • разрешать только безопасные http/https ссылки;
  • не исполнять пользовательский JavaScript;
  • иметь ограничение размера тела.

Preview возвращает HTML только после экранирования исходного Markdown; raw HTML и JavaScript не исполняются.

Этап: Напоминания

Статус: реализовано.

Добавить локальные reminders:

  • название;
  • сервис;
  • срок;
  • описание;
  • completed;
  • просроченные записи.

Примеры напоминаний:

  • обновить SSL-сертификат;
  • проверить backup;
  • заменить API token;
  • проверить DNS;
  • обновить документацию.

Напоминания хранятся локально в SQLite и доступны через API и интерфейс Ops Board.

Этап: Улучшение dashboard

Статус: реализовано.

Добавить:

  • список последних ошибок;
  • фильтрацию по окружению;
  • фильтрацию по тегам;
  • сортировку по статусу и времени ответа;
  • график response time;
  • историю инцидентов;
  • страницу деталей сервиса;
  • ручную кнопку очистки старой истории.

Добавлены последние ошибки, фильтры по окружению и тегам, сортировка по статусу и response time, график response time, страница деталей сервиса и ручная очистка старой истории.

Этап: Уведомления

Статус: реализовано.

Добавлять только после стабильного локального мониторинга.

Возможные варианты:

  • desktop notification;
  • email;
  • Telegram;
  • webhook;

Добавлены локальные уведомления о смене статуса в SQLite и browser Notification API через кнопку Уведомления. Также добавлены глобальные каналы Telegram Bot API, Slack Incoming Webhook и SMTP email. Один статусный event всех сервисов отправляется во все включённые каналы. Настройка выполняется через /uptime и /api/v1/notification-settings. Для каждого канала доступна тестовая отправка через POST /api/v1/notification-settings/test.

Для каждого сервиса добавлены повторные уведомления активной проблемы с индивидуальным интервалом. Они выключены по умолчанию; уведомления о начале и решении инцидента отправляются всегда.

Все каналы подключены через единый dispatch-слой notifier. Новые каналы добавляются отдельно и не должны изменять логику мониторинга.

Этап: Domains

Статус: реализовано для MVP.

Отдельный пункт меню Domains и страница /uptime/domain принимают домен и необязательный DKIM selector, после чего запускает независимую DNS-диагностику. Домен можно добавить в постоянный мониторинг с индивидуальным интервалом.

MX

  • найти MX-записи домена;
  • показать priority и hostname каждого сервера;
  • разрешить MX hostname в A и AAAA;
  • сообщить об отсутствии MX, null MX и неразрешимых hostname;
  • показать понятный статус ok, warning, error или not_found.

SPF

  • найти TXT-запись, начинающуюся с v=spf1;
  • проверить наличие нескольких SPF-записей;
  • разобрать include, a, mx, ip4, ip6 и all;
  • считать вложенные DNS lookup;
  • предупредить о приближении к лимиту 10 lookup;
  • предупредить о permissive policy +all и отсутствии строгой политики.

DKIM

  • принимать selector от пользователя или выполнять поиск по common selectors;
  • искать <selector>._domainkey.<domain>;
  • проверить наличие v=DKIM1 и публичного ключа p=;
  • корректно объединять разделённые TXT-фрагменты;
  • возвращать not_found, если указанный selector и common selectors не дали запись.

DMARC

  • искать _dmarc.<domain>;
  • проверить v=DMARC1 и параметр p;
  • разобрать rua, ruf, pct, adkim и aspf;
  • предупредить о p=none и некорректных адресах отчётов;
  • отдельно показывать policy и alignment.

Blacklists

  • получить IP-адреса MX-серверов;
  • проверить IPv4 и, если включено решением из отложенных вопросов, IPv6 по DNSBL/RBL;
  • использовать конфигурационный список DNSBL;
  • показать конкретный список, IP и ссылку на процедуру delist;
  • не считать одну запись в blacklist безусловным доказательством проблемы;
  • ограничить частоту внешних DNSBL-запросов.

Domains API

POST  /api/v1/domain/check
GET   /api/v1/domain/checks
GET   /api/v1/domain/checks/:id
DELETE /api/v1/domain/checks/:id
GET   /api/v1/domain/monitors
POST  /api/v1/domain/monitors
PUT   /api/v1/domain/monitors/:id
DELETE /api/v1/domain/monitors/:id

Запрос:

{
  "domain": "example.com",
  "dkim_selector": "default"
}

Все DNS-запросы выполняются с timeout, context.Context и ограничением глубины SPF-рекурсии. Результаты проверок сохраняются в SQLite с лимитом 500 проверок на домен. Для MVP используются системный resolver и базовый список DNSBL: Spamhaus ZEN, SpamCop, Barracuda и SORBS. Проверяются IPv4 и IPv6 адреса. Фоновый worker выполняет включённые mail monitors сразу после добавления и затем по их индивидуальным интервалам; изменение общего статуса добавляет уведомление и запускает настроенные каналы доставки.

Этап: Production hardening и deployment

Статус: реализовано частично.

Уже подготовлено:

  • Cloudflare Access JWT validation;
  • защита /, /uptime, статических файлов и API;
  • systemd unit для /opt/snippetbook;
  • Nginx reverse proxy;
  • Cloudflare Origin CA и self-signed certificate scripts;
  • Makefile для кросс-компиляции;
  • GitHub Actions workflow для linux-amd64.

Остаётся проверить на реальном сервере:

  • валидный, просроченный и неподписанный Cloudflare Access JWT;
  • неверный issuer и audience;
  • отсутствие JWT;
  • корректность Nginx 443 и Full (strict);
  • rollback предыдущего релиза;
  • права sudo для пользователя GitHub Actions deployment;
  • сохранность .env, app.db и vault после деплоя.

Тесты middleware Cloudflare Access, graceful shutdown worker и syntax validation deployment scripts реализованы. Production smoke test требует реальные GitHub Secrets, Nginx, Cloudflare Access и доступный сервер, поэтому выполняется отдельно после настройки окружения.

Тестирование

Уже проверено

go test ./...
go vet ./...
go build ./...
node --check web/ops.js

Также проверены через временную SQLite-базу:

  • dashboard endpoint;
  • создание сервиса;
  • получение списка сервисов;
  • загрузка /uptime.

Необходимые тесты

Статус: основные сценарии реализованы; расширяются по мере добавления функций.

Добавить тесты рядом с кодом:

  • создание сервиса;
  • обновление сервиса;
  • удаление сервиса;
  • валидация URL;
  • нормализация тегов;
  • проверка успешного httptest.Server;
  • проверка HTTP error status;
  • timeout;
  • сохранение истории;
  • расчёт dashboard counters;
  • корректное закрытие background worker.

Добавлены тесты настроек, CRUD API, URL validation, тегов, HTTP-проверок, TLS error, истории, ограничения истории, автоматического RunOnce и protocol greeting checks. Отдельный тест graceful shutdown worker остаётся.

Для Domains добавить тесты с mock DNS resolver:

  • MX: отсутствующая, обычная и null MX запись;
  • SPF: одна запись, несколько записей, include и превышение lookup limit;
  • DKIM: валидный ключ, разделённые TXT-фрагменты и отсутствующий selector;
  • DMARC: разные p policy и некорректные параметры;
  • DNSBL: clean, listed и timeout;
  • отмена DNS-проверки через context.Context.

Что не добавлять в ближайший MVP

  • выполнение shell-команд;
  • автоматический restart сервисов;
  • Kubernetes API;
  • облачную синхронизацию;
  • multi-user режим;
  • сложную ролевую модель;
  • публикацию приложения наружу без Cloudflare Access и TLS.

Критерии готовности следующей версии

  • сервисы проверяются автоматически;
  • worker останавливается без зависших goroutine;
  • история не растёт бесконечно;
  • SSL expiration отображается на dashboard;
  • ошибки проверки не ломают проверку остальных сервисов;
  • все новые API имеют тесты;
  • ручная проверка и автоматический worker используют одну функцию проверки;
  • существующий SnippetBook продолжает работать без изменений.