# Управление клиентами

> Добавьте пользователей, поделитесь деталями подключения и управляйте ключами доступа.

## Добавить клиента

```
meridian client add alice
```

Это даёт "alice" её собственный ключ и выводит две вещи для обмена:

- **Ссылка на страницу подключения** с QR кодом — самый простой способ отправить
- **URL подписки** для прямого импорта в приложение Xray/V2Ray

Добавьте нескольких человек сразу:

```
meridian client add alice bob charlie
```

Клиенты принадлежат всем вашим серверам, а не одному серверу. Каждый выход и промежуточный сервер, который у вас есть, показывается в их подписке.

### Что видит получатель

Страница подключения построена из подлинной подписки человека, поэтому она перечисляет ровно то, что получают его приложения: прямые выходы, промежуточные серверы и все включённые способы. На ней есть:

- Два шага: установить приложение, рекомендованное для платформы человека (сначала Happ, затем FlClashX и Clash Mi, а на компьютере ещё Throne), и добавить подключение одним касанием
- QR-код подписки; на компьютере он показан рядом с шагами, чтобы человек мог настроить телефон
- Каждое отдельное подключение с кнопками «Открыть», «Копировать» и QR, свёрнутое, пока не понадобится
- Раздел «Не подключается?» с советами и проверкой «Проверить подключение», которая копирует отчёт без ссылок, чтобы его можно было отправить вам

В приложении записи названы по стране выхода и способу: «🇩🇪 DE · Reality · Chrome», «🇩🇪 DE · XHTTP · Chrome», «🇩🇪 DE · WebSocket · CDN», «🇩🇪 DE · Hysteria2 · UDP»; у записей через промежуточный сервер добавляется «via relay». Если два выхода находятся в одной стране, после флага показываются их имена («🇩🇪 main»); у выхода с неизвестной страной показывается его имя, когда выходов несколько. Reality и XHTTP приходят также копиями «· Firefox» с другим отпечатком TLS — на случай, если один отпечаток заблокируют. Приложения с автопереключением (приложения на Xray JSON, такие как Happ, а также Mihomo и sing-box) сами выбирают рабочую запись, но не переключаются между отпечатками; для этого Happ показывает отдельную запись «Automatic · Firefox».

Отправьте ссылку через любой мессенджер. Получатель открывает её, устанавливает приложение, нажимает «Добавить в …» (или сканирует QR-код с другого устройства) и подключается. [Подключение](/ru/connecting.md) проводит человека через эти шаги и подсказывает, что делать, когда подключение перестаёт работать; отправьте ему и эту страницу.

## Показать детали подключения

Чтобы снова поделиться ссылками клиента:

```
meridian client show alice
```

Это выводит страницу подключения и URL подписки, плюс статус, трафик и когда клиент был последний раз виден. Если страница отсутствует (например, загрузка не удалась), переопубликуйте её:

```
meridian client show alice --repair-page
```

## Перечислить клиентов

```
meridian client list
```

Показывает каждого клиента со статусом, трафиком, временем создания и последним видением.

## Приостановить и возобновить клиента

```
meridian client disable alice
meridian client enable alice
```

`disable` отключает клиента немедленно; `enable` позволяет им вернуться с теми же ссылками.

Отключение действует до `client enable`: apply, переразвёртывания и изменения набора серверов его не затрагивают.

## Замена утёкшей ссылки

Если ссылка или страница подключения клиента попала не к тому человеку, замените её:

```
meridian client reissue alice
```

Remnawave выдаёт клиенту новый идентификатор подписки и новые ключи. Старый URL подписки и старая страница подключения отвечают 404, а серверы отклоняют старые ключи. Meridian удаляет старую страницу, публикует новую и выводит новую страницу и URL подписки, которые нужно отправить клиенту. Новую ссылку импортируют один раз: приложения не могут обновить подписку, URL которой больше не существует. Всё остальное, что панель хранит о клиенте, сохраняется: статус, лимит и расход трафика, срок действия, описание и лимит устройств HWID.

