> 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` 与 [国家/地区特定的入口节点](https://developers.oxylabs.io/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',
    port: 7777,
    auth: {
      username: 'customer-USERNAME',
      password: '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 协议：** 路由需要真正 UDP 连接的 WebRTC、SIP 或游戏流量。

{% 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 代理凭据。 [位置设置](https://developers.oxylabs.io/products/cn/proxies/residential-proxies/location-settings.md) 和 [会话参数](https://developers.oxylabs.io/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 栈上禁用 Path MTU Discovery (PMTUD)。如果跳过此步骤，初始内层握手数据包将超过外层数据报限制，并被代理静默丢弃，导致连接无限期挂起。
{% endhint %}

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

1. **禁用 PMTUD：** 在外层和内层 QUIC 连接上关闭 Path MTU Discovery，以强制固定的数据包限制。
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`) 且本地化必须通过基于用户名的方式进行 [位置参数](https://developers.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.
