Sergey Antropoff 7ccdf75bab docs: update README and docs with strict Quick Start (docker-compose-prod), fix WebSocket paths, enforce strict tone

2025-09-04 13:43:10 +03:00

21 KiB

Raw Blame History

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 аутентификация и авторизация
Фильтрация контейнеров - Исключение проблемных контейнеров
Снимки логов - Сохранение логов в файлы для анализа
Статистика - Анализ уровней логирования
Адаптивный интерфейс - Поддержка светлой и темной темы
WebSocket API - Для интеграции с внешними системами

Скриншоты

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

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

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

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

Multi-view режим

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

Проекты

Настройки

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

Справка

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

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

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

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

Вариант A: Локальный запуск (разработка)

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

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

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

Запуск приложения
```
make up
```
Доступ к веб-интерфейсу
```
http://localhost:9001
```

Вариант B: Продакшен через docker-compose-prod.yaml

Ниже приведен пример конфигурации из 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
      DOCKER_HOST: "unix:///var/run/docker.sock"
      DOCKER_TLS_VERIFY: ""
      DOCKER_CERT_PATH: ""
      DOCKER_NETWORKS: "iaas,infrastructure_iaas"

      # БЕЗОПАСНОСТЬ
      SECRET_KEY: "your-secret-key-here"
      ENCRYPTION_KEY: "your-encryption-key-here"

      # ЛОГИРОВАНИЕ
      LOG_LEVEL: "INFO"
      LOG_FORMAT: "json"

      # ВЕБ-ИНТЕРФЕЙС
      WEB_TITLE: "LogBoard+"
      WEB_DESCRIPTION: "Веб-панель для просмотра логов микросервисов"
      WEB_VERSION: "1.0.0"

      # РЕЖИМ РАЗРАБОТКИ
      DEBUG_MODE: "false"

      # ПРОИЗВОДИТЕЛЬНОСТЬ
      MAX_CONNECTIONS: "100"
      CONNECTION_TIMEOUT: "30"
      READ_TIMEOUT: "60"

      # ФИЛЬТРАЦИЯ КОНТЕЙНЕРОВ
      LOGBOARD_SKIP_UNHEALTHY: "true"
      LOGBOARD_CONTAINER_LIST_TIMEOUT: "10"
      LOGBOARD_CONTAINER_INFO_TIMEOUT: "3"
      LOGBOARD_HEALTH_CHECK_TIMEOUT: "2"

      # АУТЕНТИФИКАЦИЯ
      AUTH_ENABLED: "true"
      AUTH_METHOD: "jwt"
      SESSION_TIMEOUT: "3600"

      # УВЕДОМЛЕНИЯ
      NOTIFICATIONS_ENABLED: "false"
      SMTP_HOST: ""
      SMTP_PORT: "587"
      SMTP_USER: ""
      SMTP_PASS: ""
      SMTP_FROM: ""

      # AJAX ОБНОВЛЕНИЕ
      LOGBOARD_AJAX_UPDATE_INTERVAL: "2000"

    ports:
      - "9001:9001"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./snapshots:/app/snapshots
    restart: unless-stopped
    user: 0:0

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

Используйте файл .env для значений чувствительных переменных (SECRET_KEY, ENCRYPTION_KEY, LOGBOARD_PASS) и не храните их в открытом виде в compose-файле.
Настройте reverse proxy (Nginx/Traefik) и включите HTTPS.

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

Пользователь: 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/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 - Логи группы сервисов

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

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

Приложение использует файл .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

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

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

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

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

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

Health Check

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

Логирование

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

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

Метрики

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

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

Разработка

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

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

git clone <repository-url>
cd logboard
make setup

Запуск в режиме разработки
```
make up
```
Просмотр логов
```
make logs
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Лицензия

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

Поддержка

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

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

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

Changelog

v1.0.0 (2024-01-XX)

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

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

21 KiB Raw Blame History Unescape Escape

LogBoard+

Описание

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

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

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

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

Скриншоты

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

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

Multi-view режим

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

Проекты

Настройки

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

Справка

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

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

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

Вариант A: Локальный запуск (разработка)

Вариант B: Продакшен через docker-compose-prod.yaml

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

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

Архитектура

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

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

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

REST API

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

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

Управление

WebSocket API

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

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

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

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

Управление

Команды Makefile

Docker Compose команды

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

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

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

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

Health Check

Логирование

Метрики

Разработка

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

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

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

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

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

Лицензия

Поддержка

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

Changelog

v1.0.0 (2024-01-XX)

21 KiB

Raw Blame History