Vrata
EnglishСоздать пространство

Назад: Разработчикам

Самостоятельный запуск

Здесь описан целевой порядок самостоятельного запуска беты Vrata 0.1.

До выхода v0.1.0 публичных образов в GHCR может не быть. Если вы работаете с исходниками, соберите образы локально с флагом --build.

Требования

Быстрый старт со сборкой из исходников

Из корня репозитория:

docker compose --env-file infra/docker/.env.selfhost.example -f infra/docker/compose.selfhost.yml config
docker compose --env-file infra/docker/.env.selfhost.example -f infra/docker/compose.selfhost.yml up -d --build

Smoke-проверки:

curl -fsS http://127.0.0.1:4000/health
curl -fsS http://127.0.0.1:4000/rooms/demo-room
curl -fsS http://127.0.0.1:4000/control-plane

Остановка после локальной оценки:

docker compose --env-file infra/docker/.env.selfhost.example -f infra/docker/compose.selfhost.yml down

Чтобы удалить постоянные данные тестового развёртывания:

docker compose --env-file infra/docker/.env.selfhost.example -f infra/docker/compose.selfhost.yml down -v

Запуск из образов выпуска

После выхода v0.1.0 скопируйте пример env-файла и выберите тег выпуска:

cp infra/docker/.env.selfhost.example infra/docker/.env.selfhost

Отредактируйте infra/docker/.env.selfhost: укажите настоящие секреты, домены и IMAGE_TAG.

Затем выполните:

docker compose --env-file infra/docker/.env.selfhost -f infra/docker/compose.selfhost.yml pull
docker compose --env-file infra/docker/.env.selfhost -f infra/docker/compose.selfhost.yml up -d

Обязательные настройки

Входящий в комплект файл compose запускает LiveKit в режиме --dev для быстрого старта беты 0.1, поэтому локальные значения по умолчанию — LIVEKIT_API_KEY=devkey и LIVEKIT_API_SECRET=secret. Прежде чем открывать развёртывание шире, чем для пробного использования, замените их защищённой конфигурацией LiveKit.

Удалённый браузер — экспериментальная функция, по умолчанию REMOTE_BROWSER_ENABLED=false. Чтобы включить его, задайте узкий список REMOTE_BROWSER_ALLOWED_ORIGINS и проверьте значения REMOTE_BROWSER_MAX_SESSIONS, REMOTE_BROWSER_SESSION_TTL_SECONDS, REMOTE_BROWSER_CPU_LIMIT, REMOTE_BROWSER_MEMORY_LIMIT и REMOTE_BROWSER_PIDS_LIMIT. Не открывайте порт исполнителя напрямую в недоверенные сети.

Постоянные данные

Файл compose для самостоятельного запуска хранит данные в томах Docker:

Перед обновлением делайте резервную копию этих томов. Используйте pnpm backup:compose, проверьте полученный манифест командой pnpm backup:validate и храните артефакты вне git. Подробнее — в docs/backup-restore.md и docs/upgrades.md.

Добавление пространства

В 0.1 минимальный порядок работает через API:

Структура пакета описана в docs/scene-bundle-contract.md.

Запуск в рабочей среде

Не открывайте доступ к самостоятельно развёрнутой установке с секретами из примера. Вариант с compose.selfhost.yml предназначен для локальной оценки и оставляет LiveKit в режиме --dev.

Для публичного сервера используйте профиль, безопасный для рабочей среды:

cp infra/docker/.env.production.example infra/docker/.env.production

Отредактируйте infra/docker/.env.production: замените каждое значение REPLACE_WITH_*, примерные имена хостов и публичные адреса. Публичные адреса, к которым обращается браузер, должны использовать https:// или wss://. Исключение — явная предстартовая проверка только на loopback с VRATA_ALLOW_INSECURE_PRODUCTION_URLS=true.

Перед запуском сервисов выполните предстартовую проверку:

node tools/validate-production-config.mjs --env-file infra/docker/.env.production

Проверьте модель compose:

docker compose --env-file infra/docker/.env.production -f infra/docker/compose.production.yml config

Запуск из образов, собранных из исходников:

docker compose --env-file infra/docker/.env.production -f infra/docker/compose.production.yml up -d --build

Или, после выхода v0.1.0, запуск из опубликованных образов выпуска:

docker compose --env-file infra/docker/.env.production -f infra/docker/compose.production.yml pull
docker compose --env-file infra/docker/.env.production -f infra/docker/compose.production.yml up -d

Smoke-проверки:

curl -fsS "$VRATA_APP_BASE_URL/health"
curl -fsS "$VRATA_APP_BASE_URL/rooms/demo-room"
curl -fsS "$VRATA_APP_BASE_URL/diagnostics"
curl -fsS "$CONTROL_PLANE_PUBLIC_URL"

