Throne API и thronectl

Throne API (начиная с 1.4.0) позволяет скриптам, программам для горячих клавиш и другим устройствам управлять Throne: запускать и останавливать профили, переключать режим TUN и системный прокси, менять профиль маршрутизации, запускать тесты, получать список профилей и статистику трафика. Через него также можно администрировать Throne: импортировать профили, добавлять и обновлять подписки, удалять группы и профили, менять настройки, создавать и восстанавливать резервные копии, перезапускать Throne и завершать его работу.

thronectl — клиент командной строки для API. На этой странице описано, как включить API в Throne для компьютера, как установить и подключить thronectl и что делает каждая команда.

В Headless Throne, который работает без окна на сервере или в контейнере, API включён с первого запуска, а управляют им с помощью thronectl. Как подключиться к нему и настроить его, описано на странице Управление через thronectl.

В Throne для Android нет Throne API.

Включение API в Throne

По умолчанию API выключен.

1. Откройте Настройки (Settings) → Integration Settings, а затем вкладку Throne API.
2. Отметьте Enable the Throne API. Throne создаст новый ключ.
3. Нажмите ОК (OK). В поле Status появится Listening on 127.0.0.1:9095.

На вкладке есть следующие элементы:

Элемент	Что делает
Enable the Throne API	Включает API.
Listen on	This computer only (по умолчанию): API слушает 127.0.0.1, поэтому подключаться могут только программы на этом компьютере. Local network: API слушает все адреса компьютера, поэтому подключаться могут и другие устройства.
Port	TCP-порт, по умолчанию 9095.
Allowed addresses	Только с Local network: IP-адреса и диапазоны, с которых можно подключаться, например 192.168.1.0/24, 10.0.0.5, через запятую или пробел. Если поле пустое, подключаться можно с любого адреса. Программы на этом компьютере всегда могут подключиться через 127.0.0.1.
Разрешить управление из локальной сети (Allow management from the local network)	Только с Local network: другие устройства тоже могут отправлять административные запросы, например импорт, изменение настроек и резервное копирование. Программы на этом компьютере могут отправлять их всегда.
Key	Секретный ключ длиной 43 символа, который нужен клиентам. Show показывает его, Copy копирует, а Regenerate создаёт новый.
Copy for scripts	Копирует две настройки, которые читает thronectl: THRONE_ADDR и THRONE_KEY. С Local network в качестве адреса указывается адрес компьютера в вашей сети.
Status	Слушает ли Throne, например Listening on port 9095 (local network), а если нет, то почему, например Port 9095 is in use.

• Изменения вступают в силу, когда вы нажимаете ОК. Новый ключ, порт или адрес закрывает открытые подключения. Скрипты со старым ключом перестают работать, поэтому Throne спрашивает подтверждение, прежде чем Regenerate заменит сохранённый ключ.
• С Local network окно предупреждает, что устройства в вашей сети могут управлять Throne с помощью ключа. Брандмауэр может спросить, разрешить ли Throne подключения.
• Каждый запрос, который что-то меняет, Throne записывает в лог вместе с адресом клиента, например [API] PUT /v1/connection from 127.0.0.1. В строках, которые начинаются с [API], также видны отклонённые подключения.
• Если включён kill switch и API слушает локальную сеть, kill switch пропускает ответы API, поэтому клиенты по-прежнему могут подключиться.

Установка thronectl

thronectl — это одна программа для Linux, Windows, macOS и FreeBSD. Она не входит в пакеты Throne; в образе Docker для headless Throne она есть.

• Скачайте её со страницы релизов Throne-api, распакуйте и поместите thronectl (thronectl.exe в Windows) в папку, которая указана в PATH.

• Или, если установлен Go:

  go install github.com/throneproj/Throne-api/cmd/thronectl@latest
  

thronectl version выводит версию программы.

Подключение thronectl к Throne

thronectl читает адрес Throne и ключ из переменных окружения:

Переменная	Что содержит
THRONE_ADDR	Адрес и порт, например 127.0.0.1:9095. По умолчанию: 127.0.0.1:9095.
THRONE_KEY	Сам ключ.
THRONE_KEY_FILE	Путь к файлу, в котором хранится ключ.

thronectl никогда не принимает ключ как аргумент командной строки, поэтому ключ не попадает в историю оболочки. Храните его в файле, который можете читать только вы, и укажите этот файл в THRONE_KEY_FILE:

1. В Throne нажмите Copy for scripts.

2. Сохраните в файл строку THRONE_KEY=… без THRONE_KEY=, то есть только ключ, например в ~/.config/throne/api-key. В Linux и macOS выполните для этого файла chmod 600.

