مستندات پیکربندی XRay

این سند نحوه اعتبارسنجی و پردازش فایل‌های پیکربندی XRay توسط PasarGuard را توضیح می‌دهد. این سند برای کمک به مبتدیان در درک فرآیند اعتبارسنجی، مقادیر پیش‌فرض و محدودیت‌های API طراحی شده است.

فهرست مطالب

1. نمای کلی
2. اعتبارسنجی پیکربندی
3. مقادیر پیش‌فرض
4. پروتکل‌های پشتیبانی شده
5. انواع شبکه
6. تنظیمات امنیتی
7. مشاهده IPهای متصل
8. محدودیت‌ها و قیود API
9. خطاهای رایج اعتبارسنجی

نمای کلی

کلاس XRayConfig مسئول موارد زیر است:

• اعتبارسنجی فایل‌های JSON پیکربندی XRay
• استخراج مقادیر پیش‌فرض از پیکربندی
• پردازش تنظیمات ورودی و خروجی
• مدیریت پیکربندی‌های خاص مانند fallback و TLS/Reality

اعتبارسنجی پیکربندی

فیلدهای الزامی

پیکربندی XRay شما باید شامل موارد زیر باشد:

1. inbounds - آرایه‌ای از پیکربندی‌های ورودی

   • نمی‌تواند خالی یا مفقود باشد
   • هر inbound باید یک tag منحصر به فرد داشته باشد
   • هر inbound باید یک فیلد protocol داشته باشد

2. outbounds - آرایه‌ای از پیکربندی‌های خروجی

   • نمی‌تواند خالی یا مفقود باشد
   • هر outbound باید یک tag منحصر به فرد داشته باشد

قوانین تگ‌های ورودی

تگ‌های ورودی قوانین سخت‌گیرانه‌ای دارند:

• ✅ باید منحصر به فرد باشند - هیچ دو inbound نمی‌توانند تگ یکسانی داشته باشند
• ✅ باید وجود داشته باشند - هر inbound نیاز به یک تگ دارد
• ❌ نمی‌توانند شامل کاما (,) باشند - کاراکتر , مجاز نیست
• ❌ نمی‌توانند شامل <=> باشند - این دنباله برای مدیریت fallback رزرو شده است

{
  "inbounds": [
    {
      "tag": "vless-ws-443",
      "port": 443,
      "protocol": "vless"
    },
    {
      "tag": "trojan-tls-8443",
      "port": 8443,
      "protocol": "trojan"
    },
    {
      "tag": "vmess-grpc",
      "port": 443,
      "protocol": "vmess"
    }
  ]
}

{
  "inbounds": [
    {
      "tag": "inbound,fallback",  // ❌ شامل کاما است
      "port": 443,
      "protocol": "vless"
    },
    {
      "tag": "inbound<=>fallback",  // ❌ شامل <=> است
      "port": 8443,
      "protocol": "trojan"
    }
  ]
}

الزامات پورت

اکثر inboundها باید یک فیلد port داشته باشند. تنها استثنا زمانی است که:

• inbound به عنوان مقصد fallback استفاده می‌شود (ارجاع داده شده توسط تنظیمات fallback inbound دیگر)
• inbound خودش یک آرایه fallbacks در تنظیمات دارد

مثال:

{
  "tag": "main-inbound",
  "port": 443,  // ✅ برای اکثر inboundها الزامی است
  "protocol": "vless"
}

مقادیر پیش‌فرض

هنگام پردازش پیکربندی شما، PasarGuard مقادیر پیش‌فرض را برای تنظیمات مختلف استخراج و تنظیم می‌کند. در ادامه آنچه به طور خودکار تنظیم می‌شود آمده است:

تنظیمات پایه (همه Inboundها)

این مقادیر پیش‌فرض برای هر inbound اعمال می‌شود:

مقادیر پیش‌فرض خاص پروتکل

