mistgate Документация
RU
300

В админке: ИИ

API админки

Connect-RPC API, на котором работает админка, как звать его через curl и сгенерированный клиент, API-токены и их профили и что токену можно, а что нельзя.

На этой странице

Админка общается с панелью через Connect-RPC API. Скрипты пользуются тем же API — с теми же проверками ролей, валидацией и журналом аудита, — только вместо cookie сессии присылают API-токен. ИИ-агенты используют те же токены через MCP-сервер.

Где находится API#

Каждая процедура — POST на адрес админки плюс api/ и путь процедуры:

Текст
<адрес админки>api/mistgate.admin.v1.<Service>/<Method>
https://panel.example.com/<prefix>/api/mistgate.admin.v1.UserService/ListUsers

Адрес админки — тот, что напечатал mistgate setup (владельцу его показывает Настройки → Домены): с секретным префиксом, на секретном хосте или на отдельном адресе. API доступен только там; на публичной стороне тот же путь отдаёт сайт-ширму.

Обработчики — это обработчики connect-go, поэтому работают протоколы Connect (JSON или бинарный protobuf), gRPC и gRPC-Web. Примеры здесь используют Connect с JSON.

Сервисы#

API описан в proto/mistgate/admin/v1/. Сгенерированный код лежит в репозитории: Go в gen/mistgate/admin/v1 (пакеты adminv1 и adminv1connect), TypeScript в web/src/gen.

Сервис Файл Что охватывает
AuthService auth.proto Вход, passkey, пароль, сессии, повторное подтверждение, журнал аудита, настройки капчи
InstanceService instance.proto Оформление, адреса админки и подписок
FleetService fleet.proto Обзор и лента событий
NodeService node.proto Ноды: список, подробности, настройки, команды установки, перезапуски, логи, вывод из флота
ProfileService profile.proto Протоколы, профили и профили на нодах
GroupService group.proto Группы
UserService user.proto Пользователи, их трафик, устройства и ссылка подписки
DeviceService device.proto Устройства AmneziaWG и их ключи
SubscriptionService subscription.proto Настройки подписок и правила для приложений
DnsService dns.proto DNS-пресеты, пресеты, которые нода предлагает на странице пользователя, и выборы людей
HealthService health.proto Алерты, проверки глазами клиента, доктор и его исправления
UpdateService update.proto Пакет релиза, обновления нод, расписания и раскатки, обновления панели
ProvisioningService provisioning.proto Установка нод по SSH и сохранённый SSH-доступ к нодам
WarpService warp.proto Аккаунты WARP нод
AwgService awg.proto Помощники редактора профиля AmneziaWG
BackupService backup.proto Зашифрованные бэкапы панели
TelegramService telegram.proto Telegram-бот и чат каждого админа (только владелец и вошедшие админы; закрыт для токенов API и MCP)
ApiTokenService, ApprovalService integrations.proto API-токены и одобрения владельца
CheburcheckService, BsbordService cheburcheck.proto, bsbord.proto Источники cheburcheck и bsbord проверки из страны: настройки, статус и проверка, а у bsbord ещё список единиц и запрос цены (только владелец; изменение и отключение источника и запрос цены требуют повторного подтверждения; закрыт для токенов API и MCP)

Справочник по каждому полю — комментарии в proto-файлах. Соглашения (common.proto):

  • Идентификаторы — непрозрачные строки с префиксом: nod_…, usr_…, prf_…, grp_…, dev_…, inb_… (профиль на ноде).
  • Время — Unix-секунды в полях с окончанием _unix; 0 — не задано. Счётчики байтов — беззнаковые 64-битные.
  • В JSON имена полей в lowerCamelCase (pageSize), перечисления — по именам (USER_FILTER_ONLINE), 64-битные целые — строками (на входе числа тоже принимаются).
  • Изменения используют optional-поля: отсутствующее поле не меняется.
  • Ошибки — коды Connect с короткими сообщениями: not_found, already_exists, invalid_argument, failed_precondition, aborted (кто-то изменил раньше), permission_denied, unauthenticated, resource_exhausted.

API-токены#

Владелец создаёт токены в ИИ → MCP и токены → Новый токен (нужно свежее повторное подтверждение входа):

