安全范围： 本指南仅适用于您自有或经授权的 QA、staging 与预发布环境。内容覆盖针对您自己 CAPTCHA 集成的诊断、测试与可观测性模式 — 不涉及第三方站点或未授权流程。
当 QA 测试覆盖多个测试账号或不同的 staging 环境时，隔离的浏览器配置文件可以防止 cookie 串扰，并提供可复现的状态。本指南聚焦自有 QA 中的配置文件管理 — 不涉及任何诊断或规避手段。
为什么 QA 需要隔离配置文件
- 防止一个测试场景的 cookies 影响另一个。
- 在每个场景中隔离测试账号。
- 在 CI 中复现一致的浏览器状态。
- 区分不同的 staging 配置。
每个配置文件应隔离什么
cookies、localStorage、sessionStorage、IndexedDB、service worker 缓存以及开发者扩展。CAPTCHA 同样会受会话状态影响，因此干净的配置文件让测试结果更稳定。
QA 配置文件状态示例
from playwright.sync_api import sync_playwright
def run(profile_dir, qa_user):
with sync_playwright() as p:
ctx = p.chromium.launch_persistent_context(
user_data_dir=profile_dir, headless=True
)
page = ctx.new_page()
page.goto('https://staging.example.com/qa-form')
# ... 在此使用 CaptchaAI 验证 CAPTCHA ...
ctx.storage_state(path=f'state-{qa_user}.json')
ctx.close()
在内部 QA suite 中集成 CaptchaAI
为每个配置文件运行同一套 CAPTCHA 流程：在 staging 页面检测 widget、提交 in.php、轮询 res.php、通过 QA backend endpoint 验证 token。结果按 profile_id 与 qa_case_id 分别记录。
故障排除
| 问题 | 处理方式 |
|---|---|
| 测试找不到 widget | 检查 staging 环境中的选择器与等待时机 |
CaptchaAI 返回 ERROR_NO_SLOT_AVAILABLE |
在内部 pipeline 中按指数退避重试 |
| 后端 QA 拒绝 token | 对照真实配置核对 action / sitekey / secret |
| 端到端时延偏高 | 在自有环境中重新测量并检查内部网络抖动 |
可观测性
为每次 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 QA 测试
- 自有表单的 CAPTCHA endpoint 测试
- 浏览器测试失败但 API 测试通过的调试
- 使用 API 解决 reCAPTCHA v2
- 使用 API 解决 Cloudflare Turnstile
- 使用 API 解决 GeeTest v3
请在自有环境中使用 CaptchaAI 验证 CAPTCHA 集成。
