مقدمة

العربية

English
简体中文
繁體中文

العربية

English
简体中文
繁體中文

المظهر

وثائق تطوير soga-v1 webapi ​

مقدمة ​

نوع اللوحة soga-v1 هو مجموعة من واجهات webapi المخصّصة التي تعرّفها soga v2.12.3+، ويمكنك تطويرها في لوحتك الخاصة وفق وثائق الواجهات التالية، ثم ضبط type=soga-v1 في إعدادات soga لاستخدام واجهة webapi هذه

إعداد webapi_url ​

يمكنك تخصيص مسار webapi_url، وسيرتبط رمز ترخيص soga بالمسار الكامل لـ webapi_url هذا، كما تدمج soga تلقائيًا مسار webapi_url مع uri الواجهة عند الوصول إلى واجهات webapi، مثل https://www.website.com/your/custom/uri/api/v1/node

webapi_url=https://www.website.com/your/custom/uri/

الواجهات ​

جميع الواجهات تنقل البيانات بتنسيق json

كل واجهة ترسل ترويسات الطلب، وفيما يلي معلومات ترويسات الطلب

Keyالوصف
API-KEYقيمة webapi_key في إعدادات soga، وتستخدمها اللوحة للتحقق من طلبات webapi
NODE-IDمعرّف العقدة
NODE-TYPEنوع العقدة: vmess vless shadowsocks shadowsocksr trojan hysteria anytls mieru
IF-NONE-MATCHتسري على واجهات GET، فإذا تضمّنت ترويسات استجابة webapi بيانات ETAG، فسيحمل الطلب التالي هذه الترويسة، لتقليل حركة البيانات الناتجة عن webapi، ويجب على اللوحة تنفيذ ETAG بشكل صحيح

تنبيه

الواجهات التالية إلزامية التنفيذ، وإذا أعاد الوصول إليها 404 فلن تعمل soga بشكل طبيعي

الحصول على معلومات العقدة GET <webapi_url>/api/v1/node ​

البيانات المُعادة ​

تختلف البيانات المُعادة باختلاف نوع العقدة، فأعد تنسيق البيانات المطابق لنوع العقدة

نوع العقدة vmess

json
{
  "basic": { // optional
    "pull_interval": 60,            // optional, interval for pulling data, in seconds
    "push_interval": 60,            // optional, interval for pushing data, in seconds
    "speed_limit": 0                // optional, total speed limit for the node, in Mbps, 0 means unlimited
  },
  "config": {
    "port": 12345,                  // listening port
    "stream_type": "ws",            // options: tcp ws http h2 grpc
    "tls_type": "none",             // options: none tls
    "ech_key": "",                  // v2.17.1+, ECH private key, applies when tls is used, leave empty to disable, can be generated with sing-box generate ech-keypair
    
    "path": "/path",                // required for ws
    "service_name": "service_name"  // required for grpc
  }
}

نوع العقدة trojan

json
{
  "basic": { // optional
    "pull_interval": 60,            // optional, interval for pulling data, in seconds
    "push_interval": 60,            // optional, interval for pushing data, in seconds
    "speed_limit": 0                // optional, total speed limit for the node, in Mbps, 0 means unlimited
  },
  "config": {
    "port": 12345,                  // listening port
    "stream_type": "ws",            // options: tcp ws http h2 grpc
    "ech_key": "",                  // v2.17.1+, ECH private key, applies when tls is used, leave empty to disable, can be generated with sing-box generate ech-keypair
    
    "path": "/path",                // required for ws
    "service_name": "service_name"  // required for grpc
  }
}

نوع العقدة ss

json
{
  "basic": { // optional
    "pull_interval": 60,        // optional, interval for pulling data, in seconds
    "push_interval": 60,        // optional, interval for pushing data, in seconds
    "speed_limit": 0            // optional, total speed limit for the node, in Mbps, 0 means unlimited
  },
  "config": {
    "port": 12345,              // listening port
    "cipher": "aes-128-gcm",    // see the ciphers supported by soga ss
    "password": "",             // node password required when the cipher is ss2022, base64 encoded
    "obfs": "plain",            // options: plain simple_obfs_http simple_obfs_tls
    
    "path": "/path",            // optional for simple_obfs_http obfuscation
    "host": "www.server.com"    // optional for simple_obfs_http and simple_obfs_tls obfuscation
  }
}

نوع العقدة ssr

json
{
  "basic": { // optional
    "pull_interval": 60,        // optional, interval for pulling data, in seconds
    "push_interval": 60,        // optional, interval for pushing data, in seconds
    "speed_limit": 0            // optional, total speed limit for the node, in Mbps, 0 means unlimited
  },
  "config": {
    "port": 12345,                  // listening port
    "method": "chacha20-ietf",      // see the ciphers supported by soga ssr
    "password": "asd",              // password
    "protocol": "auth_chain_a",     // see the protocols supported by soga ssr
    "obfs": "http_simple",          // see the obfuscation methods supported by soga ssr
    "single_port_type": "protocol"  // options: protocol obfs, meaning protocol single port and obfs single port respectively
  }
}