3. Задайте переменные, например в ~/.bashrc:

   export THRONE_ADDR=127.0.0.1:9095
   export THRONE_KEY_FILE=~/.config/throne/api-key
   

   В PowerShell, например в $PROFILE:

   $env:THRONE_ADDR = "127.0.0.1:9095"
   $env:THRONE_KEY_FILE = "$HOME\throne-api-key.txt"
   

4. Проверьте подключение:

   thronectl status
   

Эти флаги можно указывать до или после команды:

Флаг	Что делает
--addr host:port	Адрес Throne. По умолчанию: THRONE_ADDR, а если она не задана, то 127.0.0.1:9095.
--key-file file	Читает ключ из этого файла. Имеет приоритет над THRONE_KEY и THRONE_KEY_FILE.
--json	Выводит ответ Throne в формате JSON вместо таблицы.
--timeout 30s	Прекращает ожидание через указанное время, по умолчанию 30s. 0 означает ждать столько, сколько нужно Throne.

Для headless Throne команда Throne --print-connection выводит строки export для обеих переменных. См. Подключение thronectl к Throne.

Команды

thronectl help <command> описывает команду. В своих списках thronectl показывает ID профилей, групп, профилей маршрутизации и тестов; команды принимают эти ID.

Команда	Что делает
status	Показывает состояние, запущенный профиль, режимы, профиль маршрутизации, версию Throne, а если TUN занят чем-то другим, то чем именно.
groups	Выводит список групп с их ID.
profiles [--group N] [--name REGEX] [--ids 1,2]	Выводит список профилей с результатами их последних тестов.
connect <id>	Запускает профиль. --restart перезапускает его, если он уже запущен.
connect last	Запускает работающий профиль, если его нет, то последний, а если нет и его, то запомненный.
connect best [--group N] [--name REGEX] [--max-age 1h]	Запускает профиль с наименьшей задержкой. Сначала проверяет профили, у которых нет результата новее --max-age. По умолчанию используется группа, которую показывает Throne.
disconnect	Останавливает запущенный профиль.
toggle	connect last, если ничего не запущено, иначе disconnect.
tun on, tun off, tun toggle	Включает или выключает режим TUN.
proxy on, proxy off, proxy toggle	Включает или выключает системный прокси.
routes	Выводит список профилей маршрутизации.
route <id>	Делает профиль маршрутизации активным и перезапускает запущенный профиль.
test latency, test ip, test speed	Выполняет тест задержки (URL-тест), тест IP или тест скорости и показывает результаты. Добавьте --group N (при необходимости с --name REGEX) или ID профилей.
jobs, job <id>, cancel <id>	Выводит список недавних тестов, показывает один тест, останавливает тест.
clear	Удаляет результаты тестов. Добавьте --group N (при необходимости с --name REGEX) или ID профилей.
live	Показывает текущую скорость трафика.
traffic [--by profile] [--by app] [--since 24h]	Показывает суммарный трафик по профилям (по умолчанию) или по приложениям. --since принимает и дни, например 7d.
import [--group N] FILE	Импортирует ссылки для обмена, тело подписки или конфигурацию Clash, sing-box, Xray, WireGuard или OpenVPN из файла размером до 900 KiB. - читает стандартный ввод; с --url URL Throne один раз загружает URL. По умолчанию используется группа, которую показывает Throne.
sub add <url> [--name NAME]	Добавляет группу подписки, по умолчанию названную по имени хоста из URL, и обновляет её. --no-auto-update исключает её из автоматических обновлений; с --no-update группа сейчас не загружается.
sub update <id>…, sub update --all	Обновляет группы подписок или все группы, кроме архивных.
group add <name>, group rm <id>	Добавляет группу; удаляет группу вместе с её профилями.
profile rm <id>…, profile rm --group N [--name REGEX]	Удаляет профили.
settings [get] [KEY…]	Показывает настройки, которыми управляет API. См. Настройки.
settings set KEY=VALUE…	Меняет настройки. true, false и числа передаются как есть, всё остальное — как текст.
backup create [-o FILE] [--parts LIST]	Записывает архив .thrbackup, по умолчанию throne-backup-<time>.thrbackup.
backup restore FILE [--parts LIST] [--yes]	Показывает содержимое архива, спрашивает подтверждение, восстанавливает архив и перезапускает Throne. Части по умолчанию: profiles,routes,otp,ip_lists.
rulesets update	Заново загружает удалённые наборы правил запущенного профиля.
geo, geo update [geoip] [geosite] [--only-missing]	Показывает геофайлы Xray; заново загружает их.
restart	Перезапускает Throne.
shutdown [--yes]	Завершает работу Throne после подтверждения.
keygen [-o FILE]	Создаёт новый ключ: выводит его или записывает в новый файл, который можете читать только вы. К Throne не подключается.
call <METHOD> <PATH> [key=value…] [--body JSON]	Отправляет любой запрос из спецификации API и выводит ответ.
completion bash, zsh, fish или powershell	Выводит скрипт автодополнения для оболочки.
version	Выводит версию thronectl.

