Denozordec
2d7b06260e
- Added optional Mihomo configuration fields in `config.compose.yaml` and `config.example.yaml` for enhanced integration with the Mihomo external-controller. - Updated the `Gateway` to handle Mihomo API requests, including proxying and error handling for Mihomo-specific endpoints. - Enhanced the documentation in `GATEWAY_RUN.md` to guide users on configuring Mihomo integration. - Introduced new utility functions in the web client for interacting with Mihomo API endpoints, improving the overall user experience. - Updated the sidebar in the Svelte components to include a link to the Mihomo section, enhancing navigation.
106 lines
5.7 KiB
Markdown
106 lines
5.7 KiB
Markdown
# telemt-api
|
||
|
||
HTTP‑шлюз на Go для [Telemt Control API](docs/API.md): один порт, **белый список IP (CIDR)**, маршруты вида `/api/{alias}/…` → `{base_url}/v1/…`, опционально **Mihomo** — `/api/{alias}/mihomo/…` к external-controller (см. [docs/GATEWAY_RUN.md](docs/GATEWAY_RUN.md#mihomo-external-controller)), агрегация нескольких инстансов — [`/api/agg/…`](docs/AGGREGATE.md), 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/`:
|
||
|
||
```bash
|
||
# при необходимости (закрытый registry): логин Gitea + PAT с read:package
|
||
docker login git.shts.su
|
||
|
||
docker pull git.shts.su/denozord/telemt-api:latest
|
||
```
|
||
|
||
Конфиг возьмите из репозитория или создайте свой `config.yaml` (см. [config.example.yaml](config.example.yaml)):
|
||
|
||
```bash
|
||
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](Dockerfile)).
|
||
|
||
```bash
|
||
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](web/README.md). Полный сценарий Docker (CLI, compose, сборка, CI): [docs/GATEWAY_RUN.md](docs/GATEWAY_RUN.md).
|
||
|
||
### Web UI (локально без Docker)
|
||
|
||
Если шлюз уже запущен (например на `http://127.0.0.1:8080`):
|
||
|
||
```bash
|
||
cd web
|
||
cp .env.example .env
|
||
# при необходимости отредактируйте PUBLIC_TELEMT_GATEWAY_URL
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
Откройте адрес Vite (обычно `http://localhost:5173`). В конфиге шлюза добавьте [CORS](docs/AGGREGATE.md), например:
|
||
|
||
```yaml
|
||
cors_allowed_origins:
|
||
- "http://localhost:5173"
|
||
```
|
||
|
||
### Локальная сборка образа
|
||
|
||
`docker build -t telemt-api-gateway:local .` — в образ попадают Web UI и бинарь шлюза (см. [Dockerfile](Dockerfile)). В `docker run` укажите этот тег. Подробнее — [docs/GATEWAY_RUN.md](docs/GATEWAY_RUN.md).
|
||
|
||
## Документация
|
||
|
||
| Документ | Содержание |
|
||
|----------|------------|
|
||
| **[docs/GATEWAY_RUN.md](docs/GATEWAY_RUN.md)** | Полная инструкция: конфиг, pull/registry, Docker CLI, Compose, CI/CD, неполадки |
|
||
| **[docs/API.md](docs/API.md)** | Контракт Telemt Control API (`/v1/…`) |
|
||
| **[docs/AGGREGATE.md](docs/AGGREGATE.md)** | Агрегирующие эндпоинты шлюза (`/api/agg/…`), CORS, кэш |
|
||
| **[docs/AGGREGATE_OPENAPI.yaml](docs/AGGREGATE_OPENAPI.yaml)** | OpenAPI 3 черновик для `/api/agg/*` (генерация типов для UI) |
|
||
| **[docs/OPERATIONS_BASELINE.md](docs/OPERATIONS_BASELINE.md)** | Baseline UX/SLO для панели быстрого реагирования (MTTD/MTTR и критерии успеха) |
|
||
| **[docs/INCIDENT_ROLLOUT.md](docs/INCIDENT_ROLLOUT.md)** | Пошаговый rollout incidents/live функций и настройка alert policy |
|
||
| **[web/README.md](web/README.md)** | Web UI (SvelteKit): разработка с Vite, `PUBLIC_TELEMT_GATEWAY_URL`, встраивание в образ шлюза |
|
||
| **[docs/GEOIP.md](docs/GEOIP.md)** | GeoLite2 City (страна/город) и опционально ASN (номер AS, организация) для IP в `unique-ips` |
|
||
|
||
## Сборка и тесты без Docker
|
||
|
||
```bash
|
||
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](.gitea/workflows/docker.yaml) — тесты Go, сборка и публикация образа в Container Registry Gitea (см. раздел «Обновление и CI/CD» в [docs/GATEWAY_RUN.md](docs/GATEWAY_RUN.md)).
|