پروتکل‌های پشتیبانی شده

PasarGuard این پروتکل‌ها را پردازش و اعتبارسنجی می‌کند:

1. Vmess
2. Vless
3. Trojan
4. Shadowsocks

انواع شبکه

انواع شبکه/انتقال زیر پشتیبانی می‌شوند:

قوانین خاص شبکه

{
  "streamSettings": {
    "network": "tcp",
    "tcpSettings": {
      "header": {
        "type": "http",
        "request": {
          "path": ["/path"],  // ✅ آرایه
          "headers": {
            "Host": ["example.com"]  // ✅ آرایه
          }
        }
      }
    }
  }
}

{
  "streamSettings": {
    "network": "ws",
    "wsSettings": {
      "path": "/path",  // ✅ رشته
      "host": "example.com"  // ✅ رشته
    }
  }
}

{
  "streamSettings": {
    "network": "grpc",
    "grpcSettings": {
      "serviceName": "my-service",  // به عنوان path استفاده می‌شود
      "authority": "example.com"     // به عنوان host استفاده می‌شود
    }
  }
}

تنظیمات امنیتی

{
  "streamSettings": {
    "security": "tls",
    "tlsSettings": {
      "certificates": [{
        "certificateFile": "/path/to/cert.pem",
        "keyFile": "/path/to/key.pem"
      }]
    }
  }
}

{
  "streamSettings": {
    "security": "reality",
    "realitySettings": {
      "serverNames": ["example.com"],
      "privateKey": "your-private-key-here",
      "shortIds": [""]
    }
  }
}

مشاهده IPهای متصل

شما می‌توانید ردیابی آمار آنلاین کاربران را فعال کنید تا آخرین آدرس‌های IP متصل به هسته خود را مشاهده کنید. این ویژگی به شما امکان می‌دهد که IPهای در حال حاضر متصل به هسته XRay خود را نظارت کنید.

فعال‌سازی آمار آنلاین کاربران

برای فعال‌سازی این ویژگی، باید یک بخش policy به ریشه فایل JSON پیکربندی XRay خود اضافه کنید. پیکربندی زیر را اضافه کنید:

{
  "policy": {
    "levels": {
      "0": {
        "statsUserOnline": true
      }
    }
  },
  "inbounds": [
    // ... پیکربندی‌های inbound شما
  ],
  "outbounds": [
    // ... پیکربندی‌های outbound شما
  ]
}

مشاهده IPهای متصل

پس از فعال‌سازی policy statsUserOnline و راه‌اندازی مجدد نود شما:

1. نیاز به اولین اتصال: ردیابی IP پس از برقراری اولین اتصال کاربر شروع به کار می‌کند
2. دسترسی به آمار: پس از فعال‌سازی و بعد از اولین اتصال، می‌توانید آخرین IPهای متصل را از طریق رابط آمار پنل خود مشاهده کنید

مثال کامل

در اینجا یک مثال کامل از پیکربندی با بخش policy فعال شده آورده شده است:

