docs: vendor the documentation site into the monorepo

Fold the standalone 3x-ui-docs project (Next.js 16 + Fumadocs, deployed to docs.sanaei.dev) into docs/ so the panel and its documentation share a single source of truth, the way sing-box keeps its docs in-tree. The old repo becomes redundant and can be retired. - Import the full site under docs/ (app, components, content, lib, public, scripts, config). The self-contained pnpm project sits alongside the existing engineering notes with no filename collisions. - Re-point "Edit on GitHub" links from MHSanaei/3x-ui-docs to this repo's docs/content/docs path (docs/lib/shared.ts, docs/app/.../page.tsx). - Add docs-ci.yml and docs-deploy.yml under .github/workflows/, scoped to docs/** and run with working-directory: docs, since GitHub only runs workflows from the repo-root .github/. deploy-static.yml's GitHub Pages publish (CNAME docs.sanaei.dev) carries over unchanged. Follow-up (outside this commit): attach the docs.sanaei.dev custom domain to this repository's Pages (or set the Vercel project's root directory to docs), confirm the site is live from the monorepo, then delete MHSanaei/3x-ui-docs.
2026-10-26 15:55:02 +03:00 · 2026-07-07 23:07:14 +02:00
parent 2c49dbf54e
commit 9b91f0f42e
283 changed files with 44179 additions and 0 deletions
@@ -0,0 +1,130 @@
+---
+title: Первый вход
+description: Найдите сгенерированные учётные данные 3x-ui, откройте панель, включите двухфакторную аутентификацию и защитите её, прежде чем открывать доступ извне.
+icon: KeyRound
+---
+
+После установки ваша первая задача — войти в панель и **защитить её**, прежде
+чем открывать доступ к чему-либо ещё.
+
+## Открытие панели
+
+Панель доступна по адресу:
+
+```text
+http://<your-server-ip>:<port>/<web-base-path>
+```
+
+Порт по умолчанию — **2053**, а базовый путь по умолчанию — `/`, однако при
+установке через скрипт имя пользователя, пароль, **порт** и базовый веб-путь
+**генерируются случайным образом**, поэтому проверьте свои фактические значения.
+
+### Поиск учётных данных
+
+При установке через скрипт по завершении выводится сводка учётных данных,
+которая также записывается в файл, доступный только пользователю root:
+
+```bash title="/etc/x-ui/install-result.env (mode 600)"
+XUI_USERNAME=...
+XUI_PASSWORD=...
+XUI_PANEL_PORT=...
+XUI_WEB_BASE_PATH=...
+XUI_ACCESS_URL=...
+XUI_API_TOKEN=...
+XUI_DB_TYPE=sqlite
+```
+
+Если вы их пропустили, воспользуйтесь инструментами управления:
+
+```bash
+x-ui              # menu → 11 (View Current Settings)
+x-ui settings     # or the one-shot form
+```
+
+В случае **Docker** прочитайте сгенерированные учётные данные из логов
+контейнера или выполните `docker exec -it <container> x-ui setting -show`.
+
+<Callout type="warn">
+  Если ваша панель всё ещё использует учётные данные по умолчанию `admin` /
+  `admin` (панель предупреждает об этом), смените их немедленно — прежде чем
+  создавать какие-либо входящие подключения.
+</Callout>
+
+## Смена учётных данных, порта и пути
+
+Нестандартный порт и длинный случайный **базовый веб-путь** значительно
+усложняют обнаружение панели. Измените их в разделе **Panel Settings** в
+интерфейсе или через меню `x-ui`:
+
+- **7 — Reset Username & Password** (с возможностью одновременно отключить 2FA)
+- **8 — Reset Web Base Path** (генерирует случайный путь)
+- **10 — Change Port**
+
+Смена имени пользователя или пароля **завершает все активные сессии** и, если
+была включена двухфакторная аутентификация, отключает её.
+
+## Двухфакторная аутентификация (2FA)
+
+3x-ui поддерживает двухфакторную аутентификацию по TOTP (совместима с Google
+Authenticator, Aegis и т. п.). Включите её в разделе **Panel Settings** — после
+включения страница входа будет запрашивать 6-значный код в дополнение к паролю,
+а её активация заставит всех войти заново. Отключить 2FA можно через пункт меню
+**Reset Username & Password** или командой `x-ui setting -resetTwoFactor`.
+
+## Встроенная защита входа
+
+- **Ограничение перебора:** после **5** неудачных попыток входа с одного и того
+  же IP/имени пользователя в течение 5 минут эта комбинация блокируется на
+  **15 минут**.
+- **Обобщённые ошибки:** страница входа сообщает «wrong username or password»
+  как при неверных учётных данных, так и при неверных кодах 2FA, поэтому ничего
+  не раскрывает.
+- **Сессии** действуют `sessionMaxAge` минут (по умолчанию **360** = 6 часов) и
+  аннулируются при смене учётных данных.
+- **LDAP** можно включить как резервный способ аутентификации в разделе Panel
+  Settings.
+
+## Базовый чек-лист по защите
+
+<Steps>
+
+<Step>
+### Задайте надёжные уникальные учётные данные
+
+Замените сгенерированные (или `admin/admin`) имя пользователя и пароль на
+надёжные значения.
+</Step>
+
+<Step>
+### Используйте нестандартный порт и случайный базовый путь
+
+Перенесите панель с порта `2053` и разместите её по длинному случайному пути.
+</Step>
+
+<Step>
+### Включите двухфакторную аутентификацию
+
+Включите 2FA, чтобы одной лишь утечки пароля было недостаточно для доступа.
+</Step>
+
+<Step>
+### Разместите панель за TLS
+
+Используйте действительный сертификат (через управление SSL в меню `x-ui` или
+обратный прокси), чтобы панель была доступна только по HTTPS.
+</Step>
+
+<Step>
+### Ограничьте доступ с помощью брандмауэра
+
+Открывайте только действительно необходимые порты и рассмотрите возможность
+ограничения доступа к панели по IP.
+</Step>
+
+</Steps>
+
+<Callout type="info">
+  Хотите разместить панель на отдельном домене с автоматическим HTTPS? См.
+  [Обратный прокси](/docs/operations/reverse-proxy). Для более глубокой защиты см.
+  [Безопасность](/docs/operations/security).
+</Callout>
@@ -0,0 +1,71 @@
+---
+title: Знакомство с 3x-ui
+description: Веб-панель для Xray-core — управляйте входящими подключениями, протоколами, клиентами и подписками из браузера, не редактируя JSON вручную.
+icon: Info
+---
+
+**3x-ui** — это веб-панель управления, которая работает поверх
+[Xray-core](https://github.com/XTLS/Xray-core), прокси-движка, который непосредственно
+передаёт ваш трафик. Вместо того чтобы вручную писать и перезагружать JSON-конфигурацию Xray,
+вы управляете всем — входящими подключениями, протоколами, клиентами, сертификатами,
+подписками — из панели управления в браузере.
+
+## Как всё связано между собой
+
+<Mermaid
+  chart={`
+flowchart LR
+  Admin["Admin browser"] -->|HTTPS panel| Panel["3x-ui panel"]
+  Panel -->|writes config, reloads| Xray["Xray-core"]
+  Panel --- DB[("SQLite or PostgreSQL")]
+  Clients["Client apps"] -->|VLESS / VMess / Trojan / ...| Xray
+  Xray -->|proxied traffic| Internet["Internet"]
+`}
+/>
+
+- **Панель** — это уровень управления: она хранит вашу конфигурацию в
+  базе данных, отображает панель управления, предоставляет REST API и записывает
+  актуальную конфигурацию Xray.
+- **Xray-core** — это уровень передачи данных: он принимает клиентские подключения на ваших
+  **входящих подключениях** и пересылает трафик к месту назначения.
+- **Клиентские приложения** (такие как v2rayNG, Clash/Mihomo, Hiddify и другие) подключаются
+  по ссылке для подключения или подписке, которую панель генерирует для каждого клиента.
+
+## Что она вам даёт
+
+- Панель управления **входящими подключениями** по всем основным протоколам — VLESS, VMess,
+  Trojan, Shadowsocks, WireGuard, Hysteria2, SOCKS, HTTP и Dokodemo-door.
+- Полноценная поддержка **REALITY** и **XTLS-Vision** для скрытных и быстрых
+  транспортов.
+- **Поклиентские** квоты трафика, даты истечения, ограничения по IP, статус «онлайн» и
+  ссылки для подключения / QR-коды в один клик.
+- **Подписки** в форматах VLESS, Clash/Mihomo и JSON.
+- Инструменты для эксплуатации: управление **несколькими узлами**, **Telegram-бот**, резервные копии,
+  ограничение по IP на базе Fail2ban и документированный REST API.
+
+## Что под капотом
+
+| Уровень        | Технология                                   |
+| ------------ | -------------------------------------------- |
+| Бэкенд      | Go с веб-фреймворком Gin                |
+| Фронтенд     | TypeScript / React                           |
+| База данных     | SQLite (по умолчанию) или PostgreSQL               |
+| Прокси-движок | Xray-core (входит в комплект и управляется панелью) |
+
+База данных SQLite по умолчанию находится по пути `/etc/x-ui/x-ui.db`, а панель слушает
+порт **2053** по умолчанию. Оба значения настраиваются — см.
+[Первый вход](/docs/guide/first-login) и справочник по переменным окружения.
+
+## Для кого она
+
+3x-ui рассчитана на всех, кто запускает собственный сервер Xray: от одного личного
+VPS до операторов, управляющих множеством узлов и клиентов. Если вам нужна вся мощь
+Xray-core без необходимости жить в файлах JSON-конфигурации, это для вас.
+
+<Callout type="info">
+  3x-ui — это улучшенный форк оригинального проекта X-UI, добавляющий более широкую поддержку
+  протоколов, повышенную стабильность, поклиентский учёт трафика, управление несколькими
+  узлами и множество улучшений для удобства работы.
+</Callout>
+
+Готовы к установке? Переходите к разделу [Установка](/docs/guide/installation).
@@ -0,0 +1,151 @@
+---
+title: Установка
+description: Установите 3x-ui с помощью официального скрипта (стабильная, фиксированная или dev-сборка), в автоматическом режиме / через cloud-init либо в Docker — и выберите SQLite или PostgreSQL.
+icon: Download
+---
+
+3x-ui работает на широком спектре дистрибутивов Linux — Ubuntu, Debian, Armbian,
+Fedora, CentOS, RHEL, AlmaLinux, Rocky Linux, Oracle Linux, Amazon Linux,
+Virtuozzo, Arch, Manjaro, openSUSE (Tumbleweed/Leap), Alpine — а также в Windows,
+на архитектурах `amd64`, `386`, `arm64`, `armv7`, `armv6`, `armv5` и `s390x`.
+
+<Callout type="warn">
+  Запускайте установочный скрипт от имени **root** (или через `sudo`). Он
+  устанавливает службу, настраивает команду управления `x-ui` и включает
+  автозапуск панели при загрузке.
+</Callout>
+
+<Tabs items={['Script', 'Docker', 'Manual']}>
+
+<Tab value="Script">
+
+Официальный скрипт — рекомендуемый способ. В процессе установки он генерирует
+**случайные** имя пользователя, пароль и путь доступа (базовый веб-путь),
+настраивает службу и устанавливает команду управления `x-ui`.
+
+```bash title="latest stable"
+bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
+```
+
+Чтобы установить **конкретную версию**, добавьте её тег:
+
+```bash title="pinned version"
+bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) v3.4.0
+```
+
+Чтобы установить скользящую **dev**-сборку (последний предварительный релиз по
+каждому коммиту из `main` — не стабильный релиз), передайте `dev-latest`:
+
+```bash title="rolling dev build"
+bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) dev-latest
+```
+
+По завершении запишите выведенные данные для входа и выполните `x-ui`, чтобы
+открыть [меню управления](/docs/guide/update-uninstall#the-x-ui-management-menu),
+а затем переходите к разделу [Первый вход](/docs/guide/first-login).
+
+</Tab>
+
+<Tab value="Docker">
+
+В конфигурации Compose по умолчанию используется SQLite. Клонируйте репозиторий
+(или скопируйте его файлы `docker-compose.yml` и `Dockerfile`) и запустите:
+
+```bash
+docker compose up -d
+```
+
+Чтобы запустить со встроенной службой **PostgreSQL**, раскомментируйте две
+строки `XUI_DB_*` в `docker-compose.yml` и запустите с соответствующим профилем:
+
+```bash
+docker compose --profile postgres up -d
+```
+
+Предпочитаете готовый образ? Он публикуется в GitHub Container Registry. Образ
+включает Fail2ban (для [ограничений по IP](/docs/operations/security)), который
+блокирует через `iptables` и поэтому требует `NET_ADMIN` (а для IPv6 — ещё и
+`NET_RAW`); в противном случае блокировки логируются, но никогда не применяются:
+
+```bash title="docker run"
+docker run -d \
+  --cap-add=NET_ADMIN \
+  --cap-add=NET_RAW \
+  -e XUI_ENABLE_FAIL2BAN=true \
+  -v $PWD/db/:/etc/x-ui/ \
+  -v $PWD/cert/:/root/cert/ \
+  --network=host \
+  --restart=unless-stopped \
+  --name 3x-ui \
+  ghcr.io/mhsanaei/3x-ui:latest
+```
+
+Том `db/` хранит базу данных SQLite (`/etc/x-ui/x-ui.db`), а `cert/` — TLS-сертификаты,
+поэтому ваши данные сохраняются при обновлениях.
+
+</Tab>
+
+<Tab value="Manual">
+
+Опытные пользователи могут скачать архив релиза для своей архитектуры со
+[страницы релизов](https://github.com/MHSanaei/3x-ui/releases), распаковать его и
+запустить бинарный файл как службу systemd. Установочный скрипт автоматизирует
+ровно эти шаги, поэтому он предпочтительнее, если только у вас нет особой причины
+устанавливать вручную.
+
+</Tab>
+
+</Tabs>
+
+## Сформируйте команду установки
+
+Подстройте команду под свою конфигурацию:
+
+<InstallCommandBuilder />
+
+## Выберите базу данных
+
+Хранилище выбирается на этапе установки:
+
+- **SQLite** (по умолчанию) — единственный файл по пути `/etc/x-ui/x-ui.db`. Без
+  какой-либо настройки.
+- **PostgreSQL** — для большого числа клиентов или конфигураций с несколькими
+  узлами. Установщик может развернуть её локально либо использовать
+  предоставленный вами DSN.
+
+Подробности и миграцию SQLite→PostgreSQL см. в разделе [База данных](/docs/reference/database).
+
+## Автоматическая установка / cloud-init
+
+Установщик также работает **в неинтерактивном режиме** для автоматизации.
+Задайте `XUI_NONINTERACTIVE=1` (или запустите без TTY), и он выполнит установку
+от начала до конца без единого запроса, сгенерировав случайные учётные данные и
+записав их в `/etc/x-ui/install-result.env`:
+
+```bash
+XUI_NONINTERACTIVE=1 bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
+```
+
+В каталоге [`deploy/`](https://github.com/MHSanaei/3x-ui/tree/main/deploy)
+репозитория есть готовые **cloud-init** user-data для автоматической установки в
+любом облаке (Hetzner, AWS, DigitalOcean, Vultr, GCP, Azure, Oracle).
+
+## Дальнейшие шаги
+
+<Cards>
+  <Card
+    title="Первый вход"
+    href="/docs/guide/first-login"
+    description="Откройте панель и защитите её."
+  />
+  <Card
+    title="Обновление и удаление"
+    href="/docs/guide/update-uninstall"
+    description="Меню x-ui, обновления и удаление."
+  />
+  <Card
+    title="REALITY"
+    href="/docs/config/reality"
+    description="Настройте своё первое скрытное входящее подключение."
+  />
+</Cards>
@@ -0,0 +1,5 @@
+{
+  "title": "Начало работы",
+  "icon": "Rocket",
+  "pages": ["index", "installation", "first-login", "update-uninstall"]
+}
@@ -0,0 +1,101 @@
+---
+title: Обновление и удаление
+description: Управляйте 3x-ui через меню и CLI x-ui — обновляйте (стабильная, dev- или старая версия), меняйте настройки и удаляйте панель без остатков.
+icon: RefreshCw
+---
+
+После установки через скрипт команда `x-ui` становится вашим центром управления.
+Запустите её без аргументов, чтобы открыть интерактивное меню, либо передайте
+подкоманду для разового действия.
+
+```bash
+x-ui
+```
+
+## Меню управления `x-ui`
+
+В меню (пункты `0`–`28`) сверху отображается статус панели/Xray, а далее:
+
+| #     | Пункт                                  | Что делает                                                |
+| ----- | -------------------------------------- | --------------------------------------------------------- |
+| 1     | Install                                | (Пере)установка из удалённого скрипта                     |
+| 2     | Update                                 | Обновление до последнего **стабильного** релиза           |
+| 3     | Update to Dev Channel (latest commit)  | Обновление до скользящей сборки `dev-latest`              |
+| 4     | Update Menu                            | Обновление только скрипта меню `x-ui`                     |
+| 5     | Legacy Version                         | Установка конкретной старой версии (запросит тег)         |
+| 6     | Uninstall                              | Удаление 3x-ui (см. ниже)                                 |
+| 7     | Reset Username & Password              | Задать новые учётные данные; при желании отключить 2FA    |
+| 8     | Reset Web Base Path                    | Сгенерировать случайный базовый веб-путь                  |
+| 9     | Reset Settings                         | Сброс настроек панели (ваша учётная запись сохраняется)   |
+| 10    | Change Port                            | Изменить порт панели                                      |
+| 11    | View Current Settings                  | Показать имя пользователя, порт, базовый веб-путь, пути к сертификатам |
+| 12–14 | Start / Stop / Restart                 | Управление службой панели                                 |
+| 15    | Restart Xray                           | Перезапустить только Xray-core                            |
+| 16    | Check Status                           | Статус службы                                             |
+| 17    | Logs Management                        | Просмотр отладочных логов / очистка логов                 |
+| 18–19 | Enable / Disable Autostart             | Включить/выключить автозапуск при загрузке               |
+| 20    | SSL Certificate Management             | Let's Encrypt (домен или IP), пользовательские пути, продление/отзыв |
+| 21    | Cloudflare SSL Certificate             | Wildcard-сертификат через DNS-01 с помощью Cloudflare     |
+| 22    | IP Limit Management                    | Ограничения по IP на клиента на базе Fail2ban             |
+| 23    | Firewall Management                    | Установка `ufw` и правила для портов                      |
+| 24    | SSH Port Forwarding Management         | Привязать панель к localhost и туннелировать через SSH    |
+| 25    | PostgreSQL Management                  | Установка/миграция/управление PostgreSQL                  |
+| 26    | Enable BBR                             | Переключить sysctl-управление перегрузкой BBR             |
+| 27    | Update Geo Files                       | Обновить данные geoip/geosite (Loyalsoldier, IR, RU)      |
+| 28    | Speedtest by Ookla                     | Запустить тест скорости Ookla                             |
+| 0     | Exit                                   | —                                                         |
+
+Некоторым из этих пунктов посвящены отдельные страницы: [SSL-сертификаты](/docs/config/ssl-certificates)
+(пункты 20–21), [Безопасность](/docs/operations/security) (ограничения по IP, фаервол),
+[Обратный прокси](/docs/operations/reverse-proxy) и [Настройки панели](/docs/config/panel)
+(TLS), а также [База данных](/docs/reference/database) (PostgreSQL).
+
+## Подкоманды CLI
+
+Для скриптов и быстрых действий `x-ui` также принимает подкоманду напрямую:
+
+| Команда                    | Действие                                            |
+| -------------------------- | --------------------------------------------------- |
+| `x-ui start` / `stop` / `restart` | Управление службой                           |
+| `x-ui restart-xray`        | Перезапустить только Xray-core                      |
+| `x-ui status`              | Показать статус                                     |
+| `x-ui settings`            | Показать текущие настройки                          |
+| `x-ui enable` / `disable`  | Включить/выключить автозапуск при загрузке         |
+| `x-ui log`                 | Вывести отладочный лог в реальном времени           |
+| `x-ui banlog`              | Показать лог блокировок Fail2ban                    |
+| `x-ui update`              | Обновить до последнего стабильного релиза           |
+| `x-ui update-dev`          | Обновить до скользящей сборки `dev-latest`          |
+| `x-ui legacy`              | Установить конкретную старую версию (с запросом)    |
+| `x-ui update-all-geofiles` | Обновить все geo-файлы, перезапустить при изменениях |
+| `x-ui migrate-db --dsn …`  | Миграция SQLite → PostgreSQL (см. [База данных](/docs/reference/database)) |
+| `x-ui install` / `uninstall` | Установка / удаление                              |
+
+## Обновление
+
+- **Стабильная версия:** пункт меню **2** или `x-ui update`. Повторный запуск
+  установочного скрипта также обновляет панель на месте.
+- **Dev-канал:** пункт меню **3** или `x-ui update-dev` — скользящая сборка
+  `dev-latest` по каждому коммиту (не стабильный релиз).
+- **Конкретная старая версия:** пункт меню **5** (Legacy Version).
+
+Обновление сохраняет вашу базу данных и настройки. Перед переходом на новую
+мажорную версию сделайте [резервную копию](/docs/operations/backup-restore).
+
+<Callout type="info">
+  Пользователи Docker обновляются иначе — нужно скачать новый образ и пересоздать
+  контейнер (`docker compose pull && docker compose up -d`), а не использовать
+  команды обновления `x-ui`.
+</Callout>
+
+## Удаление
+
+Пункт меню **6** или `x-ui uninstall`. Команда останавливает и отключает службу,
+удаляет юнит службы, а также каталоги `/etc/x-ui/` и папку установки. Если панель
+использовала локально установленный PostgreSQL, она предложит удалить и его
+(отдельное необратимое подтверждение).
+
+<Callout type="warn">
+  Удаление стирает базу данных (`/etc/x-ui/x-ui.db`) и вашу конфигурацию.
+  Сначала сделайте [резервную копию](/docs/operations/backup-restore), если она
+  может вам понадобиться.
+</Callout>