Enhance Dockerfile to build and include a new HTTP API service (mtproxy_checkerd) alongside the existing CLI tool (mtproxy_checker). Update README and documentation to reflect the new service and its usage, including environment variables and Docker run instructions.

2026-04-11 00:50:57 +07:00
parent 4905c06b9b
commit 5a66f0f2e8
8 changed files with 482 additions and 6 deletions
@@ -5,12 +5,62 @@
 | Компонент | Описание |
 |-----------|----------|
 | **База runtime** | Alpine Linux 3.20 |
-| **Бинарник** | Статическая сборка Go (`CGO_ENABLED=0`), путь в контейнере: `/usr/local/bin/mtproxy_checker` |
+| **Бинарники** | CLI: `/usr/local/bin/mtproxy_checker`. HTTP-сервис списка: `/usr/local/bin/mtproxy_checkerd` (см. ниже) |
 | **Сертификаты** | Пакет `ca-certificates` (для TLS к реальным хостам при необходимости) |
-| **ENTRYPOINT** | Тот же бинарник — все аргументы `docker run …` передаются в утилиту |
-| **Порты** | Ничего не слушает: только **исходящие** TCP до хоста и порта из ссылки |
+| **ENTRYPOINT** | По умолчанию **CLI** — аргументы `docker run …` идут в `mtproxy_checker` |
+| **Порты** | В режиме CLI ничего не слушает (только исходящий TCP). Образ объявляет **EXPOSE 8080** для режима API |

-Одна команда `docker run` = **одна** проверка одного прокси; процесс завершается с **кодом выхода** (`0`…`4`), что удобно в CI и скриптах.
+Одна команда `docker run` с entrypoint по умолчанию = **одна** проверка одного прокси; процесс завершается с **кодом выхода** (`0`…`4`), что удобно в CI и скриптах.
+
+## HTTP API: `mtproxy_checkerd`
+
+Лёгкий сервер на стандартной библиотеке Go: читает файл со списком `tg://` (как в разделе «файл — одна ссылка на строку»), **сразу после старта** выполняет первый цикл проверок, затем повторяет с интервалом. Результаты последнего цикла отдаются по HTTP в JSON.
+
+### Запуск контейнера (смена entrypoint)
+
+**Linux / macOS:**
+
+```bash
+docker run --rm -p 8080:8080 \
+  -v /path/to/proxies.txt:/data/proxies.txt:ro \
+  --entrypoint /usr/local/bin/mtproxy_checkerd \
+  mtproxy_checker:local
+```
+
+**Windows (PowerShell):**
+
+```powershell
+docker run --rm -p 8080:8080 `
+  -v "${PWD}\proxies.txt:/data/proxies.txt:ro" `
+  --entrypoint /usr/local/bin/mtproxy_checkerd `
+  mtproxy_checker:local
+```
+
+Готовый пример с переменными окружения: репозиторий **`docker-compose.api.yaml`** — `docker compose -f docker-compose.api.yaml up --build`.
+
+### Переменные окружения
+
+| Переменная | По умолчанию | Назначение |
+|------------|--------------|------------|
+| `MTPROXY_LIST_FILE` | `/data/proxies.txt` | Путь к файлу: одна `tg://` ссылка на строку; пустые строки и строки с `#` в начале пропускаются |
+| `MTPROXY_CHECK_INTERVAL` | `5m` | Интервал между циклами (`time.ParseDuration`, например `5m`, `1h`) |
+| `MTPROXY_HTTP_ADDR` | `:8080` | Адрес прослушивания HTTP |
+| `MTPROXY_CHECK_TIMEOUT` | `15s` | Таймаут одной проверки (аналог `-timeout` CLI) |
+| `MTPROXY_DC_ID` | `2` | DC id (аналог `-dc-id` CLI) |
+| `MTPROXY_ALLOWED_IPS` | *(не задана)* | Если задана непустая строка — доступ к **всем** маршрутам только с перечисленных IP/CIDR; остальные получают **403** и JSON `{"error":"forbidden"}`. Формат: через запятую, пробелы допускаются: `192.168.1.10`, `10.0.0.0/8`, IPv6 и CIDR вида `2001:db8::/32`. Учитывается только **`RemoteAddr`** TCP-соединения; заголовок `X-Forwarded-For` **не** используется |
+
+### HTTP
+
+| Метод | Путь | Ответ |
+|--------|------|--------|
+| GET | `/health` | `200`, `{"status":"ok"}` |
+| GET | `/api/v1/proxies` | `200`, JSON с полями `cycle_finished_at`, `next_check_after`, массив `proxies` |
+
+Элемент `proxies[]`: `raw_line`, при успешном разборе — `url`, `ok`, `exit_code` (`0` OK, `1` ошибка проверки, `2` ошибка разбора URL/секрета, `3` прокси закрыл соединение, `4` таймаут), `error`, при необходимости `parse_error`, `checked_at`.
+
+### Whitelist IP и Docker
+
+Процесс видит **IP источника TCP** таким, каким его передал стек в контейнер. При пробросе порта с хоста (`-p 8080:8080`) на Linux часто это адрес **шлюза bridge** или **userland-proxy**, а не «настоящий» IP клиента с хоста. Имеет смысл задавать **CIDR подсети Docker** (например `172.17.0.0/16`), слушать только внутреннюю сеть, использовать **`--network host`** (на Linux) или ограничивать доступ на **обратном прокси** (nginx `allow` и т.п.).

 ## Требования