НейроАгент

Как получить данные пользователей через API 3x-ui

Полное руководство по получению данных пользователей через API 3x-ui, включая IP-адреса клиентов. Решение проблем с эндпоинтами и настройка панели.

Как получить данные пользователей через API 3x-ui?

Здравствуйте! У меня несколько серверов с панелью 3x-ui, и я пытаюсь автоматизировать некоторые процессы. При попытке получить список IP-адресов клиента через API:

python
session.post(f"{panel_url}/panel/api/inbounds/clientIps/{client_email}", verify=False)

Я получаю ответ: {'success': True, 'msg': '', 'obj': 'No IP Record'}.

Однако в логах сервера я вижу множество записей с IP-адресами этого клиента:

grep "email: 011igg6e" /usr/local/x-ui/access.log

Вывод:

2025/11/01 06:22:48.053123 from **ip**:57758 accepted tcp:8.8.4.4:443 [inbound-443 >> direct] email: 011igg6e
2025/11/01 06:22:48.144394 from **ip**:57757 accepted udp:192.168.0.119:22000 [inbound-443 -> blocked] email: 011igg6e

При этом другие API-запросы, такие как получение списка инбаундов, работают успешно. Также я получаю пустые ответы при попытке запросить системные логи или логи подключений.

Моя конфигурация панели:

json
"log": {
    "access": "./access.log",
    "dnsLog": false,
    "error": "./error.log",
    "loglevel": "warning",
    "maskAddress": ""
  },
  "api": {
    "tag": "api",
    "services": [
      "HandlerService",
      "LoggerService",
      "StatsService"
    ]
  },

Возможно, у меня неправильные настройки панели? Я работал с API, основываясь на этом руководстве: https://www.postman.com/hsanaei/3x-ui/documentation

НейроАгент

Здравствуйте! Для получения данных пользователей через API 3x-ui, включая IP-адреса клиентов, вам нужно использовать правильные эндпоинты и убедиться, что ваша конфигурация панели настроена корректно. Основная проблема, с которой вы столкнулись, заключается в том, что эндпоинт /panel/api/inbounds/clientIps/{client_email} не существует или не возвращает данные из-за неправильной конфигурации логирования или API сервисов.


Содержание


Основные эндпоинты API 3x-ui

3x-ui предоставляет RESTful API для управления сервером. Основные эндпоинты, которые вам понадобятся:

  • Аутентификация: /panel/api/login - получение токена сессии
  • Инбаунды: /panel/api/inbounds - список всех инбаундов
  • Клиенты: /panel/api/inbounds/clients - список клиентов
  • IP-адреса клиентов: /panel/api/inbounds/clientIps/{clientId} - получение IP-адресов клиента

Важно отметить, что эндпоинт для получения IP-адресов клиентов требует clientId, а не client_email. Согласно документации, clientId является уникальным идентификатором каждого клиента.


Как получить IP-адреса клиентов

Для получения IP-адресов клиента через API выполните следующие шаги:

1. Получите список клиентов

Сначала получите список всех клиентов, чтобы найти нужный по email:

python
import requests

# Получение списка клиентов
response = session.get(f"{panel_url}/panel/api/inbounds/clients")
if response.json()['success']:
    clients = response.json()['obj']
    # Найдите клиента по email
    target_client = next((c for c in clients if c.get('email') == '011igg6e'), None)
    if target_client:
        client_id = target_client['id']

2. Получите IP-адреса клиента

Используйте полученный clientId для запроса IP-адресов:

python
# Получение IP-адресов клиента
response = session.get(f"{panel_url}/panel/api/inbounds/clientIps/{client_id}")
if response.json()['success']:
    ip_addresses = response.json()['obj']
    print(f"IP-адреса клиента: {ip_addresses}")

3. Альтернативный метод через access.log

Если API не возвращает данные, как в вашем случае, можно напрямую читать логи доступа:

python
import re
from datetime import datetime, timedelta

