router-lists-ui/README.md

# Router Lists UI

Полноценный UI/Backend для управления списками BGP (домены, IP-диапазоны, ASNs), фильтрами и конфигурациями MikroTik на базе S3 (Yandex Object Storage). Интерфейс построен на Tabler, frontend — Vite + React, backend — Express.

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

### Требования
- Node.js 18+
- S3-совместимое хранилище (Yandex Object Storage)
- Доступы AWS: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `S3_BUCKET_NAME`, `AWS_REGION`

### Запуск backend
```powershell
cd backend
npm i
# создайте .env и заполните (пример ниже)
npm start
```
Сервис поднимется на `http://localhost:3001`.

### Запуск frontend
```bash
cd frontend
npm i
npm run dev
```
Frontend доступен на `http://localhost:5173` (по умолчанию). Production-сборка: `npm run build`.

## Главные особенности
- Единая UX/UI библиотека Tabler, адаптивные панели действий и навигация.
- Онлайн-обновление (WebSocket) BGP c потоковым логом и фоновое обновление (HTTP POST) из UI.
- Блокировки (soft-lock) ресурсов с TTL, чтобы избежать гонок при одновременном редактировании.
- Версионирование данных (история/откат), если включено версии в бакете.
- Генерация конфигурации MikroTik из фильтров (`/api/filters/generate-config`) и экспорт в S3.
- Метрики Prometheus: `/metrics`, health/ready: `/health`, `/ready`.

### Важные переменные окружения
- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, `S3_BUCKET_NAME` — доступ к Object Storage
- `CORS_ORIGINS` — список разрешённых Origin через запятую (если пусто — разрешены все)
- `LOG_LEVEL` — уровень логов pino (`info` по умолчанию)
- `PORT` — порт backend (по умолчанию 3001)
- `BGP_BACKGROUND_URL` — адрес фонового обновления BGP, например:
  - `http://77.232.38.173:8080/api/update_bgp/background?api_key=...`
  - Используется эндпоинтом прокси `POST /api/update-bgp/background` для обхода CORS

Пример `.env`:
```dotenv
PORT=3001
LOG_LEVEL=info
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=ru-central1
S3_BUCKET_NAME=...
CORS_ORIGINS=http://localhost:5173
BGP_BACKGROUND_URL=http://77.232.38.173:8080/api/update_bgp/background?api_key=denozord2502
```

## API (backend)

Все ответы об ошибке имеют единый формат:
```json
{ "code": "E_*", "message": "...", "details": {}, "requestId": "..." }
```
Успешные POST/PUT возвращают:
```json
{ "ok": true, "etag": "...", "lastModified": "ISO", "contentLength": 123 }
```
И всегда выставляют заголовки `ETag`, `Last-Modified`, `Content-Length-Source` (если есть). GET поддерживают `countOnly=true` там, где это логично.

### Данные
- GET `/api/domains-new` — список доменов `{ domain, community }`
  - `?q=`, `?offset=`, `?limit=`, `?countOnly=true`, `?format=std`
- POST `/api/domains-new` — `{ domains: [{domain, community}], etag }`

- GET `/api/ip-ranges` — список `[{ ipRange, community }]`
- POST `/api/ip-ranges` — `{ ipRanges: [{ipRange, community}], etag }`

- GET `/api/asns` — список `[{ domain, type }]` (domain = AS, type = community)
- POST `/api/asns` — `{ domains: [{domain, type}], etag }`

- GET `/api/communities` — справочник community (JSON)
- POST `/api/communities` — `{ communities: [...] }` (валидация уникальности value)

### Фильтры и конфигурации
- GET `/api/filters` / POST `/api/filters` — фильтры для всех серверов.
- GET `/api/filters/generate-config` — сгенерировать конфиг MikroTik из `filters.json`.
- POST `/api/filters/export-config` — сохранить сгенерированный конфиг в S3 (`mikrotik-frouting-config.txt`).

- GET `/api/server-configs` / POST `/api/server-configs` — список серверов (id, name, ...).
- GET `/api/server-configs/:serverId` / POST `/api/server-configs/:serverId` — конфиг конкретного сервера.
- DELETE `/api/server-configs/:serverId` — удалить конфиг.
- DELETE `/api/server-configs/:serverId/complete` — удалить конфиг и фильтры.

