> 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.md).

# 住宅代理

了解有关 Oxylabs 住宅代理的一切，包括代码示例、位置定位参数和故障排除资源。

Oxylabs [**住宅代理**](https://oxylabs.io/products/residential-proxy-pool) 使用由全球物理设备连接的互联网服务提供商（ISP）提供的真实 IP 地址。这些代理会随着每次请求自动轮换，并支持精细的国家、城市、州、ZIP 码、ASN 和会话定向。

{% hint style="info" %}
**通过白名单 IP 连接？** 如果你更倾向于通过 IP 白名单进行认证，而不是 `用户名`/`密码` 凭据，请参考我们的 [IP 白名单与子域名认证指南](https://developers.oxylabs.io/products/cn/proxies/residential-proxies/whitelisting-ips.md).&#x20;
{% endhint %}

## 基础查询

{% hint style="info" %}
我们的住宅代理支持 `HTTP`, `HTTPS`, `HTTP/3 (MASQUE)`，以及 `SOCKS5` 协议。你可以进一步了解如何使用它们 [**这里**](https://developers.oxylabs.io/products/cn/proxies/residential-proxies/protocols.md).
{% endhint %}

发起基础请求只需传入你的代理用户凭据（`用户名` 和 `密码`）到回连入口节点（`pr.oxylabs.io:7777`）。每个请求都会自动通过随机 IP 地址路由。

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

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

{% 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);
if ($output)
    echo $output;
?>
```

{% endtab %}

{% tab title="Python" %}

```python
import urllib.request

用户名 = 'USERNAME'
password = 'PASSWORD'
entry = f'http://customer-{username}:{password}@pr.oxylabs.io:7777'

query = urllib.request.ProxyHandler({
    'http': entry,
    'https': entry,
})
execute = urllib.request.build_opener(query)
print(execute.open('https://ip.oxylabs.io/location').read())
```

{% endtab %}

{% tab title="Java" %}

```java
package example;

import org.apache.http.HttpHost;
import org.apache.http.client.fluent.*;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpHost entry = new HttpHost("pr.oxylabs.io", 7777);
        String query = Executor.newInstance()
            .auth(entry, "customer-USERNAME", "PASS")
            .execute(Request.Get("http://ip.oxylabs.io/location").viaProxy(entry))
            .returnContent().asString();
        System.out.println(query);
    }
}
```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using System.Net;

class Example
{
    static void Main()
    {
        var client = new WebClient();
        client.Proxy = new WebProxy("pr.oxylabs.io:7777");
        client.Proxy.Credentials = new NetworkCredential("customer-USERNAME", "PASSWORD");
        Console.WriteLine(client.DownloadString("https://ip.oxylabs.io/location"));
    }
c
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require 'uri'
require 'net/http'

uri = URI.parse('https://ip.oxylabs.io/location')
proxy = Net::HTTP::Proxy('pr.oxylabs.io', 7777, 'customer-USERNAME', 'PASSWORD')

req = Net::HTTP::Get.new(uri.path)

result = proxy.start(uri.host,uri.port) do |http|
    http.request(req)
end

puts result.body
```

{% endtab %}
{% endtabs %}

### 示例响应

测试你的连接会返回 <https://ip.oxylabs.io/location> 来自 MaxMind、IP2Location、DB-IP 和 IPinfo.io 的数据。参数包括 IP 地址、提供商、国家、城市、ZIP 码、ASN、组织名称和时区。

```json
{
  "ip": "185.220.101.5",
  "provider": "Comcast Cable",
  "country": "United States",
  "country_code": "US",
  "city": "New York",
  "zip": "10001",
  "asn": 7018,
  "organization": "ATT-INTERNET4",
  "timezone": "America/New_York"
}
```

## 自定义你的请求

一旦基本连接验证通过，即可根据你的具体需求自定义请求：

<table data-header-hidden><thead><tr><th width="216"></th><th></th></tr></thead><tbody><tr><td><a href="https://developers.oxylabs.io/products/cn/proxies/residential-proxies/location-settings.md"><strong>位置与地理定向</strong></a></td><td>应用国家、城市、州、大洲、ZIP 码、ASN 或坐标参数。</td></tr><tr><td><a href="https://developers.oxylabs.io/products/cn/proxies/residential-proxies/session-control.md"><strong>会话控制</strong></a></td><td>粘性会话（<code>sessid</code>）、会话时长（<code>sesstime</code>）、单 IP 绑定（<code>sessid_oneip</code>）以及粘性端口范围。</td></tr><tr><td><a href="https://developers.oxylabs.io/products/cn/proxies/residential-proxies/protocols.md"><strong>协议与端口</strong></a></td><td>配置 <code>HTTP</code>, <code>HTTPS</code>, <code>HTTP/3</code>，以及 <code>SOCKS5</code> 连接。</td></tr><tr><td><a href="https://developers.oxylabs.io/products/cn/proxies/residential-proxies/advanced-filters.md"><strong>高级筛选</strong></a></td><td>定位特定操作系统（<code>platform</code>）或 IP 协议版本。</td></tr><tr><td><a href="https://developers.oxylabs.io/products/cn/proxies/residential-proxies/whitelisting-ips.md"><strong>IP 白名单</strong></a></td><td>使用基于 IP 的认证，无需密码即可连接。</td></tr></tbody></table>

### 查询参数

单个回连代理（`pr.oxylabs.io:7777)` 可让你通过用户名中的附加参数自定义代理（地理位置、粘性会话等）。以下是凭据示例及其说明：

<figure><img src="https://3714446197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-d3f1a59d25a42e887f472219825623641de0ef3b%2FCode%20explained%20for%20Resi%20documentation%20(upd%202025-06).png?alt=media" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="124">参数</th><th width="114">类型</th><th>说明</th></tr></thead><tbody><tr><td><code>customer</code></td><td>必填</td><td>用户名字符串前缀（例如， <code>customer-USERNAME</code>).</td></tr><tr><td><code>cc</code></td><td>位置</td><td>不区分大小写的 2 字母 ISO 3166-1 国家/地区代码（例如， <code>cc-DE</code>, <code>cc-US</code>).</td></tr><tr><td><code>city</code></td><td>位置</td><td>英文城市名称；需要 <code>cc</code> （例如， <code>cc-US-city-los_angeles</code>).</td></tr><tr><td><code>st</code></td><td>位置</td><td>美国州名称，配合 <code>us_</code> 前缀（例如， <code>st-us_california</code>).</td></tr><tr><td><code>cn</code></td><td>位置</td><td>2 字母大洲代码（例如， <code>cn-EU</code>, <code>cn-AS</code>).</td></tr><tr><td><code>postalcode</code></td><td>位置</td><td>5 位美国 ZIP 码；需要 <code>cc-US</code> （例如， <code>postalcode-90210</code>).</td></tr><tr><td><code>ASN</code></td><td>位置</td><td>自治系统编号（例如， <code>ASN-21928</code>).</td></tr><tr><td><code>地理哈希</code></td><td>位置</td><td>定位 Geohash 网格单元 1–4 级（例如， <code>geohash-u09</code> 用于巴黎）。</td></tr><tr><td><code>sessid</code></td><td>会话</td><td>用于在请求之间保持 IP 的随机字符串（默认 10 分钟）。</td></tr><tr><td><code>sesstime</code></td><td>会话</td><td>将会话持续时间延长至最多 1440 分钟（例如， <code>sesstime-30</code>).</td></tr><tr><td><code>sessid_oneip</code></td><td>会话</td><td>将会话严格绑定到单个出口节点；断开时会返回 502。</td></tr><tr><td><code>platform</code></td><td>筛选</td><td>目标操作系统指纹（<code>windows</code>, <code>macos</code>, <code>linux</code>, <code>android</code>, <code>ios</code>).</td></tr><tr><td><code>ipversion</code></td><td>筛选</td><td>将代理池限制为 <code>ipversion-4</code> 或 <code>ipversion-6</code>.</td></tr></tbody></table>

