代理子账号

子账号的字段、状态机、流量上限的双层约束，以及怎么用它做团队和任务隔离。

子账号是接入代理的基本单位——凭据、流量上限、白名单、API Key 都挂在它上面。一个用户默认最多 10 个。

字段

字段	说明
`proxyUsername` / `proxyPassword`	接入网关用的凭据
`productId`	绑定的产品线
`trafficUnlimited`	是否不设独立上限（只受用户流量池约束）
`trafficLimitBytes`	独立流量上限，范围 1 MB – 1 TB
`trafficUsedBytes`	已用量
`status`	`active` / `disabled` / `deleted`
`remark`	备注
`expiresAt`	过期时间（模型里有，但客户接口没有设置入口）

流量上限是两层

两个数任意一个见底都会被拒

网关放行时算的是：

text

有效余额 = min(用户流量池剩余, 子账号上限 − 子账号已用)

所以子账号设了上限时，用户池里还有量也不代表这个子账号能用。反过来，子账号选了"不限量"也不代表真的无限——它仍然受用户流量池约束。

两种配置的适用场景：

trafficUnlimited: true —— 只受流量池约束。适合你自己用的主力子账号，不需要额外限制。

trafficUnlimited: false + trafficLimitBytes —— 给这个子账号划一个上限。适合分给团队成员或某个具体任务，防止一个任务把整个流量池跑光。

状态机

text

创建 → active
active ⇄ disabled     （API 可双向切换）
active/disabled → deleted   （DELETE 是软删除，不可逆）

停用账号在密码正确时返回 403 account_disabled。已删除账号的凭据不再有效；账号记录不存在或密码不匹配时统一返回 407 invalid_credentials。请复制仍有效账号的原始凭据。流量耗尽另返回 402，不能靠重新输入密码解决。

删除是软删除——记录还在，用量历史保留，只是状态改成 deleted 并且不再能用。

创建

POST/api/v1/proxy/accounts

shell

curl -X POST 'https://api.example.com/api/v1/proxy/accounts' \
  -H 'Authorization: Bearer at_YOUR_ACCESS_TOKEN' \
  -H 'Origin: https://console.example.com' \
  -H 'Content-Type: application/json' \
  -d '{
    "productId": "residential_dynamic",
    "remark": "采集任务 A",
    "trafficUnlimited": false,
    "trafficLimitBytes": 10737418240
  }'

10737418240 是 10 GB。

列表、修改、删除

GET/api/v1/proxy/accounts

PATCH/api/v1/proxy/accounts/:id

shell

# 停用一个子账号
curl -X PATCH 'https://api.example.com/api/v1/proxy/accounts/ACCOUNT_ID' \
  -H 'Authorization: Bearer at_YOUR_ACCESS_TOKEN' \
  -H 'Origin: https://console.example.com' \
  -H 'Content-Type: application/json' \
  -d '{"status":"disabled"}'

DELETE/api/v1/proxy/accounts/:id

数量限制

每个用户最多 10 个子账号。超了返回 HTTP 409，错误码 proxy_account_limit_reached。

注册后前 24 小时内最多创建 2 个子账号。过了观察期恢复到 10 个。

这是风控措施。刚注册就想批量建子账号会被挡住。

每个子账号挂的东西

资源	上限
API Key	1 个（一账号恰好一个）
IP 白名单	10 条
并发连接	默认 5,000

注意白名单和 API Key 都是每子账号的额度，不是每用户。所以多建子账号能获得更多白名单额度——不过通常你不需要。

用子账号做隔离

按任务隔离

text

子账号 A：采集任务，上限 50 GB
子账号 B：账号运营，上限 5 GB
子账号 C：监控探测，上限 1 GB

好处是任何一个任务出问题（死循环、目标站返回大响应）都不会把整个流量池跑光，而且用量统计能分开看。

按团队成员隔离

给每个人一个子账号，各自的凭据和上限：

python

def provision_member(client, member: str, quota_gb: int) -> dict:
    """为团队成员开一个受限的子账号。"""
    return client.post("/api/v1/proxy/accounts", {
        "productId": "residential_dynamic",
        "remark": f"member:{member}",
        "trafficUnlimited": False,
        "trafficLimitBytes": quota_gb * 1024 ** 3,
    })


for name, quota in [("alice", 20), ("bob", 10), ("carol", 10)]:
    account = provision_member(client, name, quota)
    print(name, account["proxyUsername"])

按地区隔离？不需要

地区是请求时通过用户名参数指定的，不是绑在子账号上的。一个子账号能访问所有它被授权的地区：

shell

# 同一个子账号，不同地区
curl -x 'http://SAME_USER-country-US:PASS@GATEWAY_HOST:58971' ...
curl -x 'http://SAME_USER-country-DE:PASS@GATEWAY_HOST:58971' ...

所以不要为了多个地区去建多个子账号。

凭据泄露了怎么办

子账号凭据泄露的话，最快的处置是停用：

shell

curl -X PATCH 'https://api.example.com/api/v1/proxy/accounts/ACCOUNT_ID' \
  -H 'Authorization: Bearer at_YOUR_ACCESS_TOKEN' \
  -H 'Origin: https://console.example.com' \
  -H 'Content-Type: application/json' \
  -d '{"status":"disabled"}'

然后新建一个子账号替换。已产生的用量无法追回，但停用会立即阻止后续消耗。

这一类的其他文档