PasarGuard Deprecated APIs

[ImMohammad20000]

⚠️ PasarGuard Deprecated APIs

The following APIs and configuration patterns are deprecated and will be removed in upcoming major releases.

🚀 Changes in v4

• vless.flow will be removed from user proxy settings.
• Flow configuration will only be supported through core_config.inbound.settings.flow.

✨ Example of the new VLESS flow configuration

{
  // ....
  "protocol": "vless",
  "settings": {
    "clients": [],
    "decryption": "none",
    "flow": "xtls-rprx-vision"
  }
  // ....
}

🔥 Changes in v5

• Username-based API endpoints will no longer be the default.
• Start using /api/user/by-id/{user_id} from now on.
• In future versions, this endpoint will become /api/user/{id}.

Deprecated example

/api/user/{username}

Current replacement

/api/user/by-id/{user_id}

Future format

/api/user/{id}

💡 Migration Recommendation

Please migrate to ID-based APIs and update any VLESS flow configuration logic.

---

⚠️ APIهای منسوخ‌شده PasarGuard

موارد زیر منسوخ شده‌اند و در نسخه‌های آینده حذف خواهند شد.

🚀 تغییرات در v4

• فیلد vless.flow از تنظیمات پروکسی کاربر حذف می‌شود.
• تنظیمات Flow فقط از طریق core_config.inbound.settings.flow پشتیبانی خواهد شد.

✨ نمونه تنظیم جدید VLESS Flow

{
  // ....
  "protocol": "vless",
  "settings": {
    "clients": [],
    "decryption": "none",
    "flow": "xtls-rprx-vision"
  }
  // ....
}

🔥 تغییرات در v5

• APIهای مبتنی بر نام کاربری دیگر حالت پیش‌فرض نخواهند بود.
• از این به بعد از /api/user/by-id/{user_id} استفاده کنید.
• در نسخه‌های بعدی، این مسیر به /api/user/{id} تبدیل خواهد شد.

نمونه API منسوخ‌شده

/api/user/{username}

جایگزین فعلی

/api/user/by-id/{user_id}

فرمت آینده

/api/user/{id}

💡 پیشنهاد مهاجرت

لطفاً از APIهای مبتنی بر شناسه استفاده کرده و تنظیمات مربوط به VLESS Flow را به‌روزرسانی کنید.

---

⚠️ Устаревшие API PasarGuard

Следующие API и конфигурации устарели и будут удалены в будущих крупных версиях.

🚀 Изменения в v4

• vless.flow будет удалён из настроек пользовательского прокси.
• Настройка Flow будет доступна только через core_config.inbound.settings.flow.

✨ Пример новой конфигурации VLESS Flow

{
  // ....
  "protocol": "vless",
  "settings": {
    "clients": [],
    "decryption": "none",
    "flow": "xtls-rprx-vision"
  }
  // ....
}

🔥 Изменения в v5

• API-эндпоинты на основе имени пользователя больше не будут использоваться по умолчанию.
• С этого момента используйте /api/user/by-id/{user_id}.
• В будущих версиях этот маршрут станет /api/user/{id}.

Устаревший пример

/api/user/{username}

Текущая замена

/api/user/by-id/{user_id}

Будущий формат

/api/user/{id}

💡 Рекомендация по миграции

Пожалуйста, переходите на API с использованием ID и обновите конфигурацию VLESS Flow.

---

⚠️ PasarGuard 已弃用 API

以下 API 和配置方式已被弃用，并将在未来的主要版本中移除。

🚀 v4 变更

• vless.flow 将从用户代理设置中移除。
• Flow 配置仅支持通过 core_config.inbound.settings.flow 设置。

✨ 新版 VLESS Flow 配置示例

{
  // ....
  "protocol": "vless",
  "settings": {
    "clients": [],
    "decryption": "none",
    "flow": "xtls-rprx-vision"
  }
  // ....
}

🔥 v5 变更

• 基于用户名的 API 将不再作为默认接口。
• 从现在开始，请使用 /api/user/by-id/{user_id}。
• 在未来版本中，该接口将变为 /api/user/{id}。

已弃用示例

/api/user/{username}

当前替代方案

/api/user/by-id/{user_id}

未来格式

/api/user/{id}

💡 迁移建议

请迁移到基于 ID 的 API，并更新所有 VLESS Flow 配置逻辑。

[M03ED]

Deprecated Compatibility Placeholders

---

🇬🇧 English