Полезно знать:

• --name — регулярное выражение, которое не учитывает регистр и может совпадать с любой частью имени. Заключайте его в кавычки в оболочке, например --name 'DE|NL'.
• --parts принимает список через запятую из значений profiles, routes, settings, otp, ip_lists и icons.
• Команды, которые запускают или останавливают профиль, ждут результата, но не дольше --timeout. Если Throne нужно больше времени, thronectl показывает текущее состояние, например connecting, а Throne завершает действие сам. Импорт, обновление, удаление и загрузка ждут так же. С --no-wait команда завершается сразу.
• Тесты и загрузка геофайлов могут занимать минуты, поэтому задавайте для них больший --timeout, например --timeout 15m. Тест, который длится дольше, продолжает выполняться в Throne; следите за ним с помощью thronectl job <id>.
• Throne выполняет только один тест за раз, независимо от того, запущен он из окна или через API.
• thronectl завершается с кодом 0 при успехе; 1 — при ошибке от Throne (выводится как error: <code>: <message>), при неудачном обновлении подписки, набора правил или геофайлов или при отрицательном ответе на вопрос; 2 — при неверной команде или флаге; 3 — если не удаётся подключиться, ключ отклонён или файл нельзя прочитать.

Настройки

thronectl settings показывает настройки, которые может менять API, а thronectl settings set меняет их, например thronectl settings set log_level=debug kill_switch=true. Throne сначала проверяет каждое значение и ничего не меняет, если хотя бы одно из них неверно.

Область	Настройки
Запуск	remember_enable
Логи	log_level, xray_log_level
Смешанный входящий порт (mixed)	inbound_enabled, inbound_address, inbound_port
Тесты	test_url, test_concurrency, test_timeout_ms
Автоматические обновления	sub_auto_update, sub_respect_server_interval, route_auto_update (в минутах, 0 — выключено)
Kill switch	kill_switch
TUN	tun_strict_route, tun_auto_redirect (Linux), tun_mtu, tun_ipv6, tun_ipv4_cidr, tun_ipv6_cidr
Порты и API	dns_in_port, clash_api_port, clash_listen_addr, singbox_api_port
DNS и время	remote_dns, direct_dns, ntp_enabled, ntp_server, ntp_interval

Большинство изменений логов, входящего подключения, портов, DNS и NTP вступают в силу при следующем запуске профиля. Настройкам TUN этот перезапуск нужен, только пока профиль работает в режиме TUN; иначе они применяются при следующем включении режима TUN. Пока перезапуск нужен, thronectl status сообщает об этом; thronectl connect last --restart применяет изменения. Допустимые значения указаны в таблице настроек спецификации.

Административные запросы

Эти команды отправляют административные запросы: import, sub add, group add, group rm, profile rm, settings set, backup, restart и shutdown. Остальные команды, включая sub update, rulesets update и geo update, отправляют запросы управления. Ключ для обоих видов запросов один и тот же.

• Throne отвечает на административные запросы только со своего компьютера, то есть с 127.0.0.1 или ::1.
• С другого устройства они завершаются ошибкой forbidden, если не включён параметр Разрешить управление из локальной сети (Allow management from the local network). Для headless Throne вместо этого нужен параметр --api-admin-lan.
• Архивы резервных копий содержат пароли и ключи ваших профилей и секреты OTP в открытом виде. thronectl создаёт их так, что читать их можете только вы. Не меняйте это и удаляйте архивы, когда они больше не нужны.
• backup restore отклоняет архив, профили которого запускали бы программы или читали файлы на компьютере, например профили дополнительного ядра (Extra Core) (invalid_archive). Восстановите такой архив в окне Throne.
• backup restore и shutdown спрашивают подтверждение, прежде чем что-либо сделать. В скрипте без терминала добавьте --yes.

При восстановлении settings сохраняются настройки, которые относятся к этому компьютеру: Throne API, входящее подключение и порты, TUN, kill switch, Запомнить последний профиль (Remember last profile), NTP, логирование, системный прокси и пути.

Примеры

Повседневные команды:

