Полное руководство по сбросу и изменению пароля в 3x-ui (Docker Edition)

3x‑ui — удобная веб‑панель для управления Xray/V2Ray. Однако при потере пароля или повреждении базы данных доступ к GUI блокируется, а штатный механизм «Reset Username & Password» внутри меню не срабатывает, если ядро панели не инициализировано.

Данное руководство показывает как вернуть доступ без переустановки и без потери текущих конфигураций клиентов, inbounds/outbounds и трафиковых логов. Подойдёт как для домашних серверов, так и для production‑среды с минимальным простоем.

Инфраструктура и исходные данные

Важно: Docker Compose network_mode: host даёт контейнеру доступ напрямую к сетевому стеку хоста. Поэтому последующие правила iptables применяются к самому хосту.

Мини‑чеклист перед началом

SSH‑доступ к серверу с правами sudo или root.

Выключаем панель (чтобы закрыть файл базы):

docker stop 3x-ui

Устанавливаем SQLite CLI (если на хосте нет):

sudo apt install sqlite3 -y

Убеждаемся, что ./db/x-ui.db реально существует и не равен нулю байт.

Горячий бэкап: на случай «чёрного лебедя»

cp ./db/x-ui.db ./db/x-ui.db.$(date +%F-%H%M%S).bak
ls -lh ./db/*.bak

Бэкап обязателен: если что‑то пойдёт не так, всегда можно вернуть базу командой mv.

Анатомия базы x-ui.db

3x‑ui хранит всё в SQLite. Основные таблицы:

• users — учётные записи GUI;

• inbounds / outbound_traffics — конфигурации прокси и логи;

• settings — глобальные параметры (порт, JWT‐секрет, автологин и т. д.);

• client_traffics — счётчики пользователей.

Колонки таблицы users:

Пароль хранится plain‑text — поэтому сервер нужно изолировать.

Изменение логина/пароля без потери данных

sqlite3 ./db/x-ui.db <<SQL

PRAGMA table_info(users);
SELECT id, username FROM users;

UPDATE users
SET username = 'admin',
    password = 'admin'
WHERE id = 1;

SELECT * FROM users;
.quit
SQL

Объяснение:

• login_secret можно обнулить, чтобы сбросить 2FA/JWT.

• Пароль генерируем on‑the‑fly через подстановку Unix‑timestamp — минимизируем вероятность дубликатов.

После правки запускаем панель:

docker start 3x-ui

Проверка доступа и мгновенная смена пароля через GUI

1. Открываем браузер: http://<SERVER_IP>:2053

2. Вводим admin / admin

3. В левом меню → Settings → Admin задаём окончательный сложный пароль (GUI автоматически выполнит перехеш).

Hash‑функция: SHA‑256 + salt, который хранится в login_secret. Поэтому сначала мы обнулили поле, а GUI создаст новое.

Уменьшаем поверхность атаки (hardening)

Автоматизация для DevOps pipeline

Создаём скрипт reset_xui_admin.sh:

#!/usr/bin/env bash
DB_PATH="$(pwd)/db/x-ui.db"
NEWPASS="Admin$(date +%s)"
sqlite3 "$DB_PATH" "UPDATE users SET username='admin', password='${NEWPASS}', login_secret='' WHERE id=1;"
echo "Новый пароль: $NEWPASS"
docker restart 3x-ui

Добавляем в cron для ежемесячного обновления пароля или ставим в GitLab CI как job after_script.

Типовые ошибки и их решения

Заключение

Сброс пароля через SQLite даёт точечное восстановление доступа без даунтайма прокси‑сервисов. Главное правило — делайте бэкап перед изменениями и ограничивайте доступ к панели. С этими рецептами вы сможете за пару минут вернуть контроль над 3x‑ui даже в самых нештатных сценариях.

«Бэкап — это то, что вы делаете до, а не после…» © admin