Nstproxy 现已升级为 Nstdata。了解此次变化。
周一至周五 09:00 - 18:00(UTC+08:00) 公司地址
19H MAXGRAND PLAZA NO.3 TAI YAU STREET SAN PO KONG, KOWLOON HONG KONG ©2026 NST LABS TECH LTD. 保留所有权利。
浏览器会话生命周期:创建、重连和停止
Ivy Lin Community & Content Lead
云浏览器会话管理:安全地创建、重新连接和停止 TL;DR
云浏览器会话生命周期跟踪被管理的浏览器资源,与网站登录或客户端连接无关。
在发送会话创建请求之前,保持 UUID v4 requestId 和完整的创建主体。
使用相同的 ID 和相同的主体重试不确定的创建;更改配置需要新的 ID。
ready 意味着浏览器可以进行连接,而不是您的业务任务已成功。
刷新实时视图或重新连接 CDP 不会重置浏览器的生命周期。
停止请求仅在原始会话达到 ended 时才完成;stopping 是中间状态。
什么是浏览器会话生命周期?
浏览器会话生命周期是一个受管浏览器从创建到终止所经历的状态序列。它描述了您的自动化所消耗的资源。网站身份验证会话描述特定网站是否认为用户已登录,而 CDP 客户端连接描述您的程序是否当前已连接。这三个生命周期可以独立结束。
Nstdata Cloud Browser 提供用于浏览器自动化和 AI 代理的受管云浏览器。显式管理该资源使团队能够从工作失败中恢复,协调人工交接,并在页面任务完成后考虑运行时。Cloud Browser 介绍 提供产品背景;本指南专注于实际作业运行器所需的所有权和状态转换。
例如,您的脚本可能在浏览器仍然准备好并登录到应用程序时失去 WebSocket。相反,socket 可以在网站过期登录时保持连接。单个 success 标志无法准确表示这两种条件。
您的应用程序应该处理哪些状态?
您的应用程序应该处理来自会话响应的 state 字段中的 creating、unknown、ready、stopping、ended 和 failed。请不要查找未记录的 status 字段或从预览图像中推断资源状态。
unknown当前资源状态不确定 调和原始操作;避免重复创建
ready浏览器可以接受连接 获取凭据并验证任务的页面状态
failed资源失败 捕获失败上下文并在新尝试之前解决清理工作
当前的 浏览器自动化 API 指南 是这些值的合同。保持一个单独的应用程序任务状态,例如等待人工、工作、接受或拒绝。这些是您自己的作业状态,而不是额外的 Cloud Browser API 状态。
您需要哪些端点和参数? 您需要位于 https://api.nstdata.io/api/v1/cloud-browser 下的选项、创建、检查、凭据发放和删除端点。在构建创建主体之前检索当前选项,因为资源类、国家和允许的持续时间取决于当前服务配置。
方法和路径 目的 重要字段 GET /sessions/options查找有效配置 resourceClasses、proxyCountries、defaults、sessionPOST /sessions创建或重试相同意图 requestId、name、resourceClass、proxyCountry、ttlSecondsGET /sessions/{sessionId}检查原始会话 响应 state POST /sessions/{sessionId}/automation-credentials附加自动化客户端 cdpUrl、headerName、accessToken、expiresAtDELETE /sessions/{sessionId}请求关闭 通过后续检查确认 ended
创建示例还提供 targetUrl、recording: false 和 captchaSolver: { enabled: false }。在自定义时审核创建响应中的 warnings 和 effectiveConfiguration。配置警告值得调查,才能允许作业执行有意义的工作。
在生命周期 HTTP 调用中使用 x-api-key 而不是 Bearer。在 Settings → Account 下获取个人密钥,或在 Members 下获取绑定团队成员密钥。使用个人密钥时,可选的 x-team-id 选择已加入的团队;在每个请求中保持相同的值。CDP 凭据单独发放,绝不应保存在作业记录中。
如何创建和停止会话,同时避免重复创建? 创建和停止会话时,请通过在创建之前持久化预期请求来安全地完成此操作,并保留返回的会话 ID,并将关闭视为确认的状态转换。此示例故意将命令分开,以便被中断的工作者可以恢复其现有意图。
步骤 1:准备 Node.js 项目 使用 Node.js 22.12 或更高版本并创建工作目录。生命周期控制器使用内置 Node API,并不安装浏览器客户端。
mkdir browser-lifecycle-demo
cd browser-lifecycle-demo
创建一个私有的 .env 文件,其中包含 NSTDATA_API_KEY 和(仅在需要时)NSTDATA_TEAM_ID。将 .env 文件和生成的作业记录排除在版本控制之外。在其自己的目录中运行每个作业,或者选择一个不同的 JOB_FILE 路径。
步骤 2:保存 HTTP 辅助工具 将此模块保存为 cloud-api.mjs。它验证响应信封并避免打印可能包含敏感数据的原始服务器消息。Node 的 AbortSignal timeout 独立于浏览器生命周期界定每个请求。
凭据先决条件: 这些 HTTP 请求需要一个 Nstdata 商业密钥。API 行为经过当前文档和合成状态转换测试的检查;本文不声称进行实时管理帐户运行。
const root = 'https://api.nstdata.io/api/v1/cloud-browser' ;
export async function api ( method , path , body ) {
const key = process . env . NSTDATA_API_KEY ;
if ( ! key ) throw new Error ( 'Set NSTDATA_API_KEY' ) ;
const headers = { 'x-api-key' : key } ;
if ( process . env . NSTDATA_TEAM_ID ) headers [ 'x-team-id' ] = process . env . NSTDATA_TEAM_ID ;
if ( body ) headers [ 'content-type' ] = 'application/json' ;
let response ;
try {
response = await fetch ( root + path , {
method , headers , redirect : 'error' ,
body : body ? JSON . stringify ( body ) : undefined ,
signal : AbortSignal . timeout ( 20_000 ) ,
} ) ;
} catch {
throw Object . assign ( new Error ( 'API transport failed; reconcile the original operation' ) , { retryable : true } ) ;
}
const retryable = response . status === 429 || response . status >= 500 ;
let result ;
try { result = await response . json ( ) ; }
catch { throw Object . assign ( new Error ( 'Invalid API JSON' ) , { retryable } ) ; }
if ( ! response . ok || result . err === true || result . success === false ) {
throw Object . assign ( new Error ( ` Cloud Browser API HTTP ${ response . status } ` ) , { retryable } ) ;
}
if ( ! result . data ) throw new Error ( 'Missing API data' ) ;
return result . data ;
}
export async function connection ( id ) {
if ( ! id ) throw new Error ( 'Set NSTDATA_SESSION_ID' ) ;
const path = ` /sessions/ ${ encodeURIComponent ( id ) } ` ;
const session = await api ( 'GET' , path ) ;
if ( session . state !== 'ready' ) throw new Error ( ` Session is ${ session . state } , not ready ` ) ;
const c = await api ( 'POST' , path + '/automation-credentials' ) ;
if ( c . sessionId !== id || ! c . headerName || ! c . accessToken ||
! ( Date . parse ( c . expiresAt ) > Date . now ( ) ) || new URL ( c . cdpUrl ) . protocol !== 'wss:' ) {
throw new Error ( 'Invalid or expired CDP credentials' ) ;
}
return {
endpoint : c . cdpUrl ,
headers : { [ c . headerName ] : c . headerName . toLowerCase ( ) === 'authorization'
? ` Bearer ${ c . accessToken } ` : c . accessToken } ,
} ;
}
export async function endpoint ( ) {
// An isolated local CDP endpoint can test the client without managed credentials.
if ( process . env . LOCAL_CDP_URL ) {
const url = new URL ( process . env . LOCAL_CDP_URL ) ;
if ( ! [ '127.0.0.1' , 'localhost' , '[::1]' ] . includes ( url . hostname ) ) {
throw new Error ( 'LOCAL_CDP_URL must use loopback' ) ;
}
return { endpoint : url . href , headers : { } } ;
}
return connection ( process . env . NSTDATA_SESSION_ID ) ;
}
步骤 3:保存可恢复控制器 将以下代码保存为 lifecycle.mjs。控制器专门创建本地记录,并拒绝覆盖现有意图。它的重试循环重复使用存储的主体,包括使用 Node.js randomUUID 生成的相同 UUID。
凭据先决条件: API 分支要求您的工作区密钥。恢复和重复创建行为通过一个明显分开的 HTTP 夹具进行了测试,而不是以 Nstdata 服务输出的形式呈现。
import { randomUUID } from 'node:crypto' ;
import { readFile , writeFile } from 'node:fs/promises' ;
import { setTimeout as delay } from 'node:timers/promises' ;
import { api } from './cloud-api.mjs' ;
const file = process . env . JOB_FILE || 'browser-job.json' ;
const pathFor = id => ` /sessions/ ${ encodeURIComponent ( id ) } ` ;
const save = job => writeFile ( file , JSON . stringify ( job , null , 2 ) , { mode : 0o600 } ) ;
async function retry ( operation ) {
for ( let attempt = 0 ; ; attempt ++ ) {
try { return await operation ( ) ; }
catch ( error ) {
if ( ! error . retryable || attempt === 2 ) throw error ;
await delay ( 500 * 2 ** attempt + Math . random ( ) * 250 ) ;
}
}
}
async function wait ( id , expected ) {
const deadline = Date . now ( ) + 90_000 ;
while ( Date . now ( ) < deadline ) {
const session = await retry ( ( ) => api ( 'GET' , pathFor ( id ) ) ) ;
if ( session . state === expected ) return session ;
if ( [ 'ended' , 'failed' ] . includes ( session . state ) ) {
throw new Error ( ` Session ${ session . state } ; expected ${ expected } ` ) ;
}
await delay ( 2_000 ) ;
}
throw new Error ( 'State wait expired; inspect the original session' ) ;
}
const command = process . argv [ 2 ] ;
if ( command === 'create' ) {
const options = await api ( 'GET' , '/sessions/options' ) ;
const { resourceClass , proxyCountry , ttlSeconds } = options . defaults ;
if ( ! options . resourceClasses . some ( x => x . value === resourceClass ) ||
! options . proxyCountries . some ( x => x . value === proxyCountry ) ||
! Number . isInteger ( ttlSeconds ) || ttlSeconds < options . session . minSeconds ||
ttlSeconds > options . session . maxSeconds ) throw new Error ( 'Inspect current options' ) ;
const job = { body : { requestId : randomUUID ( ) , name : 'lifecycle-demo' ,
resourceClass , proxyCountry , ttlSeconds , targetUrl : 'https://example.com/' ,
recording : false , captchaSolver : { enabled : false } } } ;
await writeFile ( file , JSON . stringify ( job , null , 2 ) , { flag : 'wx' , mode : 0o600 } ) ;
console . log ( 'Saved create intent. Run: node lifecycle.mjs resume' ) ;
} else if ( [ 'resume' , 'inspect' , 'stop' ] . includes ( command ) ) {
const job = JSON . parse ( await readFile ( file , 'utf8' ) ) ;
if ( ! job . sessionId && command === 'resume' ) {
const created = await retry ( ( ) => api ( 'POST' , '/sessions' , job . body ) ) ;
if ( typeof created . sessionId !== 'string' || ! created . sessionId ) throw new Error ( 'Missing sessionId' ) ;
job . sessionId = created . sessionId ;
job . configurationWarningsPresent = Boolean ( created . warnings ?. length ) ;
await save ( job ) ;
}
if ( ! job . sessionId ) throw new Error ( 'Resume the original create intent first' ) ;
if ( command === 'stop' ) {
const current = await api ( 'GET' , pathFor ( job . sessionId ) ) ;
if ( current . state !== 'ended' ) await retry ( ( ) => api ( 'DELETE' , pathFor ( job . sessionId ) ) ) ;
await wait ( job . sessionId , 'ended' ) ;
} else if ( command === 'resume' ) {
await wait ( job . sessionId , 'ready' ) ;
}
const current = await api ( 'GET' , pathFor ( job . sessionId ) ) ;
console . log ( JSON . stringify ( { sessionId : job . sessionId , state : current . state ,
configurationWarningsPresent : job . configurationWarningsPresent } ) ) ;
} else throw new Error ( 'Use create, resume, inspect, or stop' ) ;
第 4 步:持久化一个创建意图 运行创建命令。它在任何会话创建请求之前获取有效的默认值并写入 browser-job.json。该文件是本地操作记录,而不是 Cloud Browser API 字段。
node --env-file = .env lifecycle.mjs create
该命令故意不启动浏览器。在继续之前,检查记录的资源类、国家、生命周期和目标 URL。如果在此阶段必须更改配置,请以新作业文件和请求 ID 启动新意图;请勿重复用途已提交给服务的 ID。
第 5 步:恢复存储的意图 运行恢复命令以提交记录的请求并等待 ready。如果创建未返回可用结果,请调查并恢复相同记录,而不是删除它并重新运行创建。
node --env-file = .env lifecycle.mjs resume
成功时会打印原始 sessionId 和观察到的状态。configurationWarningsPresent 的值为真意味着您应该在附加任务之前检查创建配置。示例的边界重试是示范性政策,而不是保证每个短暂故障都会恢复的承诺。
第 6 步:检查原始会话 当工作者或 CDP 客户端断开连接时,使用检查命令。相同的会话可能仍在运行。如果它已准备好,单独的自动化客户端可以请求新凭证并重新发现其页面状态。
node --env-file = .env lifecycle.mjs inspect
不要仅依靠记忆恢复操作。在重复之前,请确定上一步是否完成,尤其是在可能提交表单或创建记录的情况下。生产抓取器错误处理指南 解释了为什么运输重试和业务操作重试需要不同的政策。
第 7 步:停止并确认终止 在您的任务完成后或在此生命周期演示之后立即运行停止命令。它在必要时请求删除,等待 ended,并打印最后观察到的状态。
node --env-file = .env lifecycle.mjs stop
如果无法确认关机,请保留工作记录并在 Cloud Browser → Session History 中检查原始会话。抛出的错误不应转换为成功的清理指标。
[Screenshot: Session History showing the original session has ended, with access URLs and account details concealed.]
Cloud Browser 如何帮助管理会话生命周期? Nstdata 云浏览器为控制器提供明确的会话创建、检查、附加和停止操作。仪表盘为操作员提供了在工作失败时检查资源的第二种方法。短期自动化凭据将连接授权与业务 API 密钥分开。内置代理配置属于会话,而不是每个客户端脚本。这些功能帮助团队实施恢复,但并不能替代其工作数据库或所有权规则。
当前配置发现: 读取支持的选项值,而不是部署硬编码资源类或生命周期限制。
可检查运行时: 当任务被中断时,将会话 ID 与活动浏览器和历史记录相联系。
受控附加: 为预期的就绪会话发放凭据,并在重新连接时不假设新会话包含旧状态。
明确终止: 确认关闭作为工作的完成记录的一部分。
浏览器运行时、代理流量和可选 CAPTCHA 活动应单独评估,使用 Cloud Browser pricing 。等待人类或调试停滞页面可能会保持浏览器活跃。会话持续时间限制限制了暴露,但主动停止仍是正常的清理。
生产中仍然可能出现什么问题? 生产生命周期的故障通常源于不确定的创建、竞争的所有者、中断的清理或将身份验证状态视为浏览器状态。
症状 原因 响应 创建超时 响应可能在创建后丢失 保留原始主体和请求 ID;调和该操作 HTTP 400 无效或过时的显式配置 获取选项并纠正字段;在更改配置时使用新的意图 HTTP 401/403/470 商业身份验证或工作区不匹配 检查密钥和一致的团队上下文 HTTP 409 状态冲突或已更改参数的重复 ID 检查原始操作和会话 HTTP 429/503 临时容量或速率压力 对同一操作应用有界回退 停止未确认 关闭延迟或控制器失去联系 重新检查同一会话并升级到操作员
本地 JSON 记录适用于单个工人演示。它不是分布式锁、事务数据库或安全的多工调度器。在生产中,将意图和会话身份存储在持久的工作记录中,授予一个控制器变更浏览器的租约,并在崩溃后为未完成的工作运行调和。
不要记录 API 密钥、自动化令牌、完整 CDP URLs 或签名的 Live URLs。OWASP 日志记录指南 支持将机密信息排除在日志之外。将工作记录和诊断限制为授权操作员;浏览器自动化工具指南 在比较框架或托管运行时实际拥有的责任时非常有用。
完成一个浏览器任务需要验证哪些结果? 完成的浏览器工作应证明其预期输出被接受,并且其拥有的浏览器会话已结束。必要时,将这些结果单独存储,以及会话 ID 和未解决的清理状态。仅重新连接到确认正在运行的资源,在再次创建之前调和不确定的创建,并让操作员查看未完成的工作。这是远程浏览器会话管理的实际基础。
FAQ 不。ready 表示浏览器可以接受连接。您的应用程序必须单独验证页面和任务结果。
Q: 会话结束后我可以重新连接吗?
不。已结束的会话无法通过请求另一个 CDP 令牌恢复。创建一个新的授权任务,并仅恢复明确支持的应用状态。
不。使用其原始 ID 和相同的请求体重试相同的不确定创建。更改的配置或故意的新任务需要一个新的 ID。
不。网站独立于受管理的浏览器控制其身份验证的生命周期。在重新连接后验证登录状态;不要从 ready 推断。
不。会话持续时间是一个自动限制。在任务结束后停止您拥有的会话,并确认 ended 以避免不必要的活动运行时。
不。分布式服务需要持久记录、并发控制和协调过程。本地文件展示了保留意图,但并未声称那些生产保证。
Nov. 17th 2026
从网页抓取、测试到 AI 驱动的自动化,一切都在云端运行。 探索 Cloud Browser →