Лимит устройств HWID хранится в панели, а не в ссылке. Уже зарегистрированные устройства остаются в списке HWID клиента после перевыпуска и продолжают занимать места, хотя их старая ссылка больше не подключается. Откройте клиента в панели и удалите незнакомые устройства, чтобы лимит учитывал только устройства самого клиента. Собственных билетов или привязки к устройству Meridian не добавляет.

С `--json` передайте `--yes`. Новые ссылки появляются только в выводе этой команды.

## Удаление клиента

`meridian client remove NAME` удаляет клиента окончательно: его ссылки перестанут работать и его страница подключения будет удалена. Всегда остаётся минимум один клиент. Не удаляйте пользователей в панели Remnawave напрямую — Meridian воссоздаёт любого клиента, который остался в топологии, при следующем применении.

## Ссылки подписки

URL подписки выглядят как `https://198.51.100.10/<page-path>/sub/<id>`. Они находятся под путём страницы подключения; админ-панель Remnawave остаётся на отдельном секретном пути, который общие ссылки никогда не раскрывают.

Каждая подписка просит приложения обновлять её каждые 6 часов (заголовок `profile-update-interval`, которому следуют такие приложения, как Happ и Clash Verge), поэтому когда вы добавляете выход или промежуточный сервер, клиенты подхватывают его в течение нескольких часов без новой ссылки. Приложения, игнорирующие заголовок, обновляют подписку по собственному расписанию; ручное обновление в приложении подхватывает изменения сразу.

Кнопка поддержки в приложении открывает страницу подключения этого человека с подсказками «Не подключается?». Чтобы вести людей в другое место, задайте свой заголовок `support-url` в настройках подписки в панели; Meridian его сохранит.

### Проверенные приложения и движки

Один URL подписки отдаёт каждому приложению тот формат, который оно читает. Каждое изменение Meridian запускает многоузловую тестовую лабораторию: она получает каждый формат от настоящей панели Remnawave и проверяет его движком, на котором построены эти приложения:

| Формат | Приложения | Проверенный движок | Что проверяет лаборатория |
|--------|------|---------------|---------------------|
| Xray JSON | Happ, v2rayNG, v2rayN, Streisand, V2Box | Xray 26.7.28 | Трафик проходит через каждую точку входа и через автоматическое переключение при сбое; неверный ключ отклоняется |
| Mihomo | FlClashX, Clash Mi | Mihomo 1.19.32 | `mihomo -t` загружает профиль, его правила и резервную группу |
| sing-box | sing-box (SFA, SFI), Karing | sing-box 1.14.3 | `sing-box check` загружает профиль, а его автоматическая группа является маршрутом по умолчанию |
| Base64 ссылки | другие приложения Xray/V2Ray (v2RayTun, Shadowrocket) | — | Каждая ссылка разбирается и указывает те же серверы и ключ, что и другие форматы |

Приложения сами выпускают обновления движков, поэтому приложение может использовать чуть более старый или более новый движок, чем проверенный.

## Где находятся данные клиента

Учётные записи клиентов (ключи, статус, трафик) живут в базе данных панели Remnawave на сервере контроль-плана. Список клиентов, которыми управляет Meridian, является частью вашей топологии в `~/.config/meridian/cluster.yml`. Команды client используют API панели и не требуют SSH; публикация страницы подключения использует SSH к серверу контроль-плана.

## Веб-панель

