From c40b2b312e2b2ff98456800eda72f4f7b66463c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A1=D0=B5=D1=80=D0=B3=D0=B5=D0=B9=20=D0=90=D0=BD=D1=82?= =?UTF-8?q?=D1=80=D0=BE=D0=BF=D0=BE=D0=B2?= Date: Wed, 20 Aug 2025 18:32:31 +0300 Subject: [PATCH] docs: update documentation to reflect new project structure - Update README.md with new project structure and installation instructions - Update docs/installation.md with simplified setup process - Update docs/configuration.md with correct file paths - Update docs/index.md with new documentation structure - Add docs/project-structure.md with detailed architecture overview - Reflect changes from refactoring: app/ directory structure, .env file usage - Update installation instructions to use docker compose up --build -d - Add comprehensive project structure documentation --- README.md | 74 +++++++++++++--- docs/configuration.md | 2 +- docs/index.md | 20 +++-- docs/installation.md | 19 ++--- docs/project-structure.md | 172 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 257 insertions(+), 30 deletions(-) create mode 100644 docs/project-structure.md diff --git a/README.md b/README.md index 9beaec2..bf9065c 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,17 @@ LogBoard+ особенно полезен для разработчиков, р cd logboard ``` +2. **Настройка переменных окружения** + ```bash + cp env.example .env + # Отредактируйте .env файл при необходимости + ``` + +3. **Запуск приложения** + ```bash + docker compose up --build -d + ``` + 2. **Настройка переменных окружения** ```bash make setup @@ -161,19 +172,51 @@ make debug-status ``` logboard/ -├── app.py # Основное приложение FastAPI +├── 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 -├── Makefile # Команды управления -├── env.example # Пример переменных окружения -├── excluded_containers.json # Исключенные контейнеры -├── templates/ # HTML шаблоны -│ ├── index.html # Главная страница -│ ├── login.html # Страница входа -│ └── error.html # Страницы ошибок -├── snapshots/ # Снимки логов -└── screenshots/ # Скриншоты интерфейса +├── start.sh # Скрипт запуска +└── README.md # Документация проекта ``` ## API Документация @@ -210,6 +253,12 @@ logboard/ ### Переменные окружения +Приложение использует файл `.env` для конфигурации. Создайте его из `env.example`: + +```bash +cp env.example .env +``` + Основные настройки приложения: | Переменная | Описание | По умолчанию | @@ -219,6 +268,9 @@ logboard/ | `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` | ### Настройка проектов @@ -234,7 +286,7 @@ LOGBOARD_PROJECTS=project1,project2,project3 ### Исключение контейнеров -Создайте файл `excluded_containers.json`: +Файл `app/excluded_containers.json` содержит список контейнеров, которые не будут отображаться в интерфейсе: ```json { diff --git a/docs/configuration.md b/docs/configuration.md index 43992ae..86651a8 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -21,7 +21,7 @@ LogBoard+ использует переменные окружения для н - `.env` - Основной файл конфигурации (создается из `env.example`) - `docker-compose.yml` - Конфигурация Docker Compose -- `excluded_containers.json` - Список исключенных контейнеров +- `app/excluded_containers.json` - Список исключенных контейнеров ### Приоритет настроек diff --git a/docs/index.md b/docs/index.md index 2901ed0..f7e23d3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -40,10 +40,10 @@ git clone cd logboard # Настройка переменных окружения -make setup +cp env.example .env # Запуск приложения -make up +docker compose up --build -d ``` ### Доступ @@ -62,31 +62,37 @@ make up - Настройка для продакшена - Устранение проблем установки -2. **[API Документация](./api.md)** +2. **[Структура проекта](./project-structure.md)** + - Архитектура приложения + - Описание модулей + - Принципы организации + - Добавление новых модулей + +3. **[API Документация](./api.md)** - REST API endpoints - WebSocket API - Примеры использования - Коды ошибок -3. **[WebSocket API](./websocket.md)** +4. **[WebSocket API](./websocket.md)** - Подключение к WebSocket - Real-time логи - Обработка ошибок - Лучшие практики -4. **[Конфигурация](./configuration.md)** +5. **[Конфигурация](./configuration.md)** - Переменные окружения - Настройка Docker - Настройка безопасности - Примеры конфигураций -5. **[Безопасность](./security.md)** +6. **[Безопасность](./security.md)** - Генерация ключей - Аутентификация - Настройка HTTPS - Мониторинг безопасности -6. **[Устранение неполадок](./troubleshooting.md)** +7. **[Устранение неполадок](./troubleshooting.md)** - Общие проблемы - Проблемы с Docker - Проблемы с аутентификацией diff --git a/docs/installation.md b/docs/installation.md index ff59123..3ad9096 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -85,6 +85,9 @@ cd logboard # Проверка структуры проекта ls -la + +# Настройка переменных окружения +cp env.example .env ``` ### Метод 2: Скачивание архива @@ -155,23 +158,17 @@ chmod 755 snapshots ## Первый запуск -### 1. Сборка Docker образа +### 1. Сборка и запуск приложения ```bash +# Сборка и запуск в одном команде +docker compose up --build -d + +# Или пошагово: # Сборка образа -make build - -# Или вручную docker compose build --no-cache -``` -### 2. Запуск приложения - -```bash # Запуск в фоновом режиме -make up - -# Или вручную docker compose up -d ``` diff --git a/docs/project-structure.md b/docs/project-structure.md new file mode 100644 index 0000000..1470fb8 --- /dev/null +++ b/docs/project-structure.md @@ -0,0 +1,172 @@ +# Структура проекта 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. **Логирование** - используйте централизованную систему логирования