云机 Worker 对接 API 文档

版本：v2.0.2（对齐 云机大脑-后端 / 云机大脑-前端 当前实现）

更新日期：2026-07-02

适用对象：云手机脚本、自动化 Worker、协议层以外的执行端

1. 概述

云机 Worker 通过调度大脑后端领取任务，在本地调用抖音相关能力后 上报（report） 回服务端。

系统支持两种 任务模式（task_mode / 导入时 job_mode）：

强制约定（v1.8）

>

- phone_screen（手机号筛查）：api_status=success 时 必须 上报符合规格的 PNG base64 ROI；命中 仅 由 ROI 评分裁决。不要求、不读取 api_nickname_first / api_nickname_firsts（若上报亦被忽略）。用户不存在（error_1011 / error_code=1011）不要求 ROI。

- douyin_recover（抖音号找回）：规则不变，见 §6.4；本模式 从未要求 昵称首字字段。

- 缺 ROI 或格式/尺寸错误时服务端返回 HTTP 400，msg 见 §6.8。

手机号筛查详见 §5～§7；抖音号找回详见 §9.5。

1.1 双 Worker 脚本架构（推荐）

手机号筛查 与 抖音号找回 在云机侧采用 两套独立 Worker 脚本，不合并为同一个通用脚本：

为何拆成两个脚本：

• 本地自动化流程完全不同（查号 vs 按抖音号找回）

• report 字段与成功判定逻辑不同

• 独立发版、排错、扩缩容，互不影响

部署约定：

1. 同一云机实例同一时间只跑一种 Worker，不要在同一台云机上混跑两个脚本。

2. 推荐云机池隔离：筛查任务只部署「手机号筛查 Worker」；找回任务只部署「抖音号找回 Worker」。

3. 领取任务必须使用对应专用接口（§5.1）：手机号池调用 /task/pop/phone，抖音号池调用 /task/pop/douyin；服务端仅在对应 job_mode 的 running 批次间轮询，无需每次上传任务配置 job_id。

4. pop 后仍应读取 data.task_mode 作兜底校验；若与当前脚本不符，说明云机池或接口配置错误。

5. device-info 心跳、GET /worker/proxy（若启用）、worker_key 鉴权、device_id=names 规则 两种 Worker 完全相同；差异仅在领取接口与 report Body。

┌─────────────────────┐   GET /task/pop/phone      ┌──────────┐
│ 手机号筛查 Worker 池 │ ─────────────────────────► │          │
└─────────────────────┘                            │ 调度大脑  │
                                                   │          │
┌─────────────────────┐   GET /task/pop/douyin     │          │
│ 抖音号找回 Worker 池 │ ─────────────────────────► └──────────┘
└─────────────────────┘

一号多抖音（仅 phone_screen）： 同一手机号可能绑定多个抖音账号。推荐上报 nickname_roi_base64s[] 多张 ROI，服务端取 max(roi_match_score) 判定（详见 §7.4）。无需上报 api_nickname_firsts。

手机号筛查任务：导入 JSON 须含 account_unique_key（来自抖音号找回 export）并成功绑定期望 ROI。命中判定 仅看 ROI 评分；Worker 须截取并上报 75×45 昵称 ROI PNG base64。

硬规则： 期望 ROI 必须来自找回侧 真实截图；禁止用昵称首字合成假图顶替；仅有首字、无 ROI 的账号无法进入筛查命中（详见 手机号模式-昵称ROI比对方案.md §14）。

Worker 需对接以下接口（另可选健康检查）：

旧版 GET /api/v1/task/pop 仍可用（在所有 running 批次间轮询），新部署请改用上述两个专用接口，避免混池误领。job_id 为可选调试参数，日常上传任务无需配置。

典型循环（启用出口代理时）：

                    device-info（≤60s）
┌─────────┐ ─────────────────────────► ┌──────────┐
│ 云机脚本 │                            │ 调度大脑  │
└─────────┘                            └──────────┘
     │  GET /worker/proxy（需要出口 IP 时）
     └────────────────────────────────►  配置本地代理
     │    pop     ┌──────────┐  本地查号   ┌─────────┐  report
     └──────────► │ 调度大脑  │ ─────────► │ 抖音 API │ ────────► ...
                  └──────────┘             └─────────┘
     ▲                                              │
     └────────────── 无任务则等待后重试 ───────────────┘

未启用代理网关时： 省略 GET /worker/proxy，其余流程不变。

典型循环（未启用代理）：

                    device-info（≤60s）
┌─────────┐ ─────────────────────────► ┌──────────┐
│ 云机脚本 │                            │ 调度大脑  │
└─────────┘                            └──────────┘
     │    pop     ┌──────────┐  本地查号   ┌─────────┐  report
     └──────────► │ 调度大脑  │ ─────────► │ 抖音 API │ ────────► ...
                  └──────────┘             └─────────┘
     ▲                                              │
     └────────────── 无任务则等待后重试 ───────────────┘

2. 基础信息

2.1 Base URL

所有业务接口前缀：/api/v1

2.2 鉴权：worker_key

服务端在 configs/config.yaml 中配置：

auth:
  worker_api_key: "local-e2e-worker-key"   # 生产环境请更换为强密钥

传递方式：

2.3 统一响应格式

成功时 HTTP 状态码一般为 200，Body 为 JSON：

{
  "code": 0,
  "msg": "success",
  "data": { }
}

错误时：

3. 设备标识 device_id（= Names）

统一约定： device_id 必须等于 设备信息中的 names 字段（云机实例唯一名）。

示例：

names / device_id: a3a5a0b3e1591722075c5c95da8dab20_1_T1001

看板数据模型（Admin /admin/workers）：

双状态（请勿混淆）：

看板可见条件：

前端管理端与云机 Worker 必须连接同一后端实例。本地开发时前端代理默认 http://127.0.0.1:8080。

4. 设备信息上报 — POST /api/v1/worker/device-info

云机脚本应 每 ≤ 60 秒 调用一次，上报宿主机与实例信息。管理端看板按 ip 分组 展示宿主机摘要，展开后查看该 IP 下各实例。

4.1 请求

POST /api/v1/worker/device-info?worker_key={worker_key}
Content-Type: application/json

Body（JSON）：

{
  "names": "a3a5a0b3e1591722075c5c95da8dab20_1_T1001",
  "state": "running",
  "data": "/mmc/data/data1_1780849293633",
  "index": 1,
  "ip": "192.168.1.104"
}