### 常见代理字符串格式

根据你的工作流、第三方软件或自定义脚本，代理凭据可以采用多种格式：

<table><thead><tr><th width="359">格式</th><th>适用场景</th></tr></thead><tbody><tr><td>HOST:PORT:USER:PASS<br>(<code>pr.oxylabs.io:7777:customer-john:pass123</code>)</td><td>标准自动化工具中使用的回连入口网关格式。</td></tr><tr><td>USER:PASS@HOST:PORT<br>(<code>customer-john:pass123@pr.oxylabs.io:7777</code>)</td><td>标准 URI 格式，适用于 cURL、Python <code>requests</code>、Node.js <code>axios</code>等等。</td></tr><tr><td>IP:PORT:USER:PASS<br>(<code>185.220.101.5:8000:john:pass123</code>)</td><td>常用于机器人工具和桌面抓取器的直接 IP 格式。</td></tr><tr><td>USER:PASS:IP:PORT<br>(<code>john:pass123:185.220.101.5:8000</code>)</td><td>需要自定义解析的旧工具所使用的反向字符串格式。</td></tr><tr><td>IP:PORT<br>(<code>185.220.101.5:8000</code>)</td><td>IP 白名单格式（无需用户名/密码）。</td></tr></tbody></table>

## 仪表板与账户管理

* 访问你的 [Oxylabs 仪表板](https://dashboard.oxylabs.io/en) 以查看实时流量用量、请求统计并管理子用户。
* 使用自动化的 [Endpoint Generator](https://developers.oxylabs.io/products/cn/proxies/residential-proxies/endpoint-generator.md) 以生成并导出自定义代理列表，格式可为 cURL、Python、PHP、Node.js、GO、Java，或用于集成的自定义详情。
* 通过以下方式以程序化方式管理子用户并跟踪用量： [Public API](https://developers.oxylabs.io/products/cn/proxies/residential-proxies/public-api.md).

## 需要技术支持？

&#x20;联系你的客户经理，或使用以下任一方式联系我们的 24/7 支持团队：

* **在线聊天。** 可通过您的仪表板或在 [**Oxylabs 网站**](https://oxylabs.io/) 快速提问或报告漏洞。
* **电子邮件**。您可以通过 [**support@oxylabs.io**](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.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.
