Add RAG basic implementation

This commit is contained in:
2026-11-09 08:43:30 +03:00
parent 447464c16c
commit 7fa1d774a0
76 changed files with 3030 additions and 124 deletions
+92
View File
@@ -0,0 +1,92 @@
# Развёртывание в Docker
**Дата:** 2 ноября 2026 · **Статус:** файлы написаны и проверены имитацией; сборка образа и `docker compose up` в среде разработки не запускались (там нет Docker)
## Что входит
| Файл | Назначение |
|---|---|
| `Dockerfile` | Образ сервиса: двухэтапная сборка на `python:3.12-slim`, запуск не от root (пользователь `app`, uid 10001), проверка здоровья `/health` |
| `docker/entrypoint.sh` | Точка входа: `serve` (по умолчанию), `migrate`, любая другая команда передаётся в `python -m estimator` |
| `docker-compose.yml` | Три сервиса: `db` (PostgreSQL 16 с pgvector), `migrate` (разовое задание), `app` (сервис) |
| `.dockerignore` | Не пускает в образ `.env`, тесты, документацию, `.git` |
| `.env.example` | Шаблон `.env`: настройки сервиса, переменные compose, веб-интерфейс, обратный прокси |
## Порядок запуска и миграции
```
db становится healthy ─► migrate применяет схему и завершается успешно ─► app запускается
```
- `migrate` ждёт базу (`wait-db`, до 60 секунд), выполняет `alembic upgrade head` и выходит. `app` стартует только при коде возврата 0 (`service_completed_successfully`): **если миграция не прошла, сервис не запускается**.
- Миграции вынесены в отдельное задание, а не в запуск самого сервиса: при нескольких копиях сервиса они не будут применяться одновременно.
- Миграция повторяема: повторный запуск ничего не меняет. Она создаёт расширение `vector` (поэтому образ базы `pgvector/pgvector:pg16`, а пользователь базы должен быть суперпользователем, как в compose).
- Для одного контейнера без compose есть `MIGRATE_ON_START=true`: тогда `serve` сначала ждёт базу и применяет миграции, при сбое любого шага сервис не стартует.
- Проверка готовности базы в compose идёт по TCP (`pg_isready -h 127.0.0.1`): временный сервер первого запуска слушает только сокет, и проверка по сокету могла бы объявить базу готовой раньше времени.
## Запуск
```bash
cp .env.example .env # POSTGRES_PASSWORD, ключ(и) LLM, EST_API__KEYS
docker compose up -d --build
docker compose logs -f migrate app
curl http://localhost:8000/health
```
`POSTGRES_PASSWORD` обязателен: без него compose отказывается стартовать. Пароль должен состоять из букв и цифр, он входит в строку подключения.
## Обновление
```bash
git pull && docker compose up -d --build # migrate выполнится перед запуском новой версии сервиса
```
Откат схемы не автоматический: перед обновлением делайте копию базы.
## Резервная копия и восстановление
```bash
docker compose exec db pg_dump -U estimator -Fc estimator > estimator.dump
docker compose exec -T db pg_restore -U estimator -d estimator --clean < estimator.dump
```
## Администрирование
```bash
# пароль для пользователя веб-интерфейса (запрашивается дважды, не короче 12 символов)
docker compose run --rm app hash-password
# загрузка корпуса аналогов (файл монтируется в контейнер)
docker compose run --rm -v "$PWD/refs.csv:/data/refs.csv:ro" app rag import /data/refs.csv --project "Проект"
docker compose run --rm app rag stats
```
Хэш пароля содержит знаки `$`. В `.env` значение `EST_WEB__USERS` берите в одинарные кавычки, иначе compose попытается их раскрыть.
## За обратным прокси и HTTPS
- Включите `EST_API__PROXY_HEADERS=true` и укажите адреса прокси в `EST_API__FORWARDED_ALLOW_IPS` (никогда `*`, если порт доступен напрямую): иначе ограничитель попыток входа видит адрес прокси вместо адреса клиента.
- В образе по умолчанию `EST_ENV=prod`, то есть `config/prod.toml` с `cookie_secure = true`: сессионная cookie отправляется только по HTTPS (на `localhost` современные браузеры это допускают). Для обычного http на другом адресе задайте `EST_WEB__COOKIE_SECURE=false`.
- Сервис сам HTTPS не терминирует.
## Что сделано для безопасности
Запуск не от root, `cap_drop: ALL`, `no-new-privileges`, база не публикуется на хост, секреты не попадают в образ (`.env` исключён из контекста сборки, в `Dockerfile` нет ключей), пароль базы обязателен, пакеты ставятся только из собранных колёс. Конфигурация и промпты лежат в образе (`/app/config`, `/app/prompts`); чтобы их заменить, смонтируйте свои каталоги поверх.
## Что проверено и что нет
Проверено:
- колесо собирается и содержит шаблоны, статику и `htmx.min.js`; в зависимостях объявлен `pgvector` (его не хватало, он нужен схеме; теперь тест сверяет все импортируемые пакеты с `pyproject.toml`);
- в чистом виртуальном окружении, установленном из колёс (без каталога проекта), команда `migrate` применяет схему на PostgreSQL 16 с pgvector (таблицы, расширение, индекс HNSW), повторный запуск ничего не меняет;
- `serve` с `MIGRATE_ON_START=true` на пустой базе применяет миграции и только потом поднимает сервис, который отвечает на запросы;
- недоступная база или сломанная миграция останавливают запуск, порт не слушается;
- `wait-db` ждёт появления базы и возвращается, когда она создана;
- тесты в репозитории проверяют порядок вызовов точки входа (заглушкой вместо `python`), структуру compose (порядок запуска, один образ, обязательный пароль, база не опубликована) и свойства `Dockerfile` (не root, что копируется, нет секретов, `.dockerignore` не исключает нужное).
Не проверено (в среде нет Docker): `docker build`, `docker compose up`, размер образа, проверка здоровья внутри контейнера, поведение образа `pgvector/pgvector:pg16` на первом запуске (предполагается, что расширение в нём есть, а пользователь по умолчанию суперпользователь). Первый запуск стоит пройти вручную и посмотреть `docker compose logs migrate`.
## Ограничения
- Фоновые расчёты идут внутри процесса: запускайте одну копию `app`.
- Нет автоматических резервных копий и срока хранения старых оценок, нет ограничения частоты запросов к API.
- Образ не подписывается и не сканируется на уязвимости; версии зависимостей не закреплены (задаются нижними границами в `pyproject.toml`).