Справочник API
Полный справочник REST API и gRPC для PasarGuard Node
Обзор API
PasarGuard Node предоставляет интерфейсы REST API и gRPC для управления нодой, пользователями и получения статистики.
Аутентификация
Все запросы к API требуют аутентификации с использованием API_KEY
, настроенного в вашем файле .env
.
REST API:
Authorization: Bearer <api_key>
gRPC:
authorization: Bearer <api_key>
Базовый URL
Запросы REST API должны отправляться на:
https://your-node-address:port/
Тип содержимого
REST API использует Protocol Buffers для сериализации данных:
Content-Type: application/x-protobuf
Структуры данных
Backend
message Backend {
BackendType type; // Тип бэкенда (XRAY = 0)
string config; // Конфигурация бэкенда
repeated User users; // Список пользователей
uint64 keepAlive; // Длительность keep alive в секундах
}
User
message User {
string email; // Уникальный идентификатор email пользователя
Proxy proxies; // Конфигурации прокси
repeated string inbounds; // Список тегов входящих соединений
}
StatRequest
message StatRequest {
string name; // Email пользователя или тег входящего/исходящего соединения
bool reset; // Сбросить статистику трафика после получения
StatType type; // Тип статистики для получения
}
enum StatType {
Outbounds = 0; // Вся статистика исходящих соединений
Outbound = 1; // Статистика одного исходящего соединения
Inbounds = 2; // Вся статистика входящих соединений
Inbound = 3; // Статистика одного входящего соединения
UsersStat = 4; // Статистика всех пользователей
UserStat = 5; // Статистика одного пользователя
}
Методы API
Управление нодой
Запуск Backend
Запустите backend ноды с конфигурацией.
POST /start
Authorization: Bearer <api_key>
Content-Type: application/x-protobuf
Body: Backend (protobuf)
rpc Start(Backend) returns (BaseInfoResponse)
Это единственный метод, который вызывается перед созданием соединения с нодой.
Остановка Backend
Остановите backend и деактивируйте клиентские соединения.
PUT /stop
Authorization: Bearer <api_key>
rpc Stop(Empty) returns (Empty)
Получение базовой информации
Получите базовую информацию о ноде и проверьте статус соединения.
GET /info
Authorization: Bearer <api_key>
rpc GetBaseInfo(Empty) returns (BaseInfoResponse)
Ответ:
message BaseInfoResponse {
string version;
string core_type;
bool running;
}
Логирование
Получение логов
Потоковая передача логов backend в реальном времени.
GET /logs
Authorization: Bearer <api_key>
// Returns Server-Sent Events (SSE) stream
rpc GetLogs(Empty) returns (stream Log)
Структура лога:
message Log {
string detail; // Log message
}
Статистика
Получение системной статистики
Получите статистику на уровне системы.
GET /stats/system
Authorization: Bearer <api_key>
rpc GetSystemStats(Empty) returns (SystemStatsResponse)
Ответ:
message SystemStatsResponse {
uint64 mem_total; // Total memory
uint64 mem_used; // Used memory
uint64 cpu_cores; // CPU cores
double cpu_usage; // CPU usage %
uint64 incoming_bandwidth_speed; // Download speed
uint64 outgoing_bandwidth_speed; // Upload speed
}
Получение статистики Backend
Получите статистику работы backend.
GET /stats/backend
Authorization: Bearer <api_key>
rpc GetBackendStats(Empty) returns (BackendStatsResponse)
Ответ:
message BackendStatsResponse {
uint32 num_goroutine; // Active goroutines
uint32 num_gc; // GC runs
uint64 alloc; // Allocated memory
uint64 total_alloc; // Total allocated
uint64 sys; // System memory
uint64 mallocs; // Malloc count
uint64 frees; // Free count
uint64 live_objects; // Live objects
uint64 pause_total_ns; // Total GC pause
uint32 uptime; // Uptime in seconds
}
Получение статистики трафика
Получите статистику трафика для пользователей, inbound или outbound.
GET /stats
Authorization: Bearer <api_key>
Content-Type: application/x-protobuf
Body: StatRequest (protobuf)
rpc GetStats(StatRequest) returns (StatResponse)
Примеры:
Получить статистику всех пользователей:
StatRequest {
type: UsersStat,
reset: false
}
Получить статистику конкретного пользователя:
StatRequest {
name: "user@example.com",
type: UserStat,
reset: true // Reset after retrieval
}
Ответ:
message StatResponse {
repeated Stat stats;
}
message Stat {
string name; // User email or tag
string type; // Stat type
string link; // Link identifier
int64 value; // Traffic value in bytes
}
Получение онлайн-статистики пользователя
Получите количество активных соединений пользователя.
GET /stats/user/online
Authorization: Bearer <api_key>
Content-Type: application/x-protobuf
Body: StatRequest (protobuf)
rpc GetUserOnlineStats(StatRequest) returns (OnlineStatResponse)
Ответ:
message OnlineStatResponse {
string name; // User email
int64 value; // Online connection count
}
Получение списка IP-адресов онлайн пользователя
Получите список IP-адресов активных соединений пользователя.
GET /stats/user/online_ip
Authorization: Bearer <api_key>
Content-Type: application/x-protobuf
Body: StatRequest (protobuf)
rpc GetUserOnlineIpListStats(StatRequest) returns (StatsOnlineIpListResponse)
Управление пользователями
Синхронизация пользователя
Добавьте, обновите или удалите одного пользователя.
PUT /user/sync
Authorization: Bearer <api_key>
Content-Type: application/x-protobuf
Body: User (protobuf)
rpc SyncUser(stream User) returns (Empty)
Чтобы удалить пользователя, отправьте пустой массив inbounds. gRPC предоставляет потоковый интерфейс, но REST требует отдельных вызовов для каждого пользователя.
Синхронизация пользователей
Замените всех пользователей новым набором.
PUT /users/sync
Authorization: Bearer <api_key>
Content-Type: application/x-protobuf
Body: Users (protobuf)
rpc SyncUsers(Users) returns (Empty)
Этот метод удаляет всех старых пользователей и заменяет их предоставленным списком.
Ответы об ошибках
HTTP коды статуса
Код | Значение |
---|---|
200 | Успешно |
400 | Неверный запрос - недопустимые данные |
401 | Неавторизован - недействительный API_KEY |
404 | Не найдено - endpoint не существует |
500 | Внутренняя ошибка сервера |
Формат ошибки
{
"error": "Error description",
"code": "ERROR_CODE"
}
Ограничение скорости
В настоящее время нет встроенных ограничений скорости, но рекомендуется:
- Группировать обновления пользователей, когда это возможно
- Кешировать статистику локально
- Избегать чрезмерного опроса