介紹

繁體中文

English
简体中文
العربية

繁體中文

English
简体中文
العربية

外觀

soga-v1 webapi 開發文件 ​

介紹 ​

soga-v1面板類型是 sogav2.12.3+自訂的一系列 webapi 介面，可根據以下介面文件在自己的面板上進行開發，在 soga 設定中設定type=soga-v1即可使用此 webapi 介面

webapi_url 設定 ​

可自訂你的webapi_url路徑，soga 授權碼將會繫結此webapi_url完整路徑，soga 存取 webapi 介面時也會自動拼接webapi_url路徑與介面 uri，例如https://www.website.com/your/custom/uri/api/v1/node

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

介面 ​

所有介面均使用json格式傳遞資料

每個介面均會傳送請求標頭，請求標頭的資訊如下

Key說明
API-KEYsoga 設定中的webapi_key，用於面板驗證 webapi 請求
NODE-ID節點 id
NODE-TYPE節點類型: vmess vless shadowsocks shadowsocksr trojan hysteria anytls mieru
IF-NONE-MATCHGET介面有效，如果 webapi 回應標頭中有 ETAG 資料，則下次請求會帶上此請求標頭，以此節省 webapi 產生的流量，面板需正確實作 ETAG

注意

以下介面為必須實作的介面，存取若回傳 404 則會導致 soga 無法正常工作

取得節點資訊GET <webapi_url>/api/v1/node ​

回傳資料 ​

不同節點類型回傳的資料有所不同，根據節點類型回傳不同的資料格式

vmess節點類型

json
{
  "basic": { // 可省略
    "pull_interval": 60,            // 可省略，設定拉取資訊的時間間隔，單位秒
    "push_interval": 60,            // 可省略，設定推送資訊的時間間隔，單位秒
    "speed_limit": 0                // 可省略，設定節點總限速，單位 Mbps，0 表示不限制
  },
  "config": {
    "port": 12345,                  // 監聽埠
    "stream_type": "ws",            // 可選: tcp ws http h2 grpc
    "tls_type": "none",             // 可選: none tls
    "ech_key": "",                  // v2.17.1+，ECH 私鑰，tls 時生效，留空表示不開啟，可用 sing-box generate ech-keypair 生成
    
    "path": "/path",                // ws 協定時需要
    "service_name": "service_name"  // grpc 協定時需要
  }
}

trojan節點類型

json
{
  "basic": { // 可省略
    "pull_interval": 60,            // 可省略，設定拉取資訊的時間間隔，單位秒
    "push_interval": 60,            // 可省略，設定推送資訊的時間間隔，單位秒
    "speed_limit": 0                // 可省略，設定節點總限速，單位 Mbps，0 表示不限制
  },
  "config": {
    "port": 12345,                  // 監聽埠
    "stream_type": "ws",            // 可選: tcp ws http h2 grpc
    "ech_key": "",                  // v2.17.1+，ECH 私鑰，tls 時生效，留空表示不開啟，可用 sing-box generate ech-keypair 生成
    
    "path": "/path",                // ws 協定時需要
    "service_name": "service_name"  // grpc 協定時需要
  }
}

ss節點類型

json
{
  "basic": { // 可省略
    "pull_interval": 60,        // 可省略，設定拉取資訊的時間間隔，單位秒
    "push_interval": 60,        // 可省略，設定推送資訊的時間間隔，單位秒
    "speed_limit": 0            // 可省略，設定節點總限速，單位 Mbps，0 表示不限制
  },
  "config": {
    "port": 12345,              // 監聽埠
    "cipher": "aes-128-gcm",    // 具體參考 soga ss 支援的加密方式
    "password": "",             // 當加密方式為 ss2022 時需要節點密碼，格式為 base64
    "obfs": "plain",            // 可選: plain simple_obfs_http simple_obfs_tls
    
    "path": "/path",            // simple_obfs_http 混淆可設定
    "host": "www.server.com"    // simple_obfs_http、simple_obfs_tls 混淆可設定
  }
}

