mirror of https://github.com/by-sonic/tglock.git synced 2026-07-31 07:45:13 +03:00

Files

T

Никита Sonic f03e9106ee docs: инструкция по Cloudflare Worker + скрипт, снять флаг пререлиза (#29 )

Резервный маршрут через Worker был в коде с 2.0, но воспользоваться им никто
не мог: в ARCHITECTURE_V2.md описан только контракт эндпоинта — это
спецификация для того, кто будет писать воркер, а не руководство. Ни скрипта,
ни шагов в репозитории не было. Поэтому люди, у которых легли все обычные
маршруты, писали «не работает» вместо того, чтобы включить запасной выход.

Добавлено:
- worker/tglock-worker.js — готовый скрипт. Проверяет путь и upgrade,
  подтверждает подпротокол binary (без этого клиент рвёт рукопожатие),
  соединяется только с семью адресами Telegram, которые запрашивает TGLock,
  и поддерживает необязательный TGLOCK_TOKEN. Без списка адресов воркер стал
  бы открытым TCP-прокси для любого, кто узнает его адрес.
- docs/CLOUDFLARE_WORKER.md — когда это нужно и когда нет (таблица
  «что видно в приложении → нужен ли Worker»), установка через веб-интерфейс,
  проверка живости, подключение в GUI и через --worker, ограничение доступа,
  контракт для своих реализаций.
- Ссылки из README: в FAQ про блокировку web.telegram.org и в блок docs.

Контракт закреплён тестами, чтобы документация не разошлась с кодом:
- worker_path вынесен в функцию, из неё же строятся боевые маршруты;
- documented_worker_contract_matches_the_requested_path сверяет формат пути;
- worker_allowlist_covers_every_address_a_route_can_ask_for падает, если в
  маршрутах появится адрес, которого нет в скрипте воркера;
- connects_through_the_documented_worker_contract поднимает сервер, ведущий
  себя ровно по документации, и проверяет что туннель работает в обе стороны
  и что запрошен именно документированный URI.

Чего тесты не проверяют: развёрнутый воркер в самом Cloudflare. Это указано и
в самой инструкции.

Отдельно: снят флаг prerelease в release.yml. До правки /releases/latest
отдавал v2.0.0-beta.1, то есть кнопка «Скачать» в README вела на сборку без
CLI и без фикса рендера. Существующий релиз v2.0.0-beta.2 помечен как latest
вручную.

Co-authored-by: by-sonic <171230345+by-sonic@users.noreply.github.com>

2026-07-30 14:06:19 +03:00

7.0 KiB

Raw Permalink Blame History

Резервный маршрут через свой Cloudflare Worker

Когда это нужно

Только в одном случае: провайдер заблокировал саму веб-инфраструктуру Telegram, и все обычные маршруты TGLock перестали отвечать.

Как это выглядит в приложении:

Что видно	Что это значит	Нужен ли Worker
«Telegram на связи»	туннель работает	нет
«Ищем новый маршрут» и не проходит	маршруты перебираются и все падают	да
«Защита включена», DC не определяется	Telegram ещё не подключался	нет, открой Telegram
В диагностике счётчик сбоев растёт, туннелей 0	ни один маршрут не отвечает	да

В CLI то же самое видно в строке статуса: туннелей 0 · DC не определён · сбоев 14.

Если Telegram работает — ничего настраивать не надо. Поле Worker в настройках существует для случая, когда обычные маршруты умерли.

Обрати внимание: Worker не спасает, если Telegram недоступен с самого воркера. Он помогает, когда домены Telegram заблокированы у тебя, а датацентры Cloudflare до них дотягиваются.

Что понадобится

аккаунт Cloudflare (бесплатного тарифа достаточно);
10 минут.

Ни своего сервера, ни домена, ни карты не нужно — воркер получит адрес вида имя.твой-логин.workers.dev.

Установка через веб-интерфейс

Зайди на dash.cloudflare.com → Workers & Pages → Create application → Create Worker.
Дай имя, например tglock. Нажми Deploy — сначала задеплоится заготовка, это нормально.
Нажми Edit code.
Удали всё содержимое редактора и вставь файл worker/tglock-worker.js из этого репозитория целиком.
Deploy.
Скопируй адрес воркера. Он показан сверху и выглядит как tglock.имя.workers.dev — без https:// и без пути.

Проверка, что воркер жив

Открой в браузере https://tglock.имя.workers.dev/apiws. Должно вернуться expected a websocket upgrade — это правильный ответ: значит код развёрнут и работает, просто браузер пришёл обычным запросом.

Если вернулось not found — проверь, что путь именно /apiws. Если ошибка про cloudflare:sockets — у воркера слишком старая дата совместимости, поставь в Settings → Compatibility date сегодняшнюю.

Подключение в TGLock

В приложении: Настройки → поле Cloudflare Worker → вставь tglock.имя.workers.dev → Сохранить. Настройки меняются только при выключенной защите.

В CLI: флаг --worker, можно повторять:

tglock-cli --worker tglock.имя.workers.dev
tglock-cli --worker первый.workers.dev --worker второй.workers.dev

Worker всегда пробуется последним, после всех маршрутов Telegram. Пока обычные маршруты живы, трафик через него не пойдёт, и это осознанно: чужая инфраструктура в цепочке — это лишнее звено, а не улучшение.

Ограничение доступа

Адрес воркера сам по себе секрет, но лучше поставить токен: Settings → Variables → Add variable, имя TGLOCK_TOKEN, значение — любая длинная строка.

Пока переменная не задана, проверка токена выключена. Когда задана — воркер начнёт отвечать 403 без параметра ?token=. Клиент TGLock этот параметр пока не отправляет, так что включать токен есть смысл, если ты правишь и сам скрипт, и адрес.

Независимо от токена воркер соединяется только с семью адресами Telegram, которые запрашивает TGLock. Любой другой dst получает 403, так что открытым TCP-прокси он не станет.

Контракт

Если захочешь написать свою реализацию — вот что именно делает клиент (src/transport.rs):

wss://<домен>/apiws?dst=<telegram-ip>&dc=<номер-dc>
Sec-WebSocket-Protocol: binary

dst — адрес Telegram, к которому нужно подключиться по TCP на порт 443;
dc — номер датацентра, для логов;
подпротокол binary обязательно нужно подтвердить в ответе — без этого клиент разорвёт рукопожатие;
дальше бинарные frames пересылаются в обе стороны без изменений;
TLS до самого воркера обеспечивает Cloudflare.

Список допустимых dst совпадает с transport::worker_allowed_destinations().

Честно про проверку

Скрипт написан по контракту, вычитанному из исходников клиента, и путь с параметрами закреплён тестом connects_through_the_documented_worker_contract — он поднимает локальный сервер, который ведёт себя ровно так, как описано выше, и проверяет, что туннель через него поднимается и данные доходят в обе стороны.

Чего этот тест не проверяет: развёрнутый воркер в самом Cloudflare. Если что-то не сойдётся с их API — открой issue, поправлю.

7.0 KiB Raw Permalink Blame History Unescape Escape