نوع العقدة vless

json
{
  "basic": { // optional
    "pull_interval": 60,              // optional, interval for pulling data, in seconds
    "push_interval": 60,              // optional, interval for pushing data, in seconds
    "speed_limit": 0                  // optional, total speed limit for the node, in Mbps, 0 means unlimited
  },
  "config": {
    "port": 12345,                    // listening port
    "stream_type": "tcp",             // options: tcp ws http h2 grpc xhttp
    "tls_type": "reality",            // options: none tls reality
    "ech_key": "",                    // v2.17.1+, ECH private key, applies when tls is used, leave empty to disable, can be generated with sing-box generate ech-keypair

    // reality settings
    "flow": "xtls-rprx-vision",
    "server_names": ["www.server1.com", "www.server2.com"],
    "private_key": "",
    "short_ids": ["1234567890123456", "1234567890123456"],
    "dest": "www.server.com:443",
    
    // v2.13.7+, empty or "none" disables vless encryption, any other value is used as the vless decryption parameter
    "decryption": "",

    "path": "/path",                   // required for ws
    "service_name": "service_name",    // required for grpc

    "xhttp_settings": {                // xhttp settings, see: https://github.com/XTLS/Xray-core/discussions/4113
      "host": "example.com",
      "path": "/yourpath",
      "mode": "auto",
      "extra": {
        "headers": {
          // "key": "value"
        },
        "xPaddingBytes": "100-1000",
        "noSSEHeader": false,
        "scMaxEachPostBytes": 1000000,
        "scMaxBufferedPosts": 30,
        "scStreamUpServerSecs": "20-80"
      }
    }
  }
}

نوع العقدة hysteria

json
{
  "basic": { // optional
    "pull_interval": 60,  // optional, interval for pulling data, in seconds
    "push_interval": 60,  // optional, interval for pushing data, in seconds
    "speed_limit": 0      // optional, total speed limit for the node, in Mbps, 0 means unlimited
  },
  "config": {
    "port": 12345,        // listening port
    "obfs": "salamander", // options: plain salamander
    "obfs_password": "",  // obfuscation password
    "ech_key": "",        // v2.17.1+, ECH private key, applies when tls is used, leave empty to disable, can be generated with sing-box generate ech-keypair
    
    "up_mbps": 1000,      // upload bandwidth, in Mbps, bbr is used if both upload and download bandwidth are 0
    "down_mbps": 1000     // download bandwidth, in Mbps, bbr is used if both upload and download bandwidth are 0
  }
}

نوع العقدة anytls

json
{
  "basic": { // optional
    "pull_interval": 60,  // optional, interval for pulling data, in seconds
    "push_interval": 60,  // optional, interval for pushing data, in seconds
    "speed_limit": 0      // optional, total speed limit for the node, in Mbps, 0 means unlimited
  },
  "config": {
    "port": 12345,        // listening port
    "tls_type": "tls",    // options: none tls reality
    "ech_key": "",        // v2.17.1+, ECH private key, applies when tls is used, leave empty to disable, can be generated with sing-box generate ech-keypair
    
    // reality settings
    "flow": "xtls-rprx-vision",
    "server_names": ["www.server1.com", "www.server2.com"],
    "private_key": "",
    "short_ids": ["1234567890123456", "1234567890123456"],
    "dest": "www.server.com:443",
    
    "padding_scheme": [   // paddingScheme, leave empty to use the default
      "stop=8",
      "0=30-30",
      "1=100-400",
      "2=400-500,c,500-1000,c,500-1000,c,500-1000,c,500-1000",
      "3=9-9,500-1000",
      "4=500-1000",
      "5=500-1000",
      "6=500-1000",
      "7=500-1000"
    ]
  }
}

نوع العقدة mieru

json
{
  "basic": { // optional
    "pull_interval": 60,  // optional, interval for pulling data, in seconds
    "push_interval": 60,  // optional, interval for pushing data, in seconds
    "speed_limit": 0      // optional, total speed limit for the node, in Mbps, 0 means unlimited
  },
  "config": {
    "port": 12345,           // listening port
    "transport": "TCP"       // transport protocol, only TCP is supported for now
  }
}

الحصول على معلومات المستخدمين GET <webapi_url>/api/v1/users ​

البيانات المُعادة ​

تختلف البيانات المُعادة باختلاف نوع العقدة، فأعد تنسيق البيانات المطابق لنوع العقدة

نوعا العقدة vmess vless