state=running 仅表示云手机已开机，不代表 Worker 脚本正在 pop/report。脚本是否在干活请看管理端「Worker 活跃」列。

4.2 成功响应

{
  "code": 0,
  "msg": "recorded"
}

4.3 错误示例

{
  "code": 400,
  "msg": "names required"
}

4.4 信息在线与开机状态判定（后端兜底）

管理端 不会 因 device-info 心跳缺失而误判「关机」，前提是 pop/report 仍在进行。云机侧无需额外逻辑。

典型场景：

info_inferred=true 表示当前「在线/已开机」由 Worker 活动推断，而非最新 device-info 心跳。

4.5 出口代理 — GET /api/v1/worker/proxy

云机 只对接调度大脑，不直连快代理等代理商。当管理端开启 proxy.enabled=true 且配置快代理（KDL）凭证后，云机在需要出口 IP 时调用本接口；不与 pop 捆绑，按需获取即可。

双模式并行（v2.0+）： 管理端通过 proxy.dps.enabled / proxy.tps.enabled 独立开关，可同时启用；云机通过 Query proxy_mode=dps|tps 指定产品线：

v2.0 变更： 废弃全局 proxy.mode 二选一；DPS 与 TPS 绑定在 device_proxy 中 按 (device_id, proxy_mode) 双行并存，互不影响。

云机脚本 仍解析 connection 配置本地 HTTP 代理，一般无需区分模式；若需打日志或排查，可读 proxy_mode、egress_ip（TPS 当前出口 IP，仅展示用）、kdl_order_id（启用订单池时，本次分配使用的快代理订单号）。详见 快代理-隧道代理对接文档 §9。

多订单池（proxy.pool.enabled=true）： Worker 侧 请求格式不变；后端在 getdps / 隧道解析前从 kdl_order_pool 按策略 Pick 可用订单，并将订单号写入响应 kdl_order_id 与表 device_proxy.kdl_order_id。单订单凭证（pool.enabled=false）时仍走 providers.kdl_dps / kdl_tps 静态配置，kdl_order_id 通常为空。运维见 出口代理网关-多订单池优化方案。

4.5.1 请求

GET /api/v1/worker/proxy?device_id={names}&worker_key={worker_key}&proxy_mode=dps&refresh=0

proxy_mode 缺省解析顺序： Query 合法且对应模式已启用 → 使用；否则读 default_mode；仅一种模式开启 → 用该模式；双开且无法确定 → 400 proxy_mode required。

4.5.2 成功响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "proxy_id": "a1b2c3...",
    "device_id": "a3a5a0b3e1591722075c5c95da8dab20_1_T1001",
    "host": "113.31.123.45",
    "port": 15818,
    "username": "user001",
    "password": "pass001",
    "addr": "113.31.123.45:15818",
    "connection": "113.31.123.45:15818:user001:pass001",
    "scheme": "http",
    "status": "active",
    "assigned_at": "2026-06-12T10:00:00+08:00",
    "valid_until": "2026-06-12T10:30:00+08:00",
    "remaining_seconds": 1800,
    "last_check_at": "2026-06-12T10:05:00+08:00",
    "last_check_ok": true,
    "reused": true,
    "provider": "kdl",
    "proxy_mode": "dps",
    "kdl_order_id": "987807746559625"
  }
}

TPS 模式示例（字段差异）： host / connection 中为 隧道入口（非出口 IP）；egress_ip 为当前出口 IP（可选阅读）：

{
  "code": 0,
  "msg": "success",
  "data": {
    "proxy_id": "a1b2c3...",
    "device_id": "a3a5a0b3e1591722075c5c95da8dab20_1_T1001",
    "host": "tps-xxx.kdlapi.com",
    "port": 15818,
    "username": "user001",
    "password": "pass001",
    "addr": "tps-xxx.kdlapi.com:15818",
    "connection": "tps-xxx.kdlapi.com:15818:user001:pass001",
    "scheme": "http",
    "status": "active",
    "proxy_mode": "tps",
    "egress_ip": "113.31.123.45",
    "valid_until": "2026-06-12T10:30:00+08:00",
    "remaining_seconds": 1800,
    "last_check_ok": true,
    "reused": true,
    "provider": "kdl",
    "kdl_order_id": "997807654380916"
  }
}

复用与换 IP 策略（按模式）：

管理端看板亦提供 检测 / 换 IP，行为与上表一致。

4.5.3 代理不可用

{
  "code": 50301,
  "msg": "proxy_unavailable",
  "data": null
}

含义： 代理网关未启用、凭证无效、订单池无可用 ACTIVE 订单、或代理商暂时无可用 IP。

常见原因（v2.0+）：

云机建议：

1. 不要 pop（无可用出口时不应领任务）。

2. 等待 10～30 秒后重试 GET /worker/proxy。

3. 仍失败则记录日志并告警，勿空转 pop。

4.5.4 推荐脚本顺序

# 伪代码
while True:
    post_device_info()  # 每 ≤60s

    proxy = get_proxy(device_id, proxy_mode="dps", refresh=0)
    if proxy.code == 50301:
        sleep(15)
        continue
    configure_local_proxy(proxy.data.connection)  # host:port:user:pass（DPS=出口IP，TPS=隧道入口）
    # 可选日志：proxy.data.proxy_mode, proxy.data.kdl_order_id, proxy.data.remaining_seconds

    task = pop(device_id)
    if task.code == 40401:
        sleep(3)
        continue
    result = query_douyin(task.data.phone)
    report(task.data.task_id, result)

4.5.5 connection 字段解析（云机侧）

data.connection 格式固定为 四段，以英文冒号分隔：

host:端口:账号:密码

TPS 模式下实际出口 IP 在 egress_ip 字段；配置本地 HTTP 代理时仍使用 connection 中的隧道 host:port，不要将 egress_ip 当作代理服务器地址。

解析示例（Python）：

def parse_connection(connection: str):
    host, port, username, password = connection.split(":", 3)
    return host, int(port), username, password

云机脚本建议：

1. 优先使用 connection 一次性解析；也可分别读取 host / port / username / password。

2. 按本地环境配置 HTTP 代理（scheme 默认 http，见 data.scheme）。

3. 在 remaining_seconds 接近 0 或查号失败需换 IP 时，再次调用 GET /worker/proxy?proxy_mode={mode}&refresh=1（须与当前业务使用的模式一致）。

4. 同一 (device_id, proxy_mode) 在有效期内默认复用绑定（reused=true），避免频繁换 IP 触发代理商限流。

