> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/proxies/residential-proxies/protocols.md).

# 协议

探索支持的住宅代理协议，并了解如何配置 HTTP、HTTPS、HTTPS/3 和 SOCKS5 连接。

Oxylabs 住宅代理支持 `HTTP`, `HTTPS`, `HTTP/3`，以及 `SOCKS5` 连接协议。你可以选择最适合你的抓取技术栈、HTTP 库或第三方软件的协议。

<table><thead><tr><th width="93">协议</th><th width="247">网关</th><th width="114">传输</th><th>说明</th></tr></thead><tbody><tr><td><a href="#http-protocol"><strong>HTTP</strong></a></td><td><code>pr.oxylabs.io:7777</code></td><td>TCP</td><td>所有库和工具都支持的默认连接方式。</td></tr><tr><td><a href="#https-protocol"><strong>HTTPS</strong></a></td><td><code>https://pr.oxylabs.io:7777</code></td><td>TCP / SSL</td><td>与代理网关的完全加密连接。</td></tr><tr><td><a href="#http-3-protocol"><strong>HTTP/3</strong></a></td><td><code>socks.pr.oxylabs.io:7777</code></td><td>UDP / QUIC</td><td>需要支持 UDP 的 SOCKS5 代理。</td></tr><tr><td><a href="#socks5-protocol"><strong>SOCKS5</strong></a></td><td><code>socks5h://pr.oxylabs.io:7777</code></td><td>TCP / UDP</td><td>底层代理。需要使用用户名标志进行地理定位。</td></tr></tbody></table>

## HTTP

标准 `HTTP` 协议是 Oxylabs 住宅代理的主要连接方式，所有 HTTP 客户端库、网页抓取框架和第三方工具都开箱即用地支持它。

#### 代码示例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -x pr.oxylabs.io:7777 -U "customer-USERNAME:PASSWORD" https://ip.oxylabs.io/location
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

代理 = {
    'http': 'http://customer-USERNAME:PASSWORD@pr.oxylabs.io:7777',
    'https': 'http://customer-USERNAME:PASSWORD@pr.oxylabs.io:7777',
}

response = requests.get('https://ip.oxylabs.io/location', proxies=proxies)
print(response.text)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$username = 'USERNAME';
$password = 'PASSWORD';
$proxy = 'pr.oxylabs.io:7777';

