logboard/docs/index.md

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

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

## Обзор

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

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

### Установка

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

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

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

### Доступ

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

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

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

1. **[Установка и настройка](./installation.md)**
   - Предварительные требования
   - Пошаговая установка
   - Настройка для продакшена
   - Устранение проблем установки

2. **[API Документация](./api.md)**
   - REST API endpoints
   - WebSocket API
   - Примеры использования
   - Коды ошибок

3. **[WebSocket API](./websocket.md)**
   - Подключение к WebSocket
   - Real-time логи
   - Обработка ошибок
   - Лучшие практики

4. **[Конфигурация](./configuration.md)**
   - Переменные окружения
   - Настройка Docker
   - Настройка безопасности
   - Примеры конфигураций

5. **[Безопасность](./security.md)**
   - Генерация ключей
   - Аутентификация
   - Настройка HTTPS
   - Мониторинг безопасности

6. **[Устранение неполадок](./troubleshooting.md)**
   - Общие проблемы
   - Проблемы с Docker
   - Проблемы с аутентификацией
   - Диагностика и логи

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

- **[README.md](../README.md)** - Основная документация проекта
- **[env.example](../env.example)** - Пример конфигурации
- **[Makefile](../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` |

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

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

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

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

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

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

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

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

### Health Check

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

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

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

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

### Python

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

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

```bash
# Получение токена
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**
   ```bash
   sudo usermod -aG docker $USER
   newgrp docker
   ```

2. **Контейнеры не отображаются**
   ```bash
   docker ps --format "table {{.Names}}\t{{.Labels}}"
   ```

3. **Ошибки аутентификации**
   ```bash
   make env-check
   ```

### Диагностика

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

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

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

## Поддержка

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

## Лицензия

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

---

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