thronectl status
thronectl profiles --group 3 --name 'DE|NL'
thronectl connect 12
thronectl tun on
thronectl route 2
thronectl --timeout 2m test latency --group 3
thronectl traffic --by app --since 7d
thronectl sub add 'https://sub.example.com/abc' --name Provider
thronectl --timeout 2m sub update --all
thronectl backup create -o throne.thrbackup

Подключение лучшего профиля

Подключите профиль с наименьшей задержкой в группе, которую показывает Throne. Результаты старше десяти минут проверяются заново:

thronectl connect best --max-age 10m

Подключение самого быстрого профиля

Выполните тест скорости для профилей группы 3, в именах которых есть DE или NL, а затем подключите самый быстрый из них. Для этого нужен jq:

best=$(thronectl --json --timeout 15m test speed --group 3 --name 'DE|NL' |
  jq -r '[.results[] | select(.download_bps > 0)] | max_by(.download_bps) | .id // empty')
[ -n "$best" ] && thronectl connect "$best"

Подключение и отключение одной клавишей

Чтобы подключаться и отключаться одной клавишей Stream Deck, макропада или программы для горячих клавиш, назначьте этой клавише команду:

thronectl toggle

Программы, которые запускают команды по нажатию клавиши, часто не читают настройки вашей оболочки. Задайте THRONE_KEY_FILE (и при необходимости THRONE_ADDR) как переменную окружения своей учётной записи пользователя или добавьте к команде --key-file. В Throne для компьютера также есть глобальные горячие клавиши Start/Stop Profile и Toggle Tun Mode.

PowerShell

Пример с тестом скорости в PowerShell:

$job = thronectl --json --timeout 15m test speed --group 3 --name 'DE|NL' | ConvertFrom-Json
$best = $job.results | Where-Object download_bps -gt 0 | Sort-Object download_bps -Descending | Select-Object -First 1
if ($best) { thronectl connect $best.id }

Автодополнение в оболочке

thronectl completion <shell> выводит скрипт, который дополняет команды, флаги, имена настроек, части резервной копии и другие фиксированные значения в bash, zsh, fish и PowerShell. Если Throne отвечает в течение секунды, скрипт также дополняет ID профилей, групп, профилей маршрутизации и тестов вместе с их именами.

# bash: in ~/.bashrc (on macOS, ~/.bash_profile)
eval "$(thronectl completion bash)"
# zsh: in ~/.zshrc
autoload -Uz compinit && compinit
source <(thronectl completion zsh)
# fish
thronectl completion fish > ~/.config/fish/completions/thronectl.fish

# In $PROFILE
thronectl completion powershell | Out-String | Invoke-Expression

Скрипты спрашивают у thronectl, что дополнять, поэтому остаются правильными после обновления thronectl.

Безопасность

• Тот, у кого есть ключ, управляет подключением, режимами и маршрутизацией Throne и может читать имена, адреса, результаты тестов и трафик ваших профилей. С этого компьютера, а также из локальной сети, если включён параметр Разрешить управление из локальной сети (Allow management from the local network), ключ также позволяет импортировать, удалять, менять настройки и создавать резервные копии, которые содержат ваши учётные данные в открытом виде.
• Не указывайте ключ в командных строках и скриптах, которые могут читать другие. Используйте файл ключа, который можете читать только вы, или THRONE_KEY из менеджера паролей или хранилища секретов.
• Каждое сообщение между thronectl и Throne шифруется и аутентифицируется с помощью ключа, в том числе в локальной сети. Прямой секретности (forward secrecy) нет: тот, кто узнает ключ, сможет прочитать записанный ранее трафик.
• Если ключ утёк, нажмите Regenerate и передайте скриптам новый ключ. Для headless Throne см. Защита от потери доступа и восстановление.
• Оставьте для Listen on значение This computer only, если API не нужен вам в сети. Если API работает в сети, перечислите в Allowed addresses устройства, которым можно подключаться.
• После 5 неудачных попыток подключения за минуту с одного адреса Throne отклоняет этот адрес на 60 секунд. Пока это время не истечёт, блокируются и другие клиенты с тем же адресом, например за тем же роутером. Throne никогда не отклоняет 127.0.0.1 и адрес, с которого клиент успешно вошёл за последние 10 минут.
• Ответы никогда не содержат учётных данных ваших профилей и URL ваших подписок. Исключение — резервные копии.

Библиотека для Go

Репозиторий Throne-api также содержит библиотеку для Go, github.com/throneproj/Throne-api, с методом для каждого запроса, и спецификацию API с описанием протокола обмена, чтобы вы могли написать клиент на другом языке.