Перейти к содержанию

Docker / Docker Compose

Synth поставляется готовым образом git.itphx.ru/itphx/synth и файлом docker-compose.yml. Это самый простой способ развернуть платформу, если не хочется устанавливать Node.js: образ уже содержит и core, и веб-интерфейс.

Быстрый запуск образа

docker run -p 4300:4300 \
  -e SYNTH_API_KEY=my-secret-key \
  -v synth-data:/var/synth/data \
  git.itphx.ru/itphx/synth:0.13.10

Откройте http://localhost:4300 и введите ключ my-secret-key. Образ сам слушает 0.0.0.0:4300 и хранит данные в томе /var/synth/data.

Docker Compose

Готовый docker-compose.yml лежит в корне репозитория. По умолчанию он поднимает один сервис synth; остальные сценарии включаются профилями: ollama (локальные модели), postgres (хранилище в базе), all-in-one (сервер с инструментами и отдельный UI) и split (тонкий сервер плюс исполнители).

git clone https://gitverse.ru/itphx/synth && cd synth
echo "SYNTH_API_KEY=my-secret-key" > .env
docker compose up -d

Откройте http://localhost:4300 и введите ключ my-secret-key. Логи сервиса: docker compose logs -f synth.

Состав Compose

Сервис Профиль Порт Назначение
synth по умолчанию 4300 Платформа целиком: сервер + UI, файловое хранилище, том synth-data
synth-backend all-in-one 5000 Сервер с инструментами; команды исполняются в его процессе (inline)
synth-ui all-in-one, split 5002 Веб-интерфейс; проксирует API на synth-backend
synth-backend-split split 5000 Тонкий сервер без инструментов; команды уходят исполнителю
synth-executor split 5100 (внутри сети) Исполнитель команд, общий том synth-workspace
postgres postgres 5432 База для storage.backend: postgres, том postgres-data
ollama ollama 11434 Локальный сервер моделей, том ollama-data

Простой docker compose up -d поднимает только synth. Сервисы с профилем запускаются явно, например docker compose --profile all-in-one up -d или docker compose --profile split up -d; профиль postgres можно сочетать с любым из них.

Compose уже настроен на работу с Ollama внутри сети Docker: провайдер указывает на нативный http://ollama:11434 (без /v1) — так применяются num_ctx, think и инструменты.

Хранилище: файлы и PostgreSQL

По умолчанию состояние лежит в томе synth-data (файловое хранилище). Для командной работы его можно перевести в PostgreSQL:

cat >> .env <<'EOF'
SYNTH_STORAGE_BACKEND=postgres
SYNTH_POSTGRES_PASSWORD=change-me
EOF
docker compose --profile postgres up -d

В Compose хост базы — postgres, база и пользователь — synth. Параметры соединения задаются переменными SYNTH_POSTGRES_HOST, SYNTH_POSTGRES_PORT, SYNTH_POSTGRES_DATABASE, SYNTH_POSTGRES_USER. Пароль хранится только в SYNTH_POSTGRES_PASSWORD или в файле {каталог данных}/secrets/postgres-password.

Резервная копия — база и том

При postgres в томе остаются секреты, служебные метаданные и двоичные объекты: вложения, артефакты, содержимое скиллов, логи процессов. Поэтому архива каталога данных недостаточно — сохраняйте и базу, и том synth-data.

Подробнее о параметрах, деградации и переносе данных — Конфигурация.

Раздельное исполнение (split)

В split-топологии сервер не запускает команды сам: shell, git и поиск выполняются в отдельном контейнере-исполнителе. Управляющий слой остаётся тонким, а инструменты и их зависимости живут в исполнителе.

Подготовьте токен доверия — сервер читает его из файла, исполнитель из переменной окружения:

TOKEN=$(openssl rand -base64 32)
printf '%s' "$TOKEN" > .executor-token
printf 'SYNTH_EXECUTOR_TOKEN=%s\n' "$TOKEN" >> .env
docker compose --profile split up -d

Что поднимается:

  • synth-backend-split — сервер без инструментов, с SYNTH_EXECUTION_MODE=remote;
  • synth-executor — исполнитель на внутреннем порту 5100;
  • synth-ui — веб-интерфейс;
  • общий том synth-workspace — один и тот же путь в сервере и исполнителе.