Поле Правило
Название От 1 до 64 символов, без повторов среди действующих токенов без учёта регистра. Именно его показывает журнал аудита.
Доступ Профиль: Только чтение, Оператор или Админ.
Срок жизни По умолчанию 90 дней, не больше 365. Токен всегда истекает; чтобы продлить, создайте новый и отзовите старый.
Запросов в минуту По умолчанию 120, от 1 до 600.

Секрет выглядит как tk1_ и 43 символа, безопасных для URL. Его показывают один раз; панель хранит только его SHA-256 и последние четыре символа (чтобы различать токены в списке). Одновременно может быть не больше 50 действующих токенов. Список показывает, когда и откуда каждый токен использовался последний раз и через что (API или MCP).

Отозвать останавливает токен сразу: следующий его запрос отклоняется, а изменения, которые он запланировал через MCP и ещё не применил, отменяются. Отзыв требует повторного подтверждения.

Аутентификация#

Передавайте токен в одном заголовке Authorization со схемой Bearer:

Текст
Authorization: Bearer tk1_...

Запрос с заголовком Bearer оценивается только по токену; cookie не смотрятся. Отказы:

Статус code в ответе Сообщение
401 unauthenticated not signed in (токена нет, он искажён или неизвестен), token revoked, token expired
403 permission_denied this call is not available to API tokens, this token's profile cannot do this, this needs the owner's approval; it is not available over the API, this is used only while the MCP server makes a plan; it is not available over the API
429 resource_exhausted too many requests for this token, slow down, с Retry-After

Вызов API#

Через curl#

Shell
TOKEN=$(head -n1 ~/.config/mistgate/token)
ADMIN=https://panel.example.com/<prefix>/

curl -sS "${ADMIN}api/mistgate.admin.v1.UserService/ListUsers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filter": "USER_FILTER_ONLINE", "pageSize": 20}'

Изменение выглядит так же. Продлить двух пользователей на 30 дней (профиль «Оператор» и выше):

Shell
curl -sS "${ADMIN}api/mistgate.admin.v1.UserService/ExtendUsers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userIds": ["usr_...", "usr_..."], "days": 30}'

Ошибка приходит в JSON с HTTP-статусом ошибки:

JSON
{"code": "permission_denied", "message": "this token's profile cannot do this"}

Через сгенерированный клиент#

Пакеты Go импортируются из модуля github.com/mistgate/mistgate; закрепите тег релиза или коммит, потому что до 1.0 API ещё может меняться. Базовый адрес клиента — адрес админки плюс api:

Go
package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"os"
	"strings"

	"connectrpc.com/connect"

	adminv1 "github.com/mistgate/mistgate/gen/mistgate/admin/v1"
	"github.com/mistgate/mistgate/gen/mistgate/admin/v1/adminv1connect"
)

// bearer adds the API token to every request.
type bearer struct{ token string }

func (b bearer) RoundTrip(r *http.Request) (*http.Response, error) {
	r = r.Clone(r.Context())
	r.Header.Set("Authorization", "Bearer "+b.token)
	return http.DefaultTransport.RoundTrip(r)
}

func main() {
	raw, err := os.ReadFile(os.Getenv("MISTGATE_TOKEN_FILE"))
	if err != nil {
		log.Fatal(err)
	}
	token := strings.TrimSpace(strings.SplitN(string(raw), "\n", 2)[0])
	hc := &http.Client{Transport: bearer{token}}

	// The admin URL that `mistgate setup` printed, plus "api".
	base := "https://panel.example.com/<prefix>/api"
	users := adminv1connect.NewUserServiceClient(hc, base)

	resp, err := users.ListUsers(context.Background(), connect.NewRequest(&adminv1.ListUsersRequest{PageSize: 10}))
	if err != nil {
		log.Fatal(connect.CodeOf(err), err)
	}
	for _, u := range resp.Msg.GetUsers() {
		fmt.Println(u.GetId(), u.GetName(), u.GetStatus())
	}
}

Для другого языка сгенерируйте клиент из proto/ командой buf generate с плагином Connect или gRPC для этого языка.

Telegram-прокси#

