# Proxy 端口

> URL: https://foura.ai/zh/docs/api/proxy-port
> Updated: 2026-10-15
> Index: https://foura.ai/llms.txt

可从任何支持 proxy URL 的客户端（浏览器、下载工具或现有的爬虫）将流量通过 FourA 的出口节点发送。proxy 端口会与你指定的目标建立隧道并进行双向字节传输，因此能够承载 JSON API 无法处理的内容：流传输、大文件下载以及完整的浏览器会话。

## 连接

| Setting | Value |
|---------|-------|
| Host | `proxy.foura.ai` |
| Port | `34004` |
| Protocol | 支持 Basic 认证的 HTTP CONNECT |
| Target ports | `443` and `80` |

凭据获取自控制台。在侧边栏的 **Proxy** 下创建 proxy 用户，即可获取生成的用户名和密码。凭据与 API key 刻意分开：proxy 握手在每次连接时明文传输，且轮换 proxy 用户不会影响你的 API 集成。详见 [Proxy Users](https://foura.ai/docs/dashboard/proxy)。

```bash
curl -x http://USERNAME:PASSWORD@proxy.foura.ai:34004 https://example.com
```

```python
import requests

proxy = "http://USERNAME:PASSWORD@proxy.foura.ai:34004"
r = requests.get("https://example.com", proxies={"https": proxy, "http": proxy})
print(r.status_code)
```

该端口仅支持 CONNECT。所有客户端均会对 `https://` 目标进行隧道传输。普通 `http://` 目标在客户端同样对其建立隧道时亦可正常工作（curl：`--proxytunnel`）；若客户端直接将明文请求转发给代理，则会收到 `405 Method Not Allowed`。

## 选项通过 Username 传递

凭据之后的所有内容均为 `-key-value` 键值对列表，顺序不限：

```
USERNAME-network-premium-country-de-session-a1
```

取值为小写单词。值内的连字符会启动一个新选项，因此 `-city-new-york` 会被识别为两个选项并被拒绝。未知键也会被拒绝，绝不会被忽略：拼写错误的 `-contry-de` 会返回包含支持键名称的 400 错误，而不是从错误的国家提供服务。

| 选项 | 取值 | 功能说明 |
|--------|--------|--------------|
| `network` | `shared`（默认，别名 `pool`），`premium`（别名 `residential`） | 地址来源网络。Shared 为 FourA 自身出口，包含在您的套餐中。Premium 为家庭住址，来自套餐包含的 premium 流量及您额外购买的额度。 |
| `fallback` | `premium`（别名 `residential`），`off` | 仅限共享网络。当共享网络无法承载请求时使用 premium 出口。默认关闭，且仅在套餐包含 premium 流量且额度有剩余时触发。 |
| `country` | ISO 3166-1 alpha-2，可重复 | 目标看到的出口国家。重复设置以实现多国家范围：`-country-de-country-fr`。 |
| `session` | 1 到 32 个字母、数字或下划线 | 共享同一名称的连接将共享一个地址（sticky）。省略此项则每个连接使用新地址（rotating）。 |
| `state` | 单词 | 地区。仅限 Premium。 |
| `city` | 单词 | 城市。仅限 Premium。 |
| `asn` | 数字 | 网络，按 AS 号指定。仅限 Premium。 |
| `os` | `windows`，`android`，`ios`，`mac` | 地址所属的设备类型。仅限 Premium。 |
| `lifetime` | `3` 到 `1440` | sticky premium 地址保留的分钟数。仅限 Premium。 |

除 `network`、`fallback` 和 `session` 外，每个选项均接受 `any`，用于清除该连接在 proxy 用户上保存的值。

以下三种组合会被直接拒绝并返回 400，而不是部分执行：

- 在共享网络上使用 `state`、`city`、`asn`、`os` 或 `lifetime`。共享网络仅按国家筛选，无法更细粒度定位；若要定位城市，请添加 `-network-premium`。
- `-fallback-premium` 与 `-network-premium` 同时使用。回退机制在其回退的目标网络上没有任何作用。
- 启用回退时使用更精细的定位。回退可能会或可能不会触发，因此仅能偶尔满足的城市定位会被拒绝。

### 会话

在共享网络上，只要您持续使用，命名会话将在 10 分钟滑动窗口内保留相同的出口。如果该出口停止工作，会话将迁移到另一个出口而不是直接失败。通过该端口控制的浏览器应始终携带会话名称：页面加载会打开数十个连接，如果没有会话，每个连接都会从不同的地址发出。

在 premium 网络上，命名会话将其地址保留 `lifetime` 分钟，或者在未设置时采用网络默认值。

### 保存的默认值

在控制台中为 proxy 用户保存的定向配置会应用于该用户建立的每个连接，因此用户名可以保持简短。在用户名中指定的任何选项都会优先应用于该次连接，而 `any` 会恢复已保存的值。已保存的高级默认配置仅在您的套餐允许时产生费用；否则连接将通过共享网络提供，隧道仍会正常建立。

### CONNECT header

能够在 CONNECT request 中添加 header 的客户端，可以将相同的选项作为 header 发送。header 的优先级高于用户名中的相同选项。

| Header | 等同于 |
|--------|---------|
| `X-Foura-Network` | `-network-` |
| `X-Foura-Fallback` | `-fallback-` (`premium` 或 `off`) |
| `X-Foura-Country` | `-country-`，多个值用逗号分隔 |
| `X-Foura-Session` | `-session-` |
| `X-Foura-State` | `-state-` |
| `X-Foura-City` | `-city-` |
| `X-Foura-Asn` | `-asn-` |
| `X-Foura-Lifetime` | `-lifetime-` |

```bash
curl -x http://USERNAME:PASSWORD@proxy.foura.ai:34004 \
  --proxy-header "X-Foura-Country: de" \
  https://example.com
```

## 响应

成功开启的隧道会返回 `200 Connection established`。在凭证验证通过后返回的所有拒绝响应都会附带一个包含单行原因的 `X-Foura-Error` 响应头，因此请优先读取该 header。

| 状态码 | 触发场景 |
|--------|------|
| 400 Bad Request | 格式错误的请求，或 FourA 无法支持的选项。`X-Foura-Error` 会明确指出该选项及所支持的值。 |
| 403 Forbidden | 目标端口未提供服务、目标并非公共互联网主机、端口未包含在您的套餐中，或者您指定了 `-network-premium` 但套餐的高级流量已耗尽或未包含高级网络。 |
| 405 Method Not Allowed | 发送了普通请求而非 CONNECT 请求。 |
| 407 Proxy Authentication Required | 凭证缺失或错误。响应从不指明具体哪一部分出错。 |
| 408 Request Timeout | 客户端已连接但在 15 秒内未发送任何内容。 |
| 431 Request Header Fields Too Large | CONNECT 请求的 header 大小超过 16 KB。 |
| 429 Too Many Requests | 达到套餐的某项额度上限：同时开启的隧道数、每分钟开启隧道数或当前账单周期的标准流量。端口本身达到容量上限或开启速率限制时也会触发。`X-Foura-Error` 会指明具体原因。 |
| 502 Bad Gateway | 在选择预算内未能为该目标找到可用出口，或 FourA 自身的解析器无法解析该主机。这两者在 `X-Foura-Error` 中显示为不同的消息。 |
| 503 Service Unavailable | 代理端口已关闭。 |

## 限制

- 同时开启的隧道数和每分钟开启隧道数取决于您的套餐，且按账户而非单个代理用户进行计算：签发第二组凭证不会增加配额。您的具体配额显示在 [用量与限制](https://foura.ai/docs/dashboard/quota) 页面。
- 寻找出口最多需要 45 秒，超时后端口将返回 502 错误并放弃尝试。已有分配出口的会话通常在远低于一秒内即可完成连接。
- 双向均无数据传输的隧道将在空闲两分钟后关闭。
- 端口更新时，已开启的隧道有略少于三分钟的时间完成传输，随后将被关闭，期间新连接仍可正常建立。长时间的下载或流式传输应在隧道关闭后重新连接。
- 在控制台中停用或删除的代理用户将在单分钟内停止通过身份验证。

## 计量

通过端口的字节数计入您 [用量与限制](https://foura.ai/docs/dashboard/quota) 页面中的带宽，通过高级出口的字节数同时计入高级流量：相同的字节数会被分别统计两次，而非相加叠加。隧道开启时，端口尝试过但最终未采用的高级出口流量也会计入高级流量。未使用的共享网络尝试不予计入，且隧道未开启时不会计入任何流量。

端口可使用的标准流量由您的套餐决定。在按积分计费的套餐中，端口包含独立的可用 GB 额度，您也可以在“账单”页面购买更多额度；在按流量计费的套餐中，端口与 API 共享同一流量池。当额度耗尽时，系统将拒绝新连接，直到周期重置或您购买了更多额度，用量通知邮件中会说明具体时间。

一旦高级额度耗尽，接入该网络的三种方式会故意返回不同的响应。指定了 `-network-premium` 的连接将被拒绝并返回 403 明确说明，因为如果调用方请求付费使用却被静默降级路由，就会持续发起请求并对账实际上未生效的高级线路。系统不会执行回退，并且代理用户保存的高级默认配置会降级到共享网络，但仍会建立隧道：因为这两种情况均未明确选择在本次连接上消费额度。

## 相关内容

- [代理用户](https://foura.ai/docs/dashboard/proxy)：在控制面板中创建代理用户并构建连接字符串
- [代理请求](https://foura.ai/docs/api/endpoints#proxy-request)：基于 JSON API 的替代方案，内置重试和验证
- [跨请求复用代理](https://foura.ai/docs/how-to/reuse-a-proxy)：在 JSON API 上保持单一出口
- [用量与限制](https://foura.ai/docs/dashboard/quota)：套餐对应的带宽和高级流量配额