Сервис API — sing-box

Сервис api — это gRPC-сервер для наблюдения за запущенным экземпляром sing-box и управления им: состояние сервиса, журналы, группы исходящих (выбор и URL-тесты), режим Clash, отслеживание соединений, а также инструменты вроде тестов качества сети и STUN или операций Tailscale. Он предоставляет тот же интерфейс, который графические клиенты используют локально, поэтому их функция удалённого управления, веб-клиент sing-box Dashboard и команда sing-box api могут управлять удалённым экземпляром. Слушатель также принимает gRPC-Web (включая транспорт WebSocket клиента gRPC-Web от improbable-eng для потоковых вызовов), так что браузер может обращаться к нему напрямую.

Параметры

type: "api" в services[]:

Поле	Тип	По умолчанию	Допустимые значения	Описание
secret	string	(empty)	<string>	Общий секрет. Клиенты передают его в заголовке метаданных gRPC authorization: Bearer <secret>. Пустое значение полностью отключает аутентификацию, поэтому всегда задавайте его на слушателе, доступном с других хостов.
access_control_allow_origin	badoption.Listable[string]	*	<origin> | …	Разрешённые источники CORS для браузерных (gRPC-Web) клиентов, например sing-box Dashboard. Пустое значение означает *.
access_control_allow_private_network	bool	false	true | false	Отвечать на предварительные запросы Private Network Access (Access-Control-Allow-Private-Network), чтобы страница с публичного источника — например, размещённая Dashboard — могла обращаться к API, слушающему частный или loopback-адрес.
dashboard	*APIDashboardOptions	(disabled)	true | false | <directory path> | APIDashboardOptions	Отдавать sing-box Dashboard по пути /dashboard/ на том же слушателе; остальные браузерные запросы перенаправляются туда. true равносильно { "enabled": true }, а строка — сокращение для { "enabled": true, "path": "<string>" }.

Исходный код: option/api.go:11-18 · зафиксировано на v1.14.2 (af6e64c)

Сервис также встраивает ListenOptions (listen, listen_port, … — см. Входящие) и входящий блок tls (см. TLS). Порта по умолчанию нет — задайте listen_port явно.

dashboard

Поле	Тип	По умолчанию	Допустимые значения	Описание
enabled	bool	false	true | false	Включить панель управления.
path	string	dashboard	<directory path>	Каталог с файлами панели относительно рабочего каталога. Пустой каталог заполняется загрузкой и отслеживается файлом .etag; непустой каталог без .etag отдаётся как есть и никогда не обновляется.
download_url	string	(gh-pages archive)	<URL>	Zip-архив, из которого загружается панель. По умолчанию — архив ветки gh-pages репозитория sing-box-dashboard на GitHub.
http_client	*HTTPClientOptions	(default client)	<http_clients tag> | HTTPClientOptions	HTTP-клиент для загрузки: встроенный объект или тег записи http_clients. Не используется, если в каталоге файлы пользователя.
update_interval	badoption.Duration	1d	<duration>	Как часто проверять адрес загрузки на наличие более нового архива панели.

Исходный код: option/api.go:20-26 · зафиксировано на v1.14.2 (af6e64c)

Команда sing-box api

sing-box api — клиент командной строки для этого сервиса с теми же операциями, что и в графических клиентах: состояние, журналы, группы исходящих, режим Clash, соединения, тесты качества сети и STUN, Tailscale, аутентификация OpenVPN / OpenConnect, USB/IP и другое. Укажите сервис через --url (или $BOX_API_URL; без схемы подразумевается http://) и --secret (или $BOX_API_SECRET).

Минимальный пример

{
  "services": [
    {
      "type": "api",
      "tag": "api",
      "listen": "127.0.0.1",
      "listen_port": 9091,
      "secret": "change-me",
      "dashboard": true
    }
  ]
}

sing-box api --url 127.0.0.1:9091 --secret change-me status

При dashboard: true открытие http://127.0.0.1:9091/ в браузере перенаправляет на Dashboard.

Примечания

• Пустой secret означает, что любой, кто может достучаться до порта, может читать журналы, переключать группы исходящих и закрывать соединения. Держите слушатель на loopback либо задайте secret (и tls), прежде чем открывать его наружу.
• Без tls слушатель говорит на HTTP/1.1 и HTTP/2 без шифрования (h2c); с tls в список ALPN автоматически добавляются h2 и http/1.1.
• Панель загружается при запуске сервиса и перепроверяется каждые update_interval. Каталог, где уже есть файлы, но нет .etag, считается пользовательским: он отдаётся как есть и никогда не перезаписывается.
• Сервису не нужен тег сборки.
• REST API, совместимый с Clash, — отдельная функция, experimental.clash_api; см. Экспериментальное.

Сравнение с другими ядрами

• Xray-core предоставляет gRPC API (api.services, например HandlerService и StatsService), доступный через отдельное входящее и правило маршрутизации. Встроенной панели управления у него нет.
• mihomo использует совместимый с Clash REST внешний контроллер, по желанию с веб-интерфейсом, — это то же семейство API, что и experimental.clash_api в sing-box, а не этот gRPC-сервис.

Исходный код: option/api.go:11-26 · v1.14.2 (af6e64c)