logboard/README.md

# LogBoard+

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

[![Python](https://img.shields.io/badge/Python-3.11-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.104.1-green.svg)](https://fastapi.tiangolo.com/)
[![Docker](https://img.shields.io/badge/Docker-6.1.3-blue.svg)](https://www.docker.com/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Автор:** Сергей Антропов  
**Сайт:** 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** - Для интеграции с внешними системами

## Скриншоты

### 🔐 Страница входа
| Светлая тема | Темная тема |
|--------------|-------------|
| ![Вход - светлая тема](screenshots/login-white.png) | ![Вход - темная тема](screenshots/login-dark.png) |

### 📊 Основной интерфейс
| Светлая тема | Темная тема |
|--------------|-------------|
| ![Single View - светлая тема](screenshots/single-view-white.png) | ![Single View - темная тема](screenshots/single-view-dark.png) |

### 🖥️ Multi-view режим
![Multi-view режим](screenshots/multi-view.png)

### 📋 Карточки контейнеров
![Карточки контейнеров](screenshots/container-cards.png)

### 📁 Проекты
![Список проектов](screenshots/projects.png)

### ⚙️ Настройки
![Панель настроек](screenshots/options.png)

### 🔧 Сворачиваемая боковая панель
![Сворачиваемая боковая панель](screenshots/collapse-sidebar.png)

### ❓ Справка
![Окно справки](screenshots/help.png)

### 🚨 Страницы ошибок
![Страницы ошибок](screenshots/error%20pages.png)

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

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

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

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

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

2. **Настройка переменных окружения**
   ```bash
   cp env.example .env
   # Отредактируйте .env файл при необходимости
   ```

3. **Запуск приложения**
   ```bash
   docker compose up --build -d
   ```

2. **Настройка переменных окружения**
   ```bash
   make setup
   # Отредактируйте файл .env под свои нужды
   ```

3. **Запуск приложения**
   ```bash
   make up
   ```

4. **Доступ к веб-интерфейсу**
   ```
   http://localhost:9001
   ```

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

- **Пользователь:** `admin`
- **Пароль:** `admin`

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

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

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

```bash
# Включить режим отладки
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`:

```bash
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:

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

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

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

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

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

## Управление

### Команды Makefile

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

### Docker Compose команды

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

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

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

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

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

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

1. **Измените пароли по умолчанию**
   ```bash
   LOGBOARD_PASS=your-secure-password
   ```

2. **Настройте секретные ключи**
   ```bash
   SECRET_KEY=your-very-secure-secret-key
   ENCRYPTION_KEY=your-encryption-key
   ```

3. **Используйте HTTPS**
   - Настройте reverse proxy (nginx, traefik)
   - Включите SSL/TLS сертификаты

4. **Ограничьте доступ к Docker socket**
   ```bash
   # Создайте группу docker и добавьте пользователя
   sudo usermod -aG docker $USER
   ```

5. **Настройте файрвол**
   ```bash
   # Ограничьте доступ к порту 9001
   sudo ufw allow from 192.168.1.0/24 to any port 9001
   ```

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

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

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

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

### Health Check

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

### Логирование

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

### Метрики

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

## Разработка

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

1. **Клонирование и настройка**
   ```bash
   git clone <repository-url>
   cd logboard
   make setup
   ```

2. **Запуск в режиме разработки**
   ```bash
   make up
   ```

3. **Просмотр логов**
   ```bash
   make logs
   ```

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

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

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

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

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

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

1. **Ошибка подключения к Docker**
   ```bash
   # Проверьте права доступа к Docker socket
   ls -la /var/run/docker.sock
   sudo usermod -aG docker $USER
   ```

2. **Контейнеры не отображаются**
   ```bash
   # Проверьте фильтры проектов
   docker ps --format "table {{.Names}}\t{{.Labels}}"
   ```

3. **Ошибки аутентификации**
   ```bash
   # Проверьте переменные окружения
   make env-check
   ```

4. **WebSocket соединения не работают**
   ```bash
   # Проверьте настройки прокси
   # Убедитесь, что WebSocket поддерживается
   ```

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

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

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

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

## Лицензия

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

## Поддержка

- **Автор:** Сергей Антропов
- **Сайт:** https://devops.org.ru
- **Issues:** Создавайте issues в репозитории проекта
- **Документация:** [./docs/](./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+** - Удобный просмотр логов микросервисов в реальном времени.