429 lines
12 KiB
Markdown
429 lines
12 KiB
Markdown
# Production Readiness Checklist
|
||
|
||
Полная проверка готовности Brief Bench FastAPI к развертыванию в продакшн.
|
||
|
||
## Backend (FastAPI)
|
||
|
||
### Код и архитектура
|
||
- [x] **Все 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`
|
||
|
||
- [x] **Бизнес-логика покрыта тестами: 99%**
|
||
- 119 unit tests (99% coverage)
|
||
- Integration tests (DB API)
|
||
- E2E tests (полный стек)
|
||
|
||
- [x] **Services реализованы**
|
||
- AuthService (JWT токены)
|
||
- RagService (RAG backends: IFT, PSI, PROD)
|
||
|
||
- [x] **Interfaces реализованы**
|
||
- TgBackendInterface (базовый HTTP клиент)
|
||
- DBApiClient (DB API integration)
|
||
|
||
- [x] **Models валидация**
|
||
- Все Pydantic models для request/response
|
||
- Валидация входных данных
|
||
|
||
## Frontend (Static Files)
|
||
|
||
- [x] **HTML/CSS/JS файлы**
|
||
- index.html
|
||
- styles.css (Material Design)
|
||
- app.js (основная логика)
|
||
- api-client.js (API клиент)
|
||
- settings.js (настройки)
|
||
|
||
- [x] **Интеграция с backend**
|
||
- API client использует `/api/v1` endpoints
|
||
- JWT токены в localStorage
|
||
- Правильная обработка ошибок (401, 502, etc.)
|
||
- StaticFiles монтированы в main.py
|
||
|
||
- [x] **UI функциональность**
|
||
- Login screen
|
||
- Multi-environment tabs (IFT, PSI, PROD)
|
||
- Settings panel
|
||
- Query interface
|
||
- Results display
|
||
- Session management
|
||
|
||
## Конфигурация (ТРЕБУЕТ ВНИМАНИЯ!)
|
||
|
||
### КРИТИЧНО - Сделать перед деплоем:
|
||
|
||
- [ ] **1. Создать `.env` файл**
|
||
```bash
|
||
cp .env.example .env
|
||
nano .env
|
||
```
|
||
|
||
- [ ] **2. Сгенерировать новый JWT_SECRET_KEY**
|
||
```python
|
||
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](app/main.py#L21):
|
||
```python
|
||
# Было:
|
||
allow_origins=["*"], # TODO: Configure properly in production
|
||
|
||
# Стало (если нужно ограничить):
|
||
allow_origins=["https://your-domain.com"],
|
||
```
|
||
|
||
**ИЛИ** оставить `["*"]` если:
|
||
- Фронтенд и бэкенд на одном домене/IP (CORS не нужен)
|
||
- JWT токены обеспечивают безопасность
|
||
|
||
- [ ] **7. Отключить DEBUG режим**
|
||
```
|
||
DEBUG=false
|
||
```
|
||
|
||
## Docker & Deployment
|
||
|
||
- [x] **Dockerfile готов**
|
||
- Multi-stage build
|
||
- Копирует static/ файлы
|
||
- Expose 8000
|
||
- Uvicorn с правильными параметрами
|
||
|
||
- [x] **docker-compose.yml готов**
|
||
- Порты пробрасываются (8000:8000)
|
||
- Volume для certs (read-only)
|
||
- Volume для static файлов
|
||
- .env подключается
|
||
- restart: unless-stopped
|
||
|
||
## Безопасность
|
||
|
||
- [x] **Authentication**
|
||
- JWT токены (30 дней expiration)
|
||
- Bearer token authentication
|
||
- Middleware для проверки токенов
|
||
|
||
- [x] **Secrets management**
|
||
- .env не в git (.gitignore)
|
||
- .env.integration не в git
|
||
- .env.e2e не в git
|
||
- ВАЖНО: Сменить JWT_SECRET_KEY в продакшн!
|
||
|
||
- [x] **mTLS сертификаты**
|
||
- Хранятся только на сервере
|
||
- Read-only volume в Docker
|
||
- Не коммитятся в git
|
||
|
||
- [ ] **HTTPS (рекомендуется)**
|
||
- Настроить reverse proxy (nginx/traefik)
|
||
- Let's Encrypt сертификаты
|
||
- Редирект HTTP → HTTPS
|
||
|
||
## Документация
|
||
|
||
- [x] **README.md** - основная документация
|
||
- [x] **DB_API_CONTRACT.md** - контракт с DB API
|
||
- [x] **TESTING.md** - полное руководство по тестированию
|
||
- [x] **PROJECT_STATUS.md** - статус реализации
|
||
- [x] **tests/integration/README.md** - интеграционные тесты
|
||
- [x] **tests/e2e/README.md** - E2E тесты
|
||
|
||
## Pre-Deployment Testing
|
||
|
||
### Локальное тестирование
|
||
|
||
- [ ] **1. Запустить unit тесты**
|
||
```bash
|
||
.\run_unit_tests.bat
|
||
# Ожидается: 119 tests passed, 99% coverage
|
||
```
|
||
|
||
- [ ] **2. Запустить integration тесты** (если DB API доступно)
|
||
```bash
|
||
.\run_integration_tests.bat
|
||
# Требует: DB API running на localhost:8081
|
||
```
|
||
|
||
- [ ] **3. Локальный запуск**
|
||
```bash
|
||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
- [ ] **4. Проверить основные endpoint'ы**
|
||
```bash
|
||
# 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**
|
||
```bash
|
||
docker-compose build
|
||
```
|
||
|
||
- [ ] **2. Запустить контейнер**
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
- [ ] **3. Проверить логи**
|
||
```bash
|
||
docker-compose logs -f fastapi
|
||
# Не должно быть ошибок
|
||
```
|
||
|
||
- [ ] **4. Проверить доступность**
|
||
```bash
|
||
curl http://localhost:8000/health
|
||
curl http://localhost:8000/
|
||
```
|
||
|
||
- [ ] **5. Остановить**
|
||
```bash
|
||
docker-compose down
|
||
```
|
||
|
||
## Deployment Steps
|
||
|
||
### 1. Подготовка сервера
|
||
|
||
```bash
|
||
# Клонировать на сервер
|
||
git clone <your-repo> /opt/brief-bench-fastapi
|
||
cd /opt/brief-bench-fastapi
|
||
|
||
# Создать .env из шаблона
|
||
cp .env.example .env
|
||
nano .env
|
||
# Заполнить все переменные!
|
||
```
|
||
|
||
### 2. Разместить сертификаты
|
||
|
||
```bash
|
||
# Создать директорию для сертификатов
|
||
mkdir -p certs/{ift,psi,prod}
|
||
|
||
# Скопировать сертификаты
|
||
# scp или другим способом разместить в certs/
|
||
```
|
||
|
||
### 3. Запуск
|
||
|
||
```bash
|
||
# Build и запуск
|
||
docker-compose up -d
|
||
|
||
# Проверка логов
|
||
docker-compose logs -f fastapi
|
||
|
||
# Проверка health
|
||
curl http://localhost:8000/health
|
||
```
|
||
|
||
### 4. Настройка reverse proxy (опционально, но рекомендуется)
|
||
|
||
**Nginx конфиг:**
|
||
```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`
|
||
|
||
## Мониторинг и обслуживание
|
||
|
||
### Логи
|
||
|
||
```bash
|
||
# Просмотр логов
|
||
docker-compose logs -f fastapi
|
||
|
||
# Последние 100 строк
|
||
docker-compose logs --tail=100 fastapi
|
||
```
|
||
|
||
### Restart
|
||
|
||
```bash
|
||
# Перезапуск после изменений
|
||
docker-compose restart fastapi
|
||
|
||
# Полный rebuild
|
||
docker-compose down
|
||
docker-compose up -d --build
|
||
```
|
||
|
||
### Обновление
|
||
|
||
```bash
|
||
# 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
|
||
|
||
### Проблема: Контейнер не запускается
|
||
|
||
**Проверить:**
|
||
1. Логи: `docker-compose logs fastapi`
|
||
2. `.env` существует и заполнен
|
||
3. Порт 8000 не занят: `netstat -an | grep 8000`
|
||
|
||
### Проблема: Frontend не загружается
|
||
|
||
**Проверить:**
|
||
1. Static файлы скопированы в Docker: `docker exec -it brief-bench-fastapi ls /app/static`
|
||
2. main.py монтирует `/static`
|
||
3. index.html существует
|
||
|
||
### Проблема: RAG запросы падают с timeout
|
||
|
||
**Проверить:**
|
||
1. RAG backends доступны с сервера
|
||
2. mTLS сертификаты правильные
|
||
3. `RAG_REQUEST_TIMEOUT=1800` в .env
|
||
4. Nginx/proxy timeouts настроены (если используется)
|
||
|
||
### Проблема: 401 Unauthorized
|
||
|
||
**Проверить:**
|
||
1. JWT токен в localStorage браузера
|
||
2. JWT_SECRET_KEY одинаковый между запусками
|
||
3. Токен не истек (30 дней по умолчанию)
|
||
|
||
## Final Checklist Summary
|
||
|
||
Перед деплоем в продакшн:
|
||
|
||
1. Backend код готов (99% coverage)
|
||
2. Frontend интегрирован
|
||
3. Docker конфигурация готова
|
||
4. **`.env` создан и заполнен**
|
||
5. **`JWT_SECRET_KEY` сгенерирован новый**
|
||
6. **RAG hosts настроены**
|
||
7. **DB_API_URL настроен**
|
||
8. **mTLS сертификаты размещены** (если используются)
|
||
9. **CORS настроен** (при необходимости)
|
||
10. **DEBUG=false**
|
||
11. Unit тесты passed
|
||
12. Integration тесты passed (опционально)
|
||
13. Локальное тестирование пройдено
|
||
14. Docker build успешен
|
||
|
||
---
|
||
|
||
**Статус готовности: ПОЧТИ ГОТОВ**
|
||
|
||
**Готово:** Код, тесты, Docker, документация
|
||
**Требуется:** Конфигурация окружения (.env, сертификаты, финальная настройка)
|
||
|
||
После выполнения пунктов из раздела "КРИТИЧНО" → **ГОТОВ К ПРОДАКШН**
|