logboard/README.md

LogBoard+

Веб-панель для просмотра логов микросервисов

Автор: Сергей Антропов
Сайт: https://devops.org.ru
Версия: 1.0.0

Описание

LogBoard+ - это современная веб-панель для мониторинга и просмотра логов Docker контейнеров в реальном времени. Приложение идеально подходит для локальной разработки, позволяя разработчикам всегда держать логи микросервисов перед глазами на втором мониторе.

🎯 Идеально для локальной разработки

LogBoard+ особенно полезен для разработчиков, работающих с микросервисной архитектурой:

• Второй монитор - Держите логи всех микросервисов постоянно видимыми
• Быстрая отладка - Мгновенный доступ к логам без переключения между терминалами
• Мониторинг в реальном времени - Видите проблемы сразу, как они возникают
• Централизованный просмотр - Все логи в одном месте, а не в десятках терминалов

🐳 Оптимизирован для Docker и Docker Compose

Если ваша инфраструктура основана на Docker и Docker Compose, LogBoard+ станет незаменимым инструментом:

• Автоматическое обнаружение всех проектов Docker Compose
• Быстрый просмотр логов всех контейнеров в проекте
• Фильтрация по проектам - легко переключаться между разными проектами
• Multi-view режим - одновременный просмотр логов нескольких контейнеров
• Интеграция с Docker API - прямая работа с контейнерами

🚀 Производительность и удобство

Приложение предоставляет удобный веб-интерфейс для работы с логами микросервисов, поддерживает множественные проекты Docker Compose и включает в себя функции безопасности.

Основные возможности

• Просмотр логов в реальном времени - WebSocket соединения для live-логов
• Поддержка множественных проектов - Фильтрация по проектам Docker Compose
• 🌐 Удаленные клиенты - Сбор логов с множества серверов с визуальным разделением
• 🔽 Сворачивание секций - Удобное управление отображением локальных и удаленных контейнеров
• ⚡ Периодическое обновление - Автоматическое обновление списка контейнеров и фильтрация остановленных
• Безопасность - JWT аутентификация и API ключи для клиентов
• Фильтрация контейнеров - Исключение проблемных контейнеров
• Снимки логов - Сохранение логов в файлы для анализа
• Статистика - Анализ уровней логирования
• Адаптивный интерфейс - Поддержка светлой и темной темы
• WebSocket API - Для интеграции с внешними системами

Скриншоты

🔐 Страница входа

Светлая тема	Темная тема

📊 Основной интерфейс

Светлая тема	Темная тема

🖥️ Multi-view режим

📋 Карточки контейнеров

📁 Проекты

⚙️ Настройки

🔧 Сворачиваемая боковая панель

❓ Справка

🚨 Страницы ошибок

Быстрый старт

Предварительные требования

• Docker Engine 20.10+
• Docker Compose 2.0+
• 1 GB RAM
• 1 CPU core

🌐 Удаленные клиенты

LogBoard+ поддерживает работу с удаленными клиентами для централизованного сбора логов с множества серверов. Новый интерфейс визуально разделяет локальные и удаленные контейнеры, группируя их по хостам.

✨ Новые возможности интерфейса

• Визуальное разделение - Локальные и удаленные контейнеры отображаются в отдельных секциях
• Группировка по хостам - Удаленные контейнеры сгруппированы по серверам-источникам
• Цветовая индикация - Оранжевый цвет для удаленных контейнеров
• Иконки и бейджи - 🌐 для удаленных контейнеров, 🖥️ для хостов
• Время обновления - Показывается время последнего обновления логов
• Статистика по хостам - Количество контейнеров на каждом хосте
• 🔽 Сворачивание секций - Можно сворачивать/разворачивать секции "Локальные контейнеры" и "Удаленные контейнеры"
• 🖥️ Сворачивание хостов - Каждый хост в удаленных контейнерах можно сворачивать отдельно
• ⚡ Автоматическое обновление - Список контейнеров обновляется каждые 30 секунд
• 🚫 Фильтрация остановленных - Остановленные контейнеры автоматически скрываются из интерфейса

Архитектура

┌─────────────────┐    HTTP/JSON    ┌─────────────────┐
│   Server A      │ ──────────────► │  LogBoard       │
│  (Client)       │                 │  Server         │
│                 │                 │                 │
│ ┌─────────────┐ │                 │ ┌─────────────┐ │
│ │LogBoard     │ │                 │ │API          │ │
│ │Client       │ │                 │ │Endpoint     │ │
│ │Container    │ │                 │ │/logs/remote │ │
│ └─────────────┘ │                 │ └─────────────┘ │
│         ▲       │                 │         │       │
│         │       │                 │         ▼       │
│ ┌─────────────┐ │                 │ ┌─────────────┐ │
│ │Docker       │ │                 │ │File         │ │
│ │Socket       │ │                 │ │Storage      │ │
│ └─────────────┘ │                 │ └─────────────┘ │
└─────────────────┘                 └─────────────────┘

Установка клиента

# Клонирование репозитория клиента
git clone ssh://git@git.antropoff.ru:222/PetProject/logboard-client.git
cd logboard-client