Предстартовая проверка рабочей конфигурации не даёт запустить сервисы, если находит отсутствующие обязательные переменные, публичные адреса http:// / ws://, CORS с подстановочным знаком, режим dev-ролей через параметры запроса, секреты-заглушки, слабые секреты, повторяющиеся значения секретов, неверные публичный IP или порты LiveKit, а также хост в LIVEKIT_URL, не совпадающий с VRATA_LIVEKIT_DOMAIN. Диагностика содержит только имена переменных и коды причин; значения секретов выводиться не должны.

Сетевой профиль LiveKit / TURN

Профиль compose для рабочей среды запускает LiveKit не в режиме --dev, а с явной конфигурацией из LIVEKIT_CONFIG. Caddy завершает HTTPS для сигнального адреса LIVEKIT_URL, например wss://livekit.example.com, и перенаправляет трафик на livekit:7880.

Откройте входящие порты на сервере или в облачном файрволе:

Требования к DNS:

Варианты TURN/TLS:

Ответы API /health и /health/ready содержат несекретную диагностику развёртывания LiveKit в dependencies.livekitConfig: состояние TLS для сигнализации, настроенный хост, признак включения TURN, домен TURN, порты TURN и диапазон ретрансляции. Диагностика runtime, которую клиент отправляет в POST /api/rooms/:roomId/diagnostics, включает media.webrtc: состояния транспортов, состояние выбранной пары ICE-кандидатов, типы кандидатов и логические флаги доступности и использования ретрансляции TURN. Снимок runtime намеренно не содержит исходных адресов и портов ICE-кандидатов.

Когда публичные DNS и HTTPS настроены, откройте в браузере $VRATA_APP_BASE_URL/diagnostics?roomId=demo-room&autorun=1. Добавьте skipMic=1, если нужно обойтись без запроса права на микрофон, но сохранить проверки API, WSS сервиса состояния комнаты, хранилища, LiveKit и WebRTC/TURN. JSON-отчёт прикладывайте к обращениям в поддержку: значения параметров, похожие на токены, и ключи, похожие на секреты, в нём скрыты.

В рабочей среде POST /api/tokens/media и POST /api/tokens/remote-browser-media возвращают livekit_config_invalid, если адрес, ключ или секрет LiveKit не заданы, небезопасны или всё ещё совпадают с учётными данными для разработки.

Откат для этого профиля затрагивает только метаданные и конфигурацию: верните предыдущий .env.production и тег образа через pnpm rollback:compose, затем выполните smoke-проверку адреса приложения. Если проблема в самом профиле рабочей среды, остановите его и вернитесь к ранее использованному задокументированному файлу compose. Восстановление базы данных на момент времени здесь не предусмотрено.

Обновления и откат

Здесь описаны целевые правила обновления самостоятельно развёрнутых установок Vrata 0.1.

Правила

Резервная копия перед обновлением

Перед сменой тегов образов создайте и проверьте резервную копию compose-стека:

pnpm backup:compose -- --env-file infra/docker/.env.selfhost --compose-file infra/docker/compose.selfhost.yml --output-dir backups
pnpm backup:validate -- --backup-dir backups/vrata-<timestamp>-<image-tag>

Команда резервного копирования выгружает Postgres, объекты бакетов MinIO, опись объектов, метаданные политик бакетов (если они есть), метаданные образов и манифест с контрольными суммами. Восстановление и действия при аварии описаны в docs/backup-restore.md.

Обновление

Отредактируйте infra/docker/.env.selfhost:

IMAGE_TAG=0.1.1

Затем выполните:

docker compose --env-file infra/docker/.env.selfhost -f infra/docker/compose.selfhost.yml pull
docker compose --env-file infra/docker/.env.selfhost -f infra/docker/compose.selfhost.yml up -d

Smoke-проверки:

curl -fsS "$VRATA_APP_BASE_URL/health"
curl -fsS "$VRATA_APP_BASE_URL/rooms/demo-room"
curl -fsS "$VRATA_APP_BASE_URL/control-plane"

Откат

Если smoke-проверка не прошла, верните в IMAGE_TAG предыдущий заведомо рабочий тег и перезапустите сервисы:

pnpm rollback:compose -- \
  --previous-image-tag 0.1.0 \
  --env-file infra/docker/.env.selfhost \
  --compose-file infra/docker/compose.selfhost.yml \
  --smoke-base-url "$VRATA_APP_BASE_URL" \
  --confirm-rollback

Не запускайте down -v при откате, если только вы не хотите намеренно удалить данные.

Состояние миграций

Сейчас схема создаётся при первом запуске: слой хранения API идемпотентно создаёт таблицы и столбцы. Отдельный механизм запуска миграций запланирован; без него Vrata не может давать более строгих гарантий обновления в рабочей среде.

