12 KiB

Raw 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 - основная документация
CLAUDE.md - архитектура и гайд для Claude
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 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 Blame History