sing-box Status — расширение для GNOME Shell

Показывает статус прокси sing-box в верхней панели GNOME, используя встроенный Clash API.

Что показывает

В панели (компактно):

• монохромный индикатор-кружок (цвет берётся из цвета текста панели, поэтому индикатор одинаково читается на тёмной и светлой теме):

  • яркий залитый круг — сервис работает и через активный outbound есть связь;
  • тусклый залитый круг — сервис работает, связь ещё проверяется;
  • яркое сплошное кольцо — сервис работает, но связи через outbound нет;
  • пунктирное тусклое кольцо — сервис (Clash API) недоступен / подключение.

  Различие «есть связь / нет связи / проверяется» доступно только при включённой опции «Connectivity check» (см. ниже) — иначе кружок просто залит, когда API отвечает, и пунктирный, когда нет. Связь измеряется только для узла группы, показанной в панели; реальный трафик может идти по другим правилам и группам — см. разбивку соединений в меню;

• имя активного outbound (текущий узел группы);

• текущую скорость, например ↓2.4M ↑120K.

В выпадающем меню (подробности):

• строка статуса: sing-box · Active / Unreachable, а при включённой проверке связности также Active (checking…) (связь проверяется) и No connectivity (связи через outbound нет);
• полная скорость (↓ 2.4 MB/s ↑ 120 KB/s);
• каждая группа outbound'ов отдельным подменю. Selector-группы переключаемы — выбор узла меняет активный outbound; URLTest/Fallback-группы показываются только для просмотра (узел выбирает сам sing-box). Текущий узел помечен точкой, рядом — последняя измеренная задержка, если она есть. Пункт Test latency в подменю запускает ручной замер задержки всех узлов группы по адресу connectivity-url и обновляет значения на месте (меню при этом не закрывается);
• число активных соединений с разбивкой по outbound;
• Open dashboard (MetaCubeXD или ваш дашборд Clash) и Settings.

Требования

• GNOME Shell 45–48.
• sing-box с включённым experimental_clash_api:

{
  "experimental": {
    "clash_api": {
      "external_controller": "127.0.0.1:9090",
      "secret": "ваш-секрет",
      "external_ui": "..."        // опционально, для дашборда
    }
  }
}

Установка

Полная последовательность после свежего git clone (в репозитории нет собранной схемы — её нужно скомпилировать локально, шаг 3):

# 1. Клонировать репозиторий
git clone https://git.vakhrushev.me/av/sing-box-gnome-extension.git
cd sing-box-gnome-extension

# 2. Установить как пользовательское расширение. Симлинк на клон удобен тем, что
#    обновления затем подтягиваются простым `git pull` (не удаляйте каталог клона).
UUID="sing-box-status@git.vakhrushev.me"
mkdir -p "$HOME/.local/share/gnome-shell/extensions"
ln -s "$PWD" "$HOME/.local/share/gnome-shell/extensions/$UUID"

# 3. Скомпилировать схему GSettings (обязательно: gschemas.compiled не хранится в git)
glib-compile-schemas schemas/

# 4. Перезапустить GNOME Shell, чтобы он увидел новое расширение:
#      X11     — Alt+F2, ввести «r», Enter
#      Wayland — выйти из сессии и войти снова (перезапуск на лету невозможен)

# 5. Включить расширение
gnome-extensions enable "$UUID"

Вместо симлинка можно скопировать файлы (cp -r . "$HOME/.local/share/gnome-shell/extensions/$UUID"), но тогда каждое обновление придётся копировать заново.

Проверить состояние:

gnome-extensions info sing-box-status@git.vakhrushev.me   # ENABLED / DISABLED / ошибки

После включения откройте Settings из меню расширения (или gnome-extensions prefs "$UUID") и задайте:

• API URL — например http://127.0.0.1:9090 (ваш external_controller);
• Secret — ваш clash_api.secret;
• Dashboard URL — например http://127.0.0.1:9091.

Обновление

cd sing-box-gnome-extension && git pull
glib-compile-schemas schemas/          # если менялась схема
# перезапуск GNOME Shell (см. шаг 4) — на Wayland через перелогин

Отключение и удаление

Временно отключить (расширение остаётся установленным, настройки сохраняются):

gnome-extensions disable sing-box-status@git.vakhrushev.me

Снова включить:

gnome-extensions enable sing-box-status@git.vakhrushev.me

Отключать и включать можно и через GUI — приложение Extensions («Расширения») или Extension Manager.

Полностью удалить:

UUID="sing-box-status@git.vakhrushev.me"
gnome-extensions disable "$UUID"
rm "$HOME/.local/share/gnome-shell/extensions/$UUID"   # симлинк (или каталог при копировании)
dconf reset -f /org/gnome/shell/extensions/sing-box-status/   # необязательно: сбросить настройки

На Wayland индикатор из панели исчезнет после перелогина.

Как это работает

Каждые N секунд (по умолчанию 2) расширение опрашивает две точки Clash API:

• GET /connections — накопительные downloadTotal / uploadTotal (скорость — их приращение за интервал) и список активных соединений с цепочками outbound;
• GET /proxies — Selector-группы, их текущий узел и история задержек по узлам.

Переключение outbound выполняется запросом PUT /proxies/{group} с телом {"name": "..."}. По умолчанию расширение не шлёт активных замеров задержки — показываются только те, что sing-box измерил сам. Ручной замер (пункт Test latency) выполняется через GET /proxies/{name}/delay только по нажатию.

Проверка связности (опция). Если включить check-connectivity в настройках, расширение раз в connectivity-interval секунд (по умолчанию 30) делает GET /proxies/{активный-узел}/delay по адресу connectivity-url (по умолчанию https://www.gstatic.com/generate_204). Успех → кружок залит и в меню показывается задержка (Active · N ms); ошибка/таймаут → сплошное кольцо и No connectivity. Это единственный режим, когда расширение шлёт трафик в фоне; по умолчанию он выключен.

Сетевой слой (авторизация, разбор ответов, переключение outbound) проверен на живом API sing-box 1.13.13.

Файлы

• extension.js — точка входа, добавляет кнопку в панель.
• metadata.json — метаданные расширения (UUID, версии GNOME Shell).
• lib/indicator.js — виджет панели, меню, цикл опроса, отрисовка.
• lib/clashApi.js — асинхронный клиент Clash API на libsoup 3.
• lib/format.js — форматирование байтов и скорости.
• prefs.js — настройки на Adwaita.
• stylesheet.css — стили индикатора и меню.
• schemas/ — схема GSettings.

Лицензия

MIT — см. LICENSE.