SERVER_IP and SERVER_IPV6 used to be resolved dynamically from the server network, but that added slow startup behavior and could block badly when the host network was broken or an external IP lookup was unreachable.

They are also unnecessary now — panel-side no-proxy handling is already covered elsewhere, and the effective connection path is handled by the node layer rather than these globals.

SERVER_IP = "127.0.0.1"
SERVER_IPV6 = "[::1]"

---

🇮🇷 فارسی

SERVER_IP و SERVER_IPV6 پیش‌تر به‌صورت پویا از شبکه‌ی سرور دریافت می‌شدند، اما این کار باعث کندی در راه‌اندازی می‌شد و در صورت قطعی شبکه یا عدم دسترسی به سرویس تشخیص IP خارجی، می‌توانست اجرا را به طور کامل متوقف کند.

علاوه بر این، این متغیرها دیگر ضروری نیستند — مدیریت حالت no-proxy در سمت پنل جای دیگری انجام می‌شود، و مسیر اتصال مؤثر توسط node کنترل می‌شود، نه این متغیرهای سراسری.

SERVER_IP = "127.0.0.1"
SERVER_IPV6 = "[::1]"

---

🇷🇺 Русский

Ранее SERVER_IP и SERVER_IPV6 разрешались динамически через сеть сервера, однако это замедляло запуск и могло приводить к полному зависанию при проблемах с сетью хоста или недоступности внешнего сервиса определения IP.

Кроме того, эти переменные больше не нужны — обработка режима no-proxy на стороне панели реализована в другом месте, а фактический путь соединения управляется слоем нод, а не этими глобальными переменными.

SERVER_IP = "127.0.0.1"
SERVER_IPV6 = "[::1]"

---

🇨🇳 中文

SERVER_IP 和 SERVER_IPV6 过去通过服务器网络动态解析，但这会导致启动缓慢，且在宿主网络异常或外部 IP 查询不可达时可能造成严重阻塞。

此外，这些变量现在已不再必要——面板侧的 no-proxy 处理已在其他地方实现，实际连接路径由节点层管理，而非这些全局变量。

SERVER_IP = "127.0.0.1"
SERVER_IPV6 = "[::1]"

[M03ED]

V5 Migration Guide

🌐 فارسی | Русский | 中文

---

[Breaking] User email format change in core config routing

What changed

The identifier used to represent users inside the xray core (exposed as the email field) changed format:

	Format	Example
Before	{id}.{username}	42.john
After	{id}	42

This affects the value of the email field in all user-level stats and routing contexts within the core.

Why

The old id.username format required splitting the string on . every time a usage stat was processed, adding unnecessary CPU work on the hot path of the usage recording job. Using only the numeric ID eliminates that split entirely with no loss of information, since the ID alone uniquely identifies a user.

Who is affected

You are affected if your xray core config contains routing rules that match users by email. These rules will silently stop matching after this change unless updated.

How to migrate

Update any routing rules that reference user emails to use the new numeric-ID-only format.

Before:

{
  "type": "field",
  "user": ["42.john", "7.alice"],
  "outboundTag": "direct"
}

After:

{
  "type": "field",
  "user": ["42", "7"],
  "outboundTag": "direct"
}

To find your user IDs, check the PasarGuard admin panel or query the API — the numeric ID is shown on each user's detail page.

Note on stats

Per-user traffic stats in the core (visible via the xray stats API) are also now keyed by numeric ID only. If you have external tooling that reads raw core stats and parses the id.username key format, update it to expect a plain numeric string.

---

[Breaking] Operator admin access to templates and groups (RBAC)

What changed

In version 4, all admins — including operators (formerly is_sudo=false) — could read the full templates and groups endpoints. With the introduction of RBAC, operator admins now only have access to the lightweight "simple" variants of those endpoints, which return id and name only.

Endpoint	Sudo (Administrator)	Operator
GET /api/user_templates	full read	no access
GET /api/user_templates/simple	full read	id + name only
GET /api/groups	full read	no access
GET /api/groups/simple	full read	id + name only

Sudo admin access is unchanged.

Why

RBAC was implemented to give fine-grained control over what operator admins can see and do. Exposing full template and group management pages to operators was unnecessary for their workflow and cluttered the frontend. The simple endpoints are sufficient for operators to assign templates and groups when creating or editing users.

Who is affected

Operator admins (previously is_sudo=false) and any external API clients or scripts that call the full GET /api/user_templates or GET /api/groups endpoints using operator credentials.

Response format comparison

Simple variant (/api/groups/simple) — available to operators:

