logboard/docs/project-structure.md

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

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

Обзор структуры

LogBoard+ имеет модульную архитектуру с четким разделением ответственности. Проект организован в соответствии с лучшими практиками Python и FastAPI.

Дерево файлов

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 стили
│   │   │   ├── index.css  # Основные стили
│   │   │   ├── login.css  # Стили страницы входа
│   │   │   └── error.css  # Стили страниц ошибок
│   │   ├── js/            # JavaScript файлы
│   │   │   ├── index.js   # Основная логика
│   │   │   ├── login.js   # Логика входа
│   │   │   └── error.js   # Логика ошибок
│   │   ├── images/        # Изображения
│   │   │   └── favicon.ico # Иконка сайта
│   │   └── fonts/         # Шрифты
│   └── templates/         # HTML шаблоны
│       ├── index.html     # Главная страница
│       ├── login.html     # Страница входа
│       └── error.html     # Страницы ошибок
├── docs/                  # Документация
│   ├── index.md          # Главная страница документации
│   ├── installation.md   # Установка и настройка
│   ├── configuration.md  # Конфигурация
│   ├── api.md            # API документация
│   ├── websocket.md      # WebSocket API
│   ├── security.md       # Безопасность
│   ├── troubleshooting.md # Устранение неполадок
│   └── project-structure.md # Структура проекта
├── snapshots/             # Снимки логов
├── screenshots/           # Скриншоты интерфейса
├── .env                   # Переменные окружения (создается из env.example)
├── env.example            # Пример переменных окружения
├── docker-compose.yml     # Конфигурация Docker Compose
├── Dockerfile            # Образ Docker
├── requirements.txt      # Зависимости Python
├── start.sh              # Скрипт запуска
└── README.md             # Документация проекта

Описание модулей

app/app.py

Основной файл приложения FastAPI. Содержит:

• Инициализацию FastAPI приложения
• Подключение статических файлов
• Обработчики исключений
• Подключение роутеров

app/api/v1/

API модули версии 1:

• router.py - Основной роутер, объединяющий все endpoints
• endpoints/ - Отдельные модули для каждого типа API

app/api/v1/endpoints/

API endpoints разделены по функциональности:

• auth.py - Аутентификация (login, logout, me)
• containers.py - Управление контейнерами (список, проекты)
• logs.py - Работа с логами (получение, статистика, снимки)
• pages.py - HTML страницы (главная, вход, ошибки)
• settings.py - Настройки приложения
• websocket.py - WebSocket API для real-time логов

app/core/

Основные модули приложения:

• auth.py - Логика аутентификации и авторизации
• config.py - Конфигурация приложения из переменных окружения
• docker.py - Работа с Docker API
• logger.py - Система логирования

app/models/

Pydantic модели данных:

• auth.py - Модели для аутентификации (UserLogin, Token)

app/static/

Статические файлы:

• css/ - CSS стили для всех страниц
• js/ - JavaScript файлы с логикой интерфейса
• images/ - Изображения и иконки
• fonts/ - Шрифты

app/templates/

HTML шаблоны:

• index.html - Главная страница с интерфейсом
• login.html - Страница входа в систему
• error.html - Шаблон для страниц ошибок

Принципы организации

1. Модульность

Каждый модуль отвечает за свою область ответственности:

• API endpoints разделены по функциональности
• Core модули содержат бизнес-логику
• Models определяют структуру данных

2. Версионирование API

API организован по версиям (v1/), что позволяет:

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

3. Разделение статических файлов

Статические файлы разделены по типам:

• CSS для стилизации
• JavaScript для интерактивности
• Изображения для визуальных элементов

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

Все настройки централизованы в app/core/config.py:

• Загрузка из переменных окружения
• Значения по умолчанию
• Валидация конфигурации

Добавление новых модулей

Новый API endpoint

1. Создайте файл в app/api/v1/endpoints/
2. Определите роутер с нужными маршрутами
3. Подключите в app/api/v1/router.py

Новый core модуль

1. Создайте файл в app/core/
2. Добавьте необходимые импорты
3. Обновите документацию

Новые статические файлы

1. Добавьте файлы в соответствующие папки app/static/
2. Обновите ссылки в HTML шаблонах
3. Проверьте корректность загрузки

Лучшие практики

1. Именование файлов - используйте snake_case для Python файлов
2. Документация - добавляйте docstrings ко всем функциям
3. Типизация - используйте type hints везде, где возможно
4. Обработка ошибок - добавляйте try-catch блоки
5. Логирование - используйте централизованную систему логирования