WireGuard Manager

Профессиональное GUI приложение для управления профилями WireGuard на Ubuntu 22.04/24.04.

📋 Содержание

• Быстрый старт
• Особенности
• Установка
• Настройка PolicyKit
• Использование
• Логирование
• Тестирование
• Разработка
• Лицензия

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

1. Клонируйте репозиторий:

   git clone <repository-url>
   cd wg-manager

2. Запустите установку:

   chmod +x install.sh run.sh
   ./install.sh

3. Запустите приложение:

   ./run.sh

Готово! Приложение появится в меню приложений как "WireGuard Manager".

✨ Особенности

🔧 Технические возможности

• Профессиональное логирование с ротацией, цветным выводом и раздельными файлами
• 100% покрытие тестами критической бизнес-логики
• Безопасность через PolicyKit (pkexec) вместо прямого sudo
• Асинхронный UI с блокировкой кнопок во время операций
• Защита от повторных кликов (дебаунс 500 мс)
• Настраиваемые профили через конфигурационный файл

🎨 Интерфейс

• Адаптивный интерфейс 700x500px
• Темная тема GTK (Adwaita-dark)
• Цветная индикация статуса профилей
• Вкладки "Статус" и "Логи"
• Горячие клавиши (Ctrl+1, Ctrl+2, Ctrl+3, F5)

📊 Мониторинг

• Реальное время работы соединения
• Статистика передачи данных (МБ принято/отправлено)
• Вывод команды wg show
• Просмотр последних 100 записей логов

📦 Установка

Автоматическая установка

./install.sh

Скрипт выполнит:

1. Установку системных зависимостей (wireguard-tools, python3-gi, policykit-1)
2. Настройку PolicyKit
3. Создание директорий для логов
4. Интеграцию в системное меню
5. Запуск тестов

Ручная установка

Зависимости

sudo apt update
sudo apt install wireguard-tools policykit-1 python3 python3-pip \
                 python3-gi python3-gi-cairo gir1.2-gtk-3.0 \
                 gir1.2-glib-2.0 python3-setuptools

Настройка PolicyKit

Скрипт установки автоматически создаст файл политики в /usr/share/polkit-1/actions/org.wireguard.manager.policy

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

Убедитесь, что профили созданы в /etc/wireguard/:

• App.conf
• bomBox.conf
• usa.conf

⚙️ Конфигурация профилей

По умолчанию приложение работает с тремя профилями: App, bomBox, usa. Вы можете изменить этот список через конфигурационный файл.

Настройка через конфигурационный файл

Создайте файл ~/.local/share/wg-manager/config.json:

{
  "profiles": ["myprofile1", "myprofile2", "vpn-work", "vpn-home"]
}

Важно: Имена профилей должны соответствовать именам файлов конфигурации в /etc/wireguard/ (без расширения .conf).

Пример для двух профилей

{
  "profiles": ["work", "home"]
}

Соответствующие файлы конфигурации должны существовать:

• /etc/wireguard/work.conf
• /etc/wireguard/home.conf

Пользовательские настройки

Вы также можете настроить другие параметры (в разработке):

{
  "profiles": ["App", "bomBox"],
  "timeout_wg_show": 30,
  "timeout_wg_quick": 60,
  "auto_refresh_interval": 2
}

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

🔐 Настройка PolicyKit

Файл политики

Установщик создает следующий файл политики:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE policyconfig PUBLIC
 "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
 "http://www.freedesktop.org/standards/PolicyKit/1/policyconfig.dtd">
<policyconfig>
  <action id="org.wireguard.manager.run-wg-quick">
    <description>Run wg-quick commands for WireGuard profiles</description>
    <message>Authentication is required to manage WireGuard VPN connections</message>
    <icon_name>network-wireless</icon_name>
    <defaults>
      <allow_any>auth_admin</allow_any>
      <allow_inactive>auth_admin</allow_inactive>
      <allow_active>auth_admin_keep</allow_active>
    </defaults>
    <annotate key="org.freedesktop.policykit.exec.path">/usr/bin/wg-quick</annotate>
    <annotate key="org.freedesktop.policykit.exec.allow_gui">false</annotate>
  </action>
</policyconfig>

Проверка политики

pkaction --action-id org.wireguard.manager.run-wg-quick

