English | Русский
FastH-SingleAuth — Легкий и современный шаблон для создания сайтов-визиток и лендингов на FastAPI с предустановленной админ-панелью и защищенной авторизацией.
| Компоненты | |
|---|---|
| 🐍 Язык: Python 3.14+ |  |
| ⚡ Фреймворк: FastAPI |  |
| 🪄 Фронтенд: HTMX |  |
| 🚀 ASGI-сервер: Uvicorn + Gunicorn |   |
| 🗄️ База Данных: PostgreSQL (asyncpg) |  |
| 🔁 ORM: SQLAlchemy (async) |  |
| 🔄 Миграции БД: Alembic |  |
| 🔧 Админка: SQLAdmin |  |
| ✅ Валидация: Pydantic v2 + pydantic-settings |   |
| 🧩 Кэширование: Redis + fastapi-cache2 |  |
| 📄 Шаблонизация: Jinja2 |  |
| 🛡️ Защита: CORS + Nginx Rate Limiting |   |
| 📦 Менеджер пакетов: uv |  |
| 🐳 Контейнеризация: Docker + Docker Compose |   |
| 🧪 Тестирование: Pytest + httpx + faker |    |
| 📘 Документация: OpenAPI (Swagger UI) |  |
| 🧹 Форматирование кода: Black |  |
| 📊 Покрытие тестами: pytest-cov |  |
- 🔐 Облегченная авторизация (SingleAuth System)
Безопасный вход для единственного администратора через сессионные куки. Никакой регистрации лишних пользователей — только вы и ваш контент. Защита от
XSSиCSRFна уровне Middleware - 🛡️ Защита инфраструктуры (Nginx Limiter Ready) & (Security Headers)
Автоматическая настройка HTTP-заголовков безопасности (HSTS, Content-Security-Policy, X-Frame-Options) для защиты сайта в продакшене. Настройка
CORSдля безопасного взаимодействия с фронтенд-приложениями. Архитектура проекта подготовлена к деплою с использованием Nginx в качестве реверс-прокси. Встроенная поддержкаRate Limitingна уровне сети для защиты админки и поиска от ботов. - 🛠️ Профессиональная админ-панель (SQLAdmin)
Полноценный интерфейс для управления данными: CRUD операции, фильтрация и поиск по всем моделям базы данных прямо в браузере.
- 🏗️ Современная архитектура (Clean Architecture)
Разделение приложения на независимые слои: Views, Services, Repositories и Models.
- 💎 Современный Frontend (HTMX + Glassmorphism)
Живой пользовательский интерфейс без тяжелых JS-фреймворков. Интерактивный поиск, динамические формы и стильный дизайн с эффектом «матового стекла» (Glassmorphism).
- 🚀 Реактивная сборка (uv)
Использование пакетного менеджера
uvдля мгновенной установки зависимостей и сборки виртуального окружения. - 🗄️ Работа с данными (SQLAlchemy 2.0)
Полностью асинхронное взаимодействие с
PostgreSQL (asyncpg). Универсальный базовый репозиторий для минимизации шаблонного кода при работе с БД. - 🔄 Автоматизация миграций (Alembic)
Управление схемами базы данных с поддержкой асинхронности. Автоматический накат миграций при запуске контейнера.
- 📧 Асинхронные уведомления (aiosmtplib)
Отправка системных и транзакционных писем (подтверждение регистрации, сброс пароля) без блокировки основного потока приложения.
- 🧩 Кэширование (Redis + fastapi-cache2)
Интеграция с
Redisдля кэширования тяжелых запросов, что значительно снижает нагрузку на базу данных и ускоряет отклик API. - 📦 Контейнеризация (Docker & Docker Compose)
Готовая инфраструктура в
Docker Compose: приложение, БД, Redis и PGAdmin запускаются одной командой. - 🧪 Надежное тестирование (Pytest)
Настроенная среда для тестирования асинхронного API с использованием
HTTPX. Генерация фейковых данных черезFakerи отчеты о покрытии кода черезpytest-cov. - 📘 Чистая документация (Swagger/OpenAPI)
Интерактивная документация API, автоматически отключаемая в режиме production для дополнительной безопасности.
FastH-SingleAuth/
├── app/ # Основной пакет приложения
│ ├── admin/ # Конфигурация админ-панели SQLAdmin
│ ├── alembic/ # История и версии миграций базы данных
│ ├── core/ # Системное ядро и инфраструктурные компоненты
│ │ ├── cache/ # Настройки и утилиты кэширования (Redis)
│ │ ├── gunicorn/ # Конфигурация WSGI-сервера для продакшена
│ │ ├── config/ # Валидация настроек через pydantic-settings (.env)
│ │ ├── db_helper.py # Инициализация движка SQLAlchemy и сессий
│ │ └── templates.py # Интеграция и конфигурация Jinja2Templates
│ ├── exceptions/ # Обработка исключений
│ │ ├── custom.py # Определение пользовательских классов ошибок
│ │ └── handlers.py # Глобальные обработчики исключений
│ ├── middleware/ # Кастомные middleware
│ ├── models/ # Описание сущностей базы данных (ORM SQLAlchemy)
│ ├── repositories/ # Слой доступа к данным (Data Access Layer)
│ │ └── crud_manager.py # Универсальный CRUD-менеджер для работы с моделями
│ ├── schemas/ # Модели данных Pydantic (DTO) для валидации
│ ├── services/ # Слой бизнес-логики (UseCase Layer)
│ ├── static/ # Статическое содержимое (CSS, JS, Изображения)
│ ├── templates/ # HTML-шаблоны (Jinja2)
│ ├── utils/ # Вспомогательные функции общего назначения
│ │ └── case_converter.py # Функция конвертации имени таблицы
│ ├── views/ # Роутеры для рендеринга HTML-страниц (Frontend-интерфейс)
│ ├── .env # Переменные окружения (не отображается в git)
│ ├── .env.template # Шаблон .env (автоматически заменяет .env, если его нет)
│ ├── alembic.ini # Конфигурационный файл миграций Alembic
│ ├── create_fastapi_app.py # Фабрика для сборки и настройки экземпляра FastAPI
│ ├── main.py # Точка входа для запуска в режиме разработки
│ ├── run.py # Запуск приложения через Gunicorn (для Docker)
│ └── run_main.py # Создания и запуск приложения через Gunicorn
├── docker-build/ # Инфраструктурные файлы сборки
│ └── app/
│ ├── Dockerfile # Инструкции для сборки Docker-образа
│ └── prestart.sh # Скрипт подготовки БД (миграции + создание админа)
├── docker-compose.yml # Оркестрация контейнеров (App, DB, Redis, PGAdmin)
├── pyproject.toml # Конфигурация проекта, зависимостей и инструментов (uv)
└── uv.lock # Фиксированные версии установленных пакетов- Клонируйте репозиторий
В терминале выполните команду:
git clone https://github.com/Mishchenko-Vladimir/FastH-SingleAuth.gitПерейдите в директорию проекта:
cd FastH-SingleAuth
- Настройка переменных окружения
Заполните файлы
.env.templateиdocker-compose.ymlсвоими значениями.
- Ваша разработка и настройка приложения
Синхронизируйте виртуальное окружение проекта с зависимостями:
uv syncПримените миграцию:
cd app alembic upgrade head cd ..Просто редактируйте и добавляйте новые файлы в папку
app/, и изменения автоматически применятся в запущенном контейнере.Локальный запуск (без
Docker):uv run python app/main.py
- Запуск приложение через Docker
Если вы запускаете образ в Windows, убедись что файлы
docker-build/app/prestart.shиapp/run.py, стоят в расширенииLF, а неCRLF.Сборка образа с именем
app:docker compose build appЗапуск сборки (приложения):
docker compose up -dОстальные команды
docker:
docker compose ps— посмотреть какие контейнеры запущеныdocker compose logs -f app— посмотреть логи приложенияdocker compose stop— остановка приложенияdocker compose down— удаления сборки
Приложение будет доступно по адресу http://localhost:8000, а документация http://localhost:8000/docs
- GitHub: Mishchenko-Vladimir
- Mail.ru: mishchienko.2001@mail.ru
- Gmail: mishchieko.2001@gmail.com
- Telegram: @VM_Dev
💌 Не забудьте поставить звезду ⭐ на GitHub, если вам понравился проект! 😉
💡 Ищете больше возможностей?
Если вам нужна расширенная версия c полным циклом Auth & Security (
FastAPI-Users), готовой Интерактивной UI (HTMX+Jinja2), защитой CSRF и современным интерфейсом в стиле Glassmorphism, обратите внимание на этот проект: