Harbor
Harbor помогает пользоваться одной VPN-подпиской дома и на Mac без ручной настройки sing-box.
Проект работает в двух режимах:
| Режим | Где работает | Для чего нужен |
|---|---|---|
| Harbor Gateway | На отдельной Linux-машине | Проводит через VPN весь интернет-трафик домашних устройств или работает как общий HTTP/SOCKS5-прокси |
| Harbor Connect | На macOS | Даёт приложениям на Mac локальный HTTP/SOCKS5-прокси |
В обоих режимах управление одинаковое: откройте веб-интерфейс, вставьте ссылку VPN-подписки, выберите сервер и нажмите кнопку подключения.
Что понадобится
- ссылка на подписку от VPN-провайдера;
- Docker с командой
docker compose; - для ручной установки Gateway — Git;
- для Gateway — Linux-машина в одной локальной сети с устройствами;
- для Connect — Mac с запущенным Docker Desktop.
Harbor не является VPN-провайдером и не создаёт подписки самостоятельно.
Что выбрать
Используйте Harbor Connect, если VPN нужен только приложениям на одном Mac.
Используйте Harbor Gateway, если нужно подключить телевизор, телефон, игровую приставку или сразу несколько устройств. Устройства можно направить через Gateway целиком либо настроить в отдельных приложениях общий прокси.
Оба режима можно использовать вместе. Дома Connect автоматически распознаёт настроенный Harbor Gateway и не запускает второй VPN-маршрут. В другой сети Connect возвращается к локальному VPN.
Установка Harbor Gateway
1. Скачайте проект
git clone https://git.dokops.ru/dokril/vpn-proxy.git
cd vpn-proxy
2. Создайте настройки
cp .env.example .env
Стандартные значения подходят для обычной домашней сети. При необходимости откройте .env в текстовом редакторе и измените порты.
3. Запустите Gateway
docker compose -f docker-compose.gateway.yml up -d --build
Откройте в браузере:
http://АДРЕС-GATEWAY:3456
Например, если Linux-машина имеет адрес 192.168.1.20, интерфейс будет доступен по адресу http://192.168.1.20:3456.
4. Добавьте подписку
- Вставьте ссылку VPN-подписки.
- Нажмите «Сохранить подписку».
- Выберите сервер.
- Включите VPN.
После подключения Harbor покажет два варианта использования:
- Gateway — укажите IP-адрес Linux-машины как основной шлюз устройства. Через VPN пойдёт весь его интернет-трафик;
- Gateway Proxy — укажите адрес Linux-машины и порт
8080в приложении. Поддерживаются HTTP и SOCKS5 на одном порту.
Приватные и локальные адреса не отправляются в VPN, поэтому устройства сохраняют доступ к домашней сети. Общий прокси по умолчанию принимает подключения только из приватных сетей.
Установка Harbor Connect на macOS
1. Запустите Docker Desktop
Установщик проверит наличие Docker, Docker Compose, curl и tar. Если Docker Desktop не запущен, установка остановится с понятным сообщением.
2. Запустите установщик
curl -fsSL https://git.dokops.ru/dokril/vpn-proxy/raw/branch/master/install.sh | 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.
Другие порты
Передайте нужные значения при повторном запуске установщика:
curl -fsSL https://git.dokops.ru/dokril/vpn-proxy/raw/branch/master/install.sh | \
VPN_PROXY_CLIENT_PORT=9080 \
VPN_PROXY_CLIENT_UI_PORT=3457 \
sh
Допустимы порты от 1024 до 65535. Установщик не позволит выбрать занятый порт или один порт одновременно для интерфейса и прокси.
Локальные правила маршрутизации
После добавления подписки откройте «Локальные правила» справа от основного экрана. При первом обновлении Harbor добавит обычное включённое правило *.ru, поэтому российские домены пойдут напрямую. Его, как и любое другое правило, можно выключить или удалить. Доступны точный домен, suffix домена и фрагмент имени; включённые правила обходят VPN, а остальной трафик идёт через выбранный сервер.
Полный URL можно вставить в поле точного домена, но Harbor сохранит только hostname. Путь и параметры HTTPS зашифрованы и недоступны sing-box на уровне маршрутизации. GeoSite, GeoIP и подключаемые списки пока не поддерживаются.
При сохранении Harbor проверяет фактическое состояние sing-box. Работающий процесс автоматически перезагружает новую конфигурацию. Если sing-box остановлен, правила сохраняются с признаком «ждут перезапуска» и начнут работать при следующем запуске или restart; этот статус виден в интерфейсе.
Системный прокси macOS
Сначала посмотрите точное имя сетевого подключения:
networksetup -listallnetworkservices
Для подключения с именем Wi-Fi включите HTTP, HTTPS и SOCKS5-прокси:
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
Чтобы отключить их:
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.
Для этого:
- добавьте одну и ту же ссылку подписки в Gateway и Connect;
- убедитесь, что Mac может открыть интерфейс Gateway на порту
3456; - оставьте автоматический режим включённым в 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
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
git pull --ff-only
docker compose -f docker-compose.gateway.yml up -d --build
Connect
Повторно запустите однострочный установщик. Он обновит рабочую копию, снова спросит порт прокси и пересоберёт Connect:
curl -fsSL https://git.dokops.ru/dokril/vpn-proxy/raw/branch/master/install.sh | sh
Если раньше использовался нестандартный порт, укажите его снова через VPN_PROXY_CLIENT_PORT.
Версии
Текущая версия всегда показана в правом нижнем углу интерфейса. Connect показывает строку M (Mac client). Gateway показывает C (Gateway client UI), B (текущий control-backend) и D (фактически развёрнутый dataplane). Поэтому после control-only deploy B обновится сразу, а D может намеренно остаться на прежней версии до следующего runtime-deploy. Наведите курсор или переведите клавиатурный фокус на цифру, чтобы увидеть смысл major, minor или hotfix; у D также указана фактическая версия sing-box.
Компонентные версии меняются в 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 недостаточно.
Если что-то не работает
Интерфейс не открывается
Проверьте контейнер и журнал:
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.
Проверка конфигурации без запуска
docker compose -f docker-compose.gateway.yml config
docker compose -f docker-compose.client.yml config
docker compose -f docker-compose.client.local.yml config
Эти команды только проверяют и показывают итоговую конфигурацию Docker Compose.
Локальное тестирование Harbor Connect
Тестовый Connect запускается рядом с установленным клиентом и использует отдельные контейнер, volumes и порты:
docker compose -f docker-compose.client.local.yml up -d --build
Интерфейс доступен на http://127.0.0.1:3457, HTTP/SOCKS5-прокси — на 127.0.0.1:8083. Остановить и удалить только тестовый стек можно командой:
docker compose -f docker-compose.client.local.yml down -v
Порты можно заменить через LOCAL_CLIENT_UI_PORT и LOCAL_CLIENT_PROXY_PORT.
Служебные команды
Этот раздел нужен тем, кто собирает, проверяет или развёртывает сам проект. Для обычного использования он не требуется.
Команды 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, поэтому строка B соответствует текущему коду API. Процесс sing-box и сетевые правила остаются в vpn-proxy-dataplane; он пересоздаётся только при изменении его runtime-зависимостей, а его фактическая версия показывается отдельно как D.
Хранение данных
Подписка, выбранный сервер и состояние подключения хранятся в именованных Docker volumes. Поэтому обычные команды restart, down, обновление проекта и повторная сборка не удаляют настройки.
Не публикуйте файл .env, ссылку подписки и содержимое Docker volumes. .env уже исключён из Git.