PasarGuard
Нод

Официальные библиотеки

Официальные библиотеки Go и Python для интеграции с PasarGuard Node

PasarGuard предоставляет официальные библиотеки для упрощения интеграции с Node. Эти библиотеки обрабатывают аутентификацию, сериализацию и предоставляют типобезопасные интерфейсы для всех операций API.

Библиотека Go

node-bridge

Официальная библиотека Go для бесшовной интеграции с PasarGuard Node.

Репозиторий: PasarGuard/node_bridge

Установка

go get github.com/PasarGuard/node_bridge

Быстрый старт

package main

import (
    "context"
    "log"

    bridge "github.com/PasarGuard/node_bridge"
)

Примеры

Запуск бэкенда

package main

import (
    "context"
    "log"
    
    "github.com/PasarGuard/node_bridge"
    pb "github.com/PasarGuard/node_bridge/proto"
)

func main() {
    client, _ := nodebridge.NewClient("https://node:443", "session-id")
    defer client.Close()

    backend := &pb.Backend{
        Type: pb.BackendType_XRAY,
        Config: `{
            "log": {"loglevel": "warning"},
            "inbounds": [...],
            "outbounds": [...]
        }`,
        Users: []*pb.User{
            {
                Email: "user1@example.com",
                Proxies: &pb.Proxy{
                    Vmess: &pb.Vmess{
                        Id: "uuid-here",
                    },
                },
                Inbounds: []string{"inbound-tag"},
            },
        },
        KeepAlive: 60,
    }

    info, err := client.Start(context.Background(), backend)
    if err != nil {
        log.Fatal(err)
    }
    
    log.Printf("Бэкенд запущен: %v", info)
}

Синхронизация пользователей

// Синхронизировать одного пользователя
user := &pb.User{
    Email: "newuser@example.com",
    Proxies: &pb.Proxy{
        Vmess: &pb.Vmess{Id: "uuid"},
    },
    Inbounds: []string{"inbound-tag"},
}

err := client.SyncUser(context.Background(), user)
if err != nil {
    log.Fatal(err)
}

// Удалить пользователя (пустые входящие)
user.Inbounds = []string{}
err = client.SyncUser(context.Background(), user)

Получение статистики

// Получить статистику всех пользователей
statsReq := &pb.StatRequest{
    Type: pb.StatType_UsersStat,
    Reset: false,
}

stats, err := client.GetStats(context.Background(), statsReq)
if err != nil {
    log.Fatal(err)
}

for _, stat := range stats.Stats {
    log.Printf("Пользователь: %s, Трафик: %d байт", stat.Name, stat.Value)
}

// Получить статистику конкретного пользователя и сбросить
userStatsReq := &pb.StatRequest{
    Name: "user@example.com",
    Type: pb.StatType_UserStat,
    Reset: true,
}

userStats, err := client.GetStats(context.Background(), userStatsReq)

Потоковая передача логов

ctx := context.Background()
logStream, err := client.GetLogs(ctx)
if err != nil {
    log.Fatal(err)
}

for {
    logMsg, err := logStream.Recv()
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Лог бэкенда: %s", logMsg.Detail)
}

Получение системной статистики

sysStats, err := client.GetSystemStats(context.Background())
if err != nil {
    log.Fatal(err)
}

log.Printf("Использование CPU: %.2f%%", sysStats.CpuUsage)
log.Printf("Память: %d/%d MB",
    sysStats.MemUsed/1024/1024,
    sysStats.MemTotal/1024/1024)

Расширенное использование

Использование gRPC

client, err := nodebridge.NewGRPCClient(
    "node:50051",
    "session-id",
    grpc.WithTransportCredentials(...),
)

Контекст с таймаутом

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

info, err := client.GetBaseInfo(ctx)

Обработка ошибок

import "google.golang.org/grpc/codes"
import "google.golang.org/grpc/status"

info, err := client.GetBaseInfo(ctx)
if err != nil {
    st, ok := status.FromError(err)
    if ok {
        switch st.Code() {
        case codes.Unauthenticated:
            log.Println("Неверный session ID")
        case codes.Unavailable:
            log.Println("Нода недоступна")
        default:
            log.Printf("Ошибка: %v", st.Message())
        }
    }
}

Библиотека Python

node-bridge-py

Официальная библиотека Python для интеграции с PasarGuard Node.

Репозиторий: PasarGuard/node-bridge-py

Установка

pip install pasarguard-node-bridge

Быстрый старт

from pasarguard_node_bridge import NodeClient

# Создать клиент
client = NodeClient(
    url="https://your-node:443",
    session_id="your-session-id"
)

# Получить информацию о ноде
info = client.get_base_info()
print(f"Версия нода: {info.version}, Запущен: {info.running}")

Примеры

Запуск бэкенда

from pasarguard_node_bridge import NodeClient, Backend, User, Proxy, Vmess

client = NodeClient("https://node:443", "session-id")

