Visión general de Pages

Pages publica sitios estáticos como proyectos con despliegues inmutables y Tags mutables. Un despliegue es un artefacto fijo producido por una subida manual o por un build desde Git. Un Tag es un puntero con nombre que se puede mover a un despliegue. Las Routes apuntan a Tags, nunca a despliegues en bruto, lo que convierte la promoción y la reversión en acciones operativas deliberadas en lugar de cambios en un artefacto ya publicado.

Pages sirve documentación, páginas de aterrizaje, paneles y otros frontends estáticos sin un servidor de aplicaciones. Cada versión se puede previsualizar, promover, verificar y revertir sin volver a construir ni editar el artefacto anterior.

Pages sirve salida estática entregada al navegador. Los procesos de API, los workers en segundo plano, las sesiones con estado y el código de aplicación del lado del servidor se ejecutan como cargas de trabajo detrás de las Routes de Opfield.

Este portal de documentación y la página principal del producto Opfield se publican también a través de Opfield Pages. Usan el mismo modelo de despliegues inmutables, Tags, Routes, TLS y reversión que se describe aquí.

Modelo de recursos y propiedad

Un Pages Project es responsable de su historial de despliegues, sus Tags, sus Routes, su configuración de ejecución, sus relaciones de acceso y su comportamiento de retención. Opfield guarda cada artefacto publicado de forma centralizada y lo materializa en los nodos nginx asignados. Nginx sirve la configuración de Pages aplicada, mientras que Opfield sigue siendo la fuente de verdad sobre qué Tag debe usar una Route.

Los despliegues son inmutables: cambiar los archivos del sitio, la salida del build o la entrada del código crea un despliegue nuevo. Los Tags son mutables: mover un Tag cambia el despliegue ya creado que selecciona. El Tag latest, gestionado por el sistema, sigue el despliegue actual adecuado; usa Tags personalizados para entornos con nombre, canales de versiones o una puerta de promoción explícita.

Decisiones antes de la primera versión

Acuerda cinco puntos antes de conectar un dominio público:

1. Propiedad: quién puede crear despliegues, mover los Tags de producción, editar la configuración de ejecución y eliminar candidatos de reversión.
2. Origen de las versiones: subida manual de artefactos o una integración de Git y un Build Worker aprobados.
3. Política de promoción: despliegue automático para sitios de bajo riesgo o una revisión explícita antes de mover el Tag de producción.
4. Retención: cuántos despliegues que se sabe que funcionan deben seguir disponibles y durante cuánto tiempo.
5. Contrato de ejecución: qué valores públicos pueden cambiar independientemente del artefacto y qué cambios requieren un build nuevo.

Usa Tags separados cuando los entornos necesiten una promoción independiente. No uses los nombres de los Tags como control de acceso: los permisos y las Routes siguen siendo el límite de seguridad.

Publica desde Git o manualmente

Para una versión basada en Git, una integración de código compatible y un Build Worker producen un despliegue inmutable nuevo. Para una versión manual, proporciona el artefacto del sitio estático ya preparado y crea un despliegue nuevo a partir de él. En ambos casos, revisa el artefacto resultante y la identidad del despliegue antes de mover un Tag público.

Una subida manual puede ser un único archivo HTML, que se convierte en el index.html del sitio, o un archivo .tar.gz con index.html en su raíz. Al finalizar la subida se devuelve el enlace de vista previa del despliegue y, cuando la subida indicaba un Tag, el enlace del Tag, de modo que un agente que ha generado un informe puede dar una URL al usuario de inmediato (consulta la skill publishing-html-pages en Skills para agentes de IA). Una subida puede fijar una caducidad (expiresInHours o expiresAt). Cuando vence, Opfield elimina el despliegue con sus archivos y vistas previas y vacía los Tags que todavía lo seleccionan; un despliegue que todavía sirve una Route conserva sus archivos, pero sus vistas previas dejan de funcionar. Los tokens de despliegue restringidos a determinados Tags no pueden fijar una caducidad.

Cada subida (desde la consola, a través de la API de despliegue reanudable o mediante un enlace de un solo uso de MCP) puede ser tan grande como el File upload limit de Settings > General > Access and limits: 100 MB por defecto y como máximo 500 MB. Un artefacto mayor se rechaza con 413 PAGES_ARTIFACT_TOO_LARGE, y también se aplica la cuota de almacenamiento del proyecto. Una subida sin terminar se puede cancelar de inmediato desde la consola, la REST API o MCP; una subida fallida desde la consola se limpia sola, y una subida abandonada caduca 30 minutos después de su último fragmento. Los agentes publican mediante enlaces de subida de un solo uso con comandos curl listos para usar en lugar de base64 en las llamadas a herramientas.

Crear un despliegue no lo publica en un dominio personalizado. La publicación empieza cuando una Route apunta a un Tag que apunta a ese despliegue. Esto permite a un equipo verificar una versión antes de la promoción y permite que una reversión ante un incidente mueva un Tag sin reescribir el artefacto anterior.

