安全范围： 本指南仅适用于您自有或经授权的 QA、staging 与预发布环境。内容覆盖针对您自己 CAPTCHA 集成的诊断、测试与可观测性模式 — 不涉及第三方站点或未授权流程。
出口网络的丢包、抖动与时延会影响 CAPTCHA widget 的下发与求解时延。本指南演示如何在自有 QA 中度量这一影响 — 不涉及任何网络层调优或诊断回避。
安全范围
- 仅限自有出口网络。
- 在 staging 上观测网络质量对 CAPTCHA 的影响。
- 仅观测自有出口网络。
度量方法
在自有 pipeline 中并行运行 200+ 任务并记录：DNS 时间、TCP 握手、TLS 时间、首字节时间与求解总耗时。
示例脚本
import os, time, requests
API_KEY = os.environ['CAPTCHAAI_API_KEY']
def measure(sitekey, pageurl):
t0 = time.time()
r = requests.post('https://ocr.captchaai.com/in.php', data={
'key': API_KEY, 'method': 'userrecaptcha',
'googlekey': sitekey, 'pageurl': pageurl, 'json': 1,
}).json()
return time.time() - t0, r
在 QA backend 验证
把求得的 token 在内部 endpoint 上验证；记录端到端时延与 backend 状态码。
结果解读
结果仅作为您自有出口网络的参考值，可能因 CAPTCHA 类型、地区、负载与集成方式而变化，不应理解为通用保证。
故障排除
| 问题 | 处理方式 |
|---|---|
| token 在 QA 环境中过期 | 在有效期内复用，不在生产环境复用 |
| backend 拒绝 token | 比对 sitekey、action 与 secret |
| 内部缓存命中率偏低 | 检查 TTL 是否短于 token 实际有效期 |
可观测性
为每次 QA 运行生成结构化日志。建议采集的指标包括：token 总耗时、HTTP 响应码、任务编号、队列深度。把不同环境（development、staging、pre-production）写入独立通道，通过分布式追踪（例如 OpenTelemetry）关联 correlation id。能够基于单一 id 重放整个场景，会在事故排查时把诊断时间至少减半。
检查清单
- 测试范围严格限定在自有应用或经授权的资源。
- CaptchaAI key 存放在 CI secret 仓库或 vault，不进入源代码。
- 每次运行记录调用耗时与响应状态码。
- 为瞬时错误配置幂等的重试策略与上限。
- 测试可在 CI 中可复现地重复运行。
示例 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 或您自有的 QA 域名等授权环境。请在自有 staging 副本中复现生产 CAPTCHA 配置。
API key 可以写在代码里吗？
不可以。请通过 CI secret 管理器、环境变量或 vault 注入。已经提交到代码仓库的 key 必须立即轮换。
对瞬时错误你们建议什么？
幂等重试，配合指数退避（例如 1s、2s、4s）和上限。网络错误、5xx 响应和 ERROR_NO_SLOT_AVAILABLE 都适合重试；持久性的鉴权错误不应重试。
安全相关指南
请在自有环境中使用 CaptchaAI 验证 CAPTCHA 集成。
