会话
理解会话的生命周期、连接方式与清理策略。
目标页依赖 JavaScript、浏览器状态、截图或 Playwright 控制时创建会话。
保持 timeoutSec 显式，任务结束后主动停止会话。
只有需要持久登录态或稳定浏览器上下文时再附加档案。
什么时候创建会话
每次需要一个真实浏览器运行环境时创建会话。常见场景包括：
用 Playwright 或 Puppeteer 执行登录、点击、导航、截图和页面验证。
在调试台验证单页抓取、多页爬取、选择器、超时和产物输出。
附加浏览器档案，复用 cookies、本地存储和稳定浏览器上下文。
保留日志、回放、截图和产物，让失败运行可以复现和定位。
如果只是调用普通 HTTP API，不需要创建会话；如果目标站点依赖 JavaScript、浏览器状态或真实渲染，就应该使用会话。
会话生命周期
每个会话依次经历这些状态：
会话已申请，等待 API 分配健康运行节点。
运行节点正在启动 Chromium；如附加浏览器档案，也会同步下载状态。
Chromium 已运行，可以通过 CDP 连接并执行自动化。
停止时刷新产物、写回浏览器档案并释放运行节点资源。
如果启动或运行过程中出错，会话会进入 ERROR 状态。
默认策略：普通自动化任务显式设置 timeoutSec 并在结束后停止会话；只有人工检查才开启会话保留；只有需要登录态才附加浏览器档案；排查失败时再开启录制或保留产物。字段级请求体、默认值和响应结构见会话 API。
通过 Playwright 连接
创建会话后，使用返回的 connectUrl 连接：
import { chromium } from 'playwright-core';
const browser = await chromium.connectOverCDP(session.connectUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] || (await context.newPage());
// 然后就可以像本地浏览器一样使用
await page.goto('https://example.com');
await page.screenshot({ path: 'screenshot.png' });connectUrl 包含一次性连接令牌。流量经由连接网关路由到正确的运行节点。
停止并收集结果
使用完成后显式停止会话：
const res = await fetch(`${API}/v1/sessions/${sessionId}/stop`, {
method: 'POST',
headers: { Authorization: `Bearer ${API_KEY}` },
});停止阶段会写回可写浏览器档案、刷新待处理截图/PDF/内容提取，并释放浏览器进程和会话槽位。
如果你没有手动停止，会话会在 timeoutSec 秒后被终止。
排查建议
查状态、超时设置和运行节点健康。
确认 connectUrl 来自当前 ACTIVE 会话且令牌未过期。
查 timeoutSec、脚本异常、浏览器日志和网络事件。
确认已附加档案并允许写回；生产只保存会话 ID、终态和关键时间。字段见会话 API。