12 KiB

Raw Permalink Blame History

Production Readiness Checklist

Полная проверка готовности Brief Bench FastAPI к развертыванию в продакшн.

Backend (FastAPI)

Код и архитектура

Все API endpoints реализованы
- Auth: /api/v1/auth/login
- Settings: GET/PUT /api/v1/settings
- Query: POST /api/v1/query/bench, /api/v1/query/backend
- Analysis: CRUD /api/v1/analysis/sessions
- Health: /health
Бизнес-логика покрыта тестами: 99%
- 119 unit tests (99% coverage)
- Integration tests (DB API)
- E2E tests (полный стек)
Services реализованы
- AuthService (JWT токены)
- RagService (RAG backends: IFT, PSI, PROD)
Interfaces реализованы
- TgBackendInterface (базовый HTTP клиент)
- DBApiClient (DB API integration)
Models валидация
- Все Pydantic models для request/response
- Валидация входных данных

Frontend (Static Files)

HTML/CSS/JS файлы
- index.html
- styles.css (Material Design)
- app.js (основная логика)
- api-client.js (API клиент)
- settings.js (настройки)
Интеграция с backend
- API client использует /api/v1 endpoints
- JWT токены в localStorage
- Правильная обработка ошибок (401, 502, etc.)
- StaticFiles монтированы в main.py
UI функциональность
- Login screen
- Multi-environment tabs (IFT, PSI, PROD)
- Settings panel
- Query interface
- Results display
- Session management

Конфигурация (ТРЕБУЕТ ВНИМАНИЯ!)

КРИТИЧНО - Сделать перед деплоем:

1. Создать .env файл
```
cp .env.example .env
nano .env
```

2. Сгенерировать новый JWT_SECRET_KEY

import secrets
print(secrets.token_urlsafe(32))

Заменить в .env:

JWT_SECRET_KEY=<сгенерированный-ключ>

3. Настроить DB_API_URL

DB_API_URL=http://your-db-api-host:8080/api/v1

4. Настроить RAG backend hosts

IFT_RAG_HOST=your-ift-rag-host.com
PSI_RAG_HOST=your-psi-rag-host.com
PROD_RAG_HOST=your-prod-rag-host.com

5. Разместить mTLS сертификаты (если используются)

certs/
  ift/
    ca.crt
    client.key
    client.crt
  psi/
    ca.crt
    client.key
    client.crt
  prod/
    ca.crt
    client.key
    client.crt

6. Настроить CORS для production

Отредактировать app/main.py:21:
```
# Было:
allow_origins=["*"],  # TODO: Configure properly in production

# Стало (если нужно ограничить):
allow_origins=["https://your-domain.com"],
```
ИЛИ оставить ["*"] если:
- Фронтенд и бэкенд на одном домене/IP (CORS не нужен)
- JWT токены обеспечивают безопасность
7. Отключить DEBUG режим
```
DEBUG=false
```

Docker & Deployment

Dockerfile готов
- Multi-stage build
- Копирует static/ файлы
- Expose 8000
- Uvicorn с правильными параметрами
docker-compose.yml готов
- Порты пробрасываются (8000:8000)
- Volume для certs (read-only)
- Volume для static файлов
- .env подключается
- restart: unless-stopped

Безопасность

Authentication
- JWT токены (30 дней expiration)
- Bearer token authentication
- Middleware для проверки токенов
Secrets management
- .env не в git (.gitignore)
- .env.integration не в git
- .env.e2e не в git
- ВАЖНО: Сменить JWT_SECRET_KEY в продакшн!
mTLS сертификаты
- Хранятся только на сервере
- Read-only volume в Docker
- Не коммитятся в git
HTTPS (рекомендуется)
- Настроить reverse proxy (nginx/traefik)
- Let's Encrypt сертификаты
- Редирект HTTP → HTTPS

Документация

README.md - основная документация
DB_API_CONTRACT.md - контракт с DB API
TESTING.md - полное руководство по тестированию
PROJECT_STATUS.md - статус реализации
tests/integration/README.md - интеграционные тесты
tests/e2e/README.md - E2E тесты

Pre-Deployment Testing

Локальное тестирование

1. Запустить unit тесты

.\run_unit_tests.bat
# Ожидается: 119 tests passed, 99% coverage

2. Запустить integration тесты (если DB API доступно)

.\run_integration_tests.bat
# Требует: DB API running на localhost:8081

3. Локальный запуск

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

4. Проверить основные endpoint'ы

# Health check
curl http://localhost:8000/health

# Frontend доступен
curl http://localhost:8000/

# Login (замените на реальный тестовый логин)
curl -X POST "http://localhost:8000/api/v1/auth/login?login=12345678"

5. Проверить frontend в браузере
- Открыть http://localhost:8000/
- Войти с тестовым логином
- Проверить все три окружения (IFT, PSI, PROD)
- Проверить Settings panel
- Отправить тестовый запрос (если RAG доступен)