$query = curl_init('https://ip.oxylabs.io/location');
curl_setopt($query, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($query, CURLOPT_PROXY, "http://$proxy");
curl_setopt($query, CURLOPT_PROXYUSERPWD, "customer-$username:$password");
$output = curl_exec($query);
curl_close($query);
echo $output;
?>
```

{% endtab %}
{% endtabs %}

## HTTPS

通过连接 `HTTPS` 为代理入口节点提供端到端加密的 SSL 连接。要启用 HTTPS 代理，请添加 `https://` 到您的代理入口点（例如， `https://pr.oxylabs.io:7777`）。在使用时同样适用 `HTTPS` 与 [特定国家的入口节点](/products/cn/proxies/residential-proxies/location-settings.md#country-specific-entry-nodes).

{% hint style="info" %}
验证您的特定 `HTTP` 客户端库或第三方工具支持 `HTTPS` 协议在使用前设置，因为旧工具可能默认使用未加密的 `HTTP` 代理连接。
{% endhint %}

#### 代码示例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -x https://pr.oxylabs.io:7777 -U "customer-USERNAME:PASSWORD" https://ip.oxylabs.io/location
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

代理 = {
    'http': 'https://customer-USERNAME:PASSWORD@pr.oxylabs.io:7777',
    'https': 'https://customer-USERNAME:PASSWORD@pr.oxylabs.io:7777',
}

response = requests.get('https://ip.oxylabs.io/location', proxies=proxies)
print(response.text)
```

{% endtab %}

{% tab title="Node.js（axios）" %}

```javascript
const axios = require('axios');

axios.get('https://ip.oxylabs.io/location', {
  proxy: {
    protocol: 'https',
    host: 'pr.oxylabs.io',
    端口: 7777,
    auth: {
      用户名: 'customer-USERNAME',
      密码: 'PASSWORD'
    }
  }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));
```

{% endtab %}
{% endtabs %}

## **HTTP/3 (MASQUE)**

{% hint style="warning" %}
**注意：** `谷歌` 是一个受限目标，可与 `UDP` 连接。
{% endhint %}

Oxylabs 住宅代理支持原生 `UDP` 和 `HTTP/3` 通过 MASQUE 的隧道传输（[RFC 9298 CONNECT-UDP](https://www.rfc-editor.org/rfc/rfc9298.html)).

传统代理会将流量强制通过 `TCP` 连接（通过 `HTTP CONNECT` 或 `SOCKS5`），导致 `HTTP/3` 请求降级为 `HTTP/1.1` 或 `HTTP/2`。MASQUE 维持端到端的 `QUIC` 连接，通过我们的住宅出口节点，让你的客户端传输原生 `UDP` 流量直接到现代目标站点。

MASQUE 服务运行在 `QUIC` 上，使用专用 `UDP` 端口：

```
masque.oxylabs.io:50000
```

{% hint style="info" %}
**注意：** 确保你的防火墙允许出站 `UDP` 流量通过端口 `50000`.
{% endhint %}

### 用例 <a href="#use-cases" id="use-cases"></a>

* **原生 HTTP/3 网络抓取：** 在不触发协议降级标记的情况下抓取现代目标网站。
* **通过 UDP 进行 DNS 解析：** 执行直接 DNS 查询（`53/udp`）通过住宅 IP。
* **实时 UDP 协议：** 路由 WebRTC、SIP 或需要真正 UDP 连接的游戏流量。

{% hint style="info" %}
**注意：** 如果你的抓取应用只需要标准 `HTTP` 或 `HTTPS` (`TCP`）连接，请使用我们的主 backconnect 端点（`pr.oxylabs.io:7777`）。MASQUE 引入 `QUIC` 连接建立开销，仅在你需要以下内容时才需要 `UDP` 或原生 `HTTP/3` 传输。
{% endhint %}

### MASQUE 设置 <a href="#masque-setup" id="masque-setup"></a>

**有关完整设置、配置和认证详情，请参见下面的技术设置指南。**

<details>

<summary><strong>MASQUE 设置与配置</strong></summary>

<table data-header-hidden><thead><tr><th width="164"></th><th width="218"></th><th></th></tr></thead><tbody><tr><td><strong>Proxy Endpoint</strong></td><td><code>masque.oxylabs.io:50000</code></td><td>专用 QUIC 接入节点</td></tr><tr><td><strong>传输</strong></td><td><code>HTTP/3</code> 通过 <code>QUIC</code></td><td>使用 UDP 端口 <code>50000</code></td></tr><tr><td><strong>ALPN</strong></td><td><code>h3</code></td><td>应用层协议协商字符串</td></tr><tr><td><strong>数据报支持</strong></td><td><code>EnableDatagrams: true</code></td><td>必须在你的客户端 QUIC 设置中启用</td></tr><tr><td><strong>最大数据报大小</strong></td><td><code>1500</code> 字节</td><td>超过 1500 字节的数据报会被代理丢弃</td></tr><tr><td><strong>TLS 验证</strong></td><td>标准公共 CA</td><td>无需自定义 CA 证书或覆盖设置</td></tr></tbody></table>

### 端点配置和 URI 格式 <a href="#endpoint-configuration-and-uri-formats" id="endpoint-configuration-and-uri-formats"></a>

要建立隧道，您的客户端发送一个 `CONNECT` 请求，带有 `:protocol = connect-udp` 到代理监听器：

* **RFC 9298 标准（推荐）：** `https://masque.oxylabs.io:50000/.well-known/masque/udp/{target_host}/{target_port}/`
* **旧版查询格式：** `https://masque.oxylabs.io:50000/masque?h={target_host}&p={target_port}`

**主机名和 IP：** 代理会通过住宅出口节点代表您解析主机名。您可以传入域名（`example.com`）或 IP 地址（`1.2.3.4`）。IPv6 地址必须进行百分号编码（例如， `2001%3Adb8%3A%3A1`).

### 认证 <a href="#authentication" id="authentication"></a>

身份验证通过标准 **HTTP Basic 认证** 使用 `Proxy-Authorization` 标头发送在 `CONNECT-UDP` 请求中：

```bash
Proxy-Authorization: Basic Base64(customer-USERNAME[-key-value]:PASSWORD)
```

您使用标准的 Oxylabs 代理凭据。 [位置设置](/products/cn/proxies/residential-proxies/location-settings.md) 和 [会话参数](/products/cn/proxies/residential-proxies/session-control.md) 的功能与标准 `HTTP/HTTPS` 代理相同。例如：

```bash
Proxy-Authorization: Basic customer-myuser-cc-us-sessid-abc123:PASSWORD
```

### 嵌套 QUIC 和数据包大小 <a href="#nested-quic-and-packet-size" id="nested-quic-and-packet-size"></a>

在通过 MASQUE 使用 HTTP/3 时，第二个 QUIC 栈会运行在代理隧道之上（*嵌套 QUIC）*。外层连接（*客户端到代理*）封装内层连接数据包（*客户端到目标*），增加 *\~*&#x34;0 字节的协议封装开销。

