# Harbor

Harbor помогает пользоваться одной VPN-подпиской дома и на Mac без ручной настройки `sing-box`.

Проект работает в двух режимах:

| Режим | Где работает | Для чего нужен |
| --- | --- | --- |
| **Harbor Gateway** | На отдельной Linux-машине | Проводит через VPN весь интернет-трафик домашних устройств или работает как общий HTTP/SOCKS5-прокси |
| **Harbor Connect** | На macOS | Даёт приложениям на Mac локальный HTTP/SOCKS5-прокси |

В обоих режимах управление одинаковое: откройте веб-интерфейс, вставьте ссылку VPN-подписки, выберите сервер и нажмите кнопку подключения.

## Что понадобится

- ссылка на подписку от VPN-провайдера;
- Git;
- Docker с командой `docker compose`;
- для Gateway — Linux-машина в одной локальной сети с устройствами;
- для Connect — Mac с запущенным Docker Desktop.

Harbor не является VPN-провайдером и не создаёт подписки самостоятельно.

## Что выбрать

Используйте **Harbor Connect**, если VPN нужен только приложениям на одном Mac.

Используйте **Harbor Gateway**, если нужно подключить телевизор, телефон, игровую приставку или сразу несколько устройств. Устройства можно направить через Gateway целиком либо настроить в отдельных приложениях общий прокси.

Оба режима можно использовать вместе. Дома Connect автоматически распознаёт настроенный Harbor Gateway и не запускает второй VPN-маршрут. В другой сети Connect возвращается к локальному VPN.

## Установка Harbor Gateway

### 1. Скачайте проект

```bash
git clone https://git.dokops.ru/dokril/vpn-proxy.git
cd vpn-proxy
```

### 2. Создайте настройки

```bash
cp .env.example .env
```

Стандартные значения подходят для обычной домашней сети. При необходимости откройте `.env` в текстовом редакторе и измените порты.

### 3. Запустите Gateway

```bash
docker compose -f docker-compose.gateway.yml up -d --build
```

Откройте в браузере:

```text
http://АДРЕС-GATEWAY:3456
```

Например, если Linux-машина имеет адрес `192.168.1.20`, интерфейс будет доступен по адресу `http://192.168.1.20:3456`.

### 4. Добавьте подписку

1. Вставьте ссылку VPN-подписки.
2. Нажмите «Сохранить подписку».
3. Выберите сервер.
4. Включите VPN.

После подключения Harbor покажет два варианта использования:

- **Gateway** — укажите IP-адрес Linux-машины как основной шлюз устройства. Через VPN пойдёт весь его интернет-трафик;
- **Gateway Proxy** — укажите адрес Linux-машины и порт `8080` в приложении. Поддерживаются HTTP и SOCKS5 на одном порту.

Приватные и локальные адреса не отправляются в VPN, поэтому устройства сохраняют доступ к домашней сети. Общий прокси по умолчанию принимает подключения только из приватных сетей.

## Установка Harbor Connect на macOS

### 1. Запустите Docker Desktop

Установщик проверит наличие Git, Docker, Docker Compose и `curl`. Если Docker Desktop не запущен, установка остановится с понятным сообщением.

### 2. Скачайте проект и запустите установщик

```bash
git clone https://git.dokops.ru/dokril/vpn-proxy.git
cd vpn-proxy
./scripts/install-macos-client.sh
```

Установщик:

- сохранит рабочую копию в `~/.vpn-proxy-client`;
- предложит порт для локального прокси;
- соберёт и запустит контейнер Harbor Connect;
- добавит пользовательский LaunchAgent для определения текущего Gateway.

По умолчанию используются адреса:

| Назначение | Адрес |
| --- | --- |
| Интерфейс Harbor Connect | `http://127.0.0.1:3456` |
| HTTP-прокси | `127.0.0.1:8082` |
| SOCKS5-прокси | `127.0.0.1:8082` |

### 3. Добавьте подписку

Откройте `http://127.0.0.1:3456`, вставьте ссылку подписки, выберите сервер и включите VPN.

Сам по себе локальный прокси не перенаправляет приложения автоматически. Адрес `127.0.0.1:8082` нужно указать в настройках нужного приложения или в системных настройках macOS.

### Другие порты

Передайте нужные значения при повторном запуске установщика:

```bash
VPN_PROXY_CLIENT_PORT=9080 \
VPN_PROXY_CLIENT_UI_PORT=3457 \
./scripts/install-macos-client.sh
```

Допустимы порты от `1024` до `65535`. Установщик не позволит выбрать занятый порт или один порт одновременно для интерфейса и прокси.

## Локальные правила маршрутизации

После добавления подписки откройте «Локальные правила» справа от основного экрана. Встроенное правило `*.ru` всегда отправляет российские домены напрямую. Дополнительно можно добавить точный домен, suffix домена или фрагмент имени; эти правила также обходят VPN, а остальной трафик идёт через выбранный сервер.

