homer eleven

100% открытая телеком-наблюдаемость с 2011 года

homer — это монолитный сервер захвата HEP и API всё-в-одном, лежащий в основе дата-лейка Homer 11.x

Возможности

• Приложение «всё-в-одном» (Writer, Reader, Coordinator, Compactor, API)
• Современная кодовая база на golang для X64/ARM64 под Linux/MacOS
• Работает на DuckDB 1.5 и Apache Arrow/IPC/Parquet
• Архитектура дата-лейка на основе каталога DuckLake и локального/объектного хранилища
• Сквозной колоночный дизайн OTLP с выполнением запросов по требованию
• Линейное масштабирование запросов поверх общего каталога/пула объектного хранилища
• Гибкая схема для растущего числа задач и протоколов
• Обратная совместимость со всеми агентами HEPv3
• Опциональный сборщик SIP QoS VQRTCP (application/vq-rtcpxr → DuckLake + UI QoS транзакций)
• Опциональная сигнальная SRS SIPREC (захват метаданных по RFC 7865/7866)
• Простота сопровождения, эксплуатации и масштабирования (вплоть до нуля!)
• Cloud Native-дизайн для K8s и стандартных развёртываний
• Встроенный пользовательский интерфейс для людей
• Поддержка MCP и дружелюбный к LLM/агентам дизайн (украдите наши скучные задачи)

Архитектура

Homer использует модульную архитектуру с четырьмя основными компонентами:

┌─────────────────────────────────────────────────────────────────────────────┐
│                           Homer Core                                        │
│                                                                             │
│  ┌─────────────┐   ┌─────────────┐   ┌──────────┐   ┌─────────────────┐     │
│  │   Ingest    │   │   Storage   │   │   Node   │   │   Coordinator   │     │
│  │  (HEP recv) │──▶│  (DuckLake) │──▶│ gRPC/HTTP│──▶│    (REST API)   │     │
│  └─────────────┘   └─────────────┘   └──────────┘   └─────────────────┘     │
│   UDP/TCP/HTTP      Parquet+S3     Airport :50051     HTTP :8080            │
│                                    FlightSQL :50055  (opt. proxy :32010)    │
└─────────────────────────────────────────────────────────────────────────────┘

Модули

Быстрый старт

Варианты установки

• Скачайте релиз и установите пакет homer для вашей ОС/архитектуры
• Используйте официальные docker-сборки и примеры compose
• Соберите свой релиз локально (читайте дальше)

Развёртывание «всё-в-одном»

{
  "ingest": {
    "enable": true,
    "udp": { "enable": true, "port": 9060 },
    "tcp": { "enable": true, "port": 9061 },
    "http": { "enable": true, "port": 9080 }
  },
  "storage": {
    "enable": true,
    "ducklake": {
      "catalog_path": "/data/homer/homer_catalog.sqlite",
      "data_path": "/data/homer/parquet"
    }
  },
  "node": {
    "enable": true,
    "flight_server": { "port": 50051 },
    "ducklake": {
      "lake_name": "homer_lake",
      "volumes": [
        {
          "name": "default",
          "type": "local",
          "catalog_type": "sqlite",
          "catalog_path": "/data/homer/homer_catalog.sqlite",
          "path": "/data/homer/parquet"
        }
      ]
    }
  },
  "coordinator": {
    "enable": true,
    "http_server": { "port": 8080 }
  }
}

Дополнительные варианты хранения описаны в доступной документации STORAGE POLICIES

Опционально: поддержка VQRTCP-коллектора и SIPREC

Обе функции отключены по умолчанию и требуют модуль writer (DuckLake). Включите их в секции ingest файла homer.json:

{
  "ingest": {
    "vqrtcp": {
      "enable": true,
      "bind_ip": "0.0.0.0",
      "sip_port": 5063,
      "transports": ["udp", "tcp"],
      "methods": ["PUBLISH", "MESSAGE"],
      "reply_200": true
    },
    "siprec": {
      "enable": true,
      "bind_ip": "0.0.0.0",
      "advertise_ip": "203.0.113.10",
      "sip_port": 5062,
      "transports": ["udp", "tcp"],
      "require_siprec": true
    }
  }
}

Направьте ваш SBC или медиашлюз на SIP-порт VQRTCP для передачи отчётов application/vq-rtcpxr. Направьте SIPREC Session Recording Client (SRC) на порт SIPREC для записи сигнализации и rs-metadata.

Подробности о форматах, корреляции и настройке см. в docs/VQRTCP.md и docs/SIPREC.md.

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

# Build
make

# Run as server (default mode)
./homer --config-path /etc/homer/homer.json

# With debug logging
./homer --config-path /etc/homer/homer.json --log-level debug

Контейнер для разработки

О рабочем процессе разработки внутри контейнера (сборка + тесты) читайте в docs/DEVCONTAINER.md.

Подкоманды

Homer использует CLI на основе подкоманд. Запуск homer без аргументов запускает сервер.

homer                         Run the server (default)
homer search [flags]          Search Homer data via coordinator API
homer cli [flags]             Interactive DuckLake SQL shell
homer system [flags]          System operations (compaction, extensions, reload)
homer wizard [flags]          Interactive config generator wizard
homer config show [flags]     Print effective config (file + env + defaults)
homer mcp [flags]             Start MCP stdio server
homer version                 Show version
homer help                    Show full help with all flags