5. 可选：读取 proxy_mode / egress_ip / kdl_order_id / remaining_seconds 写日志；配置本地代理不必分支，两种模式解析 connection 方式相同。

4.5.6 错误响应

proxy_mode required 示例：

{
  "code": 400,
  "msg": "proxy_mode required"
}

device_id required 示例：

{
  "code": 400,
  "msg": "device_id required"
}

5. 领取任务 — 双池专用接口（推荐）

手机号筛查与抖音号找回使用 两个独立领取地址。服务端仅在对应 job_mode 且 status=running 的批次间公平轮询；管理端上传并启动任务后，云机无需配置 job_id。

5.1 手机号筛查 — GET /api/v1/task/pop/phone

GET /api/v1/task/pop/phone?device_id={device_id}&worker_key={worker_key}&job_id={optional}

调度范围： 仅 job_mode=phone_screen 且 status=running 的批次。

5.2 抖音号找回 — GET /api/v1/task/pop/douyin

GET /api/v1/task/pop/douyin?device_id={device_id}&worker_key={worker_key}&job_id={optional}

参数与 §5.1 相同。

调度范围： 仅 job_mode=douyin_recover 且 status=running 的批次。

5.3 兼容接口 — GET /api/v1/task/pop（不推荐）

GET /api/v1/task/pop?device_id={device_id}&worker_key={worker_key}&job_id={optional}

在所有 running 批次（不区分 job_mode）间公平轮询。两种模式批次同时运行时可能领到错误类型任务，仅保留给旧脚本；新部署请使用 §5.1 / §5.2。

5.4 成功 — 领到任务（手机号筛查）

{
  "code": 0,
  "msg": "success",
  "data": {
    "task_id": "12345",
    "job_id": "882fb1ae-b1e6-45c6-aba5-86a8e9ae9fd4",
    "task_mode": "phone_screen",
    "uid": "104474489018",
    "phone": "15664076367",
    "bucket": "top"
  }
}

领取后的服务端状态（phone_screen）：

• 该抖音号进入 筛查中（locked）

• 该候选号进入 已派发（dispatched）

• 启动锁定时长计时（见 §8）

领取后的服务端状态（douyin_recover）：

• 该抖音号进入 筛查中（locked）

• 无候选手机号；1 抖音号 = 1 次 pop

• 启动锁定时长计时（见 §8）

5.5 成功 — 暂无任务

{
  "code": 40401,
  "msg": "no_task",
  "data": null
}

含义： 当前接口对应模式下没有可领取的待办（无 running 批次、已全部处理完毕、或指定 job_id 无待办）。

建议： 等待 2～5 秒后重试 pop，避免空转打满 CPU。

使用专用接口时：抖音号池在仅有手机号批次 running 时会收到 40401（反之亦然），属正常现象，表示该池当前无任务，不会误领另一模式任务。

5.6 错误示例

{
  "code": 400,
  "msg": "device_id required"
}

5.7 调度说明（手机号筛查 Worker）

1. 每次 pop 只返回 1 个手机号，不是一次返回整个 Top 组。

2. 同一抖音号 同一时刻只会有一条 号码处于 dispatched。

3. 未指定 job_id 时，多个同模式 running 批次按 公平轮询 分配。

4. 单批次内，候选号按 Top → Other → Segment 顺序尝试（sort_order 升序）。

5.8 抖音号找回模式 — pop 响应（douyin_recover Worker）

{
  "code": 0,
  "msg": "success",
  "data": {
    "task_id": "67890",
    "job_id": "882fb1ae-b1e6-45c6-aba5-86a8e9ae9fd4",
    "task_mode": "douyin_recover",
    "douyin_id": "Lai.1204",
    "uid": "4029078185206584"
  }
}

每个抖音号 仅 pop 一次；无 phone / bucket 字段。锁定时长与超时回收规则与 §8 相同。

6. 上报结果 — POST /api/v1/task/report

手机号筛查与抖音号找回 共用同一 report 接口，但 Body 字段与校验规则 完全不同。服务端根据 task_id 路由：

1. 先在 douyin_recover 批次中按 douyin_records.id 查找；

2. 未命中再在 phone_screen 批次中按 candidate_phones.id 查找。

pop 响应 不含 has_expected_roi 等子类型标记。Worker 须按 本池任务模式 与 管理端导入约定 选择 report 形态（见 §6.0）。

6.0 按任务模式：强制上报字段总览

PNG base64 统一规格（凡要求 ROI 时）：

6.1 请求公共约定

POST /api/v1/task/report?worker_key={worker_key}
Content-Type: application/json

成功响应：

{
  "code": 0,
  "msg": "recorded"
}

校验失败时 HTTP 400，Body 示例：{"code":400,"msg":"nickname_roi_base64 required for ROI-bound record"}（完整列表见 §6.8）。

6.2 手机号筛查 — Legacy 昵称首字（已废弃，v1.8 起不再支持）

v1.8 起：phone_screen 模式 统一为 ROI 判定，不再接受 Legacy 首字比对路径。无绑定期望 ROI 的记录在 success report 时将返回 HTTP 400（record requires ROI binding）。本节内容 仅作历史参考，新部署 Worker 请勿 再上报 api_nickname_first* 作为命中依据。

6.3 手机号筛查 — ROI 图像比对（phone_screen）

适用：管理端导入手机号 JSON 时，每条携带有效 account_unique_key 且服务端已成功绑定期望 ROI（expected_roi_path 非空）。

导入前提： 对应抖音号找回记录须已落盘真实 75×45 昵称小图。仅有昵称首字、无 recover_nickname_roi_path 时，import 无法绑定期望 ROI，该条会被 跳过，不进入筛查队列。禁止用首字「画一张假 ROI」冒充基准（见 手机号模式-昵称ROI比对方案.md §14）。

查询成功 — 仅需上报 PNG base64：

{
  "task_id": "12345",
  "device_id": "a3a5a0b3e1591722075c5c95da8dab20_1_T1001",
  "api_status": "success",
  "data": {
    "nickname_roi_base64": "iVBORw0KGgoAAAANSUhEUgAAAEsAAAAtCAIAAABpgQH6...",
    "nickname_roi_base64s": []
  }
}

一号多抖音 — 推荐多张 ROI：

{
  "task_id": "12345",
  "device_id": "a3a5a0b3e1591722075c5c95da8dab20_1_T1001",
  "api_status": "success",
  "data": {
    "nickname_roi_base64s": [
      "iVBORw0KGgoAAAANSUhEUg...",
      "iVBORw0KGgoAAAANSUhEUg..."
    ]
  }
}

