Esta página es una traducción automática de la página en inglés, que es la versión de referencia. Leer la página en inglés
Poner un CDN delante de la entrega de archivos multimedia
Un CDN delante del servidor (Cloudflare, Google Cloud CDN, CloudFront, etc.) puede entregar los archivos multimedia (/media/ y /media/proxy/).
Las solicitudes que se responden desde la caché del CDN no consumen CPU ni transferencia del servidor.
Esta guía cubre la configuración en la que el servidor es el origen del CDN (origin pull). Se aplica a cualquier almacén de blobs: con blob = s3 o blob = gcs el servidor
lee los archivos del bucket privado y los sirve bajo /media/ igual que con blob = fs, así que el bucket nunca es el origen del CDN.
Cuando todo el servidor está detrás del CDN, también puede rechazar las solicitudes que no han pasado por él.
Configurarlo
Sección titulada «Configurarlo»Establece media_origin (MY_MEDIA_ORIGIN) con el nombre de host del CDN (por ejemplo, media.example.org).
MY_MEDIA_ORIGIN=https://media.example.org- El valor es solo un origen (
scheme://host[:port]), sin ruta, consulta ni barra final. Se exigehttps, yhttpse admite únicamente para hosts de loopback comolocalhost. Un valor no válido hace que el arranque falle. - Si no se establece, los archivos multimedia se sirven desde el origen del propio servidor (
https://{host}). - Estas URL usan este origen:
{media_origin}/media/...para los archivos multimedia locales y{media_origin}/media/proxy/...para el proxy de los archivos multimedia remotos. Quedan cubiertas todas las URL que emiten la API de cliente, ActivityPub (attachment,icon,imagey eliconde los emoji personalizados) y las vistas previas de enlaces (OGP). - La Content-Security-Policy del cliente web añade este origen a
img-srcymedia-src. - Los URI federados, como el
idde un objeto de ActivityPub, siguen bajohttps://{host}/sea cual seamedia_origin. Solo cambia el lugar desde el que se sirven los archivos, no los identificadores. - Las URL se construyen cada vez que se leen y no se guardan en la base de datos, así que cambiar
media_origincambia también las URL de los archivos multimedia existentes. Las URL antiguas que guardaron servidores remotos siguen funcionando mientras/media/en el origen antiguo siga sirviendo.
Apuntar el CDN al servidor
Sección titulada «Apuntar el CDN al servidor»- Haz que el origen (backend) sea el nombre de host público del servidor (
https://{host}). El CDN solo necesita obtener del servidor las rutas bajo/media/. - El servidor no restringe
/media/ni/media/proxy/por nombre de host. Sirve cualquierHostque envíe el CDN. /media/no requiere autenticación y la Authorized Fetch no se aplica a esa ruta. El servidor responde tal cual a las solicitudes sin firmar del CDN.- En los archivos multimedia remotos (
/media/proxy/{id}/{variant}?sig=...),sigforma parte de la URL. Incluye la cadena de consulta en la clave de caché. De lo contrario, las URL con firmas distintas compartirían una misma entrada. - Deja que el
Cache-Controldel origen decida cuánto tiempo se guarda en caché (no lo sobrescribas en el CDN).
| Ruta | Cache-Control |
|---|---|
/media/{...} (archivos multimedia locales) |
public, max-age=31536000, immutable (un año) |
/media/proxy/{...} (archivos multimedia remotos) |
public, max-age= el número de segundos de la configuración de instancia remote_media_cache_ttl_seconds |
Ambos se devuelven con Cross-Origin-Resource-Policy: cross-origin, de modo que las páginas de otros orígenes pueden leerlos.
En Cloud Run, ingress-cloudflare-media lo configura con OpenTofu: consulta Despliegue en Cloud Run.
Quién puede abrir las URL de archivos multimedia
Sección titulada «Quién puede abrir las URL de archivos multimedia»Las URL de los archivos multimedia no tienen control de acceso. Cualquiera que tenga la URL de un archivo puede abrirlo, sin iniciar sesión, sea cual sea la visibilidad de la publicación a la que está adjunto. Esto es así con o sin CDN, e incluye los adjuntos de las publicaciones solo para seguidores y de los mensajes directos, y las URL de proxy de los archivos multimedia remotos.
- Las URL son difíciles de adivinar: la URL de un archivo local contiene identificadores con una parte aleatoria, y una URL de proxy lleva una firma. Conocer una URL no revela las demás.
- Cualquiera que haya visto una publicación puede compartir las URL de sus archivos multimedia, y esas URL siguen funcionando para otras personas.
- Las respuestas se marcan como
public, así que el CDN y cualquier caché compartida entre el servidor y quien lee pueden conservar una copia (en la tabla anterior verás cuánto tiempo). Esto es lo que permite a un CDN servir archivos multimedia sin consultar al servidor.
Explica a tus usuarios que una publicación no pública limita quién ve la publicación, pero no impide que quien tenga el enlace de un archivo adjunto lo abra.
Eliminación y caché
Sección titulada «Eliminación y caché»Después de eliminar un archivo multimedia, la caché del CDN lo conserva durante max-age. Un archivo eliminado puede seguir visible hasta un año en el caso de los archivos locales, y hasta remote_media_cache_ttl_seconds en el caso del proxy.
El servidor no purga la caché del CDN. Si algo debe desaparecer justo después de una eliminación o de una acción de moderación, purga la caché a mano en la consola o la API del CDN.
Service Worker
Sección titulada «Service Worker»El Service Worker del cliente web no guarda en caché los archivos multimedia de otro origen y deja que los gestione la red del navegador, así que solo se aplica la caché del CDN.
Rechazar las solicitudes que no han pasado por el CDN
Sección titulada «Rechazar las solicitudes que no han pasado por el CDN»Un CDN solo protege al servidor de las solicitudes que pasan por él. Cuando el origen también es accesible en su propia dirección, como ocurre con *.run.app en Cloud Run con tráfico desde internet, cualquiera puede llamarlo directamente, esquivando el WAF y la caché.
Si las direcciones del CDN están en trusted_proxies, quien llame desde la propia plataforma sin servidor del CDN (por ejemplo, un Cloudflare Worker propio) también se conecta desde una dirección de confianza y puede elegir la IP de cliente que ven los límites de frecuencia.
Los tres valores de configuración siguientes cierran esa vía. El CDN añade una cabecera secreta a cada solicitud que reenvía, y el servidor responde 403 a cualquier solicitud que no la lleve, antes de hacer nada más con ella.
- Los navegadores y las aplicaciones (páginas, la API de cliente, OAuth y URL de archivos multimedia) y otros servidores (entregas y consultas de ActivityPub)
llegan al CDN en
hosty en el host demedia_origin. El CDN responde por sí mismo a los archivos/media/en caché y estableceorigin_secret_headercon el valor deorigin_secreten cada solicitud que reenvía al servidor. - La plataforma (sondeos de salud, monitores de disponibilidad, Cloud Tasks y Cloud Scheduler) y cualquier otra persona, como un script o un webhook propio, llegan directamente a la dirección del servidor, sin la cabecera.
- La comprobación de origen se ejecuta primero en el servidor. Deja pasar una solicitud que lleva la cabecera una vez con
origin_secretoorigin_secret_previousy, sin la cabecera, soloGETyHEADde las comprobaciones de salud yPOSTa/_internal/. Elimina la cabecera de todas las solicitudes y rechaza el resto con403. - Una solicitud que pasa llega al cliente web, la API de cliente, OAuth, ActivityPub, las comprobaciones de salud o
/_internal/, o a/media/y/media/proxy/, que leen el almacenamiento multimedia (blob = fs,s3ogcs) o retransmiten el archivo de otro servidor. Una solicitud rechazada recibe403conCache-Control: no-storey se suma amy.http.origin_refused.
Úsalo cuando el servidor tenga una dirección pública que la plataforma no pueda cerrar a todo excepto al CDN. No lo necesitas cuando un cortafuegos o la propia plataforma ya limitan quién puede conectarse, por ejemplo un servidor que escucha solo en una red privada detrás de tu balanceador de carga.
Tampoco cuando ese balanceador de carga comprueba él mismo la cabecera del CDN y admite solo las direcciones del CDN, como puede hacer un Application Load Balancer de AWS detrás de CloudFront con una regla de listener y la lista de prefijos administrada com.amazonaws.global.cloudfront.origin-facing. En ese caso, incluye en trusted_proxies tanto las direcciones del balanceador de carga como las del CDN, ya que cada uno añade su entrada a X-Forwarded-For.
No sirve cuando es una función de la propia plataforma la que reenvía el tráfico y no añade ninguna cabecera que controles, como una asignación de dominio de Cloud Run. Solo sirve un CDN o un balanceador de carga que pueda añadir una cabecera de solicitud.
| Configuración | Qué contiene |
|---|---|
origin_secret (MY_ORIGIN_SECRET) |
El valor, de al menos 32 bytes de ASCII visible. Es un secreto, y se lee del entorno o de MY_ORIGIN_SECRET_FILE |
origin_secret_header (MY_ORIGIN_SECRET_HEADER) |
El nombre de la cabecera, el que elijas. Obligatorio junto con origin_secret. No son válidos los nombres que un CDN se niega a establecer o que lee el servidor o un proxy, como los que empiezan por cf- o x-cf- |
origin_secret_previous (MY_ORIGIN_SECRET_PREVIOUS) |
Un segundo valor aceptado, solo durante una rotación |
Si no se establece ninguno, no se comprueba nada y el servidor se comporta como si esta sección no existiera.
Qué pasa sin la cabecera
Sección titulada «Qué pasa sin la cabecera»| Solicitud | Por qué |
|---|---|
GET o HEAD de /healthz, /readyz, /health/live, /health/ready, /api/v1/instance/health |
Las sondas de la plataforma y los monitores de disponibilidad las llaman directamente |
POST a rutas /_internal/ |
Cloud Tasks y Cloud Scheduler las llaman en la propia URL del servidor. Llevan su propio token firmado |
Todo lo demás necesita la cabecera, también en el modo de mantenimiento: el cliente web y sus recursos, /media/, la API de cliente, OAuth y ActivityPub, incluidas las entregas de otros servidores.
Por tanto, todo lo que llame al servidor directamente por su propia dirección, en lugar de a través de la CDN, se rechaza: un webhook propio, un servidor multimedia de voz, un script. Apúntalo al nombre de host de la CDN.
El puerto de métricas (metrics_listen) es un listener aparte que no es público y no se comprueba.
Una solicitud que no lleva el secreto no tiene voz en el resto del tratamiento, aunque pase: su IP de cliente es la del par de la conexión, diga lo que diga X-Forwarded-For, y su traceparent y su X-Request-Id se ignoran.
Configurarlo
Sección titulada «Configurarlo»Todo nombre de host que la CDN reenvía al servidor necesita la cabecera: host, el host de media_origin y un account_domain aparte si la CDN lo sirve. Un host de contenido multimedia detrás de la misma CDN también la define, ya que /media/ se rechaza como todo lo demás.
-
Genera el valor y elige un nombre que nada más use:
Ventana de terminal openssl rand -hex 32 -
Define primero la cabecera en la CDN. El servidor ignora una cabecera que no conoce, así que este paso aún no cambia nada.
- Cloudflare: una regla de transformación de cabecera de solicitud (Rules, luego Transform Rules, luego Modify Request Header), en cualquier plan. Haz coincidir todas las solicitudes entrantes de la zona y elige Set static con tu nombre y valor. Sustituye un valor que envió un cliente. Una regla solo para algunos nombres de host deja a los demás bloqueados.
- Amazon CloudFront: una cabecera personalizada de origen en el origen de cada distribución. También sustituye el valor del espectador.
- Balanceadores de carga de Google Cloud: una cabecera de solicitud personalizada en el servicio de backend.
- Cualquier otra CDN o proxy: la cabecera debe definirse, no añadirse, en cada solicitud al servidor.
-
Define
MY_ORIGIN_SECRETyMY_ORIGIN_SECRET_HEADERy despliega.my config checklos valida y repite lo que se comprueba, pero no puede ver la CDN. -
Comprueba desde fuera, con la dirección del propio origen:
Ventana de terminal curl -s -o /dev/null -w '%{http_code}\n' https://<host>/ # 200: through the CDNcurl -s -o /dev/null -w '%{http_code}\n' https://<origin address>/ # 403: directlycurl -s -o /dev/null -w '%{http_code}\n' https://<origin address>/health/live # 200: a health check
Incluye también las direcciones de la CDN en trusted_proxies, o el servidor ve un solo cliente y todas las solicitudes comparten los límites de tasa de la CDN; my config check avisa de ello.
Una solicitud rechazada recibe el mismo documento de problema 403 que cualquier otra solicitud prohibida, con Cache-Control: no-store, sea cual sea el modo en que la cabecera era incorrecta. Nada en la respuesta nombra la cabecera.
Cuando todos quedan bloqueados
Sección titulada «Cuando todos quedan bloqueados»Una configuración incorrecta rechaza todas las solicitudes mientras las comprobaciones de salud siguen en 200, así que la plataforma ve un servidor sano y un monitor de disponibilidad de /health/live no ve nada. Las señales son:
403en todas las páginas a través de la CDN.- La métrica
my.http.origin_refusedsube mientras las solicitudes dehttp.server.request.durationse detienen. - Líneas
http requesten el registro con el estado403y sinhttp.route. El registro y las trazas nunca contienen la cabecera, su nombre ni su valor. Una solicitud rechazada no crea ningún span de traza.
Para recuperarte, despliega sin la comprobación: quita MY_ORIGIN_SECRET y MY_ORIGIN_SECRET_HEADER. Otros servidores reintentan sus entregas, pero las personas no pudieron llegar al servidor mientras tanto.
Después compara el nombre y el valor en la CDN con los ajustes, comprueba que la regla cubre todos los nombres de host y vuelve a definirlos.
Rotar el valor
Sección titulada «Rotar el valor»El CDN y el servidor no pueden cambiar en el mismo instante, y cada réplica del servidor se reinicia a su ritmo, así que con un solo valor aceptado un cambio rechazaría el tráfico mientras difieran. Por eso el servidor acepta dos valores durante una rotación:
- Establece
MY_ORIGIN_SECRETcon el valor nuevo yMY_ORIGIN_SECRET_PREVIOUScon el antiguo, y despliega. Ambos valores pasan. - Cambia el valor en el CDN y espera a que el cambio llegue a todas sus ubicaciones.
- Quita
MY_ORIGIN_SECRET_PREVIOUSy despliega.my config checkavisa mientras esté establecido.
El nombre de la cabecera no rota de este modo. Para cambiarlo, repite la configuración con la comprobación del servidor desactivada un momento, o establece el nombre nuevo en el CDN junto al antiguo antes de desplegarlo.
Para LLM y agentes de programación:llms.txt,llms-full.txt, llms-small.txt