# WebApi 基础部分

## 功能介绍

{% hint style="info" %}
**对应后端程序**

* 不同后端有其对应的链接；
* 其中对应后端程序分别：ss，ssr，v2ray，trojan;
* 正确链接也可通过访问 [Route ](https://github.com/ProxyPanel/ProxyPanel/blob/master/routes/api.php)文件获得；
  {% endhint %}

### 功能：CoreController

本章节重点为所有WebApi都会使用的通用方程内容：包含上报节点心跳信息，在线人数，用户流量使用情况，节点的审计规则获取与触发审计后的上报。

{% hint style="info" %}
新特性：所有的发送的Get请求数据都会在 header头部 带有**ETAG**属性，用与请求`header('IF-NONE-MATCH')` 进行对比减少重复信息交互。

```
$etag = sha1(json_encode($data))
```

{% endhint %}

### 注意

* 节点后端与面板使用的时间误差不应该超过5分钟，否则API授权验证失败；
* required 字段必须存在，后端可以多提供信息，但不能缺失required 字段，面板可以按需添加其他字段；

{% hint style="danger" %}
请求Header中推荐`Accept`填入`application/json` 以明确需要json放回
{% endhint %}

## 上报节点心跳信息

<mark style="color:green;">`POST`</mark> `https://api.proxypanel.ml/api/{后端}/v1/nodeStatus/:id`

后端周期性（每分钟）上传节点信息

#### Path Parameters

| Name                                 | Type   | Description           |
| ------------------------------------ | ------ | --------------------- |
| id<mark style="color:red;">\*</mark> | number | 节点ID：int(10) unsigned |

#### Headers

| Name                                        | Type   | Description           |
| ------------------------------------------- | ------ | --------------------- |
| key<mark style="color:red;">\*</mark>       | string | 由管理后台线路系统，线路授权处取得授权密钥 |
| timestamp<mark style="color:red;">\*</mark> | number | 每次请求的10位时间戳           |

#### Request Body

| Name                                     | Type   | Description  |
| ---------------------------------------- | ------ | ------------ |
| cpu<mark style="color:red;">\*</mark>    | string | cpu负载        |
| mem<mark style="color:red;">\*</mark>    | string | 内存负载         |
| net<mark style="color:red;">\*</mark>    | string | 网络负载         |
| disk<mark style="color:red;">\*</mark>   | string | 磁盘情况         |
| uptime<mark style="color:red;">\*</mark> | number | 后端存活时长（单位：秒） |

{% tabs %}
{% tab title="200 上报成功" %}

```
成功：
{
    "status": "success",
    "code": 200,
    "data": "",
    "message": "上报节点心跳信息成功"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity 信息缺失" %}

```
{
    "status": "fail",
    "code": 400,
    "data": "",
    "message": "上报节点心跳信息失败，请检查字段"
}
```

{% endtab %}
{% endtabs %}

#### 传入参数示例

```
{"cpu":"2%","mem":"36%","net":"1.5 GB\u2191-38 GB\u2193","disk":"4%","uptime":89582}
```

## 上报节点在线信息

<mark style="color:green;">`POST`</mark> `https://api.proxypanel.ml/api/{后端}/v1/nodeOnline/:id`

后端周期性（每分钟）上传节点在线信息

#### Path Parameters

| Name                                 | Type    | Description           |
| ------------------------------------ | ------- | --------------------- |
| id<mark style="color:red;">\*</mark> | integer | 节点ID：int(10) unsigned |

#### Headers

| Name                                        | Type    | Description           |
| ------------------------------------------- | ------- | --------------------- |
| key<mark style="color:red;">\*</mark>       | string  | 由管理后台线路系统，线路授权处取得授权密钥 |
| timestamp<mark style="color:red;">\*</mark> | integer | 每次请求的10位时间戳           |

#### Request Body

| Name                                  | Type    | Description |
| ------------------------------------- | ------- | ----------- |
| uid<mark style="color:red;">\*</mark> | integer | 用户ID        |
| ip<mark style="color:red;">\*</mark>  | string  | 在线IP        |

{% tabs %}
{% tab title="200: OK 上报成功" %}

```
{
    "status": "success",
    "code": 200,
    "data": "",
    "message": "上报节点在线情况成功"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity 信息缺失" %}

```
{
    "status": "fail",
    "code": 400,
    "data": "",
    "message": "上报节点在线情况失败，请检查字段"
}
```

{% endtab %}
{% endtabs %}

#### 传入参数示例

```
[{"uid":14,"ip":"111.203.198.58,223.104.3.237,223.104.3.245"},{"uid":1,"ip":"117.30.139.216"}]
```

## 上报用户流量日志

<mark style="color:green;">`POST`</mark> `https://api.proxypanel.ml/api/{后端}/v1/userTraffic/:id`

后端周期性（每分钟）上传用户流量日志

#### Path Parameters

| Name                                 | Type    | Description           |
| ------------------------------------ | ------- | --------------------- |
| id<mark style="color:red;">\*</mark> | integer | 节点ID：int(10) unsigned |

#### Headers

| Name                                        | Type    | Description           |
| ------------------------------------------- | ------- | --------------------- |
| key<mark style="color:red;">\*</mark>       | string  | 由管理后台线路系统，线路授权处取得授权密钥 |
| timestamp<mark style="color:red;">\*</mark> | integer | 每次请求的10位时间戳           |

#### Request Body

| Name                                       | Type    | Description |
| ------------------------------------------ | ------- | ----------- |
| uid<mark style="color:red;">\*</mark>      | integer | 用户ID        |
| upload<mark style="color:red;">\*</mark>   | integer | 上传          |
| download<mark style="color:red;">\*</mark> | integer | 下载          |

{% tabs %}
{% tab title="200: OK 上报成功" %}

```
{
    "status": "success",
    "code": 200,
    "data": "",
    "message": "上报用户流量日志成功"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity 信息缺失" %}

```
{
    "status": "fail",
    "code": 400,
    "data": "",
    "message": "上报用户流量日志失败，请检查字段"
}
```

{% endtab %}
{% endtabs %}

#### 传入参数示例

```
[{"uid":14,"upload":52197,"download":3381985},{"uid":15,"upload":52166,"download":3389995}]
```

## 获取节点的审计规则

<mark style="color:blue;">`GET`</mark> `https://api.proxypanel.ml/api/{后端}/v1/nodeRule/:id`

后端启动和重载时获取对应节点的审计规则

#### Path Parameters

| Name                                 | Type    | Description           |
| ------------------------------------ | ------- | --------------------- |
| id<mark style="color:red;">\*</mark> | integer | 节点ID：int(10) unsigned |

#### Headers

| Name                                        | Type    | Description           |
| ------------------------------------------- | ------- | --------------------- |
| key<mark style="color:red;">\*</mark>       | string  | 由管理后台线路系统，线路授权处取得授权密钥 |
| timestamp<mark style="color:red;">\*</mark> | integer | 每次请求的10位时间戳           |

{% tabs %}
{% tab title="200: OK 返回审计规则" %}

```
第一种：mode为all时，表示节点未设置任何审计规则，全部放行
{
    "status": "success",
    "code": 200,
    "data": {
        "mode": "all",
        "rules": []
    },
    "message": "获取节点审计规则成功"
}

第二种：mode为reject时，表示节点设置了阻断规则，凡是匹配到阻断规则的请求都要拦截
{
    "status": "success",
    "code": 200,
    "data": {
        "mode": "reject",
        "rules": [
            {
                "id": 2, // 审计规则ID，用户触发审计规则时需要上报该ID
                "type": "reg", // 审计规则类型：reg-正则表达式、domain-域名、ip-IP、protocol-应用层协议（HTTP协议、FTP协议、TELNET协议、SFTP协议、BitTorrent协议、POP3协议、IMAP协议、SMTP协议、PPTP协议、L2TP协议）
                "pattern": "(Subject|HELO|SMTP)" // 审计规则的值
            },
            {
                "id": 3,
                "type": "reg",
                "pattern": "BitTorrent protocol"
            },
            {
                "id": 4,
                "type": "reg",
                "pattern": "(api|ps|sv|offnavi|newvector|ulog\\.imap|newloc)(\\.map|)\\.(baidu|n\\.shifen)\\.com"
            },
            {
                "id": 5,
                "type": "reg",
                "pattern": "(.*\\.||)(dafahao|minghui|dongtaiwang|epochtimes|ntdtv|falundafa|wujieliulan|zhengjian)\\.(org|com|net)"
            },
            {
                "id": 7,
                "type": "reg",
                "pattern": "(^.*\\@)(guerrillamail|guerrillamailblock|sharklasers|grr|pokemail|spam4|bccto|chacuo|027168)\\.(info|biz|com|de|net|org|me|la)"
            }
        ]
    },
    "message": "获取节点审计规则成功"
}

第三种：mode为allow时，表示节点设置了仅放行的白名单，凡是非白名单内的全部拦截，仅放行匹配了白名单规则的
{
    "status": "success",
    "code": 200,
    "data": {
        "mode": "allow",
        "rules": [
            {
                "id": 3,
                "type": "reg",
                "pattern": "BitTorrent protocol"
            },
            {
                "id": 6,
                "type": "reg",
                "pattern": "(torrent|\\.torrent|peer_id=|info_hash|get_peers|find_node|BitTorrent|announce_peer|announce\\.php\\?passkey=)"
            },
            {
                "id": 9,
                "type": "domain",
                "pattern": "pornhub.com"
            },
            {
                "id": 10,
                "type": "ip",
                "pattern": "192.168.2.2"
            },
            {
                "id": 12,
                "type": "reg",
                "pattern": "234"
            }
        ]
    },
    "message": "获取节点审计规则成功"
}
```

{% endtab %}
{% endtabs %}

## 上报用户触发审计规则记录

<mark style="color:green;">`POST`</mark> `https://api.proxypanel.ml/api/{后端}/v1/trigger/:id`

用户触发则实时上报，后端需要过滤用户在5\~10分钟内的重复访问（例：10分钟内反复触发仅上报一次）

#### Path Parameters

| Name                                 | Type    | Description           |
| ------------------------------------ | ------- | --------------------- |
| id<mark style="color:red;">\*</mark> | integer | 节点ID：int(10) unsigned |

#### Headers

| Name                                        | Type    | Description           |
| ------------------------------------------- | ------- | --------------------- |
| key<mark style="color:red;">\*</mark>       | string  | 由管理后台线路系统，线路授权处取得授权密钥 |
| timestamp<mark style="color:red;">\*</mark> | integer | 每次请求的10位时间戳           |

#### Request Body

| Name                                       | Type    | Description |
| ------------------------------------------ | ------- | ----------- |
| uid<mark style="color:red;">\*</mark>      | integer | 用户ID        |
| rule\_id<mark style="color:red;">\*</mark> | integer | 规则ID        |
| reason<mark style="color:red;">\*</mark>   | integer | 触发原因        |

{% tabs %}
{% tab title="200: OK 上报成功" %}

```
成功：
{
    "status": "success",
    "code": 200,
    "data": "",
    "message": "上报用户触发审计规则记录成功"
}
```

{% endtab %}

{% tab title="400: Bad Request 上报失败" %}

```
{
    "status": "fail",
    "code": 400,
    "data": "",
    "message": "上报用户触发审计规则记录失败"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity 信息缺失" %}

```javascript
{
    "status": "fail",
    "code": 400,
    "data": "",
    "message": "上报用户触发审计规则记录失败"
}
```

{% endtab %}
{% endtabs %}

#### 传入参数示例

```
{"uid":12,"rule_id":2,"reason":"https:\/\/sex.com\/images\/xx.png"}
```


---

# 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://proxypanel.gitbook.io/wiki/webapi/webapi-base.md?ask=<question>
```

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.