Профили MTProto и Telegram-ключ человека используют эти части ProfileService и UserService:

  • ProtocolInfo.experimental (из ProfileService.ListProtocols): true для нового протокола, ещё не проверенного на практике. У MTProto он выставлен.
  • AppToggles.telegram в CreateUser и UpdateUser — переключатель Telegram у человека. Включение создаёт ключ человека, выключение отзывает его. Хотя бы один из happ и amnezia должен остаться включённым.
  • ListUsers принимает фильтр USER_FILTER_TELEGRAM: люди с включённым переключателем Telegram, независимо от ключа и профилей MTProto. Каждый пользователь в списке несёт access_telegram (переключатель включён и для человека пригоден сервер MTProto) и telegram_issued (ключ создан).
  • GetTelegramLinks читает прокси человека: has_key, key_device_id, key_issued_unix и ссылки tg://proxy, по одной на ноду и профиль; ipv6, relay и via отмечают IPv6-двойник ноды и двойник ретрансляции. Ничего не пишет. Ссылка несёт секрет человека, поэтому обращайтесь с ответом как с паролем.
  • IssueTelegramKey создаёт ключ, если его нет (нужны включённый переключатель и человек, который не отключён; лимит устройств не действует), RotateTelegramKey даёт ему новый секрет, и все прежние ссылки перестают работать (not_found «key», если ключа нет), а RevokeTelegramKey отзывает ключ и оставляет переключатель включённым. Каждый отвечает прокси человека, как GetTelegramLinks. Ключ — устройство человека вида DEVICE_KIND_TELEGRAM_KEY, и RevokeDevice тоже его удаляет.

Все четыре вызова — для владельца и помощников и закрыты для API-токенов, как и другие вызовы, возвращающие учётные данные.

Профили токенов#

Профиль работает как роль админа: Только чтение — как «Только чтение», Оператор — как «Помощник», Админ — как «Владелец». Сверх роли токену доступны только процедуры из фиксированного списка разрешений (internal/panel/auth/policy_tokens.go); всё остальное отклоняется при любом профиле. Ни одна процедура из списка не возвращает учётных данных.

Процедура Только чтение Оператор Админ
FleetService.Overview, FleetService.ListEvents да да да
NodeService.ListNodes, NodeService.GetNode да да да
NodeService.CheckPorts нет да да
HealthService.ListAlerts, GetChecks, GetDoctor да да да
UserService.ListUsers, UserService.GetUser да да да
GroupService.ListGroups да да да
ProfileService.ListProfiles, ProfileService.GetProfile (секреты скрыты) да да да
ProfileService.ListProtocols, ProfileService.PreviewProfile да да да
SubscriptionService.GetSubscriptionSettings, ListClients, TestUserAgent да да да
UpdateService.GetUpdates, GetOsUpdates да да да
UserService.CreateUser, UpdateUser, SetUsersEnabled, ExtendUsers, ResetUserTraffic, RevokeDevice нет да да
HealthService.MuteAlert, DismissAlert, RunChecksNow, RunDoctor нет да да
AuthService.ListAudit нет нет да
HealthService.ApplyFix нет нет только через одобренный план MCP
UpdateService.StartRollout, PauseRollout, ResumeRollout, CancelRollout, RollbackNode нет нет только через одобренный план MCP
UpdateService.StartOsRollout, CancelOsRollout нет нет только через одобренный план MCP
UpdateService.RefreshOsUpdates нет нет нет (нажатие владельца в админке)
UpdateService.ScheduleNodeUpdate, CancelNodeUpdateSchedule, SetUpdateTimezone, SetUpdateDownloadTimeout нет нет только через одобренный план MCP
ProvisioningService.ListNodeServerAccess (данные подключения, без пароля) нет нет да
ProvisioningService.GetSSHFingerprint нет нет только пока MCP-сервер составляет план node_install
ProvisioningService.StartNodeProvision, RotateNodeServerPassword нет нет только через одобренный план MCP
SubscriptionService.UpdateSubscriptionSettings (одно приложение на странице пользователя) нет только через одобренный план MCP только через одобренный план MCP
ProfileService.CreateProfile, UpdateProfile, DeleteProfile, CreateInbound, DeleteInbound; GroupService.UpdateGroup нет нет только через одобренный план MCP

