PetProject/logboard
PetProject/logboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update documentation to reflect new project structure

Browse Source 
- 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
This commit is contained in:
Сергей Антропов 2025-08-20 18:32:31 +03:00
parent ab4c2924c3
commit c40b2b312e
5 changed files with 257 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
README.md
View File

@ -99,6 +99,17 @@ LogBoard+ особенно полезен для разработчиков, р
cd logboard cd logboard
``` ```
2. **Настройка переменных окружения**
```bash
cp env.example .env
# Отредактируйте .env файл при необходимости
```
3. **Запуск приложения**
```bash
docker compose up --build -d
```
2. **Настройка переменных окружения** 2. **Настройка переменных окружения**
```bash ```bash
make setup make setup
@ -161,19 +172,51 @@ make debug-status
``` ```
logboard/ 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 ├── docker-compose.yml # Конфигурация Docker Compose
├── Dockerfile # Образ Docker ├── Dockerfile # Образ Docker
├── requirements.txt # Зависимости Python ├── requirements.txt # Зависимости Python
├── Makefile # Команды управления ├── start.sh # Скрипт запуска
├── env.example # Пример переменных окружения └── README.md # Документация проекта
├── excluded_containers.json # Исключенные контейнеры
├── templates/ # HTML шаблоны
│ ├── index.html # Главная страница
│ ├── login.html # Страница входа
│ └── error.html # Страницы ошибок
├── snapshots/ # Снимки логов
└── screenshots/ # Скриншоты интерфейса
``` ```
## API Документация ## API Документация
@ -210,6 +253,12 @@ logboard/
### Переменные окружения ### Переменные окружения
Приложение использует файл `.env` для конфигурации. Создайте его из `env.example`:
```bash
cp env.example .env
```
Основные настройки приложения: Основные настройки приложения:
| Переменная | Описание | По умолчанию | | Переменная | Описание | По умолчанию |
@ -219,6 +268,9 @@ logboard/
| `LOGBOARD_PASS` | Пароль пользователя | `admin` | | `LOGBOARD_PASS` | Пароль пользователя | `admin` |
| `LOGBOARD_TAIL` | Количество строк логов | `500` | | `LOGBOARD_TAIL` | Количество строк логов | `500` |
| `SECRET_KEY` | Секретный ключ JWT | `your-secret-key-here` | | `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 ```json
{ {

2
docs/configuration.md
View File

@ -21,7 +21,7 @@ LogBoard+ использует переменные окружения для н
- `.env` - Основной файл конфигурации (создается из `env.example`) - `.env` - Основной файл конфигурации (создается из `env.example`)
- `docker-compose.yml` - Конфигурация Docker Compose - `docker-compose.yml` - Конфигурация Docker Compose
- `excluded_containers.json` - Список исключенных контейнеров - `app/excluded_containers.json` - Список исключенных контейнеров
### Приоритет настроек ### Приоритет настроек

20
docs/index.md
View File

@ -40,10 +40,10 @@ git clone <repository-url>
cd logboard 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 - REST API endpoints
- WebSocket API - WebSocket API
- Примеры использования - Примеры использования
- Коды ошибок - Коды ошибок
3. **[WebSocket API](./websocket.md)** 4. **[WebSocket API](./websocket.md)**
- Подключение к WebSocket - Подключение к WebSocket
- Real-time логи - Real-time логи
- Обработка ошибок - Обработка ошибок
- Лучшие практики - Лучшие практики
4. **[Конфигурация](./configuration.md)** 5. **[Конфигурация](./configuration.md)**
- Переменные окружения - Переменные окружения
- Настройка Docker - Настройка Docker
- Настройка безопасности - Настройка безопасности
- Примеры конфигураций - Примеры конфигураций
5. **[Безопасность](./security.md)** 6. **[Безопасность](./security.md)**
- Генерация ключей - Генерация ключей
- Аутентификация - Аутентификация
- Настройка HTTPS - Настройка HTTPS
- Мониторинг безопасности - Мониторинг безопасности
6. **[Устранение неполадок](./troubleshooting.md)** 7. **[Устранение неполадок](./troubleshooting.md)**
- Общие проблемы - Общие проблемы
- Проблемы с Docker - Проблемы с Docker
- Проблемы с аутентификацией - Проблемы с аутентификацией

19
docs/installation.md
View File

@ -85,6 +85,9 @@ cd logboard
# Проверка структуры проекта # Проверка структуры проекта
ls -la ls -la
# Настройка переменных окружения
cp env.example .env
``` ```
### Метод 2: Скачивание архива ### Метод 2: Скачивание архива
@ -155,23 +158,17 @@ chmod 755 snapshots
## Первый запуск ## Первый запуск
### 1. Сборка Docker образа ### 1. Сборка и запуск приложения
```bash ```bash
# Сборка и запуск в одном команде
docker compose up --build -d
# Или пошагово:
# Сборка образа # Сборка образа
make build
# Или вручную
docker compose build --no-cache docker compose build --no-cache
```
### 2. Запуск приложения
```bash
# Запуск в фоновом режиме # Запуск в фоновом режиме
make up
# Или вручную
docker compose up -d docker compose up -d
``` ```

172
docs/project-structure.md Normal file
View File

@ -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. **Логирование** - используйте централизованную систему логирования