- GET `/api/server-filters/:serverId` — фильтры сервера.
- POST `/api/server-filters/:serverId` — сохранить фильтры сервера.
- POST `/api/server-filters/generate-config` — сгенерировать конфиг MikroTik на лету из переданных `{ filters }`.

### Прочее
- GET `/api/servers` / POST `/api/servers` — список серверов.
- GET `/api/billing` / POST `/api/billing` — биллинг (ноды, статусы и т.п.).
- GET `/api/auto-urls` / POST `/api/auto-urls` — список авто-URL.
- POST `/api/auto-urls/process` — обработать авто-URL и добавить IP в `bgp_data/ips.txt`.
- GET `/api/servers/availability?ttlSeconds=60` — быстрый TCP‑чек доступности нод.
- GET `/api/s3/last-modified` — метаданные S3 (etag/lastModified/contentLength) по ключевым файлам.
- POST `/api/update-bgp/background` — прокси к фоновой задаче обновления BGP. Требует `BGP_BACKGROUND_URL` в `.env`.
- Locks: GET `/api/locks/:resource`, POST `/api/locks/:resource`, DELETE `/api/locks/:resource`.
- History: GET `/api/history/:resource`, POST `/api/history/:resource/rollback`.

## Frontend
- Vite + React, Tabler CSS/JS (`@tabler/core`).
- Общий компонент `PageHeaderActions` — единый toolbar на страницах данных.
- Модалка `WsUpdateModal` — поток логов online-обновления (ws).
- Доступность: роли, подписи, фокус-кольца, hot-path без мыши.

### Скрипты
```bash
npm run dev    # dev-сервер
npm run build  # продакшн сборка
```

## Структура репозитория
```
backend/         # Express API
frontend/        # Vite React UI
```

## Безопасность и эксплуатация
- Helmet, RateLimit, CORS, отключён слабый etag на JSON.
- Prometheus метрики по умолчанию.
- Для истории версий включите versioning в бакете S3.

## Лицензия
MIT

# 📂 S3 Lists Manager


Веб-интерфейс для удобного управления файлами в S3-совместимом хранилище Yandex Cloud. Приложение позволяет в реальном времени просматривать, добавлять, редактировать, удалять и массово изменять записи в следующих файлах:

- **domains.txt** - список доменов и их шлюзов
- **asns.txt** - список AS номеров и их шлюзов  
- **servers.json** - список серверов с расширенной информацией (IP, DNS, страна, провайдер, тип туннеля)

## ✨ Возможности

- **Три режима работы:** Управление списками доменов, AS-номеров и серверов через вкладки.
- **CRUD операции:** Полный набор действий: создание, чтение, обновление и удаление записей.
- **Поиск в реальном времени:** Мгновенная фильтрация списков по мере ввода.
- **Массовая замена:** Быстрое обновление шлюзов для сотен записей в один клик.
- **Сохранение в S3:** Все изменения сохраняются непосредственно в файлах в бакете Yandex Cloud.
- **Docker-контейнеризация:** Готовый `Dockerfile` для сборки и запуска приложения в изолированном окружении.
- **CI/CD с Gitea Actions:** Автоматическая сборка и публикация Docker-образа в Gitea Registry при пуше в `main`.
- **Современный интерфейс:** Полностью интегрированный Tabler UI с официальными компонентами.

## 🛠️ Технологический стек