用户不存在：

{
  "task_id": "12345",
  "api_status": "error_1011",
  "data": { "error_code": 1011 }
}

data.api_register_time 已废弃：Worker 无需上报。手机号筛查 命中判定仅看 roi_match_score（默认阈值 97.5，可配置 roi.pass_score）。api_nickname_first* 手机号模式不要求。

6.4 抖音号找回 — douyin_recover report

由 GET /task/pop/douyin 领到的任务，task_id = douyin_records.id（不是 candidate_phones.id）。

找回成功 — phone_prefix 与 nickname_roi_base64 均为必填：

{
  "task_id": "67890",
  "device_id": "a3a5a0b3e1591722075c5c95da8dab20_1_T1001",
  "api_status": "success",
  "data": {
    "phone_prefix": "156",
    "nickname_roi_base64": "iVBORw0KGgoAAAANSUhEUgAAAEsAAAAtCAIAAABpgQH6..."
  }
}

缺 ROI 仅报首字：不算找回完成，不能产生可用于手机号筛查的期望图绑定。历史仅有首字的数据须 补采（重跑本模式并强制截图）后再 export。

找回失败：

{
  "task_id": "67890",
  "device_id": "a3a5a0b3e1591722075c5c95da8dab20_1_T1001",
  "api_status": "recover_failed",
  "data": {}
}

6.5 管理端回写字段（ROI 绑定手机号任务）

Worker 无需上报以下字段；服务端比对后写入任务详情供运维复核：

管理端展示 查询结果（用户存在 / 不存在）由服务端根据 api_status 与 ROI 判定自动回写；Worker 无需 上报昵称首字。

6.6 api_status 约定

也可仅通过 data.error_code: 1011 表达用户不存在（与 api_status: error_1011 等效）。

6.7 重复上报（幂等）

6.8 错误示例（与后端实现一致）

通用：

{ "code": 400, "msg": "task not found" }

{ "code": 400, "msg": "invalid task_id" }

手机号 ROI 绑定：

{ "code": 400, "msg": "nickname_roi_base64 required for ROI-bound record" }

{ "code": 400, "msg": "invalid nickname_roi_base64" }

{ "code": 400, "msg": "nickname_roi must be valid PNG" }

{ "code": 400, "msg": "nickname_roi must be 75x45" }

抖音号找回：

{ "code": 400, "msg": "phone_prefix must be 3 digits" }

{ "code": 400, "msg": "nickname_roi_base64 required" }

{ "code": 400, "msg": "record not locked" }

以上 msg 为服务端 tasksvc / verify 包实际返回字符串；云机脚本应对 400 打日志并区分「缺字段」与「图像规格错误」。

7. 命中判定规则（report 后）

政策原因：不再使用注册年份 作为通过条件。

服务端按任务类型选择判定路径：

v1.8 起：手机号筛查 不再 使用昵称首字文本比对（Legacy 路径已移除）。

7.1～7.2 Legacy 昵称首字（已废弃）

v1.8 之前 JSON/JSONL 无 ROI 绑定时曾用 api_nickname_first(s) 与导入期望首字比对。当前版本不再支持；所有 phone_screen 任务须走 ROI 判定。

7.3 命中后的数据

7.4 手机号筛查 — 昵称 ROI 图像比对

当导入记录已通过 account_unique_key 绑定期望 ROI 后，手机号 report 在 api_status=success 时 必须 上报符合 §6.3 规格的 nickname_roi_base64（或 nickname_roi_base64s[]）。缺 ROI 返回 HTTP 400，不会进入评分流程。

硬门槛（V2）：

• 全图二值一致率 s2 ≥ 98%

• 左侧首字区（宽 35%）二值一致率 ≥ 95%

评分公式：

若 PNG 字节完全一致：roi_match_score = 100（L1）
否则：
  s2 = binary_match_rate × 100
  s3 = (1 - dhash_hamming / 63) × 100
  tier_bonus = (s2 ≥ 98% ? +5 : 0)    # 仅 L2 达标加分
  roi_match_score = min(100, 0.70×s2 + 0.30×s3 + tier_bonus)

一号多抖音： 对 nickname_roi_base64s[] 逐张算分，取 max 与阈值比较。

report 成功示例（手机号筛查）：

{
  "task_id": "12345",
  "device_id": "a3a5a0b3e1591722075c5c95da8dab20_1_T1001",
  "api_status": "success",
  "data": {
    "nickname_roi_base64": "iVBORw0KGgoAAAANSUhEUg...",
    "nickname_roi_base64s": ["iVBORw0KGgo...", "iVBORw0KGgo..."]
  }
}

手机号筛查 命中判定仅看 roi_match_score 与硬门槛；不要求 api_nickname_first。管理端 ROI 评分回写字段见 §6.5。

导入后缓存预扫： ES 缓存 仅 用于 user_not_exists（1011）预跳过；不再 用昵称首字预 pass/skip。须等待 Worker 实际上报 PNG base64 后评分。

与「仅有首字」的关系： 期望图必须是找回真截图。算法「首字区」= 左 35% 像素相似度，不是文本字符。禁止合成假期望图；详见方案 §14 / FAQ Q18。

8. 锁定时长与超时回收

pop 成功后，服务端对该抖音号加锁，默认 120 秒（import.lock_timeout_seconds）。

daemon 扫描间隔默认 30 秒（daemon.interval_seconds），故最坏回收时间约为 锁定时长 + 扫描间隔。

8.1 云机脚本建议

1. pop 后 尽快 report；若本地脚本约需 60 秒，当前默认 120 秒锁通常足够。

2. 本地记录 pop 时间；若接近锁超时仍无法完成，放弃本次 report，重新 pop（避免过期 report 干扰）。

3. 若脚本 P99 耗时 > 90 秒，请运维调大 lock_timeout_seconds（如 180）。

9. bucket 字段说明

bucket 不影响 命中判定规则，仅影响统计分类与尝试顺序。

9.5 抖音号找回模式（douyin_recover Worker 专章）

本节供 抖音号找回 Worker 对接；手机号筛查 Worker 无需阅读 report 字段部分。

9.5.1 管理端导入格式

管理端选择 任务模式 = 抖音号找回，上传 JSON 数组（非 JSONL）。单条结构示例：

{
  "data": {
    "buyer": {
      "douyin_id": "Lai.1204",
      "uid": "4029078185206584",
      "user_name": "不再打翻牛奶"
    }
  }
}

