hunabgit/local_machine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Expand local_machine docs and automation for connectivity, games, and ops.

Browse Source 
Add proxy/VPN/telegram launchd and emergency runbooks; reorganize apps docs;
document JA3 CrossOver runbook and Wine troubleshooting; add GOG/HoMM game
scripts, disk cleanup guides, and gitea push-via-proxy helper. Ignore temp/.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
ahauimix
2026-06-01 08:12:19 +03:00
parent a39ef89125
commit 1938b7c743
135 changed files with 9933 additions and 388 deletions
Download Patch File Download Diff File Expand all files Collapse all files

299
docs/connectivity/TELEGRAM_GUIDE.md
View File

@@ -1,146 +1,213 @@
# Telegram через SOCKS-туннель (ru.hunab.app)
# Telegram через SOCKS (RU-прокси → DigitalOcean)
Трафик Telegram идёт через прокси 149.154.64.19 по SOCKS5 на **127.0.0.1:1081**. Гайд для быстрых команд и для настройки с нуля на новой машине.
На Mac поднимается **SOCKS5** на **127.0.0.1:1081**. Для выхода в интернет с **IP DO** используется **только** цепочка **Mac → 149.154.64.19 → DO (209.38.32.21)** (`telegram-socks-via-do`). Без доступа к RU автоматический SOCKS «напрямую в DO» **не** поднимается. Подробности: [PROXY_GUIDE.md](./PROXY_GUIDE.md).
Все пути ниже — от корня репозитория **local_machine**.
---
## ⚡ Быстрые команды
## Быстрые команды
### Туннель вручную (основной: только Mac→RU→DO)
```bash
# Поднять туннель вручную
export TELEGRAM_SOCKS_VIA_DO=1
./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
Убедись, что вход без пароля работает:
```bash
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. Поднять туннель вручную (первый раз)
Из корня репо:
```bash
./docs/connectivity/scripts/telegram-socks-tunnel.sh start
```
Ожидаемый вывод: `SOCKS tunnel started: 127.0.0.1:1081 -> ahau@149.154.64.19`.
Проверка порта:
```bash
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)
Чтобы не запускать туннель вручную после каждой перезагрузки:
```bash
./docs/connectivity/launchd/install.sh
```
Скрипт копирует plist в `~/Library/LaunchAgents/` и загружает его. Дальше при каждом входе в систему туннель будет подниматься сам (и перезапускаться при обрыве).
**Важно:** при старте системы SSH должен иметь доступ к ключу. Добавь ключ в связку с keychain (один раз):
```bash
ssh-add --apple-use-keychain
# или, если ключ не дефолтный:
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
```
Проверка после перезагрузки:
```bash
lsof -i :1081
./docs/connectivity/scripts/telegram-socks-tunnel.sh status
```
### 6. Проверка и диагностика
**Туннель слушает порт?**
### Проверка порта и API Telegram
```bash
lsof -i :1081 -sTCP:LISTEN
curl -x socks5h://127.0.0.1:1081 -sI --connect-timeout 10 https://api.telegram.org | head -5
```
**Доступ к API Telegram через SOCKS?**
### Автозапуск после перезагрузки (via-DO + авто-fallback)
Скрипт **`~/Library/Application Support/hunab/telegram-socks-launch.sh`** ставится из репо командой ниже.
```bash
curl -x socks5h://127.0.0.1:1081 -sI https://api.telegram.org | head -5
./docs/connectivity/launchd/install-via-do.sh
./docs/connectivity/launchd/uninstall-via-do.sh
launchctl list | grep telegram-socks
launchctl kickstart -k "gui/$(id -u)/com.hunab.telegram-socks-via-do"
```
Успех: в ответе есть HTTP-заголовки (например 302 или 200). Таймаут или отказ — туннель не работает или порт занят.
Лог агента: `tail -50 /tmp/telegram-socks-tunnel-via-do.log`
**Лог LaunchAgent (если туннель при старте не поднимается):**
### Ключи в связку (один раз после смены ключей / сбоя SSH)
```bash
tail -50 /tmp/telegram-socks-tunnel.log
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
ssh-add --apple-use-keychain ~/.ssh/hunab_deploy_key
```
Типичные причины: ключ не в keychain, ошибка «Permission denied», сеть ещё недоступна при RunAtLoad.
### Прокси в Telegram (обязательно)
### 7. Конфликты портов
| Поле | Значение |
|------|----------|
| Тип | **SOCKS5** |
| Сервер | **127.0.0.1** |
| Порт | **1081** |
| Логин / пароль | *пусто* |
| Порт | Назначение |
|-------|------------|
| 1081 | Telegram SOCKS (этот гайд) |
| 10809 | Cursor IDE SOCKS (другой туннель) |
**Настройки → Данные и память → Прокси** — добавить, сохранить, **включить**.
Если на 1081 уже висит другой прокси (например Shadowsocks), смени порт в plist и в настройках Telegram или отключи автозапуск: `./docs/connectivity/launchd/uninstall.sh`.
---
### 8. Ссылки
## Регламент
- [PROXY_GUIDE.md](./PROXY_GUIDE.md) — общее руководство по прокси ru.hunab.app (SSH, Nginx, Cursor, scp).
- [launchd/README.md](./launchd/README.md) — детали LaunchAgent (удаление, ThrottleInterval, логи).
Документ задаёт **обязательные** правила и **порядок действий**. Отклонения — только осознанно (обрывы, DPI, конфликт портов).
### 1. Назначение
- Выход в интернет через **DO**; предпочтительно через **`hsites-ahau`**, при его недоступности — **прямой** SSH к DO (автоматически).
- Исключить работу Telegram **мимо** туннеля и конкуренцию на порту **1081**.
### 2. Обязательные нормы (всегда)
| № | Требование |
|---|------------|
| N1 | **Основной** сценарий: **`TELEGRAM_SOCKS_VIA_DO=1`** и/или LaunchAgent **`com.hunab.telegram-socks-via-do`**, не «только RU без DO», если с RU TLS до Telegram нестабилен. |
| N2 | В Telegram — **SOCKS5**, **127.0.0.1**, **1081**, без логина/пароля (см. таблицу в «Быстрые команды»). |
| N3 | На **1081** только наш `ssh -D`. Другие прокси (Shadowsocks, v2ray и т.п.) на этот порт **не ставить**. |
| N4 | В `~/.ssh/config` есть **`Host telegram-socks-via-do`** (с jump **`hsites-ahau`**) и **`hsites-ahau`** — [PROXY_GUIDE.md](./PROXY_GUIDE.md). |
| N5 | Ключи **id_ed25519** и **hunab_deploy_key** доступны SSH после входа: **связка ключей** (`ssh-add --apple-use-keychain`). |
| N6 | Для работы после перезагрузки: plist **`~/Library/LaunchAgents/com.hunab.telegram-socks-via-do.plist`** загружен. Ручной `start` без агента перезагрузку **не переживает**. |
| N7 | Не держать **два** LaunchAgent на **1081**: `com.hunab.telegram-socks` (только RU) и `com.hunab.telegram-socks-via-do` — **ровно один** вариант. |
### 3. Первоначальная настройка (один раз)
Порядок фиксирован (детальнее и варианты — раздел «Развёртывание с нуля»).
1. Проверка SSH (см. быстрые проверки в сценарии 1).
2. `~/.ssh/config`: **`Host telegram-socks-via-do`** по [PROXY_GUIDE.md](./PROXY_GUIDE.md).
3. `ssh-add --apple-use-keychain` для обоих ключей.
4. Снять старый агент only-RU при необходимости: `./docs/connectivity/launchd/uninstall.sh`.
5. `./docs/connectivity/launchd/install-via-do.sh`.
6. Настроить прокси в Telegram (таблица выше).
7. Контрольные проверки (п. 6).
### 4. Повседневная эксплуатация
| Ситуация | Действие |
|----------|----------|
| Обычный день | Ничего не запускать: туннель поднимает LaunchAgent после входа. |
| Ручной перезапуск туннеля | `stop` → `export TELEGRAM_SOCKS_VIA_DO=1` → `start` (см. быстрые команды). |
| После смены plist / обновления репо | `install-via-do.sh` или `kickstart` (см. быстрые команды). |
### 5. Норматив: клиент Telegram
Соответствует таблице в разделе **«Быстрые команды»**. Иначе нарушение N2.
### 6. Контрольные проверки
```bash
test -f "$HOME/Library/LaunchAgents/com.hunab.telegram-socks-via-do.plist" && echo "plist OK" || echo "FAIL: нет plist"
launchctl list | grep telegram-socks
lsof -i :1081 -sTCP:LISTEN
curl -x socks5h://127.0.0.1:1081 -sI --connect-timeout 10 https://api.telegram.org | head -5
```
Лог: `/tmp/telegram-socks-tunnel-via-do.log`.
### 7. Запреты и конфликты
- Не занимать **1081** сторонним ПО (N3).
- Не два LaunchAgent на 1081 (N7).
- Не отключать прокси в Telegram и ожидать тот же доступ «через туннель» (N2).
| Порт | Назначение |
|------|------------|
| **1081** | Telegram SOCKS |
| **10809** | Cursor IDE SOCKS |
### 8. Действия при сбое
1. П. 6 (контрольные проверки).
2. `tail -80 /tmp/telegram-socks-tunnel-via-do.log`.
3. **`Too many open files`**: обновить plist из репозитория, снова `install-via-do.sh`.
4. **`channel … open failed`**: часто сеть или следствие п.3; перезапуск туннеля после правок.
5. После правок `~/.ssh/config`: `stop` → `TELEGRAM_SOCKS_VIA_DO=1` → `start` или `kickstart`.
6. Прокси в Telegram по-прежнему включён (п. 5).
7. **`Connection timed out during banner exchange`** к RU: без доступа к **149.154.64.19** цепочка Mac→RU→DO **невозможна** — восстановите доступ к RU или временно используйте только-RU агент (`install.sh`) / другую сеть; автоматического SOCKS «напрямую в DO» нет.
### 9. Снятие автозапуска и откат
- Via-DO: `./docs/connectivity/launchd/uninstall-via-do.sh`.
- Переход на только-RU: `./docs/connectivity/launchd/install.sh` — см. **сценарий 2** ниже.
---
## Развёртывание с нуля (по сценариям)
Общие требования: **macOS**; репозиторий **local_machine**; SSH без пароля к **209.38.32.21:2222** (hunab, `hunab_deploy_key`) и к **149.154.64.19** (ahau) — для SOCKS через DO нужен **оба** hop (Mac→RU→DO).
### Сценарий 1: основной — macOS, автозапуск (только Mac→RU→DO)
Рекомендуемый вариант (регламент N1, N6).
1. Проверка SSH (для via-DO нужны **оба**):
```bash
ssh -o BatchMode=yes -o ConnectTimeout=10 ahau@149.154.64.19 "echo OK"
ssh -o BatchMode=yes -o ConnectTimeout=15 -i ~/.ssh/hunab_deploy_key -p 2222 hunab@209.38.32.21 "echo OK"
```
2. Добавить в `~/.ssh/config` блок **`Host telegram-socks-via-do`** — [PROXY_GUIDE.md](./PROXY_GUIDE.md).
3. `ssh-add --apple-use-keychain` для `id_ed25519` и `hunab_deploy_key`.
4. Если ранее стоял агент только-RU: `./docs/connectivity/launchd/uninstall.sh`.
5. `./docs/connectivity/launchd/install-via-do.sh`.
6. В Telegram — прокси по таблице в **«Быстрые команды»**.
7. Проверки из п. 6 регламента.
### Сценарий 2: только RU-прокси (без DO)
Если прямой выход с **149.154.64.19** до Telegram устойчив или для диагностики. **Не** ставить одновременно с via-DO на 1081 (N7).
**Ручной туннель:**
```bash
./docs/connectivity/scripts/telegram-socks-tunnel.sh start
```
**Автозапуск:** `./docs/connectivity/launchd/install.sh`
**Снятие:** `./docs/connectivity/launchd/uninstall.sh`
Перед переходом на сценарий 1 — `uninstall.sh`, затем сценарий 1 с шага 5.
### Сценарий 3: без LaunchAgent, только ручной туннель (via-DO)
Для отладки; после перезагрузки нужно снова поднимать вручную.
```bash
export TELEGRAM_SOCKS_VIA_DO=1
./docs/connectivity/scripts/telegram-socks-tunnel.sh start
```
Убедиться, что `~/.ssh/config` и ключи настроены как в сценарии 1 (шаги 1–3). Прокси в Telegram — как в таблице.
### Сценарий 4: смена с via-DO на only-RU или обратно
- **На only-RU:** `./docs/connectivity/launchd/uninstall-via-do.sh`, затем `./docs/connectivity/launchd/install.sh`.
- **Обратно на via-DO:** `./docs/connectivity/launchd/uninstall.sh`, затем `./docs/connectivity/launchd/install-via-do.sh`.
Каждый раз проверять: один plist на 1081, `launchctl list | grep telegram-socks`.
### Сценарий 5: Linux (без LaunchAgent)
Репозиторий и скрипт `docs/connectivity/scripts/telegram-socks-tunnel.sh`; автозапуск — **systemd**, **cron @reboot**, или ручной `start` как в сценарии 3. Plist macOS на Linux не используется.
---
## Ссылки
- [PROXY_GUIDE.md](./PROXY_GUIDE.md) — прокси ru.hunab.app, `Host telegram-socks-via-do`, scp.
- [launchd/README.md](./launchd/README.md) — LaunchAgent, логи, порты.