Полный URL можно вставить в поле точного домена, но Harbor сохранит только hostname. Путь и параметры HTTPS зашифрованы и недоступны sing-box на уровне маршрутизации. GeoSite, GeoIP и подключаемые списки пока не поддерживаются.

## Системный прокси macOS

Сначала посмотрите точное имя сетевого подключения:

```bash
networksetup -listallnetworkservices
```

Для подключения с именем `Wi-Fi` включите HTTP, HTTPS и SOCKS5-прокси:

```bash
networksetup -setwebproxy Wi-Fi 127.0.0.1 8082
networksetup -setsecurewebproxy Wi-Fi 127.0.0.1 8082
networksetup -setsocksfirewallproxy Wi-Fi 127.0.0.1 8082
```

Чтобы отключить их:

```bash
networksetup -setwebproxystate Wi-Fi off
networksetup -setsecurewebproxystate Wi-Fi off
networksetup -setsocksfirewallproxystate Wi-Fi off
```

Если сетевое подключение называется иначе, замените `Wi-Fi` его точным именем.

## Автоматическое использование домашнего Gateway

Harbor Connect раз в пять секунд узнаёт у macOS адрес текущего основного шлюза. Если по этому адресу работает Harbor Gateway с той же VPN-подпиской, Connect оставляет локальный прокси доступным для приложений, но не создаёт второй VPN-маршрут: трафик уже обрабатывает Gateway.

Для этого:

1. добавьте одну и ту же ссылку подписки в Gateway и Connect;
2. убедитесь, что Mac может открыть интерфейс Gateway на порту `3456`;
3. оставьте автоматический режим включённым в Harbor Connect.

Ссылка должна содержать персональный секрет или token длиной не менее 16 символов — обычные ссылки подписок уже соответствуют этому условию. Ссылка между устройствами не передаётся: она используется локально для проверки, что Connect нашёл именно ваш Gateway. При смене сети или после трёх неудачных проверок Connect возвращается к локальному VPN.

## Повседневные команды

Все команды Gateway выполняются из каталога проекта. Команды Connect — из `~/.vpn-proxy-client`.

### Harbor Gateway

| Действие | Команда |
| --- | --- |
| Запустить или обновить после изменения файлов | `docker compose -f docker-compose.gateway.yml up -d --build` |
| Обновить только интерфейс и управление | `docker compose -f docker-compose.gateway.yml build vpn-proxy-control && docker compose -f docker-compose.gateway.yml up -d --no-deps vpn-proxy-control` |
| Показать состояние | `docker compose -f docker-compose.gateway.yml ps` |
| Смотреть журнал | `docker compose -f docker-compose.gateway.yml logs -f` |
| Перезапустить только интерфейс и управление | `docker compose -f docker-compose.gateway.yml restart vpn-proxy-control` |
| Перезапустить VPN dataplane | `docker compose -f docker-compose.gateway.yml restart vpn-proxy-dataplane` |
| Остановить | `docker compose -f docker-compose.gateway.yml down` |
| Удалить вместе с сохранёнными данными | `docker compose -f docker-compose.gateway.yml down -v` |

### Harbor Connect

```bash
cd ~/.vpn-proxy-client
```

| Действие | Команда |
| --- | --- |
| Обновить и снова запустить | `./scripts/install-macos-client.sh` |
| Показать состояние | `docker compose -f docker-compose.client.yml ps` |
| Смотреть журнал | `docker compose -f docker-compose.client.yml logs -f` |
| Перезапустить | `docker compose -f docker-compose.client.yml restart` |
| Остановить | `docker compose -f docker-compose.client.yml down` |
| Удалить вместе с сохранёнными данными | `docker compose -f docker-compose.client.yml down -v` |

Команда с `-v` удаляет подписку, выбранный сервер и другие сохранённые данные. Для обычной остановки используйте `down` без `-v`.

## Обновление

### Gateway

```bash
git pull --ff-only
docker compose -f docker-compose.gateway.yml up -d --build
```

### Connect

Повторно запустите установщик. Он обновит рабочую копию, снова спросит порт прокси и пересоберёт Connect:

```bash
cd ~/.vpn-proxy-client
./scripts/install-macos-client.sh
```

Если раньше использовался нестандартный порт, укажите его снова через `VPN_PROXY_CLIENT_PORT`.

### Версии

Текущая версия всегда показана в правом нижнем углу интерфейса. Connect показывает одну строку `M`, Gateway — строки `C` (client) и `B` (backend). Наведите курсор или переведите клавиатурный фокус на любую цифру, чтобы увидеть смысл `major`, `minor` или `hotfix`; у backend там же указана фактическая версия `sing-box` из dataplane.

