Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Page caching: document the warm origin, and that rendering and warming need different URLs

Cerrado Apto para principiantes
  • ¿Algo no está bien?
#92 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
75/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
docker, javascript, kubernetes, node.js, nuxtjs
Área
backend, devops, documentation

Línea de trabajo

El archivo a editar es content/5.nuxt-module/11.page-caching.md, específicamente la sección 'Warming the cache from site settings'. Lea la documentación existente para comprender la estructura actual, luego agregue la explicación faltante sobre cuándo y por qué configurar NUXT_CWA_PAGE_CACHE_WARM_ORIGIN, centrándose en implementaciones de un solo servidor frente a Kubernetes. Verifique la ruta del certificado de Caddy mencionada en el issue con el diseño de volúmenes del proyecto. Asegúrese de que las dos correcciones menores sobre el bloqueo de single-flight y la lista de fallos también se incorporen. Pruebe construyendo la documentación localmente para confirmar que se conserva el formato.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

From cwa-nuxt-module#343. The module change is diagnosis only — how the warm connects is unchanged — but the page-caching docs are missing the thing that makes a single-server deploy work at all.

Page: content/5.nuxt-module/11.page-caching.md, in Warming the cache from site settings. NUXT_CWA_PAGE_CACHE_WARM_ORIGIN is listed as an option, but not when you would set it — and on a single-server deploy it is mandatory, not an escape hatch.

The point to get across

origin defaults to the origin of apiUrl, and the public host still travels in the Host header, so the page is stored under the key visitors hit and the request never leaves the cluster.

On Kubernetes, leave it unset — Caddy there listens on port 80 with no HTTPS and no redirect, so the derived origin is already right.

On a single-server deploy, where Caddy runs its own automatic HTTPS, it must be set, and to a different URL from the one the server renders with. These are not the same request and they need different schemes:

URL Why
Rendering (apiUrl) http://php.local/_api Over HTTPS the TLS name would be the internal host, which only an internally issued certificate covers, and Node rightly refuses it.
Warming (NUXT_CWA_PAGE_CACHE_WARM_ORIGIN) https://php.local The warm sends the public Host, so the TLS name becomes the real domain and its ACME certificate validates.

Over plain HTTP on that stack, Caddy's automatic HTTPS answers every page with a 308, so every page is reported failed and nothing is warmed.

Worth stating explicitly: don't keep the warm on HTTP to dodge the certificate. Caddy's reverse_proxy sets X-Forwarded-Proto from the scheme it terminated, so pages would be rendered and cached with http:// canonical and og:url values no visitor ever receives — for the API's full cache lifetime.

Where Caddy issues the certificate itself (SERVER_NAME=localhost, a .local host, or tls internal) the warm fails with DEPTH_ZERO_SELF_SIGNED_CERT, because Node does not trust Caddy's own root. Point Node at it with NODE_EXTRA_CA_CERTS (Caddy writes the root to /data/caddy/pki/authorities/local/root.crt in its data volume) or --use-system-ca once it is installed in the system trust store. Local development hits the same wall against the self-signed certificate; set origin to a plain http:// URL there instead.

The module offers no way to turn certificate verification off, and won't — worth saying in the docs so nobody goes looking. It would be a permanent invisible downgrade in the only TLS client the module has, and it would make a misconfigured origin succeed quietly: pointed at the wrong host you would be told every page was warmed while nothing was stored.

Two smaller corrections on the same page

  • The single-flight lock is per process: a second request to the same server gets a 409 while one is running, but separate replicas can warm at the same time. The admin message now says "on this server".
  • The failure list now names the cause: a redirect shows where it was sent — /about (308 → https://www.example.com/about) — and an unreachable page shows the underlying error code — /about (no response: DEPTH_ZERO_SELF_SIGNED_CERT). Only a 200 counts as warmed; the page list already excludes redirect routes, so a 3xx here means the request never reached the renderer.

One thing to check before publishing

The /data/caddy/pki/authorities/local/root.crt path is Caddy's documented default but was not confirmed against the template's volume layout — worth a glance.

Background on why the obvious fix was rejected: the issue originally proposed setting servername for https origins. That is a no-op — Node's HTTP agent derives the TLS server name and the certificate identity check from the Host header when none is set, verified against a real TLS server with an SNICallback. The only real failure is certificate trust, which no module code can fix.

Lenguaje dominante
Vue
Estrellas
0
Forks
0
Merge medio
1 h 20 min
PR fusionados (30 d)
1

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de components-web-app/docs

Todos los issues de components-web-app/docs

Issues similares

Más issues de Backend & API Design

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.