json
[
  {
    "id": 1,                
    "uuid": "701534e1-8540-49f3-87af-71680a1b97ff",
    "speed_limit": 0,                                   // user speed limit, in Mbps, 0 means unlimited
    "device_limit": 0,                                  // user IP limit, 0 means unlimited
    "tcp_limit": 0                                      // user tcp connection limit, 0 means unlimited
  },
  {
    "id": 2,
    "uuid": "247862fd-1490-447d-8cec-971f756f1424",
    "speed_limit": 0,
    "device_limit": 0,
    "tcp_limit": 0
  }
]

أنواع العقدة trojan ss hysteria ssr anytls

json
[
  {
    "id": 1,                
    "password": "password1",
    "speed_limit": 0,                                   // user speed limit, in Mbps, 0 means unlimited
    "device_limit": 0,                                  // user IP limit, 0 means unlimited
    "tcp_limit": 0                                      // user tcp connection limit, 0 means unlimited
  },
  {
    "id": 2,                
    "password": "password2",
    "speed_limit": 0,
    "device_limit": 0,
    "tcp_limit": 0
  }
]

نوع العقدة mieru

json
[
  {
    "id": 1,
    "username": "username1",                            // mieru username
    "password": "password1",                            // mieru password
    "speed_limit": 0,                                   // user speed limit, in Mbps, 0 means unlimited
    "device_limit": 0,                                  // user IP limit, 0 means unlimited
    "tcp_limit": 0                                      // user tcp connection limit, 0 means unlimited
  },
  {
    "id": 2,
    "username": "username2",
    "password": "password2",
    "speed_limit": 0,
    "device_limit": 0,
    "tcp_limit": 0
  }
]

الحصول على قواعد التدقيق GET <webapi_url>/api/v1/audit_rules ​

كل سلسلة نصية تمثّل قاعدة تدقيق واحدة، وللتنسيق التفصيلي راجع وثائق soga

البيانات المُعادة ​

json
[
  {
    "id": 1,              // audit rule id, used when reporting user audit events
    "rule": "google"      // audit rule
  },
  {
    "id": 2,
    "rule": "regexp:.*google\.com"
  }
]

الحصول على القائمة البيضاء للتدقيق GET <webapi_url>/api/v1/white_list ​

للتفاصيل راجع قواعد القائمة البيضاء في وثائق soga

تُدمج القائمة البيضاء للتدقيق التي تُجلب عبر هذه الواجهة تلقائيًا مع الملف المحلي whiteList

البيانات المُعادة ​

json
[
  "google",
  "regexp:.*google\.com",
  "domain:google.com",
  "full:google.com",
  "geosite:google",
  "ip:192.168.0.0/16",
  "geoip:cn",
  "port:1-1024,12345,23456"
]

إرسال حركة بيانات المستخدمين POST <webapi_url>/api/v1/traffic ​

البيانات المُرسلة ​

json
[
  {
    "id": 1,         // user id
    "u": 1024,       // upload traffic, in bytes
    "d": 1024        // download traffic, in bytes
  },
  {
    "id": 2,         // user id
    "u": 1024,       // upload traffic, in bytes
    "d": 1024        // download traffic, in bytes
  }
]

البيانات المُعادة ​

json
{
  "code": 0,         // 0 means success, any other value means failure
  "message": ""      // custom error message
}

إرسال عناوين IP المتصلة للمستخدمين POST <webapi_url>/api/v1/alive_ip ​

البيانات المُرسلة ​

json
[
  {
    "id": 1,
    "ips": ["1.2.3.4", "2.3.4.5"]
  },
  {
    "id": 2,
    "ips": ["3.4.5.6"]
  }
]

البيانات المُعادة ​

json
{
  "code": 0,         // 0 means success, any other value means failure
  "message": ""      // custom error message
}

إرسال سجلات تدقيق المستخدمين POST <webapi_url>/api/v1/audit_log ​

عندما يطابق المستخدم نفسه قاعدة التدقيق نفسها عدة مرات، تُسجَّل مرة واحدة فقط

البيانات المُرسلة ​

json
[
  {
    "user_id": 1,      // user id
    "audit_id": 2      // id of the triggered audit rule
  },
  {
    "user_id": 1,
    "audit_id": 3
  },
  {
    "user_id": 2,
    "audit_id": 2
  }
]

البيانات المُعادة ​

json
{
  "code": 0,         // 0 means success, any other value means failure
  "message": ""      // custom error message
}

إرسال حالة العقدة POST <webapi_url>/api/v1/status ​

البيانات المُرسلة ​

json
{
  "cpu": 23.5,               // average CPU usage since the last report
  "mem": {
    "total": 1073741824,     // total memory, in bytes
    "used": 536870912        // memory used, in bytes
  },
  "swap": {
    "total": 1073741824,     // total swap, in bytes
    "used": 536870912        // swap used, in bytes
  },
  "disk": {
    "total": 1073741824,     // total disk space, in bytes
    "used": 536870912        // disk space used, in bytes
  },
  "uptime": 123456           // system uptime, in seconds
}

البيانات المُعادة ​

json
{
  "code": 0,         // 0 means success, any other value means failure
  "message": ""      // custom error message
}