# 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"}
```