Cambio dinámico de proxy para contextos de navegador separados

Cambiar un proxy después de que una sesión ya acumuló cookies y páginas abiertas conserva estado útil, pero también puede confundir una petición antigua con una ruta nueva. Usa un proxy por contexto cuando la tarea permanece en una región y reserva el cambio en ejecución para trabajo autorizado que pueda verificar la nueva salida antes de continuar.

TL;DR

• Un contexto es la unidad más pequeña útil para mantener juntos la ruta y el estado de sesión almacenado.
• BotBrowser.setBrowserContextProxy cambia un contexto existente; las peticiones ya en curso pueden terminar por la ruta anterior.
• Registra y compara la IP de salida, la zona horaria, la configuración regional y el idioma de cada contexto tras cada cambio.

Contents

• Decide qué unidad es dueña de la ruta
• Asigna un proxy al crear el contexto
• Cambia el proxy de un contexto activo
• Verifica cada contexto por separado
• Límites que conviene tener en cuenta
• Conclusión práctica

Decide qué unidad es dueña de la ruta

Un navegador rara vez necesita una sola ruta de red para todo lo que hace. Un equipo que prueba un servicio regional, mantiene separadas varias cuentas autorizadas o compara una página desde dos ubicaciones necesita que cada una de esas tareas salga por su propia ruta. Un único proxy aplicado al iniciar el navegador es sencillo y predecible, pero vincula todas las páginas a la misma dirección de salida mientras el navegador siga abierto. El cambio dinámico de proxy es una respuesta a ese límite, pero es solo una de tres, así que la primera decisión es qué unidad debe ser dueña de la ruta: toda la instancia del navegador, un contexto del navegador o un contexto cuya ruta cambia mientras permanece abierto. BotBrowser puede aplicar un proxy por cada contexto aislado para que cada tarea autorizada conserve su propia ruta; no puede hacer que una red o un sitio acepte esa ruta.

Un contexto del navegador es una sesión aislada dentro de una instancia del navegador. Tiene sus propias cookies, su propio almacenamiento local y su propia caché, y es barato de crear y de descartar en comparación con iniciar otro navegador. Playwright describe los contextos como perfiles de navegador aislados, y Puppeteer expone la misma idea con su propia API de contextos. Como el contexto ya es el límite del estado almacenado, también es un límite natural para una ruta de red: el trabajo que debe permanecer separado no debería compartir ni almacenamiento ni dirección de salida.

La tabla compara las tres opciones. El coste de memoria y el aislamiento del estado suelen decidir la elección, y el nivel de licencia determina qué opciones tienes disponibles.

Opción	Cuándo conviene	Coste y aislamiento	Requisito documentado
Un proxy por contexto, fijado al crearlo	Cada cuenta o región mantiene una sola ruta durante toda la vida de su contexto	Los contextos comparten una instancia del navegador, así que usan menos memoria que instancias separadas, y cada uno conserva sus propias cookies y su almacenamiento	Licencia ENT Tier3 para el proxy por contexto de BotBrowser
Cambio en ejecución de un contexto existente	Un flujo de trabajo se mueve entre regiones, o hay que reemplazar una ruta sin descartar el contexto abierto	El contexto conserva sus páginas y su estado almacenado mientras cambia la ruta	Licencia ENT Tier3 y el comando BotBrowser.setBrowserContextProxy
Una instancia de navegador por proxy	Necesitas la separación más amplia, o el enrutamiento por contexto no forma parte de tu nivel	Cada instancia carga con su propia huella completa de navegador y su propio directorio de datos de usuario	Un valor --proxy-server a nivel de inicio, descrito en la guía de configuración de proxy

Tres preguntas suelen resolver la elección. Si la ruta tiene que cambiar mientras el mismo contexto sigue abierto, usa el cambio en ejecución. Si cada cuenta mantiene una sola ruta durante toda su vida, asigna el proxy al crear el contexto, porque una ruta que nunca cambia es más fácil de revisar y de explicar después. Si tu licencia no incluye el enrutamiento por contexto, o quieres la separación más amplia, inicia una instancia de navegador por proxy y acepta el consumo extra de memoria.

La memoria es el coste que más a menudo decide entre contextos e instancias separadas, y depende de lo que hagan las páginas. Las pestañas abiertas, los medios, las extensiones y las descargas se suman, así que el resultado de una página vacía dice poco sobre un trabajo de producción. Mide con tu carga de trabajo real y autorizada, fija límites conservadores y deja margen para picos breves en lugar de copiar una cifra de capacidad de una demostración o de la configuración de otro equipo.

