# 用户名格式

> **仅适用于网关型产品——住宅代理与移动代理。** ISP 代理使用不同的凭证模式：每个 IP 以 `ip:port:user:pass` 一行的形式包含在可下载清单中。详见 [代理清单格式](/helodata-zh/chan-pin/overview-2/proxy-list-format.md)。

对于**网关型产品**，helodata 把所有定位参数——子账号、产品类型、地理、ASN、粘性会话——编码到一个代理**用户名**字符串里。密码保持不变，切换国家、切换子账号、开粘性会话时**只改用户名**。

## 完整语法

```
helo_{username}-type-{type}-region-{region}[-state-{state}][-city-{city}][-asn-{asn}][-session-{session_id}-sesstime-{ttl}]
```

| 字段                                     | 必填 | 说明                                                                                                              |
| -------------------------------------- | -- | --------------------------------------------------------------------------------------------------------------- |
| `helo_`                                | 是  | 固定前缀，用于识别凭证格式。                                                                                                  |
| `{username}`                           | 是  | **控制台 → 子账号** 中的子账号名（例如 `s1a2b3c4d5e`）。                                                                         |
| `-type-{type}`                         | 是  | 产品类型。取值：`res`（住宅）或 `mob`（移动）。                                                                                   |
| `-region-{region}`                     | 是  | ISO-3166 alpha-2 国家代码，小写（如 `us`、`de`、`jp`）。                                                                     |
| `-state-{state}`                       | 可选 | 州 / 省代码，用于更精确定位。美国州使用 2 位代码（`ca`、`ny`）。                                                                         |
| `-city-{city}`                         | 可选 | 城市 slug（小写、无空格，例如 `la`、`newyork`、`tokyo`）。                                                                      |
| `-asn-{asn}`                           | 可选 | AS 号，用于绑定运营商或 ISP（如 `2516` 代表 KDDI）。                                                                            |
| `-session-{session_id}-sesstime-{ttl}` | 可选 | 开启粘性会话。`{session_id}` 由你自定义（最长 32 个 `[a-z0-9]` 字符），`{ttl}` 为会话时长，单位**分钟**（住宅 / ISP 1–30，移动 1–60）。两段必须同时出现或同时省略。 |

各字段用单个 `-` 拼接，**必须按上表顺序出现**。出现未知字段或顺序错乱会在网关层返回 `407`，详见 [407 代理身份验证失败](/helodata-zh/gu-zhang-pai-cha/407.md)。

## 示例

| 目标                   | 用户名                                                             |
| -------------------- | --------------------------------------------------------------- |
| 基础代理（任意美国住宅出口）       | `helo_s1a2b3c4d5e-type-res-region-us`                           |
| 精确地理：美国加州洛杉矶         | `helo_s1a2b3c4d5e-type-res-region-us-state-ca-city-la`          |
| 移动，日本，KDDI（ASN 2516） | `helo_s1a2b3c4d5e-type-mob-region-jp-asn-2516`                  |
| 粘性会话：美国住宅，30 分钟      | `helo_s1a2b3c4d5e-type-res-region-us-session-abc-sesstime-30`   |
| 粘性会话：美国移动，60 分钟      | `helo_s1a2b3c4d5e-type-mob-region-us-session-job42-sesstime-60` |

## 轮换与粘性

* **省略 `session` 段** → 每条 TCP 连接获取一个新的出口 IP（轮换模式）。
* **包含 `session-XXX-sesstime-N`** → 使用相同 `session_id` 的连接会复用同一出口 IP，最长 N 分钟（粘性模式）。

同一个 `session_id` 但其他参数不同的两次请求被视为**不同**会话。请将完整用户名字符串（不仅仅是 `session_id`）作为会话键来管理。

## 用户名的使用位置

在代理 URL 中：

```
http://helo_s1a2b3c4d5e-type-res-region-us:PASSWORD@gate.helodata.io:7777
```

在 `Proxy-Authorization` 头中（Basic 认证，对 `username:password` 进行 base64 编码）：

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

## 校验工具

控制台提供[代理测试工具](/helodata-zh/zi-yuan/proxy-tester.md)，可解析任意用户名并告诉你各字段被如何识别。请求返回非预期地理或 407 时使用它排查。


---

# 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/kuai-su-ru-men/username-format.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.