# 身份认证

helodata 住宅代理支持两种认证模式。可以在每个子账号上独立切换，并不互斥。

## 模式 A — 用户名 + 密码（默认）

在请求中传入代理用户名与密码。用户名承载全部定位参数；密码是子账号的固定值。

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

底层客户端会把 `username:password` 做 Base64 编码后发送：

```
Proxy-Authorization: Basic aGVsb19zMWEyYjNjNGQ1ZS10eXBlLXJlcy1yZWdpb24tdXM6UEFTU1dPUkQ=
```

**优点**

* 任意来源 IP 可用，无需提前部署
* 每个请求可独立指定定位（仅修改用户名）
* 通过多子账号轻松按客户隔离

**缺点**

* 凭证存在于代码或配置中，需做好保护

### 凭证写入位置

* **URL 形式** `http://user:pass@host:port` — 大多数 HTTP 客户端支持
* **`Proxy-Authorization` 头** — URL 形式不便时使用（例如浏览器 CDP）
* **环境变量** `HTTP_PROXY=http://user:pass@host:port HTTPS_PROXY=...` — 适用 curl、wget、requests 与多数 Unix 工具

## 模式 B — IP 白名单

在控制台登记出口 IP。来自这些 IP 的请求无需 `Proxy-Authorization` 头即可通过。用户名中仍需带子账号，以便定位与计费。

```bash
curl -x http://helo_s1a2b3c4d5e-type-res-region-us@gate.helodata.io:7777 \
     https://example.com
```

开启方法：

1. 进入 **控制台 → 住宅 → {子账号} → IP 白名单**。
2. 每个子账号最多添加 50 个 IPv4 地址或 CIDR 网段。
3. 修改约 60 秒内生效。

**优点**

* 没有可泄露的密钥
* 代码更整洁，无内嵌凭证

**缺点**

* 不适合出口 IP 动态变化的客户端（笔记本、移动设备、临时 CI）
* 定位仍需写入用户名，无法做到完全无凭证

## 如何选择

| 场景             | 推荐              |
| -------------- | --------------- |
| 出口 IP 固定的服务器   | IP 白名单          |
| 自动扩缩容容器（IP 可变） | 用户名 + 密码        |
| 笔记本本地开发        | 用户名 + 密码        |
| NAT 后的无头浏览器集群  | NAT 出口 IP 加入白名单 |

可以并用：生产服务器走白名单，开发机沿用用户名/密码。

## 轮换凭证

重置子账号密码：

1. **控制台 → 住宅 → {子账号} → 重置密码**。
2. 旧密码继续有效 60 秒，之后返回 `407`。
3. 更新部署。

## API

白名单与子账号凭证也可通过 [白名单 API](/helodata-zh/api-can-kao/whitelists.md) 与 [子账号 API](/helodata-zh/api-can-kao/sub-users.md) 管理。


---

# 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/authentication.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.