sing-box JSON: обязательные поля минимальной конфигурации

sing-box — универсальный прокси-ядро, которое поддерживает VLESS, Trojan, Shadowsocks и другие протоколы. При переходе с других инструментов часто возникает вопрос: какой минимальный набор полей JSON обязателен, чтобы конфигурация была валидной и работала? В этой статье разберём структуру минимальной конфигурации, объясним назначение каждого обязательного блока и покажем пошаговую настройку от сервера до клиента.

Что такое минимальная конфигурация sing-box?

Минимальная конфигурация — это JSON-файл, в котором отсутствуют все необязательные параметры, но при этом ядро стартует, принимает соединения и корректно маршрутизирует трафик. В зависимости от сценария (сервер, клиент, TUN) набор обязательных полей различается, но есть общий каркас: всегда требуются ключи log, dns, inbounds, outbounds и route. Даже если вы не собираетесь использовать DNS или свою маршрутизацию, эти поля должны присутствовать, хотя бы с минимальными значениями.

Обязательные поля JSON: логика и структура

В файле конфигурации sing-box верхний уровень — это объект. Согласно официальной документации, разделы log, dns, inbounds, outbounds, route являются обязательными в том смысле, что без них ядро либо откажется запускаться, либо будет работать некорректно. Давайте рассмотрим каждый:

• log — определяет уровень логирования. Минимально: "level": "info".
• dns — DNS-серверы и правила. Минимально: указать хотя бы один сервер (servers). Без этого sing-box может не резолвить домены для маршрутизации.
• inbounds — точки входа (локальный SOCKS, HTTP, TUN и т.д.). Обязательно описать хотя бы один.
• outbounds — исходящие подключения (direct, VLESS, Trojan). Минимум — один outbound.
• route — правила маршрутизации. Минимально можно указать "final": "outbound" (или default).

С точки зрения синтаксиса, JSON должен быть строго валидным, без комментариев и запятых в конце. Новички часто пропускают обязательные поля, и sing-box выдаёт ошибку missing outbounds или missing dns.

Пошаговая настройка: от core до клиента

Рассмотрим практический пример. Допустим, у нас есть VPS-сервер с установленным sing-box. Создайте файл config.json:

{
  "log": { "level": "info" },
  "dns": { "servers": [ {"address": "8.8.8.8"} ] },
  "inbounds": [
    {
      "type": "vless",
      "tag": "vless-in",
      "listen": "0.0.0.0",
      "listen_port": 443,
      "users": [ { "uuid": "ваш-uuid" } ],
      "tls": { "enabled": true, "certificate_path": "/etc/ssl/cert.pem", "key_path": "/etc/ssl/key.pem" }
    }
  ],
  "outbounds": [
    { "type": "direct", "tag": "direct" }
  ],
  "route": { "final": "direct" }
}

На клиенте конфигурация выглядит иначе: inbound обычно — локальный SOCKS или TUN, outbound — VLESS-сервер. Например:

{
  "log": { "level": "info" },
  "dns": { "servers": [ { "address": "8.8.8.8" } ] },
  "inbounds": [
    { "type": "socks", "listen": "127.0.0.1", "listen_port": 1080 }
  ],
  "outbounds": [
    {
      "type": "vless",
      "server": "ваш-сервер.com",
      "server_port": 443,
      "uuid": "ваш-uuid",
      "tls": { "enabled": true, "server_name": "ваш-сервер.com" }
    }
  ],
  "route": { "final": "vless-out" }
}

В этом минимальном примере мы не добавляем правило для обхода локальных IP, но это ок для старта. Обратите внимание на поле route.final — оно указывает, какой outbound используется по умолчанию.

Маршрутизация (route) и DNS в минимальной конфигурации

Раздел route в sing-box позволяет гибко управлять тем, какой трафик идёт через какой outbound. В минимальной конфигурации достаточно одного поля final. Однако есть обязательный подводный камень: если в dns не указаны серверы, sing-box может резолвить домены только через системный резолвер, но при включённом TUN это часто ломает маршрутизацию. Поэтому мы добавляем хотя бы один DNS-сервер (например, 8.8.8.8 или 1.1.1.1).

Для более продвинутой маршрутизации (например, чтобы не проксировать локальные адреса) можно добавить правила в rules. Но в рамках минимальной конфигурации это не обязательно. Важно понимать: если вы используете TUN, то dns становится критическим, так как перехватываются все DNS-запросы системы.

TUN и VLESS: обязательные поля transport

TUN (сетевой интерфейс) в sing-box является типом inbound. Минимальные поля для TUN:

{
  "type": "tun",
  "tag": "utun",
  "interface_name": "tun0",
  "mtu": 1500,
  "auto_route": true
}

Но для работы TUN требуется, чтобы в route была правильная маршрутизация. Часто также указывают strict_route и stack. При использовании TUN обязательно в outbounds должны быть и direct, и проксирующий outbound, иначе трафик зациклится.

Что касается VLESS outbound, обязательные поля: server, server_port, uuid, а также tls (если на сервере включён TLS). Внутри tls обязательны enabled и server_name. Для transport (например, WebSocket, gRPC) поле называется transport. Если server на VLESS использует transport.type": "ws", то клиент обязан указать тот же тип и путь. Пример:

"transport": { "type": "ws", "path": "/ws", "headers": { "Host": "example.com" } }

Поле transport не является обязательным в самом VLESS, но если сервер настроен на WS, то без него клиент не подключится. Поэтому при переносе конфигурации всегда сверяйте transport.

Проверка и диагностика конфигурации

Прежде чем запускать sing-box, проверьте JSON на валидность. Используйте sing-box check (команда в CLI) для локальной проверки. Если вы используете панель, то она сама проверит, но вручную это тоже полезно. Основные ошибки:

1. Отсутствует dns.servers — ядро предупреждает, но может работать.
2. Неправильно указан uuid — VLESS не соединится.
3. В outbounds нет ни одного прямого outbound — TUN зациклится.
4. Не совпадает transport на клиенте и сервере.

Для диагностики сетевых проблем используйте log.level": "debug". В логах будет видно, как обрабатывается соединение, какой outbound выбран, есть ли ошибки TLS. После проверки верните уровень на info, чтобы не засорять диск.

Помните: sing-box активно развивается, поэтому всегда сверяйтесь с официальной документацией на sing-box.sagernet.org. Версии, упомянутые в этой статье (1.11.x), могут устареть, но структура основных полей остаётся стабильной.