Закрыто для любого токена: удаление пользователей, ссылка подписки, ключ и ссылки Telegram-прокси, устройства и их ключи, снятие блокировки с устройства (UserService.UnblockDevice; токен может заблокировать устройство через RevokeDevice с block, но блокировку снимает только админ), подключение нод, их настройки, перезапуски, логи и вывод из флота, подготовка модуля ядра AmneziaWG, шаги установки по SSH из админки (проверка сервера, повтор задания, показ и удаление сохранённого доступа), создание групп, DNS-пресеты и настройки подписок (кроме списка приложений на странице пользователя через одобренный план), WARP, бэкапы, обновления панели и пересмотр пакета, оформление, токены, одобрения, собственный аккаунт админа (passkey, пароль, сессии, повторное подтверждение) и настройки капчи.

Изменения, которым нужен владелец#

Токен никогда не проходит повторное подтверждение. Процедуры, которым оно нужно или которые меняют то, что работает на нодах, напрямую токену недоступны; через обычный API они отвечают 403 «this needs the owner's approval; it is not available over the API».

Добраться до них можно только через MCP-сервер с токеном профиля «Админ» (до списка приложений на странице пользователя — начиная с профиля «Оператор»): агент планирует изменение, владелец читает план в ИИ → Ждут вас и одобряет его (со своим повторным подтверждением), после чего применение выполняет одобренный план. Одобрение проверяется в базе при каждом вызове, а разрешение охватывает только процедуры, перечисленные в этом плане. План истекает через 10 минут после создания.

Ограничения#

  • Запросов в минуту на токен: сколько задано у токена (от 1 до 600, по умолчанию 120), подряд — до 30. Сверх лимита — 429 с Retry-After.
  • Изменений пользователей на токен: за час, считая от первого такого изменения, токен может отнять доступ или переписать не больше 10 человек: отключить, сбросить трафик, отозвать или заблокировать устройство, изменить человека, перенести людей группы или изменить группу так, что меняется выдача её людям. Считается каждый человек в каждом вызове; вызов, который ничего не меняет, бесплатен, а создание, продление и включение людей не считаются. Вызов сверх лимита отклоняется целиком: 429 с кодом token_user_change_limit и полями limit, used, asked и retry_after_seconds (если один вызов просит больше всего лимита, оно равно 0, а в сообщении есть ещё reason=over_hourly_limit: разбейте вызов или обратитесь к владельцу). Владелец может снять лимит с одного токена в ИИ → MCP и токены (Лимит в строке токена или переключатель при создании); нужно свежее подтверждение входа. Через MCP план сверх лимита не отклоняется, а ждёт одобрения владельца. После обновления существующие токены ограничены.
  • На сеть клиента на стороне админки: 30 запросов в секунду, подряд до 200 — одинаково для cookie и токенов.
  • Размер запроса: от 64 КиБ до 1 МиБ в зависимости от сервиса.
  • Срок жизни: каждый токен истекает (не позже чем через 365 дней).

Аудит#

Каждый вызов токеном пишет строку в журнал аудита: «вызвал(а) <процедура>», HTTP-статус, адрес клиента и автор «API-токен <имя>» (или «токен MCP <имя>» через MCP). Удачные чтения пишутся не чаще раза в минуту на процедуру; изменения и отказы — всегда. Строки самой процедуры (например, «создал(а) пользователя …») пишутся так же, как для админа.

Чего никогда нет в ответах#

  • CreateUser, вызванный токеном, возвращает пользователя без ссылки подписки и пароля страницы. GetSubscriptionLink для токенов закрыт.
  • Секреты профилей приходят скрытыми (••••) для любого вызывающего.
  • Ключи и конфигурации устройств (DeviceService) и аккаунты WARP для токенов закрыты.
  • ID устройства (HWID) никогда не хранится и не возвращается: Device.fingerprint — первые шесть символов его хеша, чтобы отличить два одинаковых телефона.
  • Секрет токена после создания не возвращается никогда, даже владельцу.
  • В параметрах аудита нет секретов.

Править страницу на GitHub