Files
2026-11-09 08:43:30 +03:00

93 lines
8.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Развёртывание в 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`).