backend = Backend(
    type=Backend.Type.XRAY,
    config="""{
        "log": {"loglevel": "warning"},
        "inbounds": [...],
        "outbounds": [...]
    }""",
    users=[
        User(
            email="user1@example.com",
            proxies=Proxy(
                vmess=Vmess(id="uuid-here")
            ),
            inbounds=["inbound-tag"]
        )
    ],
    keep_alive=60
)

info = client.start(backend)
print(f"Бэкенд запущен: {info}")

Синхронизация пользователей

from pasarguard_node_bridge import User, Proxy, Vmess

# Добавить/обновить пользователя
user = User(
    email="newuser@example.com",
    proxies=Proxy(
        vmess=Vmess(id="uuid")
    ),
    inbounds=["inbound-tag"]
)

client.sync_user(user)

# Удалить пользователя (пустые входящие)
user.inbounds = []
client.sync_user(user)

Получение статистики

from pasarguard_node_bridge import StatRequest, StatType

# Получить статистику всех пользователей
stats_req = StatRequest(
    type=StatType.USERS_STAT,
    reset=False
)

stats = client.get_stats(stats_req)
for stat in stats.stats:
    print(f"Пользователь: {stat.name}, Трафик: {stat.value} байт")

# Получить статистику конкретного пользователя
user_stats_req = StatRequest(
    name="user@example.com",
    type=StatType.USER_STAT,
    reset=True
)

user_stats = client.get_stats(user_stats_req)

Потоковая передача логов

# Потоковая передача логов в реальном времени
for log in client.get_logs():
    print(f"Лог бэкенда: {log.detail}")

Получение системной статистики

sys_stats = client.get_system_stats()

print(f"Использование CPU: {sys_stats.cpu_usage:.2f}%")
print(f"Память: {sys_stats.mem_used/1024/1024}/{sys_stats.mem_total/1024/1024} MB")
print(f"Загрузка: {sys_stats.incoming_bandwidth_speed/1024/1024:.2f} MB/s")
print(f"Выгрузка: {sys_stats.outgoing_bandwidth_speed/1024/1024:.2f} MB/s")

Получение онлайн пользователей

online_req = StatRequest(
    name="user@example.com",
    type=StatType.USER_STAT
)

online_stats = client.get_user_online_stats(online_req)
print(f"У пользователя {online_stats.value} активных подключений")

# Получить список IP
ip_list = client.get_user_online_ip_list(online_req)
for ip, count in ip_list.value.items():
    print(f"IP: {ip}, Подключений: {count}")

Расширенное использование

Поддержка асинхронности

from pasarguard_node_bridge import AsyncNodeClient

async def main():
    client = AsyncNodeClient("https://node:443", "session-id")

    info = await client.get_base_info()
    print(info)

    await client.close()

# Запуск с asyncio
import asyncio
asyncio.run(main())

Обработка ошибок

from pasarguard_node_bridge import NodeError, AuthenticationError

try:
    info = client.get_base_info()
except AuthenticationError:
    print("Неверный session ID")
except NodeError as e:
    print(f"Ошибка ноды: {e}")
except Exception as e:
    print(f"Неожиданная ошибка: {e}")

Использование gRPC

client = NodeClient(
    url="node:50051",
    session_id="session-id",
    use_grpc=True
)

Лучшие практики

Управление соединением

Go:

// Всегда закрывайте клиенты
defer client.Close()

Python:

# Используйте context manager
with NodeClient(url, session_id) as client:
    # Используйте клиент
    pass

# Или закрывайте вручную
client.close()

Обработка ошибок

Всегда обрабатывайте ошибки должным образом:

  • Ошибки аутентификации → Проверьте SESSION_ID
  • Ошибки подключения → Убедитесь, что нод запущен
  • Ошибки тайм-аута → Увеличьте тайм-аут контекста

Советы по производительности

  1. Переиспользуйте клиенты - Не создавайте новые клиенты для каждого запроса
  2. Пакетные операции - Используйте SyncUsers для обновления нескольких пользователей
  3. Кэшируйте статистику - Не опрашивайте статистику слишком часто
  4. Используйте потоковую передачу - Для логов используйте потоковую передачу вместо опросов

Примеры и руководства

Ознакомьтесь с полными примерами в репозиториях библиотек:

Справочник API

Полный справочник REST API и gRPC для PasarGuard Node

Руководство по миграции

Коллекция руководств по миграции.

On this page

Библиотека Gonode-bridgeУстановкаБыстрый стартПримерыЗапуск бэкендаСинхронизация пользователейПолучение статистикиПотоковая передача логовПолучение системной статистикиРасширенное использованиеИспользование gRPCКонтекст с таймаутомОбработка ошибокБиблиотека Pythonnode-bridge-pyУстановкаБыстрый стартПримерыЗапуск бэкендаСинхронизация пользователейПолучение статистикиПотоковая передача логовПолучение системной статистикиПолучение онлайн пользователейРасширенное использованиеПоддержка асинхронностиОбработка ошибокИспользование gRPCЛучшие практикиУправление соединениемОбработка ошибокСоветы по производительностиПримеры и руководства