{% hint style="danger" %}
您必须手动配置数据包大小，并在两个客户端 QUIC 栈上禁用路径 MTU 发现（PMTUD）。如果跳过此步骤，初始的内层握手数据包将超过外层数据报限制，并被代理静默丢弃，导致连接无限期卡住。
{% endhint %}

要正确设置连接，请调整以下内容：

1. **禁用 PMTUD：** 在外层和内层 QUIC 连接上关闭路径 MTU 发现，以强制固定的数据包限制。
2. **外层 QUIC（客户端到代理）：** 将初始/最大数据包大小设置为 `1392` 字节。
3. **内层 QUIC（客户端到目标）：** 将初始/最大数据包大小设置为 `1352` 字节。

{% hint style="info" %}
约 40 字节的差值用于支持外层 QUIC 标头、AEAD 加密标签、DATAGRAM 帧标头、RFC 9297 下的 HTTP-datagram 封装，以及 RFC 9298 下的 CONNECT-UDP 上下文 ID。
{% endhint %}

### 响应状态码 <a href="#response-status-codes" id="response-status-codes"></a>

<table><thead><tr><th width="80">代码</th><th width="260">状态</th><th>说明</th></tr></thead><tbody><tr><td><code>200</code></td><td><code>OK</code></td><td>隧道已建立。UDP 数据报现在可以在请求流上流动。</td></tr><tr><td><code>400</code></td><td><code>错误请求</code></td><td>目标 URI 格式错误或请求参数无效。</td></tr><tr><td><code>407</code></td><td><code>需要代理身份验证</code></td><td>身份验证失败或已达到账户流量限制。</td></tr></tbody></table>

</details>

## SOCKS5

Oxylabs 住宅代理支持 `SOCKS5` 通过……的连接 `TCP` 和 `UDP`.&#x20;

{% hint style="info" %}
SOCKS5 连接同时支持 `socks5h://` 和 `socks5://`:&#x20;

* `socks5h` 传递主机名
* `socks5` 传递解析后的 IP
  {% endhint %}

对于标准 `SOCKS5` 连接，请使用 `socks5h://` 并将其添加到您的连接字符串中：

```
socks5h://pr.oxylabs.io:7777
```

{% hint style="warning" %}

* `SOCKS5` Google Chrome 不支持代理身份验证。请改用 Mozilla Firefox 或 HTTP 客户端。
* 某些目标网站可以使用 `SOCKS5`. 如果遇到连接错误，请切换到 `HTTP` 或 `HTTPS`.
* `SOCKS5` 连接不支持按国家/地区划分的入口点（例如 `de-pr.oxylabs.io`），且本地化必须通过基于用户名的 [位置参数](/products/cn/proxies/residential-proxies/location-settings.md).
* `谷歌` 是一个受限目标，可与 `UDP` 连接。
  {% endhint %}

#### 代码示例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -x socks5h://pr.oxylabs.io:7777 -U "customer-USERNAME-cc-FR:PASSWORD" https://ip.oxylabs.io/location
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

代理 = {
    'http': 'socks5h://customer-USERNAME-cc-FR:PASSWORD@pr.oxylabs.io:7777',
    'https': 'socks5h://customer-USERNAME-cc-FR:PASSWORD@pr.oxylabs.io:7777'
}

response = requests.get('https://ip.oxylabs.io/location', proxies=proxies)
print(response.text)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$username = 'USERNAME';
$password = 'PASSWORD';
$country = 'FR';
$proxy = 'pr.oxylabs.io:7777';

$query = curl_init('https://ip.oxylabs.io/location');
curl_setopt($query, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($query, CURLOPT_PROXY, "socks5h://$proxy");
curl_setopt($query, CURLOPT_PROXYUSERPWD, "customer-$username-cc-$country:$password");
$output = curl_exec($query);
curl_close($query);
echo $output;
?>
```

{% endtab %}
{% endtabs %}

## 允许的代理目标端口

代理端口的默认配置包括 `80` 和 `443`，旨在适配标准 `HTTP` 和 `HTTPS` 协议。 `HTTP/3 (MASQUE)` 在 UDP 端口上运行 `50000`.&#x20;

| 协议                | 传输  | 端口      |
| ----------------- | --- | ------- |
| `HTTP`            | TCP | `80`    |
| `HTTPS`           | TCP | `443`   |
| `HTTP/3 (MASQUE)` | UDP | `50000` |

如需访问其他端口，需要进行合规审核，请联系我们的 [**支持**](mailto:support@oxylabs.io).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/cn/proxies/residential-proxies/protocols.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.