Адрес исполнителя уже задан в Compose (http://synth-executor:5100). Токен сервер читает только из файла /etc/synth/executor/token, в который монтируется .executor-token. Если файла нет, Docker создаст на его месте каталог, и сервер не стартует.

Хранилище и общий том

Если управляющий слой работает в нескольких репликах, состояние должно лежать в PostgreSQL: файловые данные не разделяются между контейнерами. Рабочий том при нескольких исполнителях обязан поддерживать одновременную запись — в Kubernetes это класс ReadWriteMany.

Варианты образов (flavor)

Для сервера и исполнителя есть несколько вариантов образа — от slim до full. Набор инструментов в образе определяет, какие команды доступны агенту.

Flavor Что внутри Когда выбирать
slim только управляющий слой, без инструментов сервер в split-топологии
core базовый набор: shell, git, поиск обычная работа, all-in-one
dev сборка, компиляторы, клиенты БД разработка
devops инфраструктурные утилиты и диагностика эксплуатация
browser Chromium и Playwright браузерная автоматизация
full всё перечисленное универсальный исполнитель

Тонкий сервер публикуется как synth-backend:<версия> — без суффикса; для остальных вариантов тег выглядит как <версия>-<flavor>, например 0.13.10-core. Тег latest не публикуется.

Docker-сокет не монтируется

Ни один образ не получает доступ к docker.sock и не управляет соседними контейнерами на хосте. Для задач, которым нужен Docker, используйте внешний runner или отдельный исполнитель с нужными правами.

Переменные окружения

Переменная Обязательна Назначение
SYNTH_API_KEY да Ключ доступа к UI и API
SYNTH_STORAGE_BACKEND нет file (по умолчанию), memory или postgres
SYNTH_POSTGRES_PASSWORD для PostgreSQL Пароль базы; альтернатива — файл в каталоге секретов
SYNTH_EXECUTION_MODE нет inline (по умолчанию) или remote для split
SYNTH_EXECUTOR_TOKEN для split Токен доверия исполнителя; то же значение — в файле у сервера
SYNTH_PROVIDER_OLLAMA_URL для Ollama Нативный адрес Ollama (http://ollama:11434, без /v1)
SYNTH_PROVIDER_OLLAMA_MODEL для Ollama Модель, например qwen3.8:27b
SYNTH_PROVIDER_OLLAMA_TYPE для Ollama Тип провайдера — ollama
SYNTH_PROVIDER_<NAME>_API_KEY для внешних API Ключ провайдера

Провайдеры можно задать и через CLI/UI уже после запуска — подробности в Провайдеры и модели.

Ollama в Compose

Локальные модели одной командой

Запустите профиль и загрузите модель:

docker compose --profile ollama up -d
docker compose exec ollama ollama pull qwen3.8:27b

После этого Ollama доступна приложению по адресу http://ollama:11434 (нативный /api/chat), а наружу — на http://localhost:11434.

Контекстное окно (num_ctx) можно задать через Synth — флагом --num-ctx у synth config provider add, переменной SYNTH_PROVIDER_OLLAMA_NUM_CTX или полем num_ctx/numCtx в POST/PATCH /api/v2/providers (приоритет выше contextWindow модели). num_ctx передаётся в теле запроса к нативному /api/chat и применяется. Если базовый URL задан со старым суффиксом /v1, Synth снимет его и уйдёт на /api/chat, предупредив в лог; для OpenAI-совместимого пути нужен провайдер type: openai/generic. Дополнительно у сервиса ollama в docker-compose.yml выставлена переменная OLLAMA_CONTEXT_LENGTH (по умолчанию 262144 — серверный дефолт окна, окно 256k токенов).

Данные и тома

Данные Synth живут в именованном томе synth-data (внутри — /var/synth/data): сессии, проекты, провайдеры, модели, агенты, секреты. При storage.backend: postgres состояние переезжает в том postgres-data, а в synth-data остаются секреты, служебные метаданные и двоичные объекты. Модели Ollama — в томе ollama-data, общий рабочий каталог split-топологии — в томе synth-workspace.

  • docker compose down останавливает сервисы, но сохраняет тома.
  • docker compose down -v удаляет тома вместе с данными — используйте осознанно.
  • Список томов: docker volume ls.

Обновление версии

# Compose собирает образ из исходников репозитория
git pull
docker compose up -d --build
# для образа, запущенного вручную
docker pull git.itphx.ru/itphx/synth:0.13.10
docker rm -f synth
# затем запустите контейнер заново

Обновление не затрагивает тома, поэтому история и настройки сохраняются.

Фиксируйте версию

Тег latest не публикуется — в реестре остаются только версионные теги. Поэтому docker pull git.itphx.ru/itphx/synth без тега не сработает: указывайте конкретную версию, например :0.13.10.

Один контейнер — вся платформа

Базовый образ synth содержит и серверный движок, и собранный SPA. Отдельные контейнеры для UI или исполнителя нужны только в выбранной топологии all-in-one или split.

Что дальше