Algunos equipos rotan rutas con interceptación de peticiones dentro del framework de automatización, o con un servicio local de proxy que reenvía a distintos proxies de salida. Esos diseños pueden funcionar, pero añaden piezas que ejecutar y vigilar. La documentación de BotBrowser indica además que la alineación de la zona horaria depende de un proxy definido con --proxy-server o del proxy por contexto, y no de opciones de proxy exclusivas del framework, así que mantén la ruta del lado del navegador cuando las señales regionales importen para tu tarea. Un servicio local de proxy es también un servicio en localhost, y Protección contra el sondeo de puertos del navegador en localhost explica cómo un navegador puede sondear puertos locales.

Asigna un proxy al crear el contexto

La forma documentada por BotBrowser de dar a un contexto su propia ruta es indicar el proxy al crearlo. En Puppeteer es la opción proxyServer de createBrowserContext, con las credenciales incluidas en la URL del proxy. Un contexto creado sin proxy propio hereda la ruta de proxy y la identidad geográfica del perfil de inicio, así que cualquier contexto que no deba usar la ruta del navegador necesita un proxy propio.

const client = await browser.target().createCDPSession();

const ctx = await browser.createBrowserContext({
  proxyServer: 'socks5://user:[email protected]:1080',
});

await client.send('BotBrowser.setBrowserContextFlags', {
  browserContextId: ctx._contextId,
  botbrowserFlags: ['--bot-profile=path/to/profile.enc', '--proxy-ip=203.0.113.1'],
});

const page = await ctx.newPage();

Tras la creación, BotBrowser detecta la IP de salida del proxy de ese contexto y fija a partir de ella la zona horaria, la configuración regional y el idioma del contexto. Si ya conoces la IP de salida, indícala con --proxy-ip y se omite la consulta. Cuando un contexto tiene su propia ruta y además declaras la IP de salida, proporciona ambas al crearlo: la documentación advierte de que aplicar --proxy-ip solo después de la creación puede permitir que la resolución geográfica empiece antes de que esté disponible la declaración de la dirección. Envía la actualización de flags antes de crear la primera página del contexto, como en el ejemplo anterior.

Los ajustes que se dejan en auto siguen al proxy del contexto, mientras que los valores explícitos se resuelven de forma independiente para cada contexto y cada ajuste. Eso es útil cuando un equipo fija deliberadamente un valor, como un idioma de interfaz que exige el plan de pruebas, y deja que los demás sigan a la ruta. Trata cada valor fijado como una decisión con un responsable. Una anulación antigua sigue pareciendo válida cuando la ruta cambia, y es fácil olvidar que existe.

Playwright documenta su propia opción proxy para contextos nuevos, y es la referencia correcta para lo que esa opción hace dentro de Playwright. La documentación de BotBrowser sobre el proxy por contexto está escrita en torno a la opción de creación de contexto y a los flags mostrados arriba, así que confirma los valores regionales en tu propia página de prueba antes de depender de la alineación automática en una configuración con Playwright. La página de Playwright enlazada en las fuentes es la referencia para el comportamiento del framework.

Las credenciales merecen el mismo cuidado que la ruta. El comando documentado y la opción de creación aceptan la URL del proxy con credenciales incluidas, así que déjalas ahí en lugar de sustituirlas por una llamada aparte a page.authenticate(). Obtenlas de tu gestor de secretos al iniciar el trabajo, mantenlas fuera de archivos de código, tickets y registros de ejecución, y rótalas a través de su responsable. El artículo sobre autenticación de proxy e higiene de credenciales trata ese proceso con más detalle.

Cerrar un contexto descarta sus cookies, su almacenamiento local y su caché, y el siguiente contexto empieza limpio. Es el comportamiento que quieres cuando cada tarea debe empezar desde cero, y un problema cuando la sesión de una cuenta tiene que sobrevivir al contexto. Si una sesión debe continuar, decide antes de cerrar qué exportas, dónde se guarda y quién puede leerla. La guía de proxy por contexto describe cómo mantener juntos un propósito, un contexto y una ruta.

Un registro breve de rutas mantiene estas asignaciones revisables. Para cada contexto, anota una etiqueta legible de la ruta, la tarea a la que sirve, su responsable, la región prevista cuando importe y la referencia al secreto que guarda sus credenciales. Usa una etiqueta que describa el propósito en lugar de copiar un nombre de host en muchos trabajos, de modo que el proveedor pueda rotar un endpoint sin que cambie cada plantilla. Cuando cambie el propósito, crea una asignación nueva en lugar de reutilizar en silencio una etiqueta antigua, porque las revisiones que dependen de la etiqueta dejan de ser fiables.

Cambia el proxy de un contexto activo

El cambio en ejecución existe para los flujos de trabajo en los que el mismo contexto necesita otra ruta más adelante. Con una licencia ENT Tier3, BotBrowser documenta el comando CDP BotBrowser.setBrowserContextProxy, que cambia el proxy de un contexto de navegador existente. El comando recibe el browserContextId y una URL proxyServer con credenciales incluidas, y opcionalmente proxyIp, proxyBypassList y proxyBypassRgx.