🖥️ Использование

Запуск приложения

./run.sh                    # Обычный запуск
./run.sh --debug           # С отладкой
./run.sh --no-gui          # Без GUI (для CI)
./run.sh --log-level=DEBUG # Детальное логирование

Горячие клавиши

• Ctrl+1: Отключить все профили
• Ctrl+2: Активировать bomBox
• Ctrl+3: Активировать App
• F5: Обновить статус

Функции кнопок

🔴 OFF

Отключает все профили в последовательности:

wg-quick down App
wg-quick down bomBox
wg-quick down usa

🌍 Bombox

Активирует профиль bomBox:

wg-quick down App
wg-quick down usa
wg-quick up bomBox

📱 App

Активирует профиль App:

wg-quick down usa
wg-quick down bomBox
wg-quick up App

📝 Логирование

Файлы логов

• Основной лог: ~/.local/share/wg-manager/wg-manager.log
• Лог ошибок: ~/.local/share/wg-manager/errors.log

Формат логов

[2026-02-14 15:30:22] [INFO] [core:45] Активация профиля bomBox...
[2026-02-14 15:30:23] [DEBUG] [core:89] Команда выполнена успешно за 1.23с
[2026-02-14 15:30:24] [WARNING] [core:102] Профиль уже активен

Уровни логирования

• DEBUG: Все команды перед выполнением, сырые выводы
• INFO: Успешные операции, смена статуса
• WARNING: Профиль уже активен/отключен
• ERROR: Ошибки выполнения команд
• CRITICAL: Системные ошибки (PolicyKit, права)

Экспорт логов

Нажмите "💾 Сохранить лог" в интерфейсе для экспорта последних 1000 строк.

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

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

cd wg-manager
python3 -m pytest tests/ -v

Покрытие кода

python3 -m pytest tests/ --cov=wg_manager --cov-report=term-missing

Структура тестов

tests/
├── test_core.py     # Тесты бизнес-логики (100% покрытие)
└── test_logger.py   # Тесты системы логирования

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

• Активация/деактивация профилей
• Валидация конфигураций
• Обработка ошибок
• Идемпотентность операций
• Парсинг вывода команд

🛠️ Разработка

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

wg-manager/
├── wg-manager.py          # Основной файл приложения
├── wg_manager/            # Пакет с модулями
│   ├── __init__.py
│   ├── core.py           # Бизнес-логика
│   ├── logger.py         # Система логирования
│   └── ui.py             # GUI компоненты
├── tests/                 # Автотесты
│   ├── __init__.py
│   ├── test_core.py
│   └── test_logger.py
├── run.sh                # Скрипт запуска
├── install.sh            # Скрипт установки
├── wg-manager.desktop    # Файл для меню приложений
└── README.md             # Документация

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

• Python 3.10+ с type hints
• Следование PEP 8
• 100% покрытие тестами критической логики
• Комментарии на русском языке

Сборка

# Установка зависимостей разработчика
pip install pytest pytest-cov

# Запуск линтера
python3 -m py_compile wg_manager/*.py

# Запуск тестов
python3 -m pytest tests/ --cov=wg_manager --cov-report=html

🔧 Устранение неполадок

Ошибка: "Не удалось импортировать GTK"

sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-3.0

Ошибка: "PolicyKit не обнаружен"

sudo apt install policykit-1

Ошибка: "Нет прав на /etc/wireguard"

sudo chmod 755 /etc/wireguard
# Или добавьте пользователя в соответствующую группу

Ошибка: "Профиль не найден"

Убедитесь, что файлы конфигурации существуют:

ls -la /etc/wireguard/*.conf

Просмотр логов

tail -f ~/.local/share/wg-manager/wg-manager.log

📄 Лицензия

MIT License

Copyright (c) 2026 WireGuard Manager

Разрешается бесплатное использование, копирование, изменение и распространение программного обеспечения при условии указания авторства.

🤝 Вклад в проект

1. Форкните репозиторий
2. Создайте ветку для вашей функции
3. Внесите изменения
4. Добавьте тесты
5. Отправьте pull request

📞 Поддержка

• Отчеты об ошибках: Issues
• Документация: Wiki

---

WireGuard Manager — профессиональный инструмент для управления VPN соединениями с открытым исходным кодом.