def get_client_ips_from_log(email, log_path="/usr/local/x-ui/access.log", hours=24):
    """Получение IP-адресов клиента из логов доступа"""
    since_time = (datetime.now() - timedelta(hours=hours)).strftime("%Y/%m/%d %H:%M:%S.%f")[:-3]
    
    pattern = rf"{email}$"
    ips = set()
    
    try:
        with open(log_path, 'r') as f:
            for line in f:
                if email in line and line.split()[0] >= since_time:
                    # Извлечение IP-адреса из лога
                    ip_match = re.search(r'from (\d+\.\d+\.\d+\.\d+):', line)
                    if ip_match:
                        ips.add(ip_match.group(1))
    except FileNotFoundError:
        print(f"Лог файл не найден: {log_path}")
    
    return list(ips)

Настройка конфигурации панели

Ваша текущая конфигурация API может не включать необходимые сервисы для работы с логами. В разделе "api" убедитесь, что включен LoggerService:

json
{
  "log": {
    "access": "./access.log",
    "dnsLog": false,
    "error": "./error.log",
    "loglevel": "warning",
    "maskAddress": ""
  },
  "api": {
    "tag": "api",
    "services": [
      "HandlerService",
      "LoggerService",
      "StatsService"
    ]
  }
}

Важно, что LoggerService должен быть включен для доступа к логам через API. Как указано в документации, без этого сервиса эндпоинты, связанные с логами, могут не работать.


Аутентификация в API

Перед выполнением API-запросов необходимо пройти аутентификацию:

python
import requests

url = "https://your-panel-ip:port"
username = "your_username"
password = "your_password"

# Получение токена сессии
login_response = requests.post(
    f"{url}/panel/api/login",
    json={"username": username, "password": password},
    verify=False
)

if login_response.json()['success']:
    token = login_response.json()['obj']
    # Установка заголовка для последующих запросов
    headers = {"Authorization": f"Bearer {token}"}
    session = requests.Session()
    session.headers.update(headers)

Альтернативные методы получения данных

1. Использование библиотеки 3x-ui-js

Существует JavaScript библиотека для работы с 3x-ui API. Согласно репозиторию, она предоставляет метод getClientIps(clientId):

javascript
// Пример использования библиотеки
const { Xui } = require('3x-ui-js');

const xui = new Xui('panel-host', 443, '/panel', false);
await xui.login('username', 'password');

const clientIps = await xui.getClientIps('clientId');
console.log('Client IP addresses:', clientIps);

2. Прямой доступ к базе данных

Если API не работает, можно напрямую обращаться к базе данных SQLite:

python
import sqlite3
import json

def get_client_ips_from_db(db_path="/usr/local/x-ui/db/x-ui.db", client_email="011igg6e"):
    """Получение IP-адресов из базы данных"""
    conn = sqlite3.connect(db_path)
    cursor = conn.cursor()
    
    # Получение клиента по email
    cursor.execute("SELECT id FROM clients WHERE email = ?", (client_email,))
    client = cursor.fetchone()
    
    if not client:
        return []
    
    client_id = client[0]
    
    # Получение IP-адресов (если таблица существует)
    try:
        cursor.execute("SELECT ip FROM client_ips WHERE client_id = ?", (client_id,))
        ips = [row[0] for row in cursor.fetchall()]
    except sqlite3.OperationalError:
        print("Таблица client_ips не существует")
        ips = []
    
    conn.close()
    return ips

Отладка и решение проблем

1. Проверка эндпоинтов

Убедитесь, что эндпоинты доступны и возвращают правильные данные:

python
# Проверка доступности эндпоинта
response = session.get(f"{panel_url}/panel/api/inbounds/clientIps/test")
print(response.json())  # Должен вернуть ошибку, а не 'No IP Record'

2. Проверка прав доступа

Убедитесь, что пользователь, от имени которого вы делаете запрос, имеет необходимые права. Согласно документации, API требует аутентификации и соответствующих разрешений.

3. Проверка формата данных

Убедитесь, что clientId имеет правильный формат. Обычно это числовой идентификатор:

python
# Проверка списка клиентов для получения правильного формата clientId
response = session.get(f"{panel_url}/panel/api/inbounds/clients")
clients = response.json()['obj']
for client in clients:
    print(f"Email: {client.get('email')}, ID: {client.get('id')}")

Примеры кода на Python

Полный пример для получения IP-адресов клиента

python
import requests
import re
from datetime import datetime, timedelta

class XUIClient:
    def __init__(self, panel_url, username, password):
        self.panel_url = panel_url
        self.username = username
        self.password = password
        self.token = None
        self.session = requests.Session()
        self.session.verify = False
        
    def login(self):
        """Вход в панель и получение токена"""
        response = self.session.post(
            f"{self.panel_url}/panel/api/login",
            json={"username": self.username, "password": self.password}
        )
        
        if response.json()['success']:
            self.token = response.json()['obj']
            self.session.headers.update({"Authorization": f"Bearer {self.token}"})
            return True
        return False
    
    def get_client_by_email(self, email):
        """Получение клиента по email"""
        response = self.session.get(f"{self.panel_url}/panel/api/inbounds/clients")
        
        if response.json()['success']:
            clients = response.json()['obj']
            return next((c for c in clients if c.get('email') == email), None)
        return None
    
    def get_client_ips_api(self, client_id):
        """Получение IP-адресов через API"""
        response = self.session.get(f"{self.panel_url}/panel/api/inbounds/clientIps/{client_id}")
        
        if response.json()['success']:
            return response.json()['obj']
        return []
    
    def get_client_ips_from_log(self, email, hours=24):
        """Получение IP-адресов из логов"""
        since_time = (datetime.now() - timedelta(hours=hours)).strftime("%Y/%m/%d %H:%M:%S")[:-3]
        log_path = "/usr/local/x-ui/access.log"
        
        pattern = rf"email: {email}$"
        ips = set()
        
        try:
            with open(log_path, 'r') as f:
                for line in f:
                    if email in line and line.split()[0] >= since_time:
                        ip_match = re.search(r'from (\d+\.\d+\.\d+\.\d+):', line)
                        if ip_match:
                            ips.add(ip_match.group(1))
        except FileNotFoundError:
            print(f"Лог файл не найден: {log_path}")
        
        return list(ips)
    
    def get_client_ips(self, email, use_api_first=True):
        """Основной метод получения IP-адресов клиента"""
        # Получение клиента по email
        client = self.get_client_by_email(email)
        if not client:
            return []
        
        # Попытка через API
        if use_api_first:
            ips = self.get_client_ips_api(client['id'])
            if ips and ips != 'No IP Record':
                return ips
        
        # Если не получилось через API, читаем логи
        return self.get_client_ips_from_log(email)

# Использование
client = XUIClient("https://your-panel:443", "username", "password")
if client.login():
    ips = client.get_client_ips("011igg6e")
    print(f"Найденные IP-адреса: {ips}")

Заключение

Для получения данных пользователей через API 3x-ui необходимо:

  1. Использовать правильные эндпоинты API, включая /panel/api/inbounds/clientIps/{clientId}
  2. Убедиться, что в конфигурации панели включен LoggerService
  3. Правильно обрабатывать аутентификацию через токен сессии
  4. При проблемах с API использовать альтернативные методы: чтение логов напрямую или обращение к базе данных

Основные проблемы, с которыми вы столкнулись, связаны с неправильным эндпоинтом (email вместо clientId) и возможной неправильной конфигурацией API сервисов. Рекомендуется проверить текущую версию 3x-ui и убедиться, что вы используете актуальную документацию API.

Источники

  1. 3X-UI Configuration Documentation - GitHub Wiki
  2. 3X-UI API Documentation - Postman Network
  3. 3X-UI JS Client Library - GitHub
  4. 3X-UI Client Management - DeepWiki
  5. 3X-UI Inbound Management - DeepWiki
  6. 3X-UI Installation Guide - SpaceCore Wiki