---
title: "代理使用文档：配置、身份验证与地理定位 | Proxonym"
description: "配置 Proxonym 代理：网关主机和端口、用户名密码与 IP 白名单身份验证、轮换与粘性会话、地理定位、7 种语言的代码示例以及错误码说明。"
url: https://proxonym.com/zh/docs
updated: 2026-10-02T03:03:46+00:00
---

# Proxonym 文档

连接 Proxonym 所需的一切：端点与端口、身份验证、会话、地理定位、代码示例和错误处理。

- 网关 `gw.proxonym.com`
- HTTP / HTTPS `8000`
- SOCKS5 `1080`
- 定位 `USERNAME-country-us-session-a7k2`

### 目录

速查

- **网关**: `gw.proxonym.com`
- **HTTP / HTTPS**: `8000`
- **SOCKS5**: `1080`
- **国家/地区**: `-country-de`
- **城市**: `-city-berlin`
- **粘性 IP**: `-session-a7k2`
- **保持时长**: `-lifetime-30`

网关错误码

- `407` 凭据或白名单问题
- `402` 余额用尽或套餐过期
- `403` 目标被可接受使用政策屏蔽
- `429` 触发速率保护，请放慢速度
- `502` 节点连接失败，请重试
- `504` 目标超时

**遇到问题？**帮助中心解答计费、错误和账户方面的问题。

