> 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 白名单与子域认证指南](/products/cn/proxies/residential-proxies/whitelisting-ips.md). {% endhint %} ## 基础查询 {% hint style="info" %} 我们的住宅代理支持 `HTTP`, `HTTPS`, `HTTP/3 (MASQUE)`，以及 `SOCKS5` 协议。你可以在这里了解更多关于使用它们的信息 [**这里**](/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 ``` {% endtab %} {% tab title="Python" %} ```python import urllib.request username = '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](https://ip.oxylabs.io/location) 返回来自 MaxMind、IP2Location、DB-IP 和 IPinfo.io 的数据。参数包括 IP 地址、提供商、国家、城市、邮政编码、ASN、组织名称和时区。 ```json { "ip": "185.220.101.5", "provider": "Comcast Cable", "country": "美国", "country_code": "US", "city": "纽约", "zip": "10001", "asn": 7018, "organization": "ATT-INTERNET4", "timezone": "America/New_York" } ``` ## 自定义你的请求 一旦基础连接验证通过，即可根据你的具体需求自定义请求：
位置与地理定位应用国家、城市、州、洲、ZIP 代码、ASN 或坐标参数。
会话控制粘性会话（sessid），会话时长（sesstime），单 IP 绑定（sessid_oneip），以及粘性端口范围。
协议与端口配置 HTTP, HTTPS, HTTP/3，以及 SOCKS5 连接。
高级筛选指定目标操作系统（platform）或 IP 协议版本。
IP 白名单使用基于 IP 的身份验证，无需密码即可连接。
### 查询参数 单个回连代理（`pr.oxylabs.io:7777)` 可通过用户名中的附加参数（地理位置、粘性会话等）来自定义你的代理。以下是凭据示例及其说明：
参数类型说明
customer必填用户名字符串前缀（例如， customer-USERNAME).
cc位置不区分大小写的 2 位 ISO 3166-1 国家代码（例如， cc-DE, cc-US).
城市位置英文城市名称；需要 cc （例如， cc-US-city-los_angeles).
st位置美国州名称，带 us_ 前缀（例如， st-us_california).
cn位置2 位洲代码（例如， cn-EU, cn-AS).
postalcode位置5 位美国邮政编码；需要 cc-US （例如， postalcode-90210).
ASN位置自治系统编号（例如， ASN-21928).
geohash位置定位 Geohash 网格单元 1–4 级（例如， geohash-u09 适用于巴黎）。
sessid会话用于在请求之间保持 IP 的随机字符串（默认 10 分钟）。
sesstime会话将会话时长延长至最多 1440 分钟（例如， sesstime-30).
sessid_oneip会话将会话严格绑定到单个出口节点；连接断开时返回 502。
platform筛选目标 OS 指纹（Windows, macOS, Linux, Android, iOS).
ipversion筛选将代理池限制为 ipversion-4 或 ipversion-6.
### 常见代理字符串格式 根据你的工作流、第三方软件或自定义脚本，代理凭据可以采用多种格式：
格式使用场景
HOST:PORT:USER:PASS
(pr.oxylabs.io:7777:customer-john:pass123)		标准自动化工具中使用的回连入口网关格式。
USER:PASS@HOST:PORT
(customer-john:pass123@pr.oxylabs.io:7777)		cURL、Python 使用的标准 URI 格式 requestsNode.js axios等。
IP:PORT:USER:PASS
(185.220.101.5:8000:john:pass123)		常用于 bot 工具和桌面抓取器的直接 IP 格式。
USER:PASS:IP:PORT
(john:pass123:185.220.101.5:8000)		需要自定义解析的旧版工具所用的反向字符串格式。
IP:PORT
(185.220.101.5:8000)		IP 白名单格式（无需用户名/密码）。
## 控制面板与账户管理 * 访问你的 [Oxylabs 仪表板](https://dashboard.oxylabs.io/en) 以查看实时流量使用情况、请求统计信息并管理子用户。 * 使用自动化 [Endpoint 生成器](/products/cn/proxies/residential-proxies/endpoint-generator.md) 用于生成并导出适用于 cURL、Python、PHP、Node.js、GO、Java 的自定义代理列表，或用于集成的自定义详细信息。 * 通过以下方式以程序化方式管理子用户并跟踪使用情况： [Public API](/products/cn/proxies/residential-proxies/public-api.md). ## 需要技术支持？ 联系你的客户经理，或通过以下任一方式联系我们的 24/7 支持团队： * **在线聊天。** 可通过你的控制面板或在 [**Oxylabs 网站**](https://oxylabs.io/) 上使用在线聊天，用于快速提问或提交 bug 报告。 * **电子邮件**. 你可以通过 [**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=&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.