{
  "policy": {
    "levels": {
      "0": {
        "statsUserOnline": true
      }
    }
  },
  "inbounds": [
    {
      "tag": "vless-ws-443",
      "port": 443,
      "protocol": "vless",
      "settings": {
        "clients": []
      },
      "streamSettings": {
        "network": "ws",
        "wsSettings": {
          "path": "/path"
        }
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom"
    }
  ]
}

محدودیت‌ها و قیود API

هنگام ایجاد یا تغییر پیکربندی‌های هسته از طریق API، این محدودیت‌ها اعمال می‌شوند:

محدودیت‌های فیلد

قوانین خاص

1. محافظت هسته پیش‌فرض

   • پیکربندی هسته با id = 1 نمی‌تواند حذف شود
   • این پیکربندی پیش‌فرض/سیستمی هسته است

2. طول رشته تگ

   • وقتی exclude_inbound_tags و fallbacks_inbound_tags به یک رشته جدا شده با کاما ترکیب می‌شوند، طول کل نباید از 2048 کاراکتر تجاوز کند
   • مثال: اگر 100 تگ با 20 کاراکتر هر کدام داشته باشید، این 2000 کاراکتر است (به علاوه 99 کاما = 2099) که از محدودیت تجاوز می‌کند

3. اعتبارسنجی پیکربندی

   • دیکشنری config نمی‌تواند خالی {} باشد
   • باید تمام قوانین اعتبارسنجی XRay را پاس کند (inbounds، outbounds، تگ‌ها و غیره)

نقاط پایانی API

نقاط پایانی زیر برای مدیریت پیکربندی هسته در دسترس هستند:

• POST /api/core - ایجاد پیکربندی هسته جدید
• GET /api/core/{core_id} - دریافت پیکربندی هسته با ID
• PUT /api/core/{core_id} - تغییر پیکربندی هسته موجود
• DELETE /api/core/{core_id} - حذف پیکربندی هسته (به جز id=1)
• GET /api/cores - لیست تمام پیکربندی‌های هسته
• POST /api/core/{core_id}/restart - راه‌اندازی مجدد نودهای استفاده‌کننده از این هسته

خطاهای رایج اعتبارسنجی

در ادامه خطاهای رایجی که ممکن است با آن‌ها مواجه شوید و نحوه رفع آن‌ها آمده است:

{
  "inbounds": [
    {
      "tag": "my-inbound",
      "port": 443,
      "protocol": "vless"
    }
  ],
  "outbounds": []
}

{
  "inbounds": [
    {"tag": "inbound-1", "port": 443, "protocol": "vless"},
    {"tag": "inbound-2", "port": 8443, "protocol": "trojan"}  // ✅ تگ متفاوت
  ]
}

{
  "inbounds": [
    {
      "tag": "inbound,fallback",  // ❌ نامعتبر
      "port": 443,
      "protocol": "vless"
    },
    {
      "tag": "inbound-fallback",  // ✅ معتبر
      "port": 443,
      "protocol": "vless"
    }
  ]
}

{
  "tag": "my-inbound",
  "port": 443,  // ✅ این را اضافه کنید
  "protocol": "vless"
}

{
  "protocol": "shadowsocks",
  "settings": {
    "method": "2022-blake3-aes-128-gcm"  // ✅ پشتیبانی می‌شود
    // "method": "2022-blake3-chacha20-poly1305"  // ❌ پشتیبانی نمی‌شود
  }
}

{
  "settings": {
    "method": "2022-blake3-aes-128-gcm",
    "password": "base64-encoded-password-here"  // ✅ باید base64 باشد
  }
}

{
  "streamSettings": {
    "security": "reality",
    "realitySettings": {
      "privateKey": "your-private-key-here",  // ✅ الزامی
      "shortIds": [""],
      "serverNames": ["example.com"]
    }
  }
}

{
  "realitySettings": {
    "shortIds": [""],  // ✅ حداقل یک عنصر (می‌تواند رشته خالی باشد)
    // "shortIds": []  // ❌ آرایه خالی مجاز نیست
  }
}

{
  "streamSettings": {
    "network": "tcp",
    "tcpSettings": {
      "header": {
        "type": "http",
        "request": {
          "path": ["/path"],  // ✅ آرایه، نه رشته
          "headers": {
            "Host": ["example.com"]  // ✅ آرایه، نه رشته
          }
        }
      }
    }
  }
}

{
  "streamSettings": {
    "network": "ws",
    "wsSettings": {
      "path": "/path",  // ✅ رشته، نه آرایه
      "host": "example.com"  // ✅ رشته، نه آرایه
    }
  }
}

خلاصه

برای اطلاعات بیشتر در مورد فرمت پیکربندی XRay، به XRay مستندات رسمی مراجعه کنید.