> For the complete documentation index, see [llms.txt](https://soga.yougotme.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://soga.yougotme.cc/doc/soga-v1-webapi-kai-fa-wen-dang.md). # soga v1 webapi 开发文档 ## 介绍 `soga-v1`面板类型是 soga`v2.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-KEY | soga 配置中的`webapi_key`，用于面板验证 webapi 请求 | | NODE-ID | 节点 id | | NODE-TYPE | 节点类型: `vmess` `vless` `shadowsocks` `shadowsocksr` `trojan` `hysteria` `anytls` | | IF-NONE-MATCH | `GET`接口有效，如果 webapi 返回头中有 ETAG 数据，则下次请求会带上此请求头，以此节省 webapi 产生的流量，面板需正确实现 [ETAG](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag) | {% hint style="warning" %} 以下接口为必须实现的接口，访问若返回 404 则会导致 soga 无法正常工作 {% endhint %} ### 获取节点信息`GET /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 "path": "/path", // simple_obfs_http 混淆可设置 "host": "www.server.com" // simple_obfs_http 混淆可设置 } } ``` **`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, // 监听端口 "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 /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 /api/v1/audit_rules` > 每个字符串为一个审计规则，具体格式参考 soga 文档 #### 返回数据 ```json [ { "id": 1, // 审计规则 id，用于提交用户触发审计时使用 "rule": "google" // 审计规则 }, { "id": 2, "rule": "regexp:.*google\.com" } ] ``` ### 获取审计白名单`GET /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 /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 /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 /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 /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": "" // 自定义报错信息 } ```