287 lines
13 KiB
Markdown
287 lines
13 KiB
Markdown
# Telegram WEB proxy: установка и настройка
|
||
|
||
Этот проект разворачивает собственный WEB proxy для Telegram в Docker и
|
||
подключает его к уже работающему Nginx Proxy Manager. Контейнер не публикует
|
||
порты на хосте: входящие HTTPS-соединения принимает Nginx Proxy Manager и
|
||
передаёт их контейнеру через общую Docker-сеть.
|
||
|
||
> WEB proxy пока является новым типом транспорта. Для подключения нужен клиент
|
||
> Telegram, в котором есть тип прокси `WEB`. Если такого пункта в настройках
|
||
> нет, установленная версия клиента этот транспорт ещё не поддерживает.
|
||
|
||
## Самый простой вариант: чистый VPS и один вопрос
|
||
|
||
Этот вариант подходит, если вы только что купили отдельный чистый VPS и не
|
||
хотите настраивать Nginx Proxy Manager. Скрипт сам установит Docker, запустит
|
||
прокси вместе с Caddy и получит HTTPS-сертификат. Он спросит только домен.
|
||
|
||
Понадобятся:
|
||
|
||
- 64-битный VPS `x86_64` с Ubuntu или Debian;
|
||
- один домен или поддомен с единственной DNS-записью `A`, которая уже указывает
|
||
прямо на публичный IPv4 этого VPS;
|
||
- открытые у провайдера сервера входящие TCP-порты `80` и `443`.
|
||
|
||
На странице проекта в Gitea нажмите **Code**, скопируйте адрес **HTTPS**, затем
|
||
подключитесь к VPS по SSH и выполните команды ниже. Вместо текста в угловых
|
||
скобках вставьте скопированный адрес:
|
||
|
||
```sh
|
||
sudo apt update
|
||
sudo apt install -y git
|
||
git clone <АДРЕС_РЕПОЗИТОРИЯ>
|
||
cd telegram-web-proxy-stack
|
||
sudo ./quick-install.sh
|
||
```
|
||
|
||
После запуска нужно ввести только подготовленный домен. Пароли или токены
|
||
Gitea для публичного репозитория не требуются.
|
||
|
||
Можно случайно вставить домен вместе с `https://` — установщик уберёт схему и
|
||
лишний путь. После проверки DNS он автоматически:
|
||
|
||
1. установит системные компоненты и Docker из официального репозитория;
|
||
2. соберёт Telegram WEB proxy;
|
||
3. запустит Caddy и выпустит HTTPS-сертификат;
|
||
4. покажет сервер, секрет и готовую ссылку подключения.
|
||
|
||
Для автоматического запуска домен разрешается передать сразу:
|
||
|
||
```sh
|
||
sudo ./quick-install.sh --domain proxy.example.com
|
||
```
|
||
|
||
Секрет сохраняется в Docker-томе и остаётся прежним при повторном запуске.
|
||
Для обновления используйте только быстрый установщик:
|
||
|
||
```sh
|
||
git pull --ff-only
|
||
sudo ./quick-install.sh
|
||
```
|
||
|
||
Если выпуск сертификата не завершился, проверьте DNS и правила входящего
|
||
трафика у провайдера VPS, затем запустите ту же команду ещё раз. Этот вариант
|
||
не использует Nginx Proxy Manager и не требует входа в какую-либо панель.
|
||
|
||
Остановить быструю установку, не удаляя секрет и сертификат:
|
||
|
||
```sh
|
||
docker compose --env-file .env -f compose.yml -f compose.quick.yml down
|
||
```
|
||
|
||
Повторно запустить:
|
||
|
||
```sh
|
||
docker compose --env-file .env -f compose.yml -f compose.quick.yml up -d
|
||
```
|
||
|
||
Ниже описан второй, отдельный вариант для сервера, где Nginx Proxy Manager уже
|
||
установлен.
|
||
|
||
## Схема работы
|
||
|
||
```text
|
||
Telegram с поддержкой WEB proxy
|
||
-> HTTPS / WebSocket, порт 443
|
||
Nginx Proxy Manager
|
||
-> tg-web-proxy:8088
|
||
WEB relay
|
||
-> локальный MTProxy
|
||
-> дата-центры Telegram
|
||
```
|
||
|
||
Обычный запрос к домену показывает небольшую нейтральную страницу. Запрос от
|
||
поддерживаемого клиента получает защищённый bridge и используется как транспорт
|
||
для Telegram.
|
||
|
||
## Что потребуется
|
||
|
||
- сервер `x86_64` с Linux;
|
||
- Docker Engine и плагин Docker Compose;
|
||
- работающий Nginx Proxy Manager на том же Docker-хосте;
|
||
- отдельное доменное имя, например `proxy.example.com`;
|
||
- DNS-запись `A`, указывающая на публичный IPv4 сервера;
|
||
- исходящий доступ по HTTPS для сборки образа и загрузки конфигурации Telegram.
|
||
|
||
Публичный IPv4 и домен в репозитории не сохраняются. Инсталлятор записывает их
|
||
только в локальный файл `.env`, который исключён из Git.
|
||
|
||
## 1. Подготовьте DNS
|
||
|
||
Создайте у DNS-провайдера запись:
|
||
|
||
| Тип | Имя | Значение |
|
||
| --- | --- | --- |
|
||
| `A` | выбранный поддомен | публичный IPv4 Docker-хоста |
|
||
|
||
Дождитесь обновления DNS. Если на домене включено проксирование CDN, на время
|
||
первой проверки лучше использовать обычную DNS-запись без дополнительного
|
||
прокси между клиентом и Nginx Proxy Manager.
|
||
|
||
## 2. Скачайте и запустите установщик
|
||
|
||
Скопируйте URL репозитория на его странице в Gitea, затем выполните на
|
||
Docker-хосте:
|
||
|
||
```sh
|
||
git clone <URL_РЕПОЗИТОРИЯ>
|
||
cd telegram-web-proxy-stack
|
||
./install.sh
|
||
```
|
||
|
||
Установщик запросит только необходимые значения:
|
||
|
||
1. публичное доменное имя прокси;
|
||
2. публичный IPv4 Docker-хоста;
|
||
3. Docker-сеть Nginx Proxy Manager, если её не удалось определить автоматически.
|
||
|
||
Два криптографических секрета генерируются локально. Они не отправляются в
|
||
Gitea, не записываются в `.env` и остаются в Docker-томе
|
||
`tg_webproxy_data`.
|
||
|
||
Для автоматической установки те же параметры можно передать явно:
|
||
|
||
```sh
|
||
./install.sh \
|
||
--hostname proxy.example.com \
|
||
--public-ip <ПУБЛИЧНЫЙ_IPV4> \
|
||
--npm-network <DOCKER_СЕТЬ_NPM> \
|
||
--yes
|
||
```
|
||
|
||
После успешного запуска установщик выведет параметры для Nginx Proxy Manager и
|
||
секрет клиента. Сохраните секрет в надёжном месте и не публикуйте вывод
|
||
установщика.
|
||
|
||
## 3. Настройте Nginx Proxy Manager
|
||
|
||
Откройте **Hosts → Proxy Hosts → Add Proxy Host** и заполните поля:
|
||
|
||
| Поле | Значение |
|
||
| --- | --- |
|
||
| Domain Names | домен, введённый при установке |
|
||
| Scheme | `http` |
|
||
| Forward Hostname / IP | `tg-web-proxy` |
|
||
| Forward Port | `8088` |
|
||
| Websockets Support | включено |
|
||
| Block Common Exploits | допустимо включить |
|
||
|
||
На вкладке **SSL**:
|
||
|
||
1. запросите или выберите сертификат для этого домена;
|
||
2. включите **Force SSL**;
|
||
3. включите **HTTP/2 Support**;
|
||
4. сохраните Proxy Host.
|
||
|
||
Nginx Proxy Manager и `tg-web-proxy` должны находиться в одной Docker-сети.
|
||
Публиковать порт `8088` на самом сервере не требуется.
|
||
|
||
## 4. Проверьте сервер
|
||
|
||
Откройте в браузере ваш домен по HTTPS. Должна появиться нейтральная страница,
|
||
а сертификат должен определяться как действительный.
|
||
|
||
Проверить состояние контейнера можно так:
|
||
|
||
```sh
|
||
docker ps --filter name=tg-web-proxy
|
||
docker logs --tail 100 tg-web-proxy
|
||
```
|
||
|
||
Не публикуйте журналы без просмотра: в диагностических данных могут оказаться
|
||
сведения о вашей конфигурации.
|
||
|
||
## 5. Подключите Telegram
|
||
|
||
В клиенте с поддержкой WEB proxy откройте настройки соединения и добавьте новый
|
||
прокси типа **WEB**. Введите:
|
||
|
||
| Поле | Значение |
|
||
| --- | --- |
|
||
| Сервер | только домен, например `proxy.example.com` |
|
||
| Секрет | 32-символьный секрет, выведенный `install.sh` |
|
||
|
||
В поле сервера не нужно добавлять `https://`, порт, параметры запроса или символ
|
||
`/` в конце. Для корневой конфигурации порт `443` используется автоматически.
|
||
|
||
Если клиент поддерживает ссылки WEB proxy, можно сформировать локально:
|
||
|
||
```text
|
||
tg://webproxy?server=proxy.example.com&secret=<СЕКРЕТ_КЛИЕНТА>
|
||
```
|
||
|
||
Не публикуйте эту ссылку: содержащийся в ней секрет предоставляет доступ к
|
||
прокси. Адрес bridge с параметром `?bridge=` также считается секретным.
|
||
|
||
## Обновление
|
||
|
||
Получите проверенные изменения и снова запустите установщик:
|
||
|
||
```sh
|
||
git pull --ff-only
|
||
./install.sh
|
||
```
|
||
|
||
Именованный Docker-том сохраняется, поэтому клиентский секрет не меняется при
|
||
обычном обновлении. Не удаляйте том `tg_webproxy_data`, если хотите сохранить
|
||
действующие подключения.
|
||
|
||
## Остановка
|
||
|
||
Остановить контейнер, сохранив данные и секреты:
|
||
|
||
```sh
|
||
docker compose --env-file .env down
|
||
```
|
||
|
||
Повторный запуск:
|
||
|
||
```sh
|
||
docker compose --env-file .env up -d
|
||
```
|
||
|
||
## Частые проблемы
|
||
|
||
### Nginx Proxy Manager показывает 502
|
||
|
||
- проверьте, что контейнер `tg-web-proxy` запущен и имеет статус `healthy`;
|
||
- убедитесь, что оба контейнера подключены к одной Docker-сети;
|
||
- проверьте имя `tg-web-proxy` и порт `8088` в Proxy Host.
|
||
|
||
### Домен не открывается по HTTPS
|
||
|
||
- проверьте DNS-запись `A`;
|
||
- убедитесь, что входящие порты `80` и `443` доступны Nginx Proxy Manager;
|
||
- проверьте выпуск и срок действия сертификата.
|
||
|
||
### Страница открывается, но Telegram не подключается
|
||
|
||
- убедитесь, что в клиенте действительно доступен тип прокси `WEB`;
|
||
- используйте только домен без схемы и порта;
|
||
- перепроверьте секрет клиента;
|
||
- убедитесь, что в Nginx Proxy Manager включена поддержка WebSocket;
|
||
- не включайте перенаправление на другой домен.
|
||
|
||
### Установщик не находит сеть Nginx Proxy Manager
|
||
|
||
Посмотрите сети контейнера Nginx Proxy Manager в Portainer или Docker и
|
||
запустите установщик с параметром `--npm-network`.
|
||
|
||
## Безопасность перед публикацией изменений
|
||
|
||
Не добавляйте в Git `.env`, клиентский секрет, bridge-ссылки, файлы ключей,
|
||
экспорт Docker-тома или резервную копию Portainer.
|
||
|
||
Перед публикацией запускайте:
|
||
|
||
```sh
|
||
./scripts/audit-public.sh
|
||
```
|
||
|
||
Для проверки собственных доменов, сетей и других частных идентификаторов можно
|
||
создать локальный файл `.audit-private-patterns`, записав по одному точному
|
||
значению в строке. Этот файл исключён из Git и не публикуется.
|
||
|
||
Дополнительные эксплуатационные проверки и порядок отката описаны в
|
||
[`docs/runbook.md`](docs/runbook.md).
|