Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Chiusa Adatta ai principianti
  • Qualcosa non va?
#92 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
75/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
docker, javascript, kubernetes, node.js, nuxtjs
Ambito
backend, devops, documentation

Direzione di ricerca

Il file da modificare è content/5.nuxt-module/11.page-caching.md, in particolare la sezione 'Warming the cache from site settings'. Leggere la documentazione esistente per comprenderne la struttura attuale, quindi aggiungere la spiegazione mancante su quando e perché impostare NUXT_CWA_PAGE_CACHE_WARM_ORIGIN, concentrandosi sui deployment a server singolo rispetto a Kubernetes. Verificare il percorso del certificato Caddy menzionato nell'issue rispetto al layout dei volumi del progetto. Assicurarsi che le due correzioni minori riguardanti il lock single-flight e l'elenco dei fallimenti siano anch'esse incorporate. Testare compilando la documentazione localmente per confermare che la formattazione sia preservata.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
Vue
Stelle
0
Fork
0
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di components-web-app/docs

Tutte le issue di components-web-app/docs

Issue simili

Altre issue su Backend & API Design

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.