[Remnawave](https://remna.st/) админ-панель показывает трафик, пользователей и узлы в браузере, и вы добро пожаловать использовать её. `meridian panel` выводит её URL и имя администратора; `meridian panel --show-password` также выводит пароль.

Meridian и панель разделяют работу поэтому ваши правки не переписываются:

| Meridian управляет (следующее применение восстанавливает его версию) | Ваши для изменения (apply никогда не касается этих) |
|---|---|
| Узлы, профили конфигурации, inbounds, опубликованные Hosts, отряды | Статус каждого клиента: включить/отключить, лимиты трафика, истечение, HWID лимиты, описание |
| Шаблоны подписки и параметры которые Meridian устанавливает (название, интервал обновления, Xray JSON для приложений, которые его читают, ссылка поддержки, если вы не задали свою) | Пользователи которых вы создали сами в панели |
| Какие клиенты существуют, их имена и их отряды | Оповещения, плагины, IP контроль и другие параметры панели |

`meridian plan` показывает любую разницу в том что Meridian управляет перед что-либо изменится. Пользователи которых вы добавили в панель никогда не перечисляются, не изменяются или не удаляются Meridian; чтобы дать кому-то управляемую Meridian ссылку и страницу подключения, используйте `meridian client add` вместо этого.

### Плагины узлов

Плагины узлов Remnawave (Ingress Filter, Egress Filter, Torrent Blocker, Connection Drop) необязательны и находятся в панели. Чтобы использовать один из них, откройте **Node Plugins** в интерфейсе администратора, создайте конфигурацию плагинов, включите нужные плагины и привяжите конфигурацию к своим узлам. Meridian уже запускает каждый узел с разрешением `NET_ADMIN`, которое нужно плагинам, и никогда не изменяет и не удаляет ваши конфигурации плагинов.

Плагины записывают правила nftables на хосте, поэтому upstream также требует ядро Linux 5.7 или новее; на более старом они молча ничего не делают. `meridian check` сообщает об этом как о **Node plugin readiness** на каждом выходе и шлюзе и предупреждает о старом ядре (перейдите на Ubuntu 22.04+ или Debian 11+). Если вы не используете плагины, это предупреждение можно игнорировать.

Torrent Blocker распознаёт BitTorrent с помощью sniffing трафика, который Meridian включает (в режиме route-only, поэтому адреса назначения никогда не переписываются) на каждом inbound, который он формирует. Включите плагин в панели, и он заработает на каждом выходе.

### Подключить бота к панели

Сторонние боты, например Telegram бот, который сообщает, сколько трафика осталось, обращаются напрямую к API Remnawave. Дайте каждому боту собственный токен только с нужным ему доступом:

1. Откройте панель (`meridian panel` выводит URL), перейдите в **Remnawave Settings → API tokens** (настройки Remnawave, API токены) и выберите **Create API token**.
2. Назовите токен именем бота и задайте **Expires in (days)** на срок, который вы действительно будете ротировать, например 30 или 90 дней.
3. Начните с пресета **Read only** или выберите отдельные эндпоинты и выдайте только то, что использует бот. Панель показывает токен один раз; храните его вместе с секретами бота.
4. Укажите боту URL панели из `meridian panel` и отправляйте токен как `Authorization: Bearer <token>`. Пути API идут после этого URL, например `https://198.51.100.10/<secret-path>/api/users/by-username/alice`. URL содержит секретный путь панели, поэтому храните его так же скрытно, как токен.

Права называются `resource:endpoint`; `resource:read` даёт все эндпоинты чтения ресурса, а `resource:write` все эндпоинты записи. Типичному боту только для чтения нужны:

| Право | Эндпоинт | Возвращает |
|---|---|---|
| `users:by-username` | `GET /api/users/by-username/{username}` | Статус одного пользователя, использованный трафик и лимит, срок действия |
| `users:by-short-uuid` | `GET /api/users/by-short-uuid/{shortUuid}` | То же, но по идентификатору из ссылки подписки пользователя |
| `users:list` | `GET /api/users` | Всех пользователей, постранично |
| `system:stats` | `GET /api/system/stats` | Общие итоги по пользователям и трафику панели |
| `nodes:list` | `GET /api/nodes` | Статус и трафик каждого узла |

Добавляйте право на запись, только если бот изменяет учётные записи, например `users:extend` (`POST /api/users/{id}/actions/extend`) для платёжного бота, продлевающего срок. Статус, лимиты и срок действия вы изменяете сами (см. таблицу выше), поэтому следующее применение сохраняет правки бота. Бот не должен переименовывать или удалять клиентов Meridian: следующее применение создаст их заново.

Не давайте боту собственный токен Meridian (`meridian-provisioner` в списке токенов). Он даёт полный доступ к панели и практически не истекает, поэтому утечка с хоста бота раскроет все узлы, ключи и пользователей. Отдельный токен ограничивает ущерб тем, что умеет бот, истекает сам и может быть удалён без последствий для Meridian. Не трогайте `meridian-provisioner`; его используют все команды клиентов и применения.