[
  { "id": 1, "name": "Basic Plan" },
  { "id": 2, "name": "Premium Plan" }
]

Full endpoint (/api/groups) — sudo only:

[
  {
    "id": 1,
    "name": "Basic Plan",
    "inbound_tags": [],
    "total_users": 10,
    "is_disabled": false
  }
]

The same pattern applies to user templates (GET /api/user_templates vs GET /api/user_templates/simple).

How to migrate

• Frontend / UI: No action needed — the dashboard already reflects the new permissions.
• API clients using operator credentials: Switch from the full read endpoints to the simple variants if you only need to list available templates or groups for selection. If you need full detail, use a sudo admin account instead.
• Custom integrations: Review any scripts that call these endpoints with operator tokens and update them accordingly.

---

---

راهنمای مهاجرت

[تغییر حیاتی] فرمت ایمیل کاربر تو روتینگ هسته عوض شد

چی عوض شد

اون شناسه‌ای که هسته xray برای کاربرا استفاده می‌کنه (همون فیلد email) فرمتش فرق کرده:

	فرمت	مثال
قبلاً	{id}.{username}	42.john
الان	{id}	42

این روی فیلد email تو تمام آمار کاربرا و روتینگ هسته تأثیر داره.

چرا؟

فرمت قدیمی id.username هر بار که یه آمار مصرف پردازش می‌شد، باید رشته رو روی . اسپلیت می‌کرد — یه کار اضافه‌ی بی‌معنی روی hot path ثبت مصرف. با شناسه عددی تنها، اون اسپلیت کلاً حذف می‌شه و هیچ اطلاعاتی هم گم نمی‌شه، چون ID به تنهایی کاربر رو یکتا شناسایی می‌کنه.

کی تحت تأثیره؟

اگه تو کانفیگ هسته xray‌ت روتینگ رول‌هایی داری که کاربرا رو با email مچ می‌کنن، این تغییر برات مهمه. این رول‌ها بعد از آپدیت، بی‌سروصدا از کار می‌افتن مگه اینکه آپدیتشون کنی.

چطور مایگریت کنیم؟

هر روتینگ رولی که به email کاربر ارجاع می‌ده رو به فرمت جدید (فقط ID عددی) آپدیت کن.

قبلاً:

{
  "type": "field",
  "user": ["42.john", "7.alice"],
  "outboundTag": "direct"
}

الان:

{
  "type": "field",
  "user": ["42", "7"],
  "outboundTag": "direct"
}

برای پیدا کردن ID کاربرا، پنل ادمین PasarGuard رو چک کن یا از API بپرس — ID عددی تو جزئیات هر کاربر نشون داده می‌شه.

یه نکته درباره آمار

آمار ترافیک per-user تو هسته (که از xray stats API می‌شه دیدش) هم الان فقط با ID عددی کی‌گذاری می‌شه. اگه ابزار خارجی داری که آمار خام هسته رو می‌خونه و کلید id.username رو پارس می‌کنه، آپدیتش کن که یه رشته عددی ساده انتظار داشته باشه.

---

[تغییر حیاتی] دسترسی اپراتورها به تمپلیت‌ها و گروه‌ها (RBAC)

چی عوض شد

تو نسخه ۴، همه ادمین‌ها — از جمله اپراتورها (که قبلاً is_sudo=false بودن) — می‌تونستن اندپوینت‌های کامل تمپلیت‌ها و گروه‌ها رو بخونن. با اومدن RBAC، اپراتورها الان فقط به نسخه‌های ساده‌ی این اندپوینت‌ها دسترسی دارن که فقط id و name برمی‌گردونن.

اندپوینت	Sudo (ادمین کل)	اپراتور
GET /api/user_templates	دسترسی کامل	بدون دسترسی
GET /api/user_templates/simple	دسترسی کامل	فقط id و name
GET /api/groups	دسترسی کامل	بدون دسترسی
GET /api/groups/simple	دسترسی کامل	فقط id و name

دسترسی sudo ادمین‌ها هیچ تغییری نکرده.

چرا؟

RBAC اومده که بشه کنترل دقیق‌تری داشت روی اینکه اپراتورها چی ببینن و چیکار کنن. نمایش صفحات کامل مدیریت تمپلیت و گروه به اپراتورها نه برای worflow‌شون لازم بود، نه چیز خوبی برای UI. اندپوینت‌های simple کافیه که اپراتورها موقع ساختن یا ویرایش کاربر، تمپلیت و گروه اساین کنن.

کی تحت تأثیره؟

