This commit is contained in:
Denozordec
+1187
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,159 @@
|
||||
# Запуск Telemt API Gateway (Docker)
|
||||
|
||||
Оглавление:
|
||||
|
||||
1. [Назначение](#назначение)
|
||||
2. [Требования](#требования)
|
||||
3. [Минимальная конфигурация](#минимальная-конфигурация)
|
||||
4. [Переменные окружения](#переменные-окружения)
|
||||
5. [Сборка образа](#сборка-образа)
|
||||
6. [Запуск через Docker CLI](#запуск-через-docker-cli)
|
||||
7. [Запуск через Docker Compose](#запуск-через-docker-compose)
|
||||
8. [Проверка](#проверка)
|
||||
9. [Обновление и CI/CD](#обновление-и-cicd)
|
||||
10. [Устранение неполадок](#устранение-неполадок)
|
||||
|
||||
## Назначение
|
||||
|
||||
Шлюз — это один HTTP‑вход для нескольких экземпляров [Telemt Control API](API.md):
|
||||
|
||||
- **Белый список 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](API.md).
|
||||
|
||||
## Требования
|
||||
|
||||
- Установленные [Docker](https://docs.docker.com/get-docker/) и при необходимости [Docker Compose](https://docs.docker.com/compose/) v2.
|
||||
- Для локальной сборки из исходников: [Go 1.22+](https://go.dev/dl/) (опционально, если не используете только готовый образ из registry).
|
||||
|
||||
## Минимальная конфигурация
|
||||
|
||||
Скопируйте [config.example.yaml](../config.example.yaml) в свой `config.yaml` и отредактируйте.
|
||||
|
||||
Минимальный рабочий фрагмент для **разработки** (без проверки IP):
|
||||
|
||||
```yaml
|
||||
listen: ":8080"
|
||||
allow_all: true
|
||||
servers:
|
||||
- alias: main_srv
|
||||
base_url: http://127.0.0.1:9091
|
||||
```
|
||||
|
||||
Минимальный фрагмент для **продакшена** (только перечисленные сети/хосты):
|
||||
|
||||
```yaml
|
||||
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`).
|
||||
- `GET /health` на шлюзе **не** проверяется по whitelist — так проще настроить Docker `HEALTHCHECK` и оркестраторы.
|
||||
- Поле `path_prefix` по умолчанию равно `/v1` (префикс Telemt Control API).
|
||||
|
||||
Опционально для бэкенда с включённым `auth_header` в Telemt задайте в конфиге имя переменной окружения, значение которой будет отправлено как заголовок `Authorization` на этот upstream:
|
||||
|
||||
```yaml
|
||||
servers:
|
||||
- alias: main_srv
|
||||
base_url: http://telemt:9091
|
||||
authorization_env: TELEMT_API_AUTH
|
||||
```
|
||||
|
||||
Значение должно **точно** совпадать с настроенным в Telemt `auth_header` (см. [API.md](API.md)).
|
||||
|
||||
## Переменные окружения
|
||||
|
||||
| Переменная | Описание |
|
||||
|----------------|----------|
|
||||
| `CONFIG_PATH` | Путь к YAML внутри контейнера. По умолчанию: `/etc/telemt-gateway/config.yaml`. |
|
||||
| `TELEMT_API_AUTH` | Пример: секрет для `authorization_env` в конфиге (имя может быть любым). |
|
||||
|
||||
## Сборка образа
|
||||
|
||||
В каталоге репозитория:
|
||||
|
||||
```powershell
|
||||
docker build -t telemt-api-gateway:local .
|
||||
```
|
||||
|
||||
## Запуск через Docker CLI
|
||||
|
||||
Пример для PowerShell (подставьте путь к своему `config.yaml`):
|
||||
|
||||
```powershell
|
||||
docker run -d --name telemt-gateway `
|
||||
-p 8080:8080 `
|
||||
-v "C:\path\to\config.yaml:/etc/telemt-gateway/config.yaml:ro" `
|
||||
-e CONFIG_PATH=/etc/telemt-gateway/config.yaml `
|
||||
telemt-api-gateway:local
|
||||
```
|
||||
|
||||
Проверка:
|
||||
|
||||
```powershell
|
||||
Invoke-WebRequest -Uri http://127.0.0.1:8080/health -UseBasicParsing
|
||||
Invoke-WebRequest -Uri http://127.0.0.1:8080/api/main_srv/health -UseBasicParsing
|
||||
```
|
||||
|
||||
Второй запрос проксируется на `{base_url}/v1/health` для alias `main_srv`.
|
||||
|
||||
Остановка и удаление:
|
||||
|
||||
```powershell
|
||||
docker stop telemt-gateway
|
||||
docker rm telemt-gateway
|
||||
```
|
||||
|
||||
## Запуск через Docker Compose
|
||||
|
||||
В репозитории есть [docker-compose.yml](../docker-compose.yml) и пример [config.compose.yaml](../config.compose.yaml) с `allow_all: true` и `base_url: http://host.docker.internal:9091` (Telemt на хосте).
|
||||
|
||||
```powershell
|
||||
docker compose up -d --build
|
||||
docker compose logs -f gateway
|
||||
docker compose down
|
||||
```
|
||||
|
||||
На старых Linux‑хостах, где нет `host.docker.internal`, замените `base_url` на IP хоста или добавьте сервис Telemt в тот же `docker-compose` и укажите его DNS‑имя.
|
||||
|
||||
## Проверка
|
||||
|
||||
| Сценарий | Ожидание |
|
||||
|----------|----------|
|
||||
| `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
|
||||
|
||||
- **Образ**: пересоберите тег или подтяните новый из registry, затем `docker compose up -d --build` или `docker stop` / `docker run ...` с тем же volume конфига.
|
||||
- **Конфиг**: отредактируйте файл на хосте и перезапустите контейнер (шлюз не перечитывает конфиг на лету).
|
||||
- **Gitea Actions**: workflow [.gitea/workflows/docker.yaml](../.gitea/workflows/docker.yaml) выполняет `go test` и собирает Docker‑образ. Для пуша в registry задайте secrets:
|
||||
|
||||
- `REGISTRY_IMAGE` — полное имя образа без тега, например `git.example.com/owner/telemt-api-gateway`
|
||||
- `REGISTRY_URL` — хост registry, например `git.example.com`
|
||||
- `REGISTRY_USER` / `REGISTRY_PASSWORD`
|
||||
|
||||
Если secrets не заданы, образ только собирается в runner без push.
|
||||
|
||||
## Устранение неполадок
|
||||
|
||||
- **`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 ./...` в корне репозитория.
|
||||
Reference in New Issue
Block a user