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

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

Требования

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

Запуск из cmd/marv

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

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).

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

Через конфигурацию (рекомендуется)

Начиная с текущей версии, модули загружаются из конфига — это позволяет использовать один бинарник для разных проектов, управляя набором модулей только через config.yml:

app:
  modules:
    - user
    - world
    - transaction
    - message
    - event
    - stream
    - rival
    - abtest
    - remote_config
    - product
    - ads
    - alert
    - traffic_flow
    - bots
    - cron_task
    - merchant
    - platform
    - acp_user
    - system

Модули user, system, cron_task, merchant, platform и acp_user создаются движком по умолчанию. Остальные подключаются только если указаны в app.modules.

Управление роутерами через конфиг

Группы HTTP-маршрутов включаются/выключаются через app.routes (по умолчанию все выключены, кроме явно указанных):

app:
  routes:
    v1: false      # V1 API (deprecated)
    v2: true       # V2 API (основной)
    acp: true      # Admin Control Panel
    ext: true      # External webhooks

Доступные модули

Описание	Тип в конфиге
A/B тесты	abtest
Боты (Telegram)	bots
Ивенты/события	event
Система сообщений	message
Каталог продуктов	product
Удалённые конфиги	remote_config
Соперники	rival
Стримы	stream
Реклама	ads
Центр оповещений	alert
Traffic Flow	traffic_flow
Транзакции	transaction
Миры	world

Модули подключаются через конфиг app.modules (рекомендуется) или программно. При дублировании модулей Manager.Create() идемпотентен.

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

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

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

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:
      enabled: true
      rps: 100        # запросов в секунду на IP
      burst: 200      # максимальный burst

При превышении возвращается HTTP 429 Too Many Requests. Старые записи автоматически очищаются.

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

Таймауты настраиваются через конфиг app.http.timeouts:

app:
  http:
    timeouts:
      request: 30s
      dial: 20s
      keep_alive: 20s
      tls_handshake: 10s
      response_header: 10s
      handler: 30s

Метрики доступны на /acp/system/metrics (см. наблюдаемость).

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

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

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

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

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

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

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

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

С CLI-опциями:

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

• Авторизация: заголовок X-Api-Access-Token (Google OAuth)
• Доступы по ролям контроллеров задаются мидлварой WithControllerRole(...)

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

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