Режим сервера (по умолчанию)

homer --config-path /etc/homer/homer.json
homer --config-path /etc/homer/homer.json --log-level debug --syslog-disable

Поиск (через coordinator API)

Ищите данные Homer из командной строки с выводом в виде таблицы, вертикального списка, CSV, JSON, графика, call flow или PCAP (только SIP; используйте --format pcap с -o / --output).

# Basic SIP search (last hour)
homer search --host 10.0.0.1:8081 --user admin --pass secret

# Search INVITE messages with call flow diagram
homer search --host 10.0.0.1:8081 --method INVITE --format callflow

# Export SIP messages to a pcap file (same framing as API /transactions/export/pcap)
homer search --host 10.0.0.1:8081 --call-id "abc123@host" --format pcap -o /tmp/call.pcap

# Search by Call-ID
homer search --host 10.0.0.1:8081 --call-id "abc123@host" --format vertical

# Post-filter: only INVITEs and BYEs, exclude provisional responses
homer search --host 10.0.0.1:8081 --grep "INVITE,BYE" --exclude "100,183"

# Interactive TUI mode
homer search --host 10.0.0.1:8081 --interactive

Полную документацию и примеры см. в docs/SEARCH.md.

CLI (SQL-оболочка DuckLake)

Интерактивная SQL-оболочка для прямых запросов к DuckLake:

# Start interactive CLI
homer cli --config-path /etc/homer/homer.json

# Execute single query and exit
homer cli --config-path /etc/homer/homer.json --query "SELECT COUNT(*) FROM homer_lake.main.hep_proto_1_call"

# Run full compaction
homer system --config-path /etc/homer/homer.json --compaction-force

# Install DuckDB extensions
homer system --config-path /etc/homer/homer.json --install-extensions

# Show DuckDB version
homer system --config-path /etc/homer/homer.json --duckdb-version

# Generate example config
homer system --generate-example-config > homer.json

# Reload running process
homer system --reload

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

Каталог DuckLake SQLite содержит только метаданные (файлы parquet не копируются). Резервное копирование безопасно во время работы Homer; для восстановления необходимо остановить процесс записи.

homer catalog backup --config-path /etc/homer/homer.json
homer catalog list --config-path /etc/homer/homer.json
homer catalog restore --config-path /etc/homer/homer.json

См. docs/CATALOG.md для флагов, --out, и информации о том, когда использовать восстановление, а когда --rebuild-catalog.

Отображение конфигурации

Выводит действующую конфигурацию, с которой Homer будет запущен (JSON-файл + переменные окружения HOMER_* + значения по умолчанию структуры). Эта команда не подключается к запущенному процессу. Секреты (пароли, токены, ключи) скрываются, если не задан флаг --include-secrets.

homer config show --config-path /etc/homer/homer.json
homer config show --config-path /etc/homer/homer.json --section storage.ducklake.compaction

Мастер (Генератор конфигурации)

Интерактивный мастер, который генерирует полный конфигурационный файл homer.json:

# Interactive TUI wizard
homer wizard

# Non-interactive: generate config for a specific deployment profile
homer wizard --profile all-in-one --output homer.json
homer wizard --profile writer --output homer-writer.json
homer wizard --profile coordinator --output homer-coordinator.json
homer wizard --profile edge --output homer-edge.json
homer wizard --profile node --output homer-node.json

Примеры конфигурации

См. каталог examples/:

Документация

Опубликованная документация (GitHub Pages): https://sipcapture.github.io/homer/ — собрана из docs/ с помощью MkDocs при отправке (push) в homer11. Включите Settings → Pages → Build and deployment: GitHub Actions один раз после первого запуска рабочего процесса.

python3 -m venv .venv-docs && .venv-docs/bin/pip install -r docs-requirements.txt
.venv-docs/bin/mkdocs serve   # http://127.0.0.1:8000

• Search CLI - Поиск из командной строки (примеры, форматы, поток вызовов)
• Catalog backup / restore - Снимок состояния и откат каталога DuckLake SQLite
• Config Wizard - Интерактивный генератор конфигурации (TUI + пресеты)
• Ingest performance tuning - многоядерность, размер пакета DuckLake, интервал сброса Prometheus; scripts/profile_ingest_load.sh / make profile-ingest для воспроизводимых профилей загрузки ЦП
• Coordinator Module - Шлюз REST API
• MCP UI Guide - Помощник запросов на естественном языке (конфигурация + использование интерфейса)
• Node Module - Сервер данных FlightSQL
• Storage Architecture - Хранилище DuckLake
• Storage Policies - Многоуровневое хранилище (горячее/холодное)
• Compaction Setup - Уплотнение файлов
• VQRTCP collector - Отчеты о QoS SIP (vqrtcpxr_stats, интерфейс QoS)
• SIPREC support - Сигнальный SRS (hep_proto_1_siprec)

Лицензия

Выпущено под лицензией AGPL-3.0 License

Авторские права (C) 2025 QXIP BV