Routes, vistas previas y configuración de ejecución

Las Routes personalizadas solo apuntan a Tags. Verifica el dominio, el certificado TLS, la ubicación en nginx y el destino del Tag antes de anunciar una versión. Las vistas previas comodín opcionales dan a cada despliegue un nombre de host inmutable, útil para revisar un artefacto concreto sin cambiar un Tag público, y a cada Tag un nombre de host estable <project hash>-<tag>.<wildcard domain> que sigue al Tag cuando se mueve. El hash del proyecto es aleatorio, así que los nombres de host de las vistas previas nunca revelan el nombre de los proyectos. Los nombres de Tag nuevos deben ser etiquetas DNS en minúsculas de 50 caracteres como máximo.

Las vistas previas son públicas para cualquiera que tenga el enlace. Para protegerlas, elige una lista de acceso en los ajustes Preview links del proyecto: sus reglas de IP y su autenticación básica se aplican entonces a todas las vistas previas del proyecto, y el HTTP sin cifrar redirige a HTTPS. Las vistas previas protegidas necesitan el daemon de nginx de la 2.11: un nodo cuyo daemon no puede aplicar listas de acceso a las vistas previas retiene las vistas previas del proyecto en lugar de servirlas abiertas. Desactivar un proyecto revoca sus vistas previas. Rotate links da al proyecto un hash nuevo y nombres de host de despliegue nuevos, lo que revoca todos los enlaces de vista previa compartidos hasta ese momento.

La configuración de ejecución son datos públicos del lado del cliente y está separada de la identidad inmutable del artefacto. Se expone al sitio como window.runtime.config, con un objeto Default y sustituciones de objeto completo por Tag. Las vistas previas inmutables de los despliegues usan Default; una Route de un Tag y el nombre de host de vista previa del Tag usan la sustitución del Tag cuando existe o recurren a Default. No pongas secretos, credenciales ni topología privada en la configuración de ejecución.

La configuración de ejecución es útil para los orígenes de API públicos, la presentación de funciones, los identificadores de analítica o las etiquetas de entorno que corresponden legítimamente al navegador. Una sustitución por Tag reemplaza el objeto completo en lugar de combinar claves individuales, así que revisa todos los campos necesarios al crear una sustitución. Mantén el contrato compatible con todos los despliegues que el Tag pueda seleccionar durante una reversión.

Promueve, revierte y verifica

1. Crea un despliegue inmutable nuevo mediante Git o una publicación manual.
2. Revisa el resultado de su build o de su subida y prueba el artefacto a través de una vista previa adecuada o de una Route controlada.
3. Mueve el Tag previsto al despliegue verificado.
4. Verifica el camino DNS y TLS de la Route, la respuesta esperada, los recursos estáticos y la configuración de ejecución visible en el navegador.
5. Supervisa la Route, el estado aplicado en nginx y las operaciones del proyecto después de la promoción.

Para revertir, mueve el Tag de la Route a un despliegue anterior que se sepa que funciona. El artefacto antiguo permanece sin cambios, y la reversión queda registrada como un cambio de publicación del Tag. Mantén la configuración de ejecución compatible con versiones anteriores mientras un Tag pueda moverse entre versiones; cambiar la configuración de ejecución no crea un despliegue nuevo.

La versión solo es correcta cuando el dominio personalizado devuelve el documento previsto, los recursos referenciados se cargan sin errores, TLS es válido, la navegación del lado del cliente funciona tras una recarga directa y el navegador recibe la configuración de ejecución prevista. Una vista previa inmutable demuestra el artefacto; no demuestra el dominio de producción, el certificado, el Tag ni los valores de ejecución específicos del entorno.

Consecuencias para el ciclo de vida

Eliminar un despliegue retira esa versión inmutable de futuras selecciones y puede eliminar un destino de reversión. Elimínalo solo después de revisar los requisitos de retención y las referencias de los Tags. Eliminar un Tag o una Route cambia la accesibilidad, no el contenido del despliegue seleccionado. Desactivar Pages retira la función de la navegación normal conservando los datos de los proyectos, y Pages se puede volver a activar más adelante. Los despliegues cuyos archivos ya ha eliminado la retención se ocultan de la lista de despliegues.

Detalles para operadores: ubicación y recuperación

Opfield guarda el artefacto de Pages de forma centralizada y materializa réplicas en los nodos nginx asignados. Si una Route falla mientras el despliegue sigue listo, inspecciona la ubicación del dominio, el nodo Ingress, la relación con el certificado, el destino del Tag y la operación de Pages antes de reconstruir. Volver a construir el mismo código no sustituye a restablecer el camino de servicio.

Si una promoción provoca un incidente, mueve primero el Tag de producción al despliegue verificado anterior. Cambia la configuración de ejecución solo cuando forme parte del fallo y siga siendo compatible con el destino de reversión. Conserva el despliegue fallido, el registro del build y los logs hasta entender el incidente; la inmutabilidad los convierte en pruebas útiles.

Siguiente paso

• Construye y publica un despliegue de Pages desde Git