const client = await browser.target().createCDPSession();

await client.send('BotBrowser.setBrowserContextProxy', {
  browserContextId: ctx._contextId,
  proxyServer: 'socks5://user:[email protected]:1080',
  proxyIp: '198.51.100.1',
});

await page.goto(nextUrl);

El comando debe enviarse en una sesión de nivel de navegador. En Puppeteer es browser.target().createCDPSession() y en Playwright es browser.newBrowserCDPSession(). Una sesión de nivel de página no expone el dominio BotBrowser, y un error de «comando no encontrado» es el síntoma habitual de usar la sesión equivocada. El mismo error puede aparecer cuando la licencia no incluye la función.

Cuando llamas al comando, BotBrowser actualiza la configuración de proxy de ese contexto, vuelve a detectar la IP de salida salvo que hayas indicado proxyIp, y reconfigura la zona horaria, la configuración regional y el idioma para que coincidan con la nueva ubicación. El comando termina cuando se ha aplicado el estado geográfico actualizado, y las peticiones posteriores de ese contexto usan el proxy nuevo. Por eso debes esperar (await) al comando antes de iniciar cualquier navegación que dependa de la nueva ubicación. Mantén en secuencia los cambios de proxy, las actualizaciones de flags y la eliminación del proxy de un mismo contexto, y espera a que cada comando termine antes de enviar el siguiente.

Planifica el traspaso en sí. Las páginas ya cargadas siguen funcionando, y las peticiones que estaban en curso cuando cambiaste terminan por el proxy anterior. Solo las peticiones nuevas usan el nuevo, así que el cambio no es instantáneo ni está libre de solapamiento. En la práctica, deja que termine la navegación pendiente y pausa los temporizadores o el sondeo de la página antes de cambiar; después navega de nuevo cuando el comando termine. Una página que siguió abierta durante el cambio no debe contarse como llegada por la ruta nueva.

Indicar proxyIp elimina la consulta única previa a la primera navegación posterior a un cambio. Úsalo cuando ya tengas la dirección de salida de tu proveedor, y asegúrate de que sea la dirección de salida real de ese proxy, porque los ajustes geográficos se derivan del valor que indiques. Para un proxy con dirección en una sola familia, la documentación permite ipv4_none o ipv6_none para declarar la familia ausente. Sin proxyIp, espera que la primera carga tras un cambio tarde algo más, lo cual es normal y no es por sí solo un fallo.

El comando BotBrowser.clearBrowserContextProxy elimina la anulación y devuelve el contexto al proxy del navegador, o a una conexión directa cuando no hay ninguno configurado. Una conexión directa puede ser justo lo que no quieres, así que revisa qué aporta la configuración de inicio antes de usarlo. Un flujo de trabajo que nunca debe salir sin proxy debería cambiar a otro proxy aprobado en lugar de limpiar.

La opción proxyBypassList recibe una lista de hosts separados por punto y coma que se conectan directamente, y proxyBypassRgx recibe un patrón RE2 para las URL que deben hacer lo mismo. Esas peticiones no usan el proxy en absoluto. Mantén la lista corta, regístrala como parte de la asignación de la ruta y prueba un host que deba conectarse directamente y otro que no.

Los equipos que quieren una salida distinta para cada trabajo pueden crear un contexto nuevo en cada rotación o cambiar un mismo contexto entre trabajos. Un contexto nuevo empieza sin cookies ni caché, así que no arrastra nada. Un contexto cambiado conserva su estado almacenado, lo que significa que la sesión iniciada de una cuenta continúa desde una dirección nueva. Que eso sea aceptable es una decisión del responsable de la cuenta, y un sitio puede tratar el cambio de forma distinta a la esperada. El artículo sobre conmutación por error de proxy y continuidad visible para el usuario explica qué percibe la gente cuando una ruta cambia en mitad de una sesión.

Verifica cada contexto por separado

El objetivo de la verificación es ver, para cada contexto, su propia dirección de salida y los valores regionales que esperas. Haz la comprobación por separado en cada contexto tras crearlo, y otra vez después de cada cambio. No generalices de un contexto a otro, porque cada contexto tiene su propia ruta y sus propios ajustes geográficos.

Para la dirección, abre una página de un servicio que controles, o que tu organización apruebe, que muestre la dirección de origen de una petición, y compárala con la dirección de salida que tu proveedor indica para ese proxy. Si coincide, el tráfico salió por la ruta prevista. Si es distinta, el ajuste de proxy no se aplicó a ese contexto. Si configuraste reglas de conexión directa, comprueba un host que deba conectarse directamente y otro que no.

