介绍

外观

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
    
    "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
    
    "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

    // 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": "",  // 混淆密码
    
    "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
    
    // 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": ""      // 自定义报错信息
}