# 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`.

Подключитесь к VPS по SSH и целиком скопируйте этот блок команд:

```sh
sudo apt update
sudo apt install -y git
git clone https://gitea.sibdata.ru/dir/telegram-web-proxy-stack.git
cd telegram-web-proxy-stack
sudo ./quick-install.sh
```

После запуска нужно ввести только подготовленный домен. Пароли или токены
Gitea для публичного репозитория не требуются.

Можно случайно вставить домен вместе с `https://` — установщик уберёт схему и
лишний путь. После проверки DNS он автоматически:

1. установит системные компоненты и Docker из официального репозитория;
2. соберёт Telegram WEB proxy;
3. запустит Caddy и выпустит HTTPS-сертификат;
4. проверит уникальным ответом, что домен открывает именно этот прокси;
5. покажет сервер, секрет и готовую ссылку подключения.

Для автоматического запуска домен разрешается передать сразу:

```sh
sudo ./quick-install.sh --domain proxy.example.com
```

Секрет сохраняется в Docker-томе и остаётся прежним при повторном запуске.
Для обновления используйте только быстрый установщик:

```sh
git pull --ff-only
sudo ./quick-install.sh
```

Если проверка домена или выпуск сертификата не завершились, проверьте DNS и
правила входящего трафика у провайдера VPS, затем запустите ту же команду ещё
раз. Успешная установка означает, что DNS, сертификат и ответ именно этого
экземпляра прокси проверены автоматически. Этот вариант не использует 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 https://gitea.sibdata.ru/dir/telegram-web-proxy-stack.git
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).