Резервное копирование, восстановление и откат

Профили compose Vrata для самостоятельного запуска и рабочей среды хранят постоянное состояние в именованных томах Docker. Скрипт tools/backup-restore.mjs даёт оператору всё нужное, чтобы выгрузить это состояние, проверить артефакты резервной копии, восстановить их, откатить теги образов без удаления томов и выполнить smoke-проверки.

Что входит в резервную копию

По умолчанию резервные копии записываются в backups/. Этот каталог исключён из git: артефакты резервных копий могут содержать закрытые метаданные комнат и ассеты сцен.

Создание резервной копии

Из корня репозитория:

pnpm backup:compose -- --env-file infra/docker/.env.selfhost --compose-file infra/docker/compose.selfhost.yml --output-dir backups

Для профиля рабочей среды используйте infra/docker/.env.production и infra/docker/compose.production.yml.

Команда завершается с ненулевым кодом, если не удалось снять дамп Postgres, зеркалировать MinIO, сделать снимок образов или записать манифест. В журнал попадают только пути и стабильные коды ошибок; значения секретов из env-файла вычищаются из stderr команд.

Проверка резервной копии

pnpm backup:validate -- --backup-dir backups/vrata-<timestamp>-<image-tag>

Что проверяется:

Повреждённый или неполный манифест приводит к ненулевому коду завершения ещё до начала восстановления.

Восстановление

Восстановление перезаписывает состояние целевого развёртывания: SQL-дамп применяется к Postgres, а сохранённый набор объектов зеркалируется обратно в MinIO с флагом --remove.

Не запускайте восстановление на рабочем сервере, если вы явно не выбрали эту резервную копию точкой восстановления.

pnpm restore:compose -- \
  --backup-dir backups/vrata-<timestamp>-<image-tag> \
  --env-file infra/docker/.env.selfhost \
  --compose-file infra/docker/compose.selfhost.yml \
  --smoke-base-url http://127.0.0.1:4000 \
  --smoke-room-id demo-room \
  --confirm-restore

Восстановление всегда начинается с проверки манифеста. После применения дампа и объектов выполняются smoke-проверки /health, /rooms/:roomId, /api/rooms/:roomId/manifest и адреса пакета сцены из манифеста, если он указан.

Откат тега образа

Откат затрагивает только конфигурацию и образы. Перед правкой env-файла команда проверяет целевой тег и адрес для smoke-проверки, затем обновляет IMAGE_TAG, скачивает образы сервисов приложения и выполняет docker compose up -d --no-build. Она не запускает docker compose down -v и не удаляет тома Postgres и MinIO.

pnpm rollback:compose -- \
  --previous-image-tag 0.1.0 \
  --env-file infra/docker/.env.selfhost \
  --compose-file infra/docker/compose.selfhost.yml \
  --smoke-base-url http://127.0.0.1:4000 \
  --smoke-room-id demo-room \
  --confirm-rollback

Перед сменой IMAGE_TAG предыдущий env-файл копируется в backups/rollback-env/. latest как цель отката отклоняется: используйте явный тег SemVer или неизменяемый тег SHA.

Только smoke-проверка

pnpm smoke:compose -- --smoke-base-url http://127.0.0.1:4000 --smoke-room-id demo-room

Запускайте её после ручного восстановления или обслуживания хранилища.

Срок хранения

Пробный прогон удаления старых резервных копий:

pnpm backup:prune -- --output-dir backups --retention-days 14

Удаление:

pnpm backup:prune -- --output-dir backups --retention-days 14 --confirm-prune

Срок хранения по умолчанию можно задать в VRATA_BACKUP_RETENTION_DAYS. Команда очистки рассматривает только каталоги, имена которых начинаются с vrata-. Перед удалением копии она проверяет контрольные суммы и всегда оставляет как минимум две более новые проверенные резервные копии. Неполные или повреждённые копии сохраняются для диагностики и не считаются точками восстановления.

Действия при аварии

  1. Если возможно, остановите запись в пострадавшее развёртывание.
  2. Выберите самую свежую проверенную резервную копию, манифест которой проходит pnpm backup:validate.
  3. Восстановите её с --confirm-restore и доступным --smoke-base-url.
  4. Если проблема не в данных, а в образе приложения, выполните pnpm rollback:compose с предыдущим явным тегом образа.
  5. Выполните smoke-команду и запишите в заметки об инциденте каталог резервной копии, восстановленный IMAGE_TAG, коммит git и результат smoke-проверки.

Ограничения

Источник: docs/self-hosting.md, docs/upgrades.md, docs/backup-restore.md в vrata-labs/platform на ревизии 380b2e7ff1dd, лицензия Apache-2.0. GitHub