local_machine/docs/connectivity/TELEGRAM_GUIDE.md

Telegram через SOCKS-туннель (ru.hunab.app)

Трафик Telegram идёт через прокси 149.154.64.19 по SOCKS5 на 127.0.0.1:1081. Гайд для быстрых команд и для настройки с нуля на новой машине.

---

⚡ Быстрые команды

# Поднять туннель вручную
./docs/connectivity/scripts/telegram-socks-tunnel.sh start

# Проверить, слушается ли порт
lsof -i :1081

# Статус туннеля
./docs/connectivity/scripts/telegram-socks-tunnel.sh status

# Остановить туннель
./docs/connectivity/scripts/telegram-socks-tunnel.sh stop

# Включить автозапуск при входе (один раз)
./docs/connectivity/launchd/install.sh

# Отключить автозапуск
./docs/connectivity/launchd/uninstall.sh

# Проверить доступ к Telegram API через прокси
curl -x socks5h://127.0.0.1:1081 -sI https://api.telegram.org | head -3

В Telegram: Настройки → Данные и память → Прокси → добавить SOCKS5, 127.0.0.1, порт 1081.

---

Полный гайд: новая машина (порядок действий)

1. Требования

• macOS (для LaunchAgent; на Linux можно использовать systemd или скрипт в автозагрузке).
• Доступ по SSH к 149.154.64.19 под пользователем ahau (ключ в ~/.ssh/ или алиас в ~/.ssh/config, например hsites-ahau).
• Репозиторий local_machine склонирован (нужны скрипты из docs/connectivity/).

2. Проверка SSH

Убедись, что вход без пароля работает:

ssh -o BatchMode=yes -o ConnectTimeout=10 ahau@149.154.64.19 "echo OK"

Если просит пароль или ключ не подхватывается — настрой ~/.ssh/config или укажи ключ явно: ssh -i ~/.ssh/id_ed25519 ahau@149.154.64.19.

3. Поднять туннель вручную (первый раз)

Из корня репо:

./docs/connectivity/scripts/telegram-socks-tunnel.sh start

Ожидаемый вывод: SOCKS tunnel started: 127.0.0.1:1081 -> ahau@149.154.64.19.

Проверка порта:

lsof -i :1081

Должен быть процесс ssh в состоянии LISTEN.

4. Настройка прокси в Telegram

1. Открой Telegram (Desktop или мобильное приложение).
2. Настройки (Settings) → Данные и память (Data and Storage) → Прокси (Proxy).
3. Добавить прокси (Add Proxy):
   • Тип: SOCKS5
   • Сервер: 127.0.0.1
   • Порт: 1081
   • Логин/пароль — не нужны.
4. Сохрани и включи прокси.

После этого Telegram должен подключаться через туннель. Если не подключается — см. раздел Проверка и диагностика ниже.

5. Автозапуск туннеля при входе в систему (macOS)

Чтобы не запускать туннель вручную после каждой перезагрузки:

./docs/connectivity/launchd/install.sh

Скрипт копирует plist в ~/Library/LaunchAgents/ и загружает его. Дальше при каждом входе в систему туннель будет подниматься сам (и перезапускаться при обрыве).

Важно: при старте системы SSH должен иметь доступ к ключу. Добавь ключ в связку с keychain (один раз):

ssh-add --apple-use-keychain
# или, если ключ не дефолтный:
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Проверка после перезагрузки:

lsof -i :1081
./docs/connectivity/scripts/telegram-socks-tunnel.sh status

6. Проверка и диагностика

Туннель слушает порт?

lsof -i :1081 -sTCP:LISTEN

Доступ к API Telegram через SOCKS?

curl -x socks5h://127.0.0.1:1081 -sI https://api.telegram.org | head -5

Успех: в ответе есть HTTP-заголовки (например 302 или 200). Таймаут или отказ — туннель не работает или порт занят.

Лог LaunchAgent (если туннель при старте не поднимается):

tail -50 /tmp/telegram-socks-tunnel.log

Типичные причины: ключ не в keychain, ошибка «Permission denied», сеть ещё недоступна при RunAtLoad.

7. Конфликты портов

Порт	Назначение
1081	Telegram SOCKS (этот гайд)
10809	Cursor IDE SOCKS (другой туннель)

Если на 1081 уже висит другой прокси (например Shadowsocks), смени порт в plist и в настройках Telegram или отключи автозапуск: ./docs/connectivity/launchd/uninstall.sh.

8. Ссылки

• PROXY_GUIDE.md — общее руководство по прокси ru.hunab.app (SSH, Nginx, Cursor, scp).
• launchd/README.md — детали LaunchAgent (удаление, ThrottleInterval, логи).