| Область      | Технология                                                                                                |
|--------------|-----------------------------------------------------------------------------------------------------------|
| **Фронтенд** | [**React**](https://reactjs.org/) + [**Vite**](https://vitejs.dev/)                                         |
|              | [**@tabler/core**](https://tabler.io/) (UI-компоненты для Tabler версии)                                   |
|              | [**Tabler Icons**](https://tabler-icons.io/) (иконки)                                                      |
|              | [**Axios**](https://axios-http.com/) (HTTP-клиент)                                                        |
| **Бэкенд**   | [**Node.js**](https://nodejs.org/) + [**Express**](https://expressjs.com/)                                 |
|              | [**AWS SDK for JS**](https://aws.amazon.com/sdk-for-javascript/) (для работы с Yandex Cloud S3)           |
| **CI/CD**    | [**Docker**](https://www.docker.com/), [**Gitea Actions**](https://gitea.com/blog/2022/10/01/gitea-actions/) |

## 🏗️ Архитектура

Приложение состоит из двух основных частей: фронтенд на React и бэкенд на Node.js/Express, которые взаимодействуют через REST API.

```mermaid
graph TD
    subgraph Browser
        A[React Frontend]
    end

    subgraph Server
        B(Node.js/Express API)
    end

    subgraph Yandex Cloud
        C{S3 Bucket}
        D1[domains.txt]
        D2[asns.txt]
        D3[servers.json]
    end

    A -- HTTP Requests --> B
    B -- AWS SDK --> C
    C --- D1
    C --- D2
```

## 🚀 Установка и запуск

### Предварительные требования

- [Node.js](https://nodejs.org/) (v20.x или выше)
- [npm](https://www.npmjs.com/) или [yarn](https://yarnpkg.com/)
- Доступ к бакету Yandex Cloud S3 и сервисный аккаунт с правами на чтение и запись.

### 1. Настройка бэкенда

1.  Перейдите в директорию `backend`:
    ```bash
    cd backend
    ```
2.  Создайте файл `.env` на основе примера `.env.example`. Заполните его вашими учетными данными от Yandex Cloud S3:
    ```env
    # .env
    S3_ACCESS_KEY_ID=ВАШ_КЛЮЧ_ДОСТУПА
    S3_SECRET_ACCESS_KEY=ВАШ_СЕКРЕТНЫЙ_КЛЮЧ
    S3_BUCKET_NAME=ИМЯ_ВАШЕГО_БАКЕТА
    ```
3.  Установите зависимости:
    ```bash
    npm install
    ```

### 2. Настройка фронтенда

1.  Перейдите в директорию `frontend`:
    ```bash
    cd ../frontend
    ```
2.  Установите зависимости:
    ```bash
    npm install
    ```

### 3. Запуск приложения

1.  **Запустите бэкенд-сервер.** В директории `backend` выполните:
    ```bash
    npm start
    ```
    Сервер запустится на `http://localhost:3001`.

2.  **Запустите фронтенд.** В новой вкладке терминала, в директории `frontend`, выполните:
    ```bash
    npm run dev
    ```
    Приложение будет доступно по адресу `http://localhost:5173` и будет автоматически проксировать API-запросы на бэкенд.

## 🐳 Docker

Приложение полностью готово к запуску в Docker с двумя вариантами интерфейса.

### Доступные образы

#### Основная версия (main branch)
```bash
git.shts.su/[repository]:latest
```

#### Tabler версия (tabler branch)
```bash
git.shts.su/[repository]:tabler
```

### Быстрый запуск

#### Основная версия
```bash
docker run -d \
  --name s3-lists-manager \
  -p 3001:3001 \
  --env-file ./backend/.env \
  git.shts.su/[repository]:latest
```

#### Tabler версия
```bash
docker run -d \
  --name s3-lists-manager-tabler \
  -p 3002:3001 \
  --env-file ./backend/.env \
  git.shts.su/[repository]:tabler
```

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

Для сборки образа выполните команду в корневой директории проекта:
```bash
docker build -t s3-lists-manager .
```

### Запуск контейнера

Для запуска контейнера необходимо передать переменные окружения. Это можно сделать с помощью флага `-e` или через `--env-file`.

```bash
docker run --rm -p 3001:3001 --env-file ./backend/.env s3-lists-manager
```

После этого приложение будет доступно по адресу `http://localhost:3001`.

### Docker Compose

Создайте файл `docker-compose.yml`:

```yaml
version: '3.8'

services:
  s3-lists-manager:
    image: git.shts.su/[repository]:latest
    container_name: s3-lists-manager
    ports:
      - "3001:3001"
    restart: unless-stopped
    env_file:
      - ./backend/.env

  s3-lists-manager-tabler:
    image: git.shts.su/[repository]:tabler
    container_name: s3-lists-manager-tabler
    ports:
      - "3002:3001"
    restart: unless-stopped
    env_file:
      - ./backend/.env
```

Запуск:
```bash
docker-compose up -d
```

Подробная документация по Docker образам доступна в файле [DOCKER.md](DOCKER.md).

## ⚙️ API Endpoints

| Метод  | Путь          | Описание                         |
|--------|---------------|----------------------------------|
| `GET`  | `/api/domains`| Получить список всех доменов.    |
| `POST` | `/api/domains`| Сохранить изменения в `domains.txt`. |
| `GET`  | `/api/asns`   | Получить список всех AS.         |
| `POST` | `/api/asns`   | Сохранить изменения в `asns.txt`.   |
| `GET`  | `/api/servers`| Получить список всех серверов.   |
| `POST` | `/api/servers`| Сохранить изменения в `servers.json`. |