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
Ejecutar el servidor: arranque, parada y comprobaciones de salud
Cómo arrancar y detener el servidor, obtener su imagen y vigilarlo mientras funciona: métricas, trazas, la cola de trabajos y las comprobaciones de salud.
Iniciar el servidor
Sección titulada «Iniciar el servidor»my config check # report every configuration problem at oncemy config check -instance # also warn about instance settings that are not set (opens the database)my serve # start according to the configured role (-config <file> reads a TOML file)my version # print the version of the binarymy serve valida la configuración, construye los adaptadores de base de datos, cola de jobs y gestión de claves, y acepta HTTP en listen.
Con tls = off, el valor predeterminado, habla allí HTTP/1.1 sin cifrar: pon delante un proxy inverso o un balanceador de carga que termine HTTPS (y HTTP/2 o HTTP/3 para los clientes) y reenvíe por HTTP/1.1.
Para servir HTTPS sin un proxy, consulta Servir HTTPS desde el servidor.
Las actualizaciones en tiempo real (GET /api/v1/streaming, los streams de las cronologías local y federada y los streams de las salas de chat de voz) son respuestas de larga duración que envían un comentario de latido cada 30 segundos (15 en una sala de voz) y permanecen abiertas mientras están inactivas.
El proxy no debe almacenar en búfer estas respuestas (nginx: el servidor envía X-Accel-Buffering: no), y su timeout de inactividad o de lectura debe ser mayor que el intervalo del latido.
No aplica el esquema ni ejecuta los pasos de actualización de datos: ejecuta my schema apply y luego my db upgrade antes de iniciar (consulta Base de datos; las actualizaciones ejecutan ambos como parte de Actualizar). Hasta que my db upgrade ha registrado cada paso de la versión, /readyz responde 503.
En la configuración de Docker Compose (deploy/docker/compose.yaml; consulta Desplegar con Docker Compose), los servicios puntuales schema y upgrade ejecutan my schema apply y my db upgrade antes de que arranque el servidor.
Si el esquema no está aplicado, el proceso arranca de todos modos y la readiness devuelve 503, y no sirve nada más hasta que el esquema exista.
El primer my serve o comando my que usa la base de datos registra en ella host y account_domain. Cuando la configuración difiere de los valores registrados, my serve registra start failed con ambos pares de valores y termina con el código 1, y los comandos imprimen el mismo error. Las excepciones son my schema apply y my db backup, que no comprueban, y el modo de mantenimiento, que no lee la base de datos. my config check -instance y my db upgrade -check comprueban pero no registran nada.
Un proceso que no pudo leer la base de datos cuando arrancó no está listo hasta que pueda, y hasta entonces no ejecuta jobs y responde 503 con Retry-After a toda solicitud salvo las comprobaciones de salud (/healthz, /readyz, /health/live, /health/ready, /api/v1/instance/health). Esto es también lo que hace un servidor iniciado antes de my schema apply. Si entonces encuentra valores distintos, se detiene con el mismo error.
En el perfil production, my config check también comprueba que los ajustes válidos son adecuados para una instancia de producción: los errores, como un host al que otros servidores no pueden llegar o una KEK que no es aleatoria, hacen que termine con 1, y las advertencias, como mail = none, no.
my serve registra ambos como advertencias cuando arranca pero arranca de todos modos, así que ejecuta my config check como un paso del despliegue.
La lista de comprobación de producción enumera las comprobaciones y lo que hay que verificar a mano antes de salir a producción.
role |
HTTP | Worker de jobs |
|---|---|---|
all (predeterminado) |
Todas las rutas | Se ejecuta |
web |
Todas las rutas | No se ejecuta |
worker |
Solo comprobaciones de salud (para sondas de la plataforma) | Se ejecuta |
Los registros van a la salida de error estándar como JSON Lines. Cada línea tiene level (DEBUG, INFO, WARN, ERROR) y severity, el mismo nivel en la forma que lee Cloud Logging (DEBUG, INFO, WARNING, ERROR y CRITICAL para un error que detiene el proceso).
Los registros escritos mientras se atiende una solicitud llevan un request_id, y el mismo ID se devuelve en la cabecera de respuesta X-Request-Id.
Si el X-Request-Id de la solicitud tiene como máximo 128 caracteres de letras, dígitos y -_.:, se usa tal cual, como el ID asignado por un balanceador de carga.
Los registros dentro de una traza (solicitudes y jobs) también llevan trace_id y span_id (consulta Trazas).
Cada solicitud HTTP y cada ejecución de job escribe una línea cuando termina. La línea tiene los mismos nombres y valores que las etiquetas de las métricas de abajo,
así que en Cloud Run con metrics_exporter = none puedes construir métricas basadas en registros de Cloud Logging (contadores y distribuciones) a partir de estas líneas.
Línea (msg) |
Campos |
|---|---|
http request (INFO; las comprobaciones de salud usan DEBUG) |
http.request.method, http.route, my.surface y http.response.status_code (un número) tienen los mismos valores que las etiquetas de http.server.request.duration. También duration_seconds (un número de segundos), url.path (la ruta sin la cadena de consulta), http.response.body.size y request_id. http.route y my.surface están ausentes en las solicitudes que no llegaron a una ruta (comprobaciones de salud, solicitudes rechazadas antes del enrutado), y la métrica no las cuenta. Una solicitud cuyo cliente se fue antes de que el servidor pudiera responder tiene el estado 499 en lugar de un 5xx, salvo que un handler entrara en pánico; el cliente no recibió nada, así que no cuenta como un error del servidor |
job (INFO si tiene éxito y para postponed, WARN para retry, ERROR para dead) |
my.job.type y my.outcome tienen los mismos valores que las etiquetas de my.job.duration. También duration_seconds (my.job.duration), wait_seconds (my.job.wait), job_id, attempt y error en caso de fallo |
error report (ERROR; CRITICAL para un fallo que detiene el proceso) |
Una línea por error notificado (Informes de errores) |
Informes de errores
Sección titulada «Informes de errores»La guía de Informes de errores explica dónde leer estas líneas en cada plataforma, la pantalla de errores, las notificaciones y el envío de informes a un rastreador de errores.
El servidor informa de los errores que requieren la atención del operador como una línea error report cada uno:
- un pánico en un manejador HTTP, un trabajo o una tarea en segundo plano;
- un error detrás de una respuesta 5xx de la API de cliente, la API de administración, las páginas de inicio de sesión, ActivityPub, OAuth o los archivos multimedia;
- un trabajo que falla definitivamente (
dead): agotó los reintentos o se negó a ejecutarse de nuevo. No se informa de las entregas que se abandonaron porque el otro servidor seguía fallando; - un fallo al arrancar: una configuración no válida, o una base de datos o un adaptador que no se puede preparar.
No se informa de las respuestas 4xx, los reintentos de trabajos, el modo de mantenimiento, las comprobaciones de disponibilidad fallidas, las solicitudes cuyo cliente se fue ni los fallos causados por otros servidores; los cubren las métricas y las demás líneas de registro.
Cuando el cliente de una solicitud se va, las demás líneas de error del servidor para esa solicitud se escriben en INFO en lugar de ERROR, ya que la mayoría solo dicen que la solicitud se canceló.
La línea tiene la forma que lee Google Cloud Error Reporting: en Cloud Run, los informes aparecen en Error Reporting agrupados como errores sin ninguna configuración. En otras plataformas es una línea JSON simple:
| Campo | Valor |
|---|---|
@type, serviceContext |
El tipo de evento de Error Reporting, y {"service": "my", "version": "<version>"} |
my.error.fingerprint |
32 dígitos hexadecimales que son iguales en todas las apariciones del mismo error: construidos a partir del origen, el lugar, el tipo de error y las funciones del servidor en la traza de pila, sin números de línea |
my.error.source, my.error.kind |
server (o web), y panic o error |
my.error.where |
Dónde ocurrió: <surface> <method> <route> para una solicitud (como client_api GET /api/v1/statuses/{id}), el tipo de trabajo para un trabajo, el nombre de la tarea para una tarea en segundo plano, startup para un fallo al arrancar |
my.role, deployment.environment.name |
El role del proceso y errors_environment |
request_id, job_id, attempt, trace_id, span_id |
Los ID para encontrar las líneas de solicitud o de trabajo del mismo error, cuando los tiene |
context.httpRequest |
En el error de una solicitud: method, url (la ruta, como /api/v1/statuses/{id}, nunca la ruta que pidió el cliente) y responseStatusCode, el estado devuelto (500) |
message |
Lo último de la línea: <type>: <message>, un salto de línea y la traza de pila de Go |
Antes de que un informe salga del proceso, en el mensaje se sustituyen las URL, las direcciones de correo electrónico, las menciones @user@host, las direcciones IP, los UUID y ULID y los números de 10 dígitos o más por <url>, <email>, <acct>, <ip>, <id> y <n>, y se recorta a 1 KiB.
La traza de pila conserva las posiciones de archivo pero no los valores de los argumentos de sus líneas de función (se muestran como (...)), y se recorta a 16 KiB. Ningún informe lleva cuerpo de solicitud, cabecera, consulta, cookie, cuenta, nombre de usuario, dirección IP ni User-Agent.
Ninguna otra línea lleva una traza de pila, así que Error Reporting encuentra solo las trazas de pila de estas líneas.
El nombre de un campo es una única clave que contiene .; no está anidado. Entrecomíllalo en los filtros y extracciones de Cloud Logging (por ejemplo jsonPayload."http.route", y EXTRACT(jsonPayload.duration_seconds) para el valor de una distribución).
Los campos usados como etiquetas toman valores solo de un conjunto finito; url.path, request_id y job_id nunca son etiquetas.
Con metrics_exporter = emf, estas dos líneas son las propias líneas EMF. La línea http request lleva el valor de http.server.request.duration, y la línea job lleva los valores de my.job.duration y my.job.wait (claves con el nombre de las métricas),
además de la directiva _aws, service.name, service.version y my.role. Estas tres métricas no se escriben en ninguna otra línea. Los campos que eliges en metrics_emf_dimensions se escriben como cadenas, como exige EMF (por ejemplo, la dimensión http.response.status_code es "200").
Los registros van a la salida de error estándar y las demás líneas EMF van a la salida estándar. El controlador de registros awslogs de ECS envía ambas a CloudWatch Logs, así que las métricas se extraen de las dos.
Archivos de Docker Compose
Sección titulada «Archivos de Docker Compose»deploy/docker/ contiene lo que despliega una instancia. compose.yaml se ejecuta solo, y los demás archivos se apilan sobre él.
| Archivo | Añade | Úsalo cuando |
|---|---|---|
compose.yaml |
El servidor y sus servicios puntuales de base de datos, con SQLite y archivos multimedia en el volumen data |
Siempre |
compose.postgres.yaml |
PostgreSQL en un contenedor, en el volumen postgres |
Quieres PostgreSQL en esta máquina. Para un servidor PostgreSQL en otro lugar, omítelo y define MY_DATABASE y MY_DATABASE_URL en .env |
compose.s3.yaml |
Multimedia en un bucket compatible con S3; con COMPOSE_PROFILES=garage también un almacén Garage de un nodo en el volumen garage |
La multimedia supera un disco, o la quieres en un bucket. Sin el perfil, el almacén es el externo de los ajustes MY_BLOB_S3_* |
compose.caddy.yaml |
Caddy, con certificados TLS en los puertos 80 y 443 | MY_HOST es un dominio público y nada más termina TLS en esta máquina |
compose.build.yaml |
Construye la imagen desde un checkout | Ejecutas tu propia compilación |
Elige la base de datos y el almacén de multimedia antes del primer arranque: los datos no se mueven solos cuando cambian los archivos (Copias de seguridad muestra lo que hay que mover).
Apila los archivos con opciones -f en ese orden, o nómbralos una vez en .env, para que todos los comandos docker compose posteriores
(exec, logs, pull y los de las otras guías) usen los mismos archivos:
cd deploy/dockercp example.env .env# In .env: COMPOSE_FILE=compose.yaml:compose.postgres.yaml:compose.caddy.yamlUn archivo llamado compose.override.yaml en el directorio se lee solo cuando ni -f ni COMPOSE_FILE nombran archivos. Con
ellos, inclúyelo también en la lista.
Ajustes. Copia example.env a .env. Compose lee .env para rellenar las variables de sus archivos, y entrega todo el
archivo a los contenedores del servidor, así que todos los ajustes de la referencia de configuración funcionan
definiéndolos allí. La plantilla los enumera todos, con una frase sobre cada uno.
- La clave de cifrado de claves queda fuera de
.env, en el archivosecrets/kek, y los contenedores la leen como el secreto de Docker/run/secrets/my_kek, así que nunca se convierte en una variable de entorno. Una líneaMY_KEKen.envdetiene el servidor, que rechazaMY_KEKyMY_KEK_FILEjuntos (gestionar la clave). - El servidor se ejecuta como el usuario
65532, y Compose monta el archivo con los permisos que tiene, así que el archivo tiene que ser legible por otros. Guárdalo en un directorio al que solo puedas entrar tú, como hacen los comandos deexample.env. - Los demás secretos llegan a los contenedores como variables de entorno. Para pasar uno como archivo en su lugar, móntalo con un secreto
en un
compose.override.yamlpropio y define su<NAME>_FILE, como hacecompose.yamlpara la clave. .envcontiene secretos:chmod 600 .env, y conserva una copia con tus copias de seguridad.MY_LISTENpermanece en:8080, ya que los archivos se conectan a ese puerto, salvo que el servidor sirva HTTPS por sí mismo (Servir HTTPS desde el servidor).
TLS con Caddy. Define MY_HOST con un dominio cuyo DNS apunte a la máquina, con los puertos 80 y 443 accesibles desde
internet, y elimina MY_WEB_ORIGIN de .env. Caddy obtiene y renueva el certificado por sí mismo en la primera solicitud.
El servidor confía en el X-Forwarded-For de los pools de direcciones predeterminados de Docker; define MY_TRUSTED_PROXIES si los tuyos difieren.
El Garage incluido. compose.s3.yaml con COMPOSE_PROFILES=garage necesita los valores que example.env enumera al principio.
El servicio puntual garage-init prepara el almacén en cada up. Permanece dentro de la red de Compose, ya que el servidor
sirve la multimedia por sí mismo. Un nodo es un disco: haz copia de seguridad del volumen garage o del bucket (Copias de seguridad).
Servir HTTPS desde el servidor
Sección titulada «Servir HTTPS desde el servidor»my puede servir HTTPS por sí mismo, de modo que una máquina pequeña ejecute todo el servidor como un solo binario con un dominio y los puertos 80 y 443,
sin un proxy inverso. Con tls = acme, obtiene sus certificados de una autoridad de certificación ACME como Let’s
Encrypt. Con tls = files, sirve un certificado y una clave que tú proporcionas y mantienes al día con otra herramienta, como
certbot.
MY_TLS=acmeMY_TLS_ACME_AGREE_TERMS=true # you agree to the terms of service of the certificate authority# MY_TLS_ACME_EMAIL=ops@social.example optional contact of the account# MY_LISTEN=:443 the default with tls other than off# MY_TLS_HTTP_LISTEN=:80 the default; empty opens no port 80MY_TLS=filesMY_TLS_CERT_FILE=/etc/letsencrypt/live/social.example/fullchain.pemMY_TLS_KEY_FILE=/etc/letsencrypt/live/social.example/privkey.pem- Puertos. El servidor sirve HTTPS en
listen(:443por defecto una vez quetlsno esoff). Entls_http_listen(:80por defecto) redirige con301las solicitudesGETyHEADa la misma ruta enhttps, y responde400a todo otro método, para que ningún cuerpo de solicitud viaje en texto plano. - Hosts. El servidor sirve
host, y el host deweb_origincuando difiere. Un handshake para cualquier otro nombre falla sin certificado, y nunca hace que el servidor pida uno. - Conexiones. TLS 1.2 o posterior con los conjuntos de cifrado predeterminados de Go, HTTP/2 y HTTP/1.1, como máximo 64 KiB de cabeceras
de solicitud, y como máximo 100 streams concurrentes en una conexión HTTP/2. Los timeouts son los de HTTP sin cifrar. El servidor
sigue añadiendo
Strict-Transport-Securitya cada respuesta (Cabeceras de seguridad). - Roles. Solo los roles
webyallescuchan con TLS. Unworkersirve sus comprobaciones de salud en HTTP sin cifrar enlisten(:8080por defecto) y no abre el puerto 80. - Direcciones de cliente. Sin un proxy delante, el par de la conexión es el cliente: deja
trusted_proxiesvacío. Defínelo solo cuando una CDN delante se conecta al servidor porhttps. - Modo de mantenimiento.
my serve -maintenanceno lee nitlsni los certificados y responde en HTTP sin cifrar enlisten(:8080salvo que lo definas), así que apuntaMY_LISTENy tu cortafuegos a ese puerto mientras se ejecuta, o conserva un proxy inverso para el mantenimiento.
Certificados de una autoridad de certificación ACME
Sección titulada «Certificados de una autoridad de certificación ACME»Con tls = acme, el servidor pide un certificado para cada uno de sus hosts que no tiene ninguno, a la autoridad de certificación
de tls_acme_directory (Let’s Encrypt por defecto).
- Antes de empezar.
hostdebe ser un nombre DNS que apunte al servidor, y los puertos 443 y 80 deben ser accesibles desde internet: la autoridad de certificación comprueba que el servidor controla el nombre conectándose a él. Responde enlisten(el desafío TLS-ALPN-01) o entls_http_listen(el desafío HTTP-01), así que untls_http_listenvacío sigue funcionando solo con el puerto 443. Los certificados comodín y la validación mediante registros DNS no están disponibles. - Primer arranque. El servidor empieza a escuchar sin esperar a un certificado, y luego los pide. Hasta que un host tiene su
certificado, un handshake para él falla; con Let’s Encrypt los primeros certificados suelen llegar en un minuto. El registro
dice
obtained a TLS certificatepara cada host, ythe TLS certificate could not be obtainedcon el motivo cuando un pedido falla. - Renovaciones. El servidor renueva cada certificado en el momento que le sugiere la autoridad de certificación (ACME Renewal
Information): elige una vez una hora aleatoria dentro de la ventana sugerida, la mantiene mientras la ventana siga igual, y pregunta de nuevo
según el
Retry-Afterde la autoridad, al menos cada 12 horas, para que una autoridad que deba sustituir certificados antes de tiempo pueda mover la ventana. Cuando la autoridad no ofrece tal ventana, el servidor renueva tras dos tercios de la vida del certificado, o tras la mitad de ella para un certificado válido durante menos de 10 días. Una renovación dice a la autoridad qué certificado sustituye, lo que la mantiene fuera de los límites de tasa de Let’s Encrypt. El certificado actual sigue en servicio hasta que llega su renovación, y una renovación que falla espera como lo hace un primer pedido. - Pedidos fallidos. Tras un pedido fallido el servidor espera antes del siguiente para el mismo host: 1 minuto tras el primer fallo, 10 minutos tras el segundo, 100 minutos tras el tercero y luego un día, para mantenerse dentro de los límites de la autoridad de certificación. La espera se guarda en la base de datos y sobrevive a los reinicios. Corrige la causa (DNS, un cortafuegos, un puerto) y el siguiente pedido sale cuando termina la espera.
- Dónde se guardan. La cuenta con la autoridad de certificación, los certificados y el registro de cada pedido se guardan en la base de datos; las claves privadas se sellan con la clave de cifrado de claves, como los demás secretos (gestión de claves). Una copia de seguridad de la base de datos los incluye, y un servidor reiniciado sirve los certificados almacenados de inmediato, sin pedir. Cambiar la clave de cifrado de claves los vuelve a envolver; no pide certificados nuevos.
- Varios procesos. Los procesos que comparten la base de datos y el almacén
kvse coordinan: uno pide el certificado de un host mientras los demás esperan y luego lo cargan, y el proceso al que se conecte la autoridad de certificación responde a su comprobación. Usakv = dbokv = valkey;kv = memoryse rechaza salvo que un proceso lo ejecute todo (role = all). El proceso que obtiene un certificado avisa a los demás mediante el broker destream, y lo sirven en segundos; cada procesowebcontls = acmesigue por tanto escuchando en el broker. Constream = hub, o cuando se pierde un aviso, todos los procesos siguen leyendo los certificados actuales de la base de datos cada 5 minutos, y cada minuto una vez que su certificado ha llegado a su hora de renovación, así que una renovación les llega mucho antes de que el certificado antiguo caduque. - Perfiles.
tls_acme_profileelige un perfil que ofrece la autoridad de certificación, comoshortliveden Let’s Encrypt. Vacío toma su valor predeterminado. Tras un cambio de perfil, la siguiente renovación lo sigue, y el certificado que trae se sirve incluso cuando caduca antes que el que sustituye.
Para probarlo sin gastar los límites del entorno de producción de Let’s Encrypt, empieza con su entorno de staging, que emite certificados en los que los navegadores no confían con límites mucho más altos:
MY_TLS_ACME_DIRECTORY=https://acme-staging-v02.api.letsencrypt.org/directoryCuando el registro diga que se obtuvieron los certificados y curl -kv https://social.example/ muestre un certificado de
(STAGING), elimina el ajuste y reinicia. El servidor registra una cuenta nueva en el entorno de producción y
pide allí sus certificados; los de staging permanecen en la base de datos y ya no se sirven.
Certificados desde archivos
Sección titulada «Certificados desde archivos»Con tls = files, tls_cert_file contiene primero el certificado del servidor y luego sus intermedios (el
fullchain.pem de certbot); tls_key_file contiene su clave. El certificado debe cubrir host, y también sirve el host de
web_origin cuando difiere y el certificado lo cubre.
El servidor mira los tiempos de modificación de ambos archivos cada minuto y los carga de nuevo cuando cualquiera cambia, sin reiniciar. Un par que aún no coincide (un certificado nuevo antes de su clave nueva) mantiene el certificado anterior en servicio hasta la siguiente comprobación, y el registro dice por qué.
Comandos y métricas
Sección titulada «Comandos y métricas»my tls muestra y controla los certificados con la configuración del servidor, desde cualquier máquina que llegue a la
base de datos (la CLI de administración):
my tls status # each host: certificate, renewal, latest ordersmy tls renew -host social.example # order now, without waitingmy tls revoke -host social.example -reason key_compromisestatusmuestra, para cada host, el certificado actual (su número de serie, emisor y caducidad), cuándo se renueva (la ventana de la autoridad de certificación, o la hora derivada de su vida), cuántos pedidos seguidos no obtuvieron ninguno y los últimos pedidos con sus errores. Contls = filesmuestra el certificado detls_cert_file.renewpide un certificado ahora, omitiendo la hora de renovación y la espera tras pedidos fallidos: ejecútalo una vez que hayas corregido la causa de los pedidos fallidos. El servidor en ejecución responde a la comprobación de la autoridad de certificación, así que debe estar en marcha, y sus procesos sirven el certificado nuevo en segundos, o en 5 minutos constream = hub.revokepide primero un certificado que sustituya al actual, luego pide a la autoridad de certificación que revoque el actual y lo anota; todos los procesos dejan de servir el certificado revocado en segundos, o en 5 minutos constream = hub. Usakey_compromisecuando otras personas pueden conocer la clave privada, ysupersededuoperatoren otro caso. Cuando no se puede pedir el sustituto, la revocación se lleva a cabo de todos modos: los procesos sirven el certificado anterior del host si no está revocado, o nada hasta que el servidor obtenga uno nuevo.renewyrevokenecesitantls = acmey unkvdistinto dememory, ya que los procesos a los que se conecta la autoridad de certificación leen del almacénkvlas respuestas a sus comprobaciones. Contls = filesse rechazan: renueva o revoca el certificado con la herramienta que escribe los archivos.
Con metrics_exporter definido, pon alertas sobre my.tls.certificate.expiry por debajo de 7 días y sobre
my.tls.order.consecutive_failures de 3 o más (alertas): una renovación que falla se nota
semanas antes de que el certificado caduque.
Comprobaciones y ejecución
Sección titulada «Comprobaciones y ejecución»my config check informa, con tls = acme, de unos términos a los que no se ha dado conformidad, un host que es una dirección IP, localhost
o un nombre sin punto, un tls_acme_directory que no es una URL https y kv = memory con un role distinto de
all, como errores. Con tls = files informa de un certificado o una clave que no se pueden leer, una clave que no coincide con el
certificado, y un certificado que no cubre host, ha caducado o aún no es válido, como errores, y avisa cuando
quedan menos de 14 días. Avisa cuando trusted_proxies está definido con tls distinto de off. Con tls = off avisa
cuando listen es el puerto 80 o 443 en una dirección distinta de loopback, ya que nada parece terminar TLS delante del
servidor; el servidor registra la misma advertencia una vez por arranque cuando un servidor así, con trusted_proxies vacío, recibe una solicitud
HTTP sin cifrar desde una dirección distinta de loopback.
systemd. Los puertos por debajo de 1024 necesitan una capability para un usuario distinto de root. Dásela al servicio y a nada más:
[Service]User=myAmbientCapabilities=CAP_NET_BIND_SERVICECapabilityBoundingSet=CAP_NET_BIND_SERVICECon tls = files, el usuario también necesita leer los archivos de certificado. Con certbot, sus directorios live y archive
son legibles solo por root: da acceso al grupo del servicio (chgrp y chmod g+rx en los directorios, g+r en
las claves), o copia los archivos en un deploy hook a un directorio que lea el servicio.
Docker. Docker 20.10 y posteriores permiten que un contenedor abra puertos por debajo de 1024 sin una capability, así que la imagen funciona tal
cual. La imagen define MY_LISTEN=:8080, así que define MY_LISTEN=:443 en .env y publica ambos puertos en un
compose.override.yaml (ports: ["80:80", "443:443"]). Con tls = files, monta los archivos de certificado en solo lectura
donde apuntan MY_TLS_CERT_FILE y MY_TLS_KEY_FILE; el servidor se ejecuta como el usuario 65532, que debe poder leerlos.
Con tls = acme no hay nada que montar: los certificados viven en la base de datos.
Omite compose.caddy.yaml, que tomaría los mismos puertos. Esto no vale con network_mode: host, donde
el contenedor comparte la red de la máquina y necesita la misma capability que un servicio fuera de un contenedor.
Comparado con Caddy. Servir HTTPS desde my renuncia a HTTP/3, a la compresión de las respuestas (el servidor envía los archivos del cliente
web comprimidos y no comprime nada más), a un registro de acceso propio (las líneas de registro http request del servidor permanecen) y a los certificados validados mediante
DNS, incluidos los certificados comodín. Conserva compose.caddy.yaml, u otro proxy, cuando necesites cualquiera de ellos.
Obtener la imagen
Sección titulada «Obtener la imagen»La imagen del servidor es ghcr.io/mycroblog/my, pública, para linux/amd64 y linux/arm64, con todos los adaptadores.
| Etiqueta | Apunta a | Úsala para |
|---|---|---|
0.1.0 |
Esa versión, para siempre | Nombrar una versión |
0.1 |
El último parche de v0.1 |
Docker Compose, que aplica el esquema en cada up |
0.1.0-rc.1 |
Esa versión preliminar | Probar una versión antes de que salga |
nightly |
El último commit de main que pasó las pruebas nocturnas, movido cada noche en que cambia |
Probar cambios antes de una versión preliminar, en una instancia que puedas desechar |
No existe latest ni 0: ambas cruzarían una versión menor, y cada actualización a una versión menor nueva debe hacerse a través de la anterior. Nombra una versión en cada comando; docker pull ghcr.io/mycroblog/my a secas falla con manifest unknown.
Una versión de parche también puede necesitar my schema apply y my db upgrade, así que fuera de Docker Compose sigue Actualización para cada versión. En producción, fija el digest que indican las notas de la versión:
ghcr.io/mycroblog/my:0.1.0@sha256:...nightly no tiene ruta de actualización. Las actualizaciones solo se prometen entre versiones publicadas: de una imagen nightly a
la siguiente, o de nightly a una versión, el esquema y los pasos de datos de my db upgrade pueden cambiar de maneras por las que no pasa ninguna
versión, así que espera tener que recrear su base de datos. No la ejecutes nunca en producción. my version imprime de qué commit se trata, como en
v0.1.0-rc.5.0.20261109182600.g7a789720a1b2: una versión posterior a la última publicada (v0.1.0-rc.5), la hora del commit en UTC y los
12 primeros caracteres del commit tras la g. Para conservar una compilación, fija su digest (ghcr.io/mycroblog/my:nightly@sha256:...): una compilación más antigua pierde
la etiqueta pero sigue pudiéndose descargar por su digest.
Dónde ejecutarla:
- Docker Compose:
deploy/docker/compose.yamlejecuta la imagen deMY_VERSIONen.env(Archivos de Docker Compose). Para compilarla desde un checkout en su lugar, añade el overridecompose.build.yaml(docker compose -f compose.yaml -f compose.build.yaml up -d --build) y estableceMY_VERSIONcon un nombre propio, ya que da nombre a tu imagen local y es lo que imprimemy version. - Kubernetes: descárgala de
ghcr.iotal cual. - Cloud Run: usa directamente la imagen de
ghcr.io. Un despliegue resuelve la etiqueta a un digest. - AWS (ECS, EKS): copia la imagen a Amazon ECR, o usa un pull through cache de ECR, que necesita credenciales de ghcr.io.
Verificar una imagen
Sección titulada «Verificar una imagen»Cada imagen publicada tiene una procedencia firmada mediante Sigstore, que vincula el digest con el flujo de trabajo y el commit que la compiló, y un SBOM. Con la GitHub CLI, y con la sesión iniciada en ghcr.io si el comando lo pide:
gh attestation verify oci://ghcr.io/mycroblog/my@sha256:... -R mycroblog/my \ --signer-workflow mycroblog/my/.github/workflows/release.ymldocker buildx imagetools inspect ghcr.io/mycroblog/my@sha256:... --format '{{ json .SBOM }}'El primer comando falla a menos que la imagen la haya compilado el flujo de trabajo de publicación de este repositorio. Para una imagen nightly, verifícala con
--signer-workflow mycroblog/my/.github/workflows/nightly.yml en su lugar. Imprime el commit, que es el de la etiqueta de la versión; la etiqueta org.opencontainers.image.revision de la imagen nombra el mismo.
Publicar el código fuente (AGPL-3.0)
Sección titulada «Publicar el código fuente (AGPL-3.0)»my se distribuye con la licencia AGPL-3.0-only. La sección 13 de la AGPL-3.0 exige que quien ejecuta el servidor y permite que los usuarios interactúen con él a través de una red
les ofrezca una forma de obtener el código fuente correspondiente del programa que se está ejecutando. Esto se aplica a todas las personas que interactúan con el servidor, no solo a quienes tienen una cuenta.
Indica dónde se publica el código fuente con el ajuste source_url (variable de entorno MY_SOURCE_URL; consulta la referencia de configuración).
| Valor | Significado |
|---|---|
| Sin establecer | El valor por defecto, https://github.com/mycroblog/my. Úsalo cuando ejecutes my sin modificar: el GET /instance de una versión publicada nombra entonces el código fuente de esa versión, https://github.com/mycroblog/my/tree/v0.1.0, y NodeInfo el repositorio |
Una URL https: |
Un lugar donde se puede leer el código fuente (el repositorio de un fork, la etiqueta o el archivo de una versión concreta, etc.) |
Un URI mailto: |
Una dirección de correo electrónico a la que solicitar el código fuente (por ejemplo mailto:source@example.org; se admite ?subject=...) |
Cualquier otro valor (http:, git@..., una ruta relativa, una URL con información de usuario o un #, un mailto: sin dirección, etc.) hace que my config check falle, y el servidor no arranca.
El valor aparece en estos lugares:
source_urlen elGET /instancede la API de cliente- La sección «Código fuente» de la página de información de la instancia del cliente web (
/about) y un enlace en la página de inicio (/) metadata.sourceCodeen NodeInfo (/nodeinfo/2.1). Una URLhttps:también se publica comosoftware.repository(el esquema de NodeInfo 2.1 solo admite una URLhttp(s)ensoftware.repository, así que un valormailto:aparece únicamente enmetadata.sourceCode)
Si haces un fork o modificas my
Sección titulada «Si haces un fork o modificas my»Si ejecutas un my modificado (aplicas parches, compilas un fork o cambias dependencias), la URL por defecto ya no apunta al código fuente de lo que se está ejecutando.
Cambia source_url por el lugar donde se puede encontrar el código fuente de la versión en ejecución, con tus modificaciones. Apuntar al commit, la etiqueta o el archivo que corresponde a la versión en ejecución, en lugar de al último estado de un repositorio, permite a los usuarios obtener de forma fiable el mismo código fuente.
Si ejecutas una versión oficial sin modificar, conserva el valor por defecto.
Si usas mailto:
Sección titulada «Si usas mailto:»- Prepárate para entregar el código fuente correspondiente (incluidos los scripts necesarios para compilarlo) con prontitud cuando alguien lo pida. Solo nombrar una dirección, sin estar preparado para entregarlo, no cumple la obligación.
- Usa una dirección que siga funcionando cuando dejes de operar el servidor o cambie la persona responsable. Una dirección compartida de operaciones es mejor que un buzón personal.
- Asegúrate de que el filtro de spam no descarte las solicitudes.
- Usa una dirección que no te importe hacer pública: cualquiera puede verla en la página de información, la página de inicio y en NodeInfo.
Métricas
Sección titulada «Métricas»El ajuste metrics_exporter (none por defecto) exporta las métricas del servicio. Sus ajustes relacionados están en la referencia de configuración.
metrics_exporter |
Ruta | Adecuado para |
|---|---|---|
none |
No se exporta nada. La instrumentación cuesta casi nada. Los valores de toda la instancia siguen yendo a una línea de registro metrics snapshot cada 15 minutos |
Cloud Run (usa en su lugar las métricas de la plataforma y las métricas basadas en registros) |
prometheus |
GET /metrics en metrics_listen (127.0.0.1:9464 por defecto). Es un listener separado del listen público, sin autenticación, y se ejecuta para todo role |
Autoalojado (consultado por un servidor compatible con Prometheus o KEDA) |
otlp |
Enviado a un OpenTelemetry Collector por OTLP/HTTP. El destino viene de las variables de entorno estándar de OTel como OTEL_EXPORTER_OTLP_ENDPOINT |
Configuraciones donde puedes ejecutar un collector |
emf |
Líneas JSON de CloudWatch Embedded Metric Format. Las métricas de solicitudes y jobs viajan en las líneas de registro de cierre de arriba; las demás se escriben en la salida estándar, una línea por conjunto de etiquetas, cuando termina una solicitud o un job | AWS ECS |
Las métricas se enumeran abajo. En Prometheus, . en un nombre pasa a _ y se añade un sufijo de unidad (_seconds, y _total para un contador).
| Métrica | Tipo | Etiquetas |
|---|---|---|
http.server.request.duration |
Histograma, segundos | http.request.method, http.route (la ruta del patrón de ruta; other cuando ninguno coincide), http.response.status_code, my.surface (client_api / admin / activitypub / oauth / media / web / payments / voice / queue) |
http.server.active_requests |
UpDownCounter | my.surface |
my.inbox.activities |
Contador | activity.type (un tipo de Activity conocido, u other), my.outcome (accepted / duplicate / rejected / ignored / error), my.inbox.rejection (solo con rejected: signature para una firma o prueba de integridad que falta, no es válida o no se verifica, o cuya clave no pudo obtenerse; suspended para un dominio suspendido; federation_off; rate_limited; invalid para una actividad sin un id, type, actor u object válidos) |
my.relay.activities |
Contador | my.outcome (admitted / over_limit / restricted / not_receiving: si una actividad llevada por un relay se ingirió, y por qué se descartó; consulta Relays de federación) |
my.move.activities |
Contador | my.outcome (recorded / duplicate / not_own_actor / same_account / target_unavailable / alias_missing / target_moved / suspended / too_soon: si un Move recibido se registró, y por qué se descartó) |
my.delivery.attempts |
Contador | my.outcome (success / retry / gone / failed; gone cubre un 410 y las entregas omitidas porque el servidor no está disponible o está suspendido) |
my.delivery.duration |
Histograma, segundos | my.outcome |
my.ux.duration |
Histograma, segundos | my.ux.metric (lcp / inp / long_frame / transition / press / call_rtt / call_jitter), my.ux.name (la ruta, el tipo de interacción, la acción o el transporte de la llamada; mediciones de UX) |
my.ux.call.packet_loss |
Histograma, porcentaje | my.ux.name (el transporte de la llamada) |
my.plugin.failures |
Contador | my.plugin.kind (un tipo de plugin), my.plugin.code (el código Connect del fallo) |
my.plugin.slot_wait |
Histograma, segundos | my.plugin.kind (cuánto esperó una llamada su turno entre las llamadas de ese tipo que se ejecutan a la vez) |
my.hook.decisions |
Contador | hook, mode, outcome (las decisiones que registró un hook de decisión) |
my.hook.failures |
Contador | hook, outcome (timeout, error, invalid o breaker_open) |
my.hook.duration |
Histograma | hook (segundos por llamada al plugin) |
my.job.duration |
Histograma, segundos | my.job.type (un tipo de job registrado, u other), my.outcome (success / retry / dead / postponed: postponed es una ejecución que no hizo trabajo y no usa ninguno de los intentos del job, como una obtención de tarjeta de enlace que espera a su host) |
my.job.wait |
Histograma, segundos | my.job.type |
my.link_card.host_pauses |
Contador | http.response.status_code (429 / 503). Uno por pausa de las obtenciones de tarjetas de enlace de un host; consulta Vistas previas de enlaces |
my.translation.requests |
Contador | my.outcome (author / cache / provider / no_provider / limit / unsupported / failed). Uno por solicitud de traducir una publicación que el espectador puede ver, o una publicación o comentario de una denuncia que pide un moderador: respondida con las propias palabras del autor, con una traducción conservada o por un proveedor, o rechazada porque ningún proveedor puede recibir la publicación, se alcanzó un límite mensual, ningún proveedor traduce el idioma o ningún proveedor devolvió una traducción utilizable. |
my.translation.lock_waits |
Contador | Ninguna. Uno por solicitud que esperó a que otra solicitud tradujera la misma publicación al mismo idioma, en lugar de preguntar a un proveedor |
my.translation.characters |
Contador | my.provider (el ID de un proveedor de traducción). Los caracteres de publicaciones y comentarios de denuncias enviados al proveedor, sin marcadores, incluidas las llamadas que fallan. Esto es lo que cuentan los límites mensuales, y puede diferir de lo que factura el proveedor |
my.timeline.delivery.lag |
Histograma, segundos | Ninguna (desde la creación de una publicación local hasta su escritura en las cronologías de inicio y el aviso a los streams) |
my.stream.connections |
UpDownCounter | my.stream.kind (user, timeline para los streams de las cronologías local y federada, voice para los streams de las salas de chat de voz) |
my.stream.signals |
Contador | my.stream.kind (user / timeline). Uno por señal que gestionó un stream abierto, enviara o no algo al cliente |
my.accounts.registered |
Contador | Ninguna |
my.statuses.created |
Contador | my.visibility |
my.billing.imports |
Contador | my.billing.source (aws / gcp / plugin), my.outcome (success / failed), error.type (solo con failed: el tipo de fallo, como en Importar los cargos de uso en la nube). Cada intento cuenta, incluidos los reintentos y los fallos que esperan a la siguiente importación diaria |
my.supporter.tip_checkouts |
Contador | my.outcome (started / rate_limited / paid / expired). Uno por inicio de una propina que obtuvo la página del proveedor, por inicio que rechazaron los límites y por propina que se pagó o terminó sin pagar; consulta propinas para las alertas a las que sirve |
my.voice.turn.credentials |
Contador | my.voice.turn (coturn / cloudflare), my.outcome (issued / reused / failed). Uno por credencial TURN que pidió un participante del chat de voz al unirse a una sala o al renovar su conexión: reused significa que se devolvieron de nuevo credenciales de Cloudflare emitidas antes para la misma conexión, y failed significa que no se pudo llegar a Cloudflare o este rechazó, así que el participante recibió un error y no pudo conectarse |
my.errors.exported |
Contador | my.outcome (success / dropped / failed: uno por informe de error para el servicio de errors_exporter. dropped significa que el informe no se envió porque ya esperaban 1000 informes o el servicio pidió al servidor que fuera más despacio, y el servidor espera lo que el servicio pida antes de enviar de nuevo; failed significa que no se pudo llegar al servicio o este rechazó el informe. Un informe se envía una vez y nunca se reintenta, y los informes que aún esperan 2 segundos después de iniciarse un apagado se pierden) |
my.queue.ready |
Indicador | my.job.type (el número de jobs ejecutables en la cola de la base de datos) |
my.queue.oldest_ready_age |
Indicador, segundos | my.job.type (cuánto ha esperado el job ejecutable más antiguo de cada tipo en la cola de la base de datos; un tipo sin jobs ejecutables no tiene valor) |
my.queue.dead |
Indicador | Ninguna |
my.instance.users, my.instance.statuses |
Indicador | Ninguna (los recuentos de usuarios locales y publicaciones, como en NodeInfo) |
my.media.stored_bytes |
Indicador, bytes | my.media.origin (local / remote_cache) |
my.db.size |
Indicador, bytes | Ninguna (el tamaño de la base de datos: pg_database_size para PostgreSQL; el archivo de la base de datos sin su write-ahead log para SQLite) |
my.billing.import.failing |
Indicador | my.billing.source (1 cuando la importación más reciente de la fuente falló, 0 en otro caso) |
my.federation.instances |
Indicador | my.federation.instance.state (available: servidores a los que aún van las entregas pero que fallaron al menos un día desde que respondieron por última vez; unavailable: servidores cuyas entregas están en pausa) |
my.metrics.snapshot.age |
Indicador, segundos | my.metrics.snapshot.part (queue / totals) |
my.errors.reported |
Contador | my.error.source (server / web), my.error.kind (panic / error). Uno por informe de error |
my.tls.certificate.expiry |
Indicador, segundos | host (el tiempo hasta que caduca el certificado que este proceso sirve para uno de sus hosts, con tls = acme o tls = files; cada proceso informa del suyo, así que se nota un proceso que se quedó con un certificado antiguo. Consulta Comandos y métricas) |
my.tls.order.attempts |
Contador | host, result (issued / failed). Uno por pedido de un certificado a la autoridad de certificación ACME, por el proceso que lo hizo, incluidos my tls renew y my tls revoke |
my.tls.order.consecutive_failures |
Indicador | host (los pedidos desde el certificado actual del host que no obtuvieron ninguno: el recuento que fija la espera antes del siguiente pedido) |
my.tls.rounds |
Contador | Ninguna. Uno por ronda del gestor de certificados sobre sus hosts con tls = acme; un recuento que deja de crecer significa que el gestor se detuvo |
Las comprobaciones de salud (/healthz, /readyz, /health/live, /health/ready) no se miden. Ninguna etiqueta contiene un dominio remoto, una cuenta, una URL ni una IP de cliente.
my.queue.*, my.instance.*, my.media.stored_bytes, my.db.size, my.federation.instances y my.billing.import.failing son valores de toda la instancia: todos los procesos informan del mismo valor a partir de una instantánea conservada en el almacén clave-valor.
Métricas del sistema
Sección titulada «Métricas del sistema»Las métricas sobre el proceso, el runtime de Go y las conexiones a recursos se exportan mediante el mismo metrics_exporter.
La CPU del contenedor, la memoria, el número de instancias y las solicitudes de entrada se dejan a las métricas de la plataforma; estas cubren la saturación dentro del proceso que la plataforma no puede ver.
No las uses para activar el escalado; úsalas para alertas y para estimar el tope de instancias.
| Métrica | Tipo | Etiquetas |
|---|---|---|
go.memory.used, go.memory.limit, go.memory.gc.goal |
Indicador, bytes | Solo go.memory.used tiene go.memory.type (stack / other). go.memory.limit aparece solo cuando GOMEMLIMIT está definido |
go.memory.allocated, go.memory.allocations |
Contador | Ninguna |
go.goroutine.count, go.processor.limit, go.config.gogc |
Indicador | Ninguna |
go.schedule.duration, go.memory.gc.pause.duration |
Histograma, segundos | Ninguna (la espera desde que pasa a ser ejecutable hasta que se ejecuta, y las pausas del GC) |
go.memory.gc.cycles |
Contador | Ninguna |
process.cpu.time |
Observable Counter, segundos (total desde el inicio) | cpu.mode (user / system) |
process.memory.usage |
Indicador, bytes | Ninguna (memoria residente, RSS) |
process.unix.file_descriptor.count, my.process.file_descriptor.limit |
Indicador | Ninguna (descriptores de archivo abiertos y el límite) |
process.uptime |
Indicador, segundos | Ninguna |
db.client.connection.count |
Indicador | db.client.connection.pool.name (postgres / sqlite), db.client.connection.state (idle / used) |
db.client.connection.max |
Indicador | db.client.connection.pool.name |
db.client.connection.wait_time, my.db.client.connection.waits, db.client.connection.timeouts |
Observable Counter (total desde el inicio; segundos o recuento) | db.client.connection.pool.name. timeouts es solo de PostgreSQL |
my.adapter.operation.duration |
Histograma, segundos | my.adapter (queue.db / kv.db / kv.memory / kv.valkey / stream.<stream> / blob.fs), my.operation, my.outcome (success / error) |
my.adapter.connections |
UpDownCounter | my.adapter (conexiones de valkey y suscriptores de stream.<stream>) |
my.adapter.reconnects |
Contador | my.adapter |
http.client.request.duration |
Histograma, segundos | my.http.purpose (json / html / image / video / human_check / web_push / webhook / client_metadata / login_provider / robots / domain_list), http.request.method, my.http.status_class (2xx y así sucesivamente), error.type (forbidden_destination es un rechazo de la protección SSRF) |
http.client.open_connections |
UpDownCounter | Ninguna |
my.readiness.failures |
Contador | Ninguna |
my.readiness.shared |
Contador | Ninguna. Uno por solicitud de readiness que tomó el resultado de una comprobación ya en curso en lugar de iniciar una |
my.http.origin_refused |
Contador | Ninguna. Uno por solicitud rechazada porque no llegó a través de la CDN (origin_secret). Las sondas a la dirección del origen lo suben despacio; un salto mientras el tráfico se detiene significa que la CDN ya no envía la cabecera. El modo de mantenimiento no mide nada, así que solo su registro de acceso las muestra |
- Las métricas del runtime de Go (
go.*) las exportan soloprometheusyotlp. Conemf, un job periódico de snapshot escribe los indicadores del proceso y del pool de conexiones y los contadores observables. - Las esperas del pool y el tiempo de CPU son Observable Counters: el pool y el kernel conservan totales desde el inicio, y se leen en el momento de la recogida. En Prometheus son contadores
_total(comoprocess_cpu_time_seconds_total), en OTLP son sumas monótonas, y su crecimiento se ve conrate()de PromQL.emfno tiene contadores totales, así que escribe el aumento desde la escritura anterior (súmalos con la estadística Sum de CloudWatch). - El
claimde la cola se mide solo cuando toma un job o falla. El sondeo de un worker en espera no registra nada. db.client.connection.pending_requestsno se exporta: las estadísticas de pgx y dedatabase/sqlno informan de cuántas esperan, así que el número y la duración de las esperas lo sustituyen.- Pon alertas sobre la proporción de la suma de
go.memory.usedrespecto ago.memory.limit, y sobre el crecimiento dedb.client.connection.wait_time(se está alcanzando el límite del pool).
Límite de memoria (GOMEMLIMIT)
Sección titulada «Límite de memoria (GOMEMLIMIT)»GOMEMLIMIT es una variable de entorno del runtime de Go que establece el operador; la aplicación no la elige.
Sin ella, Go se ejecuta con su valor por defecto (sin límite), y el heap no se recolecta con antelación al acercarse al límite de memoria del contenedor.
En configuraciones con un límite de memoria del contenedor (Cloud Run, ECS, Kubernetes), establécela en torno al 90 % de ese límite (por ejemplo GOMEMLIMIT=460MiB para un contenedor de 512 MiB).
No establezcas GOMAXPROCS: el valor por defecto de Go sigue el límite de CPU del contenedor.
El ajuste traces_exporter (por defecto none) exporta trazas distribuidas. Su configuración relacionada está en la referencia de configuración.
| Span | Nombre | Atributos |
|---|---|---|
| Solicitud HTTP (servidor) | <method> <http.route> (<method> para una solicitud que no llegó a una ruta) |
http.request.method, http.route, http.response.status_code, my.surface. Un 5xx es un fallo |
| Ejecución de un trabajo (consumer) | El tipo de trabajo (my.job.type) |
my.job.type, my.job.attempt, my.outcome. Cada reintento es un span aparte |
| Transacción | my.db.transaction |
db.system.name. Cada reintento es un span aparte |
| Consulta (cliente) | El nombre de la consulta de sqlc (como InsertJobs; si no, la primera palabra del SQL, como BEGIN) |
db.system.name, db.operation.name |
Entrega (my.delivery) |
my.delivery |
activity.type, my.outcome |
| HTTP saliente (cliente) | <method> |
http.request.method, server.address (solo el nombre del host de destino), http.response.status_code. Un 4xx o 5xx es un fallo |
Un span fallido tiene error.type (un nombre finito como timeout, o un código de estado). Los atributos nunca contienen ID de cuentas, publicaciones o trabajos, URL, rutas o consultas, IP de cliente, valores de User-Agent, texto SQL ni cadenas de error.
server.address deja los nombres de host de los servidores remotos en manos del receptor, así que tú decides cuánto tiempo los conserva el receptor y quién puede verlos. Las comprobaciones de salud y las solicitudes rechazadas por origin_secret no crean ningún span.
- La ejecución de un trabajo no es hija del span que lo puso en cola (normalmente una solicitud HTTP). Es la raíz de una traza nueva con un enlace al span que lo puso en cola. En un visor, sigue el enlace desde la traza de la solicitud.
- Un
traceparententrante pasa a ser el padre solo cuando el par que se conecta está entrusted_proxiesy, conorigin_secret, la solicitud lleva el secreto. En caso contrario se descarta y empieza una traza nueva.tracestatese descarta siempre. El HTTP saliente (federación, WebFinger, archivos multimedia, Web Push, etc.) no llevatraceparent. - Muestreo: una solicitud se registra si se registró su padre de proxy de confianza, o si se registró el destino del enlace de un trabajo; en caso contrario se registra con la proporción
traces_sample_ratio(por defecto 0,01). Reducir la proporción nunca deja sin su traza a los trabajos que continúan una solicitud registrada.
| Destino | Ajustes | Ruta |
|---|---|---|
| Por defecto, autoalojado pequeño | traces_exporter = none |
No se exporta ningún span. Sigue request_id y job_id en los registros. Si un proxy de confianza aporta un traceparent, su trace_id y span_id se añaden a los registros |
| Autoalojado (Jaeger, Tempo, un OpenTelemetry Collector, etc.) | traces_exporter = otlp, traces_flush = batch |
Se envía por OTLP/HTTP al receptor en OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (o OTEL_EXPORTER_OTLP_ENDPOINT, por defecto http://localhost:4318). Las cabeceras de autenticación van en OTEL_EXPORTER_OTLP_HEADERS. Para conservar de forma fiable los errores y las trazas lentas, usa el muestreo en cola (tail sampling) del Collector |
| Google Cloud (Cloud Run) | none, u otlp con unit para activar las trazas |
Consulta más abajo |
| AWS (ECS) | none, u otlp con batch para activar las trazas |
Consulta más abajo |
Cloud Run
Sección titulada «Cloud Run»Incluso con none, la traza de solicitud que Cloud Run crea automáticamente y el trace_id de los registros comparten el mismo ID (cuando confías con trusted_proxies en la conexión que viene delante de Cloud Run).
Aún no se ha verificado si Cloud Run sobrescribe siempre el traceparent de las solicitudes públicas.
Los registros no tienen la forma del campo de traza que reconoce Cloud Logging (logging.googleapis.com/trace).
Para enviar spans de la aplicación a Cloud Trace, ejecuta un OpenTelemetry Collector como sidecar en el mismo servicio. El servidor no guarda credenciales de Google; el sidecar envía al endpoint OTLP de Cloud Trace con las Application Default Credentials.
- Servidor (el contenedor de ingreso):
MY_TRACES_EXPORTER=otlp,MY_TRACES_FLUSH=unit,OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 - Sidecar: un OpenTelemetry Collector que recibe con un receptor
otlppor HTTP enlocalhost:4318y envía con el exportadorgooglecloud, o el exportadorotlphttp(https://telemetry.googleapis.com, con la extensióngoogleclientauth). Concede a la cuenta de servicio permiso para escribir en Cloud Trace. - Al final de cada solicitud o trabajo registrado,
unitvacía los spans acumulados hacia el sidecar antes de volver. Para que el sidecar pueda enviarlos mientras no hay CPU asignada, usa la facturación basada en instancia en una configuración con trazas activadas. - El costo son los recursos del sidecar y el volumen de spans (precios de Cloud Trace). Elige la proporción con
traces_sample_ratio.
AWS ECS
Sección titulada «AWS ECS»Para enviar a X-Ray, ejecuta el AWS Distro for OpenTelemetry (ADOT) Collector como contenedor sidecar en cada tarea. El servidor no tiene firma SigV4; el Collector firma con el rol de la tarea y envía a X-Ray. El módulo mycroblog-aws del despliegue con OpenTofu hace todo esto por defecto (observability.traces = "x-ray"); el resto de esta sección es para una definición de tarea propia.
- Servidor:
MY_TRACES_EXPORTER=otlp,OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:4318/v1/tracesy el valor predeterminadoMY_TRACES_FLUSH=batch, ya que el proceso permanece en marcha. - Collector: una imagen fijada por versión, como
public.ecr.aws/aws-observability/aws-otel-collector:v0.50.0, con su configuración en la variableAOT_CONFIG_CONTENT: un receptorotlpsobre HTTP en127.0.0.1:4318y el exportadorawsxray. El endpoint OTLP de X-Ray (https://xray.<region>.amazonaws.com/v1/traces, mediante un exportadorotlphttpcon la extensiónsigv4auth) también funciona, pero necesita CloudWatch Transaction Search activado para la cuenta. - Concede al rol de la tarea
xray:PutTraceSegments, con el que escribe el exportadorawsxray. El servidor muestrea las trazas por sí mismo, así que el Collector no necesita reglas de muestreo de X-Ray. - Da al Collector una parte de la tarea:
mycroblog-awsle da 32 unidades de CPU y 128 MiB, y al servidor el resto, conGOMEMLIMITal 90 % de ese resto. Haz que el contenedor del servidor dependa del arranque del Collector, para que el Collector se detenga después del servidor y reciba sus últimos spans. - El coste es la parte de los recursos de la tarea que usa el sidecar y el número de trazas que registra X-Ray (las primeras 100 000 al mes son gratis). El
traces_sample_ratiopredeterminado de 0,01 registra unas 30 000 trazas al mes para 100 000 solicitudes al día.
Perfiles
Sección titulada «Perfiles»Las métricas del sistema dicen cuánta memoria y CPU usa un proceso; un perfil del runtime de Go dice qué las usa.
pprof_listen nombra la dirección de un listener que sirve los perfiles en /debug/pprof/, para todo role. Está vacío por defecto, lo que no abre ningún listener.
MY_PPROF_LISTEN=127.0.0.1:6060 my serve
go tool pprof -sample_index=inuse_space http://127.0.0.1:6060/debug/pprof/heap # what holds the heap nowgo tool pprof -sample_index=alloc_space http://127.0.0.1:6060/debug/pprof/heap # what has allocated since the startgo tool pprof 'http://127.0.0.1:6060/debug/pprof/profile?seconds=30' # where the CPU goes, for 30 secondscurl 'http://127.0.0.1:6060/debug/pprof/goroutine?debug=1' # every goroutine, by where it waitscurl 'http://127.0.0.1:6060/debug/pprof/heap?debug=1' | grep '^# ' # the runtime's memory statisticsEl listener no tiene autenticación, un perfil muestra las interioridades del proceso y tomar uno cuesta CPU: mantenlo en loopback y accede a él mediante un túnel (ssh -L 6060:127.0.0.1:6060 <host>, kubectl port-forward), y quítalo cuando termines.
El perfil del heap cubre solo el heap de Go. La memoria residente del proceso también contiene las páginas del binario que se leyeron, las pilas y las propias estructuras del runtime; las estadísticas de memoria las dan.
Los perfiles de mutex y de bloqueo están vacíos: el servidor no los muestrea.
Detener el servidor
Sección titulada «Detener el servidor»Con SIGTERM o SIGINT el servidor se apaga de forma ordenada.
- Deja de aceptar conexiones nuevas y de tomar trabajos.
- Espera hasta 25 segundos a que terminen las solicitudes en curso y los trabajos en ejecución.
- Pasados 25 segundos cancela el contexto de las solicitudes y trabajos restantes y cierra las conexiones. Después da a un trabajo cancelado hasta 3 segundos más para registrar su resultado y termina con el código 1 (28 segundos como máximo en total, dentro del periodo de gracia de 30 segundos por defecto de Kubernetes y ECS). Un trabajo cancelado se reintenta. Un trabajo que no se detiene en esos 3 segundos, o que se mata a medias, se abandona y un worker lo vuelve a tomar cuando caduca su concesión, así que puede ejecutarse dos veces.
Un pánico en una de las tareas en segundo plano del servidor inicia el mismo apagado, para que el servidor nunca siga funcionando en un estado roto.
La línea de registro serve failed nombra la tarea, y el proceso termina con el código 1 para que la plataforma o el gestor de procesos lo reinicie.
Para trabajar en la base de datos, el almacén clave-valor o la cola, reinicia en modo de mantenimiento (MY_MAINTENANCE=true) en lugar de detenerlo. Consulta Mantenimiento.
La cola de jobs y los jobs fallidos (muertos)
Sección titulada «La cola de jobs y los jobs fallidos (muertos)»Jobs enumera cada tipo de job: qué hace, qué lo inicia, cómo se reintenta y qué hace ejecutarlo de nuevo.
La página de jobs de administración (Administración → Jobs, /admin/jobs, permiso manage_jobs) tiene tres páginas:
- Estado de la cola (
/admin/jobs): primero cuántos jobs fallaron, con un enlace a ellos; el recuento por estado (en cola, en ejecución, esperando reintento, fallidos), cada uno con enlace a los jobs de ese estado; cuánto ha esperado el job vencido más antiguo; y una tabla de los recuentos por tipo y estado con cuánto tiempo mantiene cada tipo a un job en espera. - Lista de jobs (
/admin/jobs/list): los jobs que no han terminado (en cola, en ejecución, esperando reintento), o de un estado, y de un tipo, una página cada vez, con el tipo, el número de intentos, la hora en que vence o falló, el estado y la primera línea del último error. - Un job (
/admin/jobs/<id>, desde el tipo en la lista): Ejecutar de nuevo para un job fallido, que pregunta antes, ya que una ejecución puede repetir lo que el job hizo antes de fallar; cada dato del job, su ID y claves cada una con un botón de copiar; su último error y su payload, cada uno con un botón de copiar; una tabla de los intentos fallidos, el más reciente primero (resultado, hora de fin, worker y el error); y un enlace a los jobs de su tipo.
La API de administración es GET /api/v1/admin/queue, GET /api/v1/admin/jobs?state=&type=, GET /api/v1/admin/jobs/{id}, GET /api/v1/admin/jobs/{id}/attempts y POST /api/v1/admin/jobs/{id}/retry.
Un job completado ya no está en la cola, así que su página no se encuentra.
- Los jobs en espera, en ejecución y esperando reintento solo pueden enumerarse para las colas cuyos jobs conserva el servidor:
queue = db,queue = cloudtasks(los jobs están también en la base de datos) yqueue = inline. Los jobs fallidos y el historial de intentos están en la base de datos de la aplicación para toda cola, así que siempre pueden enumerarse. - El historial de intentos conserva solo los intentos fallidos (reintentos y el intento que finalmente falló). Sigue una ejecución con éxito mediante la línea de registro estructurada
job(que llevajob_id). El historial lo elimina la limpieza horaria una vez que ha pasadojob_attempt_retention(30 días por defecto; consulta el ajuste) desde que terminó el intento. El historial no contiene payload ni registro del handler, y un mensaje de error se corta en sus primeros 2000 bytes. Los handlers de jobs mantienen las direcciones de correo, las direcciones IP, los tokens y los cuerpos de publicaciones fuera de los mensajes de error. Para una vista limitada a los tipos de job de correo, consulta Enviar correo.
Un job cuyo handler decidió que falló definitivamente, y un job que agotó sus reintentos, pasa a ser un job muerto en la cola de la base de datos (queue = db y queue = cloudtasks).
my job los enumera, reintenta y elimina. El estado «Fallidos» de la página de jobs y la API de administración también pueden enumerarlos y reintentarlos.
my job list # newest failures first: ID, type, run count, time of failure, last error (-limit sets the count, default 50)my job retry <id> [<id>...] # reset the attempt count and put the job back in the queue to run immediatelymy job delete <id> [<id>...] # remove without runningmy job types # print every job type of this release- Si ya espera un job con la misma clave de idempotencia, ese job sustituye al reintentado. Los handlers de jobs son idempotentes, así que devolver el mismo job a la cola cualquier número de veces es seguro.
- Un ID desconocido se imprime y el comando termina con el código 1; los demás ID se procesan igualmente. El código de salida 2 significa un error de uso.
- Un job muerto que nadie reintenta lo elimina la limpieza horaria una vez que ha pasado
dead_job_retention(30 días por defecto; consulta el ajuste) desde el fallo. - Los jobs muertos de
queue = inlineviven en la memoria del proceso del servidor, así quemy jobno puede gestionarlos (código de salida 1).
Dividir los workers por tipo de trabajo
Sección titulada «Dividir los workers por tipo de trabajo»Por defecto cada worker ejecuta todos los tipos de trabajo, en el orden en que vencieron, un trabajo a la vez por proceso (consulta Ejecutar varios trabajos a la vez). Entonces una ráfaga de entregas retrasa el correo electrónico y las notificaciones, y cualquier worker que añadas reparte su tiempo entre todos. Con queue = db puedes dar a algunos tipos sus propios workers:
worker_job_types: este proceso ejecuta solo estos tipos.worker_job_types_except: este proceso ejecuta todos los tipos menos estos.
Cada uno es una lista separada por comas de tipos de trabajo (my job types los imprime; my config check rechaza un nombre que no coincide con ninguno), escritos como un nombre (federation.deliver) o un prefijo (federation.*). Establécelos por proceso, por ejemplo con MY_WORKER_JOB_TYPES. No puedes establecer ambos en un mismo proceso. Un nombre o prefijo que no coincide con ningún tipo de trabajo detiene el arranque, lo que también detecta un tipo que una versión renombró, o un tipo que solo existe con un ajuste que no has establecido. No funcionan con role = web, ni con queue = cloudtasks o inline, donde el arranque también falla: allí una señal nombra el trabajo que ejecutar, así que un proceso no puede elegir sus trabajos.
Al arrancar, un proceso con uno de estos valores registra los tipos que omite. No puede ver los valores de los demás procesos, así que asegúrate de que algún proceso ejecute todos los tipos, o esos trabajos esperarán para siempre. La limpieza periódica y el correo electrónico también son tipos de trabajo. Todos los procesos siguen iniciando los trabajos periódicos; qué proceso los ejecuta depende de esta configuración.
Decide qué dividir a partir de las métricas, no de los nombres de los tipos. my.job.wait (Prometheus: my_job_wait_seconds) muestra cuánto esperaron los trabajos por tipo antes de empezar:
histogram_quantile(0.95, sum by (my_job_type, le) (rate(my_job_wait_seconds_bucket[15m])))sum by (my_job_type) (rate(my_job_duration_seconds_sum[1h])) muestra el tiempo de worker que usa cada tipo, que es también aproximadamente cuántos procesos necesita. Un tipo que usa la mayor parte del tiempo y hace esperar a los demás es el que hay que mover.
Tres disposiciones habituales, con el número de procesos que elijas:
| Disposición | Procesos |
|---|---|
| Evitar que las entregas retrasen el resto | worker_job_types = federation.fanout,federation.deliver para las entregas, y worker_job_types_except = federation.fanout,federation.deliver para todo lo demás. Añade procesos al primer grupo durante una ráfaga. |
| Evitar que un backend de búsqueda retrase el resto | worker_job_types = search.* para los trabajos de búsqueda, y worker_job_types_except = search.* para todo lo demás (Evitar que la búsqueda retrase otros trabajos). |
| Mantener rápidos el correo electrónico y las notificaciones | worker_job_types = identity.verification_email,identity.password_reset_email,identity.password_notice_email,identity.closure_email,identity.deactivation_email,notification.email,notification.moderator_email,notification.supporter_email,notification.push,notification.post_subscribers,instance.notify_announcement,voice.notify_started para estos, y un worker sin ese ajuste para todo, que además ayuda con estos tipos cuando está libre. Deja fuera los tipos que no has establecido, o el arranque se detiene: notification.push necesita vapid_private_key, y notification.email, notification.moderator_email y notification.supporter_email necesitan mail. Consulta Trabajos que dependen de configuración. |
Un prefijo como identity.* es el módulo de código que posee los tipos, no una clase de trabajo. identity.* incluye también las exportaciones e importaciones de datos y los trabajos de caducidad, y no incluye instance.notify_announcement ni voice.notify_started, así que una disposición para una clase de trabajo nombra cada tipo.
Mantén estos juntos, en workers con el mismo ajuste. Los trabajos de una misma clave de orden se ejecutan en orden sea cual sea su tipo, así que si nada ejecuta el trabajo anterior, el posterior también espera, y si el grupo del trabajo anterior está saturado, el trabajo posterior lo espera:
| Tipos | Qué mantienen en orden |
|---|---|
federation.fanout, federation.deliver |
Las entregas de un favorito y de su deshacer |
voice.apply_media_event, voice.apply |
Los eventos de una sala de voz |
supporters.sync, supporters.command |
Los cambios de una suscripción |
Cuando actualices:
- Un proceso con
worker_job_typesno ejecuta los tipos que añade una versión nueva. Consulta las notas de la versión y los tipos omitidos en el registro. Un proceso conworker_job_types_exceptsí los ejecuta, lo que lo convierte en el lugar más seguro para todo lo demás. - Un tipo renombrado detiene el arranque, así que lee primero las notas de la versión.
Para desplegar una división, arranca primero los workers nuevos y después añade el ajuste a los antiguos. Para deshacerla, quita el ajuste de un grupo antes de detener el otro. Los trabajos permanecen en la cola, así que no se pierde nada, y un tipo que nadie ejecuta durante un tiempo solo espera.
Detectar un tipo que nada ejecuta. Los trabajos de ese tipo esperan, así que my.queue.oldest_ready_age crece para ese tipo, y las alertas MyQueueBacklog y MyQueueStalled saltan para el tipo que espera más. Para ver cuál es, o para crear alertas por tipo:
max by (my_job_type) (my_queue_oldest_ready_age_seconds) > 1800La página de trabajos de administración muestra la misma espera por tipo. Un worker con uno de estos valores también deja en paz un trabajo cuyo tipo no tiene ningún manejador (se cuenta como other en la métrica), así que, sin ningún worker sin ajuste, ese trabajo espera en lugar de convertirse en un trabajo dead.
Ejecutar varios jobs a la vez
Sección titulada «Ejecutar varios jobs a la vez»worker_job_concurrency define cuántos jobs ejecuta un proceso a la vez, de 1 a 128. Funciona con queue = db; con Cloud Tasks lo decide la plataforma. El valor predeterminado es un job a la vez, y un ajuste de 1 se comporta igual.
Súbelo para jobs que pasan su tiempo esperando a otros servidores, como federation.deliver. Esos usan poca memoria y pocas conexiones de base de datos por job, así que un proceso hace el trabajo de muchos: en una prueba local donde un job solo esperaba 200 ms una respuesta, un proceso con 32 ranuras igualó a 32 procesos con una ranura cada uno, usando una pequeña parte de la memoria. Esos jobs no hacían nada más, así que mide tu propia instancia. Combínalo con worker_job_types, y da a cada tipo de job un proceso con su propio número.
Ten en cuenta estos límites:
- Conexiones de base de datos: un job necesita una conexión para ser reclamado, para su propio trabajo y para registrar su resultado. El ajuste debe estar por debajo del máximo del pool, o el servidor no arranca. El máximo es
pool_max_connsendatabase_url, por defecto el mayor entre 4 y el número de CPU, así que una vCPU permite 3 hasta que lo subas. Comprueba que tu base de datos o pooler de conexiones acepta las conexiones de todos tus procesos. - SQLite: escribe una transacción a la vez, y en una prueba local fue más lento con 128 que con 32.
- Jobs que consumen mucha CPU: las ranuras comparten la CPU y la memoria de un proceso.
media.processespera su turno con un límite de la mitad de las CPU por defecto, y la espera cuenta contra el arrendamiento de 5 minutos del job, así que un proceso lleno demedia.processpuede pasarse del arrendamiento y empezar de nuevo. Da a esos jobs un proceso con pocas ranuras. - Un servidor a la vez: un proceso hace como máximo 8 conexiones a un mismo host, así que un proceso entrega a un solo servidor no más rápido de lo que permiten 8 conexiones, tenga las ranuras que tenga. Donde la mayoría de las entregas van a unos pocos servidores grandes, más procesos ayudan donde más ranuras no.
- Un servidor atascado retiene ranuras: las ranuras que esperan a un servidor lento no están libres para otros jobs, así que mantén las entregas separadas del correo y las notificaciones.
- Los despliegues consumen intentos: cuando el servidor se detiene, los jobs que siguen en ejecución pasado
ShutdownTimeout(25 segundos por defecto) se cancelan, y cada job cancelado consume un intento. Cuantas más ranuras ejecutan jobs lentos, más intentos consume cada despliegue. Un job cancelado cuyo resultado no se registra a tiempo espera a que caduque su arrendamiento antes de ejecutarse de nuevo. - Una caída se lleva todas las ranuras: si el proceso se queda sin memoria, todos sus jobs esperan a que caduquen sus arrendamientos.
Para decidir si subirlo, lee my.job.wait por my.job.type: si los jobs de un tipo esperan mucho mientras my.job.duration es sobre todo tiempo esperando a otros servidores y la CPU y la memoria se mantienen bajas, más ranuras deberían ayudar. Si las esperas siguen altas tras subirlo, mira las conexiones de base de datos y el límite por host de arriba antes de subirlo de nuevo.
Mientras no vence ningún job, una ranura sondea y las demás esperan, así que un proceso inactivo cuesta a la base de datos lo que cuesta un proceso de un solo job.
Esperar una conexión de base de datos
Sección titulada «Esperar una conexión de base de datos»Con database = postgres, cada sentencia y transacción espera primero una conexión libre del pool del proceso.
database_acquire_timeout (por defecto 60s) limita esa espera, y nada más: una consulta o
transacción larga que ya tiene su conexión sigue ejecutándose, tarde lo que tarde. 0 espera sin límite. SQLite no tiene límite de conexiones por las que esperar, así que establecerlo ahí falla al arrancar.
Cuando la espera se agota:
- Una solicitud recibe como respuesta
503 Service UnavailableconRetry-After: 5. - Un trabajo se ejecuta de nuevo 30 segundos después y no consume ningún intento, así que una base de datos ocupada nunca convierte un trabajo en un trabajo dead.
- La métrica
db.client.connection.timeoutslo cuenta, y salta la alertaMyDBPoolWaiting.
El valor por defecto es el tiempo de espera de escritura de 60 segundos del servidor: una solicitud que esperara más no podría enviar su respuesta de todos modos, así que el valor por defecto no hace fallar ninguna solicitud que aún pudiera haber tenido éxito. Elige un valor según cómo funcione tu instancia:
- Redúcelo para descartar carga rápidamente: los clientes reintentan tras
Retry-Afteren lugar de mantener sus solicitudes abiertas. Mantenlo por encima de tus transacciones normales más lentas, o una ráfaga breve empezará a recibir503. - Dimensiona primero el pool. Un proceso necesita aproximadamente tantas conexiones como trabajo ejecuta a la vez.
pool_max_connsendatabase_urles por defecto el mayor entre 4 y el número de CPU, y todos los procesos juntos deben quedar por debajo del límite de conexiones de la base de datos.- Con
worker_job_concurrency, las ranuras también esperan conexiones, y el ajuste debe quedar por debajo del máximo del pool. - En Cloud Run, un servicio admite 80 solicitudes simultáneas por instancia por defecto. Con un pool de 4, una ráfaga de solicitudes lentas hace cola aquí, así que sube
pool_max_conns, reduce la concurrencia del servicio, o ambas cosas.
- Con
503frecuentes odb.client.connection.timeoutssignifican que el pool es demasiado pequeño o que las consultas se han vuelto más lentas; un tiempo de espera más largo solo lo oculta. SigueMyDBPoolSaturated.
Cloud Tasks
Sección titulada «Cloud Tasks»Despliegue en Cloud Run configura todo lo que sigue con módulos de OpenTofu.
Con queue = cloudtasks los trabajos permanecen en la base de datos (database = postgres), y Google Cloud Tasks solo despierta al servidor para cada uno de ellos:
- Por cada trabajo que guarda, reintenta o devuelve a la cola, el servidor crea una tarea en
queue_cloudtasks_queuecuando se confirma la transacción. La tarea llama aPOST {queue_cloudtasks_url}/_internal/jobsa la hora en que vence el trabajo, con el ID del trabajo como cuerpo y un token de ID OIDC dequeue_cloudtasks_service_account. Un trabajo que vence con más de 30 días de antelación se señala a los 30 días, y de nuevo cuando llega esa tarea. - El proceso que recibe la tarea ejecuta el trabajo y responde
204una vez registrado su resultado, también cuando el trabajo ya se ejecutó o no ha vencido. Un trabajo que falla lo reintenta el servidor en su siguiente hora de intento, no Cloud Tasks. Cloud Tasks reintenta una tarea solo cuando la respuesta es5xx(no se pudo acceder a la base de datos) o401(un token que el servidor rechazó), así que suretryConfigno necesita configuración. - Ningún proceso sondea la tabla y ningún proceso ejecuta por sí mismo los trabajos periódicos. Crea un trabajo de Cloud Scheduler que llame a
POST {queue_cloudtasks_url}/_internal/tickcada minuto (* * * * *) con un token OIDC de la misma cuenta de servicio (y la audiencia dequeue_cloudtasks_audience, cuando esté establecida). Cada tick pone en cola los trabajos periódicos cuyo periodo ha llegado, una vez para toda la instancia (los periodos se reclaman en el KV, así quekvdebe serdbovalkey), y vuelve a señalar los trabajos que llevan vencidos más de 2 minutos sin ejecutarse, lo que recupera una señal perdida. /_internal/jobsy/_internal/ticklos sirven los procesos conrole = alloworker, y aceptan solo un token firmado por Google paraqueue_cloudtasks_service_accountcon un correo electrónico verificado, cuya única audiencia seaqueue_cloudtasks_audienceo, por defecto, la URL llamada. Cualquier otra solicitud recibe un401.- Una entrega ejecuta un trabajo, durante como máximo la concesión de 5 minutos. Mantén
queue_cloudtasks_dispatch_deadline(por defecto 10 minutos) y el tiempo de espera de solicitud del servicio de Cloud Run por encima de eso. - La propia cuenta de servicio del servidor necesita
roles/cloudtasks.enqueueren la cola yroles/iam.serviceAccountUserenqueue_cloudtasks_service_account. Se autentica con las Application Default Credentials.
Con cuánto retraso se ejecutan los trabajos periódicos
Sección titulada «Con cuánto retraso se ejecutan los trabajos periódicos»Un trabajo periódico se ejecuta hasta un periodo de su disparador después de su hora, más el tiempo que tarda la plataforma en iniciarlo. Esto es lo
que decide con cuánto retraso llegan los recordatorios y las notificaciones de inicio de los eventos y se abren sus salas de chat de voz, ya que gathering.tick las inicia: un recordatorio
se retrasa hasta el intervalo de la tabla. Los valores son los que dan el código del planificador y el disparador de cada plataforma; no se
midieron en un servidor en funcionamiento.
| Plataforma | Qué inicia los trabajos periódicos | Retraso esperado de un recordatorio o inicio de evento |
|---|---|---|
Autoalojamiento y Docker Compose (queue = db) |
El planificador de cada proceso con role = all o worker comprueba una vez por minuto, desde que arrancó el proceso, y encola cada trabajo una vez por periodo para todo el servidor |
Hasta 1 minuto, más alrededor de un segundo para que un worker recoja el trabajo |
AWS ECS Fargate (queue = db) |
El mismo planificador, en las tareas worker | Hasta 1 minuto, más alrededor de un segundo |
Cloud Run (queue = cloudtasks) |
Cloud Scheduler llama a /_internal/tick según su programación, * * * * * (cada minuto) de forma predeterminada; Cloud Tasks despierta entonces al servidor para cada trabajo |
Hasta 1 minuto, más el arranque de una instancia cuando no hay ninguna en ejecución (un arranque en frío, normalmente unos segundos). Con un tick_schedule más largo, como */10 * * * *, hasta ese intervalo |
| AWS Lambda | my no tiene despliegue en Lambda; en AWS, ejecútalo en ECS Fargate |
— |
Un recordatorio que llegaría después de que su evento empezara no se envía, ni tampoco una notificación de inicio después de que el evento terminara. Así, con un tick de más de 5 minutos, los recordatorios más cortos pueden perderse.
Dirigir tipos de trabajo a sus propias colas
Sección titulada «Dirigir tipos de trabajo a sus propias colas»Con queue = cloudtasks, un worker no puede elegir los trabajos que ejecuta: worker_job_types funciona solo con queue = db, porque la plataforma decide quién recibe una señal.
Para dar capacidad propia a algunos tipos de trabajo, envía sus señales a su propia cola y establece la capacidad de esa cola en la plataforma.
Nada cambia a menos que establezcas una ruta.
queue_cloudtasks_routes: federation.*=projects/p/locations/l/queues/my-federation@https://federation-worker.example.com,notification.email=projects/p/locations/l/queues/my-mail.
Una ruta sin @ ni URL llama a queue_cloudtasks_url.
La parte izquierda es un tipo de trabajo de la referencia de trabajos o un prefijo. Un nombre gana a un prefijo, y un prefijo más largo gana a uno más corto.
Los tipos que no coinciden con ninguna ruta, incluidos los que añada una versión posterior, usan la cola por defecto (queue_cloudtasks_queue), así que siguen ejecutándose.
my config check comprueba la forma de las rutas; una parte izquierda que no coincide con ningún tipo de trabajo detiene my serve al arrancar.
Da las mismas rutas a todos los procesos, incluido role = web. Una señal la envía el proceso que guarda el trabajo: un proceso web en la mayor parte de lo que hacen los usuarios, como el
primer trabajo de una publicación, y un worker en los trabajos que guarda un trabajo, los reintentos, el siguiente trabajo de una clave de orden y el barrido de señales perdidas.
Donde cada rol tiene su propia configuración, como los servicios de Cloud Run, pasa el mismo valor a todos ellos:
routes='federation.*=projects/p/locations/l/queues/my-federation@https://federation-worker.example.com'gcloud run services update my-web --update-env-vars "^|^MY_QUEUE_CLOUDTASKS_ROUTES=$routes"gcloud run services update my-worker --update-env-vars "^|^MY_QUEUE_CLOUDTASKS_ROUTES=$routes"gcloud run services update my-federation-worker --update-env-vars "^|^MY_QUEUE_CLOUDTASKS_ROUTES=$routes"Un proceso con otras rutas no provoca ningún error ni pierde ningún trabajo: sus señales van a otra cola, y los trabajos se ejecutan allí, fuera de la capacidad que estableciste.
my.queue.oldest_ready_age no lo muestra, porque esos trabajos no esperan. Para comparar los procesos, cada uno registra al arrancar una línea con sus routes y su routes_hash:
el hash debe ser el mismo en todas partes. Para ver adónde van las señales, lee las métricas propias de la plataforma de cada cola.
Permisos. Las credenciales de cada proceso necesitan poder enviar a todas las colas de las rutas: roles/cloudtasks.enqueuer.
Un envío que falla se registra y no se prueba en otra cola, para que un tipo que limitas no se desborde hacia los demás. Esos trabajos empiezan tarde, cuando el barrido vuelve a enviar sus señales tras 2 minutos.
Capacidad. Cualquier receptor ejecuta cualquier trabajo, así que tú eliges hasta dónde separarlos:
| Plataforma | Un receptor | Receptores separados |
|---|---|---|
| Google Cloud | Un servicio. Cada cola tiene sus propios maxConcurrentDispatches y maxDispatchesPerSecond; el límite de instancias del servicio se comparte |
Un servicio por cola, nombrado por la URL de la ruta, cada uno con su propio límite de instancias y concurrencia. Cada uno establece queue_cloudtasks_url con su propia URL |
Una cola necesita la misma configuración que la de por defecto: el rol en la cola. Solo la cola por defecto necesita el tick.
Qué añade una cola. Cada cola es una cosa más que crear, vigilar y pagar, y cuánto importa depende del tamaño de tu instancia.
Divide lo que hayas visto esperar en my.job.wait, no todo.
El barrido. Cada minuto el barrido busca trabajos que llevan vencidos más de 2 minutos sin ejecutarse, hasta 500 por ruta y 500 para la cola por defecto, y vuelve a señalarlos. Así, una cola que no da abasto recibe hasta 500 señales duplicadas por minuto. No ejecutan un trabajo dos veces, pero son mensajes que pagas, y cesan cuando se despeja la acumulación.
Las claves de orden siguen vigentes: la base de datos decide qué puede ejecutarse. Los trabajos de una misma clave pueden estar en colas distintas, pero una cola atascada también retrasa los trabajos posteriores de sus claves.
Añadir, mover y eliminar una cola.
- Crea la cola y su receptor, y da a todos los procesos permiso para enviarle.
- Cambia las rutas en todos los procesos. Mientras difieran, las señales van a una u otra cola y los trabajos se ejecutan en ambos sitios.
- Para eliminar una cola, quítala primero de las rutas en todas partes y espera a que esté vacía antes de borrarla. Una señal en una cola borrada se pierde, no su trabajo: el barrido vuelve a señalar el trabajo cuando lleva vencido 2 minutos. Una tarea de Cloud Tasks puede guardar la señal de un trabajo hasta con 30 días de antelación, así que un trabajo que vence más tarde que la espera simplemente lo señala el barrido cuando llega su hora.
Comprobaciones de salud
Sección titulada «Comprobaciones de salud»| Ruta | Tipo | Cuándo devuelve 200 |
|---|---|---|
GET /healthz, GET /health/live |
liveness (vida) | El proceso puede responder HTTP. No mira dependencias como la base de datos (para que una base de datos lenta no reinicie el proceso) |
GET /readyz, GET /health/ready |
readiness (disponibilidad) | La base de datos es accesible y el esquema está aplicado |
GET /api/v1/instance/health |
Monitorización de disponibilidad, páginas de estado y clientes (lo sirve el rol web) |
Igual que la disponibilidad. El resultado se guarda en caché en el proceso durante 60 segundos |
- Cloud Run reserva algunas rutas que terminan en
z, entre ellas/healthz, y las responde él mismo con un404; detrás de él, llama a/health/livey/health/ready, que responden lo mismo. - Un 200 de cualquiera de ellas tiene el cuerpo
{"status":"ok"}. /readyzcomprueba la base de datos en cada solicitud, y las solicitudes concurrentes comparten una sola comprobación./api/v1/instance/healthdevuelve 200 y{"status":"ok","checked_at":"<RFC 3339>"}cuando está sano, y 503 y{"status":"unavailable","checked_at":...}cuando falla (Cache-Control: no-store). Cada proceso toca la base de datos como máximo una vez por minuto, con independencia de la frecuencia con que se monitorice o se solicite, y no mira ni el token de acceso ni el límite de frecuencia. Apunta los monitores de disponibilidad a este endpoint, no al sondeo (/readyzo/health/ready). Para la configuración por servicio, el intervalo de monitorización y el costo, y cómo se trata el mantenimiento, consulta la guía de monitorización de disponibilidad.- Los tres registran en el nivel Debug del registro de acceso y no crean ningún span de traza.
- Cuando no se cumple la disponibilidad, la respuesta es 503 con un cuerpo
application/problem+jsonsegún el RFC 9457. Sutitlese traduce segúnAccept-Languagey no contiene detalles internos. La causa (un error de conexión o los nombres de las tablas que faltan) va al registro. - Una comprobación de disponibilidad se corta a los 3 segundos.
- La disponibilidad también exige que la base de datos contenga el
hosty elaccount_domainconfigurados, o que el proceso haya podido registrarlos. - Esquema aplicado significa que existe toda tabla que los archivos de esquema de la base de datos (
schema/<NN>-<module>/<dialect>.sql) declaran conCREATE TABLE(SQLite se comprueba mediantesqlite_schema, PostgreSQL mediante elcurrent_schema()de la conexión).my schema applyaplica todo el esquema, así que una tabla que falta significa que el esquema no está aplicado o es más antiguo que el binario. No se comprueban las diferencias de columnas e índices;my schema apply -dry-runimprime lo que cambiaría.
Solicitudes que esquivan el CDN
Sección titulada «Solicitudes que esquivan el CDN»Cuando el servidor está detrás de un CDN y su propia dirección sigue siendo pública, establece origin_secret y origin_secret_header para que rechace lo que no ha pasado por el CDN. Las comprobaciones de salud siguen siendo accesibles. Consulta Rechazar las solicitudes que no han pasado por el CDN.
Cabeceras de seguridad
Sección titulada «Cabeceras de seguridad»Cada respuesta lleva Strict-Transport-Security, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, Cross-Origin-Opener-Policy, Cross-Origin-Resource-Policy: same-site y X-Frame-Options,
y, en las respuestas que no son documentos, Content-Security-Policy: default-src 'none'; frame-ancestors 'none'; base-uri 'none'.
Un manejador las sobrescribe en las respuestas que necesitan otros valores, como el JSON de ActivityPub y los archivos multimedia públicos.
Permissions-Policy deniega la cámara, la geolocalización, los pagos y USB. Deniega también el micrófono, salvo mientras el chat de voz está activado (voice no es off):
entonces permite el micrófono solo a las páginas del propio origen del servidor (microphone=(self)), para que los navegadores puedan hablar en una llamada.
El HTML del cliente web recibe una CSP de documento que no usa nonce (script-src 'self', etc.).
Exige Trusted Types (require-trusted-types-for 'script') y limita las políticas que se pueden crear a las dos del cliente (trusted-types my-server-sanitized-html my-service-worker).
Cliente web
Sección titulada «Cliente web»Un proceso cuyo role es web o all sirve el cliente web incrustado en el binario.
| Ruta | Contenido | Cache-Control |
|---|---|---|
Cualquier GET que ninguna otra ruta coincida (/, /@alice, /@alice/status/{id}, /settings, etc.) |
El shell HTML de la SPA. Los ajustes de la instancia se pasan en <script type="application/json" id="config"> |
public, max-age=60, stale-while-revalidate=300, ETag |
GET /assets/* |
Archivos de compilación con nombres con hash | public, max-age=31536000, immutable, ETag |
GET /manifest.webmanifest |
El manifiesto de la aplicación web construido a partir de los ajustes de la instancia | public, max-age=60, stale-while-revalidate=300, ETag |
GET /sw.js, /icon.svg y otros archivos directamente bajo la compilación |
Servidos tal cual | no-cache, ETag |
GET /licenses/* |
Las licencias de lo que incluye la compilación (avisos de paquetes npm, y LICENSE-Unicode.txt y OFL.txt para datos incluidos que no son de npm). Servidas como text/plain; charset=utf-8 sea cual sea la extensión |
no-cache, ETag |
GET /robots.txt, /.well-known/tdmrep.json, /.well-known/security.txt |
Construidos a partir de los ajustes de la instancia (consulta Motores de búsqueda y rastreadores de IA) | public, max-age=3600, ETag |
- Las rutas bajo
/api,/oauth,/auth,/.well-known,/nodeinfo,/ap,/media,/uploads,/theme(la hoja de estilo del tema del servidor) y/licenses, y/robots.txt, nunca devuelven el shell; si ninguna otra ruta coincide devuelven un problema 404. - El shell se sirve después de la negociación de contenido de ActivityPub. Solicitar una ruta del shell con un
Acceptde ActivityPub devuelve 404 (las páginas de publicaciones redirigen, como se describe abajo). El shell siempre llevaVary: Accept. Cuando pones una CDN delante, incluye el tipo deAccept(ActivityPub o HTML) en la clave de caché, o excluye de la caché el shell,/ap/*y/@*. Sirve solo/assets/*desde la CDN. - Los archivos de texto de la compilación (scripts, hojas de estilo, imágenes SVG, avisos de licencia) se incrustan solo comprimidos. Una solicitud que acepta Brotli los recibe con
Content-Encoding: br, una que acepta gzip conContent-Encoding: gzip, y cualquier otra solicitud los recibe descomprimidos, siempre conVary: Accept-Encodingy un ETag para cada codificación. Un proxy delante no necesita compresión propia para ellos, y una CDN debe mantenerVary: Accept-Encoding(o la codificación) en su clave de caché para/assets/*. - El shell y las pantallas de inicio de sesión llevan cabeceras
Linkque nombran las hojas de estilo y el script de entrada que carga primero la página, a partir de las cuales una CDN como Cloudflare (su función Early Hints) puede crear sus propias pistas tempranas. Conweb_early_hints=true, el servidor también las envía primero en una respuesta103 Early Hints, para que el navegador obtenga los archivos mientras el servidor prepara la página. Está desactivado por defecto, ya que un proxy que no puede reenviar un 103 puede hacer fallar la solicitud:- Un Application Load Balancer externo de Google Cloud responde 502 o 503 (
backend_interim_response_not_supported): déjalo desactivado detrás de uno, como hace el despliegue en Cloud Run. - nginx lo reenvía desde la 1.29.0, con
early_hintsdefinido. - El
reverse_proxyde Caddy lo reenvía; una directivaencodelo descarta en versiones anteriores a la 2.8. - Los navegadores usan un 103 solo para una página a la que navegan, y Chrome y Edge solo sobre HTTP/2 y HTTP/3.
- Un Application Load Balancer externo de Google Cloud responde 502 o 503 (
- Un binario compilado sin el cliente web (un
go buildsimple, sin compilar antes el cliente) registra una advertencia al arrancar y sirve un shell sin scripts.
Endpoints de federación
Sección titulada «Endpoints de federación»Un proceso cuyo role es web o all responde a estos endpoints, que otros servidores del fediverso usan para encontrar y mostrar tus cuentas.
| Ruta | Contenido |
|---|---|
GET /.well-known/webfinger |
WebFinger (RFC 7033). resource es acct:alice@{account_domain} (acct:alice@{host} también funciona), un id de Actor, o la URL /@alice. subject es siempre el identificador del lado de account_domain |
GET /.well-known/host-meta, /.well-known/host-meta.json |
La plantilla de URI de WebFinger (XRD / JRD) |
GET /.well-known/nodeinfo, GET /nodeinfo/2.1 |
NodeInfo 2.1. metadata.sourceCode es el ajuste source_url, y software.repository también se establece para una URL https: (consulta Publicar el código fuente) |
GET /ap/actors/{uuid} |
El Actor (publicKey es el #main-key RSA). Una solicitud que prefiere HTML recibe un 303 a /@{username} |
GET /ap/actors/{uuid}/{outbox,followers,following,featured,featured-tags} |
Colecciones |
POST /ap/actors/{uuid}/inbox, POST /ap/inbox |
La bandeja de entrada (inbox) de cada actor local y la bandeja compartida. Las solicitudes deben llevar firma HTTP |
GET /@{username} |
Un 302 al id del Actor para un Accept de ActivityPub; en caso contrario, el HTML del cliente web (consulta más abajo) |
GET /@{username}/status/{uuid} |
Para un Accept de ActivityPub, un 302 al id (/ap/objects/{uuid}) de la publicación si un visitante sin sesión puede verla, y 404 si no. En caso contrario, el HTML del cliente web |
- El identificador del Actor de la instancia es
{account_domain}@{account_domain}(la misma forma que en Mastodon). - Una cuenta que no existe o no se puede mostrar (suspendida, desactivada, eliminada o remota) recibe siempre el mismo 404 (
Cache-Control: no-store). - Las respuestas anónimas llevan
Cache-Control: public, max-age=60. Las respuestas que varían segúnAcceptllevanVary: Accept. Para un CDN que no puede gestionarVary: Accept, excluye de la caché/ap/*y/@*.
Dominios de identificadores y de entrega separados
Sección titulada «Dominios de identificadores y de entrega separados»Cuando account_domain difiere de host, las solicitudes a /.well-known/webfinger, /.well-known/host-meta y /.well-known/nodeinfo del lado de account_domain se redirigen a host con un 301 (con Access-Control-Allow-Origin: *).
Si diriges a este servidor las solicitudes de account_domain, el servidor devuelve esa redirección por sí mismo.
Si responde otro servidor o proxy inverso, redirige a https://{host} conservando la ruta y la cadena de consulta.
Para LLM y agentes de programación:llms.txt,llms-full.txt, llms-small.txt