Flutter VLESS: создание VPN-приложений с поддержкой VLESS, Reality и других протоколов

Что такое flutter_vless и зачем он нужен

Flutter_vless — это открытый плагин для Flutter, который позволяет встраивать в приложение поддержку популярных прокси-протоколов, включая VLESS Reality, XHTTP, VMess, Trojan, Shadowsocks, Hysteria2 и WireGuard. Он работает на Android, iOS, macOS и Windows, предоставляя единый Dart API для парсинга ссылок, подписок и конфигураций, а также для запуска прокси или VPN-туннеля через нативные бэкенды.

Плагин разработан и поддерживается студией 13FOX Studio (tfox.dev) и распространяется под лицензией MIT, что допускает коммерческое использование при сохранении уведомления об авторских правах. Он включён в официальный список Xray-core как обёртка, что подтверждает его совместимость с экосистемой Xray.

Основная ценность flutter_vless — в том, что разработчику не нужно разбираться в тонкостях нативной реализации Xray для каждой платформы. Достаточно один раз написать логику на Dart, а плагин позаботится о взаимодействии с системными VPN-сервисами, управлении дочерними процессами и обработке конфигураций.

Поддерживаемые протоколы и форматы импорта

Плагин поддерживает импорт конфигураций из нескольких источников:

• Share-ссылки: vmess://, vless://, trojan://, ss://, socks://, hysteria2://, hy2://.
• Подписки: base64-закодированные списки ссылок.
• Сырые конфигурации Xray: JSON-файлы, используемые самим Xray.
• Clash YAML: популярный формат конфигурации для Clash-клиентов.
• sing-box JSON: конфигурации для sing-box.

Каждый из этих форматов может содержать профили для VLESS Reality, XHTTP, VMess, Trojan, Shadowsocks, Hysteria2 и WireGuard. Плагин автоматически распознаёт тип профиля и преобразует его во внутреннее представление.

Для работы с несколькими профилями из подписки предусмотрен метод parseMany(), который возвращает список всех поддерживаемых профилей. Это удобно при создании приложений со списком серверов.

Режимы работы: прокси и VPN-туннель

Flutter_vless поддерживает два основных режима:

• Proxy-only: приложение работает как прокси, обрабатывая трафик только тех приложений, которые явно настроены на использование прокси. Этот режим не требует прав администратора и работает на всех платформах.
• VPN/tunnel: создаётся виртуальный сетевой адаптер (TUN), через который проходит весь трафик операционной системы. Этот режим требует специальных разрешений и настроек на каждой платформе.

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

На Android VPN-режим использует VpnService, на iOS и macOS — Network Extension и Packet Tunnel, на Windows — локальный xray.exe и, возможно, права администратора. Плагин предоставляет готовые реализации для каждой платформы, но требует предварительной настройки.

Настройка под Android

Для Android плагин использует VpnService для создания VPN-туннеля. Это стандартный механизм Android, который позволяет приложению перехватывать и маршрутизировать сетевой трафик. Плагин поддерживает функцию blockedApps, которая позволяет исключить определённые приложения из туннеля (per-app bypass).

Для работы в эмуляторе не требуется дополнительных действий — бинарные файлы для эмулятора включены в основной AAR-артефакт. Плагин также поддерживает современные устройства с 16KB page size, что важно для новых версий Android.

Для запуска VPN-режима необходимо запросить разрешение у пользователя через requestPermission(). После получения разрешения можно запускать туннель с помощью startVless(). В proxy-only режиме разрешение не требуется.

Настройка под iOS и macOS

Для iOS и macOS плагин использует Network Extension framework. Это требует настройки App Group и подписанного физического устройства для тестирования VPN-режима на iOS. Симулятор не поддерживает VPN-туннели, поэтому для проверки потребуется реальное устройство.

На macOS необходимо создать Packet Tunnel extension и настроить подпись приложения. Плагин предоставляет скрипт prepare_apple_swiftpm.sh, который генерирует метаданные Swift Package Manager. Для proxy-only режима достаточно выполнить подготовку с флагом --prepare-only, для VPN-режима требуется полная настройка.