Para la zona horaria, la configuración regional y el idioma, haz que una página de prueba que controles muestre los valores que informa el navegador y compáralos con la región de la dirección de salida. En un contexto con una anulación explícita, compara con la anulación. El artículo sobre zona horaria, configuración regional e idioma explica cómo se relacionan estos valores y por qué una discrepancia informa más que cualquier valor aislado.

Tras un cambio, espera a que el comando termine y abre una página nueva o recarga la existente antes de volver a comprobar. Considera obsoletas las páginas cargadas antes del cambio. Después confirma el sentido contrario: los contextos que no cambiaste deben seguir mostrando sus direcciones originales. Esa comprobación es la prueba de que el cambio en un contexto no alteró la ruta de otro.

Mantén las evidencias acotadas. Basta un registro breve con la etiqueta de la ruta, el propósito del contexto, la dirección de salida observada, los valores regionales, el resultado y la hora. No guardes contenido de páginas, datos de cuentas ni credenciales para demostrar que se aplicó una ruta.

Usa siempre campos como contextId, routeLabel, observedIp, timezone, locale, language y checkedAt. Así se pueden comparar dos registros tras BotBrowser.setBrowserContextProxy sin guardar la URL del proxy ni sus credenciales.

Cuando una comprobación falle, revisa las causas por orden. Confirma que el comando se envió en una sesión de nivel de navegador y que tu licencia incluye la función. Confirma que el proxy acepta una conexión desde una herramienta sencilla fuera del navegador, lo que separa un problema del proveedor de un problema de configuración. Comprueba si hay una anulación explícita de zona horaria, configuración regional o idioma en ese contexto, ya que las anulaciones tienen prioridad sobre los valores derivados de la ruta. Comprueba que el valor de proxyIp que indicaste es la dirección de salida real de ese proxy. Cambia una sola cosa cada vez y repite la comprobación tras cada cambio.

Límites que conviene tener en cuenta

Un cambio de proxy modifica la ruta de red de un contexto y nada más. La calidad de esa ruta pertenece al proveedor del proxy: la reputación de la dirección de salida, su velocidad y estabilidad, y la precisión con que está registrada su ubicación. Cambiar a un proxy deficiente da al contexto una ruta deficiente, así que mide al proveedor con tus propias pruebas antes de construir un flujo de trabajo sobre él.

Una dirección de salida compartida es una señal de vinculación entre varias. Direcciones distintas reducen un tipo de conexión entre cuentas, pero no controlan cómo un sitio relaciona identidades mediante datos de cuenta, datos de pago, comportamiento, valores del dispositivo o las personas que las operan. Nada de esto garantiza que un sitio acepte, ignore o deje de correlacionar tus contextos. Usa el enrutamiento por contexto para trabajo autorizado, como tus propias cuentas, comprobaciones regionales de calidad e investigación de privacidad, y respeta los términos de cada servicio.

Decide de antemano qué ocurre cuando un cambio falla. Un endpoint del proveedor puede no estar disponible y un comando en ejecución puede ser rechazado. Para un flujo de trabajo que necesita una ruta concreta, detén el trabajo y registra el fallo en lugar de continuar por la ruta anterior, salvo que el responsable haya aprobado esa alternativa por escrito.

BotBrowser soporta proxies por contexto y, con una licencia ENT Tier3, el comando CDP BotBrowser.setBrowserContextProxy, que cambia en ejecución el proxy de un contexto de navegador existente y vuelve a detectar la IP de salida para actualizar la zona horaria, la configuración regional y el idioma de ese contexto. Eso ayuda cuando un flujo de trabajo tiene que moverse entre regiones, o cuando hay que reemplazar una ruta sin descartar el contexto abierto. BotBrowser no puede suministrar ni evaluar proxies, mejorar la reputación de IP ni la velocidad de un proxy, sacar del proxy anterior las peticiones que ya están en curso, ni garantizar cómo un sitio correlaciona o acepta identidades más allá de la ruta de red.

Conclusión práctica

Da a cada trabajo autorizado un contexto con nombre y una asignación de ruta. Para un cambio en ejecución, espera a BotBrowser.setBrowserContextProxy, carga una página nueva, compara observedIp y los valores regionales con la ruta esperada y detén el trabajo si no coinciden. No uses páginas abiertas antes del cambio para esa comparación, porque sus peticiones pueden haber terminado antes.

Fuentes públicas

• Documentación de BotBrowser sobre el cambio dinámico de proxy
• Documentación de BotBrowser sobre el proxy por contexto
• Documentación de BotBrowser sobre proxy y geolocalización
• Documentación de red de Playwright: proxy HTTP
• Documentación de Playwright sobre contextos del navegador