8.8 KiB
Развёртывание в 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): временный сервер первого запуска слушает только сокет, и проверка по сокету могла бы объявить базу готовой раньше времени.
Запуск
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 отказывается стартовать. Пароль должен состоять из букв и цифр, он входит в строку подключения.
Обновление
git pull && docker compose up -d --build # migrate выполнится перед запуском новой версии сервиса
Откат схемы не автоматический: перед обновлением делайте копию базы.
Резервная копия и восстановление
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
Администрирование
# пароль для пользователя веб-интерфейса (запрашивается дважды, не короче 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).