任务完成后 export JSON（v1.6） 会在 data.buyer 内写入 account_unique_key（32 位 hex，UI：账号唯一值），供后续手机号筛查 import 绑定 ROI。不含 ROI 原图 / base64 / 内部路径。

{
  "data": {
    "buyer": {
      "uid": "4029078185206584",
      "recover_phone_prefix": "156",
      "account_unique_key": "a1b2c3d4e5f6789012345678abcdef01"
    }
  },
  "recover_api_status": "success"
}

9.5.2 与手机号筛查的差异

9.5.3 Worker 主循环（伪代码）

# 抖音号找回 Worker — 独立脚本，部署在抖音号专用云机池
while True:
    r = requests.get(f"{BASE}/api/v1/task/pop/douyin", params={
        "device_id": NAMES,
        "worker_key": WORKER_KEY,
    }, timeout=30)
    body = r.json()
    if body["code"] == 40401:
        sleep(3)
        continue

    task = body["data"]
    if task.get("task_mode") != "douyin_recover":
        raise RuntimeError(f"unexpected task_mode: {task.get('task_mode')}")

    douyin_id = task["douyin_id"]
    task_id = task["task_id"]

    # --- 云机本地：按 douyin_id 执行找回流程，截取 75×45 昵称 ROI ---
    ok, phone_prefix, roi_png_b64 = run_douyin_recover(douyin_id)

    if ok:
        report(task_id, api_status="success", data={
            "phone_prefix": phone_prefix,           # 恰好 3 位数字
            "nickname_roi_base64": roi_png_b64,     # PNG base64，75×45
        })
    else:
        report(task_id, api_status="recover_failed", data={})

9.5.4 report 要点

• phone_prefix：恰好 3 位数字

• nickname_roi_base64：PNG base64（可带 data:image/png;base64, 前缀），尺寸 75×45，不接受 URL

• 接口路径与鉴权与手机号 Worker 相同，见 §6.3 抖音号找回 report 示例

10. 完整对接示例

10.1 cURL

设备信息心跳（≤ 60 秒一次）：

curl -s -X POST "http://127.0.0.1:8080/api/v1/worker/device-info?worker_key=local-e2e-worker-key" \
  -H "Content-Type: application/json" \
  -d '{
    "names": "a3a5a0b3e1591722075c5c95da8dab20_1_T1001",
    "state": "running",
    "data": "/mmc/data/data1_1780849293633",
    "index": 1,
    "ip": "192.168.1.104"
  }'

获取出口代理（启用代理网关时，pop 前调用）：

curl -s "http://127.0.0.1:8080/api/v1/worker/proxy?device_id=a3a5a0b3e1591722075c5c95da8dab20_1_T1001&worker_key=local-e2e-worker-key&proxy_mode=dps&refresh=0"

强制换 IP：

curl -s "http://127.0.0.1:8080/api/v1/worker/proxy?device_id=a3a5a0b3e1591722075c5c95da8dab20_1_T1001&worker_key=local-e2e-worker-key&proxy_mode=dps&refresh=1"

领取（手机号筛查 Worker）：

curl -s "http://127.0.0.1:8080/api/v1/task/pop/phone?device_id=a3a5a0b3e1591722075c5c95da8dab20_1_T1001&worker_key=local-e2e-worker-key"

上报命中（手机号筛查 / ROI）：

curl -s -X POST "http://127.0.0.1:8080/api/v1/task/report?worker_key=local-e2e-worker-key" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "12345",
    "device_id": "a3a5a0b3e1591722075c5c95da8dab20_1_T1001",
    "api_status": "success",
    "data": {
      "nickname_roi_base64": "iVBORw0KGgoAAAANSUhEUgAAAEsAAAAtCAIAAABpgQH6..."
    }
  }'

上报一号多抖音（多张 ROI）：

curl -s -X POST "http://127.0.0.1:8080/api/v1/task/report?worker_key=local-e2e-worker-key" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "12345",
    "device_id": "a3a5a0b3e1591722075c5c95da8dab20_1_T1001",
    "api_status": "success",
    "data": {
      "nickname_roi_base64s": [
        "iVBORw0KGgoAAAANSUhEUg...",
        "iVBORw0KGgoAAAANSUhEUg..."
      ]
    }
  }'

上报用户不存在：

curl -s -X POST "http://127.0.0.1:8080/api/v1/task/report?worker_key=local-e2e-worker-key" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "12345",
    "device_id": "a3a5a0b3e1591722075c5c95da8dab20_1_T1001",
    "api_status": "error_1011",
    "data": { "error_code": 1011 }
  }'

（抖音号找回 Worker）领取任务：

curl -s "http://127.0.0.1:8080/api/v1/task/pop/douyin?device_id=a3a5a0b3e1591722075c5c95da8dab20_1_T1001&worker_key=local-e2e-worker-key"

（抖音号找回 Worker）上报成功：

curl -s -X POST "http://127.0.0.1:8080/api/v1/task/report?worker_key=local-e2e-worker-key" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "67890",
    "device_id": "a3a5a0b3e1591722075c5c95da8dab20_1_T1001",
    "api_status": "success",
    "data": {
      "phone_prefix": "156",
      "nickname_roi_base64": "iVBORw0KGgoAAAANSUhEUg..."
    }
  }'

（抖音号找回 Worker）上报失败：

curl -s -X POST "http://127.0.0.1:8080/api/v1/task/report?worker_key=local-e2e-worker-key" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "67890",
    "device_id": "a3a5a0b3e1591722075c5c95da8dab20_1_T1001",
    "api_status": "recover_failed",
    "data": {}
  }'

10.2 Python 伪代码 — 手机号筛查 Worker（phone_screen）

import time
import requests
import threading

BASE = "http://127.0.0.1:8080"
WORKER_KEY = "local-e2e-worker-key"
NAMES = "a3a5a0b3e1591722075c5c95da8dab20_1_T1001"
HOST_IP = "192.168.1.104"

def heartbeat_loop():
    while True:
        requests.post(
            f"{BASE}/api/v1/worker/device-info",
            params={"worker_key": WORKER_KEY},
            json={
                "names": NAMES,
                "state": "running",
                "data": "/mmc/data/data1_1780849293633",
                "index": 1,
                "ip": HOST_IP,
            },
            timeout=30,
        ).raise_for_status()
        time.sleep(60)

threading.Thread(target=heartbeat_loop, daemon=True).start()

