===== 3X-UI =====

**3X-UI** — это современная веб-панель управления с открытым исходным кодом, предназначенная для работы с сервером **Xray-core**.  

Она обеспечивает удобный интерфейс для настройки и мониторинга различных VPN- и прокси-протоколов.

----

=== Блок-схема установки и настройки ===

^ Шаг ^ Действие ^ Описание ^
| 🐳 | Установка Docker и Docker Compose | Скачайте и установите Docker через официальный скрипт |
| 📂 | Создание папки **panel** | Подготовьте рабочую директорию |
| 📝 | Настройка **compose.yml** | Вставьте конфигурацию сервиса |
| ▶️ | Запуск контейнера | Выполните `docker compose up -d` |
| 🔑 | Первичный вход (**admin/admin**) | Перейдите по адресу `http://your-ip:2053` |
| ✏️ | Изменение пароля | Настройте *Panel Settings → Authentication* |
| 🔒 | Настройка безопасности | Включите 2FA и задайте альтернативный веб-путь |

----

=== Установка ===

== Docker ==

Перед началом установки Docker рекомендуется установить следующие утилиты через пакетный менеджер:  
  * **curl**  
  * **nano** (по необходимости)  

Установка **Docker** с помощью официального скрипта:
<code bash>
bash <(curl -sSL https://get.docker.com)
</code>

Установка и использование **Docker Compose**:

Создайте папку **panel** и перейдите в неё:
<code bash>
mkdir panel
cd panel
</code>

Создайте и отредактируйте файл **compose.yml** и вставьте в него следующее содержимое:
<code yaml>
services:
  3xui:
    image: ghcr.io/mhsanaei/3x-ui:latest
    container_name: 3xui_app
    # hostname: yourhostname <- опционально
    volumes:
      - $PWD/db/:/etc/x-ui/
      - $PWD/cert/:/root/cert/
      - $PWD/config.json:/app/bin/config.json # хранение конфигурации на хосте
    environment:
      XRAY_VMESS_AEAD_FORCED: "false"
      XUI_ENABLE_FAIL2BAN: "true"
      TZ: "Europe/Moscow"
    tty: true
    network_mode: host
    restart: unless-stopped
</code>

⚠ **Пояснение про `$PWD`**  
`$PWD` — это переменная окружения Linux, которая указывает на текущую рабочую директорию.  
Если запускать `docker compose` от root, `$PWD` может не работать корректно. В таком случае лучше использовать полный путь (например `/root/panel`).  

Запустите контейнер:
<code bash>
docker compose up -d
</code>

После запуска панель будет доступна по адресу:  
**http://your-ip:2053**

Учётные данные для входа:
<code>
admin / admin
</code>

> **Важно!** 
> Сразу после первого входа измените логин и пароль администратора:  
> Panel Settings → Authentication

> **Рекомендуется:**  
> Включить двухфакторную аутентификацию  
> Настроить дополнительный веб-путь панели для повышения безопасности  

----

=== Обновление ===

Для обновления выполните следующие команды:
<code bash>
docker compose down
docker compose pull
docker compose up -d
</code>

----

=== Удаление ===

Для полного удаления выполните:
<code bash>
docker compose down
docker system prune -a
rm -rf panel
</code>

----

=== Полезные советы ===

  * 🗄 **Резервное копирование базы**  
    Директория `db/` содержит настройки и информацию о пользователях. Настоятельно рекомендуется регулярно делать её бэкап.  

  * ⚙ **Хранение `config.json` вне контейнера**  
    Благодаря привязке тома конфигурация сохраняется даже при обновлении или пересоздании контейнера.  

  * 🔐 **Fail2Ban**  
    Опция `XUI_ENABLE_FAIL2BAN: "true"` активирует защиту от подбора пароля. Убедитесь, что у вас установлен Fail2Ban на хосте.  

  * 🌍 **Часовой пояс**  
    Параметр `TZ` позволяет задать корректный часовой пояс (например, `"Europe/Moscow"`).  

  * 🛡 **Безопасность**  
    - Меняйте порт доступа к панели с 2053 на нестандартный.  
    - Используйте HTTPS (можно пробросить сертификаты в папку `cert/`).  
    - Разграничьте доступ к панели через firewall (разрешите только свои IP).  

----

=== Частые ошибки и решения ===

  * ❌ **Панель не запускается на порту 2053**  
    → Возможно, порт занят другим процессом. Проверьте с помощью:
<code>
lsof -i:2053
</code>  
    
    Измените порт в настройках или освободите его.  

  * ❌ **Не работает `$PWD` в volumes**  
    → Используйте полный путь, например:  
<code>
- /root/panel/db/:/etc/x-ui/
</code>  

  * ❌ **Забыли пароль администратора**  
    → Остановите контейнер и удалите файл базы в `db/`. После перезапуска будут восстановлены стандартные учётные данные (**admin/admin**).  

  * ❌ **Ошибка сертификата (HTTPS)**  
    → Убедитесь, что файлы сертификата (`fullchain.pem` и `privkey.pem`) корректно проброшены в папку `cert/` и права доступа позволяют их читать.  

----