Appearance
Установка сервисов
Разворачивание prod-стека Unishift Platform из готовых образов. Установщик скачивает конфигурацию с storage.unishift.ru, сам генерирует все секреты, накатывает миграции и поднимает сервисы.
Требования
На сервере должны быть установлены:
| Компонент | Проверка |
|---|---|
| Docker Engine | docker info |
| Docker Compose v2 (плагин) | docker compose version |
| curl | curl --version |
| openssl | openssl version |
Пользователь, от которого запускается установка, должен иметь доступ к docker-демону (входить в группу docker либо запускать под root).
Установщик сам проверяет наличие утилит и останавливается с понятной ошибкой, если чего-то не хватает (например: нужна утилита 'docker', но она не найдена в PATH). На чистом VPS Docker ещё не установлен — сначала подготовьте сервер.
Подготовка чистого VPS
Инструкция рассчитана на свежий Linux-сервер (Ubuntu / Debian и аналоги). Нужны права root или sudo.
1. Базовые утилиты
curl и openssl обычно уже есть. Если нет:
bash
# Debian / Ubuntu
apt-get update
apt-get install -y curl openssl ca-certificates2. Установка Docker Engine и Compose v2
Официальный скрипт Docker ставит Engine и плагин Compose одной командой:
bash
curl -fsSL https://get.docker.com | shПроверка:
bash
docker info
docker compose versionДемон должен отвечать без ошибок. Если docker есть, а docker info жалуется на права — либо работайте под root, либо добавьте пользователя в группу и перелогиньтесь:
bash
usermod -aG docker "$USER"
# затем новый SSH-сеанс / newgrp dockerАльтернатива: пакеты репозитория Docker
Вместо get.docker.com можно поставить пакеты вручную по официальной инструкции для вашего дистрибутива. Нужны как минимум docker-ce, docker-ce-cli, containerd.io и docker-compose-plugin (команда docker compose, не отдельный docker-compose v1).
После проверки Docker переходите к быстрой установке ниже.
Быстрая установка
bash
curl -fsSL https://storage.unishift.ru/services/prod/install.sh | bashОдна команда: проверит окружение, скачает файлы, сгенерирует .env со свежими секретами, накатит миграции и поднимет стек.
На чистом VPS без Docker команда завершится ошибкой — сначала выполните подготовку сервера.
По умолчанию установка идёт в /opt/unishift. Переменные окружения нужно передавать в bash, который выполняет скрипт (не в curl):
bash
# Другой каталог
curl -fsSL https://storage.unishift.ru/services/prod/install.sh \
| INSTALL_DIR=/srv/unishift bash
# Браузер на другой машине, прямой доступ по IP (порты 18080 и 18100 открыты)
curl -fsSL https://storage.unishift.ru/services/prod/install.sh \
| PUBLIC_HOST=203.0.113.10 bash
# Домен за reverse proxy (https:// и wss:// на 443, без :18080/:18100)
curl -fsSL https://storage.unishift.ru/services/prod/install.sh \
| PUBLIC_HOST=app.example.com PUBLIC_SCHEME=https bashЕсли скрипт уже скачан:
bash
PUBLIC_HOST=203.0.113.10 ./install.sh| Переменная | Назначение | По умолчанию |
|---|---|---|
INSTALL_DIR | Куда установить | /opt/unishift |
BASE_URL | Откуда качать файлы | …/services/prod |
REGISTRY | Реестр образов | leggnom |
TAG | Тег образов | latest |
PUBLIC_HOST | Публичный IP/домен (для UI и WebSocket) | localhost |
PUBLIC_SCHEME | http или https | http |
WEB_BASE_URL | URL веб-клиента | из PUBLIC_* (см. ниже) |
CENTRIFUGO_WS_URL | WebSocket URL для браузера | из PUBLIC_* (см. ниже) |
CENTRIFUGO_ALLOWED_ORIGINS | Origin фронтенда (через пробел) | из PUBLIC_* (см. ниже) |
Как собираются URL, если их не задали явно:
PUBLIC_SCHEME | WEB_BASE_URL | CENTRIFUGO_WS_URL |
|---|---|---|
http (по умолчанию) | http://HOST:18080 | ws://HOST:18100/connection/websocket |
https | https://HOST | wss://HOST/connection/websocket |
Для https установщик предполагает reverse proxy на 443 (UI и Centrifugo на одном хосте). Если порты другие — задайте WEB_BASE_URL, CENTRIFUGO_WS_URL и CENTRIFUGO_ALLOWED_ORIGINS явно.
Что разворачивается
Полный набор модулей платформы плюс инфраструктура. Мониторинг (Prometheus и экспортеры) в prod не входит — он есть только в dev-стеке (devops/dev).
Модули: client, gateway, auth, spaces, documents, task-tracker, notifications, command-manager, scheduler, storage, env-manager, flow-manager, spark-grid, ai-router, nats-bridge.
Инфраструктура: postgres, nats, minio, centrifugo.
Стек запускается под именем проекта unishift-prod — сеть, тома и контейнеры изолированы от других окружений на той же машине.
Секреты
Установщик генерирует их однократно и складывает в INSTALL_DIR/.env с правами 600. Повторный запуск установщика их не трогает.
| Секрет | Назначение |
|---|---|
DB_PASSWORD | Пароль PostgreSQL |
JWT_SECRET | Подпись JWT и токенов Centrifugo |
SESSION_SECRET | Подпись сессий |
ENCRYPTION_KEY | Ключ шифрования Env Manager и SMTP-паролей Notifications (base64 от 32 байт) |
SERVICE_TOKEN | Межсервисные вызовы |
CENTRIFUGO_API_KEY | Серверный HTTP API Centrifugo |
MINIO_ROOT_PASSWORD | Пароль MinIO |
Сделайте резервную копию .env
Потеря ENCRYPTION_KEY делает нечитаемыми все значения, сохранённые в Env Manager. Смена DB_PASSWORD на уже инициализированной БД ломает доступ к данным. Скопируйте INSTALL_DIR/.env в надёжное место после установки.
Порты
Публикуются в диапазоне 1xxxx, чтобы не конфликтовать с другими окружениями.
| Сервис | Порт хоста |
|---|---|
| Веб-клиент | 18080 |
| Gateway | 18090 |
| Auth | 18091 |
| Spaces | 18092 |
| Documents | 18093 |
| Command Manager | 18094 |
| Scheduler | 18095 |
| Storage | 18096 |
| Env Manager | 18097 |
| Flow Manager | 18099 |
| Centrifugo | 18100 |
| AI Router | 18101 |
| Task Tracker | 18102 |
| Notifications | 18103 |
| Spark Grid | 18087 |
| PostgreSQL | 15432 |
| NATS (клиент / мониторинг) | 14222 / 18222 |
| MinIO (API / консоль) | 19010 / 19011 |
Значения меняются в .env через переменные *_PORT.
WebSocket и удалённый доступ
Браузер подключается к Centrifugo напрямую по адресу из CENTRIFUGO_WS_URL (gateway отдаёт его в /api/v1/services). Значение ws://localhost:18100/... работает только если UI открыт на той же машине, где крутится стек.
Если в консоли браузера:
text
WebSocket connection to 'ws://localhost:18100/connection/websocket' failedпоправьте .env на публичный адрес сервера и пересоздайте gateway + centrifugo:
bash
cd /opt/unishift
# пример для IP; для HTTPS/домена — wss:// и https:// origin
PUBLIC=203.0.113.10 # ← ваш IP или домен
# в .env:
# WEB_BASE_URL=http://$PUBLIC:18080
# CENTRIFUGO_WS_URL=ws://$PUBLIC:18100/connection/websocket
# CENTRIFUGO_ALLOWED_ORIGINS=http://$PUBLIC:18080
# SESSION_SECURE=false # для http; для https оставьте true
docker compose up -d gateway centrifugoПорт 18100 должен быть открыт на firewall (или Centrifugo должен быть за reverse proxy с wss://). CENTRIFUGO_ALLOWED_ORIGINS обязан совпадать с Origin страницы (схема + хост + порт UI).
Логирование
В prod по умолчанию LOG_LEVEL=error и LOG_FORMAT=text — в логи попадают только ошибки, обычным текстом (не JSON). Для отладки поднимите уровень в .env:
env
LOG_LEVEL=info # debug | info | warn | error | fatal | panic
LOG_FORMAT=json # text | jsonУправление
Все команды выполняются из каталога установки:
bash
cd /opt/unishift
docker compose ps # статус сервисов
docker compose logs -f # логи в реальном времени
docker compose restart auth # перезапуск одного сервиса
docker compose down # остановить стек (данные в томах сохраняются)
docker compose up -d # поднять сноваОбновление
Образы сервисов помечены тегом latest и pull_policy: always, поэтому каждый запуск подтягивает свежую сборку:
bash
cd /opt/unishift
docker compose up -d # перекачает latest и пересоздаст изменившиесяИнфраструктура (postgres, nats, minio, centrifugo) закреплена на конкретных версиях и не перекачивается.
Закрепить версию
Чтобы зафиксировать конкретную версию сервисов вместо latest, задайте TAG в .env и перезапустите:
env
TAG=0.0.3bash
docker compose up -dМиграции
Установщик накатывает их автоматически. Запустить вручную (например, после обновления образов с новыми миграциями):
bash
cd /opt/unishift
./migrate.shСкрипт поднимает postgres и minio, создаёт бакет и по очереди прогоняет миграции сервисов с БД (auth, spaces, documents, command-manager, scheduler, storage, env-manager, flow-manager, spark-grid, ai-router). Каждый прогон идёт через одноразовый контейнер и убирается за собой.
Переустановка с нуля
Тома с данными переживают down. Чтобы удалить и данные тоже:
bash
cd /opt/unishift
docker compose down -v # СНОСИТ тома: БД, файлы MinIO, данные NATSПосле этого при следующем up PostgreSQL заново отработает init-скрипты и создаст пустые базы — понадобится повторный ./migrate.sh.
Если миграции падают с postgres is unhealthy
Permission denied на /docker-entrypoint-initdb.d
В логах postgres:
text
ls: cannot open directory '/docker-entrypoint-initdb.d/': Permission deniedи статус Restarting (2). На VPS с umask 077 каталог postgres/init создаётся как 700 root:root, а процесс внутри контейнера идёт под uid 999 и не может его прочитать.
bash
cd /opt/unishift
chmod -R a+rX postgres centrifugo searxng
docker compose down -v
./migrate.sh
docker compose up -dHealthcheck не успевает при первом старте
Postgres при холодном старте создаёт десяток баз (init-скрипты). Если healthcheck слишком короткий, контейнер помечается unhealthy, и *-migrate падают с dependency failed to start.
Диагностика:
bash
cd /opt/unishift
docker compose ps
docker compose logs postgres --tail 80
docker inspect "$(docker compose ps -q postgres)" --format '{{json .State.Health}}'Восстановление (.env с секретами сохраняется, сносятся только тома):
bash
cd /opt/unishift
docker compose down -v
# подтянуть актуальные файлы со storage после публикации фиксов:
curl -fsSL -o docker-compose.yaml \
https://storage.unishift.ru/services/prod/docker-compose.yaml
curl -fsSL -o migrate.sh \
https://storage.unishift.ru/services/prod/migrate.sh
curl -fsSL -o install.sh \
https://storage.unishift.ru/services/prod/install.sh
chmod +x migrate.sh install.sh
./migrate.sh
docker compose up -d