PROXY_ENABLED = True  # 与后端 proxy.enabled 一致；关闭时可设为 False 并跳过 get_proxy
PROXY_MODE = "dps"    # dps | tps；双模式均开启时必传，与 UI worker_proxy_mode 一致

def get_proxy(refresh: int = 0, proxy_mode: str = PROXY_MODE):
    r = requests.get(
        f"{BASE}/api/v1/worker/proxy",
        params={
            "device_id": NAMES,
            "worker_key": WORKER_KEY,
            "proxy_mode": proxy_mode,
            "refresh": refresh,
        },
        timeout=30,
    )
    r.raise_for_status()
    return r.json()

def configure_local_proxy(connection: str):
    host, port, user, password = connection.split(":", 3)
    # TODO: 写入云机系统/脚本 HTTP 代理配置
    pass

while True:
    if PROXY_ENABLED:
        body = get_proxy(refresh=0)
        if body.get("code") == 50301:
            time.sleep(15)
            continue
        if body.get("code") != 0:
            raise RuntimeError(body)
        configure_local_proxy(body["data"]["connection"])

    r = requests.get(f"{BASE}/api/v1/task/pop/phone", params={
        "device_id": NAMES,
        "worker_key": WORKER_KEY,
    }, timeout=30)
    body = r.json()

    if body.get("code") == 40401:
        time.sleep(3)
        continue

    if body.get("code") != 0:
        raise RuntimeError(body)

    task = body["data"]
    if task.get("task_mode", "phone_screen") != "phone_screen":
        raise RuntimeError(f"unexpected task_mode for phone worker: {task.get('task_mode')}")

    task_id = task["task_id"]
    phone = task["phone"]
    uid = task["uid"]

    # --- 云机本地：用 phone + uid 调抖音查询，裁切 75×45 昵称 ROI ---
    roi_png_b64, roi_png_b64_list, api_status, error_code = run_phone_lookup_roi(phone, uid)

    data = {"error_code": error_code}
    if api_status == "success":
        if roi_png_b64_list:
            data["nickname_roi_base64s"] = roi_png_b64_list
        else:
            data["nickname_roi_base64"] = roi_png_b64

    requests.post(
        f"{BASE}/api/v1/task/report",
        params={"worker_key": WORKER_KEY},
        json={
            "task_id": task_id,
            "device_id": NAMES,
            "api_status": api_status,
            "data": data,
        },
        timeout=30,
    ).raise_for_status()

v1.8：手机号筛查 不要求 上报 api_nickname_first / api_nickname_firsts；命中仅由 ROI 评分决定。

10.2.1 Python 伪代码 — 一号多抖音 ROI 片段

一号多抖音时改用 nickname_roi_base64s[] 上报多张 ROI，服务端取 max(roi_match_score)：

# 在 §10.2 report 片段中，success 时：
if api_status == "success":
    data["nickname_roi_base64s"] = roi_png_b64_list  # 多张 ROI

10.3 Python 伪代码 — 抖音号找回 Worker

完整示例见 §9.5.3；以下为与 §10.2 同结构的独立脚本骨架：

# 抖音号找回 Worker — 独立脚本，部署在找回专用云机池
while True:
    # device-info 心跳、proxy 配置与 §10.2 相同，此处省略

    r = requests.get(f"{BASE}/api/v1/task/pop/douyin", params={
        "device_id": NAMES,
        "worker_key": WORKER_KEY,
    }, timeout=30)
    body = r.json()

    if body.get("code") == 40401:
        time.sleep(3)
        continue
    if body.get("code") != 0:
        raise RuntimeError(body)

    task = body["data"]
    if task.get("task_mode") != "douyin_recover":
        raise RuntimeError(f"unexpected task_mode for recover worker: {task.get('task_mode')}")

    task_id = task["task_id"]
    douyin_id = task["douyin_id"]

    ok, phone_prefix, roi_b64 = run_douyin_recover(douyin_id)

    requests.post(
        f"{BASE}/api/v1/task/report",
        params={"worker_key": WORKER_KEY},
        json={
            "task_id": task_id,
            "device_id": NAMES,
            "api_status": "success" if ok else "recover_failed",
            "data": {
                "phone_prefix": phone_prefix,
                "nickname_roi_base64": roi_b64,
            } if ok else {},
        },
        timeout=30,
    ).raise_for_status()

11. 可选：健康检查

Worker 启动时可探测服务是否可用（无需 worker_key）：

GET /health

{
  "status": "ok",
  "mysql": "up"
}

12. 服务端配置参考

配置文件路径：云机大脑-后端/configs/config.yaml

proxy 段示例 — 双模式 + 订单池（推荐 v2.0+）：

proxy:
  enabled: true
  default_mode: dps
  dps:
    enabled: true
  tps:
    enabled: false
  default_provider: kdl
  pool:
    enabled: true
    account_secret_id: "your-account-secret-id"
    account_secret_key: "your-account-secret-key"
    sync_interval_seconds: 60
    min_ip_balance: 10
    tps_load_factor: 0.8
    max_pick_retries: 5
    strategies:
      dps: prefer_high_balance
      tps: least_devices
    alerts:
      ip_balance_warn: 100
      expire_days_warn: 7
  providers:
    kdl_dps:
      secret_id: ""          # pool.enabled=true 时可留空，由订单池提供
      signature: ""
      base_url: "https://dps.kdlapi.com"
      default_username: ""
      default_password: ""
      timeout_seconds: 15
    kdl_tps:
      secret_id: ""
      signature: ""
      tunnel_host: ""
      tunnel_port_http: 0
      auth_plaintext: true
      valid_seconds_default: 300
      timeout_seconds: 15

proxy 段示例 — 单订单 DPS（未启用订单池）：

proxy:
  enabled: true
  default_mode: dps
  dps:
    enabled: true
  tps:
    enabled: false
  default_provider: kdl
  pool:
    enabled: false
  providers:
    kdl_dps:
      secret_id: "your-dps-secret-id"
      signature: "your-dps-signature"
      base_url: "https://dps.kdlapi.com"
      default_username: "proxy_user"
      default_password: "proxy_pass"
      timeout_seconds: 15

proxy 段示例 — 单订单 TPS：

proxy:
  enabled: true
  default_mode: tps
  dps:
    enabled: false
  tps:
    enabled: true
  default_provider: kdl
  pool:
    enabled: false
  providers:
    kdl_tps:
      secret_id: "your-tps-secret-id"
      signature: "your-tps-signature"
      tunnel_host: ""              # 可选，留空则 getorderinfo 自动填充
      tunnel_port_http: 0
      auth_plaintext: true
      valid_seconds_default: 300
      timeout_seconds: 15

