telemt-api

HTTP‑шлюз на Go для Telemt Control API: один порт, белый список IP (CIDR), маршруты вида /api/{alias}/… → {base_url}/v1/…, опционально Mihomo — /api/{alias}/mihomo/… к external-controller (см. docs/GATEWAY_RUN.md), агрегация нескольких инстансов — /api/agg/…, live SSE поток — /api/live/events, метрики Prometheus на /metrics. Web UI (SvelteKit) встроен в тот же процесс/образ: статика на /, API на /api/… и /health, раздел Mihomo на /servers/{alias}/mihomo.

Быстрый старт (Linux)

Предполагается установлены Docker и Docker Compose v2.

Рекомендуется брать уже собранный образ из Container Registry Gitea (после каждого push CI обновляет теги, в том числе latest). В актуальном образе вместе с шлюзом уже встроена панель на http://<хост>:8080/:

# при необходимости (закрытый registry): логин Gitea + PAT с read:package
docker login git.shts.su

docker pull git.shts.su/denozord/telemt-api:latest

Конфиг возьмите из репозитория или создайте свой config.yaml (см. config.example.yaml):

git clone <url-репозитория> && cd telemt-api
cp config.example.yaml config.yaml
# отредактируйте config.yaml: servers, whitelist_cidrs или allow_all для разработки

docker run -d --name telemt-gateway \
  -p 8080:8080 \
  -v "$(pwd)/config.yaml:/etc/telemt-gateway/config.yaml:ro" \
  -e CONFIG_PATH=/etc/telemt-gateway/config.yaml \
  git.shts.su/denozord/telemt-api:latest

curl -sS http://127.0.0.1:8080/health
curl -sS http://127.0.0.1:8080/api/main_srv/health
# панель в браузере: http://127.0.0.1:8080/

Обновление образа: docker pull git.shts.su/denozord/telemt-api:latest и пересоздайте контейнер (docker rm -f telemt-gateway и снова docker run …).

Compose

Один сервис gateway — в образе уже есть и API, и статика панели (см. Dockerfile).

git clone <url-репозитория> && cd telemt-api
docker compose pull
docker compose up -d
docker compose logs -f gateway

• Всё на одном порту: http://127.0.0.1:8080/ — Web UI, http://127.0.0.1:8080/api/… — шлюз, http://127.0.0.1:8080/health — проверка живости.

Подробнее по фронту и dev-режиму: web/README.md. Полный сценарий Docker (CLI, compose, сборка, CI): docs/GATEWAY_RUN.md.

Web UI (локально без Docker)

Если шлюз уже запущен (например на http://127.0.0.1:8080):

cd web
cp .env.example .env
# при необходимости отредактируйте PUBLIC_TELEMT_GATEWAY_URL
npm install
npm run dev

Откройте адрес Vite (обычно http://localhost:5173). В конфиге шлюза добавьте CORS, например:

cors_allowed_origins:
  - "http://localhost:5173"

Локальная сборка образа

docker build -t telemt-api-gateway:local . — в образ попадают Web UI и бинарь шлюза (см. Dockerfile). В docker run укажите этот тег. Подробнее — docs/GATEWAY_RUN.md.

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

Документ	Содержание
docs/GATEWAY_RUN.md	Полная инструкция: конфиг, pull/registry, Docker CLI, Compose, CI/CD, неполадки
docs/API.md	Контракт Telemt Control API (/v1/…)
docs/AGGREGATE.md	Агрегирующие эндпоинты шлюза (/api/agg/…), CORS, кэш
docs/AGGREGATE_OPENAPI.yaml	OpenAPI 3 черновик для /api/agg/* (генерация типов для UI)
docs/OPERATIONS_BASELINE.md	Baseline UX/SLO для панели быстрого реагирования (MTTD/MTTR и критерии успеха)
docs/INCIDENT_ROLLOUT.md	Пошаговый rollout incidents/live функций и настройка alert policy
web/README.md	Web UI (SvelteKit): разработка с Vite, PUBLIC_TELEMT_GATEWAY_URL, встраивание в образ шлюза
docs/GEOIP.md	GeoLite2 City (страна/город) и опционально ASN (номер AS, организация) для IP в unique-ips

Сборка и тесты без Docker

go mod tidy && go test ./...

Observability (gateway)

Prometheus метрики доступны на /metrics, включая:

• telemt_gateway_http_in_flight
• telemt_gateway_http_requests_total{code,method,alias,endpoint}
• telemt_gateway_http_request_duration_seconds{method,alias,endpoint}

CI/CD

В репозитории: .gitea/workflows/docker.yaml — тесты Go, сборка и публикация образа в Container Registry Gitea (см. раздел «Обновление и CI/CD» в docs/GATEWAY_RUN.md).