local_machine/docs/connectivity/PROXY_GUIDE.md

# 🔐 Прокси ru.hunab.app — руководство

**Сервер:** 149.154.64.19 | **Домен:** ru.hunab.app | **Прод:** hunab.app (209.38.32.21)

---

## Оглавление

1. [Схема соединений](#схема-соединений)
2. [Доступ и файлы](#-доступ-и-файлы)
3. [Клиентский SSH config и KexAlgorithms](#клиентский-ssh-config-и-kexalgorithms)
4. [Команды управления](#-команды-управления)
5. [Безопасность](#-безопасность)
6. [Запросы-сканеры (serverless и др.)](#-запросы-сканеры-serverless-и-др)
7. [Редирект на прокси](#-автоматический-редирект)
8. [Скорость и тесты](#-проверка-скорости)
9. [Telegram и SOCKS при старте](#-telegram-и-socks-при-старте)
10. [SSH к продакшену (hunab-prod)](#ssh-к-продакшену-hunab-prod)
11. [macOS: системный PAC](#-macos-системный-pac)

---

## Схема соединений

Текущая логика с **вашего Mac** (или другой клиентской машины с тем же `~/.ssh/config`):

```mermaid
flowchart TB
  subgraph client [Клиент]
    M["SSH, scp, Docker CLI,\nTelegram с SOCKS"]
  end
  RU["RU-прокси 149.154.64.19\nru.hunab.app, SSH 22, user ahau\n(Host hsites-ahau)"]
  DO["Прод 209.38.32.21 DigitalOcean\nSSH 2222, hunab / root\nDocker, Nginx, приложения"]
  NET["Интернет (выход с DO)"]

  M -->|"Основной: ssh hunab-prod,\nSOCKS telegram-socks-via-do"| RU
  RU -->|ProxyJump / туннель| DO
  M -->|"Прямой SSH: hunab-prod-direct\n(SOCKS через DO — только via-do)"| DO
  DO --> NET
```

**Кратко:**

| Направление | Как задаётся |
|-------------|----------------|
| Mac → RU | `ssh hsites-ahau`, первый прыжок в **ProxyJump** |
| RU → прод DO | Второй hop SSH на **209.38.32.21:2222** |
| Mac → прод без RU | `hunab-prod-direct`; **`telegram-socks-direct-do`** — тот же hop, для ручного SSH/scp, не для авто-SOCKS |
| Telegram / Cursor SOCKS → интернет с IP DO | Только **Mac→RU→DO** (`telegram-socks-via-do`); прямой Mac→DO в скриптах не используется |

Прод и RU — **разные** машины; ключи разные: к RU обычно **`id_ed25519`** (ahau), к проду на DO — **`hunab_deploy_key`**.

---

## 🔑 Доступ и файлы

| Параметр | Значение |
|----------|----------|
| **SSH** | `ssh hsites-ahau` или `ssh -i ~/.ssh/id_ed25519 ahau@149.154.64.19` |
| **SSH root** | `ssh -o StrictHostKeyChecking=accept-new -i ~/.ssh/hsites_new_deploy_key root@149.154.64.19` или `ssh hsites-new` |
| **Пользователь** | ahau (sudo), root через ключ `hsites_new_deploy_key` |
| **ОС** | Ubuntu 24.10 |

**Важные пути на сервере:**
- Nginx: `/etc/nginx/sites-available/ru.hunab.app` (активный сайт может быть в `sites-enabled` как `ru.hunab.app.proxy`)
- Логи: `/var/log/nginx/ru.hunab.app.proxy.access.log`, `ru.hunab.app.proxy.error.log`
- SSL: `/etc/letsencrypt/live/ru.hunab.app/`
- Кеш: `/var/cache/nginx/`

**Проверка:**
- Сайт: https://ru.hunab.app/
- Health: https://ru.hunab.app/proxy-health
- API: https://ru.hunab.app/api/health

### Клиентский SSH config и KexAlgorithms

Файл на той машине, **с которой** вы подключаетесь (обычно Mac):

- путь **`~/.ssh/config`**;
- на Mac это тот же путь в домашнем каталоге, например **`/Users/<ваш-логин>/.ssh/config`**.

Сюда добавляются `Host`, `ProxyJump`, ключи и при необходимости опции вроде **`KexAlgorithms`**.

#### Нельзя смешивать `hunab-prod` и `hunab-prod-root` в одном блоке `Host`

В одной строке **`Host hunab-prod hunab-prod-root`** может быть только **один** `User`. Если указать `User hunab`, то при вызове `ssh hunab-prod-root` клиент всё равно пойдёт как **hunab** — это **ошибка**.

**Правильно:** два отдельных блока — один с **`User hunab`**, второй с **`User root`** (и при необходимости разные `ControlPath` / алиасы).

**Можно** в одном блоке перечислить алиасы с **одним и тем же** пользователем и маршрутом, например: **`Host hunab-prod hunab-prod-via-ahau`** — оба имени ведут на прод как **hunab** через **`ProxyJump hsites-ahau`**.

#### Имеет ли смысл `KexAlgorithms`?

На актуальных **macOS** и **OpenSSH** на Ubuntu 24 набор алгоритмов обмена ключей по умолчанию уже **нормальный** (в т.ч. curve25519). Явно задавать **`KexAlgorithms`** стоит **не «на всякий случай»**, а когда есть **конкретная** проблема: сообщение вроде *Unable to negotiate … no matching key exchange method*, старый сервер или нестандартный посредник в сети.

**Минусы** жёсткого списка: если на сервере **sshd** не поддерживает ни один из перечисленных KEX, подключение **сломается**. Поэтому список должен **пересекаться** с тем, что включено на сервере (`ssh -Q kex` на клиенте, настройки `sshd_config` на сервере).

Если всё же добавляете — вставляйте строку **в каждый нужный блок отдельно** (`hunab-prod`, `hunab-prod-root`, при цепочке через RU при желании и **`Host hsites-ahau`**), **не объединяя** hunab и root в один блок из‑за разного `User`.

Пример **опционально** (без `ProxyJump` здесь не показан — в реальном конфиге сохраняйте свои `ProxyJump`, `Port`, `ControlPath` и т.д.):

```
Host hunab-prod
    HostName 209.38.32.21
    User hunab
    Port 2222
    IdentityFile ~/.ssh/hunab_deploy_key
    StrictHostKeyChecking accept-new
    IdentitiesOnly yes
    KexAlgorithms curve25519-sha256,curve25519-sha256@libssh.org,diffie-hellman-group-exchange-sha256

Host hunab-prod-root
    HostName 209.38.32.21
    User root
    Port 2222
    IdentityFile ~/.ssh/hunab_deploy_key
    StrictHostKeyChecking accept-new
    IdentitiesOnly yes
    KexAlgorithms curve25519-sha256,curve25519-sha256@libssh.org,diffie-hellman-group-exchange-sha256
```

У **текущего** репозиторийного сценария **`hunab-prod` по умолчанию через `hsites-ahau`** — в блок **`Host hunab-prod`** нужно добавлять и **`ProxyJump hsites-ahau`** (как в [TELEGRAM_GUIDE](./TELEGRAM_GUIDE.md) и полных шаблонах ниже), а не только поля из примера выше.

### SSH к продакшену (hunab-prod)

Прод: **209.38.32.21**, SSH **порт 2222**, пользователь **hunab** (или **root**), ключ **`hunab_deploy_key`**.

| Host в `~/.ssh/config` | Назначение |
|------------------------|------------|
| **hunab-prod** (и алиас **hunab-prod-via-ahau**) | **По умолчанию:** **Mac → hsites-ahau → прод**. Обычная команда `ssh -T hunab-prod 'docker …'` сразу идёт через RU — **не нужен** `export HUNAB_PROD_FORCE_VIA` (эта переменная только для скрипта `ssh-hunab-prod.sh`). |
| **hunab-prod-direct** | Прямое TCP к **209.38.32.21:2222** — когда RU недоступен, а DO доступен. |
| **hunab-prod-root** / **hunab-prod-root-via-ahau** | Root через **hsites-ahau**; **hunab-prod-root-direct** — прямой root. |
| **hunab-prod-via-ru**, **prod-ru** | ProxyJump через **hsites-new** (root); ключ **`hsites_new_deploy_key`**. |

**Два бэкенда в логах (пример):**

```bash
ssh -T hunab-prod 'docker logs -f --tail=80 hunab-prod-backend-green 2>&1 | sed -u "s/^/[GREEN] /" & docker logs -f --tail=80 hunab-prod-backend 2>&1 | sed -u "s/^/[BLUE ] /" & wait'
```

**Скрипт** `ssh-hunab-prod.sh` — при необходимости сначала пробует **hunab-prod-direct** (8 с), иначе **hunab-prod**:  
`HUNAB_PROD_FORCE_VIA=1` — сразу через RU; `HUNAB_PROD_FORCE_DIRECT=1` — только прямой.

Проверка: `ssh hunab-prod "echo OK"` (через RU), `ssh hunab-prod-direct "echo OK"` (прямой).

**Стабильность:** **ServerAliveInterval 30**, **ServerAliveCountMax 8**, **ControlMaster** / **ControlPersist 30m** на прод-хостах и **hsites-ahau**. Сброс: `ssh -O exit hunab-prod`, `ssh -O exit hunab-prod-direct`, при необходимости `rm -f ~/.ssh/cm-hunab-*`.

---

## 🔧 Команды управления

**Nginx:** `sudo nginx -t` → `sudo systemctl reload nginx`  
**SSL:** `sudo certbot certificates`, `sudo certbot renew --dry-run`  
**Безопасность:** `sudo ufw status`, `sudo fail2ban-client status`  
**Логи:** `sudo tail -f /var/log/nginx/ru.hunab.app.proxy.access.log`  
**Кеш:** `sudo du -sh /var/cache/nginx/`; очистка: `sudo rm -rf /var/cache/nginx/*` + reload

**Backup конфига:** `sudo cp /etc/nginx/sites-available/ru.hunab.app /home/ahau/nginx-backup-$(date +%Y%m%d).conf`

**Экстренно:** `sudo systemctl stop nginx`; после правок: `sudo nginx -t && sudo systemctl start nginx`

---

## 🛡️ Безопасность

Чеклист и готовые конфиги (rate limiting, fail2ban, отсечение сканеров, доверенный прокси на проде, логи без утечек):

📖 **[SECURITY.md](./SECURITY.md)** — чеклист и nginx/fail2ban-сниппеты.

Связь с общими стандартами:

📖 **[docs/security/SECURITY_STANDARDS.md](../../security/SECURITY_STANDARDS.md)** — раздел **Proxy & Edge Security (ru.hunab.app)**.

---

## 🔍 Запросы-сканеры (serverless и др.)

В логах прода с IP 149.154.64.19 видны запросы к `/api/serverless/*`, `serverless.yml`, `.serverless/` и т.п. — это **внешние боты**, не скрипты на прокси. Чтобы не гонять их на прод, на прокси добавляют `location` с `return 404` (см. [SECURITY.md](./SECURITY.md)).

---

## 🇷🇺 Автоматический редирект

Редирект пользователей из РФ на ru.hunab.app реализован на фронтенде (HTML + JS). Детали и тесты:

📖 **[AUTOMATIC_REDIRECT_SOLUTION.md](./AUTOMATIC_REDIRECT_SOLUTION.md)**

---

## 📤 Загрузка файлов на прод через туннель (scp)

Для передачи больших файлов (например, git bundle для очистки истории) на production (209.38.32.21) из РФ используйте SSH ProxyCommand через прокси:

```bash
# Туннель: локальная машина → 149.154.64.19 (прокси) → 209.38.32.21 (прод)
PROXY_CMD="ssh -i $HOME/.ssh/id_ed25519 -o StrictHostKeyChecking=accept-new -W %h:%p hsites-ahau"
scp -i ~/.ssh/hunab_deploy_key -o ProxyCommand="$PROXY_CMD" -o ServerAliveInterval=15 \
  /path/to/file.bundle hunab@209.38.32.21:/home/hunab/
```

Проверка размера файла на сервере (через тот же туннель):

```bash
ssh -i ~/.ssh/hunab_deploy_key -o ProxyCommand="$PROXY_CMD" hunab@209.38.32.21 "ls -la /home/hunab/file.bundle"
```

---

## 📊 Проверка скорости

Через прокси соединение до прода быстрее, чем прямо из РФ. Замеры: ~0.29s через ru.hunab.app vs ~3.2s напрямую. Для проверки с прокси-сервера к проду: `expect temp/check_connection_speed.sh` (с локальной машины).

---

## Cursor IDE (PING timeout из РФ)

Если Cursor выдаёт **PING timed out** при работе из России, трафик можно пустить через SOCKS (SSH `-D`) на **127.0.0.1:10809**. Скрипт **`docs/cursor/scripts/cursor-socks-tunnel.sh`** при **`CURSOR_SOCKS_VIA_DO=1`** поднимает **только Mac→RU→DO** (`telegram-socks-via-do`); без доступа к RU — ошибка (без прямого Mac→DO). **`CURSOR_SOCKS_VIA_DO=0`** — выход только с RU (`hsites-ahau`).

📖 **[docs/cursor/README.md](../cursor/README.md)** — пошагово, проверки и Windows (`cursor-socks-tunnel.ps1`).

---

## 🖥️ macOS: системный PAC

В **Системных настройках → Сеть** на Mac может быть включён **автоматический прокси** с файлом конфигурации **PAC** (часто `http://localhost:1089/proxy.pac`). Пока PAC включён, браузер и часть приложений ходят в интернет по правилам из PAC; для **локальной админки роутера** (`192.168.x.x`), **чистого Wi‑Fi без прокси** или диагностики удобно **временно выключить** PAC и потом снова включить.

**Важно:** если PAC **включён**, а по выбранному URL **ничего не слушает** (например, порт **1089** пуст), macOS и приложения ведут себя непредсказуемо; при **смене хотспота** часто кажется, что «сеть мёртвая до перезагрузки». Это не баг Wi‑Fi как такового, а **нерабочий PAC + кэш DNS**. Скрипт восстановления и пошаговый emergency: **[HOTSPOT_NETWORK_EMERGENCY.md](./HOTSPOT_NETWORK_EMERGENCY.md)** (`macos-hotspot-network-recover.sh`).

**Быстрые скрипты** (из корня репозитория):

```bash
./docs/connectivity/scripts/macos-pac-on.sh   # включить PAC (URL + состояние On)
./docs/connectivity/scripts/macos-pac-off.sh  # выключить PAC (URL не стирается, только Off)
./docs/connectivity/scripts/macos-system-pac.sh status  # что сейчас в networksetup и scutil
```

Полный вариант одной командой: `./docs/connectivity/scripts/macos-system-pac.sh on|off|status`.

**Переопределения через окружение:**

- **`MACOS_PAC_URL`** — по умолчанию `http://localhost:1089/proxy.pac`.
- **`MACOS_PAC_SERVICES`** — список имён сетевых сервисов **через символ `|`** (как в `networksetup -listallnetworkservices`). По умолчанию: `Wi-Fi|Thunderbolt Bridge 2`.

Пример только для Wi‑Fi: `MACOS_PAC_SERVICES=Wi-Fi ./docs/connectivity/scripts/macos-pac-off.sh`

Убедитесь, что процесс, который отдаёт PAC по выбранному URL (порт **1089**), запущен, иначе после `on` приложения могут не открывать сайты.

---

## 📱 Telegram и SOCKS при старте

Для стабильной связи Telegram (и других приложений) через тот же прокси поднимают SOCKS5 на **127.0.0.1:1081**:

```bash
ssh -D 1081 ahau@149.154.64.19
```

Порт **1081** не пересекается с туннелем Cursor (**10809**).

### Запуск при входе в систему (macOS)

Чтобы туннель поднимался при логине и перезапускался при обрыве:

```bash
cp connectivity/launchd/com.hunab.telegram-socks.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.hunab.telegram-socks.plist
```

Подробности и снятие с автозапуска: **[connectivity/launchd/README.md](./launchd/README.md)**.

### Ручное управление

Скрипт из репо (start/stop/status):

```bash
./connectivity/scripts/telegram-socks-tunnel.sh start   # поднять
./connectivity/scripts/telegram-socks-tunnel.sh status # проверить
./connectivity/scripts/telegram-socks-tunnel.sh stop   # остановить
```

В Telegram (или другом клиенте) укажите прокси: **SOCKS5**, **127.0.0.1**, порт **1081**.

### Выход через DigitalOcean (прокси → DO → интернет)

Если с **149.154.64.19** до инфраструктуры Telegram TLS не проходит (типично DPI), поднимите SOCKS так, чтобы **трафик выходил в интернет с прод-сервера DO** (209.38.32.21), а до RU-прокси шёл только SSH. Цепочка: **Mac → hsites-ahau (149.154.64.19) → hunab@209.38.32.21:2222**.

**Вручную:**

```bash
ssh -D 1081 -N -J hsites-ahau -i ~/.ssh/hunab_deploy_key -p 2222 hunab@209.38.32.21
```

**Скрипт из репо** (те же параметры по умолчанию):

```bash
export TELEGRAM_SOCKS_VIA_DO=1
./docs/connectivity/scripts/telegram-socks-tunnel.sh start
```

Переменные при необходимости: `TELEGRAM_SOCKS_JUMP_HOST`, `TELEGRAM_SOCKS_FINAL_HOST`, `TELEGRAM_SOCKS_FINAL_PORT` (по умолчанию 2222), `TELEGRAM_SOCKS_FINAL_IDENTITY`.

**`~/.ssh/config`** — удобно для LaunchAgent без длинной строки `ssh`:

```
Host telegram-socks-via-do
    HostName 209.38.32.21
    User hunab
    Port 2222
    IdentityFile ~/.ssh/hunab_deploy_key
    ProxyJump hsites-ahau
    StrictHostKeyChecking accept-new
    ServerAliveInterval 60
    ServerAliveCountMax 4
    ConnectTimeout 60
    TCPKeepAlive yes
    IPQoS throughput
    UseKeychain yes
    AddKeysToAgent yes
```

**Прямой SSH к DO** (без RU в цепочке) — для админки вроде `hunab-prod-direct`, **не** для автоматического SOCKS «в обход RU»:

```
Host telegram-socks-direct-do
    HostName 209.38.32.21
    User hunab
    Port 2222
    IdentityFile ~/.ssh/hunab_deploy_key
    StrictHostKeyChecking accept-new
    ServerAliveInterval 60
    ServerAliveCountMax 4
    ConnectTimeout 60
    TCPKeepAlive yes
    IPQoS throughput
    UseKeychain yes
    AddKeysToAgent yes
```

Скрипты **`TELEGRAM_SOCKS_VIA_DO=1`**, **`cursor-socks-tunnel.sh`** при выходе через DO и LaunchAgent **не** переключаются на этот host — только **Mac→RU→DO** через `telegram-socks-via-do`.

Проверка SOCKS: `ssh -D 1081 -N telegram-socks-via-do` (в другом терминале: `curl -x socks5h://127.0.0.1:1081 -sI https://api.telegram.org | head -3`).

**Автозапуск (macOS):** `./docs/connectivity/launchd/install-via-do.sh` копирует `telegram-socks-launch.sh`, который всегда запускает **`telegram-socks-via-do`** (Mac→RU→DO). Лог: `/tmp/telegram-socks-tunnel-via-do.log`. Старый RU-only агент: `./docs/connectivity/launchd/uninstall.sh`. Вернуть только RU: `./docs/connectivity/launchd/uninstall-via-do.sh` и `./docs/connectivity/launchd/install.sh`.

---

## SSL

Сертификат Let's Encrypt, обновление через certbot (timer). При первичной настройке или смене домена: временно nginx без SSL → certbot → включить полный конфиг с SSL. Скрипты в папке: `get-ssl-certificate.sh`, `setup-ssl-auto-renewal.sh` (при необходимости).