mirror of
https://github.com/by-sonic/tglock.git
synced 2026-08-02 16:45:50 +03:00
Никита Sonic
f03e9106ee
Резервный маршрут через 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>
87 lines
7.0 KiB
Markdown
87 lines
7.0 KiB
Markdown
# Резервный маршрут через свой Cloudflare Worker
|
||
|
||
## Когда это нужно
|
||
|
||
Только в одном случае: провайдер заблокировал саму веб-инфраструктуру Telegram, и **все** обычные маршруты TGLock перестали отвечать.
|
||
|
||
Как это выглядит в приложении:
|
||
|
||
| Что видно | Что это значит | Нужен ли Worker |
|
||
|---|---|---|
|
||
| «Telegram на связи» | туннель работает | нет |
|
||
| «Ищем новый маршрут» и не проходит | маршруты перебираются и все падают | **да** |
|
||
| «Защита включена», DC не определяется | Telegram ещё не подключался | нет, открой Telegram |
|
||
| В диагностике счётчик сбоев растёт, туннелей 0 | ни один маршрут не отвечает | **да** |
|
||
|
||
В CLI то же самое видно в строке статуса: `туннелей 0 · DC не определён · сбоев 14`.
|
||
|
||
Если Telegram работает — **ничего настраивать не надо.** Поле Worker в настройках существует для случая, когда обычные маршруты умерли.
|
||
|
||
Обрати внимание: Worker не спасает, если Telegram недоступен *с самого воркера*. Он помогает, когда домены Telegram заблокированы **у тебя**, а датацентры Cloudflare до них дотягиваются.
|
||
|
||
## Что понадобится
|
||
|
||
- аккаунт Cloudflare (бесплатного тарифа достаточно);
|
||
- 10 минут.
|
||
|
||
Ни своего сервера, ни домена, ни карты не нужно — воркер получит адрес вида `имя.твой-логин.workers.dev`.
|
||
|
||
## Установка через веб-интерфейс
|
||
|
||
1. Зайди на [dash.cloudflare.com](https://dash.cloudflare.com) → **Workers & Pages** → **Create application** → **Create Worker**.
|
||
2. Дай имя, например `tglock`. Нажми **Deploy** — сначала задеплоится заготовка, это нормально.
|
||
3. Нажми **Edit code**.
|
||
4. Удали всё содержимое редактора и вставь файл [`worker/tglock-worker.js`](../worker/tglock-worker.js) из этого репозитория целиком.
|
||
5. **Deploy**.
|
||
6. Скопируй адрес воркера. Он показан сверху и выглядит как `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`, можно повторять:
|
||
|
||
```bash
|
||
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`):
|
||
|
||
```text
|
||
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](https://github.com/by-sonic/tglock/issues/new), поправлю.
|