Важно: для macOS необходимо указать Apple Team в настройках проекта Xcode для обоих таргетов (Runner и XrayTunnel). Без этого подпись не будет работать.

Настройка под Windows

На Windows плагин требует наличия локального исполняемого файла xray.exe. Его необходимо разместить в папке windows/xray/ вашего проекта. Для VPN-режима могут потребоваться права администратора, так как создание TUN-адаптера требует повышенных привилегий.

Плагин автоматически управляет процессом xray, включая очистку зависших процессов при перезапуске. Это важно для стабильной работы, особенно при частых переключениях серверов.

Для proxy-only режима права администратора не требуются, но приложение должно быть настроено на использование системного прокси.

Пример использования: подключение по vless-ссылке

Рассмотрим базовый пример подключения к серверу по vless-ссылке. Сначала необходимо создать экземпляр FlutterVless и подписаться на изменения статуса:

final flutterVless = FlutterVless(
  onStatusChanged: (status) {
    debugPrint('status=${status.state} connection=${status.connectionState.name} delay=${status.duration}s');
  },
);

Затем парсим ссылку и получаем конфигурацию:

final parsed = FlutterVless.parse(shareLink);
final config = parsed.getFullConfiguration();

Далее инициализируем плагин с идентификаторами bundle и group:

await flutterVless.initializeVless(
  providerBundleIdentifier: 'com.example.myapp',
  groupIdentifier: 'group.com.example.myapp',
);

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

if (await flutterVless.requestPermission()) {
  await flutterVless.startVless(
    remark: parsed.remark,
    config: config,
  );
}

Для proxy-only режима нужно передать proxyOnly: true в startVless() и пропустить запрос разрешения.

Расширенные возможности и настройка конфигурации

Плагин предоставляет доступ к низкоуровневым картам Xray для тонкой настройки. Это позволяет изменять параметры входящих соединений, маршрутизации, логирования и потоковой передачи. Для более безопасной работы рекомендуется использовать типизированные помощники из xray_config_model.dart и xray_config_validator.dart, которые проверяют корректность конфигурации перед отправкой в нативный слой.

Плагин также поддерживает проверку задержки сервера через getServerDelay(), что полезно для отображения пинга в интерфейсе. Статус подключения отслеживается через колбэк onStatusChanged.

Для импорта подписок и Clash-конфигураций используйте parseMany(). Это позволяет загрузить все доступные профили и предоставить пользователю выбор.

Ограничения и требования к платформам

Несмотря на широкую поддержку, у плагина есть ограничения:

• iOS: VPN-режим работает только на реальном устройстве с подписью. Симулятор не поддерживается.
• macOS: требуется macOS 13.0 или новее, а также настроенная подпись Apple Team.
• Windows: для VPN-режима нужен xray.exe и права администратора.
• Android: VPN-режим требует разрешения пользователя, но работает на эмуляторе.

Плагин не предоставляет встроенного UI — разработчик должен создать интерфейс самостоятельно. Однако в комплекте есть пример приложения, который демонстрирует импорт из буфера обмена, редактирование маршрутов и отображение статуса.

Также важно помнить, что использование VPN-протоколов может регулироваться законодательством в некоторых странах. Разработчик несёт ответственность за соблюдение местных законов.

Заключение и рекомендации

Flutter_vless — это мощный инструмент для создания кроссплатформенных VPN-приложений на Flutter. Он избавляет от необходимости писать нативный код для каждой платформы и предоставляет единый API для работы с популярными протоколами.

Для начала рекомендуется изучить пример приложения и документацию, особенно разделы Platform Guides и Configuration Guide. Это поможет избежать типичных ошибок при настройке.

Если вы планируете коммерческое использование, обратите внимание на лицензию MIT — она позволяет свободно использовать и модифицировать плагин, но требует сохранения уведомления об авторских правах.

В целом, flutter_vless — отличный выбор для разработчиков, которые хотят быстро создать VPN-клиент с поддержкой современных протоколов, не углубляясь в детали реализации Xray.

Вопросы и ответы