اپراتورها (که قبلاً is_sudo=false بودن) و هر API client یا اسکریپتی که با توکن اپراتور GET /api/user_templates یا GET /api/groups رو صدا می‌زنه.

فرمت ریسپانس چطور فرق می‌کنه؟

نسخه ساده (/api/groups/simple) — برای اپراتورها:

[
  { "id": 1, "name": "Basic Plan" },
  { "id": 2, "name": "Premium Plan" }
]

اندپوینت کامل (/api/groups) — فقط sudo:

[
  {
    "id": 1,
    "name": "Basic Plan",
    "inbound_tags": [],
    "total_users": 10,
    "is_disabled": false
  }
]

همین pattern برای تمپلیت‌ها هم هست (GET /api/user_templates در مقابل GET /api/user_templates/simple).

چطور مایگریت کنیم؟

• فرانت‌اند / UI: کاری نیست — داشبورد خودش پرمیشن‌های جدید رو داره.
• API client‌هایی که با توکن اپراتور کار می‌کنن: اگه فقط می‌خوای لیست تمپلیت‌ها یا گروه‌ها رو بگیری، برو سراغ اندپوینت‌های simple. اگه به جزئیات کامل نیاز داری، از یه اکانت sudo ادمین استفاده کن.
• اینتگریشن‌های custom: هر اسکریپتی که با توکن اپراتور این اندپوینت‌ها رو صدا می‌زنه رو چک و آپدیت کن.

---

---

Руководство по миграции

[Критическое изменение] Изменение формата email пользователя в маршрутизации конфигурации ядра

Что изменилось

Изменился формат идентификатора, используемого для представления пользователей внутри ядра xray (отображается в поле email):

	Формат	Пример
До	{id}.{username}	42.john
После	{id}	42

Это затрагивает значение поля email во всей статистике на уровне пользователей и контекстах маршрутизации внутри ядра.

Почему

Старый формат id.username требовал разбивки строки по . при каждой обработке статистики использования, создавая лишнюю нагрузку на процессор в критическом пути записи использования. Использование только числового ID полностью устраняет эту разбивку без потери информации — ID в одиночку однозначно идентифицирует пользователя.

Кого это затрагивает

Вы попадаете под это изменение, если в конфигурации ядра xray есть правила маршрутизации, сопоставляющие пользователей по email. После обновления эти правила перестанут работать без каких-либо ошибок, если их не обновить.

Как мигрировать

Обновите все правила маршрутизации, ссылающиеся на email пользователей, до нового формата с числовым ID.

До:

{
  "type": "field",
  "user": ["42.john", "7.alice"],
  "outboundTag": "direct"
}

После:

{
  "type": "field",
  "user": ["42", "7"],
  "outboundTag": "direct"
}

Чтобы узнать ID пользователей, проверьте панель администратора PasarGuard или запросите API — числовой ID отображается на странице сведений о каждом пользователе.

Примечание о статистике

Статистика трафика по пользователям в ядре (доступная через xray stats API) теперь также индексируется только по числовому ID. Если у вас есть внешние инструменты, которые читают сырую статистику ядра и разбирают формат ключа id.username, обновите их для работы с обычной числовой строкой.

---

[Критическое изменение] Доступ операторов-администраторов к шаблонам и группам (RBAC)

Что изменилось

В версии 4 все администраторы — включая операторов (ранее is_sudo=false) — могли читать полные эндпоинты шаблонов и групп. С введением RBAC операторы-администраторы теперь имеют доступ только к облегчённым «простым» вариантам этих эндпоинтов, возвращающим только id и name.

Эндпоинт	Sudo (Администратор)	Оператор
GET /api/user_templates	полный доступ	нет доступа
GET /api/user_templates/simple	полный доступ	только id и name
GET /api/groups	полный доступ	нет доступа
GET /api/groups/simple	полный доступ	только id и name

Доступ sudo-администраторов не изменился.

Почему

RBAC реализован для тонкого управления тем, что операторы-администраторы могут видеть и делать. Предоставление операторам полных страниц управления шаблонами и группами было излишним для их рабочего процесса и загромождало интерфейс. Простые эндпоинты достаточны для того, чтобы операторы могли назначать шаблоны и группы при создании или редактировании пользователей.

Кого это затрагивает

Операторов-администраторов (ранее is_sudo=false) и любые внешние API-клиенты или скрипты, которые обращаются к полным эндпоинтам GET /api/user_templates или GET /api/groups с учётными данными оператора.

Сравнение форматов ответа

Простой вариант (/api/groups/simple) — доступен операторам:

