在自有 QA pipeline 中处理 CAPTCHA

安全范围： 本指南仅适用于你自有或经授权的 QA、staging 与预发布环境。内容覆盖针对你自己 CAPTCHA 集成的诊断、测试与可观测性模式 — 不涉及第三方站点或未授权流程。

CI 流水线跑到登录或注册这一步，常卡在一个 CAPTCHA widget 上。测试环境往往和生产共用同一套验证码配置，一遇到 reCAPTCHA、Turnstile 或图片验证码就直接超时失败。本文只讲一件事：如何在自己的 QA、staging 环境里，把 CAPTCHA 处理做成流水线中稳定的一环。

CAPTCHA 处理流程：从检测 widget 到拿到 token

整体流程分四步：

1. 在 staging 页面检测 CAPTCHA widget。
2. 提交任务给 CaptchaAI。
3. 轮询等待 token。
4. 把 token 交给 QA 后端验证。

例如某电商团队测试注册流程时，staging 环境保留了和生产一致的 Turnstile 组件。脚本定位 widget、取出 sitekey，换回 token 后连同表单字段一起提交给内部接口断言。

重试与追踪：把失败原因和结果对上号

重试策略

按 qa_case_id 限制每个用例的重试次数，用指数退避控制间隔（如 1s、2s、4s）。每次重试都落一条日志，标明触发原因，区分网络抖动、CaptchaAI 侧繁忙还是配置写错。

token 追踪

把每个 token 和消费它的 qa_case_id 绑成一对，记录提交与验证各自的耗时。某个用例变慢时，能立刻定位瓶颈，而不是笼统地说“CAPTCHA 慢”。

CAPTCHA 常见故障排查

可观测性：结构化日志与分布式追踪

为每次 QA 运行生成结构化日志，采集 token 总耗时、HTTP 响应码、任务编号、队列深度，并用 OpenTelemetry 关联 correlation id，方便按 id 重放场景。

上线前检查清单

1. 测试范围严格限定在自有应用或已获授权的资源上。
2. CaptchaAI key 存放在 CI secret 仓库或 vault，绝不进源代码。
3. 每次运行记录调用耗时和响应状态码。
4. 瞬时错误配置幂等重试策略，并设好上限。
5. 测试能在 CI 中可复现地反复跑。

Python 示例：最小可运行的 CAPTCHA QA 调用

下面这段 Python 展示了在自有 staging 环境里，用 CaptchaAI 测试一个 CAPTCHA widget 的最小流程。

import os
import requests

API_KEY = os.environ['CAPTCHAAI_KEY']
QA_PAGE_URL = os.environ['QA_PAGE_URL']  # 例如 https://staging.example.com/qa-login
QA_SITE_KEY = os.environ['QA_SITE_KEY']


def submit_qa_recaptcha() -> str:
    payload = {
        'clientKey': API_KEY,
        'task': {
            'type': 'NoCaptchaTaskProxyless',
            'websiteURL': QA_PAGE_URL,
            'websiteKey': QA_SITE_KEY,
        },
    }
    response = requests.post(
        'https://api.captchaai.com/createTask',
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()['taskId']


def fetch_qa_result(task_id: str) -> dict:
    payload = {'clientKey': API_KEY, 'taskId': task_id}
    response = requests.post(
        'https://api.captchaai.com/getTaskResult',
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

常见问题

这套流程会不会碰到生产流量？

不会。所有示例都假设跑在 staging.example.com 这类已获授权环境里，不直接对生产环境跑测试。

CaptchaAI key 能直接写在测试脚本里吗？

不行。要通过 CI secret 管理器或 vault 注入；已提交进代码仓库的 key 必须立刻轮换。

轮询超时或 ERROR_NO_SLOT_AVAILABLE 该怎么处理？

用幂等重试配合指数退避（比如 1s、2s、4s）加上重试上限；持久性的鉴权错误（key 无效、余额为零）不应重试。

更多 CAPTCHA QA 指南

• CaptchaAI 快速入门
• 授权 QA 测试指南
• 表单 CAPTCHA 接口测试
• 浏览器测试失败排查
• API 解决 reCAPTCHA v2
• API 解决 Cloudflare Turnstile
• API 解决 GeeTest v3

在你自己的环境里，用 CaptchaAI 验证这套 CAPTCHA 处理流程。