logboard/docs/index.md

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

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

Обзор

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

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

Установка

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

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

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

Доступ

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

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

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

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

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

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

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

3. WebSocket API

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

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

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

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

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

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

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

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

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

Архитектура

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

• 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/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 - Логи группы сервисов

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

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

Переменная	Описание	По умолчанию
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+ - Удобный просмотр логов микросервисов в реальном времени.