telemt-api/docs/GATEWAY_RUN.md

Запуск Telemt API Gateway (Docker)

Оглавление:

1. Назначение
2. Требования
3. Минимальная конфигурация
4. Переменные окружения
5. Готовый образ из registry
6. Локальная сборка образа
7. Запуск через Docker CLI
8. Запуск через Docker Compose
9. Проверка
10. Обновление и CI/CD
11. Устранение неполадок

Назначение

Шлюз — это один HTTP‑вход для нескольких экземпляров Telemt Control API:

• Белый список IP (CIDR): кто может обращаться к шлюзу (кроме GET /health, см. ниже).
• Маршрутизация по alias: клиент вызывает GET /api/{alias}/health, шлюз проксирует на {base_url}/v1/health у соответствующего сервера.
• Метрики Prometheus: GET /metrics (под тем же правилом whitelist, что и API).
• Доверенные прокси: если прямой TCP‑peer входит в trusted_proxies, для проверки whitelist берётся первый адрес из X-Forwarded-For или X-Real-IP.

Эндпоинты и контракт ответов бэкенда описаны в API.md.

Требования

• Установленные Docker и при необходимости Docker Compose v2.
• Для локальной сборки из исходников: Go 1.22+ (опционально, если не используете только готовый образ из registry).

Минимальная конфигурация

Скопируйте config.example.yaml в свой config.yaml и отредактируйте.

Минимальный рабочий фрагмент для разработки (без проверки IP):

listen: ":8080"
allow_all: true
servers:
  - alias: main_srv
    base_url: http://127.0.0.1:9091

Минимальный фрагмент для продакшена (только перечисленные сети/хосты):

listen: ":8080"
allow_all: false
whitelist_cidrs:
  - "203.0.113.10/32"
  - "10.0.0.0/8"
servers:
  - alias: main_srv
    base_url: http://telemt-internal:9091

Правила:

• При allow_all: false и пустом whitelist_cidrs доступ будет закрыт для всех (кроме GET /health).
• В whitelist_cidrs и trusted_proxies допустимы CIDR (10.0.0.0/8) и одиночный IPv4/IPv6 без маски (87.103.241.8 эквивалентно 87.103.241.8/32).
• GET /health на шлюзе не проверяется по whitelist — так проще настроить Docker HEALTHCHECK и оркестраторы.
• Поле path_prefix по умолчанию равно /v1 (префикс Telemt Control API).

Опционально для бэкенда с включённым auth_header в Telemt задайте в конфиге имя переменной окружения, значение которой будет отправлено как заголовок Authorization на этот upstream:

servers:
  - alias: main_srv
    base_url: http://telemt:9091
    authorization_env: TELEMT_API_AUTH

Значение должно точно совпадать с настроенным в Telemt auth_header (см. API.md).

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

Переменная	Описание
CONFIG_PATH	Путь к YAML внутри контейнера. По умолчанию: /etc/telemt-gateway/config.yaml.
TELEMT_API_AUTH	Пример: секрет для authorization_env в конфиге (имя может быть любым).

Готовый образ из registry

CI публикует образ в Container Registry Gitea. Для репозитория denozord/telemt-api на git.shts.su стабильный тег:

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

Если registry не публичный, сначала войдите (логин — пользователь Gitea, пароль — personal access token с правом read:package):

docker login git.shts.su

Другие полезные теги из того же workflow: имя ветки (с / заменённым на -) и sha-<12 символов коммита> — см. раздел Обновление и CI/CD.

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

Если нужно собрать образ самостоятельно из клона репозитория:

docker build -t telemt-api-gateway:local .

В командах docker run ниже вместо имени из registry подставьте telemt-api-gateway:local.

Запуск через Docker CLI

Пример для Linux (подставьте путь к config.yaml; ниже — файл из текущего каталога). Используется готовый образ:

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 -i http://127.0.0.1:8080/health
curl -sS -i http://127.0.0.1:8080/api/main_srv/health

Второй запрос проксируется на {base_url}/v1/health для alias main_srv.

Остановка и удаление:

docker stop telemt-gateway
docker rm telemt-gateway

Запуск через Docker Compose

В репозитории есть docker-compose.yml и пример config.compose.yaml с allow_all: true и base_url: http://host.docker.internal:9091 (Telemt на хосте; на Docker Desktop для Linux это обычно работает из коробки). Образ по умолчанию скачивается из registry, локальная сборка не требуется.

docker compose pull
docker compose up -d
docker compose logs -f gateway
docker compose down

Чтобы пересобрать образ из исходников вместо pull, в docker-compose.yml временно замените блок image: на build: . (и нужный тег при необходимости).

На Linux без host.docker.internal сделайте одно из:

• в docker-compose.yml для сервиса gateway добавьте extra_hosts: ["host.docker.internal:host-gateway"] (Docker Engine 20.10+);
• либо замените в config.compose.yaml значение base_url на IP хоста в docker‑bridge (часто 172.17.0.1) или на имя сервиса Telemt в той же сети compose.

Проверка

Сценарий	Ожидание
GET /health	200, JSON {"status":"ok"}
Разрешённый IP, корректный alias	ответ бэкенда (например 200 для /v1/health)
IP не в whitelist	403, JSON с code: forbidden
Неизвестный alias	404, JSON с code: not_found
Бэкенд недоступен	502, JSON с code: bad_gateway
GET /metrics	текст метрик Prometheus (при разрешённом IP)

Обновление и CI/CD

• Образ: подтяните свежий тег (docker pull git.shts.su/denozord/telemt-api:latest или docker compose pull), пересоздайте контейнер (docker compose up -d или новый docker run с тем же volume конфига). Локальная пересборка нужна только если вы меняете Dockerfile/код и не пользуетесь CI.

• Конфиг: отредактируйте файл на хосте и перезапустите контейнер (шлюз не перечитывает конфиг на лету).

• Gitea Actions: workflow .gitea/workflows/docker.yaml сначала выполняет go mod tidy && go test ./..., затем собирает образ через Buildx и пушит в Container Registry Gitea.

  • В репозитории должен быть secret ACTIONS_PAT — personal access token пользователя с правом write:package (и при необходимости read:package), как для обычного docker login к registry.
  • Логин в registry: пользователь gitea.actor (кто запустил workflow), пароль — этот PAT.
  • Хост registry задаётся в workflow в env.REGISTRY (по умолчанию git.shts.su); при другом инстансе Gitea измените значение в .gitea/workflows/docker.yaml.
  • Теги образа: latest, имя ветки/тега (с / заменённым на -), и sha-<первые 12 символов коммита>. Полный путь: {REGISTRY}/{gitea.repository}:<тег>.

Устранение неполадок

• docker pull: unauthorized / denied: выполните docker login git.shts.su с учётной записью Gitea и PAT с read:package.
• 403 forbidden с хоста при allow_all: false: добавьте CIDR клиента в whitelist_cidrs. Запросы из контейнера к самому себе идут с 127.0.0.1 — при необходимости добавьте 127.0.0.1/32.
• За reverse proxy: укажите CIDR прокси в trusted_proxies, иначе whitelist видит IP прокси, а не клиента.
• 502 bad_gateway: проверьте base_url, DNS в Docker‑сети и то, что Telemt слушает API ([server.api].enabled=true и корректный listen).
• Сборка Go без Docker: в корне репозитория выполните go mod tidy && go test ./....