# 🚀 Полное руководство по 3x-ui: Установка, Настройка и Решение проблем

Это исчерпывающее руководство по панели **3x-ui** (продвинутая версия Xray-ui от MHSanaei), составленное на основе официальной вики проекта.

---

## 📂 Содержание
1. [[#1. Установка|Установка (One-line, Docker, Manual)]]
2. [[#2. Начальная настройка|Начальная настройка и Безопасность]]
3. [[#3. Управление через CLI|Управление через терминал (CLI)]]
4. [[#4. Конфигурация и SSL|Конфигурация, SSL и Fail2Ban]]
5. [[#5. Reverse Proxy (Nginx, Caddy)|Reverse Proxy (Nginx, Caddy)]]
6. [[#6. API и Переменные окружения|API и Переменные окружения]]
7. [[#7. Продвинутые функции (Telegram, WARP, TOR)|Продвинутые функции (Telegram, WARP, TOR)]]
8. [[#8. Решение проблем и FAQ|Решение проблем и FAQ]]

---

## 1. Установка

### 🛠 Установка одной командой (Рекомендуется)
Самый быстрый способ установки на чистый сервер (Ubuntu, Debian, CentOS).

1. Обновите систему и установите `curl`:
```bash
apt update && apt upgrade -y && apt install curl -y
```
2. Выполните команду установки:
```bash
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
```

или

```bash
curl -Ls https://raw.githubusercontent.com/MHSanaei/3x-ui/master/install.sh -o install.sh
chmod +x install.sh
sudo bash install.sh
rm install.sh
```

3. В процессе скрипт предложит настроить порт, логин и пароль.

### 🐳 Установка через Docker

#### Использование Docker Compose
1. Создайте файл `compose.yml`:
```yaml
services:
  3xui:
    image: ghcr.io/mhsanaei/3x-ui:latest
    container_name: 3xui_app
    volumes:
      - $PWD/db/:/etc/x-ui/
      - $PWD/cert/:/root/cert/
    environment:
      XRAY_VMESS_AEAD_FORCED: "false"
      XUI_ENABLE_FAIL2BAN: "true"
    tty: true
    network_mode: host
    restart: unless-stopped
```

```sh
docker run -d \
  --name 3xui_app \
  --network host \
  -v "$PWD/db/:/etc/x-ui/" \
  -v "$PWD/cert/:/root/cert/" \
  -e XRAY_VMESS_AEAD_FORCED="false" \
  -e XUI_ENABLE_FAIL2BAN="true" \
  --restart unless-stopped \
  ghcr.io/mhsanaei/3x-ui:latest
```

2. Запустите: `docker compose up -d`

### 🏗 Ручная установка (Manual)
Для специфических систем или ручного контроля:
```bash
# Определение архитектуры
ARCH=$(uname -m)
case "${ARCH}" in
  x86_64 | x64 | amd64) XUI_ARCH="amd64" ;;
  arm64 | aarch64) XUI_ARCH="arm64" ;;
  *) XUI_ARCH="amd64" ;;
esac

# Скачивание и установка
wget https://github.com/MHSanaei/3x-ui/releases/latest/download/x-ui-linux-${XUI_ARCH}.tar.gz
tar zxvf x-ui-linux-${XUI_ARCH}.tar.gz
chmod +x x-ui/x-ui x-ui/bin/xray-linux-* x-ui/x-ui.sh
cp x-ui/x-ui.sh /usr/bin/x-ui
mv x-ui/ /usr/local/
systemctl enable x-ui && systemctl restart x-ui
```

---

## 2. Начальная настройка и Безопасность

После установки панель доступна по адресу: `http://<IP_ВАШЕГО_СЕРВЕРА>:2053`

> [!warning] Данные по умолчанию
> Если вы не меняли их при установке:
> - **Логин:** `admin`
> - **Пароль:** `admin`
> 
> **ОБЯЗАТЕЛЬНО измените их в разделе "Panel Settings" -> "Authentication"!**

### Рекомендуемые шаги безопасности:
1. **Смена порта:** Измените стандартный `2053` на любой случайный (например, `49231`).
2. **Web Base Path:** Установите секретный путь, например `/mysecretpanel/`. Теперь адрес будет `http://ip:port/mysecretpanel/`. Это защитит от автоматического сканирования.
3. **2FA:** Включите двухфакторную аутентификацию (Google Authenticator) в настройках.

---

## 3. Управление через терминал (CLI)

Команда `x-ui` запускает интерактивное меню. Основные флаги:

| Команда | Описание |
| :--- | :--- |
| `x-ui` | Основное меню управления |
| `x-ui status` | Текущий статус сервиса |
| `x-ui start/stop/restart` | Управление работой панели |
| `x-ui enable/disable` | Включение/отключение автозагрузки |
| `x-ui log` | Просмотр логов в реальном времени |
| `x-ui update` | Обновление панели и Xray-core |
| `x-ui install/uninstall` | Установка или полное удаление |

---

## 4. Конфигурация, SSL и Fail2Ban

### 🔐 Получение SSL сертификата
Для работы протоколов Reality, VLESS-gRPC и защиты самой панели.

- **Через меню x-ui:** Запустите `x-ui` и выберите пункт `SSL Certificate Management`. Скрипт поможет выпустить сертификат через ACME (Let's Encrypt).
- **Cloudflare API:** Если домен на Cloudflare, можно использовать Global API Key для автоматического подтверждения прав на домен.

### 🛡 Fail2Ban (Ограничение по IP)
Для предотвращения брутфорса и ограничения количества одновременных подключений на одного клиента:
1. В терминале: `x-ui` -> `IP Limit Management`.
2. В панели (Xray Configs): установите `Access log` -> `./access.log`.
3. Перезапустите Xray. Система начнет блокировать нарушителей через фаервол сервера.

---

## 5. Reverse Proxy (Nginx, Caddy)

### Nginx (рекомендуемый конфиг)
Позволяет повесить панель на стандартный 443 порт вместе с сайтом.
```nginx
location / {
    proxy_redirect off;
    proxy_pass http://127.0.0.1:2053; # Порт вашей панели
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

# Для работы подписок
location /sub {
    proxy_pass http://127.0.0.1:2096; # Порт подписок
    proxy_set_header Host $http_host;
}
```

---

## 6. API и Переменные окружения

Панель полностью управляется через REST API.

### Основные эндпоинты:
- Авторизация: `POST /login`
- Список клиентов: `GET /panel/api/inbounds/list`
- Добавление клиента: `POST /panel/api/inbounds/addClient`
- Статистика: `GET /panel/api/inbounds/getClientTraffics/:email`

### Переменные окружения (Docker):
- `XUI_DB_FOLDER`: Путь к базе данных (дефолт `/etc/x-ui`).
- `XUI_LOG_LEVEL`: Уровень логирования (debug, info, warn, error).
- `XUI_BIN_FOLDER`: Путь к бинарным файлам Xray.

---

## 7. Продвинутые функции (Telegram, WARP, TOR)

### 💭 Telegram бот
Бот присылает уведомления о входе, нагрузке на сервер и делает автоматические бэкапы БД.
1. Создайте бота через `@BotFather`.
2. Узнайте свой ID через `@userinfobot`.
3. В **Panel Settings** введите Token и Chat ID.
4. Установите расписание (Cron), например `@daily` или `@every 12h`.

### ➡️ Cloudflare WARP
Используется, если ваш IP сервера забанен в Google (403), ChatGPT или вы хотите скрыть исходящий IP.
1. В разделе **Outbounds** нажмите кнопку **WARP** -> Создать.
2. В **Routing Rules** добавьте правило:
    - **Outbound Tag:** `warp`
    - **Domain:** `geosite:google, openai.com, netflix.com`

---

## 8. Решение проблем и FAQ

- **Ошибка "Database is locked":** Возникает из-за медленной записи логов. В настройках Xray установите `Access Log` в значение `none`.
- **Ошибка 400 (Bad Request):** Проверьте синхронизацию времени на сервере (`timedatectl`). Разница более 30 секунд ломает протоколы.
- **Панель не открывается после смены порта:** Проверьте фаервол:
    ```bash
    ufw allow <ваш_порт>/tcp
    # или
    iptables -A INPUT -p tcp --dport <ваш_порт> -j ACCEPT
    ```
- **Сброс настроек:** Если вы забыли пароль или порт, введите `x-ui` в терминале и выберите **Reset Settings**. Это вернет доступ по `admin/admin` на порт `2053`.

---
#3x_ui #xray #vpn #proxy #tutorial #linux #devops