Как развернуть Headscale на VPS-сервере
Если у вас есть несколько устройств — домашний компьютер, ноутбук, смартфон и, например, сервер в дата-центре. И вы хотите, чтобы они общались друг с другом напрямую, безопасно, без посредников, при этом не заботясь о том, какой у каждого из них IP-адрес и за каким роутером они спрятаны. Это и есть задача, которую решают современные mesh-решения на базе протокола WireGuard.
Одним из самых удобных таких решений является Tailscale — сервис, который позволяет собрать устройства в частную сеть буквально за пять минут. Но у Tailscale есть нюанс: его координационный сервер (control plane) находится на стороне компании, и бесплатный тариф ограничивает количество устройств. Для многих это приемлемо, но если вы хотите полного контроля над своей сетью, не хотите зависеть от стороннего сервиса и планируете подключать десятки или сотни устройств — вам понадобится Headscale.
Headscale — это открытая (open-source) реализация координационного сервера Tailscale, которую вы можете запустить на собственном сервере. По сути, вы получаете все преимущества Tailscale (простые клиенты, автоматический обход NAT, шифрование WireGuard), но управляющий центр находится у вас. И лучший способ его развернуть — использовать VPS (виртуальный выделенный сервер) с публичным IP-адресом.
В этой статье мы подробно разберем, что такое Headscale, как он устроен, зачем его запускать на VPS, и пошагово пройдем весь процесс установки и настройки. Вы узнаете, какие варианты развертывания существуют, с какими типичными ошибками можно столкнуться и как их избежать. Статья рассчитана на широкую аудиторию — даже если вы не профессиональный системный администратор, но готовы следовать инструкциям, у вас все получится.
Что такое Headscale и зачем он нужен
Чтобы понять Headscale, нужно сначала разобраться, как работает Tailscale. Tailscale — это сервис, который строит mesh-сети поверх протокола WireGuard. WireGuard — это современный и очень быстрый VPN-протокол, но в «чистом» виде он требует ручной настройки каждого устройства: нужно сгенерировать ключи, прописать их в конфигурационные файлы, указать IP-адреса пиров. Как только устройств становится больше двух-трех, этот процесс превращается в головную боль.
Tailscale решает эту проблему с помощью координационного сервера (control plane). Этот сервер берет на себя:
- регистрацию устройств;
- обмен публичными ключами;
- координацию подключений;
- распределение политик доступа (ACL);
- обход NAT (NAT traversal) с помощью DERP-релеев.
Сама передача данных происходит напрямую между устройствами по протоколу WireGuard — через координационный сервер не проходит ни байт вашего трафика. Координационный сервер нужен только для «знакомства» устройств друг с другом.
Headscale — это открытая, self-hosted реализация именно этого координационного сервера. Вы устанавливаете Headscale на свой сервер (например, на VPS), и все ваши устройства подключаются уже к нему, а не к серверам Tailscale Inc.. При этом вы используете те же самые официальные клиенты Tailscale на всех устройствах — они полностью совместимы.
Иными словами, Headscale позволяет вам заменить облачный координационный сервер Tailscale на свой собственный.
Ключевые возможности Headscale:
- Полная совместимость с официальными клиентами Tailscale (Windows, macOS, Linux, Android, iOS).
- Управление пользователями и устройствами через командную строку (CLI) или веб-интерфейс (Headscale-UI).
- Поддержка ACL (Access Control Lists) для тонкой настройки прав доступа между устройствами.
- Встроенный MagicDNS — устройства доступны по именам, а не по IP-адресам.
- Возможность использования собственных DERP-релеев для обхода NAT.
- Поддержка PostgreSQL и SQLite в качестве базы данных.
- Неограниченное количество пользователей и устройств.
Как работает Headscale: архитектура и принципы
Чтобы лучше понимать, что именно мы настраиваем, давайте разберем архитектуру Headscale. Она состоит из трех основных уровней.
Уровень 1: координационный сервер (Headscale)
Это серверное приложение, которое вы запускаете на VPS. Оно предоставляет API, с которым взаимодействуют клиенты Tailscale. Здесь хранятся:
- информация о зарегистрированных устройствах;
- публичные ключи WireGuard;
- назначенные IP-адреса из пула (обычно из диапазона 100.64.0.0/10);
- политики доступа (ACL);
- данные о пользователях и пространствах имен (namespaces).
Headscale может использовать SQLite (для небольших развертываний) или PostgreSQL (для продакшн-окружений). Конфигурация задается в файле config.yaml.
Уровень 2: клиенты (Tailscale)
На каждом устройстве, которое вы хотите объединить в сеть, устанавливается официальный клиент Tailscale. При запуске клиент:
- Получает адрес вашего Headscale-сервера (вы указываете его при подключении).
- Генерирует пару ключей WireGuard.
- Отправляет публичный ключ на Headscale для регистрации.
- Получает от Headscale список других устройств в сети и их публичные ключи.
- Устанавливает прямые WireGuard-соединения с этими устройствами.
Важно: клиент Tailscale не нужно модифицировать — он «думает», что общается с официальным сервером Tailscale, потому что Headscale реализует тот же протокол.
Уровень 3: передача данных (WireGuard P2P)
После того как устройства «познакомились» через Headscale, они устанавливают прямые зашифрованные соединения друг с другом по протоколу WireGuard. Трафик идет напрямую, минуя ваш VPS. Если прямое соединение невозможно (например, оба устройства за строгим NAT), в дело вступают DERP-релеи — специальные серверы-посредники, которые ретранслируют трафик. Вы можете использовать публичные DERP-серверы Tailscale или развернуть свои собственные.
Таким образом, Headscale — это только «диспетчерская», которая организует соединения, но не участвует в передаче данных. Это обеспечивает высокую производительность и низкую нагрузку на ваш VPS.
Почему для Headscale нужен VPS
Headscale — это серверное приложение, которому требуется постоянный доступ в интернет с публичным IP-адресом. Клиенты Tailscale должны иметь возможность подключиться к нему в любой момент, чтобы обновить информацию о сети, получить ключи или пройти аутентификацию.
Запускать Headscale на домашнем компьютере или Raspberry Pi за домашним роутером — не лучшая идея, потому что:
- Домашний IP-адрес может меняться (динамический IP).
- Роутер может отключать питание или перезагружаться.
- Провайдер может блокировать входящие подключения на определенных портах.
- Домашнее интернет-соединение может быть нестабильным.
VPS (Virtual Private Server) — это идеальное место для Headscale, потому что:
- У него статический публичный IP-адрес.
- Он работает круглосуточно с гарантированной доступностью.
- Вы имеете полный контроль над операционной системой и сетевыми настройками.
- Стоимость базового VPS невысока — для Headscale достаточно 1 vCPU и 512 МБ — 1 ГБ RAM.
Для развертывания Headscale вы можете арендовать VPS-сервер у провайдера, например, в Serverspace. Это надежная и простая в управлении инфраструктура, которая позволит вам запустить координационный сервер за считанные минуты. Базовые тарифы Serverspace отлично подходят для Headscale: требуется минимум ресурсов, а стабильность и доступность обеспечены на уровне дата-центра.
Пошаговое руководство по установке Headscale на VPS
Теперь перейдем к самому главному — практической установке. Мы рассмотрим два основных способа развертывания Headscale на VPS: с помощью готового скрипта (самый быстрый способ) и с помощью Docker Compose (более гибкий и удобный для управления). Выберите тот, который вам ближе.
Перед началом убедитесь, что у вас есть:
- VPS с операционной системой Ubuntu 22.04 или 24.04 (рекомендуется).
- Домен или поддомен, для которого настроена A-запись, указывающая на IP-адрес вашего VPS (например,
headscale.ваш-домен.ru). Это нужно для работы HTTPS. - Доступ к VPS по SSH с правами root или sudo.
Вариант 1: установка с помощью автоматического скрипта
Самый простой способ развернуть Headscale — использовать готовый скрипт от сообщества. Он автоматически скачивает бинарный файл, настраивает systemd-сервис, открывает порты в файрволе и создает первого пользователя.
Выполните на вашем VPS следующие команды:
wget -O headscale.sh https://get.vpnsetup.net/hs
sudo bash headscale.sh --auto --serverurl https://headscale.ваш-домен.ru
Замените https://headscale.ваш-домен.ru на ваш реальный домен. Если вы не укажете --serverurl, скрипт использует публичный IP-адрес и HTTP, что не рекомендуется для использования в продакшн-окружении.
Скрипт выполнит все необходимые действия: установит Headscale, настроит его как системную службу, сгенерирует конфигурационный файл и запустит сервер. После завершения установки вы получите имя первого пользователя (по умолчанию admin) и команду для генерации ключа предварительной авторизации.
Этот способ подходит для быстрого старта, но он менее гибкий, чем Docker-вариант. Если вы хотите больше контроля над конфигурацией, используйте второй способ.
Вариант 2: установка с помощью Docker Compose
Docker Compose позволяет описать всю инфраструктуру в одном файле и управлять ею с помощью простых команд. Этот способ особенно удобен, если вы планируете также развернуть веб-интерфейс (Headscale-UI) или reverse proxy для автоматического HTTPS.
Шаг 1: установите Docker и Docker Compose на VPS
sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Эти команды добавят официальный репозиторий Docker и установят необходимые пакеты.
Шаг 2: создайте структуру каталогов
mkdir -p /opt/headscale/config
cd /opt/headscale
Шаг 3: создайте конфигурационный файл Headscale
Создайте файл /opt/headscale/config/config.yaml со следующим минимальным содержимым (адаптируйте под свой домен):
server_url: https://headscale.ваш-домен.ru
listen_addr: 0.0.0.0:8080
private_key_path: /var/lib/headscale/private.key
noise:
private_key_path: /var/lib/headscale/noise_private.key
ip_prefixes:
- 100.64.0.0/10
- fd7a:115c:a1e0::/48
derp:
server:
enabled: false
urls:
- https://controlplane.tailscale.com/derpmap/default
database:
type: sqlite3
sqlite:
path: /var/lib/headscale/db.sqlite
Это базовая конфигурация. Headscale будет использовать SQLite как базу данных и публичные DERP-серверы Tailscale для обхода NAT.
Шаг 4: создайте файл docker-compose.yml
Создайте файл /opt/headscale/docker-compose.yml:
version: '3'
services:
headscale:
image: headscale/headscale:latest
container_name: headscale
restart: unless-stopped
volumes:
- ./config:/etc/headscale
- ./data:/var/lib/headscale
ports:
- "8080:8080"
command: headscale serve
Этот файл описывает один сервис — Headscale. Он монтирует локальные папки config и data внутрь контейнера, где хранятся конфигурация и база данных соответственно.
Шаг 5: запустите Headscale
docker compose up -d
Контейнер запустится в фоновом режиме. Проверьте, что он работает:
docker compose ps
Шаг 6: настройте HTTPS с помощью reverse proxy
Для безопасной работы клиентам Tailscale требуется HTTPS. Самый простой способ — использовать Caddy или Nginx в качестве reverse proxy. Caddy умеет автоматически получать SSL-сертификаты от Let's Encrypt.
Создайте файл Caddyfile в отдельном контейнере или установите Caddy на хост-систему. Пример минимальной конфигурации Caddy:
headscale.ваш-домен.ru {
reverse_proxy localhost:8080
}
Запустите Caddy, и он автоматически выпустит сертификат для вашего домена.
После этого Headscale будет доступен по адресу https://headscale.ваш-домен.ru.
Создание первого пользователя и подключение устройства
После установки Headscale (любым способом) необходимо создать пользователя (в терминах Headscale — namespace) и сгенерировать ключ для подключения устройства.
Создайте пользователя:
docker compose exec headscale headscale users create myuser
Вместо myuser выберите любое имя.
Сгенерируйте ключ предварительной авторизации (pre-auth key):
docker compose exec headscale headscale preauthkeys create --user myuser --expiration 24h
Вы получите ключ вида abcdef123456.... Скопируйте его.
Подключение устройств разных типов:
Для компьютеров (Linux, macOS, Windows с WSL или командной строкой):
Установите официальный клиент Tailscale и выполните команду:
tailscale up --login-server https://headscale.ваш-домен.ru --auth-key КЛЮЧ_КОТОРЫЙ_ВЫ_ПОЛУЧИЛИ
Устройство зарегистрируется в вашем Headscale и появится в списке узлов.
Для смартфонов (Android / iOS):
На мобильных платформах нет командной строки, поэтому подключение выполняется через графический интерфейс:
- Android: установите приложение Tailscale из Google Play или F-Droid. Откройте меню (три точки) → «Use an alternate server» → введите URL вашего Headscale. Затем в том же меню выберите «Use an auth key» и вставьте сгенерированный ключ.
- iOS: установите приложение Tailscale из App Store. Убедитесь, что вы не авторизованы. Откройте системные Настройки → Tailscale → в поле «ALTERNATE COORDINATION SERVER URL» введите URL вашего Headscale. Закройте и снова откройте приложение, затем нажмите «Sign in» — будет выполнена аутентификация через ваш сервер.
После успешной регистрации устройство появится в списке узлов, аналогично компьютерам.
Проверить список подключенных устройств можно командой:
docker compose exec headscale headscale nodes list
Плюсы, минусы и ограничения Headscale
Как и любое решение, Headscale имеет свои сильные и слабые стороны. Важно понимать их, прежде чем принимать решение о развертывании.
| Аспект | Плюсы Headscale | Минусы и ограничения |
|---|---|---|
| Контроль данных | Полный контроль над ключами, метаданными и политиками. Данные не покидают вашу инфраструктуру. | Требует самостоятельного обеспечения безопасности сервера (обновления, бэкапы, мониторинг). |
| Стоимость | Полностью бесплатно, нет ограничений по количеству устройств и пользователей. | Требуются затраты на аренду VPS (обычно от $5–10 в месяц). |
| Совместимость | Полная совместимость с официальными клиентами Tailscale на всех платформах. | Некоторые новые функции Tailscale могут появляться в Headscale с задержкой (например, Funnel пока не поддерживается). |
| Управление | Гибкая настройка через CLI и конфигурационные файлы; возможность использования веб-интерфейса (Headscale-UI). | Требует начальной настройки и знаний командной строки; нет «коробочного» веб-интерфейса (требуется отдельная установка). |
| Производительность | Передача данных происходит напрямую P2P по WireGuard — максимальная скорость и минимальная задержка. | Производительность зависит от качества интернет-соединения между устройствами; при использовании DERP-релеев скорость может снижаться. |
| Надежность | Вы сами контролируете uptime и можете обеспечить высокую доступность (например, с помощью кластеризации). | Отвечаете за надежность самостоятельно; если VPS упадет, новые устройства не смогут подключиться, а существующие могут потерять связь (до восстановления). |
Важно отметить, что хотя один экземпляр Headscale обслуживает одну сеть (tailnet), вы можете использовать пространства имен (namespaces) для логического разделения устройств и эмуляции изоляции между группами пользователей. Это позволяет организовать, например, отдельные пространства для разработки, тестирования и продакшна в рамках одного сервера.
Для чего нужен Headscale
Headscale подходит для самых разных задач. Вот несколько типовых сценариев, где он оказывается особенно полезным.
1. Безопасный доступ к домашней лаборатории (homelab)
У вас дома есть сервер с Docker, Raspberry Pi или старый компьютер, на котором запущены различные сервисы (например, Plex, Home Assistant, Grafana). Вы хотите иметь к ним доступ из любого места, но не хотите открывать порты в интернет. Headscale позволяет собрать все устройства в частную сеть, и вы можете подключаться к домашним сервисам по их внутренним IP-адресам из любой точки мира, как будто вы находитесь дома.
2. Безопасное соединение нескольких VPS и облачных серверов
Если у вас есть несколько VPS в разных дата-центрах или у разных провайдеров, Headscale позволяет объединить их в одну сеть. Это упрощает администрирование: вы можете копировать файлы между серверами, настраивать мониторинг, использовать общие базы данных — и все это по зашифрованным каналам, без необходимости открывать SSH в интернет.
3. Корпоративная частная сеть для небольшой команды
Для небольшой компании или стартапа Headscale может стать отличной альтернативой корпоративным VPN-решениям. Вы можете развернуть координационный сервер, выдать каждому сотруднику доступ в частную сеть и настроить ACL таким образом, чтобы, например, разработчики имели доступ к серверам разработки, а менеджеры — только к CRM-системе. При этом все данные остаются под вашим контролем, а количество пользователей не ограничено.
4. Удаленный доступ к IoT-устройствам
Если у вас есть множество IoT-устройств (камеры, датчики, контроллеры), разбросанных по разным локациям, Headscale позволяет объединить их в одну сеть и управлять ими удаленно. Устройства могут находиться за NAT, но благодаря встроенным механизмам обхода NAT они будут доступны из любой точки.
5. Приватная сеть для разработки и тестирования
Разработчики часто используют изолированные среды для тестирования приложений. Headscale позволяет создать приватную сеть, в которой будут находиться только тестовые серверы и рабочие станции разработчиков. Это изолирует тестовую среду от продакшн-сетей и интернета, повышая безопасность.
Частые ошибки при установке и настройке Headscale (и как их избежать)
Даже при следовании инструкциям могут возникать проблемы. Вот самые распространенные ошибки и способы их решения.
Ошибка: клиент не может подключиться к Headscale («context deadline exceeded»)
Причина: клиент Tailscale не может достичь вашего Headscale-сервера. Чаще всего это связано с отсутствием HTTPS или неправильным указанием URL.
Решение: убедитесь, что вы используете https:// в адресе сервера. Проверьте, что ваш домен правильно резолвится в IP-адрес VPS. Откройте порт 443 (или тот, на котором работает ваш reverse proxy) в файрволе. Проверьте, что Headscale действительно слушает на нужном порту и что reverse proxy (Caddy/Nginx) корректно перенаправляет трафик.
Ошибка: «failed to load config: open config.yaml: no such file or directory»
Причина: Headscale не может найти конфигурационный файл. Это часто случается при установке из DEB-пакета или при ручном запуске.
Решение: убедитесь, что конфигурационный файл находится в правильном месте. Для DEB-установки это /etc/headscale/config.yaml. Для Docker — убедитесь, что вы правильно смонтировали том с конфигурацией. Проверьте права доступа к файлу.
Ошибка: «noise handshake failed: decrypting machine key»
Причина: ошибка при обновлении Headscale до новой версии — клиенты не могут установить соединение из-за изменения протокола или ключей.
Решение: перед обновлением Headscale ознакомьтесь с релизными заметками. В некоторых случаях требуется перерегистрация устройств. Чтобы избежать этой проблемы, всегда делайте бэкап базы данных перед обновлением и тестируйте на некритичных устройствах.
Ошибка: порт уже занят («address already in use»)
Причина: другой процесс слушает на том же порту, что и Headscale (по умолчанию 8080).
Решение: измените порт в конфигурации Headscale (параметр listen_addr) или остановите конфликтующий процесс. Если вы используете reverse proxy, Headscale может слушать только на localhost (127.0.0.1:8080), чтобы не конфликтовать с другими сервисами.
Ошибка: устройство подключается, но не появляется в списке узлов
Причина: ключ предварительной авторизации (pre-auth key) мог истечь, или устройство не прошло регистрацию.
Решение: сгенерируйте новый ключ с достаточным сроком действия (например, --expiration 720h для 30 дней) и повторите подключение. Убедитесь, что вы используете правильный --login-server URL.
Сравнение способов развертывания Headscale
Чтобы вам было проще выбрать подходящий метод установки, вот сравнительная таблица.
| Критерий | Автоматический скрипт | DEB-пакет (apt) | Docker Compose |
|---|---|---|---|
| Сложность установки | Очень низкая (одна команда) | Низкая (стандартная установка пакета) | Средняя (требуется знание Docker) |
| Гибкость настройки | Ограниченная | Высокая | Максимальная |
| Управление сервисом | systemd | systemd | Docker (docker compose) |
| Обновление | Повторный запуск скрипта | apt update && apt upgrade | Изменение тега образа + перезапуск |
| Изоляция от системы | Низкая (устанавливается в систему) | Низкая (устанавливается в систему) | Высокая (в контейнере) |
| Подходит для продакшн | Ограниченно | Да | Да (при правильной настройке) |
Часто задаваемые вопросы (FAQ)
Чем Headscale отличается от Tailscale?
Tailscale — это готовый облачный сервис с собственным координационным сервером и официальными клиентами. Headscale заменяет облачный control plane Tailscale на сервер, который вы разворачиваете самостоятельно, при этом для подключения устройств используются те же клиенты Tailscale.
Бесплатен ли Headscale?
Да. Headscale распространяется бесплатно с открытым исходным кодом и не требует покупки лицензии. Основные расходы связаны только с арендой VPS, доменным именем и, при необходимости, дополнительной инфраструктурой для резервного копирования или собственных DERP-релеев.
Сколько устройств можно подключить к Headscale?
Headscale не устанавливает фиксированных ограничений на количество пользователей и устройств. Реальный предел зависит от производительности VPS, выбранной базы данных и общей нагрузки на координационный сервер.
Нужны ли домен и HTTPS для Headscale?
Для тестовой установки можно использовать IP-адрес, но для постоянной эксплуатации рекомендуется настроить домен и HTTPS. Защищённое соединение повышает безопасность и необходимо для корректной работы некоторых клиентов, особенно на мобильных устройствах.
Какой VPS нужен для установки Headscale?
Для небольшой сети достаточно VPS с 1 vCPU, 512 МБ–1 ГБ оперативной памяти и небольшим SSD-диском. Сервер должен иметь статический публичный IP-адрес, стабильное интернет-соединение и работать круглосуточно.
Как обновить Headscale и не потерять настройки?
Перед обновлением необходимо создать резервную копию базы данных и конфигурационного файла. При установке через Docker Compose достаточно скачать новый образ и перезапустить контейнеры, а при пакетной установке обновление выполняется через менеджер пакетов. Перед переходом на новую версию также стоит проверить примечания к релизу.
Вывод: стоит ли разворачивать Headscale и что делать дальше
Headscale — это мощный и гибкий инструмент для создания собственной частной mesh-сети. Он идеально подходит для тех, кто ценит контроль над своими данными, не хочет ограничений по количеству устройств и готов потратить немного времени на первоначальную настройку.
Кому подойдет Headscale:
- Энтузиастам self-hosting и владельцам домашних лабораторий.
- Небольшим компаниям, которым нужна корпоративная VPN без абонентской платы.
- Разработчикам, которые тестируют распределенные системы.
- Всем, кто хочет объединить свои VPS, облачные серверы и домашние устройства в одну безопасную сеть.
Кому лучше остаться на Tailscale:
- Тем, кто не хочет администрировать сервер и предпочитает решение «все в одном».
- Пользователям с небольшим количеством устройств (до 100), которым хватает бесплатного тарифа.
- Тем, кому нужны готовые интеграции с SSO и корпоративные функции «из коробки».
Если вы решили попробовать Headscale, начните с аренды VPS у надежного провайдера, например Serverspace. Выберите базовый тариф с Ubuntu 22.04, настройте домен и следуйте нашему пошаговому руководству. Весь процесс займет не более 30–40 минут, а результат — полностью контролируемая и безопасная частная сеть — окупит потраченное время.
После успешного развертывания вы можете расширить инфраструктуру: установить веб-интерфейс Headscale-UI для удобного управления, настроить ACL для разграничения доступа между пользователями, подключить свои DERP-релеи для оптимизации обхода NAT. Возможности дальнейшей настройки зависят от ваших задач и технической подготовки.
Начните строить свою приватную mesh-сеть уже сегодня — с Headscale и VPS от Serverspace это проще, чем вы думаете.