logboard/docs/index.md

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

Автор: Сергей Антропов
Сайт: https://devops.org.ru

Обзор

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

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

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

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

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

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

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

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

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

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

Вариант A: Разработка

# Клонирование репозитория
git clone <repository-url>
cd logboard

# Настройка переменных окружения
make setup

# Запуск приложения
make up

Вариант B: Продакшен (пример docker-compose-prod.yaml)

services:
  logboard:
    image: docker.io/inecs/logboard:v1
    container_name: logboard
    environment:
      LOGBOARD_PORT: "9001"
      LOGBOARD_TAIL: "500"
      LOGBOARD_USER: "admin"
      LOGBOARD_PASS: "admin"
      LOGBOARD_SNAPSHOT_DIR: "/app/snapshots"
      LOGBOARD_STATIC_DIR: "/app/static"
      LOGBOARD_INDEX_HTML: "./app/templates/index.html"
      TZ_TS: "Europe/Moscow"
      DOCKER_HOST: "unix:///var/run/docker.sock"
      SECRET_KEY: "your-secret-key-here"
      ENCRYPTION_KEY: "your-encryption-key-here"
      LOG_LEVEL: "INFO"
      LOG_FORMAT: "json"
      DEBUG_MODE: "false"
      AUTH_ENABLED: "true"
      SESSION_TIMEOUT: "3600"
    ports:
      - "9001:9001"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./snapshots:/app/snapshots
    restart: unless-stopped
    user: 0:0

После запуска интерфейс доступен по адресу: http://localhost:9001

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

• Пользователь: admin
• Пароль: admin (обязательно измените в продакшене)

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

Основные разделы

1. Установка и настройка

   • Предварительные требования
   • Пошаговая установка
   • Настройка для продакшена
   • Устранение проблем установки

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

   • Архитектура приложения
   • Описание модулей
   • Принципы организации
   • Добавление новых модулей

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

   • REST API endpoints
   • WebSocket API
   • Примеры использования
   • Коды ошибок

4. WebSocket API

   • Подключение к WebSocket
   • Real-time логи
   • Обработка ошибок
   • Лучшие практики

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

   • Переменные окружения
   • Настройка Docker
   • Настройка безопасности
   • Примеры конфигураций

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

   • Генерация ключей
   • Аутентификация
   • Настройка HTTPS
   • Мониторинг безопасности

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

   • Общие проблемы
   • Проблемы с Docker
   • Проблемы с аутентификацией
   • Диагностика и логи

Дополнительные ресурсы

• README.md - Основная документация проекта
• env.example - Пример конфигурации
• Makefile - Команды управления

Скриншоты

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

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

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

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

Multi-view режим

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

Проекты

Настройки

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

Справка

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

Архитектура

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

• 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

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

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

API Endpoints

REST API

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

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

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

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

Управление

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

WebSocket API

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

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

Основные переменные окружения

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

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

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

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

Управление

Команды 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. Измените пароли по умолчанию
2. Настройте секретные ключи
3. Используйте HTTPS
4. Ограничьте доступ к Docker socket
5. Настройте файрвол

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

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

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

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

Health Check

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

Логирование

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

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

Примеры использования

Python

import requests

# Аутентификация
response = requests.post('http://localhost:9001/api/auth/login', json={
    'username': 'admin',
    'password': 'your-password'
})
token = response.json()['access_token']

# Получение списка контейнеров
headers = {'Authorization': f'Bearer {token}'}
containers = requests.get('http://localhost:9001/api/services', headers=headers).json()

JavaScript

// Получение токена
const response = await fetch('http://localhost:9001/api/auth/login', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
        username: 'admin',
        password: 'your-password'
    })
});
const {access_token} = await response.json();

// WebSocket подключение
const ws = new WebSocket(`ws://localhost:9001/ws/logs/container-id?token=${access_token}`);

cURL

# Получение токена
TOKEN=$(curl -s -X POST "http://localhost:9001/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}' \
  | jq -r '.access_token')

# Получение списка контейнеров
curl -X GET "http://localhost:9001/api/services" \
  -H "Authorization: Bearer $TOKEN"

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

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

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

   sudo usermod -aG docker $USER
   newgrp docker
   

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

   docker ps --format "table {{.Names}}\t{{.Labels}}"
   

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

   make env-check
   

Диагностика

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

# Просмотр логов
make logs

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

Поддержка

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

Лицензия

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

---

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