# 协议

住宅网关在同一端口上同时支持 HTTP、HTTPS、SOCKS5，由客户端握手自动识别，无需服务端配置。

## HTTP / HTTPS

兼容性最广。`http://` 与 `https://` 目标都可通过同一连接访问。

```bash
# HTTP 目标
curl -x http://helo_s1a2b3c4d5e-type-res-region-us:PASSWORD@gate.helodata.io:7777 \
     http://example.com

# HTTPS 目标（到目标的 TLS 端到端）
curl -x http://helo_s1a2b3c4d5e-type-res-region-us:PASSWORD@gate.helodata.io:7777 \
     https://example.com
```

访问 HTTPS 目标时，客户端会向代理发送 `CONNECT example.com:443` 打通 TCP 隧道，helodata 看不到请求体。

## SOCKS5

非 HTTP 流量（裸 TCP、部分数据库客户端、自定义协议）必须使用 SOCKS5；部分爬虫栈也因为开销略低而偏爱它。

```bash
curl --socks5-hostname helo_s1a2b3c4d5e-type-res-region-us:PASSWORD@gate.helodata.io:7777 \
     https://ipv4.icanhazip.com
```

务必使用 `--socks5-hostname`（而非 `--socks5`）让代理做 DNS 解析——否则客户端本地解析，会泄露 DNS，且导致地理定位失败。

### Python SOCKS5

```python
import requests

USER = "helo_s1a2b3c4d5e-type-res-region-us"
PASS = "PASSWORD"
proxy = f"socks5h://{USER}:{PASS}@gate.helodata.io:7777"

r = requests.get(
    "https://ipv4.icanhazip.com",
    proxies={"http": proxy, "https": proxy},
    timeout=30,
)
```

注意是 `socks5h://`（多一个 `h`），等同于 `--socks5-hostname`，强制远端解析。

### Node.js SOCKS5

```js
import { SocksProxyAgent } from "socks-proxy-agent";
import fetch from "node-fetch";

const agent = new SocksProxyAgent(
  "socks5://helo_s1a2b3c4d5e-type-res-region-us:PASSWORD@gate.helodata.io:7777"
);
const res = await fetch("https://ipv4.icanhazip.com", { agent });
```

## 如何选择

| 场景                                    | 推荐                                       |
| ------------------------------------- | ---------------------------------------- |
| 标准 HTTP/HTTPS 采集                      | HTTP/HTTPS                               |
| 浏览器自动化（Selenium、Playwright、Puppeteer） | HTTP/HTTPS                               |
| 裸 TCP、MQTT、自定义协议                      | SOCKS5                                   |
| 追求最大吞吐与最小开销                           | SOCKS5                                   |
| 便于调试                                  | HTTP/HTTPS — 可用 `mitmproxy`、浏览器 devtools |

## 不支持的协议

* **SOCKS4 / SOCKS4a** — 请改用 SOCKS5
* **到网关的 HTTP/3 (QUIC)** — 但目标站点仍可通过隧道提供 HTTP/3
* **明文（非 TLS）认证暴露在公网** — 客户端总会做 Base64 编码；敏感场景请通过 TLS 连接网关（同一端口 `7777`，网关自动识别）

## 常见陷阱

* **SOCKS5 DNS 泄露** — 始终使用 `socks5h://` / `--socks5-hostname` 让代理解析
* **库要求 `http://` 代理 URL 却访问 HTTPS 目标** — 这是正常现象，只有目标 URL 是 HTTPS
* **`curl` 忽略 `HTTPS_PROXY`** — 同时设置 `HTTP_PROXY` 与 `HTTPS_PROXY`，部分 Unix 还需要设置小写形式


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/helodata-zh/chan-pin/overview/protocols.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.