[
  { "id": 1, "name": "Basic Plan" },
  { "id": 2, "name": "Premium Plan" }
]

Полный эндпоинт (/api/groups) — только sudo:

[
  {
    "id": 1,
    "name": "Basic Plan",
    "inbound_tags": [],
    "total_users": 10,
    "is_disabled": false
  }
]

Та же схема применяется к шаблонам пользователей (GET /api/user_templates против GET /api/user_templates/simple).

Как мигрировать

• Фронтенд / UI: Никаких действий не требуется — панель управления уже отражает новые права доступа.
• API-клиенты с учётными данными оператора: Если вам нужен только список доступных шаблонов или групп для выбора, переключитесь с полных эндпоинтов на простые варианты. Если нужны полные данные, используйте sudo-аккаунт администратора.
• Кастомные интеграции: Проверьте все скрипты, обращающиеся к этим эндпоинтам с операторскими токенами, и обновите их соответствующим образом.

---

---

迁移指南

[破坏性变更] 核心配置路由中用户 email 格式变更

变更内容

xray 核心内部用于表示用户的标识符（通过 email 字段暴露）格式已发生变化：

	格式	示例
变更前	{id}.{username}	42.john
变更后	{id}	42

此变更影响核心内所有用户级统计和路由上下文中 email 字段的值。

原因

旧的 id.username 格式在每次处理使用量统计时都需要按 . 分割字符串，在使用记录任务的热路径上增加了不必要的 CPU 开销。仅使用数字 ID 可完全消除此分割操作，且不损失任何信息——ID 本身就能唯一标识一个用户。

影响范围

如果您的 xray 核心配置中包含按 email 匹配用户的路由规则，则会受到此变更影响。除非更新，否则这些规则在变更后将静默停止匹配。

迁移方式

将所有引用用户 email 的路由规则更新为新的纯数字 ID 格式。

变更前：

{
  "type": "field",
  "user": ["42.john", "7.alice"],
  "outboundTag": "direct"
}

变更后：

{
  "type": "field",
  "user": ["42", "7"],
  "outboundTag": "direct"
}

如需查找用户 ID，请查看 PasarGuard 管理面板或通过 API 查询——每个用户的详情页均会显示其数字 ID。

关于统计数据的说明

核心中按用户划分的流量统计（可通过 xray stats API 查看）现在同样仅以数字 ID 作为键。如果您有读取原始核心统计并解析 id.username 键格式的外部工具，请将其更新为使用纯数字字符串。

---

[破坏性变更] 操作员管理员对模板和分组的访问权限（RBAC）

变更内容

在第 4 版中，所有管理员——包括操作员（原 is_sudo=false）——均可读取完整的模板和分组接口。随着 RBAC 的引入，操作员管理员现在只能访问这些接口的轻量"简单"变体，该变体仅返回 id 和 name。

接口	Sudo（超级管理员）	操作员
GET /api/user_templates	完整读取	无权限
GET /api/user_templates/simple	完整读取	仅 id 和 name
GET /api/groups	完整读取	无权限
GET /api/groups/simple	完整读取	仅 id 和 name

Sudo 管理员的访问权限保持不变。

原因

RBAC 的引入是为了对操作员管理员的可见范围和操作权限进行精细控制。向操作员暴露完整的模板和分组管理页面对其工作流程而言并无必要，反而使前端界面更加混乱。简单接口足以支持操作员在创建或编辑用户时分配模板和分组。

影响范围

操作员管理员（原 is_sudo=false）以及任何使用操作员凭据调用完整 GET /api/user_templates 或 GET /api/groups 接口的外部 API 客户端或脚本。

响应格式对比

简单变体（/api/groups/simple）——操作员可用：

[
  { "id": 1, "name": "Basic Plan" },
  { "id": 2, "name": "Premium Plan" }
]

完整接口（/api/groups）——仅限 sudo：

[
  {
    "id": 1,
    "name": "Basic Plan",
    "inbound_tags": [],
    "total_users": 10,
    "is_disabled": false
  }
]

同样的规则适用于用户模板（GET /api/user_templates 对比 GET /api/user_templates/simple）。

迁移方式

• 前端 / UI：无需任何操作——管理面板已体现新权限。
• 使用操作员凭据的 API 客户端：如果仅需列出可用模板或分组供选择，请从完整接口切换至简单变体。如需完整详情，请改用 sudo 管理员账户。
• 自定义集成：检查所有使用操作员令牌调用这些接口的脚本，并相应更新。