# 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" ] } } ``` ### 获取用户信息`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 } ] ``` ### 获取审计规则`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": "" // 自定义报错信息 } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://soga.yougotme.cc/doc/soga-v1-webapi-kai-fa-wen-dang.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.