> For the complete documentation index, see [llms.txt](https://proxypanel.gitbook.io/wiki/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://proxypanel.gitbook.io/wiki/webapi/v2ray-webapi.md).

# V2ray WebApi对接

## 功能：V2RayController

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

**本章节包含了VNet-V2ray 以及 V2ray-Posidon的对接内容**
{% endhint %}

本章节重点为V2ray获取节点，用户信息与上报域名证书信息

### 注意

* 节点后端与面板使用的时间误差不应该超过5分钟，否则API授权验证失败
* 使用WebApi后，用户设置中的节点设置信息将不再采用，而是统一获取节点的配置信息；用户的个人配置信息仅适用于DB版本

## 获取节点信息

<mark style="color:blue;">`GET`</mark> `https://api.proxypanel.ml/api/v2ray/v1/node/:id`

V2ray后端启动和重载时获取节点信息

#### 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 返回节点信息" %}

```
{
    "status": "success",
    "code": 200,
    "data": {
        "id": 2,
        "is_udp": true,
        "speed_limit": 6555555,
        "client_limit": 1,
        "push_port": 8081,
        "secret": "tdcpxpip",
        "key": "",
        "pem": "",
        "v2_license": "234234",
        "v2_alter_id": 0,
        "v2_port": 10085,
        "v2_method": "aes-128-gcm",
        "v2_net": "ws",
        "v2_type": "http",
        "v2_host": "v1.vnetpanel.com",
        "v2_path": "/3l1iop1tev35tov9",
        "v2_tls": true,
        "v2_tls_provider": "{\"provider\": \"cloudflare\", \"email\": \"admin@vnetpanel.com\", \"api_key\": \"vnetpanel\"}"
    },
    "message": "获取节点信息成功"
}
```

{% endtab %}
{% endtabs %}

## 获取用户列表

<mark style="color:blue;">`GET`</mark> `https://api.proxypanel.ml/api/v2ray/v1/userList/:id`

V2ray后端启动和重载时获取用户列表

#### 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 返回用户信息" %}

```
{
    "status": "success",
    "code": 200,
    "data": [
        {
            "uid": 1,
            "vmess_uid": "1727ed1f-78d0-675a-5cc8-a9a002fdf1a4",
            "speed_limit": 134217728
        },
        {
            "uid": 2,
            "vmess_uid": "d86a54d1-00a3-3677-f356-91df194adf35",
            "speed_limit": 131072
        }
    ],
    "message": "获取用户列表成功",
    "updateTime": 1565172630
}
```

{% endtab %}
{% endtabs %}

## 上报伪装域名证书信息

<mark style="color:green;">`POST`</mark> `https://api.proxypanel.ml/api/v2ray/v1/certificate/:id`

后端根据获取节点信息中返回的`v2_host`、`key`、`pem`字段来判断：如果`v2_host`有值，但`key`和`pem`为空，则由后端自动签证书并上报给管理系统用于记录，用于解决后端重启后无需在重新签一张新的证书的问题

#### 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 |
| ------------------------------------- | ------ | ----------- |
| key<mark style="color:red;">\*</mark> | string | 证书KEY       |
| pem<mark style="color:red;">\*</mark> | string | 证书PEM       |

{% 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 %}

#### 传入参数示例

```
{"key":"xxxxxxxxxxxxxxxx","pem":"xxxxxxxxxxxxxxxxxxx"}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/v2ray-webapi.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.