MARV

Appearance

Настройка и запуск сервера ​

Этот гайд описывает быстрый старт и ключевые опции инициализации через pkg/engine.

Требования ​

  • Go 1.26+
  • PostgreSQL и Redis (или совместимые) при включённых соответствующих модулях
  • Конфигурационные файлы (см. config/config.example.yml и docs/config/overview.md)

Запуск из cmd/marv ​

Сборка и запуск:

bash
go run ./cmd/marv \
  --stdout \
  --log-level=info \
  --host=0.0.0.0 --port=8080

Опции:

  • --stdout - писать логи в stdout (ранний логгер)
  • --log-level - ранний уровень логирования (trace|debug|info|warn|error)
  • --config-dir - базовый каталог для конфигов (по умолчанию: каталог бинарника или корень проекта при go run)
  • --noauth - отключить проверку сигнатур (для локальной отладки)
  • --nocors - отключить CORS (для локальной отладки)
  • --host, --port - переопределить адрес/порт HTTP-сервера

Конфиги ищутся в <config-dir>/ (например config.debug.yml, bots.debug.json).

Включение модулей ​

Модули и роутеры настраиваются через конфиг — см. Основной конфиг, секции app.modules и app.routes.

Список доступных модулей и их типы описаны там же.

Валидация конфигурации ​

Конфиг автоматически валидируется по JSON-схеме (config.schema.json) при загрузке. Очистка кэша marv:cache:* при старте настраивается через app.cache_clear.patterns.

Сетевой адрес и флаги безопасности ​

go
engine.WithServerAddr(host, port),
engine.WithDisableAuth(), // отключает проверку токена платформы
engine.WithEnableCORS(), // включает CORS middleware (только для dev/тестов)

Используйте только в dev-окружении.

Rate Limiting ​

Встроенный rate limiter (in-memory token bucket, per-IP). Настройки — см. Основной конфиг, секция app.security.rate_limit. При превышении возвращается HTTP 429.

HTTP клиент и метрики ​

Таймауты HTTP-клиента — см. Основной конфиг, секция app.http.timeouts. Метрики доступны на /acp/system/metrics (см. наблюдаемость).

Опции раннего запуска (Bootstrap) ​

Эти опции применяются до инициализации конфигов/БД/кэша и управляют ранним логированием:

go
engine.BootLogStdout(true),         // логировать в stdout до инициализации основного логгера
engine.BootLogLevel("info"),        // уровень раннего логгера: trace|debug|info|warn|error

Двухфазный запуск (порядок применения опций) ​

Движок применяет опции в два этапа:

  • Bootstrap-фаза: собираются и применяются только «boot»-части опций (BootLogStdout, BootLogLevel). Это позволяет видеть ранние логи до загрузки конфигов и инфраструктуры.
  • Runtime-фаза: после загрузки конфигов и инициализации инфраструктуры (логгер, БД, кэш, контейнер, фабрики платформ) применяются остальные опции (модули, HTTP‑таймауты, метрики, перезапись параметров конфигурации, toggles).

Итого (config-driven подход, рекомендуется):

go
e, err := engine.New(
  engine.BootLogStdout(true),
  engine.BootLogLevel("debug"),
)
// Модули, роуты, таймауты, rate limiting — всё из config.yml

С CLI-опциями:

go
e, err := engine.New(
  engine.BootLogStdout(true),
  engine.BootLogLevel("debug"),
  engine.WithServerAddr("0.0.0.0", 8080),
  engine.WithDisableAuth(),
)

Конфигурация ​

См.:

  • config/config.example.yml - пример
  • docs/config/main.md - параметры (infrastructure.platforms.*, infrastructure.cloudflare.*, domain.*, app.*, observability.*)

Минимум для запуска:

  • Блок server (host/port)
  • Подключения database/cache (если задействованы)
  • platforms - хотя бы одна платформа для клиентских запросов (V1/V2)
  • (опционально) bots, products.json

Профиль ACP ​

  • Авторизация: заголовок Authorization: Bearer <Google-OAuth-JWT>
  • Доступы по ролям контроллеров задаются мидлварой WithControllerRole(...)

Завершение работы ​

Пример ловит os.Interrupt и корректно вызывает engine.Stop(). Для контейнеров (Docker/K8s) убедитесь, что посылаете SIGTERM и настроены graceful shutdown таймауты прокси/оркестратора.