bd - api
This commit is contained in:
357
API_README.md
Normal file
357
API_README.md
Normal file
@@ -0,0 +1,357 @@
|
||||
# Telegram Bot API
|
||||
|
||||
FastAPI приложение для взаимодействия с Telegram ботом и базой данных PostgreSQL через SQLAlchemy.
|
||||
|
||||
## Структура проекта
|
||||
|
||||
```
|
||||
bot-telegram/
|
||||
├── api/ # FastAPI приложение
|
||||
│ ├── __init__.py
|
||||
│ ├── main.py # Основное приложение
|
||||
│ ├── routers.py # API маршруты
|
||||
│ ├── schemas.py # Pydantic схемы
|
||||
│ └── config.py # Конфигурация
|
||||
├── database/ # Модули базы данных
|
||||
│ ├── __init__.py
|
||||
│ ├── database.py # Подключение к БД
|
||||
│ ├── models.py # SQLAlchemy модели
|
||||
│ └── ...
|
||||
├── pyproject.toml # Зависимости проекта
|
||||
├── .env.example # Пример переменных окружения
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Установка и настройка
|
||||
|
||||
### Способ 1: Запуск через Docker (рекомендуется)
|
||||
|
||||
#### 1. Запуск с Docker Compose
|
||||
|
||||
```bash
|
||||
# Клонируйте репозиторий и перейдите в директорию
|
||||
cd bot-telegram
|
||||
|
||||
# Запустите все сервисы (API + PostgreSQL)
|
||||
docker-compose up -d
|
||||
|
||||
# Для просмотра логов
|
||||
docker-compose logs -f api
|
||||
|
||||
# Остановка сервисов
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
#### 2. Запуск с pgAdmin (опционально)
|
||||
|
||||
```bash
|
||||
# Запуск с админкой для базы данных
|
||||
docker-compose --profile admin up -d
|
||||
|
||||
# pgAdmin будет доступен по адресу: http://localhost:5050
|
||||
# Email: admin@admin.com
|
||||
# Password: admin
|
||||
```
|
||||
|
||||
#### 3. Сборка только API контейнера
|
||||
|
||||
```bash
|
||||
# Сборка образа
|
||||
docker build -t telegram-bot-api .
|
||||
|
||||
# Запуск контейнера (требует запущенный PostgreSQL)
|
||||
docker run -d \
|
||||
--name telegram-bot-api \
|
||||
-p 8000:8000 \
|
||||
-e DB_HOST=host.docker.internal \
|
||||
-e DB_PASSWORD=your_password \
|
||||
telegram-bot-api
|
||||
```
|
||||
|
||||
### Способ 2: Локальная установка
|
||||
|
||||
#### 1. Установка зависимостей
|
||||
|
||||
```bash
|
||||
# Используя uv (рекомендуется)
|
||||
uv sync
|
||||
|
||||
# Или используя pip
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
#### 2. Настройка базы данных
|
||||
|
||||
1. Создайте файл `.env` на основе `.env.example`:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
2. Отредактируйте `.env` файл с вашими настройками PostgreSQL:
|
||||
```env
|
||||
DB_USER=postgres
|
||||
DB_PASSWORD=your_password
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5432
|
||||
DB_NAME=telegram_bot
|
||||
```
|
||||
|
||||
3. Убедитесь, что PostgreSQL запущен и база данных создана:
|
||||
```sql
|
||||
CREATE DATABASE telegram_bot;
|
||||
```
|
||||
|
||||
#### 3. Запуск API
|
||||
|
||||
```bash
|
||||
# Из корневой директории проекта
|
||||
python run_api.py
|
||||
|
||||
# Или с помощью uvicorn напрямую
|
||||
uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload
|
||||
```
|
||||
|
||||
API будет доступно по адресу: http://localhost:8000
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Общие endpoints
|
||||
|
||||
- `GET /` - Корневая информация
|
||||
- `GET /health` - Проверка состояния приложения
|
||||
- `GET /docs` - Swagger UI документация (автоматически)
|
||||
- `GET /redoc` - ReDoc документация (автоматически)
|
||||
|
||||
### Пользователи (`/api/v1/users`)
|
||||
|
||||
- `GET /api/v1/users/` - Получить всех пользователей
|
||||
- `GET /api/v1/users/{telegram_id}` - Получить пользователя по Telegram ID
|
||||
- `POST /api/v1/users/` - Создать нового пользователя
|
||||
- `PUT /api/v1/users/{telegram_id}` - Обновить пользователя
|
||||
- `DELETE /api/v1/users/{telegram_id}` - Деактивировать пользователя
|
||||
|
||||
### Сообщения (`/api/v1/messages`)
|
||||
|
||||
- `GET /api/v1/messages/` - Получить сообщения с фильтрацией
|
||||
- `GET /api/v1/messages/{message_id}` - Получить конкретное сообщение
|
||||
- `POST /api/v1/messages/` - Создать новое сообщение
|
||||
|
||||
### Настройки бота (`/api/v1/settings`)
|
||||
|
||||
- `GET /api/v1/settings/` - Получить все настройки как словарь
|
||||
- `GET /api/v1/settings/list` - Получить все настройки как список объектов
|
||||
- `GET /api/v1/settings/{key}` - Получить настройку по ключу
|
||||
- `POST /api/v1/settings/` - Создать или обновить настройку
|
||||
- `PUT /api/v1/settings/{key}` - Обновить существующую настройку
|
||||
- `DELETE /api/v1/settings/{key}` - Удалить настройку
|
||||
|
||||
## Примеры использования
|
||||
|
||||
### Создание пользователя
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8000/api/v1/users/" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"telegram_id": 123456789,
|
||||
"username": "john_doe",
|
||||
"first_name": "John",
|
||||
"last_name": "Doe",
|
||||
"language_code": "en"
|
||||
}'
|
||||
```
|
||||
|
||||
### Создание сообщения
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8000/api/v1/messages/" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"telegram_message_id": 12345,
|
||||
"user_id": 1,
|
||||
"text": "Привет!",
|
||||
"message_type": "text"
|
||||
}'
|
||||
```
|
||||
|
||||
### Настройка бота
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8000/api/v1/settings/" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"key": "welcome_message",
|
||||
"value": "Добро пожаловать в наш бот!",
|
||||
"description": "Приветственное сообщение для новых пользователей"
|
||||
}'
|
||||
```
|
||||
|
||||
## Модели данных
|
||||
|
||||
### User (Пользователь)
|
||||
- `id` - Внутренний ID
|
||||
- `telegram_id` - Telegram ID пользователя (уникальный)
|
||||
- `username` - Username в Telegram
|
||||
- `first_name` - Имя
|
||||
- `last_name` - Фамилия
|
||||
- `language_code` - Код языка (по умолчанию 'ru')
|
||||
- `is_active` - Активен ли пользователь
|
||||
- `is_admin` - Является ли администратором
|
||||
- `created_at` - Дата создания
|
||||
- `updated_at` - Дата обновления
|
||||
|
||||
### Message (Сообщение)
|
||||
- `id` - Внутренний ID
|
||||
- `telegram_message_id` - ID сообщения в Telegram
|
||||
- `user_id` - ID пользователя (внешний ключ)
|
||||
- `text` - Текст сообщения
|
||||
- `message_type` - Тип сообщения (text, photo, document, etc.)
|
||||
- `created_at` - Дата создания
|
||||
|
||||
### BotSettings (Настройки бота)
|
||||
- `id` - Внутренний ID
|
||||
- `key` - Ключ настройки (уникальный)
|
||||
- `value` - Значение настройки
|
||||
- `description` - Описание настройки
|
||||
- `created_at` - Дата создания
|
||||
- `updated_at` - Дата обновления
|
||||
|
||||
## Переменные окружения
|
||||
|
||||
| Переменная | Описание | По умолчанию |
|
||||
|------------|----------|--------------|
|
||||
| `DB_USER` | Пользователь PostgreSQL | `postgres` |
|
||||
| `DB_PASSWORD` | Пароль PostgreSQL | `password` |
|
||||
| `DB_HOST` | Хост PostgreSQL | `localhost` |
|
||||
| `DB_PORT` | Порт PostgreSQL | `5432` |
|
||||
| `DB_NAME` | Имя базы данных | `telegram_bot` |
|
||||
| `API_HOST` | Хост API сервера | `0.0.0.0` |
|
||||
| `API_PORT` | Порт API сервера | `8000` |
|
||||
| `API_RELOAD` | Автоперезагрузка в dev режиме | `true` |
|
||||
| `LOG_LEVEL` | Уровень логирования | `INFO` |
|
||||
|
||||
## Разработка
|
||||
|
||||
### Структура API
|
||||
|
||||
API организовано по модульному принципу:
|
||||
|
||||
- `main.py` - Основное приложение FastAPI
|
||||
- `routers.py` - Определения маршрутов и бизнес-логика
|
||||
- `schemas.py` - Pydantic схемы для валидации данных
|
||||
- `config.py` - Конфигурация приложения
|
||||
|
||||
### Документация
|
||||
|
||||
FastAPI автоматически генерирует интерактивную документацию:
|
||||
|
||||
- Swagger UI: http://localhost:8000/docs
|
||||
- ReDoc: http://localhost:8000/redoc
|
||||
|
||||
### Логирование
|
||||
|
||||
Приложение использует стандартный модуль `logging` Python. Уровень логирования можно настроить через переменную окружения `LOG_LEVEL`.
|
||||
|
||||
## Интеграция с Telegram ботом
|
||||
|
||||
Этот API предназначен для использования Telegram ботом. Бот может:
|
||||
|
||||
1. Регистрировать новых пользователей при первом взаимодействии
|
||||
2. Сохранять все входящие сообщения
|
||||
3. Получать и обновлять настройки бота
|
||||
4. Управлять пользователями (активация/деактивация, права администратора)
|
||||
|
||||
Пример интеграции с aiogram или python-telegram-bot будет добавлен позже.
|
||||
|
||||
## Docker контейнеризация
|
||||
|
||||
### Структура Docker файлов
|
||||
|
||||
- **`Dockerfile`** - Многоступенчатая сборка для оптимизации размера образа
|
||||
- **`docker-compose.yml`** - Оркестрация API + PostgreSQL + pgAdmin
|
||||
- **`.dockerignore`** - Исключение ненужных файлов из контекста сборки
|
||||
- **`init.sql`** - Скрипт инициализации базы данных
|
||||
|
||||
### Docker Compose сервисы
|
||||
|
||||
1. **`postgres`** - PostgreSQL 15 база данных (отдельный контейнер)
|
||||
- Порт: 5432
|
||||
- Данные сохраняются в Docker volume
|
||||
- Автоматическая проверка готовности
|
||||
|
||||
2. **`app`** - Единое приложение (API + database логика в одном контейнере)
|
||||
- Порт: 8000
|
||||
- Включает FastAPI сервер и все модули для работы с БД
|
||||
- Подключается к внешней PostgreSQL по сети
|
||||
- Автоматически ждет готовности БД
|
||||
|
||||
3. **`pgadmin`** - Веб-админка PostgreSQL (опционально)
|
||||
- Порт: 5050
|
||||
- Запускается только с профилем `admin`
|
||||
|
||||
### Команды Docker
|
||||
|
||||
```bash
|
||||
# Сборка и запуск всех сервисов
|
||||
docker-compose up --build -d
|
||||
|
||||
# Просмотр логов конкретного сервиса
|
||||
docker-compose logs -f api
|
||||
docker-compose logs -f postgres
|
||||
|
||||
# Перезапуск сервиса
|
||||
docker-compose restart api
|
||||
|
||||
# Остановка и удаление контейнеров
|
||||
docker-compose down
|
||||
|
||||
# Остановка с удалением volumes (ВНИМАНИЕ: удаляет данные БД)
|
||||
docker-compose down -v
|
||||
|
||||
# Запуск только определенного сервиса
|
||||
docker-compose up postgres -d
|
||||
|
||||
# Выполнение команд внутри контейнера
|
||||
docker-compose exec api bash
|
||||
docker-compose exec postgres psql -U postgres -d telegram_bot
|
||||
```
|
||||
|
||||
### Переменные окружения в Docker
|
||||
|
||||
В `docker-compose.yml` настроены следующие переменные:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
# База данных
|
||||
DB_HOST: postgres
|
||||
DB_PORT: 5432
|
||||
DB_NAME: telegram_bot
|
||||
DB_USER: postgres
|
||||
DB_PASSWORD: password
|
||||
|
||||
# API
|
||||
API_HOST: 0.0.0.0
|
||||
API_PORT: 8000
|
||||
API_RELOAD: "false"
|
||||
LOG_LEVEL: INFO
|
||||
```
|
||||
|
||||
### Volumes и сети
|
||||
|
||||
- **Volume `postgres_data`** - Постоянное хранение данных PostgreSQL
|
||||
- **Network `bot_network`** - Изолированная сеть для взаимодействия сервисов
|
||||
|
||||
### Производственное развертывание
|
||||
|
||||
Для продакшена рекомендуется:
|
||||
|
||||
1. Изменить пароли по умолчанию
|
||||
2. Настроить внешние тома для данных
|
||||
3. Использовать reverse proxy (nginx)
|
||||
4. Настроить SSL сертификаты
|
||||
5. Ограничить CORS origins
|
||||
|
||||
```bash
|
||||
# Пример для продакшена
|
||||
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
|
||||
```
|
||||
Reference in New Issue
Block a user