旧配置兼容： 若 YAML 仍使用顶层 mode: dps|tps 或 providers.kdl，启动时会自动映射到 default_mode + dps/tps.enabled，并合并到 providers.kdl_dps。

>

管理端可在 系统配置 → 出口代理 Tab，或 云机集群看板 → 出口代理配置 弹窗中配置 DPS/TPS 独立开关、default_mode、订单池与凭证；保存后走 PUT /api/v1/admin/config 热更新，无需重启。

>

代理绑定持久化于表 device_proxy（migrations/008）；v1.9 增加 proxy_mode、egress_ip（015）；v2.0 改为 uk_device_mode (device_id, proxy_mode) 双行并存，并增加 kdl_order_id（017）。订单池快照见 kdl_order_pool（016～019）。

13. 常见问题

Q1：pop 一直返回 40401 no_task？

• 确认任务批次状态为 running（管理端任务大厅可见）。

• 确认云机调用的是对应专用接口：手机号池用 /task/pop/phone，抖音号池用 /task/pop/douyin。

• 可能 ES 缓存阶段已全部命中/跳过（手机号模式），或任务已 succeeded。

• 未指定 job_id 时，确认至少有一个同模式的 running 批次。

Q2：report 成功但抖音号仍显示筛查中？

• 未命中且仍有候选号：记录会回到 pending，继续 pop 下一个。

• 仅当 命中 或 候选耗尽 时，抖音号才会 passed / failed。

Q3：api_register_time / api_nickname_first 还要填吗？

• api_register_time：不需要，云机脚本 不要上报。

• api_nickname_first / api_nickname_firsts：仅 phone_screen（手机号筛查）不要求。该模式命中 仅看 ROI；若上报首字字段，服务端 忽略。

• douyin_recover：本模式 从未要求 昵称首字；仍须 phone_prefix + nickname_roi_base64。

• 1011 表示用户不存在，不要求 ROI 与首字。

Q14：ROI 绑定 / 抖音号找回为什么必须传 base64？不传会怎样？

• 手机号筛查（§6.3）：api_status=success 时 必须 提供 nickname_roi_base64 或非空 nickname_roi_base64s[]；缺 ROI 则 HTTP 400，msg: nickname_roi_base64 required for ROI-bound record。

• 抖音号找回（§6.4）：success / recover_success 时 必须 同时提供 phone_prefix + nickname_roi_base64；缺一即 HTTP 400。

• base64 须解码为 75×45 PNG；格式/尺寸错误同样 HTTP 400（见 §6.8）。

• 用户不存在（error_1011）时 不要 传 ROI，也不要伪造昵称首字。

Q18：找回时只有昵称首字、没有 ROI 小图，能否用合成图或文本首字做高精度筛查？

• 不能。 命中闸门 仅 为找回真实截图 ROI ↔ 手机号真实截图 ROI（评分 + 硬门槛）。详见 手机号模式-昵称ROI比对方案.md §14。

• 禁止：服务端/客户端用首字字体渲染合成「假期望 ROI」；禁止恢复 Legacy「首字文本相等即命中」。

• 正确做法：对该 uid 补采——重跑 douyin_recover，强制上报 75×45 nickname_roi_base64，再 export account_unique_key 并导入手机号任务。

• 算法中的「首字区」是图像左侧约 35% 的二值相似度，不是 OCR/文本字符「张」。

• 二期可选：对实际上报 ROI 左区做 OCR 与找回首字 审计（方案 §15），不参与 HitPass；Worker 协议不变。

Q7：一个手机号绑了两个抖音，只上报一张 ROI 怎么办？

• 手机号筛查：推荐上报 nickname_roi_base64s[] 多张 ROI；服务端取 max(roi_match_score) 与阈值比较。

• 无需 上报 api_nickname_firsts；首字字段不参与判定，管理端也不再展示。

Q11：手机号 Worker 和抖音号 Worker 可以写成同一个脚本吗？

• 不推荐。 本项目约定 两套独立脚本 + 两个领取接口 + 两个云机池（见 §1.1）。

• 技术上可在同一脚本内分支，但会增加维护成本。

• 推荐做法：手机号池固定 GET /task/pop/phone，抖音号池固定 GET /task/pop/douyin；日常无需配置 job_id。

Q12：抖音号找回 Worker pop 一直 40401？

• 确认管理端已导入 抖音号找回 批次且状态为 running。

• 确认 pop 地址为 /task/pop/douyin（不是 /task/pop/phone 或旧版 /task/pop）。

• 若线上只有手机号筛查批次在跑，抖音号池会收到 40401（不会误领手机号任务）——属正常现象，待抖音批次启动即可。

• nickname_roi_base64 须为 75×45 PNG；尺寸或格式错误会 report 失败。

Q13：每次上传任务都要配置 job_id 吗？

• 不需要。 专用 pop 接口已按 job_mode 过滤调度；管理端上传并启动后，对应云机池自动领取。

• job_id 仅用于调试或强制指定单批次（可选 Query 参数）。

Q4：pop 后 60 秒才 report 有没有问题？

• 默认锁 120 秒，60 秒内 安全。

• 超过锁定时长会被回收，号码可能被其他 Worker 再次领取。

Q5：同一 task_id 可以 report 两次吗？

• 可以，第二次起服务端幂等返回成功，不重复改判。

Q6：Worker 需要 JWT 吗？

• 不需要。Worker 接口仅使用 worker_key，与用户登录 JWT 无关。

Q8：state=running 和 Worker「活跃」是一回事吗？

• 不是。 device-info 中的 state=running 表示云手机已开机。

• Worker「活跃/处理中/空闲」由 pop/report 时间窗判定，表示筛查脚本是否在接任务。

• 云机已开机但脚本未启动时，可能出现 running + Worker idle。

Q9：device-info 没按时上报，但 pop/report 还在跑，会被判关机吗？

• 不会。 后端会以 pop/report 活动作为兜底：脚本仍在领任务/上报时，推断实例仍在线、已开机（info_inferred=true）。

• 仅当心跳超时 且 pop/report 均已停滞时，才显示「信息离线」。

• 云机无需为此增加任何额外请求或逻辑。

Q10：50301 proxy_unavailable 时还能 pop 吗？

• 不建议。 应先重试 GET /worker/proxy 直至拿到可用 connection，再配置本地代理后 pop。

• 代理网关关闭（proxy.enabled=false）时，本接口恒返回 50301；若业务不需要出口代理，可跳过该接口直接 pop。

