masque-vpn

Учебная реализация VPN на основе протокола MASQUE (CONNECT-IP) с использованием транспорта QUIC.

Этот проект предназначен для образовательных целей и исследований в области современных сетевых протоколов.

Документация на других языках

English - English documentation
中文文档 - Chinese documentation

git clone https://github.com/cloudbridge-research/masque-vpn.git

Возможности

Современные протоколы: Построен на QUIC и MASQUE CONNECT-IP (RFC 9484)
Кастомная реализация MASQUE: Собственная реализация протокола без внешних зависимостей
Модульная архитектура: Разделение сервера на специализированные компоненты
REST API: Полнофункциональный API для управления и мониторинга
Взаимная TLS-аутентификация: Аутентификация клиент-сервер на основе сертификатов
Кроссплатформенность: Поддержка Windows, Linux и macOS
Управление пулом IP: Автоматическое выделение IP-адресов клиентам
Мониторинг Prometheus: Детальные метрики для анализа производительности
Комплексное тестирование: Unit, integration и load тесты

Документация

Подробная документация для студентов и исследователей:

Руководство студента (RU): Лабораторные работы и исследовательские проекты
Руководство студента (EN): Laboratory assignments and research projects
Архитектура: Описание компонентов и потоков данных
API Документация: REST API для управления и мониторинга
Начало работы: Инструкции по сборке и запуску
Мониторинг: Настройка Prometheus и Grafana

Архитектура

Система состоит из четырех основных компонентов:

VPN-сервер: Обрабатывает MASQUE CONNECT-IP запросы и маршрутизацию трафика
VPN-клиент: Подключается к серверу через QUIC и туннелирует IP пакеты
REST API сервер: Управление клиентами и мониторинг (порт 8080)
Общие библиотеки: Кастомная реализация MASQUE и утилиты

Быстрый старт

1. Сборка

# Сборка сервера
cd vpn_server && go build -o vpn-server .

# Сборка клиента
cd ../vpn_client && go build -o vpn-client .

2. Генерация сертификатов

cd cert

# Linux/macOS
./generate-test-certs.sh

# Windows
powershell -ExecutionPolicy Bypass -File generate-certs.ps1

3. Запуск сервера (локальное тестирование)

cd vpn_server
./vpn-server -c config.server.local.toml

Сервер запустится на:

MASQUE VPN: 127.0.0.1:4433
REST API: 127.0.0.1:8080

4. Тестирование API

# Проверка состояния
curl http://127.0.0.1:8080/health

# Статус сервера
curl http://127.0.0.1:8080/api/v1/status

# Метрики Prometheus
curl http://127.0.0.1:8080/metrics

5. Запуск клиента

cd vpn_client
# Отредактируйте config.client.toml: server_addr = "127.0.0.1:4433"
./vpn-client -c config.client.toml

6. Тестирование протокола MASQUE

# Функциональный тест
go run test_masque_connection.go

Конфигурация

Локальное тестирование

Для локального тестирования используйте готовые конфигурации:

Сервер (config.server.local.toml):

listen_addr = "127.0.0.1:4433"
assign_cidr = "10.0.0.0/24"
tun_name = ""  # TUN отключен для упрощения
log_level = "debug"

[api_server]
listen_addr = "127.0.0.1:8080"

Клиент (config.client.toml):

server_addr = "127.0.0.1:4433"
server_name = "masque-vpn-server"
insecure_skip_verify = true  # Для тестовых сертификатов

Продакшн развертывание

Для продакшн используйте:

Реальные сертификаты (не самоподписанные)
TUN устройства для маршрутизации трафика
Настройку firewall для портов 4433 и 8080
Мониторинг через Prometheus/Grafana

REST API

API предоставляет endpoints для управления и мониторинга:

Endpoint	Описание
`GET /health`	Проверка состояния API
`GET /api/v1/status`	Статус сервера
`GET /api/v1/clients`	Список клиентов
`GET /api/v1/stats`	Статистика сервера
`GET /api/v1/config`	Конфигурация сервера
`GET /metrics`	Метрики Prometheus

Подробности в API документации.

Технические детали

Кастомная реализация MASQUE

Проект включает собственную реализацию протокола MASQUE CONNECT-IP:

common/masque_connectip.go - MASQUE клиент
common/masque_proxy.go - Функции проксирования IP пакетов
vpn_server/internal/server/masque_handler.go - Серверный обработчик

Модульная архитектура сервера

Сервер разделен на специализированные модули:

server.go - Основной сервер и инициализация
api_server.go - REST API сервер
masque_handler.go - Обработчик MASQUE запросов
packet_processor.go - Обработка пакетов TUN устройства
metrics.go - Метрики Prometheus
tls_config.go - Конфигурация TLS

Зависимости