[帮助中心](https://proxonym.com/zh/help) [检测代理](https://proxonym.com/zh/proxy-checker)

## 快速入门

本指南将带您在几分钟内完成从购买新套餐到成功发出代理请求的全过程。指南中使用的是共享网关 `gw.proxonym.com` 上的住宅代理。其他产品的连接方式相同，只是改用各自的主机或代理列表；详见[端点与端口](https://proxonym.com/zh/docs#endpoints-and-ports)。

### 三步上手

1. **充值并选择套餐。**使用加密货币为余额充值（最低 $30），然后在控制台中选择产品和规格（参见[价格页面](https://proxonym.com/zh/pricing)），并用余额付款。住宅、移动、不限流量住宅、共享数据中心和 SERP API 套餐即刻生效；ISP 和独享 IP 在一小时内交付。
2. **复制凭据。**您的代理用户名和密码可在控制台中找到。本页的所有示例中，请将 `USERNAME` 和 `PASSWORD` 替换为您自己的值。
3. **发送请求。**将客户端指向 `gw.proxonym.com:8000`，并使用用户名和密码进行身份验证。国家、会话等选项都写在用户名中。

### 发送第一个请求

以下命令通过一个德国住宅 IP 发送一次请求，并输出目标网站看到的 IP 地址：

**Shell**

```bash
curl -x http://gw.proxonym.com:8000 -U "USERNAME-country-de-session-a7k2:PASSWORD" https://api.ipify.org
```

- `-x http://gw.proxonym.com:8000` 用于设置代理。即使目标是 HTTPS，也请保留 `http://` 协议前缀：网关会通过 `CONNECT` 建立加密隧道。
- `-U "USERNAME-country-de-session-a7k2:PASSWORD"` 用于发送凭据。`-country-de` 选择德国的 IP，`-session-a7k2` 则让使用相同用户名的后续请求沿用该 IP，默认保持 10 分钟。
- `https://api.ipify.org` 是目标网站。它会返回所看到的 IP 地址，也就是您的出口 IP，例如 `203.0.113.58`。

在 Windows 上，请输入 `curl.exe` 而不是 `curl`。Windows PowerShell 5.1 会将 `curl` 映射为 `Invoke-WebRequest`，而后者使用的是另一套选项。

### 验证出口 IP

1. 不经代理运行 `curl https://api.ipify.org`。返回的是您自己的 IP，也可在[我的 IP 地址](https://proxonym.com/zh/what-is-my-ip)页面查看。
2. 再次运行使用代理的命令。返回的 IP 应与您自己的 IP 不同，并且在会话有效期内每次运行都保持不变。
3. 从用户名中删除 `-session-a7k2`，然后多运行几次命令。此时每个请求都会从新的 IP 出口。
4. 通过代理访问 IP 地理位置查询服务，确认 IP 所在位置。响应中的 `country` 字段应为 `DE`。

**Shell**

```bash
curl -s -x http://gw.proxonym.com:8000 \
  -U "USERNAME-country-de:PASSWORD" \
  https://ipinfo.io/json
```

收到 `407` 响应表示代理拒绝了您的凭据。请检查是否有拼写错误，并确保各选项以短横线连接、不含空格。其他所有状态码的说明请见[错误与故障排查](https://proxonym.com/zh/docs#errors-and-troubleshooting)。

接下来，您可以通过[会话](https://proxonym.com/zh/docs#rotating-and-sticky-sessions)控制 IP 何时更换，通过[地理定位](https://proxonym.com/zh/docs#geo-targeting)选择位置，或直接从[代码示例](https://proxonym.com/zh/docs#code-examples)中复制客户端代码。

## 身份验证

Proxonym 通过两种方式对代理连接进行身份验证：随每个连接发送的用户名和密码，或 IP 白名单（名单中的机器无需凭据即可连接）。可用的方式取决于产品。

| 产品 | 用户名和密码 | IP 白名单 |
| --- | --- | --- |
| 住宅代理、移动代理、不限流量住宅代理 | 是，支持用户名选项 | 否 |
| 共享数据中心代理 | 是 | 是，含 3 个 IP |
| ISP | 是，凭据见代理列表 | 否 |
| 独享数据中心代理 | 是，凭据见代理列表 | 否 |

账户 API 和 SERP API 则改用 API 密钥进行身份验证。详见 [API 参考](https://proxonym.com/zh/docs/api#authentication)。

### 用户名和密码

您的代理用户名和密码可在控制台中找到。客户端通过 HTTP Basic 代理身份验证（`Proxy-Authorization` 请求头）或 SOCKS5 用户名/密码方式发送凭据。大多数工具支持以下两种形式之一：

- 写在代理 URL 中：`http://USERNAME:PASSWORD@gw.proxonym.com:8000`
- 作为单独的设置项，例如 cURL 的 `-U USERNAME:PASSWORD`，或 HTTP 库的代理身份验证选项

对于住宅代理、移动代理和不限流量住宅代理，用户名中还可以携带选项，以短横线依次附加：`USERNAME-country-us-city-new_york-session-a7k2-lifetime-30`。无论添加什么选项，密码都保持不变。选项的用法详见[轮换会话与粘性会话](https://proxonym.com/zh/docs#rotating-and-sticky-sessions)和[地理定位](https://proxonym.com/zh/docs#geo-targeting)。

如果密码中包含 `@`、`:`、`/` 或 `#` 等字符，在代理 URL 中需要对其进行百分号编码：`@` 应写为 `%40`。未经编码的特殊字符会破坏 URL 解析，导致 `407` 错误或连接失败。单独设置用户名和密码时则无需编码。

### IP 白名单（共享数据中心代理）

共享数据中心代理可以按来源 IP 进行身份验证，无需凭据，这对无法发送代理用户名的工具很有帮助。每个共享数据中心套餐均含 3 个白名单 IP。

1. 查出要连接的机器的公网 IP：在该机器上运行 `curl https://api.ipify.org`。
2. 在控制台中添加该 IP，或使用 `POST /whitelist` 添加（参见[白名单 API](https://proxonym.com/zh/docs/api#whitelist)）。
3. 无需凭据，直接连接数据中心代理列表中的任一 `ip:port`：

**Shell**

```bash
curl -x http://198.51.100.23:3129 https://api.ipify.org
```

只将拥有固定公网 IP 的机器（例如服务器）加入白名单。家庭和办公网络的 IP 经常变化，而来自未列入白名单的 IP 的请求会失败并返回 `407`。3 个名额全部用完时，需先移除一个 IP 才能添加新的 IP。如果不想管理 IP，请改用用户名和密码进行身份验证。

### 子用户

子用户是您账户下额外的几组代理凭据。每个子用户都有自己的用户名、密码、可选的流量上限和状态，其流量从您的账户余额中扣除。借助子用户，您可以为每个团队、客户或项目分配独立的凭据，以 GB 为单位限制某项任务的流量，按子用户跟踪用量，并在不影响其他凭据的情况下单独撤销某一组凭据。

可在控制台中创建子用户，也可使用 `POST /sub-users` 创建（参见[子用户 API](https://proxonym.com/zh/docs/api#sub-users)）。子用户的用户名支持与您的用户名相同的选项，例如 `sub_k3v9q2xd-country-gb-session-x91`。子用户达到流量上限后，其请求会失败并返回 `402`，直到您提高上限为止。已停用的子用户会收到 `407`。

### 安全轮换凭据

请像对待其他机密信息一样对待代理凭据：

- 将凭据保存在环境变量或密钥管理服务中，切勿写入源代码、代码仓库或客户端应用。
- 为每个服务分配独立的子用户，这样一旦发生泄露，暴露的也只是一组凭据，而非全部。
- 定期轮换凭据；一旦怀疑泄露，立即轮换。

如需在不中断服务的情况下轮换，请让新旧凭据并行运行一段时间：

1. 使用 `POST /sub-users` 创建一个新的子用户，并为其设置与旧子用户相同的流量上限。
2. 将新的用户名和密码部署到每个工作节点。
3. 在控制台中或通过 `GET /sub-users` 观察旧子用户的 `traffic_used_gb`。当该值不再增长时，说明已没有任何程序在使用旧凭据。
4. 使用 `DELETE /sub-users/{id}` 删除旧子用户。

发生泄露后，不必等待新凭据全面部署：请立即使用 `PATCH /sub-users/{id}` 并以 `{"reset_password": true}` 作为请求体重置密码，旧密码会立即失效。API 密钥的轮换方式相同：在控制台中创建新密钥并完成部署，然后撤销旧密钥。

## 端点与端口

轮换类产品通过主机名连接；静态产品则提供一份代理 IP 列表，供您直接连接。下表列出了所有接入点。

| 产品 | 主机 | HTTP 端口 | SOCKS5 端口 | 身份验证 | 格式 |
| --- | --- | --- | --- | --- | --- |
| [住宅代理](https://proxonym.com/zh/residential-proxies) | `gw.proxonym.com` | `8000` | `1080` | 用户名和密码 | `USERNAME[-options]:PASSWORD` |
| [移动代理](https://proxonym.com/zh/mobile-proxies) | `gw.proxonym.com` | `8000` | `1080` | 用户名和密码 | `USERNAME-type-mobile[-options]:PASSWORD` |
| [不限流量住宅代理](https://proxonym.com/zh/unlimited-residential-proxies) | `de.unl.proxonym.com`、`use.unl.proxonym.com` 或 `usw.unl.proxonym.com`，以结账时的选择为准 | `8000` | `1080` | 用户名和密码 | `USERNAME[-options]:PASSWORD` |
| [ISP 代理](https://proxonym.com/zh/isp-proxies) | 列表中的 IP | 列表中的端口 | 与 HTTP 端口相同 | 使用列表中的用户名和密码 | `ip:port:username:password` |
| [共享数据中心代理](https://proxonym.com/zh/datacenter-proxies) | 列表中的 IP | `3129` | `1081` | IP 白名单，或用户名和密码 | `ip:port` |
| [独享数据中心代理](https://proxonym.com/zh/dedicated-datacenter-proxies) | 列表中的 IP | 列表中的端口 | 与 HTTP 端口相同 | 使用列表中的用户名和密码 | `ip:port:username:password` |

`[-options]` 表示可选的用户名选项，例如 `-country-us-session-a7k2`。代理列表的说明请见[数据中心、ISP 和独享代理列表](https://proxonym.com/zh/docs#proxy-lists)。

### HTTPS 目标

HTTP 端口同时支持 `http://` 和 `https://` 目标。对于 HTTPS，代理会建立 `CONNECT` 隧道，TLS 为端到端加密，因此您无需安装任何证书。即使目标使用 HTTPS，代理 URL 也应以 `http://` 开头。详见[协议](https://proxonym.com/zh/docs#protocols-https)。

### API

| API | 基础 URL | 认证方式 |
| --- | --- | --- |
| 账户 API | `https://api.proxonym.com/v1` | `Authorization: Bearer <API_KEY>` |
| Google SERP API | `https://serp.proxonym.com/v1` | `X-API-Key` 请求头 |

两者的详细说明请见 [API 参考](https://proxonym.com/zh/docs/api)。

### 防火墙

端口 8000、1080、3129 和 1081 并非标准 Web 端口，部分企业网络和云安全组会将其屏蔽。如果连接在收到任何响应之前就卡住，请放行发往所用代理主机和端口的出站 TCP 流量；如果通过 SOCKS5 发送 UDP，还需放行 UDP。

## 轮换会话与粘性会话

对于住宅代理、移动代理和不限流量住宅代理，出口 IP 何时更换由用户名决定。共有两种模式：轮换（默认）和粘性。

### 轮换（默认）

不带会话选项时，每个请求都会从 IP 池中获得一个新 IP：

**文本**

```text
USERNAME-country-us
```

轮换模式适合抓取大量相互独立页面的无状态任务。每个请求看起来都像来自不同的访客，某个 IP 被封禁时，损失的只是一个请求，而不是整个任务。

网关每路由一个新请求，就会为其分配一个 IP。通过复用的 HTTPS 连接发送的请求会经过同一条 `CONNECT` 隧道，因而沿用该隧道的 IP。如果希望每次都使用新 IP，请为每个请求建立新连接，或使用粘性会话来精确控制 IP 的更换时机。

### 粘性会话

添加 `-session-{id}` 即可在多个请求之间保持同一 IP。凡是发送相同用户名（包括会话 ID）的请求，都会使用同一 IP，直到会话结束。

**文本**

```text
USERNAME-country-us-session-a7k2
USERNAME-country-us-session-a7k2-lifetime-30
```

- `-session-{id}`：由您自定的 1 到 32 位字母或数字。新的 ID 会在新 IP 上开启新会话。
- `-lifetime-{minutes}`：会话保持其 IP 的时长。不设置时，会话持续 10 分钟。

| 产品 | 会话时长 | 最长会话 |
| --- | --- | --- |
| 住宅 | 1–120 分钟，默认 10 分钟 | `-lifetime-120`（2 小时） |
| 不限流量住宅代理 | 1–720 分钟，默认 10 分钟 | `-lifetime-720`（12 小时） |
| 移动 | 1–3 分钟，需明确设置 | `-lifetime-3`（3 分钟） |

住宅 IP 和移动 IP 属于随时可能离线的真实设备。请把会话时长视为上限，而非保证：会话可能提前失去其 IP，此时请求会失败并返回 `502`。如果需要连续数天使用同一 IP，请选择 [ISP](https://proxonym.com/zh/isp-proxies) 代理或[独享数据中心](https://proxonym.com/zh/dedicated-datacenter-proxies)代理。

### 示例流程

以下脚本先在一个粘性会话中发送三个请求，再发送三个轮换请求：

**Shell**

```bash
# Sticky: same session ID, same IP for up to 30 minutes
for i in 1 2 3; do
  curl -s -x http://gw.proxonym.com:8000 \
    -U "USERNAME-country-us-session-job42-lifetime-30:PASSWORD" \
    https://api.ipify.org; echo
done

# Rotating: no session option, a new IP on every request
for i in 1 2 3; do
  curl -s -x http://gw.proxonym.com:8000 \
    -U "USERNAME-country-us:PASSWORD" \
    https://api.ipify.org; echo
done
```

示例输出：

**文本**

```text
203.0.113.41
203.0.113.41
203.0.113.41
203.0.113.187
203.0.113.9
203.0.113.152
```

如需在粘性会话结束前切换到新 IP，只需更改会话 ID，例如改为 `-session-job43`。

### 最佳实践

- **轮换**适用于无状态页面：搜索结果、商品页、列表页。
- **保持粘性**适用于网站要求多个步骤来自同一访客的场景：登录、购物车与结账、多步骤表单、与 Cookie 绑定的分页。
- 为每个工作进程、浏览器配置文件或账号使用一个独立会话，并采用随机 ID，避免并行任务意外共用同一 IP。
- 将会话时长设置为接近任务所需的时间。会话越短，流量就会分散到越多的 IP 上。
- 同一会话中的每个请求都应发送完全相同的用户名。在会话中途更改国家或其他选项，可能会让您切换到另一个 IP。
- 遇到封禁或验证码后，请换用新的会话 ID，而不是在同一 IP 上重试。

想深入了解两种模式各自的适用场景，请阅读我们的[轮换会话与粘性会话对比](https://proxonym.com/zh/blog/rotating-vs-sticky-sessions)。

## 地理定位

在用户名中添加位置选项，即可选择出口 IP 所在的位置。这些选项适用于住宅代理、移动代理和不限流量住宅代理。静态产品的位置由列表中的 IP 决定，因此请改为按国家筛选列表。

### 参数

| 选项 | 格式 | 示例 |
| --- | --- | --- |
| `-country-{cc}` | ISO 3166-1 alpha-2 代码，小写。省略时随机选择国家。 | `-country-us`, `-country-gb`, `-country-de` |
| `-state-{name}` | 州或地区，小写，空格用下划线代替 | `-state-california`, `-state-new_york` |
| `-city-{name}` | 城市，小写，空格用下划线代替 | `-city-new_york`, `-city-sao_paulo` |
| `-asn-{number}` | 网络的自治系统号（ASN） | `-asn-7922`（Comcast） |

### 规则

- 使用 `-state` 或 `-city`，切勿在同一个用户名中同时使用两者。
- 按州、城市或 ASN 定位时，务必同时包含 `-country`。许多城市名称在不止一个国家存在。
- 国家代码遵循 ISO 3166-1 标准，因此英国是 `gb`，而不是 `uk`。
- 名称请使用纯小写 ASCII 字符，空格用下划线代替：写作 `sao_paulo`，而不是 `São Paulo`。
- 请按本文档通篇使用的顺序排列选项：国家、州或城市、ASN、类型、会话、会话时长。

### 示例

| 目标 | 用户名 |
| --- | --- |
| 随机国家 | `USERNAME` |
| 美国 | `USERNAME-country-us` |
| 加利福尼亚州 | `USERNAME-country-us-state-california` |
| 纽约市 | `USERNAME-country-us-city-new_york` |
| 美国 Comcast 用户 | `USERNAME-country-us-asn-7922` |
| 巴西圣保罗 | `USERNAME-country-br-city-sao_paulo` |
| 伦敦，30 分钟内保持同一 IP | `USERNAME-country-gb-city-london-session-a7k2-lifetime-30` |
| 美国移动运营商 IP | `USERNAME-country-us-type-mobile` |

如需确认某个 IP 的位置，请通过代理访问 IP 地理位置查询服务，方法见[验证出口 IP](https://proxonym.com/zh/docs#quick-start-verify-exit-ip)。

### 覆盖范围

- **住宅代理：**5500万+ 个 IP，覆盖 195+ 个国家和地区。IP 池规模最大的是美国（830万）、巴西（520万）、印度（320万）、英国（230万）、墨西哥（180万）、阿根廷（150万）、印度尼西亚（140万）和菲律宾（110万）。
- **不限流量住宅代理：**约 1000万个 IP，覆盖 180+ 个国家和地区。
- **移动代理：**美国（`us`）、英国（`gb`）和奥地利（`at`），更多国家正陆续上线。

定位范围越窄，可用的 IP 池就越小。一个国家在任何时刻都有大量在线 IP；而小城市或单个 ASN 可能只有少量 IP，因此重试次数会更多，能获得的不同 IP 也更少。各国覆盖情况请见[地区](https://proxonym.com/zh/locations)页面。

### 没有匹配的 IP 时

如果没有匹配的 IP，网关会返回 `502`；此时请放宽定位条件。网关在放弃之前会先重试，因此如果同一用户名反复出现 `502`，通常说明定位组合过窄或有拼写错误。

放宽定位的方法：从城市改为州，从州改为国家，或去掉 ASN。同时请检查拼写：`-city-newyork` 或 `-country-uk` 不会匹配到任何 IP。

## 移动代理

[移动代理](https://proxonym.com/zh/mobile-proxies)通过 3G、4G 和 5G 运营商 IP 转发您的流量。运营商会让大量用户共用同一个公网 IP，因此网站在封禁这类 IP 时格外谨慎，这也让它们非常适合社交平台和移动优先的应用。

### 连接

移动代理使用住宅代理网关和您平常使用的凭据，只需在用户名中添加 `-type-mobile`：

**Shell**

```bash
curl -x http://gw.proxonym.com:8000 \
  -U "USERNAME-country-us-type-mobile:PASSWORD" \
  https://api.ipify.org
```

移动流量与住宅代理共用同一 GB 余额，没有需要单独充值的移动代理余额。

### 地区

移动 IP 目前覆盖美国（`-country-us`）、英国（`-country-gb`）和奥地利（`-country-at`），更多国家正陆续上线。在没有移动代理覆盖的国家，由于没有匹配的 IP，网关会返回 `502`。

### 轮换与会话

- **轮换：**移动 IP 按连接轮换。每个新连接都会获得新 IP，而通过长连接（keep-alive）发送的请求共用该连接的 IP。
- **粘性：**添加 `-session-{id}`，并将会话时长设为 1 到 3 分钟。使用移动代理时，请始终明确设置会话时长。

**文本**

```text
USERNAME-country-gb-type-mobile-session-m42x-lifetime-3
```

三分钟足以完成一个简短流程，例如加载某个个人主页及其资源。对于更长的流程，请在客户端中保存 Cookie 和状态，使其在 IP 更换后仍能继续。如果账号需要连续数天使用同一 IP，请使用 [ISP 代理](https://proxonym.com/zh/isp-proxies)。

## 不限流量住宅代理

[不限流量住宅代理](https://proxonym.com/zh/unlimited-residential-proxies)套餐按带宽和期限计费，而不是按 GB 计费。流量不计量：您可以使用覆盖 180+ 个国家和地区的约 1000万个住宅 IP，套餐的速度决定总吞吐量的上限。

### 网关服务器

每个套餐都运行在您结账时选择的独享网关服务器上。请选择离发送流量的机器最近的服务器；您仍然可以通过 `-country` 定位任意国家。

| 服务器 | 地区 | HTTP 端口 | SOCKS5 端口 |
| --- | --- | --- | --- |
| `de.unl.proxonym.com` | 德国 | `8000` | `1080` |
| `use.unl.proxonym.com` | 美国东部 | `8000` | `1080` |
| `usw.unl.proxonym.com` | 美国西部 | `8000` | `1080` |

**Shell**

```bash
curl -x http://use.unl.proxonym.com:8000 \
  -U "USERNAME-country-us-session-a7k2-lifetime-240:PASSWORD" \
  https://api.ipify.org
```

用户名选项的用法与住宅代理相同：国家、州、城市、ASN、会话和会话时长。请只连接您套餐所属的服务器。

### 带宽档位与期限

套餐提供 100、200、400、600、800 Mbps 和 1 Gbps 档位，期限为 1、7 或 30 天。档位限制的是所有连接的总速度，而不是数据量。套餐绝不自动续费：期限结束后，请求会失败并返回 `402`，直到您续费为止。价格请见[价格页面](https://proxonym.com/zh/pricing)。

### 粘性会话最长 12 小时

不限流量住宅代理支持 1 到 720 分钟的会话时长，因此使用 `-lifetime-720` 时，一个会话最长可将其 IP 保持 12 小时。与住宅代理一样，IP 仍可能在会话时长结束前离线。

### UDP 附加服务

UDP 附加服务需在结账时选择，开通后可通过 SOCKS5 的 `UDP ASSOCIATE` 命令在 `1080` 端口上使用 UDP。未开通时，网关仅传输 TCP。详见 [UDP 支持](https://proxonym.com/zh/docs#protocols-udp)。

### 合理使用

不设 GB 上限，并发不限。使用须遵守[可接受使用政策](https://proxonym.com/zh/acceptable-use)中的合理使用原则。如需超出自助档位的持续大用量，请参阅[企业方案](https://proxonym.com/zh/enterprise)。背景知识：[不限流量住宅代理的工作原理](https://proxonym.com/zh/blog/unlimited-residential-proxies-explained)。

## 数据中心、ISP 和独享代理列表

静态产品不经过网关。您直接连接分配给套餐的代理 IP，这些 IP 以列表形式下载。

### 下载代理列表

可从控制台下载列表，也可通过账户 API 获取：

**Shell**

```bash
curl -H "Authorization: Bearer $PROXONYM_API_KEY" \
  "https://api.proxonym.com/v1/proxies/datacenter?format=txt&country=us"
```

路径中的产品可以是 `datacenter`、`isp` 或 `dedicated`。`format` 可取 `txt`（每行一个代理）或 `json`，`country` 按国家代码筛选。详见 [API 参考](https://proxonym.com/zh/docs/api#proxy-lists)。

### 格式

| 产品 | 行格式 | 示例行 | 代理 URL |
| --- | --- | --- | --- |
| 共享数据中心代理 | `ip:port` | `198.51.100.23:3129` | `http://198.51.100.23:3129`（需使用白名单 IP），或 `http://USERNAME:PASSWORD@198.51.100.23:3129`。SOCKS5：同一 IP，端口 `1081` |
| ISP | `ip:port:username:password` | `198.51.100.61:6200:isp_k8w2m4:Tz6pW1qR8nVb3xYc` | `http://username:password@ip:port` 或 `socks5h://username:password@ip:port` |
| 独享数据中心代理 | `ip:port:username:password` | `198.51.100.112:6200:ded_r4n7c2:Mb9xK2vQ7tLp4wZe` | `http://username:password@ip:port` 或 `socks5h://username:password@ip:port` |

请始终以列表中的主机和端口为准。

### 将请求分散到整个列表

静态 IP 不会自动轮换：每一行始终从其对应的 IP 出口。如需分散请求，请在代码中循环使用列表：

**Python**

```python
import itertools

import requests

# proxies.txt holds one ISP or dedicated proxy per line: ip:port:username:password
with open("proxies.txt") as f:
    lines = [line.strip() for line in f if line.strip()]

def to_url(line: str) -> str:
    ip, port, user, password = line.split(":", 3)
    return f"http://{user}:{password}@{ip}:{port}"

pool = itertools.cycle([to_url(line) for line in lines])

for _ in range(5):
    proxy = next(pool)
    r = requests.get("https://api.ipify.org", proxies={"http": proxy, "https": proxy}, timeout=30)
    print(r.text)
```

### 共享数据中心代理

- 覆盖 9 个国家和地区的 40,000 个 IP（美国、巴西、德国、法国、英国、加拿大、泰国、意大利和西班牙），另有一个混合 IP 池。IP 与其他客户共享。
- 每个 IP 的 `3129` 端口提供 HTTP，`1081` 端口提供 SOCKS5，并支持基于 SOCKS5 的 UDP。
- 可通过 [IP 白名单](https://proxonym.com/zh/docs#authentication-ip-whitelist)（含 3 个 IP）或用户名和密码进行身份验证。
- 列表是静态的，默认不轮换。
- 每月带宽档位分为 250 GB、1 TB、5 TB 和不限量。不限量档位须遵守合理使用原则。

### ISP 代理

- 注册在家用宽带运营商（ISP）名下的静态 IP，由您的账户独享，带宽不限。
- 17 个地区：美国（纽约、洛杉矶、弗吉尼亚，以及 Comcast IP 池和 Verizon IP 池）、加拿大、德国、英国、香港、日本、法国、意大利、波兰、西班牙、新加坡、摩尔多瓦和韩国。
- 期限可选 1、7、30 或 90 天，一小时内交付。套餐绝不自动续费：请查看 JSON 列表或 `GET /account` 中的 `expires_at`，在您认为合适的时候续费。
- HTTP 和 SOCKS5 共用同一端口，SOCKS5 支持 TCP 和 UDP。

刚接触静态住宅 IP？请阅读[什么是 ISP 代理](https://proxonym.com/zh/blog/what-is-an-isp-proxy)。

### 独享数据中心代理

- 为您的账户专门保留的私有 IP，覆盖 8 个国家和地区：美国、加拿大、德国、法国、意大利、日本、印度和台湾。
- 使用用户名和密码进行身份验证，凭据包含在列表中。HTTP 和 SOCKS5 共用同一端口。
- 带宽不限，按每个 IP 每月计费。
- 可按需更换 IP：在控制台的**我的套餐**中选择**更换 IP**，并列出需要更换的 IP 及原因。

## 协议

所有产品均支持 HTTP、HTTPS 和 SOCKS5。使用客户端支持的任意一种即可：各协议下的 IP、凭据和用户名选项完全相同。两者的利弊权衡，请阅读我们的 [SOCKS5 与 HTTP 对比](https://proxonym.com/zh/blog/socks5-vs-http-proxies)。

### HTTP

对于 `http://` 目标，客户端会将完整请求发送给代理，再由代理转发给目标。请使用 HTTP 端口和以 `http://` 开头的代理 URL。更多信息请见 [HTTP 代理](https://proxonym.com/zh/http-proxies)页面。

### HTTPS（CONNECT）

对于 `https://` 目标，客户端会先通过 `CONNECT` 请求代理建立隧道，再经由该隧道与目标进行 TLS 协商。加密是端到端的，证书也是目标网站自己的，因此无需额外配置 CA。代理 URL 仍以 `http://` 开头，因为在隧道建立之前，与代理之间的连接是普通的 HTTP。交互过程如下：

**文本**

```text
CONNECT example.com:443 HTTP/1.1
Host: example.com:443
Proxy-Authorization: Basic VVNFUk5BTUUtY291bnRyeS11czpQQVNTV09SRA==

HTTP/1.1 200 Connection established
```

这个 Base64 值是 `USERNAME-country-us:PASSWORD` 的编码结果，HTTP 库会自动为您生成。

### SOCKS5

SOCKS5 可以传输任何 TCP 流量，而不仅仅是 HTTP，部分产品还支持 UDP。住宅代理网关和不限流量服务器使用 `1080` 端口，共享数据中心 IP 使用 `1081` 端口，ISP 和独享 IP 则使用列表中的端口。身份验证采用 SOCKS5 用户名/密码方式，凭据和用户名选项与 HTTP 相同。

使用 `socks5h://` 可让主机名在代理端解析，其中的 `h` 代表远程 DNS。如果只用 `socks5://`，您的机器会自行解析目标主机名：DNS 查询会泄露给您自己的解析器，并且可能返回针对您所在位置（而非出口 IP 所在位置）的地址。

**Shell**

```bash
curl -x socks5h://gw.proxonym.com:1080 \
  -U "USERNAME-country-us:PASSWORD" \
  https://api.ipify.org
```

在 Python 中，先用 `pip install "requests[socks]"` 安装 SOCKS 支持，再使用相同的协议前缀：

**Python**

```python
import requests

proxy = "socks5h://USERNAME-country-us:PASSWORD@gw.proxonym.com:1080"
r = requests.get("https://api.ipify.org", proxies={"http": proxy, "https": proxy}, timeout=30)
print(r.text)
```

更多信息请见 [SOCKS5 代理](https://proxonym.com/zh/socks5-proxies)页面。

### UDP 支持

UDP 通过 SOCKS5 传输，使用 RFC 1928 中定义的 `UDP ASSOCIATE` 命令。您的客户端需要使用实现了该命令的 SOCKS5 库；HTTP 代理无法传输 UDP，cURL 也不支持 SOCKS5 UDP。

| 产品 | HTTP 和 HTTPS | SOCKS5（TCP） | SOCKS5（UDP） |
| --- | --- | --- | --- |
| 住宅 | 端口 8000 | 端口 1080 | 否 |
| 移动 | 端口 8000 | 端口 1080 | 否 |
| 不限流量住宅代理 | 端口 8000 | 端口 1080 | 开通 UDP 附加服务后支持，端口 1080 |
| ISP | 列表中的端口 | 列表中的端口 | 是，使用列表中的端口 |
| 共享数据中心代理 | 端口 3129 | 端口 1081 | 是，端口 1081 |
| 独享数据中心代理 | 列表中的端口 | 列表中的端口 | 否 |

如需使用 UDP，请选择 ISP 代理、共享数据中心代理，或开通 UDP 附加服务的不限流量住宅代理。

## 代码示例

每个示例都会通过 `gw.proxonym.com:8000` 上的一个轮换美国住宅 IP 发送一次请求，并输出 `api.ipify.org` 的响应，其中包含您的出口 IP。请替换 `USERNAME` 和 `PASSWORD`，并通过修改用户名来调整定位，例如 `USERNAME-country-de-session-a7k2-lifetime-30`。在生产环境中，请从环境变量读取凭据。

### cURL

**Shell**

```bash
# Rotating US IP: a new IP on every run
curl -x http://gw.proxonym.com:8000 \
  -U "USERNAME-country-us:PASSWORD" \
  "https://api.ipify.org?format=json"

# Sticky New York IP for 30 minutes
curl -x http://gw.proxonym.com:8000 \
  -U "USERNAME-country-us-city-new_york-session-a7k2-lifetime-30:PASSWORD" \
  "https://api.ipify.org?format=json"
```

如需使用 SOCKS5，请参阅 [SOCKS5](https://proxonym.com/zh/docs#protocols-socks5)。更多选项请见 [cURL 集成指南](https://proxonym.com/zh/integrations/curl)。

### Python（requests）

**Python**

```python
import requests

USERNAME = "USERNAME-country-us"
PASSWORD = "PASSWORD"
GATEWAY = "gw.proxonym.com:8000"
URL = "https://api.ipify.org?format=json"

proxy = f"http://{USERNAME}:{PASSWORD}@{GATEWAY}"
proxies = {"http": proxy, "https": proxy}

# Rotating: each requests.get() opens a new connection and gets a new IP
r = requests.get(URL, proxies=proxies, timeout=(10, 60))
print(r.status_code, r.json())

# Sticky: the session ID keeps the IP; a Session also reuses the connection
sticky = f"http://{USERNAME}-session-a7k2-lifetime-30:{PASSWORD}@{GATEWAY}"
sticky_proxies = {"http": sticky, "https": sticky}
with requests.Session() as s:
    for _ in range(3):
        print(s.get(URL, proxies=sticky_proxies, timeout=(10, 60)).json())
```

代码中的 timeout 元组依次为连接超时和读取超时，单位为秒。另请参阅 [Python requests 集成指南](https://proxonym.com/zh/integrations/python-requests)和我们的 [Python requests 代理使用指南](https://proxonym.com/zh/blog/python-requests-proxies)。

### Python（aiohttp）

**Python**

```python
import asyncio

import aiohttp

PROXY = "http://gw.proxonym.com:8000"
AUTH = aiohttp.BasicAuth("USERNAME-country-us", "PASSWORD")
URL = "https://api.ipify.org?format=json"

async def fetch(session: aiohttp.ClientSession, n: int) -> None:
    async with session.get(URL, proxy=PROXY, proxy_auth=AUTH) as resp:
        data = await resp.json()
        print(n, resp.status, data["ip"])

async def main() -> None:
    timeout = aiohttp.ClientTimeout(total=60)
    async with aiohttp.ClientSession(timeout=timeout) as session:
        # 10 concurrent requests, each on its own connection, so each gets its own IP
        await asyncio.gather(*(fetch(session, n) for n in range(10)))

asyncio.run(main())
```

### Node.js（undici）

**JavaScript**

```javascript
// npm install undici, then save as proxy.mjs and run: node proxy.mjs
import { ProxyAgent, fetch } from "undici";

const dispatcher = new ProxyAgent("http://USERNAME-country-us:PASSWORD@gw.proxonym.com:8000");

const res = await fetch("https://api.ipify.org?format=json", {
  dispatcher,
  signal: AbortSignal.timeout(60_000),
});
console.log(res.status, await res.json());
```

该 agent 会保持长连接，因此通过同一个 `ProxyAgent` 连续发送的请求可能共用一个 IP。如需明确控制，请使用会话 ID。更多内容请见 [Node.js 集成指南](https://proxonym.com/zh/integrations/nodejs)。

### Node.js（axios 搭配 https-proxy-agent）

**JavaScript**

```javascript
// npm install axios https-proxy-agent, then run as an ES module: node proxy.mjs
import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";

const agent = new HttpsProxyAgent("http://USERNAME-country-us:PASSWORD@gw.proxonym.com:8000");

const { status, data } = await axios.get("https://api.ipify.org?format=json", {
  httpsAgent: agent,
  proxy: false, // the agent handles the proxy; turn off axios's own proxy handling
  timeout: 60_000,
});
console.log(status, data);
```

`HttpsProxyAgent` 用于处理 `https://` 目标。对于 `http://` 目标，请将 `http-proxy-agent` 包中的 `HttpProxyAgent` 作为 `httpAgent` 传入。

### PHP（cURL）

**PHP**

```php
<?php
$ch = curl_init('https://api.ipify.org?format=json');
curl_setopt_array($ch, [
    CURLOPT_PROXY          => 'http://gw.proxonym.com:8000',
    CURLOPT_PROXYUSERPWD   => 'USERNAME-country-us:PASSWORD',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT        => 60,
]);
// For SOCKS5 with remote DNS, use CURLOPT_PROXY => 'socks5h://gw.proxonym.com:1080'

$body = curl_exec($ch);
if ($body === false) {
    fwrite(STDERR, 'cURL error: ' . curl_error($ch) . PHP_EOL);
    exit(1);
}
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), ' ', $body, PHP_EOL;
```

更多内容请见 [PHP 集成指南](https://proxonym.com/zh/integrations/php)。

### Go（net/http）

**Go**

```go
package main

import (
    "fmt"
    "io"
    "log"
    "net/http"
    "net/url"
    "time"
)

func main() {
    proxyURL, err := url.Parse("http://USERNAME-country-us:PASSWORD@gw.proxonym.com:8000")
    if err != nil {
        log.Fatal(err)
    }

    client := &http.Client{
        Transport: &http.Transport{Proxy: http.ProxyURL(proxyURL)},
        Timeout:   60 * time.Second,
    }

    resp, err := client.Get("https://api.ipify.org?format=json")
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(resp.StatusCode, string(body))
}
```

更多内容请见 [Go 集成指南](https://proxonym.com/zh/integrations/go)。

### Java（HttpClient）

**Java**

```java
import java.net.Authenticator;
import java.net.InetSocketAddress;
import java.net.PasswordAuthentication;
import java.net.ProxySelector;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ProxyExample {
    public static void main(String[] args) throws Exception {
        // Java disables Basic auth for HTTPS proxy tunnels by default. Re-enable it
        // before the first HttpClient is built, or start the JVM with
        // -Djdk.http.auth.tunneling.disabledSchemes=
        System.setProperty("jdk.http.auth.tunneling.disabledSchemes", "");

        HttpClient client = HttpClient.newBuilder()
                .proxy(ProxySelector.of(new InetSocketAddress("gw.proxonym.com", 8000)))
                .authenticator(new Authenticator() {
                    @Override
                    protected PasswordAuthentication getPasswordAuthentication() {
                        if (getRequestorType() != RequestorType.PROXY) {
                            return null;
                        }
                        return new PasswordAuthentication("USERNAME-country-us", "PASSWORD".toCharArray());
                    }
                })
                .connectTimeout(Duration.ofSeconds(10))
                .build();

        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.ipify.org?format=json"))
                .timeout(Duration.ofSeconds(60))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}
```

需要 Java 11 或更高版本。将代码保存为 `ProxyExample.java`，然后运行 `java ProxyExample.java`。更多内容请见 [Java 集成指南](https://proxonym.com/zh/integrations/java)。

### C#（HttpClient）

**C#**

```csharp
// .NET 6 or later: create a console app with "dotnet new console" and replace Program.cs
using System.Net;

var handler = new HttpClientHandler
{
    Proxy = new WebProxy("http://gw.proxonym.com:8000")
    {
        Credentials = new NetworkCredential("USERNAME-country-us", "PASSWORD")
    },
    UseProxy = true
};

// Create one HttpClient per proxy configuration and reuse it
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(60) };

var body = await client.GetStringAsync("https://api.ipify.org?format=json");
Console.WriteLine(body);
```

### 浏览器与框架

其他工具的配置指南：[Scrapy](https://proxonym.com/zh/integrations/scrapy)、[Puppeteer](https://proxonym.com/zh/integrations/puppeteer)、[Playwright](https://proxonym.com/zh/integrations/playwright)、[Selenium](https://proxonym.com/zh/integrations/selenium)、[AdsPower](https://proxonym.com/zh/integrations/adspower) 和 [Multilogin](https://proxonym.com/zh/integrations/multilogin)。完整列表请见[集成](https://proxonym.com/zh/integrations)页面。

## 错误与故障排查

当代理本身拒绝请求或处理失败时，会返回下列状态码之一。其他任何状态码都来自目标网站。

### 代理状态码

| 错误码 | 含义 | 常见原因 | 解决方法 |
| --- | --- | --- | --- |
| `407` | 需要代理身份验证 | 用户名或密码错误、用户名选项有拼写错误、密码中有未经编码的特殊字符，或者（共享数据中心代理）来源 IP 不在白名单中 | 从控制台重新复制凭据，检查选项，在 URL 中对密码进行百分号编码，或将您的 IP 加入白名单 |
| `402` | 需要付款 | 流量余额已用完、套餐已过期，或子用户已达到流量上限 | 充值或续费（套餐绝不自动续费）。可通过 `GET /account` 查看余额，或提高子用户的流量上限 |
| `403` | 禁止访问 | 目标已根据[可接受使用政策](https://proxonym.com/zh/acceptable-use)被屏蔽 | 请勿重试：该屏蔽对所有账户生效。独享数据中心代理客户可通过工单咨询验证事宜 |
| `429` | 请求过多 | 触发请求速率保护：您的账户超出了约每秒 10,000 次请求的突发上限 | 降低请求频率，并使用指数退避重试 |
| `502` | 网关错误 | 上游节点失败或已离线，或者没有符合定位条件的 IP | 重试。如果反复出现，请放宽定位条件；使用粘性会话时，请换用新的会话 ID |
| `504` | 网关超时 | 目标网站在 60 秒内未响应 | 重试（最好换用新 IP），并检查目标网站是否在线 |

### 代理错误还是目标网站错误？

`403` 或 `429` 既可能来自代理，也可能来自您所请求的网站。代理错误需要您在自身配置或账户中进行修复；目标网站错误则表示该网站拒绝了请求。

- **HTTPS 目标：**代理错误会作为对 `CONNECT` 的应答返回，此时请求尚未到达目标网站。客户端会将其报告为代理错误或隧道错误，例如 cURL 的 `CONNECT tunnel failed, response 407`，或 Python 的 `ProxyError`（附带 `Tunnel connection failed: 407`）。从正常响应中读到的状态码则来自目标网站。
- **HTTP 目标：**代理的错误就是响应本身。使用 `-v` 运行 cURL，即可查看完整的交互过程。

如果目标网站用 `403`、`429` 或验证码页面拦截您，请降低请求频率、轮换 IP，并让 IP 所在国家与网站的受众相匹配。在防护严密的网站上，住宅 IP 和移动 IP 被封禁的概率低于数据中心 IP。更多内容请见我们的指南：[网页抓取如何避免被封禁](https://proxonym.com/zh/blog/web-scraping-without-getting-blocked)。

### 解决 407 错误

1. 先测试不带任何选项的凭据：`-U "USERNAME:PASSWORD"`。如果能正常使用，问题就出在选项上。
2. 检查选项：全部小写、以短横线连接、不含空格，会话 ID 为 1 到 32 位字母或数字。
3. 在代理 URL 中，对密码里的特殊字符进行百分号编码。
4. 确认白名单中的 IP 仍是您机器的公网 IP，并确认子用户的状态为 `active`。

### SSL 错误

- **`wrong version number` 或 `SSL: WRONG_VERSION_NUMBER`：**代理 URL 以 `https://` 开头。请将其改为 `http://`。代理端口使用的是普通 HTTP；与目标之间的 TLS 在隧道内进行。
- **证书验证失败：**TLS 是端到端的，因此证书来自目标网站。请更新 CA 证书包（Python 中可运行 `pip install -U certifi`），检查系统时钟，并排查您的网络中是否存在企业 TLS 检查代理。
- **仅在某个目标上握手失败：**该网站可能拒绝了您客户端的 TLS 设置。请将客户端或库更新到最新版本。

请勿在生产环境中关闭证书校验（`curl -k`、`verify=False`）。这样做会掩盖问题的根源，并使您的流量面临被拦截的风险。

### 超时

- 代理最多等待目标 60 秒，超时后返回 `504`。如果客户端设置的超时更短，您看到的将是客户端超时。
- 将连接超时设为约 10 秒，读取超时设为约 60 秒。如果 10 秒内无法连接到代理，请检查您的网络或防火墙，而不是目标网站。
- 住宅 IP 运行在真实的家庭网络上，响应速度比数据中心 IP 慢。如果延迟比 IP 类型更重要，请试试 ISP 代理或数据中心代理。
- 如果超时集中出现在某个粘性会话上，通常意味着该会话的 IP 已离线。请换用新的会话 ID。

### 连接错误

- **连接被立即拒绝或重置：**端口或协议错误。HTTP 在网关上使用 8000 端口，在共享数据中心代理上使用 3129 端口；SOCKS5 分别使用 1080 和 1081 端口。
- **卡住且无任何响应：**防火墙屏蔽了代理端口；请参阅[防火墙](https://proxonym.com/zh/docs#endpoints-and-ports-firewalls)。
- **通过 SOCKS5 时出现 DNS 错误：**请使用 `socks5h://`，让代理解析主机名。

### 获取帮助

常见问题的解答请见[帮助中心](https://proxonym.com/zh/help)。退款、IP 更换以及与您的数据相关的请求，均可在控制台的**支持**中提交；拥有有效独享数据中心套餐的账户还可以在那里提交工单。提交工单时，请附上请求时间及其时区、所用的用户名选项（切勿附上密码）、目标域名、状态码或错误信息，以及 `curl -v` 的输出（如有）。我们不通过电子邮件接收消息。

## 限制与合理使用

以下限制适用于所有账户。

| 限制项 | 限额 | 达到限额时 |
| --- | --- | --- |
| 并发连接与并发会话 | 所有产品均不限 | 不适用 |
| 请求速率 | 每个账户的突发上限约为每秒 10,000 次请求 | 代理返回 `429` |
| 目标响应时间 | 60 秒 | 代理返回 `504` |
| 粘性会话时长 | 住宅代理 120 分钟，不限流量住宅代理 720 分钟，移动代理 3 分钟 | 会话结束，新会话将使用新 IP |
| 不限流量住宅代理吞吐量 | 您套餐的速度，100 Mbps 至 1 Gbps | 总速度被限制在套餐档位以内 |
| 共享数据中心代理带宽 | 每月 250 GB、1 TB 或 5 TB，或在合理使用范围内不限量 | 额度用完后，代理返回 `402` |
| 账户 API | 每分钟 60 次请求 | API 返回 `429`，并附带 `Retry-After` |
| SERP API | 套餐的每月请求数；1 次请求返回 1 页结果 | API 返回 `403`，并附带 `quota_exceeded` |

### 可接受使用

所有流量都必须遵守法律和[可接受使用政策](https://proxonym.com/zh/acceptable-use)，一切以该政策原文为准。简而言之，Proxonym 不得用于：

- 欺诈、网络钓鱼、诈骗或任何其他非法活动；
- 未经授权的访问，例如撞库、账号盗用、暴力破解登录，或未经许可扫描系统；
- 发送垃圾信息和未经请求的群发消息；
- 拒绝服务攻击或故意使网站过载；
- 传播恶意软件或控制僵尸网络；
- 非法收集个人数据。

访问根据该政策被屏蔽的目标时，代理会返回 `403`。部分敏感用途需要先通过验证才能开通；独享数据中心代理客户可通过工单发起验证。

### 合理使用

不限流量住宅代理套餐和共享数据中心代理的不限量带宽档位均不设流量上限，但须遵守可接受使用政策中的合理使用原则。如需持续的大用量，可组合多个套餐；请参阅[面向团队的 Proxonym](https://proxonym.com/zh/enterprise)。

## 最佳实践

### 复用连接

每建立一个新连接，都需要一次 TCP 握手、一次 `CONNECT` 和一次 TLS 握手。每个任务请复用同一个客户端：一个 `requests.Session`、一个 `aiohttp.ClientSession`、一个 undici `ProxyAgent`、一个 Go `http.Client` 或一个 .NET `HttpClient`。请注意连接复用与 IP 轮换之间的相互影响：

- 复用的 HTTPS 连接会保留其隧道，因此也会保留其 IP。如果希望每个请求都使用新 IP，请每次都建立新连接，或通过会话 ID 明确控制 IP。
- 在粘性会话中，复用连接只有好处：IP 不变，握手更少。

### 使用退避策略重试

大规模运行时，出现一些失败是正常的：住宅节点会离线，响应慢的目标会超时。对于 `429`、`502`、`503`、`504` 和网络错误，请使用带随机抖动的指数退避进行重试，最多尝试 3 到 5 次。代理返回的 `402`、`403` 或 `407` 不要重试：它们需要修复，而不是再试一次。

**Python**

```python
import random
import time

import requests

PROXY = "http://USERNAME-country-us:PASSWORD@gw.proxonym.com:8000"
PROXIES = {"http": PROXY, "https": PROXY}
RETRY_STATUS = {429, 502, 503, 504}
NO_RETRY = ("402", "403", "407")

def fetch(url: str, attempts: int = 4) -> requests.Response:
    for attempt in range(1, attempts + 1):
        try:
            r = requests.get(url, proxies=PROXIES, timeout=(10, 60))
            if r.status_code not in RETRY_STATUS:
                return r
        except requests.exceptions.ProxyError as e:
            # The proxy refused the tunnel: 402, 403 and 407 need a fix, not a retry
            if any(f"failed: {code}" in str(e) for code in NO_RETRY):
                raise
        except (requests.exceptions.ConnectionError, requests.exceptions.Timeout):
            pass
        if attempt < attempts:
            time.sleep(min(30, 2 ** attempt) + random.random())  # 2, 4, 8 s plus jitter
    raise RuntimeError(f"{url}: still failing after {attempts} attempts")
```

不带会话选项时，每次重试都会使用新的 IP 发出。使用粘性会话时，如果反复出现 `502` 或 `504` 错误，请换用新的会话 ID。

### 让 IP 位置与目标匹配

- 使用位于目标市场的出口 IP：价格、排名和广告都会因国家和城市而异。
- 让请求的其余部分与 IP 保持一致：`Accept-Language`、货币，以及在浏览器中的时区和区域设置。
- 定位不要比实际需要的更精细。按国家定位的 IP 池最大，`502` 错误也最少。

### 遵守 robots.txt 和网站条款

- 采集数据之前，请阅读并遵守 `robots.txt` 和网站条款。
- 限制对每个域名的请求频率，以免您的抓取拖慢网站、影响其用户。
- 只采集公开数据，并依照适用法律处理任何个人数据。代理能提高成功率，但并不能让您规避法律或网站条款。

我们的住宅和移动 IP 来自通过合作伙伴应用和 SDK 自愿加入的用户，他们充分知情，并可随时退出。网络的构建方式请见[合规与 IP 来源](https://proxonym.com/zh/ethics)。

### 监控成功率

- 记录每个请求的状态码、目标域名、用户名选项和延迟。
- 按目标网站和国家分别跟踪成功率。某个目标的成功率下降，通常说明该网站调整了防护策略；所有目标同时下降，则问题多半出在您的配置或账户上。
- 针对代理状态码设置告警：`407` 或 `402` 增多意味着配置或计费问题，`502` 增多通常说明定位过窄，`504` 则指向响应缓慢的目标。
- 在控制台中或通过 `GET /usage` 跟踪流量，并为每个项目分配独立的子用户，以便准确归属用量。

如需为每个目标选择合适的 IP 类型，请阅读我们的[住宅代理与数据中心代理对比](https://proxonym.com/zh/blog/residential-vs-datacenter-proxies)以及[网页抓取使用场景](https://proxonym.com/zh/use-cases/web-scraping)。

- [集成](https://proxonym.com/zh/integrations): 12 款工具的分步配置指南
- [API 参考](https://proxonym.com/zh/docs/api): 账户、用量、代理列表、SERP API