Docker тестирование

1. Build Docker image
```
docker-compose build
```
2. Запустить контейнер
```
docker-compose up -d
```

3. Проверить логи

docker-compose logs -f fastapi
# Не должно быть ошибок

4. Проверить доступность

curl http://localhost:8000/health
curl http://localhost:8000/

5. Остановить
```
docker-compose down
```

Deployment Steps

1. Подготовка сервера

# Клонировать на сервер
git clone <your-repo> /opt/brief-bench-fastapi
cd /opt/brief-bench-fastapi

# Создать .env из шаблона
cp .env.example .env
nano .env
# Заполнить все переменные!

2. Разместить сертификаты

# Создать директорию для сертификатов
mkdir -p certs/{ift,psi,prod}

# Скопировать сертификаты
# scp или другим способом разместить в certs/

3. Запуск

# Build и запуск
docker-compose up -d

# Проверка логов
docker-compose logs -f fastapi

# Проверка health
curl http://localhost:8000/health

4. Настройка reverse proxy (опционально, но рекомендуется)

Nginx конфиг:

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Для long-running RAG запросов
        proxy_read_timeout 1800s;
        proxy_connect_timeout 1800s;
        proxy_send_timeout 1800s;
    }
}

Post-Deployment Verification

После деплоя проверить:

Health endpoint работает: curl https://your-domain.com/health
Frontend загружается: https://your-domain.com/
Login работает с реальным пользователем
Settings загружаются для всех окружений
Query работает для каждого окружения
Session save/load работает
Логи не содержат ошибок: docker-compose logs -f

Мониторинг и обслуживание

Логи

# Просмотр логов
docker-compose logs -f fastapi

# Последние 100 строк
docker-compose logs --tail=100 fastapi

Restart

# Перезапуск после изменений
docker-compose restart fastapi

# Полный rebuild
docker-compose down
docker-compose up -d --build

Обновление

# Pull изменений
git pull origin main

# Rebuild и restart
docker-compose down
docker-compose up -d --build

Backup

Критичные данные:

.env - секреты и конфигурация
certs/ - mTLS сертификаты
Пользовательские данные хранятся в DB API (не в FastAPI)

Performance Considerations

RAG запросы могут занимать до 30 минут (настроено)
Async/await для всех I/O операций
Connection pooling в httpx clients
Рассмотреть rate limiting для production
Рассмотреть caching для settings (опционально)

Troubleshooting

Проблема: Контейнер не запускается

Проверить:

Логи: docker-compose logs fastapi
.env существует и заполнен
Порт 8000 не занят: netstat -an | grep 8000

Проблема: Frontend не загружается

Проверить:

Static файлы скопированы в Docker: docker exec -it brief-bench-fastapi ls /app/static
main.py монтирует /static
index.html существует

Проблема: RAG запросы падают с timeout

Проверить:

RAG backends доступны с сервера
mTLS сертификаты правильные
RAG_REQUEST_TIMEOUT=1800 в .env
Nginx/proxy timeouts настроены (если используется)

Проблема: 401 Unauthorized

Проверить:

JWT токен в localStorage браузера
JWT_SECRET_KEY одинаковый между запусками
Токен не истек (30 дней по умолчанию)

Final Checklist Summary

Перед деплоем в продакшн:

Backend код готов (99% coverage)
Frontend интегрирован
Docker конфигурация готова
.env создан и заполнен
JWT_SECRET_KEY сгенерирован новый
RAG hosts настроены
DB_API_URL настроен
mTLS сертификаты размещены (если используются)
CORS настроен (при необходимости)
DEBUG=false
Unit тесты passed
Integration тесты passed (опционально)
Локальное тестирование пройдено
Docker build успешен

Статус готовности: ПОЧТИ ГОТОВ

Готово: Код, тесты, Docker, документация Требуется: Конфигурация окружения (.env, сертификаты, финальная настройка)

После выполнения пунктов из раздела "КРИТИЧНО" → ГОТОВ К ПРОДАКШН

12 KiB Raw Permalink Blame History Unescape Escape

Production Readiness Checklist

Backend (FastAPI)

Код и архитектура

Frontend (Static Files)

Конфигурация (ТРЕБУЕТ ВНИМАНИЯ!)

КРИТИЧНО - Сделать перед деплоем:

Docker & Deployment

Безопасность

Документация

Pre-Deployment Testing

Локальное тестирование

Docker тестирование

Deployment Steps

1. Подготовка сервера

2. Разместить сертификаты

3. Запуск

4. Настройка reverse proxy (опционально, но рекомендуется)

Post-Deployment Verification

Мониторинг и обслуживание

Логи

Restart

Обновление

Backup

Performance Considerations

Troubleshooting

Проблема: Контейнер не запускается

Проблема: Frontend не загружается

Проблема: RAG запросы падают с timeout

Проблема: 401 Unauthorized

Final Checklist Summary

12 KiB

Raw Permalink Blame History