Go 1.25 - Современная версия языка
QUIC: quic-go v0.57.1 - QUIC протокол
HTTP Framework: Gin - для REST API
Metrics: Prometheus client - метрики
Logging: Zap - структурированное логирование

Безопасность

Взаимный TLS: Клиент и сервер аутентифицируются сертификатами
Самоподписанный CA: Для тестирования и образовательных целей
Изоляция клиентов: Каждый клиент получает уникальный IP адрес
Валидация запросов: Проверка MASQUE заголовков и параметров

Тестирование

Запуск тестов

# Unit тесты
cd common && go test -v
cd vpn_server && go test -v ./...
cd vpn_client && go test -v

# Интеграционные тесты
cd tests/integration && go test -v

# Нагрузочные тесты
cd tests/load && go test -v

Автоматизированное тестирование

# Локальное тестирование
./scripts/test-local.sh

# Docker тестирование
./scripts/test-docker.sh

Разработка

Структура проекта

masque-vpn/
├── common/                    # Общие библиотеки
│   ├── masque_connectip.go   # MASQUE клиент
│   ├── masque_proxy.go       # Проксирование пакетов
│   └── errors.go             # Система ошибок
├── vpn_server/               # Сервер
│   ├── internal/server/      # Модули сервера
│   └── main.go              # Точка входа
├── vpn_client/              # Клиент
├── tests/                   # Тесты
├── docs/                    # Документация
└── cert/                    # Генерация сертификатов

Требования для разработки

Go 1.25 или новее
OpenSSL (для генерации сертификатов)
Docker (для контейнеризации)
Make (для автоматизации)

Решение проблем

Распространенные проблемы

Ошибки сборки:

Убедитесь, что установлен Go 1.25+
Выполните go mod tidy для обновления зависимостей

Ошибки сертификатов:

Перегенерируйте сертификаты если они истекли
Проверьте пути к сертификатам в конфигурации

Проблемы с подключением:

Проверьте настройки firewall для портов 4433 и 8080
Убедитесь, что сервер слушает на правильных адресах
Протестируйте API endpoints с помощью curl

Проблемы с производительностью:

Мониторьте системные ресурсы (CPU, память)
Проверьте логи сервера на наличие ошибок
Используйте метрики Prometheus для анализа

Отладка

# Запуск с отладочным логированием
./vpn-server -c config.server.local.toml  # уже содержит log_level = "debug"

# Проверка логов API
curl http://127.0.0.1:8080/api/v1/logs

Образовательное использование

Для студентов и исследователей

Этот проект предназначен для изучения:

Современных сетевых протоколов: QUIC, HTTP/3, MASQUE
Программирования на Go: Конкурентность, сетевое программирование, тестирование
Системного дизайна: Модульная архитектура, API дизайн, мониторинг
Методологии исследований: Анализ производительности, сбор данных, документирование

Лабораторные работы

Базовое развертывание - сборка и запуск системы
Анализ производительности - измерение метрик VPN
Глубокий анализ протокола - изучение реализации MASQUE
Тестирование в различных условиях - эмуляция сетевых проблем

Исследовательские проекты

Оптимизация производительности MASQUE
Анализ поведения под нагрузкой
Исследования безопасности
Системы мониторинга и наблюдаемости

Подробности в руководстве студента.

Участие в разработке

Проект создан в образовательных целях. Приветствуются:

Улучшения реализации протокола
Кроссплатформенная совместимость
Улучшения документации
Исправления ошибок
Новые тестовые сценарии

Стандарты и RFC

MASQUE CONNECT-IP: RFC 9484 - Проксирование IP в HTTP
QUIC Transport: RFC 9000 - QUIC транспорт
HTTP/3: RFC 9114 - HTTP/3 протокол

Лицензия и авторские права

Этот проект распространяется под лицензией MIT.

Проект основан на оригинальной работе iselt/masque-vpn и развивается CloudBridge Research для образовательных и исследовательских целей.

Поддержка

Для вопросов и сотрудничества:

Репозиторий проекта: cloudbridge-research/masque-vpn
Оригинальный репозиторий: iselt/masque-vpn
Обсуждения и вопросы на GitHub
Образовательные учреждения могут форкать и адаптировать проект

Name		Name	Last commit message	Last commit date
Latest commit History 80 Commits
.vscode		.vscode
admin_webui		admin_webui
cert		cert
common		common
docs		docs
grafana		grafana
monitoring		monitoring
scripts		scripts
tests		tests
vpn_client		vpn_client
vpn_server		vpn_server
.gitignore		.gitignore
DEPLOYMENT.md		DEPLOYMENT.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README_en.md		README_en.md
README_zh.md		README_zh.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
habr_part2.md		habr_part2.md
launch-improvements.sh		launch-improvements.sh
test_masque_connection.go		test_masque_connection.go

License

cloudbridge-research/masque-vpn

Folders and files

Latest commit

History

Repository files navigation