# Настройка и запуск
cp .env.example .env
# Отредактируйте .env файл
docker-compose up -d

Подробная документация: LogBoard+ Client

Конфигурация

На сервере LogBoard:

# В .env файле
LOGBOARD_API_KEYS=key1,key2,key3

На клиенте:

# В .env файле клиента
LOGBOARD_SERVER_URL=http://logboard.example.com:8000
LOGBOARD_API_KEY=key1
HOSTNAME=production-server-01

Подробная документация: docs/remote-clients.md

Установка и запуск

1. Клонирование репозитория

   git clone <repository-url>
   cd logboard
   

2. Настройка переменных окружения

   cp env.example .env
   # Отредактируйте .env файл при необходимости
   

3. Запуск приложения

   docker compose up --build -d
   

4. Настройка переменных окружения

   make setup
   # Отредактируйте файл .env под свои нужды
   

5. Запуск приложения

   make up
   

6. Доступ к веб-интерфейсу

   http://localhost:9001
   

Учетные данные по умолчанию

• Пользователь: admin
• Пароль: admin

Важно: Обязательно измените пароль в продакшене!

Режим отладки

Для разработки и тестирования доступен режим отладки:

# Включить режим отладки
make debug-on

# Выключить режим отладки
make debug-off

# Проверить статус
make debug-status

В режиме отладки доступно:

• Auto-reload - автоматическая перезагрузка при изменении кода
• Swagger UI - документация API по адресу /docs
• ReDoc - альтернативная документация по адресу /redoc
• Подробное логирование - детальные логи для отладки

В продакшене обязательно отключите режим отладки!

Архитектура

Технологический стек

• Backend: Python 3.11, FastAPI 0.104.1
• Web Server: Uvicorn с uvloop
• Docker Integration: Docker SDK for Python 6.1.3
• Authentication: JWT с PyJWT
• Frontend: HTML5, CSS3, JavaScript (Vanilla)
• Templates: Jinja2
• Containerization: Docker, Docker Compose

Структура проекта

logboard/
├── app/                    # Основная папка приложения
│   ├── __init__.py        # Инициализация пакета
│   ├── app.py             # Основное приложение FastAPI
│   ├── excluded_containers.json  # Исключенные контейнеры
│   ├── api/               # API модули
│   │   ├── __init__.py
│   │   └── v1/
│   │       ├── __init__.py
│   │       ├── router.py  # Основной роутер API
│   │       └── endpoints/ # API endpoints
│   │           ├── __init__.py
│   │           ├── auth.py        # Аутентификация
│   │           ├── containers.py  # Управление контейнерами
│   │           ├── logs.py        # Логи
│   │           ├── pages.py       # HTML страницы
│   │           ├── settings.py    # Настройки
│   │           └── websocket.py   # WebSocket API
│   ├── core/              # Основные модули
│   │   ├── __init__.py
│   │   ├── auth.py        # Аутентификация и авторизация
│   │   ├── config.py      # Конфигурация приложения
│   │   ├── docker.py      # Работа с Docker API
│   │   └── logger.py      # Система логирования
│   ├── models/            # Модели данных
│   │   ├── __init__.py
│   │   └── auth.py        # Модели аутентификации
│   ├── static/            # Статические файлы
│   │   ├── css/           # CSS стили
│   │   ├── js/            # JavaScript файлы
│   │   ├── images/        # Изображения
│   │   └── fonts/         # Шрифты
│   └── templates/         # HTML шаблоны
│       ├── index.html     # Главная страница
│       ├── login.html     # Страница входа
│       └── error.html     # Страницы ошибок
├── docs/                  # Документация
├── snapshots/             # Снимки логов
├── screenshots/           # Скриншоты интерфейса
├── .env                   # Переменные окружения (создается из env.example)
├── env.example            # Пример переменных окружения
├── docker-compose.yml     # Конфигурация Docker Compose
├── Dockerfile            # Образ Docker
├── requirements.txt      # Зависимости Python
├── start.sh              # Скрипт запуска
└── README.md             # Документация проекта

API Документация

REST API

Аутентификация

• POST /api/auth/login - Вход в систему
• POST /api/auth/logout - Выход из системы
• GET /api/auth/me - Информация о текущем пользователе

Контейнеры и сервисы

• GET /api/services - Список контейнеров
• GET /api/projects - Список проектов Docker Compose
• GET /api/logs/{container_id} - Логи контейнера
• GET /api/logs/stats/{container_id} - Статистика логов

Управление

• GET /api/settings - Настройки приложения
• GET /api/excluded-containers - Список исключенных контейнеров
• POST /api/excluded-containers - Обновление исключенных контейнеров
• POST /api/snapshot - Создание снимка логов

WebSocket API

• ws://host:port/ws/logs/{container_id} - Логи отдельного контейнера
• ws://host:port/ws/fan/{service_name} - Логи сервиса (все реплики)
• ws://host:port/ws/fan_group - Логи группы сервисов

Конфигурация

Переменные окружения

Приложение использует файл .env для конфигурации. Создайте его из env.example:

cp env.example .env

Основные настройки приложения:

Переменная	Описание	По умолчанию
LOGBOARD_PORT	Порт веб-интерфейса	9001
LOGBOARD_USER	Имя пользователя	admin
LOGBOARD_PASS	Пароль пользователя	admin
LOGBOARD_TAIL	Количество строк логов	500
SECRET_KEY	Секретный ключ JWT	your-secret-key-here
ENCRYPTION_KEY	Ключ шифрования	your-encryption-key-here
AUTH_ENABLED	Включить аутентификацию	true
LOG_LEVEL	Уровень логирования	INFO

Настройка проектов

Для фильтрации контейнеров по проектам Docker Compose:

# Один проект
COMPOSE_PROJECT_NAME=myproject

# Несколько проектов
LOGBOARD_PROJECTS=project1,project2,project3

Исключение контейнеров

Файл app/excluded_containers.json содержит список контейнеров, которые не будут отображаться в интерфейсе:

{
  "excluded_containers": [
    "noisy-container-1",
    "noisy-container-2"
  ],
  "description": "Контейнеры с избыточным логированием"
}

Управление

Команды Makefile

make help          # Справка по командам
make setup         # Настройка переменных окружения
make build         # Сборка Docker образа
make up            # Запуск сервисов
make down          # Остановка сервисов
make restart       # Перезапуск сервисов
make logs          # Просмотр логов
make clean         # Очистка проекта
make status        # Статус сервисов
make shell         # Подключение к контейнеру

Docker Compose команды

# Запуск
docker compose up -d

# Остановка
docker compose down

# Просмотр логов
docker compose logs -f

# Пересборка
docker compose build --no-cache

Безопасность

Рекомендации для продакшена

1. Измените пароли по умолчанию

   LOGBOARD_PASS=your-secure-password
   

2. Настройте секретные ключи

   SECRET_KEY=your-very-secure-secret-key
   ENCRYPTION_KEY=your-encryption-key
   

3. Используйте HTTPS

   • Настройте reverse proxy (nginx, traefik)
   • Включите SSL/TLS сертификаты

4. Ограничьте доступ к Docker socket

   # Создайте группу docker и добавьте пользователя
   sudo usermod -aG docker $USER
   

5. Настройте файрвол

   # Ограничьте доступ к порту 9001
   sudo ufw allow from 192.168.1.0/24 to any port 9001
   

Аутентификация

Приложение использует JWT токены для аутентификации:

• Токены хранятся в HTTP-only cookies
• Время жизни токена настраивается через SESSION_TIMEOUT
• Поддерживается автоматическое обновление токенов

Мониторинг и логирование

Health Check

curl http://localhost:9001/healthz
# Ответ: ok

Логирование

Приложение логирует:

• Ошибки подключения к Docker
• Проблемы с контейнерами
• Ошибки аутентификации
• WebSocket соединения

Метрики

Доступные метрики:

• Количество активных WebSocket соединений
• Статистика по уровням логирования
• Количество исключенных контейнеров
• Время ответа API

Разработка

Локальная разработка

1. Клонирование и настройка

   git clone <repository-url>
   cd logboard
   make setup
   

2. Запуск в режиме разработки

   make up
   

3. Просмотр логов

   make logs
   

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

# Проверка конфигурации
make validate

# Проверка переменных окружения
make env-check

# Тестирование API
curl -X GET "http://localhost:9001/api/services" \
  -H "Authorization: Bearer YOUR_TOKEN"

Устранение неполадок

Частые проблемы

1. Ошибка подключения к Docker

   # Проверьте права доступа к Docker socket
   ls -la /var/run/docker.sock
   sudo usermod -aG docker $USER
   

2. Контейнеры не отображаются

   # Проверьте фильтры проектов
   docker ps --format "table {{.Names}}\t{{.Labels}}"
   

3. Ошибки аутентификации

   # Проверьте переменные окружения
   make env-check
   

4. WebSocket соединения не работают

   # Проверьте настройки прокси
   # Убедитесь, что WebSocket поддерживается
   

Логи и отладка

# Просмотр логов приложения
make logs

# Подключение к контейнеру
make shell

# Проверка статуса
make status

Лицензия

MIT License - см. файл LICENSE для подробностей.

Поддержка

• Автор: Сергей Антропов
• Сайт: https://devops.org.ru
• Issues: Создавайте issues в репозитории проекта
• Документация: ./docs/

Вклад в проект

1. Fork репозитория
2. Создайте feature branch (git checkout -b feature/amazing-feature)
3. Commit изменения (git commit -m 'Add amazing feature')
4. Push в branch (git push origin feature/amazing-feature)
5. Откройте Pull Request

Changelog

v1.0.0 (2024-01-XX)

• Первый релиз LogBoard+
• Поддержка множественных проектов Docker Compose
• JWT аутентификация
• WebSocket API для live-логов
• Адаптивный веб-интерфейс
• Система исключения контейнеров
• Снимки логов
• Статистика логирования

---

LogBoard+ - Удобный просмотр логов микросервисов в реальном времени.