ssr節點類型

json
{
  "basic": { // 可省略
    "pull_interval": 60,        // 可省略，設定拉取資訊的時間間隔，單位秒
    "push_interval": 60,        // 可省略，設定推送資訊的時間間隔，單位秒
    "speed_limit": 0            // 可省略，設定節點總限速，單位 Mbps，0 表示不限制
  },
  "config": {
    "port": 12345,                  // 監聽埠
    "method": "chacha20-ietf",      // 具體參考 soga ssr 支援的加密
    "password": "asd",              // 密碼
    "protocol": "auth_chain_a",     // 具體參考 soga ssr 支援的協定
    "obfs": "http_simple",          // 具體參考 soga ssr 支援的混淆
    "single_port_type": "protocol"  // 可選: protocol obfs，分別表示協定單埠和混淆單埠
  }
}

vless節點類型

json
{
  "basic": { // 可省略
    "pull_interval": 60,              // 可省略，設定拉取資訊的時間間隔，單位秒
    "push_interval": 60,              // 可省略，設定推送資訊的時間間隔，單位秒
    "speed_limit": 0                  // 可省略，設定節點總限速，單位 Mbps，0 表示不限制
  },
  "config": {
    "port": 12345,                    // 監聽埠
    "stream_type": "tcp",             // 可選: tcp ws http h2 grpc xhttp
    "tls_type": "reality",            // 可選: none tls reality
    "ech_key": "",                    // v2.17.1+，ECH 私鑰，tls 時生效，留空表示不開啟，可用 sing-box generate ech-keypair 生成

    // reality 設定
    "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+，留空或 "none" 表示不使用 vless 加密，其他值表示 vless decryption 參數
    "decryption": "",

    "path": "/path",                   // ws 協定時需要
    "service_name": "service_name",    // grpc 協定時需要

    "xhttp_settings": {                // xhttp 設定，具體參考: 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": { // 可省略
    "pull_interval": 60,  // 可省略，設定拉取資訊的時間間隔，單位秒
    "push_interval": 60,  // 可省略，設定推送資訊的時間間隔，單位秒
    "speed_limit": 0      // 可省略，設定節點總限速，單位 Mbps，0 表示不限制
  },
  "config": {
    "port": 12345,        // 監聽埠
    "obfs": "salamander", // 可選: plain salamander
    "obfs_password": "",  // 混淆密碼
    "ech_key": "",        // v2.17.1+，ECH 私鑰，tls 時生效，留空表示不開啟，可用 sing-box generate ech-keypair 生成
    
    "up_mbps": 1000,      // 上傳頻寬，單位 Mbps，若上傳頻寬和下載頻寬都設定為 0 則使用 bbr
    "down_mbps": 1000     // 下載頻寬，單位 Mbps，若上傳頻寬和下載頻寬都設定為 0 則使用 bbr
  }
}

anytls節點類型

json
{
  "basic": { // 可省略
    "pull_interval": 60,  // 可省略，設定拉取資訊的時間間隔，單位秒
    "push_interval": 60,  // 可省略，設定推送資訊的時間間隔，單位秒
    "speed_limit": 0      // 可省略，設定節點總限速，單位 Mbps，0 表示不限制
  },
  "config": {
    "port": 12345,        // 監聽埠
    "tls_type": "tls",    // 可選: none tls reality
    "ech_key": "",        // v2.17.1+，ECH 私鑰，tls 時生效，留空表示不開啟，可用 sing-box generate ech-keypair 生成
    
    // reality 設定
    "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，留空保持預設
      "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": { // 可省略
    "pull_interval": 60,  // 可省略，設定拉取資訊的時間間隔，單位秒
    "push_interval": 60,  // 可省略，設定推送資訊的時間間隔，單位秒
    "speed_limit": 0      // 可省略，設定節點總限速，單位 Mbps，0 表示不限制
  },
  "config": {
    "port": 12345,           // 監聽埠
    "transport": "TCP"       // 傳輸協定，目前僅支援 TCP
  }
}

取得使用者資訊GET <webapi_url>/api/v1/users ​

回傳資料 ​

不同節點類型回傳的資料有所不同，根據節點類型回傳不同的資料格式

vmess vless節點類型

json
[
  {
    "id": 1,                
    "uuid": "701534e1-8540-49f3-87af-71680a1b97ff",
    "speed_limit": 0,                                   // 使用者限速，單位 Mbps，0 表示不限制
    "device_limit": 0,                                  // 使用者 IP 數限制，0 表示不限制
    "tcp_limit": 0                                      // 使用者 tcp 連線限制，0 表示不限制
  },
  {
    "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,                                   // 使用者限速，單位 Mbps，0 表示不限制
    "device_limit": 0,                                  // 使用者 IP 數限制，0 表示不限制
    "tcp_limit": 0                                      // 使用者 tcp 連線限制，0 表示不限制
  },
  {
    "id": 2,                
    "password": "password2",
    "speed_limit": 0,
    "device_limit": 0,
    "tcp_limit": 0
  }
]

mieru 節點類型

json
[
  {
    "id": 1,
    "username": "username1",                            // mieru 使用者名稱
    "password": "password1",                            // mieru 密碼
    "speed_limit": 0,                                   // 使用者限速，單位 Mbps，0 表示不限制
    "device_limit": 0,                                  // 使用者 IP 數限制，0 表示不限制
    "tcp_limit": 0                                      // 使用者 tcp 連線限制，0 表示不限制
  },
  {
    "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,              // 審計規則 id，用於提交使用者觸發審計時使用
    "rule": "google"      // 審計規則
  },
  {
    "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,         // 使用者 id
    "u": 1024,       // 上傳流量，單位位元組
    "d": 1024        // 下載流量，單位位元組
  },
  {
    "id": 2,         // 使用者 id
    "u": 1024,       // 上傳流量，單位位元組
    "d": 1024        // 下載流量，單位位元組
  }
]

回傳資料 ​

json
{
  "code": 0,         // 0 表示成功，其他數值表示失敗
  "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 表示成功，其他數值表示失敗
  "message": ""      // 自訂錯誤訊息
}

提交使用者審計 POST <webapi_url>/api/v1/audit_log ​

同一使用者多次觸發同一審計規則時，只記錄一次

提交資料 ​

json
[
  {
    "user_id": 1,      // 使用者 id
    "audit_id": 2      // 觸發的審計規則 id
  },
  {
    "user_id": 1,
    "audit_id": 3
  },
  {
    "user_id": 2,
    "audit_id": 2
  }
]

回傳資料 ​

json
{
  "code": 0,         // 0 表示成功，其他數值表示失敗
  "message": ""      // 自訂錯誤訊息
}

提交節點狀態 POST <webapi_url>/api/v1/status ​

提交資料 ​

json
{
  "cpu": 23.5,               // 上次提交至本次提交的 CPU 平均使用率
  "mem": {
    "total": 1073741824,     // 目前記憶體總量，單位位元組
    "used": 536870912        // 目前記憶體使用量，單位位元組
  },
  "swap": {
    "total": 1073741824,     // 目前交換區總量，單位位元組
    "used": 536870912        // 目前交換區使用量，單位位元組
  },
  "disk": {
    "total": 1073741824,     // 目前磁碟總量，單位位元組
    "used": 536870912        // 目前磁碟使用量，單位位元組
  },
  "uptime": 123456           // 系統已執行時間，秒
}

回傳資料 ​

json
{
  "code": 0,         // 0 表示成功，其他數值表示失敗
  "message": ""      // 自訂錯誤訊息
}