> 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/whitelisting-ips.md).

# IP 白名单和身份验证

了解如何为住宅代理创建或编辑 IP 白名单。

IP 白名单允许你使用个人已列入白名单的 IP 访问 Oxylabs 住宅代理，从而绕过代理请求中的用户名和密码要求。

{% hint style="warning" %}
**不要混用身份验证方式。** 如果你的源 IP 已列入白名单，请使用 IP 身份验证或凭据身份验证中的一种，切勿同时使用两者。来自已列入白名单 IP 的凭据可能会导致意外的路由行为或浏览器 `407 需要代理身份验证` 错误。
{% endhint %}

## 创建 IP 白名单

要启用基于 IP 的身份验证，请在 Oxylabs Dashboard 中注册您服务器的静态公共 IPv4 地址。

1. 登录到 [**Oxylabs 仪表板**](https://dashboard.oxylabs.io/).
2. 创建一个住宅代理产品实例。
3. 在 **身份验证设置** 选择 **已列入白名单的 IP**.

   <figure><img src="https://3714446197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2FQ2n1AyQHRvSd6CgAJsPE%2FScreenshot%202026-10-05%20at%2004.17.12.png?alt=media&amp;token=0799c543-bb9a-495e-a6b7-d842b6c19fa9" alt=""><figcaption></figcaption></figure>
4. 输入 **最多 10 个公共 IPv4** 地址（以 `xx.xx.xx.xx` 格式）。
5. 填写所有必要信息并点击 **创建实例**.

{% hint style="warning" %}

* 检查您的公共 IP 地址时，请确保未连接到 VPN 或本地代理服务。
* 如果您的团队共享一个公共 IP 地址，或需要分别跟踪子用户，请使用凭证身份验证，而不是 IP 白名单。
  {% endhint %}

## 使用已列入白名单的 IP 的请求

使用 IP 白名单时，参数（例如 [位置](/products/cn/proxies/residential-proxies/location-settings.md), [会话 ID](/products/cn/proxies/residential-proxies/session-control.md)，或 ASN）不能嵌入到用户名字符串中。相反，所有代理标志都直接添加到入口节点主机地址中，作为指向以下地址的子域： `.bc.pr.oxylabs.io:7777`.

```
cc-us-city-new_york-sessid-test123.bc.pr.oxylabs.io:7777
```

<table><thead><tr><th width="149">类型</th><th width="119">参数</th><th>说明</th></tr></thead><tbody><tr><td><a href="/products/cn/proxies/residential-proxies/location-settings.md#country"><strong>国家定位</strong></a></td><td><code>cc</code></td><td>2 位字母的 ISO 国家代码。<br>例如： <code>cc-de.bc.pr.oxylabs.io:7777</code></td></tr><tr><td><a href="/products/cn/proxies/residential-proxies/location-settings.md#city"><strong>城市定位</strong></a></td><td><code>城市</code></td><td>需要 <code>cc</code> 参数。空格使用 <code>_</code>。<br>例如： <code>cc-us-city-new_york.bc.pr.oxylabs.io:7777</code></td></tr><tr><td><a href="/products/cn/proxies/residential-proxies/location-settings.md#state"><strong>州定位</strong></a></td><td><code>st</code></td><td>美国州；需要 <code>us_</code> 前缀。<br>例如： <code>st-us_california.bc.pr.oxylabs.io:7777</code></td></tr><tr><td><a href="/products/cn/proxies/residential-proxies/location-settings.md#continent"><strong>洲定位</strong></a></td><td><code>cn</code></td><td>2 位字母的洲代码（<code>AF</code>, <code>AN</code>, <code>AS</code>, <code>EU</code>, <code>NA</code>, <code>OC</code>, <code>SA</code>）。<br>例如： <code>cn-eu.bc.pr.oxylabs.io:7777</code></td></tr><tr><td><a href="/products/cn/proxies/residential-proxies/location-settings.md#zip-postal-code"><strong>邮政编码定位</strong></a></td><td><code>postalcode</code></td><td>5 位美国邮政编码；需要 <code>cc-us</code>。<br>例如： <code>cc-us-postalcode-90210.bc.pr.oxylabs.io:7777</code></td></tr><tr><td><a href="/products/cn/proxies/residential-proxies/location-settings.md#geo-hash"><strong>地理哈希定位</strong></a></td><td><code>geohash</code></td><td>网格单元级别 1 到 4（<code>9</code> 到 <code>drq4</code>）。<br>例如： <code>geohash-u09.bc.pr.oxylabs.io:7777</code></td></tr><tr><td><a href="/products/cn/proxies/residential-proxies/location-settings.md#asn-targeting"><strong>ASN 定位</strong></a></td><td><code>ASN</code></td><td>指定特定的自治系统编号。<br>例如： <code>asn-21928.bc.pr.oxylabs.io:7777</code></td></tr><tr><td><a href="/products/cn/proxies/residential-proxies/session-control.md#default-sticky-sessions-sessid"><strong>粘性会话</strong></a></td><td><code>sessid</code></td><td>将连续请求绑定到同一 IP（默认 10 分钟）。<br>例如： <code>sessid-test123.bc.pr.oxylabs.io:7777</code></td></tr><tr><td><a href="/products/cn/proxies/residential-proxies/session-control.md#extend-session-duration-sesstime"><strong>会话持续时间</strong></a></td><td><code>sesstime</code></td><td>以分钟为单位延长会话时长。<br>例如： <code>sessid-test123-sesstime-15.bc.pr.oxylabs.io:7777</code></td></tr></tbody></table>

#### 代码示例

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

```shell
curl -x https://cc-us-city-new_york-sessid-test123.bc.pr.oxylabs.io:7777 https://ip.oxylabs.io/location
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$session_id = 'test123';  // Your session ID
$city = 'new_york';  // The city you want to target
$proxy = "cc-us-city-$city-sessid-$session_id.bc.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");
$output = curl_exec($query);
curl_close($query);

if ($output)
    echo $output;
?>

```

{% endtab %}

{% tab title="Python" %}

```python
import urllib.request

session_id = 'test123'  # Your session ID
city = 'new_york'  # The city you want to target
proxy = 'cc-us-city-%s-sessid-%s.bc.pr.oxylabs.io:7777' % (city, session_id)

query = urllib.request.ProxyHandler({
    'http': proxy,
    'https': proxy,
})

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("cc-us-city-new_york-sessid-test123.bc.pr.oxylabs.io", 7777);

        String query = Executor.newInstance()
            .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("cc-us-city-new_york-sessid-test123.bc.pr.oxylabs.io:7777");

        Console.WriteLine(client.DownloadString("https://ip.oxylabs.io/location"));
    }
}

```

{% endtab %}

{% tab title="Go" %}

```ruby
package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
	"net/url"
)

func main() {
	proxyURL, _ := url.Parse("https://cc-us-city-new_york-sessid-test123.bc.pr.oxylabs.io:7777")
	client := &http.Client{Transport: &http.Transport{Proxy: http.ProxyURL(proxyURL)}}

	resp, err := client.Get("https://ip.oxylabs.io/location")
	if err != nil {
		fmt.Println("Error:", err)
		return
	}
	defer resp.Body.Close()

	body, _ := ioutil.ReadAll(resp.Body)
	fmt.Println(string(body))
}
```

{% endtab %}
{% endtabs %}


---

# 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/whitelisting-ips.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.