Компонентные версии меняются в `src/shared/versions.js`. У всех компонентов должен совпадать `major`, у Gateway client и backend — `major.minor`; `hotfix` может отличаться. Runtime-значения доступны через `GET /api/version`.

Для изменения версии используйте `npm run version:harbor -- affected HEAD`, затем `npm run version:harbor -- bump <major|minor|hotfix> [компонент]` и `npm run version:harbor -- check HEAD`. Правила выбора уровня закреплены в обязательном repo skill `manage-harbor-versions`.

## Настройки `.env`

Для большинства установок достаточно стандартных значений.

| Переменная | По умолчанию | Назначение |
| --- | --- | --- |
| `PORT` | `3456` | Внутренний порт веб-интерфейса Gateway |
| `CLIENT_UI_PORT` | `3456` | Порт интерфейса Connect на Mac |
| `PROXY_PORT` | `8080` | Порт общего прокси Gateway |
| `CLIENT_PROXY_PORT` | `8082` | Порт локального прокси Connect |
| `HARBOR_GATEWAY_CONTROL_PORT` | `3456` | Порт, на котором Connect проверяет домашний Gateway |
| `PROXY_BIND_IP` | `0.0.0.0` | Адрес, на котором Gateway принимает прокси-подключения |
| `PROXY_ALLOWED_CIDRS` | приватные IPv4-сети | Сети, которым разрешён доступ к Gateway Proxy |
| `GATEWAY_CLIENT_CIDRS` | приватные IPv4-сети | Сети, трафик которых Gateway может маршрутизировать |
| `LOG_LEVEL` | `info` | Уровень подробности журнала |

Остальные значения в `.env.example` относятся к сборке контейнера и внутренней маршрутизации. Меняйте их только при нестандартном развёртывании.

После изменения `.env` пересоздайте контейнер командой `up -d` — обычного `restart` недостаточно.

## Если что-то не работает

### Интерфейс не открывается

Проверьте контейнер и журнал:

```bash
docker compose -f docker-compose.gateway.yml ps
docker compose -f docker-compose.gateway.yml logs --tail=100
```

Для Connect замените имя файла на `docker-compose.client.yml` и выполняйте команду из `~/.vpn-proxy-client`.

### Прокси не отвечает

Убедитесь, что Harbor включён в интерфейсе, а приложение использует правильные адрес и порт. Для Connect это обычно `127.0.0.1:8082`; для Gateway — IP Linux-машины и порт `8080`.

### Connect не распознаёт Gateway

Проверьте три условия:

- Gateway является текущим основным шлюзом Mac;
- на обоих устройствах сохранена одна и та же подписка;
- с Mac открывается `http://АДРЕС-GATEWAY:3456`.

### Проверка конфигурации без запуска

```bash
docker compose -f docker-compose.gateway.yml config
docker compose -f docker-compose.client.yml config
```

Эти команды только проверяют и показывают итоговую конфигурацию Docker Compose.

## Служебные команды

Этот раздел нужен тем, кто собирает, проверяет или развёртывает сам проект. Для обычного использования он не требуется.

### Команды npm

| Команда | Назначение |
| --- | --- |
| `npm ci` | Установить точные версии зависимостей из `package-lock.json` |
| `npm test` | Запустить автоматические проверки |
| `npm run build` | Собрать веб-интерфейс в `dist/` |
| `npm run dev` | Запустить Vite для разработки интерфейса |
| `npm start` | Запустить управляющий Node.js-сервис в подготовленном окружении |

### Сборка и развёртывание

| Команда | Назначение |
| --- | --- |
| `./scripts/build-runtime-base.sh` | Собрать базовый runtime-образ с Node.js, сетевыми утилитами и `sing-box` |
| `./scripts/build-on-107-deploy-111.sh` | Собрать Gateway на хосте `107` и развернуть на хосте `111`; хосты меняются через `BUILD_HOST` и `DEPLOY_HOST` |
| `GATEWAY_IMAGE=<образ> ./scripts/deploy-gateway.sh` | Развернуть уже собранный образ в `/opt/vpn-proxy` |
| `./scripts/harbor-network-monitor.sh` | Один раз записать текущий Gateway macOS; обычно этот скрипт запускает установленный LaunchAgent |

Отправка изменений в ветку `master` также запускает автоматическую сборку и развёртывание Gateway через Gitea Actions. Обычный деплой пересоздаёт только `vpn-proxy-control`; процесс `sing-box` и сетевые правила остаются в `vpn-proxy-dataplane`. Dataplane обновляется отдельно, только когда изменены его runtime-файлы.

## Хранение данных

Подписка, выбранный сервер и состояние подключения хранятся в именованных Docker volumes. Поэтому обычные команды `restart`, `down`, обновление проекта и повторная сборка не удаляют настройки.

Не публикуйте файл `.env`, ссылку подписки и содержимое Docker volumes. `.env` уже исключён из Git.