feat: initial commit of FreeLLMAPI catalog proxy and compose stack

2026-10-24 10:41:15 +00:00
commit a67cc3fef7
6 changed files with 307 additions and 0 deletions
@@ -0,0 +1,33 @@
+# FreeLLMAPI Catalog Proxy
+
+Прозрачный кэширующий реверс-прокси для доставки оригинального официального каталога моделей FreeLLMAPI (`api.freellmapi.co/v1/latest`).
+
+## Зачем это нужно
+
+FreeLLMAPI не запрашивает список моделей напрямую у сторонних провайдеров (кроме LongCat и SiliconFlow). Для остальных (Routeway, UnoRouter, BazaarLink, OrcaRouter и др.) список моделей подгружается из внешнего подписанного каталога:
+`https://api.freellmapi.co/v1/latest` (~560 КБ).
+
+При прямой загрузке на российских каналах передача файла зависает после первых ~20 КБ из-за DPI/фильтрации больших ответов. Контейнер FreeLLMAPI падает по таймауту, и в базе остаются только предзашитые базовые модели, а добавленные ключи получают пустой список моделей.
+
+## Как это работает
+
+1. Прокси подключается к `https://api.freellmapi.co/v1/latest` через стабильный SOCKS5-маршрут (Германия).
+2. Забирает **оригинальные байты** и официальный криптографический заголовок `x-catalog-signature` (Ed25519).
+3. Кэширует файл локально на 12 часов.
+4. Отдаёт каталог контейнеру FreeLLMAPI по локальной сети (`http://catalog-proxy:8080/v1/latest`).
+5. FreeLLMAPI штатно верифицирует оригинальную цифровую подпись Ed25519 (`PINNED_CATALOG_PUBKEY`) и применяет актуальные модели.
+
+## Запуск в Docker Compose
+
+1. Скопируйте `.env.example` в `.env` и укажите переменные:
+   ```bash
+   cp .env.example .env
+   ```
+2. Запустите стек:
+   ```bash
+   docker compose up -d
+   ```
+3. Проверьте логи синхронизации:
+   ```bash
+   docker compose logs -f freellmapi
+   ```