Q11：管理端点「检测」提示尚未分配代理？

• 检测仅针对 device_proxy 表中已有绑定的记录；未分配时返回 400，msg 为「该实例尚未分配出口代理…」。

• 处理方式：云机先调用 GET /worker/proxy，或管理端在实例抽屉点击 「换 IP」 主动分配。

• 看板抽屉中无 proxy_id / 出口代理列为 - 时，「检测」按钮应置灰（前端已做禁用与 Tooltip 提示）。

Q15：云机需要直连快代理吗？

• 不需要。 云机只调用调度大脑 GET /worker/proxy?proxy_mode=...；后端按请求模式内部对接 KDL：

• DPS：getdps / checkdpsvalid / getdpsvalidtime

• TPS：getorderinfo / getproxyauthorization / tpscurrentip / changetpsip

• 快代理原始 API 说明见 快代理-私密代理API对接示例、快代理-隧道代理对接文档（供运维/后端开发参考，非 Worker 必读本）。

Q16：TPS 模式下「换 IP」会影响其他云机吗？

• 会。 TPS 使用 共享隧道；refresh=1 或管理端「换 IP」会调用 changetpsip，更换的是 整条隧道的出口 IP，而非单台 device_id 独占 IP。

• 同一隧道订单下的所有云机实例会 同时 获得新出口 IP；请勿在高并发场景对多台云机连续点「换 IP」。

• DPS 模式下换 IP 为 按实例重新 getdps，互不影响（仍受代理商提取频率限制）。

Q17：响应里的 kdl_order_id / remaining_seconds 是什么？订单池和 Worker 有关系吗？

• kdl_order_id：启用 proxy.pool.enabled 时，后端从订单池 Pick 的快代理订单号，便于日志与运维对照 订单池看板；Worker 无需据此改请求参数。

• remaining_seconds：当前这次绑定的出口 剩余可用秒数（DPS≈单 IP 可用时长，TPS≈换 IP 周期），不是订单级「IP 套餐总分钟数」。接近 0 时可 refresh=1 换新绑定。

• 订单池 仅影响后端选哪张 KDL 订单出代理；Worker 仍只调 GET /worker/proxy?proxy_mode=...，与是否启用订单池无关。

14. 联调脚本

后端仓库提供 E2E 脚本，含 pop + report 完整流程：

cd 云机大脑-后端
make run          # 终端 1
./scripts/e2e_test.sh   # 终端 2

环境变量：

15. 相关文档

16. 管理端看板 API（Admin，JWT）

管理端按 宿主机 IP 分组 展示云机集群，默认仅加载摘要，展开 IP 后懒加载实例明细。需 Header：Authorization: Bearer {admin_jwt}，且用户 role=admin。

路径中的 {names} 为 URL 编码后的云机实例名（与 Worker device_id 相同），例如 a3a5a0b3e1591722075c5c95da8dab20_1_T1001。

16.1 宿主机备注 — PATCH .../hosts/{ip}

Body 示例：

{
  "alias": "机房A-03号机",
  "remark": "40 槽主力筛查机"
}

16.2 实例明细中的代理字段

GET /api/v1/admin/workers/hosts/{ip}/devices 返回的每个 devices[] 项包含 DPS / TPS 双行摘要（v2.0+）：

兼容字段（等同 proxy_dps，便于旧前端）： proxy_id、proxy_connection、proxy_status、proxy_valid_until、proxy_remaining_seconds、proxy_last_check_ok。

未分配时上述字段为空；完整 ProxyDTO（含 proxy_mode、kdl_order_id）见 §16.3 GET .../proxy。看板抽屉按模式 检测 / 换 IP。

16.3 查询实例代理 — GET .../devices/{names}/proxy

成功 — 已绑定（DPS 示例）：

{
  "code": 0,
  "data": {
    "proxy_id": "a1b2c3...",
    "device_id": "a3a5a0b3e1591722075c5c95da8dab20_1_T1001",
    "host": "113.31.123.45",
    "port": 15818,
    "username": "user001",
    "password": "pass001",
    "addr": "113.31.123.45:15818",
    "connection": "113.31.123.45:15818:user001:pass001",
    "scheme": "http",
    "status": "active",
    "proxy_mode": "dps",
    "kdl_order_id": "987807746559625",
    "valid_until": "2026-06-12T10:30:00+08:00",
    "remaining_seconds": 1800,
    "last_check_ok": true,
    "provider": "kdl"
  }
}

TPS 模式下 data 还会包含 proxy_mode: "tps"、egress_ip（当前出口 IP），且 host / connection 为隧道入口（结构同 §4.5.2）。

成功 — 未绑定： data 为 null（HTTP 200）。

16.4 检测代理 — POST .../devices/{names}/proxy/check

无 Body。后端按绑定记录的 proxy_mode 调用对应 KDL 接口，并更新 last_check_at / last_check_ok：

成功：

{
  "code": 0,
  "msg": "checked",
  "data": { "...": "同 GET proxy 的 data 结构" }
}

失败 — 尚未分配：

{
  "code": 400,
  "msg": "该实例尚未分配出口代理，请云机先调用 GET /worker/proxy 或由管理员点击「换 IP」"
}

16.5 强制换 IP — POST .../devices/{names}/proxy/refresh

无 Body。行为等同 Worker 侧 GET /worker/proxy?proxy_mode={mode}&refresh=1，按 Query proxy_mode（或 default_mode）执行：

成功后 upsert 到 device_proxy。

成功：

{
  "code": 0,
  "msg": "refreshed",
  "data": { "...": "新分配的 ProxyDTO" }
}

代理不可用：

{
  "code": 50301,
  "msg": "proxy_unavailable",
  "data": null
}

16.6 出口代理网关配置（Admin）

通过 GET/PUT /api/v1/admin/config 读写 config.proxy 对象，字段与 §12 一致。前端入口：

• 系统配置 页 → 「出口代理」Tab：DPS / TPS 独立开关 + default_mode + 订单池配置 + 凭证分块

• 出口代理 · 订单池 看板（/admin/proxy-pool）：同步、告警、订单权重/禁用

• 云机集群看板 页头 → 「出口代理配置」弹窗（同上）；抽屉内 DPS/TPS 分列 展示代理，可选 proxy_mode 后 检测 / 换 IP

保存后即时生效（热更新）。关闭某模式后该模式请求返回 50301；关闭 proxy.enabled 后 Worker 全部返回 50301。

17. 变更记录