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

Wippy настраивается через файлы .wippy.yaml. Все параметры имеют разумные значения по умолчанию.

Любое значение ниже можно переопределить при запуске с помощью wippy run --set section.path=value (можно указывать несколько раз, имеет приоритет над файлом). Чтобы переопределить отдельные записи реестра, а не эти секции конфигурации, используйте секцию override: или флаг -o — см. Переопределение записей.

Композиция конфигурации {#config-composition}

--config можно повторять; файлы компонуются слева направо по одной и той же схеме:

wippy run --config .wippy.yaml --config .wippy.local.yaml

• Более поздние файлы переопределяют совпадающие значения и сохраняют всё остальное.
• Каждый явно указанный файл должен существовать. Без --config стандартный .wippy.yaml необязателен.
• Первый файл задаёт директорию, относительно которой разрешаются относительные пути.
• Имена файлов не несут зарезервированного смысла; кроме файла по умолчанию ничего не обнаруживается автоматически.

Конфигурация применяется по порядку: композиция файлов, затем выбор --profile, затем переопределения --set. Для приложений, запускаемых из pack-файлов, упакованные значения по умолчанию среды выполнения лежат ниже всего перечисленного (см. Публикация значений по умолчанию среды выполнения).

Профили {#profiles}

Файл конфигурации может объявлять именованные оверлеи в секции profiles:. Тело каждого профиля повторяет обычные секции конфигурации; выбор через --profile <name> накладывает эти значения на объединённую базовую конфигурацию:

version: "1.0"

vars:
  port: 8085

override:
  app:db:kind: db.sql.sqlite

disable:
  namespaces: ["legacy.**"]

profiles:
  pg:
    vars:
      port: 18085
    override:
      app:db:kind: db.sql.postgres
    disable:
      namespaces.add: ["experimental.**"]

wippy run --profile pg

• --profile можно повторять; профили компонуются слева направо, после композиции файлов и перед --set. Неизвестное имя — ошибка.
• Значения объединяются по каждому листу (последняя запись выигрывает). Сама секция profiles: вырезается из итоговой конфигурации.
• Секция disable поддерживает операции над списками внутри профилей — namespaces.add, namespaces.remove, entries.add, entries.remove — так что профиль может корректировать базовый список вместо его замены.
• Ссылки ${name} интерполируются из объединённой секции vars:. Ссылки на переменные окружения ОС внутри vars профилей не допускаются; используйте ${env:NAME} в базовой конфигурации, разрешаемый при загрузке файла.

wippy run, test и pack принимают --profile; run list, install, update, lint и registry также принимают его для профилей рабочего пространства (вместе с --set). Приложения могут поставлять профили внутри pack-файлов — см. Публикация профилей.

Logger

Управляет кодировщиком zap-логгера. CLI-флаги (-v, -c, -s) переопределяют уровень/вывод; единственная опция, управляемая через yaml, — это кодировка.

logger:
  encoding: json

Log Manager

Управляет маршрутизацией логов среды выполнения. Вывод в консоль настраивается через флаги CLI (-v, -c, -s).

logmanager:
  propagate_downstream: true
  stream_to_events: false

См.: Модуль Logger

Profiler

HTTP-сервер Go pprof для профилирования CPU и памяти. Включается флагом -p или через конфиг.

profiler:
  enabled: true
  address: "localhost:6060"

Доступен по адресу http://localhost:6060/debug/pprof/

Security

Глобальное поведение безопасности. Отдельные политики определяются как записи security.policy.

security:
  strict_mode: false

См.: Система безопасности, Модуль Security

Registry

Хранилище записей и история версий. Реестр содержит все конфигурационные записи.

registry:
  history_type: sqlite
  history_path: /var/lib/wippy/registry.db

registry:
  history_type: postgres
  history_dsn: ${env:WIPPY_REGISTRY_HISTORY_DSN}
  history_schema: wippy_registry

См.: Концепция реестра, Модуль Registry

Artifact

Корень вывода для материализованных артефактов времени сборки.

artifact:
  materialization_root: build/wippy

См.: Артефакты времени сборки

Workspace

Локальные замены модулей, ключом служит org/module. Значения — каталоги; относительные пути разрешаются относительно каталога первого файла --config, а null отключает замену, унаследованную из более раннего слоя конфигурации или профиля.

workspace:
  replacements:
    acme/http: ../local-http
    acme/sql: null

Замены никогда не записываются в wippy.lock. См. Локальная разработка с заменами.

Relay

Маршрутизация сообщений между процессами на разных нодах.

relay:
  node_name: worker-1

См.: Модель процессов

Supervisor

Управление жизненным циклом сервисов. Контролирует внутренний управляющий почтовый ящик супервизора, используемый для диспетчеризации событий жизненного цикла.

supervisor:
  host:
    buffer_size: 2048
    worker_count: 32

См.: Супервизия

Lua Runtime

Кэширование Lua VM и вычисление выражений.

lua:
  cache:
    enabled: true
    dir: .cache/lua
  type_system:
    enabled: true

См.: Обзор Lua

Scheduler

Разделение ядер для среды исполнения WASM. Когда включено, reserved_cores CPU отводятся под выполнение WASM, а остальные обслуживают планировщик акторов; некорректное разделение (например, зарезервированных ядер больше, чем доступно) логируется и игнорируется.

scheduler:
  wasm_isolation:
    enabled: true
    reserved_cores: 2

Finder

Кэширование поиска по реестру. Используется внутренне для поиска записей.

finder:
  query_cache_size: 2000

OpenTelemetry

Распределённая трассировка и экспорт метрик через OTLP.

otel:
  enabled: true
  endpoint: "http://jaeger:4318"
  traces_enabled: true
  process:
    trace_lifecycle: true

Стандартные переменные окружения OTEL (OTEL_SDK_DISABLED, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_INSECURE, OTEL_SERVICE_NAME, OTEL_SERVICE_VERSION, OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG, OTEL_PROPAGATORS) переопределяют соответствующие поля.

См.: Наблюдаемость

Shutdown

Корректное завершение работы.

shutdown:
  timeout: 60s

Metrics

Буфер сбора внутренних метрик.

metrics:
  buffer:
    size: 20000
  interceptor:
    enabled: true

См.: Модуль Metrics, Наблюдаемость

Prometheus

Эндпоинт метрик Prometheus.

prometheus:
  enabled: true
  address: "0.0.0.0:9090"

Открывает эндпоинт /metrics для Prometheus, а также /livez.

См.: Наблюдаемость

Cluster

Многонодовая кластеризация: gossip-обнаружение участников и ограниченное ядро консенсуса Raft. Архитектуру и операционную модель см. в Руководстве по кластеру; этот раздел — справочник по ключам конфигурации.

Верхний уровень

Membership (gossip)

SWIM gossip через memberlist. Используется для обнаружения нод, обнаружения сбоев и распространения метаданных.

Gossip-секрет обязателен. Задайте membership.secret_key или membership.secret_file (при обоих побеждает файл); без того и другого компонент кластера не стартует. Значение кодируется в base64.

Четыре ключа проб наследуют значения memberlist по умолчанию для локальной сети, если не заданы; повышайте их для каналов с высокой задержкой (например, probe_interval: 2s, probe_timeout: 500ms, suspicion_mult: 5).

Internode (транспорт)

TCP-меш, переносящий relay- и Raft-трафик между нодами. Raft работает по этому мешу через internode request/reply; отдельного Raft-порта нет.

advertise_addr/advertise_port публикуют дополнительный эндпоинт в метаданных ноды, при этом эндпоинт привязки продолжает объявляться без изменений — кластеры со смешанными версиями сохраняют связность во время rolling-обновления.

Идентичность internode обязательна всегда, когда включена кластеризация. identity_key и identity_key_file взаимоисключающи, и один из них должен присутствовать; значение декодируется (стандартный или raw base64) либо в 32-байтный seed ed25519, либо в 64-байтный приватный ключ ed25519. trusted_peer_keys сопоставляет каждому имени ноды её 32-байтный публичный ключ ed25519 и должен содержать запись для локального cluster.name, значение которой совпадает с локальной идентичностью, — иначе запуск завершается ошибкой. См. Руководство по кластеру.

Raft (консенсус)

Ограниченный Raft. Состояние Raft по умолчанию долговечно на ФС, хранится под raft.data_dir (по умолчанию ~/.wippy/store); перезапущенная нода всё равно переприсоединяется к кворуму от пиров. Записи store.kv.raft реплицируются через него. Bootstrap управляется gossip (по образцу Consul/Nomad bootstrap_expect).

Одна нода (разработка) — кластеризация включена, нода сразу bootstrap-ит себя:

cluster:
  enabled: true
  name: dev
  membership:
    secret_key: "d2lwcHktZG9jcy1nb3NzaXAtc2VjcmV0LTMyYnl0ZXM="
  internode:
    identity_key: "d2lwcHktZG9jcy1kZXYtbm9kZS1leGFtcGxlc2VlZCE="
    trusted_peer_keys:
      dev: "rNqImcjOzef28dzvma80mSrCW1px5LBAc5TbaYqAgm0="
  raft:
    bootstrap_expect: 1

Трёхнодовый voting-кластер — каждая нода перечисляет остальные как seed и ждёт все три перед формированием кворума. Каждая нода несёт одну и ту же карту trusted_peer_keys и собственный приватный ключ:

cluster:
  enabled: true
  name: node-1
  failure_domain: us-east-1a
  membership:
    bind_port: 7946
    join_addrs: "node-2:7946,node-3:7946"
    secret_file: /etc/wippy/cluster.key
  internode:
    identity_key_file: /etc/wippy/node-1.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
      node-3: "QfP0fgllbj4s95VAztTORhy3bv9mst1l0lwuUNvO/hE="
  raft:
    bootstrap_expect: 3
    max_voters: 5

Только gossip-клиент — присоединяется к кластеру для именования/обмена сообщениями, но никогда не запускает Raft. Ему тоже нужна собственная идентичность, и он должен присутствовать в доверенной карте каждой ноды:

cluster:
  enabled: true
  name: edge-7
  membership:
    join_addrs: "node-1:7946,node-2:7946"
    secret_file: /etc/wippy/cluster.key
  internode:
    identity_key_file: /etc/wippy/edge-7.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
      node-3: "QfP0fgllbj4s95VAztTORhy3bv9mst1l0lwuUNvO/hE="
      edge-7: "7lzP4jBAkC3P+0jq4vtMsC45571BlVXk3mSlOD/Z0SA="
  raft:
    role: client

LSP

Сервер Language Server Protocol для интеграции с редакторами.

lsp:
  enabled: true
  address: ":7777"
  http_enabled: true

См.: LSP

Сетевой сервис

Менеджер оверлейных сетей (драйверы SOCKS5, I2P, Tailscale).

network_service:
  state_dir: /var/lib/wippy/net
  default_network: app:tailscale

См.: Сетевые оверлеи

HTTP Dispatcher

Настройка общего пула HTTP-клиентов, используемого HTTP-диспетчированными функциями и исходящими запросами.

dispatcher:
  http:
    timeout: 30s
    max_idle_per_host: 32

Модули

Клиент реестра модулей, используемый wippy install/update.

modules:
  registry_url: https://internal-registry.example.com

Расширения

Нативные Go-плагины, загружаемые при старте (только Unix).

extensions:
  enabled: true
  paths:
    - ./extensions/myplugin.so

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

TLS между узлами

Включите взаимный TLS для TCP-mesh между узлами через cluster.internode.tls. Он также защищает передаваемый по этой mesh трафик relay и Raft. Добавьте в существующую конфигурацию кластера:

cluster:
  internode:
    tls:
      enabled: true
      cert_file: /etc/wippy/node.crt
      key_file: /etc/wippy/node.key
      ca_file: /etc/wippy/cluster-ca.pem

По умолчанию TLS отключён. При enabled: true обязательны все три непустых пути: PEM-сертификат, соответствующий закрытый ключ и PEM-набор CA для проверки сертификатов сервера и клиента. Минимальная версия — TLS 1.2. Настройте совместимые сертификаты и доверенные корни на всех соединяющихся узлах. Идентификатор ed25519 и карта доверенных ключей узлов по-прежнему обязательны.

Неизвестные настройки TLS, неверные типы, отсутствующие или некорректные учётные данные, некорректные наборы CA и пути без enabled: true приводят к ошибке запуска. Некорректная явная конфигурация никогда не вызывает скрытый переход к незашифрованному соединению.

См. также

• Справочник CLI — параметры командной строки
• Руководство по кластеру — архитектура и операции кластеризации
• Типы записей — все типы записей
• Наблюдаемость — логирование, метрики, трассировка