Как получить данные пользователей через API 3x-ui?
Здравствуйте! У меня несколько серверов с панелью 3x-ui, и я пытаюсь автоматизировать некоторые процессы. При попытке получить список IP-адресов клиента через API:
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-запросы, такие как получение списка инбаундов, работают успешно. Также я получаю пустые ответы при попытке запросить системные логи или логи подключений.
Моя конфигурация панели:
"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
- Как получить IP-адреса клиентов
- Настройка конфигурации панели
- Аутентификация в API
- Альтернативные методы получения данных
- Отладка и решение проблем
- Примеры кода на Python
- Заключение
Основные эндпоинты 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:
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-адресов:
# Получение 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 не возвращает данные, как в вашем случае, можно напрямую читать логи доступа:
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:
{
"log": {
"access": "./access.log",
"dnsLog": false,
"error": "./error.log",
"loglevel": "warning",
"maskAddress": ""
},
"api": {
"tag": "api",
"services": [
"HandlerService",
"LoggerService",
"StatsService"
]
}
}
Важно, что LoggerService должен быть включен для доступа к логам через API. Как указано в документации, без этого сервиса эндпоинты, связанные с логами, могут не работать.
Аутентификация в API
Перед выполнением API-запросов необходимо пройти аутентификацию:
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):
// Пример использования библиотеки
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:
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. Проверка эндпоинтов
Убедитесь, что эндпоинты доступны и возвращают правильные данные:
# Проверка доступности эндпоинта
response = session.get(f"{panel_url}/panel/api/inbounds/clientIps/test")
print(response.json()) # Должен вернуть ошибку, а не 'No IP Record'
2. Проверка прав доступа
Убедитесь, что пользователь, от имени которого вы делаете запрос, имеет необходимые права. Согласно документации, API требует аутентификации и соответствующих разрешений.
3. Проверка формата данных
Убедитесь, что clientId имеет правильный формат. Обычно это числовой идентификатор:
# Проверка списка клиентов для получения правильного формата 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-адресов клиента
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 необходимо:
- Использовать правильные эндпоинты API, включая
/panel/api/inbounds/clientIps/{clientId} - Убедиться, что в конфигурации панели включен
LoggerService - Правильно обрабатывать аутентификацию через токен сессии
- При проблемах с API использовать альтернативные методы: чтение логов напрямую или обращение к базе данных
Основные проблемы, с которыми вы столкнулись, связаны с неправильным эндпоинтом (email вместо clientId) и возможной неправильной конфигурацией API сервисов. Рекомендуется проверить текущую версию 3x-ui и убедиться, что вы используете актуальную документацию API.