How am1rtl/ambox works
Назначение и запуск
ambox — Linux desktop-клиент для импорта sing-box/NekoBox VPN-профилей, управления локальным sing-box и отображения статуса подключения. Точки запуска: main.py и __main__.py; основное GUI-приложение собирается вокруг главного окна в app/main_window.py.
GUI и пользовательский поток
Главный интерфейс управляет импортом/выбором профиля, routing/DNS-настройками, подключением, логами, latency и traffic statistics. Центральный UI-компонент — app/main_window.py; краткие пользовательские уведомления выделены в app/toast.py. UI передаёт выбранный профиль и параметры подключения менеджеру VPN, а результаты процесса и измерений возвращаются в окно.
Профили и разбор конфигураций
Импортируются sing-box JSON и ссылки VMess, VLESS, Trojan, Shadowsocks, HTTP и SOCKS. Парсинг и нормализация входных форматов сосредоточены в app/config_parser.py. Результатом является профиль/конфигурация, пригодные для сохранения и генерации активной sing-box-конфигурации; постоянные профили хранятся в ~/.ambox/profiles.json.
Управление sing-box
app/vpn_manager.py образует границу между приложением и системным VPN-движком: подготавливает активную конфигурацию, запускает/останавливает sing-box run -c <config>, получает состояние и логи процесса. Активный конфиг располагается в ~/.ambox/active-config.json; для TUN-режима внешний бинарник sing-box должен быть в PATH и обычно требует CAP_NET_ADMIN. Установка из UI использует системные привилегии через pkexec и APT/SagerNet.
Routing и DNS как конфигурационная граница
Настройки интерфейса преобразуются в sing-box-правила: проксирование всего трафика, доменных списков либо исключений; отдельно поддерживаются обход .ru, поддомены и DNS через прокси/напрямую/custom server. Проверка и формирование этих параметров относятся к жизненному циклу подключения в app/vpn_manager.py, а их разбор и сохранение настроек — к app/config_parser.py и app/app_paths.py.
Latency, автопереключение и статистика
app/latency.py измеряет доступность профилей TCP-подключением к их endpoint с пользовательским timeout. Эти результаты питают UI и режим автоматического выбора минимальной задержки перед/во время использования профилей. Накопительная traffic statistics и UI/routing/DNS-параметры сохраняются в ~/.ambox/settings.ini.
Локальное состояние, логирование и поставка
app/app_paths.py централизует расположение пользовательского состояния под ~/.ambox: настройки, профили, active config, cache.db, application log и папку ручного импорта. build_linux.sh упаковывает приложение как одиночный Linux ELF через PyInstaller; зависимости Python определены в requirements.txt. Debug-флаг -d включает более подробные логи и traceback.
Main entry points: main_window.py Main window · vpn_manager.py VPN manager · app_paths.py App paths & settings · config_parser.py Config parser
Components 14
Desktop UI
- Main window · Coordinates profiles, connection controls, settings, logs, latency, and traffic UI.
app/main_window.py - Toast notifications
app/toast.py
Connection core
- Config parser · Imports and normalizes sing-box JSON and supported VPN links.
app/config_parser.py - VPN manager · Builds active configuration and controls the local sing-box process.
app/vpn_manager.py - sing-box engine · Runs the generated configuration; TUN mode needs CAP_NET_ADMIN.
- Latency checker · TCP-probes profile endpoints for UI display and automatic profile selection.
app/latency.py
Local state
- App paths & settings · Centralizes state locations and persists UI, routing, DNS, and statistics settings.
app/app_paths.py - Saved profiles
- Settings & traffic stats
- Active sing-box config
- Cache, logs & imports · Includes cache.db, application log, and manual-import directory.
Delivery
- Linux package build · Builds a single Linux ELF application.
build_linux.sh - Python dependencies
requirements.txt
Other components
- CLI entry points · Starts the desktop client and enables debug mode.
main.py
Connections 16
- CLI entry points → Main window: launches
- Main window → Config parser: imports profiles
- Config parser → Saved profiles: saves normalized profiles
- Main window → Saved profiles: selects profile
- Main window → App paths & settings: loads and saves preferences
- App paths & settings → Settings & traffic stats: persists
- App paths & settings → Cache, logs & imports: locates
- Main window → VPN manager: connect, disconnect, routing and DNS
- VPN manager → Active sing-box config: generates
- VPN manager → sing-box engine: starts and monitors
- VPN manager → Main window: status and process logs
- Main window → Latency checker: requests measurements
- Latency checker → Main window: latency and auto-select result
- Main window → Toast notifications: shows brief feedback
- Python dependencies → Linux package build: supplies build dependencies
- Linux package build → CLI entry points: packages application