Gestión de sesiones del navegador en la nube: Crear, reconectar y detener de forma segura
TL;DR
Un ciclo de vida de sesión de navegador en la nube rastrea el recurso del navegador gestionado, independientemente de un inicio de sesión en el sitio web o una conexión del cliente.
Persistir un UUID v4 requestId y el cuerpo completo de creación antes de enviar una solicitud de creación de sesión.
Reintentar una creación incierta con el mismo ID y cuerpo idéntico; una configuración cambiada requiere un nuevo ID.
ready significa que el navegador está disponible para su conexión, no que su tarea comercial ha tenido éxito.
Refrescar Live View o reconectar CDP no reinicia la duración del navegador.
Una solicitud de detención se completa solo cuando la sesión original alcanza ended; stopping es intermedio.
¿Qué es un ciclo de vida de sesión de navegador?
Un ciclo de vida de sesión de navegador es la secuencia de estados que un navegador gestionado atraviesa desde su creación hasta su finalización. Describe el recurso que su automatización consume. Una sesión de autenticación de sitio web describe si un sitio particular considera a un usuario conectado, mientras que una conexión de cliente CDP describe si su programa está actualmente adjunto. Estos tres ciclos de vida pueden terminar de forma independiente.
Nstdata Cloud Browser proporciona navegadores en la nube gestionados para la automatización de navegadores y agentes de IA. Gestionar ese recurso de manera explícita permite a un equipo recuperarse de fallas de trabajadores, coordinar una transferencia humana y tener en cuenta el tiempo de ejecución después de que termine la tarea de la página. La introducción al Cloud Browser proporciona contexto del producto; esta guía se centra en la propiedad y las transiciones de estado necesarias en un ejecutor de trabajo real.
Por ejemplo, su script puede perder su WebSocket mientras el navegador sigue listo y conectado a una aplicación. Por el contrario, el socket puede seguir conectado mientras el sitio web expira el inicio de sesión. Una única bandera de success no puede representar ambas condiciones con precisión.
¿Qué estados debe manejar su aplicación?
Su aplicación debería manejar creating, unknown, ready, stopping, ended y failed del campo state de la respuesta de sesión. No busque un campo status no documentado ni infiera el estado del recurso a partir de una imagen previa.
Estado
Significado para el controlador
Acción siguiente apropiada
creating
El inicio del navegador está en progreso
Consultar la misma sesión dentro de un plazo
unknown
El estado del recurso actual es incierto
Reconciliar la operación original; evitar creación duplicada
ready
El navegador puede aceptar una conexión
Obtener credenciales y validar el estado de la página de la tarea
stopping
Se ha solicitado el apagado
Continuar comprobando por ended
ended
Esta sesión ha terminado
No intente revivirla con credenciales antiguas
failed
El recurso ha fallado
Capturar el contexto de la falla y resolver la limpieza antes de un nuevo intento
La actual guía de la API de Automatización de Navegadores es el contrato para estos valores. Mantenga un estado de tarea de aplicación separado, como esperando-humano, trabajando, aceptado o rechazado. Esos son sus propios estados de trabajo, no estados adicionales de la API del Cloud Browser.
¿Qué puntos finales y parámetros necesita?
Necesita opciones, creación, inspección, emisión de credenciales y puntos finales de eliminación bajo https://api.nstdata.io/api/v1/cloud-browser. Recupere las opciones actuales antes de construir el cuerpo de creación porque las clases de recursos, países y duraciones permitidas dependen de la configuración del servicio actual.
Confirmar ended a través de inspecciones posteriores
El ejemplo de creación también proporciona targetUrl, recording: false, y captchaSolver: { enabled: false }. Revise warnings y effectiveConfiguration de la respuesta de creación al personalizarla. Una advertencia de configuración merece investigación antes de permitir que el trabajo realice tareas significativas.
Utilice x-api-key sin Bearer para llamadas HTTP del ciclo de vida. Obtenga una clave personal en Settings → Account o una clave de miembro del equipo vinculada en Members. Con una clave personal, el opcional x-team-id selecciona un equipo unido; mantenga el mismo valor en cada solicitud. Las credenciales de CDP se emiten por separado y no deben guardarse en el registro del trabajo.
¿Cómo crea y detiene una sesión sin duplicarla?
Crear y detener una sesión de forma segura persistiéndola la solicitud prevista antes de la creación, reteniendo el ID de sesión devuelto y tratando el apagado como una transición de estado confirmada. Este ejemplo separa deliberadamente los comandos para que un trabajador interrumpido pueda reanudar su intención existente.
Paso 1: Preparar el proyecto de Node.js
Utilice Node.js 22.12 o posterior y cree un directorio de trabajo. El controlador de ciclo de vida utiliza las API integradas de Node y no instala un cliente de navegador.
mkdir browser-lifecycle-demo
cd browser-lifecycle-demo
Cree un archivo privado .env que contenga NSTDATA_API_KEY y, solo si es necesario, NSTDATA_TEAM_ID. Excluya .env y el registro de trabajo generado del control de versiones. Ejecute cada trabajo en su propio directorio o elija una ruta de JOB_FILE distinta.
Paso 2: Guardar el helper HTTP
Guarde este módulo como cloud-api.mjs. Valida el sobre de respuesta y evita imprimir mensajes de servidor en bruto que podrían contener datos sensibles. El AbortSignal timeout de Node limita cada solicitud de forma independiente de la duración del navegador.
Requisito de credenciales: estas solicitudes HTTP requieren una clave empresarial de Nstdata. Se verificó el comportamiento de la API contra la documentación actual y pruebas de transición de estado sintéticas; este artículo no afirma una ejecución en una cuenta administrada en vivo.
const root ='https://api.nstdata.io/api/v1/cloud-browser';exportasyncfunctionapi(method, path, body){const key = process.env.NSTDATA_API_KEY;if(!key)thrownewError('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 =awaitfetch(root + path,{ method, headers,redirect:'error',body: body ?JSON.stringify(body):undefined,signal:AbortSignal.timeout(20_000),});}catch{throwObject.assign(newError('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{throwObject.assign(newError('Invalid API JSON'),{ retryable });}if(!response.ok|| result.err===true|| result.success===false){throwObject.assign(newError(`Cloud Browser API HTTP ${response.status}`),{ retryable });}if(!result.data)thrownewError('Missing API data');return result.data;}exportasyncfunctionconnection(id){if(!id)thrownewError('Set NSTDATA_SESSION_ID');const path =`/sessions/${encodeURIComponent(id)}`;const session =awaitapi('GET', path);if(session.state!=='ready')thrownewError(`Session is ${session.state}, not ready`);const c =awaitapi('POST', path +'/automation-credentials');if(c.sessionId!== id ||!c.headerName||!c.accessToken||!(Date.parse(c.expiresAt)>Date.now())||newURL(c.cdpUrl).protocol!=='wss:'){thrownewError('Invalid or expired CDP credentials');}return{endpoint: c.cdpUrl,headers:{[c.headerName]: c.headerName.toLowerCase()==='authorization'?`Bearer ${c.accessToken}`: c.accessToken},};}exportasyncfunctionendpoint(){// An isolated local CDP endpoint can test the client without managed credentials.if(process.env.LOCAL_CDP_URL){const url =newURL(process.env.LOCAL_CDP_URL);if(!['127.0.0.1','localhost','[::1]'].includes(url.hostname)){thrownewError('LOCAL_CDP_URL must use loopback');}return{endpoint: url.href,headers:{}};}returnconnection(process.env.NSTDATA_SESSION_ID);}
Paso 3: Guardar el controlador reanudable
Guarde el siguiente código como lifecycle.mjs. El controlador crea el registro local exclusivamente y se niega a sobrescribir una intención existente. Su bucle de reintento reutiliza el cuerpo almacenado, incluida la misma UUID generada con Node.js randomUUID.
Requisito de credenciales: la rama de la API requiere su clave de espacio de trabajo. El comportamiento de recuperación y repetición de creación se ejerció con un accesorio HTTP claramente separado, no presentado como salida del servicio 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';constpathFor=id=>`/sessions/${encodeURIComponent(id)}`;constsave=job=>writeFile(file,JSON.stringify(job,null,2),{mode:0o600});asyncfunctionretry(operation){for(let attempt =0;; attempt++){try{returnawaitoperation();}catch(error){if(!error.retryable|| attempt ===2)throw error;awaitdelay(500*2** attempt +Math.random()*250);}}}asyncfunctionwait(id, expected){const deadline =Date.now()+90_000;while(Date.now()< deadline){const session =awaitretry(()=>api('GET',pathFor(id)));if(session.state=== expected)return session;if(['ended','failed'].includes(session.state)){thrownewError(`Session ${session.state}; expected ${expected}`);}awaitdelay(2_000);}thrownewError('State wait expired; inspect the original session');}const command = process.argv[2];if(command ==='create'){const options =awaitapi('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)thrownewError('Inspect current options');const job ={body:{requestId:randomUUID(),name:'lifecycle-demo', resourceClass, proxyCountry, ttlSeconds,targetUrl:'https://example.com/',recording:false,captchaSolver:{enabled:false}}};awaitwriteFile(file,JSON.stringify(job,null,2),{flag:'wx',mode:0o600});console.log('Saved create intent. Run: node lifecycle.mjs resume');}elseif(['resume','inspect','stop'].includes(command)){const job =JSON.parse(awaitreadFile(file,'utf8'));if(!job.sessionId&& command ==='resume'){const created =awaitretry(()=>api('POST','/sessions', job.body));if(typeof created.sessionId!=='string'||!created.sessionId)thrownewError('Missing sessionId'); job.sessionId= created.sessionId; job.configurationWarningsPresent=Boolean(created.warnings?.length);awaitsave(job);}if(!job.sessionId)thrownewError('Resume the original create intent first');if(command ==='stop'){const current =awaitapi('GET',pathFor(job.sessionId));if(current.state!=='ended')awaitretry(()=>api('DELETE',pathFor(job.sessionId)));awaitwait(job.sessionId,'ended');}elseif(command ==='resume'){awaitwait(job.sessionId,'ready');}const current =awaitapi('GET',pathFor(job.sessionId));console.log(JSON.stringify({sessionId: job.sessionId,state: current.state,configurationWarningsPresent: job.configurationWarningsPresent}));}elsethrownewError('Use create, resume, inspect, or stop');
Paso 4: Persistir una intención de creación
Ejecute el comando de creación. Obtiene valores por defecto válidos y escribe browser-job.json antes de cualquier solicitud de creación de sesión. El archivo es un registro operativo local, no un campo de API de Cloud Browser.
node --env-file=.env lifecycle.mjs create
El comando intencionalmente no lanza el navegador. Inspecione la clase de recurso grabada, país, duración y URL de destino antes de continuar. Si la configuración debe cambiar en esta etapa, inicie una intención deliberadamente nueva con un nuevo archivo de trabajo y ID de solicitud; no reutilice un ID que ya se haya enviado al servicio.
Paso 5: Reanudar la intención almacenada
Ejecute el comando de reanudación para enviar la solicitud grabada y esperar a que esté ready. Si la creación no devuelve un resultado utilizable, investigue y reanude el mismo registro en lugar de eliminarlo y volver a ejecutar la creación.
node --env-file=.env lifecycle.mjs resume
El éxito imprime el sessionId original y el estado observado. Un valor de configurationWarningsPresent igual a verdadero significa que debe inspeccionar la configuración de creación antes de adjuntar una tarea. Los intentos limitados del ejemplo son una política de demostración, no una promesa de que cada falla transitoria se recuperará.
Paso 6: Inspeccionar la sesión original
Utilice el comando de inspección cuando un trabajador o cliente CDP se desconecte. La misma sesión puede seguir ejecutándose. Si está lista, un cliente de automatización separado puede solicitar nuevas credenciales y redescubrir el estado de su página.
node --env-file=.env lifecycle.mjs inspect
No restaure acciones solo de la memoria. Determine si el paso anterior se completó antes de repetirlo, especialmente si pudiera enviar un formulario o crear un registro. La guía de manejo de errores del scraper de producción explica por qué los reintentos de transporte y los reintentos de operaciones comerciales necesitan políticas diferentes.
Paso 7: Detener y confirmar la terminación
Ejecute el comando de detención después de su tarea o inmediatamente después de esta demostración de ciclo de vida. Solicita eliminación cuando sea necesario, espera a ended y imprime el estado final observado.
node --env-file=.env lifecycle.mjs stop
Si no se puede confirmar el apagado, mantenga el registro del trabajo e inspeccione la sesión original en Cloud Browser → Session History. Un error lanzado no debe convertirse en una métrica de limpieza exitosa.
[Screenshot: Historia de la sesión que muestra que la sesión original ha terminado, con las URLs de acceso y los detalles de la cuenta ocultos.]
¿Cómo ayuda Cloud Browser a gestionar el ciclo de vida de las sesiones?
Nstdata Cloud Browser le da a un controlador operaciones explícitas para la creación, inspección, adjunto y detención de sesiones. El panel de control ofrece al operador una segunda forma de inspeccionar el recurso cuando un trabajador falla. Credenciales de automatización de corta duración mantienen la autorización de conexión separada de la clave API de negocio. La configuración de proxy incorporada pertenece a la sesión en lugar de a cada script de cliente. Estas capacidades ayudan a un equipo a implementar la recuperación, pero no reemplazan su base de datos de trabajos o reglas de propiedad.
Descubrimiento de configuración actual: leer valores de opción soportados en lugar de desplegar clases de recursos codificadas o límites de duración.
Tiempo de ejecución inspeccionable: correlacionar una ID de sesión con el navegador activo y el historial cuando una tarea es interrumpida.
Adjunto controlado: emitir credenciales para la sesión lista pretendida y reconectar sin asumir que una nueva sesión contiene el estado anterior.
Terminación explícita: hacer de la apagado confirmado parte del registro de finalización del trabajo.
El tiempo de ejecución del navegador, el tráfico del proxy y la actividad de CAPTCHA opcional deben evaluarse por separado utilizando la tarificación de Cloud Browser. Esperar a un humano o depurar una página detenida puede mantener el navegador activo. Un límite de duración de sesión limita la exposición, pero la detención proactiva sigue siendo una limpieza normal.
Las fallas en el ciclo de vida de producción generalmente surgen de la creación incierta, propietarios competidores, limpieza interrumpida o tratar el estado de autenticación como estado del navegador.
Síntoma
Causa
Respuesta
La creación se agota
La respuesta puede haberse perdido después de la creación
Preservar el cuerpo original y la ID de solicitud; reconciliar esa operación
HTTP 400
Configuración explícita inválida o desactualizada
Obtener opciones y corregir el campo; usar una nueva intención al cambiar la configuración
HTTP 401/403/470
Desajuste de autenticación empresarial o de espacio de trabajo
Verificar la clave y el contexto de equipo coherente
HTTP 409
Estado en conflicto o ID reutilizado con parámetros cambiados
Inspeccionar la operación original y la sesión
HTTP 429/503
Capacidad temporal o presión de tasa
Aplicar retroceso limitado a la misma operación
La detención permanece no confirmada
El apagado se retrasa o el controlador perdió contacto
Reinspeccionar la misma sesión y escalar a un operador
El registro local JSON es adecuado para una demostración de un solo trabajador. No es un bloqueo distribuido, base de datos transaccional o programador seguro de múltiples trabajadores. En producción, almacene la intención y la identidad de la sesión en un registro de trabajo duradero, dé a un controlador el arrendamiento para modificar el navegador, y ejecute reconciliación para trabajos no finalizados después de fallos.
No registre claves API, tokens de automatización, URLs CDP completas o URLs en vivo firmadas. La guía de registro de OWASP apoya mantener secretos fuera de los registros. Restringa los registros de trabajos y diagnósticos a operadores autorizados; la guía de herramientas de automatización de navegador es útil al comparar qué responsabilidades tiene realmente un marco o tiempo de ejecución gestionado.
¿Qué debe demostrar una tarea de navegador completada?
Un trabajo de navegador completado debe probar que su salida prevista fue aceptada y que su sesión de navegador propiedad terminó. Almacene esos resultados por separado, junto con la ID de sesión y el estado de limpieza no resuelto cuando sea necesario. Reconecte solo a un recurso en ejecución confirmado, reconcilie la creación incierta antes de crear nuevamente, y deje que un operador vea el trabajo no terminado. Esa es la base práctica para la gestión remota de sesiones de navegador.
No. listo significa que el navegador puede aceptar una conexión. Su aplicación debe verificar por separado la página y el resultado de la tarea.
Q: ¿Puedo reconectar después de que la sesión termine?
No. Una sesión finalizada no puede ser reactivada solicitando otro token CDP. Crea una nueva tarea autorizada y restaura solo el estado de la aplicación explícitamente soportado.
Q: ¿Debería un reintento de creación generar un nuevo ID de solicitud?
No. Reintenta la misma creación incierta con su ID original y cuerpo idéntico. Una configuración cambiada o una tarea deliberadamente nueva requieren un nuevo ID.
Q: ¿Es el inicio de sesión en un sitio web lo mismo que la sesión del navegador?
No. Un sitio web controla la duración de su autenticación de manera independiente del navegador gestionado. Verifica el estado de inicio de sesión después de reconectar; no lo infieras de listo.
Q: ¿La duración de la sesión reemplaza a la limpieza?
No. La duración de la sesión es un límite automático. Detén tu sesión propia después de la tarea y confirma finalizada para evitar un tiempo de ejecución activo innecesario.
Q: ¿Es el archivo de trabajo local suficiente para un servicio distribuido?
No. Un servicio distribuido necesita registros duraderos, control de concurrencia y un proceso de reconciliación. El archivo local demuestra la intención preservada sin reclamar esas garantías de producción.
Automatización del navegador con intervención humana: del inicio de sesión manual a tareas automatizadas
Deje que un operador inicie sesión a través de Live View antes de que un script verifique la misma pestaña de la aplicación. Defina la propiedad, las afirmaciones de cuenta, los límites de aprobación y la limpieza sin incluir una contraseña en la automatización.
Ivy Lin
Nov. 17th 2026
Inicia navegadores en la nube bajo demanda
Gestiona huellas digitales y CAPTCHA
Automatiza flujos de trabajo e impulsa agentes de IA
Desde la extracción de datos web y las pruebas hasta la automatización con IA, ejecútalo todo en la nube.