Diese Seite ist eine maschinelle Übersetzung der englischen Seite, die maßgeblich ist. Englische Seite lesen
Den Server betreiben: Start, Stopp und Health-Checks
So startest und stoppst du den Server, beziehst sein Image und beobachtest ihn im Betrieb: Metriken, Traces, die Job-Warteschlange und Health-Checks.
Den Server starten
Abschnitt betitelt „Den Server starten“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 validiert die Konfiguration, baut die Adapter für Datenbank, Job-Queue und Schlüsselverwaltung auf und nimmt HTTP auf listen an.
Mit tls = off, dem Standard, spricht es dort reines HTTP/1.1: Setze einen Reverse-Proxy oder Load Balancer davor, der HTTPS (und HTTP/2 oder HTTP/3 für die Clients) beendet und per HTTP/1.1 weiterleitet.
Um HTTPS ohne Proxy auszuliefern, siehe HTTPS vom Server aus ausliefern.
Die Echtzeit-Aktualisierungen (GET /api/v1/streaming, die Streams der lokalen und der föderierten Timeline und die Streams der Sprachchat-Räume) sind langlebige Antworten, die alle 30 Sekunden (in einem Sprachraum alle 15) einen Heartbeat-Kommentar senden und im Leerlauf offen bleiben.
Der Proxy darf diese Antworten nicht puffern (nginx: Der Server sendet X-Accel-Buffering: no), und sein Idle- oder Read-Timeout muss länger sein als das Heartbeat-Intervall.
Er wendet das Schema nicht an und führt die Daten-Upgrade-Schritte nicht aus: Führe vor dem Start my schema apply und dann my db upgrade aus (siehe Datenbank; Upgrades führen beides als Teil von Upgraden aus). Bis my db upgrade jeden Schritt des Releases aufgezeichnet hat, antwortet /readyz mit 503.
Im Docker-Compose-Setup (deploy/docker/compose.yaml; siehe Bereitstellung mit Docker Compose) führen die einmaligen Dienste schema und upgrade my schema apply und my db upgrade aus, bevor der Server startet.
Ist das Schema nicht angewendet, startet der Prozess trotzdem und die Bereitschaftsprüfung liefert 503, und er liefert nichts anderes aus, bis das Schema da ist.
Das erste my serve oder my-Kommando, das die Datenbank verwendet, trägt host und account_domain darin ein. Weicht die Konfiguration von den eingetragenen Werten ab, protokolliert my serve start failed mit beiden Wertepaaren und beendet sich mit Exit-Code 1, und die Kommandos geben denselben Fehler aus. Ausgenommen sind my schema apply und my db backup, die nicht prüfen, und der Wartungsmodus, der die Datenbank nicht liest. my config check -instance und my db upgrade -check prüfen, tragen aber nichts ein.
Ein Prozess, der die Datenbank beim Start nicht lesen konnte, ist nicht bereit, bis er es kann, und führt bis dahin keine Jobs aus und antwortet auf jede Anfrage außer den Health Checks (/healthz, /readyz, /health/live, /health/ready, /api/v1/instance/health) mit 503 und Retry-After. Das tut auch ein Server, der vor my schema apply gestartet wurde. Findet er dann andere Werte, hält er mit demselben Fehler an.
Im Profil production prüft my config check außerdem, ob die gültigen Einstellungen zu einer Produktionsinstanz passen: Fehler, etwa ein host, den andere Server nicht erreichen können, oder ein KEK, der nicht zufällig ist, lassen es mit 1 enden, Warnungen, etwa mail = none, nicht.
my serve protokolliert beides beim Start als Warnungen, startet aber trotzdem, führe my config check daher als Schritt der Bereitstellung aus.
Die Produktions-Checkliste listet die Prüfungen auf und was du vor dem Livegang von Hand überprüfen solltest.
role |
HTTP | Job-Worker |
|---|---|---|
all (Standard) |
Alle Routen | Läuft |
web |
Alle Routen | Läuft nicht |
worker |
Nur Health Checks (für Plattform-Probes) | Läuft |
Logs gehen als JSON Lines auf die Standardfehlerausgabe. Jede Zeile hat level (DEBUG, INFO, WARN, ERROR) und severity, dieselbe Stufe in der Form, die Cloud Logging liest (DEBUG, INFO, WARNING, ERROR und CRITICAL für einen Fehler, der den Prozess beendet).
Logs, die beim Bearbeiten einer Anfrage geschrieben werden, tragen eine request_id, und dieselbe ID wird im Antwort-Header X-Request-Id zurückgegeben.
Hat die X-Request-Id der Anfrage höchstens 128 Zeichen aus Buchstaben, Ziffern und -_.:, wird sie unverändert verwendet, als die von einem Load Balancer vergebene ID.
Logs innerhalb eines Traces (Anfragen und Jobs) tragen außerdem trace_id und span_id (siehe Traces).
Jede HTTP-Anfrage und jede Job-Ausführung schreibt am Ende eine Zeile. Die Zeile hat dieselben Namen und Werte wie die Labels der Metriken unten,
sodass du auf Cloud Run mit metrics_exporter = none aus diesen Zeilen logbasierte Metriken von Cloud Logging (Zähler und Verteilungen) bauen kannst.
Zeile (msg) |
Felder |
|---|---|
http request (INFO; Health Checks verwenden DEBUG) |
http.request.method, http.route, my.surface und http.response.status_code (eine Zahl) haben dieselben Werte wie die Labels von http.server.request.duration. Dazu duration_seconds (eine Zahl in Sekunden), url.path (der Pfad ohne Query-String), http.response.body.size und request_id. http.route und my.surface fehlen bei Anfragen, die keine Route erreicht haben (Health Checks, vor dem Routing abgelehnte Anfragen), und die Metrik zählt sie nicht. Eine Anfrage, deren Client ging, bevor der Server antworten konnte, hat den Status 499 statt eines 5xx, außer wenn ein Handler in Panik geriet; der Client hat nichts erhalten, daher zählt sie nicht als Serverfehler |
job (INFO bei Erfolg und bei postponed, WARN bei retry, ERROR bei dead) |
my.job.type und my.outcome haben dieselben Werte wie die Labels von my.job.duration. Dazu duration_seconds (my.job.duration), wait_seconds (my.job.wait), job_id, attempt und bei einem Fehler error |
error report (ERROR; CRITICAL bei einem Fehler, der den Prozess beendet) |
Eine Zeile pro gemeldetem Fehler (Fehlerberichte) |
Fehlerberichte
Abschnitt betitelt „Fehlerberichte“Die Anleitung Fehlerberichte behandelt, wo du diese Zeilen auf jeder Plattform liest, den Fehler-Bildschirm, Benachrichtigungen und das Senden von Berichten an einen Error-Tracker.
Der Server meldet die Fehler, die die Aufmerksamkeit des Betreibers brauchen, als je eine error report-Zeile:
- eine Panic in einem HTTP-Handler, einem Job oder einer Hintergrundaufgabe;
- ein Fehler hinter einer 5xx-Antwort der Client-API, der Admin-API, der Anmeldeseiten, von ActivityPub, OAuth oder Medien;
- ein Job, der endgültig fehlschlägt (
dead): Ihm gingen die Wiederholungen aus, oder er weigerte sich, erneut zu laufen. Zustellungen, die aufgaben, weil der andere Server weiter fehlschlug, werden nicht gemeldet; - ein Fehler beim Start: eine ungültige Konfiguration oder eine Datenbank oder ein Adapter, der sich nicht einrichten lässt.
4xx-Antworten, Job-Wiederholungen, der Wartungsmodus, fehlgeschlagene Readiness-Prüfungen, Anfragen, deren Client wegging, und Fehler, die andere Server verursachen, werden nicht gemeldet; die Metriken und die anderen Logzeilen decken sie ab.
Geht der Client einer Anfrage weg, werden die anderen Fehlerzeilen des Servers für diese Anfrage mit INFO statt ERROR geschrieben, da die meisten von ihnen nur sagen, dass die Anfrage abgebrochen wurde.
Die Zeile hat die Form, die Google Cloud Error Reporting liest: Auf Cloud Run erscheinen die Berichte ohne jede Einrichtung als Fehler gruppiert in Error Reporting. Auf anderen Plattformen ist sie eine einfache JSON-Zeile:
| Feld | Wert |
|---|---|
@type, serviceContext |
Der Ereignistyp von Error Reporting und {"service": "my", "version": "<version>"} |
my.error.fingerprint |
32 Hexadezimalziffern, die bei jedem Auftreten desselben Fehlers gleich sind: gebildet aus der Quelle, der Stelle, dem Fehlertyp und den Funktionen des Servers im Stack, ohne Zeilennummern |
my.error.source, my.error.kind |
server (oder web) sowie panic oder error |
my.error.where |
Wo es geschah: <surface> <method> <route> bei einer Anfrage (etwa client_api GET /api/v1/statuses/{id}), der Job-Typ bei einem Job, der Aufgabenname bei einer Hintergrundaufgabe, startup bei einem Fehler beim Start |
my.role, deployment.environment.name |
Die role des Prozesses und errors_environment |
request_id, job_id, attempt, trace_id, span_id |
Die IDs, um die Anfrage- oder Job-Zeilen desselben Fehlers zu finden, wenn er sie hat |
context.httpRequest |
Bei einem Fehler einer Anfrage: method, url (die Route, etwa /api/v1/statuses/{id}, nie der Pfad, den der Client angefragt hat) und responseStatusCode, der beantwortete Status (500) |
message |
Zuletzt in der Zeile: <type>: <message>, ein Zeilenumbruch und der Go-Stack |
Bevor ein Bericht den Prozess verlässt, werden in der Meldung URLs, E-Mail-Adressen, @user@host-Handles, IP-Adressen, UUIDs und ULIDs sowie Zahlen mit 10 oder mehr Ziffern durch <url>, <email>, <acct>, <ip>, <id> und <n> ersetzt, und sie wird auf 1 KiB gekürzt.
Der Stack behält seine Dateipositionen, aber nicht die Argumentwerte seiner Funktionszeilen (sie werden als (...) gezeigt), und wird auf 16 KiB gekürzt. Kein Bericht trägt einen Request-Body, Header, Query, Cookie, ein Konto, einen Benutzernamen, eine IP-Adresse oder einen User-Agent.
Keine andere Zeile trägt einen Stack, daher findet Error Reporting die Stacks nur dieser Zeilen.
Ein Feldname ist ein einzelner Schlüssel, der . enthält; er ist nicht verschachtelt. Setze ihn in Cloud-Logging-Filtern und -Extraktionen in Anführungszeichen (zum Beispiel jsonPayload."http.route" und EXTRACT(jsonPayload.duration_seconds) für den Wert einer Verteilung).
Felder, die als Labels verwendet werden, nehmen nur Werte aus einer endlichen Menge an; url.path, request_id und job_id sind nie Labels.
Mit metrics_exporter = emf sind diese beiden Zeilen selbst die EMF-Zeilen. Die Zeile http request trägt den Wert von http.server.request.duration, und die Zeile job trägt die Werte von my.job.duration und my.job.wait (Schlüssel nach den Metriken benannt),
dazu die Direktive _aws, service.name, service.version und my.role. Diese drei Metriken werden in keiner anderen Zeile geschrieben. Felder, die du in metrics_emf_dimensions wählst, werden als Strings geschrieben, wie EMF es verlangt (zum Beispiel ist die Dimension http.response.status_code "200").
Logs gehen auf die Standardfehlerausgabe und die anderen EMF-Zeilen auf die Standardausgabe. Der Log-Treiber awslogs von ECS sendet beide an CloudWatch Logs, sodass Metriken aus beiden extrahiert werden.
Docker-Compose-Dateien
Abschnitt betitelt „Docker-Compose-Dateien“deploy/docker/ enthält, was eine Instanz bereitstellt. compose.yaml läuft allein, und die anderen Dateien werden darübergelegt.
| Datei | Fügt hinzu | Verwende sie, wenn |
|---|---|---|
compose.yaml |
Den Server und seine einmaligen Datenbankdienste, auf SQLite und Mediendateien im Volume data |
Immer |
compose.postgres.yaml |
PostgreSQL in einem Container, im Volume postgres |
Du PostgreSQL auf dieser Maschine willst. Für einen PostgreSQL-Server anderswo lass sie weg und setze MY_DATABASE und MY_DATABASE_URL in .env |
compose.s3.yaml |
Medien in einem S3-kompatiblen Bucket; mit COMPOSE_PROFILES=garage zusätzlich ein Garage-Speicher mit einem Knoten im Volume garage |
Die Medien eine Platte übersteigen oder du sie in einem Bucket willst. Ohne das Profil ist der Speicher der externe der Einstellungen MY_BLOB_S3_* |
compose.caddy.yaml |
Caddy, mit TLS-Zertifikaten auf den Ports 80 und 443 | MY_HOST eine öffentliche Domain ist und auf dieser Maschine nichts anderes TLS beendet |
compose.build.yaml |
Baut das Image aus einem Checkout | Du deinen eigenen Build verwendest |
Wähle die Datenbank und den Medienspeicher vor dem ersten Start: Die Daten ziehen nicht von selbst um, wenn sich die Dateien ändern (Sichern zeigt, was umziehen muss).
Lege Dateien übereinander mit -f-Optionen in dieser Reihenfolge, oder nenne sie einmal in .env, damit jedes spätere docker compose-Kommando
(exec, logs, pull und die in den anderen Anleitungen) dieselben Dateien verwendet:
cd deploy/dockercp example.env .env# In .env: COMPOSE_FILE=compose.yaml:compose.postgres.yaml:compose.caddy.yamlEine Datei namens compose.override.yaml im Verzeichnis wird nur gelesen, wenn weder -f noch COMPOSE_FILE Dateien nennt. Führe sie
dann ebenfalls auf.
Einstellungen. Kopiere example.env nach .env. Compose liest .env, um die Variablen seiner Dateien zu füllen, und gibt die gesamte
Datei an die Container des Servers weiter, sodass jede Einstellung der Konfigurationsreferenz funktioniert,
indem sie dort gesetzt wird. Die Vorlage listet sie alle auf, mit je einem Satz dazu.
- Der Schlüsselverschlüsselungsschlüssel bleibt aus
.envheraus, in der Dateisecrets/kek, und die Container lesen ihn als Docker-Secret/run/secrets/my_kek, sodass er nie zu einer Umgebungsvariable wird. Eine ZeileMY_KEKin.envhält den Server an, derMY_KEKundMY_KEK_FILEzusammen ablehnt (den Schlüssel verwalten). - Der Server läuft als Benutzer
65532, und Compose bindet die Datei mit den Rechten ein, die sie hat, daher muss die Datei für andere lesbar sein. Lege sie in einem Verzeichnis ab, das nur du betreten kannst, wie es die Kommandos inexample.envtun. - Die anderen Secrets erreichen die Container als Umgebungsvariablen. Um eines stattdessen als Datei zu übergeben, binde es mit einem Secret
in einer eigenen
compose.override.yamlein und setze sein<NAME>_FILE, wie escompose.yamlfür den Schlüssel tut. .enventhält Secrets:chmod 600 .env, und bewahre eine Kopie bei deinen Backups auf.MY_LISTENbleibt:8080, da die Dateien sich mit diesem Port verbinden, es sei denn, der Server liefert HTTPS selbst aus (HTTPS vom Server aus ausliefern).
TLS mit Caddy. Setze MY_HOST auf eine Domain, deren DNS auf die Maschine zeigt, mit aus dem Internet erreichbaren Ports 80 und 443,
und entferne MY_WEB_ORIGIN aus .env. Caddy besorgt und erneuert das Zertifikat bei der ersten Anfrage selbst.
Der Server vertraut dem X-Forwarded-For der Standard-Adresspools von Docker; setze MY_TRUSTED_PROXIES, wenn deine abweichen.
Das mitgelieferte Garage. compose.s3.yaml mit COMPOSE_PROFILES=garage braucht die Werte, die example.env am Anfang auflistet.
Der einmalige Dienst garage-init bereitet den Speicher bei jedem up vor. Er bleibt innerhalb des Compose-Netzwerks, da der Server
die Medien selbst ausliefert. Ein Knoten ist eine Platte: Sichere das Volume garage oder den Bucket (Sichern).
HTTPS vom Server aus ausliefern
Abschnitt betitelt „HTTPS vom Server aus ausliefern“my kann HTTPS selbst ausliefern, sodass eine kleine Maschine den ganzen Server als eine Binärdatei mit einer Domain und den Ports 80 und 443
ohne Reverse-Proxy betreibt. Mit tls = acme besorgt es seine Zertifikate bei einer ACME-Zertifizierungsstelle wie Let’s
Encrypt. Mit tls = files liefert es ein Zertifikat und einen Schlüssel aus, die du bereitstellst und mit einem anderen Werkzeug, etwa
certbot, aktuell hältst.
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- Ports. Der Server liefert HTTPS auf
listenaus (standardmäßig:443, sobaldtlsnichtoffist). Auftls_http_listen(standardmäßig:80) leitet erGET- undHEAD-Anfragen mit301an denselben Pfad aufhttpsweiter und beantwortet jede andere Methode mit400, damit kein Anfrage-Body im Klartext unterwegs ist. - Hosts. Der Server bedient
hostund den Host vonweb_origin, wenn der abweicht. Ein Handshake für jeden anderen Namen schlägt ohne Zertifikat fehl und veranlasst den Server nie, eines zu bestellen. - Verbindungen. TLS 1.2 oder neuer mit den Standard-Cipher-Suites von Go, HTTP/2 und HTTP/1.1, höchstens 64 KiB Anfrage-Header
und höchstens 100 gleichzeitige Streams auf einer HTTP/2-Verbindung. Die Timeouts sind die von reinem HTTP. Der Server
fügt weiterhin jeder Antwort
Strict-Transport-Securityhinzu (Sicherheits-Header). - Rollen. Nur die Rollen
webundallhören mit TLS zu. Einworkerliefert seine Health Checks in reinem HTTP auflisten(standardmäßig:8080) aus und öffnet keinen Port 80. - Client-Adressen. Ohne Proxy davor ist die Gegenstelle der Verbindung der Client: Lass
trusted_proxiesleer. Setze es nur, wenn sich ein CDN davor überhttpsmit dem Server verbindet. - Wartungsmodus.
my serve -maintenanceliest wedertlsnoch die Zertifikate und antwortet in reinem HTTP auflisten(:8080, wenn du nichts setzt), richteMY_LISTENund deine Firewall daher auf diesen Port aus, solange er läuft, oder behalte einen Reverse-Proxy für die Wartung.
Zertifikate von einer ACME-Zertifizierungsstelle
Abschnitt betitelt „Zertifikate von einer ACME-Zertifizierungsstelle“Mit tls = acme bestellt der Server für jeden seiner Hosts, der keines hat, ein Zertifikat bei der Zertifizierungsstelle
unter tls_acme_directory (standardmäßig Let’s Encrypt).
- Bevor du anfängst.
hostmuss ein DNS-Name sein, der auf den Server zeigt, und die Ports 443 und 80 müssen aus dem Internet erreichbar sein: Die Zertifizierungsstelle prüft, ob der Server den Namen kontrolliert, indem sie sich mit ihm verbindet. Er antwortet auflisten(die TLS-ALPN-01-Challenge) oder auftls_http_listen(die HTTP-01-Challenge), sodass ein leerestls_http_listenmit Port 443 allein trotzdem funktioniert. Wildcard-Zertifikate und die Validierung über DNS-Einträge sind nicht verfügbar. - Erster Start. Der Server beginnt zuzuhören, ohne auf ein Zertifikat zu warten, und bestellt sie dann. Bis ein Host sein
Zertifikat hat, schlägt ein Handshake dafür fehl; bei Let’s Encrypt kommen die ersten Zertifikate meist innerhalb einer Minute. Das Log
sagt für jeden Host
obtained a TLS certificateundthe TLS certificate could not be obtainedmit dem Grund, wenn eine Bestellung fehlschlägt. - Erneuerungen. Der Server erneuert jedes Zertifikat zu dem Zeitpunkt, den die Zertifizierungsstelle dafür vorschlägt (ACME Renewal
Information): Er wählt einmal einen zufälligen Zeitpunkt innerhalb des vorgeschlagenen Fensters, behält ihn, solange das Fenster bleibt, und fragt erneut,
wie das
Retry-Afterder Stelle sagt, mindestens alle 12 Stunden, damit eine Stelle, die Zertifikate früher ersetzen muss, das Fenster verschieben kann. Bietet die Stelle kein solches Fenster, erneuert der Server nach zwei Dritteln der Lebensdauer des Zertifikats oder nach der Hälfte bei einem Zertifikat, das weniger als 10 Tage gültig ist. Eine Erneuerung teilt der Stelle mit, welches Zertifikat sie ersetzt, was sie außerhalb der Rate Limits von Let’s Encrypt hält. Das aktuelle Zertifikat bleibt in Betrieb, bis seine Erneuerung kommt, und eine fehlgeschlagene Erneuerung wartet wie eine erste Bestellung. - Fehlgeschlagene Bestellungen. Nach einer fehlgeschlagenen Bestellung wartet der Server vor der nächsten für denselben Host: 1 Minute nach dem ersten Fehler, 10 Minuten nach dem zweiten, 100 Minuten nach dem dritten, dann einen Tag, damit er innerhalb der Grenzen der Zertifizierungsstelle bleibt. Die Wartezeit wird in der Datenbank gehalten und übersteht Neustarts. Behebe die Ursache (DNS, eine Firewall, ein Port), und die nächste Bestellung geht hinaus, wenn die Wartezeit endet.
- Wo sie aufbewahrt werden. Das Konto bei der Zertifizierungsstelle, die Zertifikate und die Aufzeichnung jeder Bestellung werden in der Datenbank aufbewahrt; die privaten Schlüssel werden wie die anderen Secrets mit dem Schlüsselverschlüsselungsschlüssel versiegelt (Schlüsselverwaltung). Ein Backup der Datenbank enthält sie, und ein neu gestarteter Server liefert die gespeicherten Zertifikate sofort aus, ohne zu bestellen. Wird der Schlüsselverschlüsselungsschlüssel geändert, werden sie neu verpackt; es werden keine neuen Zertifikate bestellt.
- Mehrere Prozesse. Prozesse, die die Datenbank und den
kv-Store teilen, koordinieren sich: Einer bestellt das Zertifikat eines Hosts, während die anderen warten und es dann laden, und jeder Prozess, mit dem sich die Zertifizierungsstelle verbindet, beantwortet ihre Prüfung. Verwendekv = dboderkv = valkey;kv = memorywird abgelehnt, es sei denn, ein Prozess führt alles aus (role = all). Der Prozess, der ein Zertifikat erhält, sagt es den anderen über denstream-Broker, und sie liefern es innerhalb von Sekunden aus; jederweb-Prozess mittls = acmehört daher weiter am Broker zu. Mitstream = huboder wenn eine Mitteilung verloren geht, liest dennoch jeder Prozess alle 5 Minuten die aktuellen Zertifikate aus der Datenbank, und jede Minute, sobald sein Zertifikat seinen Erneuerungszeitpunkt erreicht hat, sodass eine Erneuerung sie lange vor dem Ablauf des alten Zertifikats erreicht. - Profile.
tls_acme_profilewählt ein Profil, das die Zertifizierungsstelle anbietet, etwashortlivedbei Let’s Encrypt. Leer nimmt ihren Standard. Nach einem Profilwechsel folgt die nächste Erneuerung ihm, und das Zertifikat, das sie bringt, wird ausgeliefert, auch wenn es vor dem abläuft, das es ersetzt.
Um es auszuprobieren, ohne die Grenzen der Produktionsumgebung von Let’s Encrypt zu verbrauchen, beginne mit deren Staging-Umgebung, die Zertifikate ausstellt, denen Browser nicht vertrauen, unter viel höheren Grenzen:
MY_TLS_ACME_DIRECTORY=https://acme-staging-v02.api.letsencrypt.org/directorySobald das Log sagt, dass die Zertifikate erhalten wurden, und curl -kv https://social.example/ ein Zertifikat von
(STAGING) zeigt, entferne die Einstellung und starte neu. Der Server registriert ein neues Konto bei der Produktionsumgebung und
bestellt dort seine Zertifikate; die Staging-Zertifikate bleiben in der Datenbank und werden nicht mehr ausgeliefert.
Zertifikate aus Dateien
Abschnitt betitelt „Zertifikate aus Dateien“Mit tls = files enthält tls_cert_file zuerst das Zertifikat des Servers, dann seine Zwischenzertifikate (das fullchain.pem von
certbot); tls_key_file enthält seinen Schlüssel. Das Zertifikat muss host abdecken, und es bedient auch den Host von
web_origin, wenn der abweicht und das Zertifikat ihn abdeckt.
Der Server sieht jede Minute auf die Änderungszeiten beider Dateien und lädt sie neu, wenn sich eine ändert, ohne Neustart. Ein Paar, das noch nicht zusammenpasst (ein neues Zertifikat vor seinem neuen Schlüssel), lässt das vorherige Zertifikat bis zur nächsten Prüfung in Betrieb, und das Log sagt, warum.
Kommandos und Metriken
Abschnitt betitelt „Kommandos und Metriken“my tls zeigt und steuert die Zertifikate mit der Konfiguration des Servers, von jeder Maschine aus, die die
Datenbank erreicht (die Admin-CLI):
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_compromisestatuszeigt für jeden Host das aktuelle Zertifikat (Seriennummer, Aussteller und Ablauf), wann es erneuert wird (das Fenster der Zertifizierungsstelle oder der aus seiner Lebensdauer abgeleitete Zeitpunkt), wie viele Bestellungen in Folge keines erbracht haben, und die letzten Bestellungen mit ihren Fehlern. Mittls = fileszeigt es das Zertifikat vontls_cert_file.renewbestellt jetzt ein Zertifikat und überspringt den Erneuerungszeitpunkt und die Wartezeit nach fehlgeschlagenen Bestellungen: Führe es aus, sobald du die Ursache fehlgeschlagener Bestellungen behoben hast. Der laufende Server beantwortet die Prüfung der Zertifizierungsstelle, er muss also laufen, und seine Prozesse liefern das neue Zertifikat innerhalb von Sekunden aus, mitstream = hubinnerhalb von 5 Minuten.revokebestellt zuerst ein Zertifikat, das das aktuelle ersetzt, bittet dann die Zertifizierungsstelle, das aktuelle zu widerrufen, und zeichnet es auf; jeder Prozess hört innerhalb von Sekunden auf, das widerrufene Zertifikat auszuliefern, mitstream = hubinnerhalb von 5 Minuten. Verwendekey_compromise, wenn der private Schlüssel anderen bekannt sein könnte, sonstsupersededoderoperator. Lässt sich das Ersatzzertifikat nicht bestellen, geht der Widerruf trotzdem durch: Die Prozesse liefern das vorherige Zertifikat des Hosts aus, wenn es nicht widerrufen ist, oder nichts, bis der Server ein neues erhält.renewundrevokebrauchentls = acmeund ein andereskvalsmemory, da die Prozesse, mit denen sich die Zertifizierungsstelle verbindet, die Antworten auf ihre Prüfungen aus demkv-Store lesen. Mittls = fileswerden sie abgelehnt: Erneuere oder widerrufe das Zertifikat mit dem Werkzeug, das die Dateien schreibt.
Ist metrics_exporter gesetzt, alarmiere bei my.tls.certificate.expiry unter 7 Tagen und bei
my.tls.order.consecutive_failures von 3 oder mehr (Alarme): Eine fehlschlagende Erneuerung zeigt sich
Wochen vor dem Ablauf des Zertifikats.
Prüfungen und Betrieb
Abschnitt betitelt „Prüfungen und Betrieb“my config check meldet mit tls = acme Bedingungen, denen nicht zugestimmt wurde, einen host, der eine IP-Adresse, localhost
oder ein Name ohne Punkt ist, ein tls_acme_directory, das keine https-URL ist, und kv = memory mit einer anderen role als
all als Fehler. Mit tls = files meldet es ein Zertifikat oder einen Schlüssel, der nicht gelesen werden kann, einen Schlüssel, der nicht zum
Zertifikat passt, und ein Zertifikat, das host nicht abdeckt, abgelaufen oder noch nicht gültig ist, als Fehler und warnt, wenn
weniger als 14 Tage bleiben. Es warnt, wenn trusted_proxies mit einem anderen tls als off gesetzt ist. Mit tls = off warnt es,
wenn listen Port 80 oder 443 auf einer anderen Adresse als Loopback ist, da anscheinend nichts vor dem
Server TLS beendet; der Server protokolliert dieselbe Warnung einmal pro Start, wenn ein solcher Server mit leerem trusted_proxies eine einfache
HTTP-Anfrage von einer anderen Adresse als Loopback erhält.
systemd. Ports unter 1024 brauchen für einen anderen Benutzer als root eine Capability. Gib sie dem Dienst und sonst nichts:
[Service]User=myAmbientCapabilities=CAP_NET_BIND_SERVICECapabilityBoundingSet=CAP_NET_BIND_SERVICEMit tls = files muss der Benutzer außerdem die Zertifikatsdateien lesen können. Bei certbot sind dessen Verzeichnisse live und archive
nur für root lesbar: Gib der Gruppe des Dienstes Zugriff (chgrp und chmod g+rx auf den Verzeichnissen, g+r auf
den Schlüsseln), oder kopiere die Dateien in einem Deploy-Hook in ein Verzeichnis, das der Dienst liest.
Docker. Docker 20.10 und neuer lassen einen Container Ports unter 1024 ohne Capability öffnen, daher funktioniert das Image
unverändert. Das Image setzt MY_LISTEN=:8080, setze also MY_LISTEN=:443 in .env, veröffentliche beide Ports in einer
compose.override.yaml (ports: ["80:80", "443:443"]). Binde mit tls = files die Zertifikatsdateien schreibgeschützt dort ein,
wohin MY_TLS_CERT_FILE und MY_TLS_KEY_FILE zeigen; der Server läuft als Benutzer 65532, der sie lesen können muss.
Mit tls = acme gibt es nichts einzubinden: Die Zertifikate liegen in der Datenbank.
Lass compose.caddy.yaml weg, das dieselben Ports belegen würde. Das gilt nicht mit network_mode: host, wo
der Container das Netzwerk der Maschine teilt und dieselbe Capability braucht wie ein Dienst außerhalb eines Containers.
Im Vergleich zu Caddy. Wer HTTPS von my ausliefert, verzichtet auf HTTP/3, die Kompression von Antworten (der Server sendet die Dateien des Web-
Clients komprimiert und komprimiert sonst nichts), ein eigenes Access-Log (die http request-Logzeilen des Servers bleiben) und per
DNS validierte Zertifikate, einschließlich Wildcard-Zertifikaten. Behalte compose.caddy.yaml oder einen anderen Proxy, wenn du etwas davon brauchst.
Das Image beziehen
Abschnitt betitelt „Das Image beziehen“Das Server-Image ist ghcr.io/mycroblog/my, öffentlich, für linux/amd64 und linux/arm64, mit jedem Adapter.
| Tag | Zeigt auf | Verwende es für |
|---|---|---|
0.1.0 |
Diese Version, für immer | Eine Version benennen |
0.1 |
Den neuesten Patch von v0.1 |
Docker Compose, das bei jedem up das Schema anwendet |
0.1.0-rc.1 |
Dieses Prerelease | Ein Release ausprobieren, bevor es erscheint |
nightly |
Den neuesten Commit von main, der die nächtlichen Tests bestanden hat, jede Nacht verschoben, in der er sich ändert |
Änderungen vor einem Prerelease ausprobieren, auf einer Instanz, die du wegwerfen kannst |
Es gibt kein latest und kein 0: Beide würden eine Minor-Version überschreiten, und jedes Upgrade auf eine neue Minor-Version muss über die vorige laufen. Nenne in jedem Befehl eine Version; docker pull ghcr.io/mycroblog/my allein schlägt mit manifest unknown fehl.
Auch ein Patch-Release kann my schema apply und my db upgrade brauchen, folge also außerhalb von Docker Compose für jede Version Upgrade. Hefte in der Produktion den Digest an, den die Notizen des Releases nennen:
ghcr.io/mycroblog/my:0.1.0@sha256:...nightly hat keinen Upgrade-Pfad. Upgrades werden nur zwischen veröffentlichten Versionen versprochen: Von einem nightly-Image
zum nächsten oder von nightly zu einem Release können sich das Schema und die Datenschritte von my db upgrade auf eine Weise ändern, die kein
Release durchläuft, rechne also damit, seine Datenbank neu anzulegen. Betreibe es nie in der Produktion. my version gibt aus, welcher Commit es ist, wie in
v0.1.0-rc.5.0.20261109182600.g7a789720a1b2: eine Version nach dem neuesten Release (v0.1.0-rc.5), die Zeit des Commits in UTC und die
ersten 12 Zeichen des Commits nach g. Um einen Build zu behalten, hefte seinen Digest an (ghcr.io/mycroblog/my:nightly@sha256:...): Ein älterer Build verliert
das Tag, bleibt aber über seinen Digest abrufbar.
Wo du es betreibst:
- Docker Compose:
deploy/docker/compose.yamlbetreibt das Image vonMY_VERSIONin.env(Docker-Compose-Dateien). Um es stattdessen aus einem Checkout zu bauen, füge die Überschreibungcompose.build.yamlhinzu (docker compose -f compose.yaml -f compose.build.yaml up -d --build) und setzeMY_VERSIONauf einen eigenen Namen, da er dein lokales Image benennt und das ist, wasmy versionausgibt. - Kubernetes: Beziehe es unverändert von
ghcr.io. - Cloud Run: Nutze das Image von
ghcr.iodirekt. Eine Bereitstellung löst das Tag zu einem Digest auf. - AWS (ECS, EKS): Kopiere das Image nach Amazon ECR oder nutze einen ECR-Pull-Through-Cache, der Zugangsdaten für ghcr.io braucht.
Ein Image verifizieren
Abschnitt betitelt „Ein Image verifizieren“Jedes veröffentlichte Image hat eine über Sigstore signierte Provenienz, die den Digest an den Workflow und den Commit bindet, der es gebaut hat, sowie eine SBOM. Mit der GitHub CLI, und bei ghcr.io angemeldet, wenn der Befehl danach fragt:
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 }}'Der erste Befehl schlägt fehl, es sei denn, das Image wurde vom Release-Workflow dieses Repositorys gebaut. Verifiziere ein nightly-Image stattdessen mit
--signer-workflow mycroblog/my/.github/workflows/nightly.yml. Er gibt den Commit aus, der der Commit des Tags der Version ist; das Label org.opencontainers.image.revision des Images nennt denselben.
Den Quellcode veröffentlichen (AGPL-3.0)
Abschnitt betitelt „Den Quellcode veröffentlichen (AGPL-3.0)“my steht unter der AGPL-3.0-only. Abschnitt 13 der AGPL-3.0 verlangt von jedem, der den Server betreibt und Nutzern erlaubt, über ein Netzwerk mit ihm zu interagieren,
diesen Nutzern einen Weg anzubieten, den zugehörigen Quellcode des laufenden Programms zu erhalten. Das gilt für alle, die mit dem Server interagieren, nicht nur für Personen mit einem Konto.
Gib mit der Einstellung source_url (Umgebungsvariable MY_SOURCE_URL; siehe die Konfigurationsreferenz) an, wo der Quellcode veröffentlicht ist.
| Wert | Bedeutung |
|---|---|
| Nicht gesetzt | Der Standard, https://github.com/mycroblog/my. Nutze ihn, wenn du my unverändert betreibst: Das GET /instance eines Releases nennt dann den Quellcode dieser Version, https://github.com/mycroblog/my/tree/v0.1.0, und NodeInfo das Repository |
Eine https:-URL |
Ein Ort, an dem der Quellcode gelesen werden kann (das Repository eines Forks, der Tag oder das Archiv einer bestimmten Version und so weiter) |
Ein mailto:-URI |
Eine E-Mail-Adresse, bei der der Quellcode angefordert werden kann (zum Beispiel mailto:source@example.org; ?subject=... ist erlaubt) |
Jeder andere Wert (http:, git@..., ein relativer Pfad, eine URL mit Nutzerangaben oder einem #, ein mailto: ohne Adresse und so weiter) lässt my config check fehlschlagen, und der Server startet nicht.
Der Wert erscheint an diesen Stellen:
source_urlimGET /instanceder Client-API- Der Abschnitt „Quellcode“ der Informationsseite des Servers im Webclient (
/about) und ein Link auf der Startseite (/) metadata.sourceCodein NodeInfo (/nodeinfo/2.1). Einehttps:-URL wird auch alssoftware.repositoryveröffentlicht (das NodeInfo-2.1-Schema erlaubt insoftware.repositorynur einehttp(s)-URL, einmailto:-Wert erscheint also nur inmetadata.sourceCode)
Wenn du my forkst oder veränderst
Abschnitt betitelt „Wenn du my forkst oder veränderst“Betreibst du ein verändertes my (du wendest Patches an, baust einen Fork oder tauschst Abhängigkeiten aus), zeigt die Standard-URL nicht mehr auf den Quellcode dessen, was läuft.
Ändere source_url auf den Ort, an dem der Quellcode der laufenden Version samt deinen Änderungen zu finden ist. Wer auf den Commit, Tag oder das Archiv zeigt, das zur laufenden Version passt, statt auf den neuesten Stand eines Repositorys, lässt Nutzer verlässlich denselben Quellcode erhalten.
Betreibst du ein unverändertes offizielles Release, behalte den Standard.
Wenn du mailto: verwendest
Abschnitt betitelt „Wenn du mailto: verwendest“- Sei bereit, den zugehörigen Quellcode (einschließlich der Skripte, die zum Bauen nötig sind) umgehend auszuhändigen, wenn jemand danach fragt. Nur eine Adresse zu nennen, ohne zur Lieferung bereit zu sein, erfüllt die Pflicht nicht.
- Verwende eine Adresse, die auch dann noch funktioniert, wenn du den Server nicht mehr betreibst oder die zuständige Person wechselt. Eine gemeinsame Betriebsadresse ist besser als ein persönliches Postfach.
- Stelle sicher, dass der Spamfilter Anfragen nicht verwirft.
- Verwende eine Adresse, die du gern öffentlich machst: Jeder kann sie auf der Informationsseite, der Startseite und in NodeInfo sehen.
Metriken
Abschnitt betitelt „Metriken“Die Einstellung metrics_exporter (Standard none) exportiert Dienstmetriken. Ihre zugehörigen Einstellungen stehen in der Konfigurationsreferenz.
metrics_exporter |
Pfad | Geeignet für |
|---|---|---|
none |
Es wird nichts exportiert. Die Instrumentierung kostet fast nichts. Die Werte der ganzen Instanz gehen weiterhin alle 15 Minuten in eine metrics snapshot-Logzeile |
Cloud Run (verwende stattdessen die Metriken der Plattform und logbasierte Metriken) |
prometheus |
GET /metrics auf metrics_listen (Standard 127.0.0.1:9464). Es ist ein vom öffentlichen listen getrennter Listener ohne Authentifizierung und läuft für jede role |
Selbst gehostet (von einem Prometheus-kompatiblen Server oder KEDA abgerufen) |
otlp |
Wird per OTLP/HTTP an einen OpenTelemetry Collector gesendet. Das Ziel stammt aus den üblichen OTel-Umgebungsvariablen wie OTEL_EXPORTER_OTLP_ENDPOINT |
Setups, in denen du einen Collector betreiben kannst |
emf |
JSON-Zeilen im CloudWatch Embedded Metric Format. Anfrage- und Job-Metriken reisen auf den abschließenden Logzeilen oben; die anderen werden auf die Standardausgabe geschrieben, eine Zeile pro Label-Satz, wenn eine Anfrage oder ein Job endet | AWS ECS |
Die Metriken sind unten aufgelistet. In Prometheus wird . in einem Namen zu _, und ein Einheiten-Suffix (_seconds und _total für einen Zähler) wird angehängt.
| Metrik | Art | Labels |
|---|---|---|
http.server.request.duration |
Histogramm, Sekunden | http.request.method, http.route (der Pfad des Routenmusters; other, wenn keines passt), 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 |
Zähler | activity.type (ein bekannter Activity-Typ oder other), my.outcome (accepted / duplicate / rejected / ignored / error), my.inbox.rejection (nur bei rejected: signature für eine Signatur oder einen Integritätsnachweis, der fehlt, ungültig ist oder sich nicht verifizieren lässt oder dessen Schlüssel nicht abgerufen werden konnte; suspended für eine gesperrte Domain; federation_off; rate_limited; invalid für eine Aktivität ohne gültige id, type, actor oder object) |
my.relay.activities |
Zähler | my.outcome (admitted / over_limit / restricted / not_receiving: ob eine von einem Relay getragene Aktivität übernommen wurde und warum sie verworfen wurde; siehe Föderations-Relays) |
my.move.activities |
Zähler | my.outcome (recorded / duplicate / not_own_actor / same_account / target_unavailable / alias_missing / target_moved / suspended / too_soon: ob ein empfangenes Move aufgezeichnet wurde und warum es verworfen wurde) |
my.delivery.attempts |
Zähler | my.outcome (success / retry / gone / failed; gone umfasst ein 410 und Zustellungen, die übersprungen werden, weil der Server nicht verfügbar oder gesperrt ist) |
my.delivery.duration |
Histogramm, Sekunden | my.outcome |
my.ux.duration |
Histogramm, Sekunden | my.ux.metric (lcp / inp / long_frame / transition / press / call_rtt / call_jitter), my.ux.name (die Route, Interaktionsart, Aktion oder der Anruf-Transport; UX-Messungen) |
my.ux.call.packet_loss |
Histogramm, Prozent | my.ux.name (der Anruf-Transport) |
my.plugin.failures |
Zähler | my.plugin.kind (eine Art von Plugin), my.plugin.code (der Connect-Code des Fehlers) |
my.plugin.slot_wait |
Histogramm, Sekunden | my.plugin.kind (wie lange ein Aufruf auf seinen Zug unter den gleichzeitig laufenden Aufrufen dieser Art wartete) |
my.hook.decisions |
Zähler | hook, mode, outcome (die Entscheidungen, die ein Entscheidungs-Hook aufgezeichnet hat) |
my.hook.failures |
Zähler | hook, outcome (timeout, error, invalid oder breaker_open) |
my.hook.duration |
Histogramm | hook (Sekunden pro Aufruf des Plugins) |
my.job.duration |
Histogramm, Sekunden | my.job.type (ein registrierter Job-Typ oder other), my.outcome (success / retry / dead / postponed: postponed ist ein Lauf, der nichts getan hat und keinen der Versuche des Jobs verbraucht, etwa ein Abruf einer Link-Karte, der auf seinen Host wartet) |
my.job.wait |
Histogramm, Sekunden | my.job.type |
my.link_card.host_pauses |
Zähler | http.response.status_code (429 / 503). Eine pro Pause der Link-Karten-Abrufe bei einem Host; siehe Link-Vorschauen |
my.translation.requests |
Zähler | my.outcome (author / cache / provider / no_provider / limit / unsupported / failed). Eine pro Anfrage, einen Beitrag zu übersetzen, den die betrachtende Person sehen darf, oder den Beitrag oder Kommentar einer Meldung, den ein Moderator anfordert: beantwortet aus den eigenen Worten der Autorin oder des Autors, aus einer aufbewahrten Übersetzung oder von einem Anbieter, oder abgelehnt, weil kein Anbieter den Beitrag erhalten darf, ein Monatslimit erreicht ist, kein Anbieter die Sprache übersetzt oder kein Anbieter eine brauchbare Übersetzung geliefert hat. |
my.translation.lock_waits |
Zähler | Keine. Eine pro Anfrage, die auf eine andere Anfrage wartete, die denselben Beitrag in dieselbe Sprache übersetzt, statt einen Anbieter zu fragen |
my.translation.characters |
Zähler | my.provider (die ID eines Übersetzungsanbieters). Die Zeichen von Beiträgen und Meldungskommentaren, die an den Anbieter gesendet werden, ohne Auszeichnungen, einschließlich fehlschlagender Aufrufe. Das zählen die Monatslimits, und es kann von dem abweichen, was der Anbieter abrechnet |
my.timeline.delivery.lag |
Histogramm, Sekunden | Keine (von der Erstellung eines lokalen Beitrags bis zu seinem Schreiben in die Startseiten-Timelines und der Benachrichtigung der Streams) |
my.stream.connections |
UpDownCounter | my.stream.kind (user, timeline für die Streams der lokalen und der föderierten Timeline, voice für die Streams der Sprachchat-Räume) |
my.stream.signals |
Zähler | my.stream.kind (user / timeline). Eines pro Signal, das ein offener Stream verarbeitet hat, ob er dem Client etwas gesendet hat oder nicht |
my.accounts.registered |
Zähler | Keine |
my.statuses.created |
Zähler | my.visibility |
my.billing.imports |
Zähler | my.billing.source (aws / gcp / plugin), my.outcome (success / failed), error.type (nur bei failed: die Art des Fehlers, wie in Cloud-Nutzungskosten importieren). Jeder Versuch zählt, auch die Wiederholungen und die Fehler, die auf den nächsten täglichen Import warten |
my.supporter.tip_checkouts |
Zähler | my.outcome (started / rate_limited / paid / expired). Eines pro Start eines Trinkgelds, das die Seite des Anbieters erhalten hat, pro Start, den die Limits abgelehnt haben, und pro Trinkgeld, das bezahlt wurde oder unbezahlt endete; siehe Trinkgelder für die Alarme, die es bedient |
my.voice.turn.credentials |
Zähler | my.voice.turn (coturn / cloudflare), my.outcome (issued / reused / failed). Eines pro TURN-Zugangsdatum, das ein Teilnehmer eines Sprachchats beim Betreten eines Raums oder beim Erneuern seiner Verbindung angefordert hat: reused heißt, früher für dieselbe Verbindung ausgestellte Cloudflare-Zugangsdaten wurden erneut zurückgegeben, und failed heißt, Cloudflare war nicht erreichbar oder hat abgelehnt, sodass der Teilnehmer einen Fehler erhielt und sich nicht verbinden konnte |
my.errors.exported |
Zähler | my.outcome (success / dropped / failed: eines pro Fehlerbericht für den Dienst von errors_exporter. dropped heißt, der Bericht wurde nicht gesendet, weil bereits 1.000 Berichte warteten oder der Dienst den Server gebeten hat, langsamer zu werden, und der Server wartet, so lange der Dienst es verlangt, bevor er wieder sendet; failed heißt, der Dienst war nicht erreichbar oder hat den Bericht abgelehnt. Ein Bericht wird einmal gesendet und nie wiederholt, und die Berichte, die 2 Sekunden nach Beginn eines Herunterfahrens noch warten, gehen verloren) |
my.queue.ready |
Gauge | my.job.type (die Zahl der ausführbaren Jobs in der Datenbank-Queue) |
my.queue.oldest_ready_age |
Gauge, Sekunden | my.job.type (wie lange der älteste ausführbare Job jedes Typs in der Datenbank-Queue gewartet hat; ein Typ ohne ausführbaren Job hat keinen Wert) |
my.queue.dead |
Gauge | Keine |
my.instance.users, my.instance.statuses |
Gauge | Keine (die Zahlen lokaler Benutzer und Beiträge, wie in NodeInfo) |
my.media.stored_bytes |
Gauge, Bytes | my.media.origin (local / remote_cache) |
my.db.size |
Gauge, Bytes | Keine (die Größe der Datenbank: pg_database_size bei PostgreSQL; die Datenbankdatei ohne ihr Write-Ahead-Log bei SQLite) |
my.billing.import.failing |
Gauge | my.billing.source (1, wenn der neueste Import der Quelle fehlschlug, sonst 0) |
my.federation.instances |
Gauge | my.federation.instance.state (available: Server, an die weiter zugestellt wird, die aber seit ihrer letzten Antwort an mindestens einem Tag fehlschlugen; unavailable: Server, deren Zustellungen pausiert sind) |
my.metrics.snapshot.age |
Gauge, Sekunden | my.metrics.snapshot.part (queue / totals) |
my.errors.reported |
Zähler | my.error.source (server / web), my.error.kind (panic / error). Eines pro Fehlerbericht |
my.tls.certificate.expiry |
Gauge, Sekunden | host (die Zeit bis zum Ablauf des Zertifikats, das dieser Prozess für einen seiner Hosts ausliefert, mit tls = acme oder tls = files; jeder Prozess meldet sein eigenes, sodass ein Prozess mit einem alten Zertifikat auffällt. Siehe Kommandos und Metriken) |
my.tls.order.attempts |
Zähler | host, result (issued / failed). Eines pro Bestellung eines Zertifikats bei der ACME-Zertifizierungsstelle, durch den Prozess, der sie aufgegeben hat, my tls renew und my tls revoke eingeschlossen |
my.tls.order.consecutive_failures |
Gauge | host (die Bestellungen seit dem aktuellen Zertifikat des Hosts, die keines erbracht haben: die Zahl, die die Wartezeit vor der nächsten Bestellung bestimmt) |
my.tls.rounds |
Zähler | Keine. Eines pro Runde des Zertifikatsmanagers über seine Hosts mit tls = acme; eine Zahl, die aufhört zu wachsen, heißt, der Manager ist stehen geblieben |
Health Checks (/healthz, /readyz, /health/live, /health/ready) werden nicht gemessen. Kein Label enthält eine entfernte Domain, ein Konto, eine URL oder eine Client-IP.
my.queue.*, my.instance.*, my.media.stored_bytes, my.db.size, my.federation.instances und my.billing.import.failing sind Werte der ganzen Instanz: Jeder Prozess meldet denselben Wert aus einem Snapshot, der im Key-Value-Store aufbewahrt wird.
Systemmetriken
Abschnitt betitelt „Systemmetriken“Metriken über den Prozess, die Go-Laufzeit und Verbindungen zu Ressourcen werden über denselben metrics_exporter exportiert.
CPU, Speicher, Instanzzahl und eingehende Anfragen des Containers überlassen wir den Metriken der Plattform; diese hier decken die Sättigung innerhalb des Prozesses ab, die die Plattform nicht sehen kann.
Verwende sie nicht, um Skalierung auszulösen; verwende sie für Alarme und zur Abschätzung der Instanzobergrenze.
| Metrik | Art | Labels |
|---|---|---|
go.memory.used, go.memory.limit, go.memory.gc.goal |
Gauge, Bytes | Nur go.memory.used hat go.memory.type (stack / other). go.memory.limit erscheint nur, wenn GOMEMLIMIT gesetzt ist |
go.memory.allocated, go.memory.allocations |
Zähler | Keine |
go.goroutine.count, go.processor.limit, go.config.gogc |
Gauge | Keine |
go.schedule.duration, go.memory.gc.pause.duration |
Histogramm, Sekunden | Keine (das Warten vom Ausführbar-Werden bis zum Laufen und GC-Pausen) |
go.memory.gc.cycles |
Zähler | Keine |
process.cpu.time |
Observable Counter, Sekunden (Summe seit dem Start) | cpu.mode (user / system) |
process.memory.usage |
Gauge, Bytes | Keine (residenter Speicher, RSS) |
process.unix.file_descriptor.count, my.process.file_descriptor.limit |
Gauge | Keine (offene Dateideskriptoren und das Limit) |
process.uptime |
Gauge, Sekunden | Keine |
db.client.connection.count |
Gauge | db.client.connection.pool.name (postgres / sqlite), db.client.connection.state (idle / used) |
db.client.connection.max |
Gauge | db.client.connection.pool.name |
db.client.connection.wait_time, my.db.client.connection.waits, db.client.connection.timeouts |
Observable Counter (Summe seit dem Start; Sekunden oder Anzahl) | db.client.connection.pool.name. timeouts gibt es nur bei PostgreSQL |
my.adapter.operation.duration |
Histogramm, Sekunden | 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 (valkey-Verbindungen und stream.<stream>-Abonnenten) |
my.adapter.reconnects |
Zähler | my.adapter |
http.client.request.duration |
Histogramm, Sekunden | 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 und so weiter), error.type (forbidden_destination ist eine Ablehnung durch den SSRF-Schutz) |
http.client.open_connections |
UpDownCounter | Keine |
my.readiness.failures |
Zähler | Keine |
my.readiness.shared |
Zähler | Keine. Eine pro Bereitschaftsanfrage, die das Ergebnis einer bereits laufenden Prüfung übernommen hat, statt eine zu starten |
my.http.origin_refused |
Zähler | Keine. Eine pro Anfrage, die abgelehnt wurde, weil sie nicht über das CDN kam (origin_secret). Proben der Adresse des Origins lassen sie langsam steigen; ein Sprung, während der Verkehr aufhört, heißt, das CDN sendet den Header nicht mehr. Der Wartungsmodus misst nichts, sodass nur sein Access-Log sie zeigt |
- Go-Laufzeitmetriken (
go.*) werden nur vonprometheusundotlpexportiert. Mitemfschreibt ein periodischer Snapshot-Job die Gauges und Observable Counter von Prozess und Verbindungspool. - Pool-Wartezeiten und CPU-Zeit sind Observable Counter: Der Pool und der Kernel halten Summen seit dem Start, die zum Erfassungszeitpunkt gelesen werden. In Prometheus sind es
_total-Zähler (etwaprocess_cpu_time_seconds_total), in OTLP monotone Summen, und ihr Wachstum siehst du mit PromQLrate().emfhat keine Summenzähler, daher schreibt es den Zuwachs seit dem vorherigen Schreiben (addiere sie mit der CloudWatch-Statistik Sum). - Das
claimder Queue wird nur gemessen, wenn es einen Job nimmt oder fehlschlägt. Das Polling eines wartenden Workers zeichnet nichts auf. db.client.connection.pending_requestswird nicht exportiert: Die Statistiken von pgx unddatabase/sqlmelden nicht, wie viele warten, daher vertreten die Zahl und die Dauer der Wartezeiten sie.- Alarmiere auf das Verhältnis der Summe von
go.memory.usedzugo.memory.limitund auf das Wachstum vondb.client.connection.wait_time(das Pool-Limit wird erreicht).
Speicherlimit (GOMEMLIMIT)
Abschnitt betitelt „Speicherlimit (GOMEMLIMIT)“GOMEMLIMIT ist eine Umgebungsvariable der Go-Runtime, die der Betreiber setzt; die Anwendung wählt sie nicht.
Ohne sie läuft Go mit seinem Standard (kein Limit), und der Heap sammelt nicht eifrig, wenn er sich dem Speicherlimit des Containers nähert.
Setze sie bei Setups mit einem Container-Speicherlimit (Cloud Run, ECS, Kubernetes) auf etwa 90 % dieses Limits (zum Beispiel GOMEMLIMIT=460MiB für einen Container mit 512 MiB).
Setze GOMAXPROCS nicht: Der Standard von Go folgt dem CPU-Limit des Containers.
Die Einstellung traces_exporter (Standard none) exportiert verteilte Traces. Die zugehörigen Einstellungen stehen in der Konfigurationsreferenz.
| Span | Name | Attribute |
|---|---|---|
| HTTP-Anfrage (Server) | <method> <http.route> (<method> bei einer Anfrage, die keine Route erreichte) |
http.request.method, http.route, http.response.status_code, my.surface. Ein 5xx ist ein Fehler |
| Job-Ausführung (Consumer) | Der Job-Typ (my.job.type) |
my.job.type, my.job.attempt, my.outcome. Jede Wiederholung ist ein eigener Span |
| Transaktion | my.db.transaction |
db.system.name. Jede Wiederholung ist ein eigener Span |
| Abfrage (Client) | Der sqlc-Abfragename (etwa InsertJobs; sonst das erste Wort des SQL, etwa BEGIN) |
db.system.name, db.operation.name |
Zustellung (my.delivery) |
my.delivery |
activity.type, my.outcome |
| Ausgehendes HTTP (Client) | <method> |
http.request.method, server.address (nur der Hostname des Ziels), http.response.status_code. Ein 4xx oder 5xx ist ein Fehler |
Ein fehlgeschlagener Span hat error.type (ein endlicher Name wie timeout oder ein Statuscode). Attribute enthalten nie Konto-, Beitrags- oder Job-IDs, URLs, Pfade oder Queries, Client-IPs, User-Agent-Werte, SQL-Text oder Fehlerstrings.
server.address überlässt die Hostnamen entfernter Server dem Empfänger, sodass du entscheidest, wie lange der Empfänger sie behält und wer sie sehen kann. Health-Checks und die von origin_secret abgelehnten Anfragen erzeugen keinen Span.
- Eine Job-Ausführung ist kein Kind des Spans, der sie eingereiht hat (meist eine HTTP-Anfrage). Sie ist die Wurzel eines neuen Traces mit einem Link zum einreihenden Span. Folge in einem Viewer dem Link vom Trace der Anfrage.
- Ein eingehendes
traceparentwird nur zum Parent, wenn der verbindende Peer intrusted_proxiessteht und, beiorigin_secret, die Anfrage das Geheimnis trägt. Andernfalls wird es verworfen und ein neuer Trace beginnt.tracestatewird immer verworfen. Ausgehendes HTTP (Föderation, WebFinger, Medien, Web Push und so weiter) trägt keintraceparent. - Sampling: Eine Anfrage wird aufgezeichnet, wenn ihr Parent über einen vertrauenswürdigen Proxy aufgezeichnet wurde oder wenn das Link-Ziel eines Jobs aufgezeichnet wurde; sonst wird sie im Verhältnis
traces_sample_ratio(Standard 0,01) aufgezeichnet. Das Senken des Verhältnisses lässt nie Jobs, die eine aufgezeichnete Anfrage fortsetzen, ohne ihren Trace zurück.
| Ziel | Einstellungen | Pfad |
|---|---|---|
| Standard, kleines Self-Hosting | traces_exporter = none |
Es werden keine Spans exportiert. Folge request_id und job_id in den Logs. Liefert ein vertrauenswürdiger Proxy ein traceparent, werden dessen trace_id und span_id zu den Logs hinzugefügt |
| Self-Hosting (Jaeger, Tempo, ein OpenTelemetry Collector und so weiter) | traces_exporter = otlp, traces_flush = batch |
Über OTLP/HTTP an den Empfänger unter OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (oder OTEL_EXPORTER_OTLP_ENDPOINT, Standard http://localhost:4318) gesendet. Authentifizierungs-Header gehören in OTEL_EXPORTER_OTLP_HEADERS. Um Fehler und langsame Traces zuverlässig zu behalten, nutze das Tail-Sampling des Collectors |
| Google Cloud (Cloud Run) | none oder otlp mit unit, um Traces zu aktivieren |
Siehe unten |
| AWS (ECS) | none oder otlp mit batch, um Traces zu aktivieren |
Siehe unten |
Cloud Run
Abschnitt betitelt „Cloud Run“Auch mit none teilen sich der Anfrage-Trace, den Cloud Run automatisch erstellt, und die trace_id in den Logs dieselbe ID (wenn du der Verbindung vor Cloud Run mit trusted_proxies vertraust).
Ob Cloud Run das traceparent öffentlicher Anfragen immer überschreibt, ist noch nicht verifiziert.
Die Logs haben nicht die Form des Trace-Felds, das Cloud Logging erkennt (logging.googleapis.com/trace).
Um Anwendungs-Spans an Cloud Trace zu senden, betreibe einen OpenTelemetry Collector als Sidecar im selben Dienst. Der Server hält keine Google-Zugangsdaten; der Sidecar sendet mit Application Default Credentials an den OTLP-Endpunkt von Cloud Trace.
- Server (der Ingress-Container):
MY_TRACES_EXPORTER=otlp,MY_TRACES_FLUSH=unit,OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 - Sidecar: ein OpenTelemetry Collector, der mit einem
otlp-Receiver über HTTP auflocalhost:4318empfängt und mit demgooglecloud-Exporter oder demotlphttp-Exporter sendet (https://telemetry.googleapis.com, mit der Erweiterunggoogleclientauth). Gib dem Service-Konto die Berechtigung, in Cloud Trace zu schreiben. - Am Ende jeder aufgezeichneten Anfrage oder jedes Jobs sendet
unitdie bisherigen Spans an den Sidecar, bevor es zurückkehrt. Damit der Sidecar sie senden kann, während keine CPU zugeteilt ist, nutze für ein Setup mit aktivierten Traces serverbasierte Abrechnung. - Die Kosten sind die Ressourcen des Sidecars und das Span-Volumen (Preise von Cloud Trace). Wähle das Verhältnis mit
traces_sample_ratio.
AWS ECS
Abschnitt betitelt „AWS ECS“Um an X-Ray zu senden, betreibe den AWS Distro for OpenTelemetry (ADOT) Collector als Sidecar-Container in jedem Task. Der Server hat keine SigV4-Signierung; der Collector signiert mit der Task-Rolle und sendet an X-Ray. Das Modul mycroblog-aws von der OpenTofu-Bereitstellung erledigt all das standardmäßig (observability.traces = "x-ray"); der Rest dieses Abschnitts ist für eine eigene Task-Definition.
- Server:
MY_TRACES_EXPORTER=otlp,OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:4318/v1/tracesund das standardmäßigeMY_TRACES_FLUSH=batch, da der Prozess weiterläuft. - Collector: ein per Version festgelegtes Image, etwa
public.ecr.aws/aws-observability/aws-otel-collector:v0.50.0, mit seiner Konfiguration in der VariableAOT_CONFIG_CONTENT: einotlp-Receiver über HTTP auf127.0.0.1:4318und derawsxray-Exporter. Der OTLP-Endpunkt von X-Ray (https://xray.<region>.amazonaws.com/v1/traces, über einenotlphttp-Exporter mit der Erweiterungsigv4auth) funktioniert auch, braucht aber eingeschaltete CloudWatch Transaction Search für das Konto. - Gib der Task-Rolle
xray:PutTraceSegments, womit derawsxray-Exporter schreibt. Der Server sampelt die Traces selbst, daher braucht der Collector keine Sampling-Regeln von X-Ray. - Gib dem Collector einen Anteil des Tasks:
mycroblog-awsgibt ihm 32 CPU-Einheiten und 128 MiB und dem Server den Rest, mitGOMEMLIMITbei 90 % dieses Rests. Lass den Container des Servers vom Start des Collectors abhängen, damit der Collector nach dem Server anhält und seine letzten Spans erhält. - Die Kosten sind der Anteil des Sidecars an den Ressourcen des Tasks und die Zahl der Traces, die X-Ray aufzeichnet (die ersten 100.000 pro Monat sind kostenlos). Das standardmäßige
traces_sample_ratiovon 0,01 zeichnet bei 100.000 Anfragen pro Tag etwa 30.000 Traces pro Monat auf.
Profile
Abschnitt betitelt „Profile“Die Systemmetriken sagen, wie viel Speicher und CPU ein Prozess nutzt; ein Profil der Go-Laufzeit sagt, was sie verbraucht.
pprof_listen nennt die Adresse eines Listeners, der die Profile unter /debug/pprof/ ausliefert, für jede role. Es ist standardmäßig leer, was keinen Listener öffnet.
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 statisticsDer Listener hat keine Authentifizierung, ein Profil zeigt das Innere des Prozesses, und eines zu erstellen kostet CPU: Halte ihn auf Loopback und erreiche ihn über einen Tunnel (ssh -L 6060:127.0.0.1:6060 <host>, kubectl port-forward), und setze ihn zurück, wenn du fertig bist.
Das Heap-Profil deckt nur den Go-Heap ab. Der residente Speicher des Prozesses enthält auch die gelesenen Seiten der Binärdatei, die Stacks und die eigenen Strukturen der Laufzeit; die Speicherstatistiken geben diese an.
Die Mutex- und Block-Profile sind leer: Der Server sampelt sie nicht.
Den Server stoppen
Abschnitt betitelt „Den Server stoppen“Bei SIGTERM oder SIGINT fährt der Server geordnet herunter.
- Er nimmt keine neuen Verbindungen und keine Jobs mehr an.
- Er wartet bis zu 25 Sekunden, bis laufende Anfragen und laufende Jobs fertig sind.
- Nach 25 Sekunden bricht er den Kontext der übrigen Anfragen und Jobs ab und schließt Verbindungen. Danach gibt er einem abgebrochenen Job bis zu 3 weitere Sekunden, sein Ergebnis zu verzeichnen, und endet mit Exit-Code 1 (insgesamt höchstens 28 Sekunden, innerhalb der standardmäßigen Kulanzfrist von 30 Sekunden bei Kubernetes und ECS). Ein abgebrochener Job wird wiederholt. Ein Job, der innerhalb dieser 3 Sekunden nicht stoppt oder mittendrin beendet wird, wird aufgegeben und von einem Worker wieder aufgenommen, wenn sein Lease abläuft, er kann also zweimal laufen.
Ein Panic in einer der Hintergrundaufgaben des Servers löst dasselbe Herunterfahren aus, damit der Server nie in einem kaputten Zustand weiterläuft.
Die Logzeile serve failed nennt die Aufgabe, und der Prozess endet mit Exit-Code 1, damit die Plattform oder der Prozessmanager ihn neu startet.
Starte für Arbeiten an der Datenbank, dem Key-Value-Speicher oder der Warteschlange statt eines Stopps im Wartungsmodus neu (MY_MAINTENANCE=true). Siehe Wartung.
Die Job-Queue und fehlgeschlagene (tote) Jobs
Abschnitt betitelt „Die Job-Queue und fehlgeschlagene (tote) Jobs“Jobs listet jeden Job-Typ auf: was er tut, was ihn startet, wie er wiederholt wird und was eine erneute Ausführung bewirkt.
Die Admin-Seite für Jobs (Administration → Jobs, /admin/jobs, Berechtigung manage_jobs) hat drei Seiten:
- Queue-Zustand (
/admin/jobs): zuerst, wie viele Jobs fehlgeschlagen sind, mit einem Link dorthin; die Zahl pro Zustand (in der Queue, laufend, wartet auf Wiederholung, fehlgeschlagen), jeweils mit Link zu den Jobs in diesem Zustand; wie lange der älteste fällige Job gewartet hat; und eine Tabelle der Zahlen pro Typ und Zustand mit der Zeit, die jeder Typ einen Job warten lässt. - Jobliste (
/admin/jobs/list): die Jobs, die nicht abgeschlossen sind (in der Queue, laufend, wartet auf Wiederholung), oder die eines Zustands und eines Typs, eine Seite nach der anderen, mit dem Typ, der Zahl der Versuche, der Zeit, zu der er fällig ist oder fehlschlug, dem Zustand und der ersten Zeile des letzten Fehlers. - Ein Job (
/admin/jobs/<id>, vom Typ in der Liste aus): Erneut ausführen für einen fehlgeschlagenen Job, was vorher nachfragt, da ein Lauf wiederholen kann, was der Job vor dem Fehlschlag getan hat; jede Angabe des Jobs, seine ID und Schlüssel jeweils mit einer Kopieren-Schaltfläche; sein letzter Fehler und seine Payload, jeweils mit einer Kopieren-Schaltfläche; eine Tabelle der erfolglosen Versuche, neueste zuerst (Ergebnis, Endzeit, Worker und der Fehler); und ein Link zu den Jobs seines Typs.
Die Admin-API ist 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 und POST /api/v1/admin/jobs/{id}/retry.
Ein abgeschlossener Job ist nicht mehr in der Queue, daher wird seine Seite nicht gefunden.
- Wartende, laufende und auf Wiederholung wartende Jobs lassen sich nur für die Queues auflisten, deren Jobs der Server hält:
queue = db,queue = cloudtasks(die Jobs liegen auch in der Datenbank) undqueue = inline. Fehlgeschlagene Jobs und der Versuchsverlauf liegen für jede Queue in der Anwendungsdatenbank, sodass sie sich immer auflisten lassen. - Der Versuchsverlauf hält nur erfolglose Versuche (Wiederholungen und den Versuch, der schließlich fehlschlug). Verfolge einen erfolgreichen Lauf über die strukturierte
job-Logzeile (diejob_idträgt). Der Verlauf wird von der stündlichen Bereinigung entfernt, sobald seit dem Ende des Versuchsjob_attempt_retention(Standard 30 Tage; siehe die Einstellung) verstrichen ist. Der Verlauf enthält weder Payload noch Handler-Log, und eine Fehlermeldung wird auf ihre ersten 2.000 Bytes gekürzt. Job-Handler halten E-Mail-Adressen, IP-Adressen, Tokens und Beitragstexte aus Fehlermeldungen heraus. Für eine auf E-Mail-Job-Typen beschränkte Ansicht siehe E-Mails versenden.
Ein Job, bei dem der Handler entschieden hat, dass er endgültig fehlschlug, und ein Job, der seine Wiederholungen aufgebraucht hat, wird in der Datenbank-Queue (queue = db und queue = cloudtasks) zu einem toten Job.
my job listet, wiederholt und löscht sie. Der Zustand „Fehlgeschlagen“ der Jobseite und die Admin-API können sie ebenfalls auflisten und wiederholen.
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- Wartet bereits ein Job mit demselben Idempotenzschlüssel, vertritt dieser Job den wiederholten. Job-Handler sind idempotent, daher ist es sicher, denselben Job beliebig oft zurückzulegen.
- Eine unbekannte ID wird ausgegeben, und das Kommando endet mit Exit-Code 1; die anderen IDs werden trotzdem verarbeitet. Exit-Code 2 bedeutet einen Aufruffehler.
- Ein toter Job, den niemand wiederholt, wird von der stündlichen Bereinigung entfernt, sobald seit dem Fehlschlag
dead_job_retention(Standard 30 Tage; siehe die Einstellung) verstrichen ist. - Tote Jobs von
queue = inlineliegen im Speicher des Serverprozesses, daher kannmy jobsie nicht bearbeiten (Exit-Code 1).
Worker nach Job-Typ aufteilen
Abschnitt betitelt „Worker nach Job-Typ aufteilen“Standardmäßig führt jeder Worker jeden Job-Typ aus, in der Reihenfolge, in der die Jobs fällig wurden, einen Job gleichzeitig pro Prozess (siehe Mehrere Jobs gleichzeitig ausführen). Ein Schwall von Zustellungen verzögert dann E-Mail und Benachrichtigungen, und jeder Worker, den du hinzufügst, teilt seine Zeit auf alle auf. Mit queue = db kannst du einigen Typen eigene Worker geben:
worker_job_types: Dieser Prozess führt nur diese Typen aus.worker_job_types_except: Dieser Prozess führt jeden Typ außer diesen aus.
Jede ist eine kommagetrennte Liste von Job-Typen (my job types gibt sie aus; my config check lehnt einen Namen ab, der keinen trifft), geschrieben als Name (federation.deliver) oder Präfix (federation.*). Setze sie pro Prozess, zum Beispiel mit MY_WORKER_JOB_TYPES. Du kannst nicht beide in einem Prozess setzen. Ein Name oder Präfix, der keinen Job-Typ trifft, hält den Start an, was auch einen Typ erfasst, den ein Release umbenannt hat, oder einen Typ, den es nur mit einer Einstellung gibt, die du nicht gesetzt hast. Sie funktionieren nicht mit role = web oder mit queue = cloudtasks oder inline, wo der Start ebenfalls fehlschlägt: Dort nennt ein Signal den auszuführenden Job, ein Prozess kann seine Jobs also nicht wählen.
Beim Start protokolliert ein Prozess mit einer der Einstellungen die Typen, die er überspringt. Er kann die Einstellungen der anderen Prozesse nicht sehen, stelle also sicher, dass irgendein Prozess jeden Typ ausführt, sonst warten diese Jobs ewig. Periodische Bereinigung und E-Mail sind ebenfalls Job-Typen. Jeder Prozess startet weiterhin die periodischen Jobs; welcher Prozess sie ausführt, hängt von diesen Einstellungen ab.
Entscheide anhand der Metriken, was du aufteilst, nicht anhand der Typnamen. my.job.wait (Prometheus: my_job_wait_seconds) zeigt, wie lange Jobs nach Typ gewartet haben, bevor sie starteten:
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])) zeigt die Worker-Zeit, die jeder Typ verbraucht, und damit etwa auch, wie viele Prozesse er braucht. Ein Typ, der den Großteil der Zeit verbraucht und die anderen warten lässt, ist der, den du verschieben solltest.
Drei übliche Aufteilungen, mit einer Prozesszahl deiner Wahl:
| Aufteilung | Prozesse |
|---|---|
| Zustellungen daran hindern, den Rest zu verzögern | worker_job_types = federation.fanout,federation.deliver für die Zustellungen und worker_job_types_except = federation.fanout,federation.deliver für alles andere. Füge der ersten Gruppe bei einem Schwall Prozesse hinzu. |
| Ein Such-Backend daran hindern, den Rest zu verzögern | worker_job_types = search.* für die Such-Jobs und worker_job_types_except = search.* für alles andere (Die Suche daran hindern, andere Jobs zu verzögern). |
| E-Mail und Benachrichtigungen schnell halten | 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 für diese und ein Worker ohne Einstellung für alles, der auch bei diesen Typen hilft, wenn er frei ist. Lass die Typen von Einstellungen weg, die du nicht gesetzt hast, sonst hält der Start an: notification.push braucht vapid_private_key, und notification.email, notification.moderator_email und notification.supporter_email brauchen mail. Siehe Jobs, die von Einstellungen abhängen. |
Ein Präfix wie identity.* ist das Code-Modul, dem die Typen gehören, keine Art von Arbeit. identity.* erfasst auch Datenexporte, Importe und Ablauf-Jobs und verfehlt instance.notify_announcement und voice.notify_started, daher nennt eine Aufteilung für eine Art von Arbeit jeden Typ.
Halte diese zusammen, auf Workern mit derselben Einstellung. Jobs mit einem Reihenfolgeschlüssel laufen der Reihe nach, was auch immer ihr Typ ist. Wenn also nichts den früheren Job ausführt, wartet auch der spätere, und wenn sich die Gruppe des früheren Jobs staut, wartet der spätere auf sie:
| Typen | Was sie in Reihenfolge halten |
|---|---|
federation.fanout, federation.deliver |
Die Zustellungen eines Likes und seines Undo |
voice.apply_media_event, voice.apply |
Die Ereignisse eines Voice-Raums |
supporters.sync, supporters.command |
Die Änderungen eines Abos |
Beim Upgrade:
- Ein Prozess mit
worker_job_typesführt die Typen nicht aus, die eine neue Version hinzufügt. Prüfe die Release Notes und die übersprungenen Typen im Log. Ein Prozess mitworker_job_types_exceptführt sie aus, was ihn zum sichereren Ort für alles andere macht. - Ein umbenannter Typ hält den Start an, lies also zuerst die Release Notes.
Um eine Aufteilung auszurollen, starte zuerst die neuen Worker und füge dann die Einstellung den alten hinzu. Um sie zurückzunehmen, entferne die Einstellung bei einer Gruppe, bevor du die andere stoppst. Jobs bleiben in der Warteschlange, nichts geht also verloren, und ein Typ, den eine Weile niemand ausführt, wartet nur.
Einen Typ erkennen, den nichts ausführt. Die Jobs eines solchen Typs warten, daher wächst my.queue.oldest_ready_age für diesen Typ, und die Alarme MyQueueBacklog und MyQueueStalled schlagen für den Typ an, der am längsten wartet. Um zu sehen, welcher es ist, oder um pro Typ zu alarmieren:
max by (my_job_type) (my_queue_oldest_ready_age_seconds) > 1800Die Admin-Seite für Jobs zeigt dieselbe Wartezeit pro Typ. Ein Worker mit einer der Einstellungen lässt auch einen Job in Ruhe, dessen Typ gar keinen Handler hat (er zählt in der Metrik unter other); gibt es also keinen Worker ohne Einstellung, wartet ein solcher Job, statt zu einem toten Job zu werden.
Mehrere Jobs gleichzeitig ausführen
Abschnitt betitelt „Mehrere Jobs gleichzeitig ausführen“worker_job_concurrency legt fest, wie viele Jobs ein Prozess gleichzeitig ausführt, von 1 bis 128. Es funktioniert mit queue = db; bei Cloud Tasks entscheidet die Plattform. Der Standard ist ein Job zugleich, und eine Einstellung von 1 verhält sich genauso.
Erhöhe es für Jobs, die ihre Zeit mit dem Warten auf andere Server verbringen, etwa federation.deliver. Diese brauchen wenig Speicher und wenige Datenbankverbindungen pro Job, sodass ein Prozess die Arbeit vieler erledigt: In einem lokalen Test, in dem ein Job nur 200 ms auf eine Antwort wartete, leistete ein Prozess mit 32 Slots so viel wie 32 Prozesse mit je einem Slot, bei einem kleinen Teil des Speichers. Diese Jobs taten nichts anderes, miss also deine eigene Instanz. Kombiniere es mit worker_job_types und gib jeder Art von Job einen Prozess mit seiner eigenen Zahl.
Behalte diese Grenzen im Blick:
- Datenbankverbindungen: Ein Job braucht eine Verbindung, um übernommen zu werden, für seine eigene Arbeit und um sein Ergebnis aufzuzeichnen. Die Einstellung muss unter dem Pool-Maximum liegen, sonst startet der Server nicht. Das Maximum ist
pool_max_connsindatabase_url, standardmäßig das Größere aus 4 und der CPU-Anzahl, sodass eine vCPU 3 erlaubt, bis du es erhöhst. Prüfe, dass deine Datenbank oder dein Connection Pooler die Verbindungen all deiner Prozesse annimmt. - SQLite: Es schreibt eine Transaktion zugleich, und in einem lokalen Test lief es bei 128 langsamer als bei 32.
- CPU-intensive Jobs: Slots teilen sich CPU und Speicher eines Prozesses.
media.processwartet standardmäßig mit einem Limit von der Hälfte der CPUs auf seinen Zug, und das Warten zählt gegen die 5-Minuten-Lease des Jobs, sodass ein Prozess vollermedia.processüber die Lease hinauslaufen und von vorn beginnen kann. Gib solchen Jobs einen Prozess mit wenigen Slots. - Ein Server zugleich: Ein Prozess baut höchstens 8 Verbindungen zu einem einzelnen Host auf, sodass ein Prozess an einen einzelnen Server nicht schneller zustellt, als 8 Verbindungen erlauben, egal wie viele Slots er hat. Gehen die meisten Zustellungen an wenige große Server, helfen mehr Prozesse, wo mehr Slots es nicht tun.
- Ein hängender Server hält Slots: Slots, die auf einen langsamen Server warten, sind für andere Jobs nicht frei, halte Zustellungen also getrennt von E-Mails und Benachrichtigungen.
- Deployments verbrauchen Versuche: Wenn der Server anhält, werden Jobs, die nach
ShutdownTimeout(standardmäßig 25 Sekunden) noch laufen, abgebrochen, und jeder abgebrochene Job verbraucht einen Versuch. Je mehr Slots langsame Jobs ausführen, desto mehr Versuche verbraucht jedes Deployment. Ein abgebrochener Job, dessen Ergebnis nicht rechtzeitig aufgezeichnet wird, wartet auf den Ablauf seiner Lease, bevor er wieder läuft. - Ein Absturz nimmt jeden Slot mit: Geht dem Prozess der Speicher aus, warten alle seine Jobs auf den Ablauf ihrer Leases.
Um zu entscheiden, ob du es erhöhen solltest, lies my.job.wait pro my.job.type: Warten Jobs eines Typs lange, während my.job.duration überwiegend aus Warten auf andere Server besteht und CPU und Speicher niedrig bleiben, sollten mehr Slots helfen. Bleiben die Wartezeiten nach dem Erhöhen hoch, sieh dir die Datenbankverbindungen und das Host-Limit oben an, bevor du es erneut erhöhst.
Solange kein Job fällig ist, pollt ein Slot und die anderen warten, sodass ein untätiger Prozess die Datenbank so viel kostet wie ein Prozess mit einem Job.
Auf eine Datenbankverbindung warten
Abschnitt betitelt „Auf eine Datenbankverbindung warten“Mit database = postgres wartet jede Anweisung und Transaktion zuerst auf eine freie Verbindung des Pools des Prozesses.
database_acquire_timeout (Standard 60s) begrenzt dieses Warten und nichts sonst: Eine lange Query oder
Transaktion, die ihre Verbindung bereits hat, läuft weiter, so lange sie auch dauert. 0 wartet ohne Limit. SQLite hat kein Limit an Verbindungen, auf die gewartet werden könnte, daher schlägt das Setzen dort beim Start fehl.
Wenn das Warten abläuft:
- Eine Anfrage wird mit
503 Service UnavailableundRetry-After: 5beantwortet. - Ein Job läuft 30 Sekunden später erneut und verbraucht keinen Versuch, eine ausgelastete Datenbank macht also nie einen Job zu einem toten Job.
- Die Metrik
db.client.connection.timeoutszählt es, und der AlarmMyDBPoolWaitingschlägt an.
Der Standard ist das Schreib-Timeout des Servers von 60 Sekunden: Eine Anfrage, die länger gewartet hat, könnte ihre Antwort ohnehin nicht mehr senden, der Standard lässt also keine Anfrage scheitern, die noch hätte gelingen können. Wähle einen Wert danach, wie dein Server läuft:
- Senke ihn, um schnell Last abzuwerfen: Clients wiederholen nach
Retry-After, statt ihre Anfragen offen zu halten. Halte ihn länger als deine langsamsten normalen Transaktionen, sonst beginnt ein kurzer Schwall mit503zu antworten. - Dimensioniere zuerst den Pool. Ein Prozess braucht etwa so viele Verbindungen, wie er Arbeit gleichzeitig ausführt.
pool_max_connsindatabase_urlist standardmäßig das Größere aus 4 und der CPU-Zahl, und alle Prozesse zusammen müssen unter dem Verbindungslimit der Datenbank bleiben.- Mit
worker_job_concurrencywarten auch Slots auf Verbindungen, und die Einstellung muss unter dem Pool-Maximum bleiben. - Auf Cloud Run nimmt ein Dienst standardmäßig 80 gleichzeitige Anfragen pro Server-Instanz an. Bei einem Pool von 4 staut sich hier ein Schwall langsamer Anfragen, erhöhe also
pool_max_conns, senke die Nebenläufigkeit des Dienstes oder beides.
- Mit
- Häufige
503oderdb.client.connection.timeoutsbedeuten, dass der Pool zu klein ist oder Queries langsamer wurden; ein längeres Timeout verbirgt das nur. FolgeMyDBPoolSaturated.
Cloud Tasks
Abschnitt betitelt „Cloud Tasks“Auf Cloud Run bereitstellen richtet alles Folgende mit OpenTofu-Modulen ein.
Mit queue = cloudtasks bleiben die Jobs in der Datenbank (database = postgres), und Google Cloud Tasks weckt den Server nur für jeden von ihnen auf:
- Für jeden Job, den er speichert, wiederholt oder zurücklegt, erstellt der Server eine Task in
queue_cloudtasks_queue, sobald die Transaktion committet. Die Task ruftPOST {queue_cloudtasks_url}/_internal/jobszu dem Zeitpunkt auf, an dem der Job fällig ist, mit der ID des Jobs als Body und einem OIDC-ID-Token vonqueue_cloudtasks_service_account. Ein Job, der mehr als 30 Tage im Voraus fällig ist, wird bei 30 Tagen signalisiert und erneut, wenn diese Task eintrifft. - Der Prozess, der die Task empfängt, führt den Job aus und antwortet mit
204, sobald sein Ergebnis erfasst ist, auch wenn der Job bereits lief oder nicht fällig ist. Ein Job, der fehlschlägt, wird vom Server zu seinem nächsten Versuchszeitpunkt wiederholt, nicht von Cloud Tasks. Cloud Tasks wiederholt eine Task nur, wenn die Antwort5xxist (die Datenbank war nicht erreichbar) oder401(ein Token, das der Server ablehnte), daher braucht seinretryConfigkeine Feinabstimmung. - Kein Prozess fragt die Tabelle ab, und kein Prozess führt die periodischen Jobs von selbst aus. Erstelle einen Cloud-Scheduler-Job, der
POST {queue_cloudtasks_url}/_internal/tickjede Minute (* * * * *) mit einem OIDC-Token desselben Dienstkontos aufruft (und mit der Audience vonqueue_cloudtasks_audience, wenn gesetzt). Jeder Tick reiht die periodischen Jobs ein, deren Zeitraum gekommen ist, einmal für die ganze Instanz (die Zeiträume werden im KV beansprucht, daher musskvdbodervalkeysein), und signalisiert erneut die Jobs, die seit über 2 Minuten fällig sind, ohne gelaufen zu sein, was ein verlorenes Signal behebt. /_internal/jobsund/_internal/tickwerden von den Prozessen mitrole = alloderworkerbedient und akzeptieren nur ein von Google signiertes Token fürqueue_cloudtasks_service_accountmit einer verifizierten E-Mail, dessen einzige Audiencequeue_cloudtasks_audienceoder, standardmäßig, die aufgerufene URL ist. Jede andere Anfrage ist ein401.- Eine Zustellung führt einen Job aus, höchstens für die 5-Minuten-Lease. Halte
queue_cloudtasks_dispatch_deadline(Standard 10 Minuten) und das Anfrage-Timeout des Cloud-Run-Dienstes länger als das. - Das eigene Dienstkonto des Servers braucht
roles/cloudtasks.enqueuerauf der Queue undroles/iam.serviceAccountUseraufqueue_cloudtasks_service_account. Es authentifiziert sich mit Application Default Credentials.
Wie spät periodische Jobs laufen
Abschnitt betitelt „Wie spät periodische Jobs laufen“Ein periodischer Job läuft bis zu einen Zeitraum seines Triggers nach seiner Zeit, plus die Zeit, die die Plattform zum Starten braucht. Das
bestimmt, wie spät die Erinnerungen und Beginn-Benachrichtigungen von Veranstaltungen ankommen und ihre Sprachchat-Räume öffnen, da gathering.tick sie startet: Eine Erinnerung
kommt bis zum Intervall der Tabelle zu spät. Die Werte sind das, was der Scheduler-Code und der Trigger jeder Plattform ergeben; sie wurden
nicht auf einem laufenden Server gemessen.
| Plattform | Was die periodischen Jobs startet | Erwartete Verzögerung einer Erinnerung oder eines Beginns einer Veranstaltung |
|---|---|---|
Self-Hosting und Docker Compose (queue = db) |
Der Scheduler in jedem Prozess mit role = all oder worker prüft einmal pro Minute, ab dem Start des Prozesses, und reiht jeden Job einmal pro Zeitraum für den ganzen Server ein |
Bis zu 1 Minute, plus etwa eine Sekunde, bis ein Worker den Job aufnimmt |
AWS ECS Fargate (queue = db) |
Derselbe Scheduler, in den Worker-Tasks | Bis zu 1 Minute, plus etwa eine Sekunde |
Cloud Run (queue = cloudtasks) |
Cloud Scheduler ruft /_internal/tick nach seinem Zeitplan auf, standardmäßig * * * * * (jede Minute); Cloud Tasks weckt dann den Server für jeden Job |
Bis zu 1 Minute, plus der Start einer Instanz, wenn keine läuft (ein Kaltstart, meist einige Sekunden). Bei einem längeren tick_schedule, etwa */10 * * * *, bis zu diesem Intervall |
| AWS Lambda | my hat keine Lambda-Bereitstellung; betreibe es auf AWS auf ECS Fargate |
— |
Eine Erinnerung, die ankäme, nachdem ihre Veranstaltung begonnen hat, wird nicht gesendet, ebenso wenig eine Beginn-Benachrichtigung, nachdem die Veranstaltung endete. Bei einem Tick, der länger als 5 Minuten ist, können daher die kürzesten Erinnerungen verloren gehen.
Job-Typen auf eigene Queues leiten
Abschnitt betitelt „Job-Typen auf eigene Queues leiten“Mit queue = cloudtasks kann ein Worker die Jobs, die er ausführt, nicht wählen: worker_job_types funktioniert nur mit queue = db, weil die Plattform entscheidet, wer ein Signal erhält.
Um einigen Job-Typen eigene Kapazität zu geben, sende ihre Signale an eine eigene Queue und lege die Kapazität dieser Queue auf der Plattform fest.
Nichts ändert sich, solange du keine Route setzt.
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.
Eine Route ohne @ und eine URL ruft queue_cloudtasks_url auf.
Die linke Seite ist ein Job-Typ aus der Job-Referenz oder ein Präfix. Ein Name gewinnt gegen ein Präfix und ein längeres Präfix gegen ein kürzeres.
Typen, die keine Route treffen, auch die, die ein späteres Release hinzufügt, nutzen die Standard-Queue (queue_cloudtasks_queue) und laufen daher weiter.
my config check prüft die Form der Routen; eine linke Seite, die keinen Job-Typ trifft, hält my serve beim Start an.
Gib jedem Prozess dieselben Routen, role = web eingeschlossen. Ein Signal sendet der Prozess, der den Job speichert: ein Web-Prozess für das meiste, was Nutzer tun, etwa den
ersten Job eines Beitrags, und ein Worker für die Jobs, die ein Job speichert, Wiederholungen, den nächsten Job eines Reihenfolgeschlüssels und den Durchlauf verlorener Signale.
Wo jede Rolle eigene Einstellungen hat, wie bei Cloud-Run-Diensten, gib allen denselben Wert:
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"Ein Prozess mit anderen Routen löst keinen Fehler aus und verliert keinen Job: Seine Signale gehen an eine andere Queue, und die Jobs laufen dort, außerhalb der Kapazität, die du festgelegt hast.
my.queue.oldest_ready_age zeigt das nicht, weil diese Jobs nicht warten. Um die Prozesse zu vergleichen, protokolliert jeder beim Start eine Zeile mit seinen routes und deren routes_hash:
Der Hash muss überall gleich sein. Um zu sehen, wohin Signale gehen, lies die eigenen Metriken der Plattform zu jeder Queue.
Berechtigungen. Die Zugangsdaten jedes Prozesses müssen an jede Queue der Routen senden dürfen: roles/cloudtasks.enqueuer.
Ein fehlgeschlagenes Senden wird protokolliert und nicht auf einer anderen Queue versucht, damit ein Typ, den du begrenzt hast, nicht auf die anderen überläuft. Diese Jobs starten spät, sobald der Durchlauf ihre Signale nach 2 Minuten erneut sendet.
Kapazität. Jeder Empfänger führt jeden Job aus, du wählst also, wie weit du sie trennst:
| Plattform | Ein Empfänger | Getrennte Empfänger |
|---|---|---|
| Google Cloud | Ein Dienst. Jede Queue hat ihre eigenen maxConcurrentDispatches und maxDispatchesPerSecond; das Server-Limit des Dienstes wird geteilt |
Ein Dienst pro Queue, benannt durch die URL in der Route, jeder mit eigenem Server-Limit und eigener Nebenläufigkeit. Jeder setzt queue_cloudtasks_url auf seine eigene URL |
Eine Queue braucht dieselbe Einrichtung wie die Standard-Queue: die Rolle auf der Queue. Nur die Standard-Queue braucht den Tick.
Was eine Queue hinzufügt. Jede Queue ist eine Sache mehr, die du erstellen, beobachten und bezahlen musst, und wie viel das ausmacht, hängt von der Größe deines Servers ab.
Teile auf, was du in my.job.wait hast warten sehen, nicht alles.
Der Durchlauf. Jede Minute sucht der Durchlauf nach Jobs, die seit über 2 Minuten fällig sind, ohne zu laufen, bis zu 500 pro Route und 500 für die Standard-Queue, und signalisiert sie erneut. Eine Queue, die nicht mithalten kann, erhält also bis zu 500 doppelte Signale pro Minute. Sie lassen keinen Job zweimal laufen, sind aber Nachrichten, für die du bezahlst, und sie hören auf, sobald sich der Rückstau auflöst.
Reihenfolgeschlüssel gelten weiter: Die Datenbank entscheidet, was laufen darf. Jobs eines Schlüssels können auf verschiedenen Queues liegen, aber eine festgefahrene Queue verzögert auch die späteren Jobs ihrer Schlüssel.
Eine Queue hinzufügen, verschieben und entfernen.
- Erstelle die Queue und ihren Empfänger und gib jedem Prozess die Berechtigung, an sie zu senden.
- Ändere die Routen in jedem Prozess. Solange sie sich unterscheiden, gehen Signale an beide Queues, und die Jobs laufen an beiden Orten.
- Um eine Queue zu entfernen, nimm sie zuerst überall aus den Routen und warte, bis sie leer ist, bevor du sie löschst. Ein Signal in einer gelöschten Queue geht verloren, nicht sein Job: Der Durchlauf signalisiert den Job erneut, sobald er seit 2 Minuten fällig ist. Ein Cloud-Tasks-Task kann ein Signal für einen Job bis zu 30 Tage im Voraus halten, ein Job, der später als die Wartezeit fällig ist, wird also einfach vom Durchlauf signalisiert, wenn seine Zeit kommt.
Health-Checks
Abschnitt betitelt „Health-Checks“| Pfad | Art | Wann er 200 zurückgibt |
|---|---|---|
GET /healthz, GET /health/live |
Liveness | Der Prozess kann HTTP beantworten. Er schaut nicht auf Abhängigkeiten wie die Datenbank (damit eine langsame Datenbank den Prozess nicht neu startet) |
GET /readyz, GET /health/ready |
Readiness | Die Datenbank ist erreichbar und das Schema ist angewendet |
GET /api/v1/instance/health |
Uptime-Monitoring, Statusseiten und Clients (von der web-Rolle bedient) |
Dasselbe wie die Readiness. Das Ergebnis wird 60 Sekunden im Prozess zwischengespeichert |
- Cloud Run reserviert einige Pfade, die auf
zenden, darunter/healthz, und beantwortet sie selbst mit einem404; rufe dahinter/health/liveund/health/readyauf, die dasselbe beantworten. - Ein 200 von jedem von ihnen hat den Body
{"status":"ok"}. /readyzprüft die Datenbank bei jeder Anfrage, und gleichzeitige Anfragen teilen sich eine Prüfung./api/v1/instance/healthgibt bei Gesundheit 200 und{"status":"ok","checked_at":"<RFC 3339>"}zurück und bei einem Fehler 503 und{"status":"unavailable","checked_at":...}(Cache-Control: no-store). Jeder Prozess berührt die Datenbank höchstens einmal pro Minute, wie oft er auch überwacht oder angefragt wird, und er schaut weder auf das Zugriffstoken noch auf das Ratenlimit. Richte Uptime-Monitore auf diesen Endpunkt, nicht auf den Probe (/readyzoder/health/ready). Zu Einrichtung pro Dienst, Monitoring-Intervall und Kosten und dazu, wie Wartung behandelt wird, siehe die Anleitung zum Uptime-Monitoring.- Alle drei loggen im Access-Log auf Debug-Stufe und erzeugen keinen Trace-Span.
- Ist die Readiness nicht erfüllt, ist die Antwort 503 mit einem RFC-9457-Body
application/problem+json. Seintitlewird gemäßAccept-Languageübersetzt und enthält keine internen Details. Die Ursache (ein Verbindungsfehler oder die Namen fehlender Tabellen) geht ins Log. - Eine Readiness-Prüfung wird nach 3 Sekunden abgebrochen.
- Die Readiness verlangt außerdem, dass die Datenbank den konfigurierten
hostund dieaccount_domainenthält oder dass der Prozess sie erfassen konnte. - Schema angewendet bedeutet, dass jede Tabelle, die die Schemadateien der Datenbank (
schema/<NN>-<module>/<dialect>.sql) mitCREATE TABLEdeklarieren, existiert (SQLite wird übersqlite_schemageprüft, PostgreSQL über dascurrent_schema()der Verbindung).my schema applywendet das ganze Schema an, daher bedeutet eine fehlende Tabelle, dass das Schema nicht angewendet oder älter als das Binary ist. Unterschiede bei Spalten und Indizes werden nicht geprüft;my schema apply -dry-rungibt aus, was sich ändern würde.
Anfragen, die das CDN umgehen
Abschnitt betitelt „Anfragen, die das CDN umgehen“Liegt der Server hinter einem CDN und bleibt seine eigene Adresse öffentlich, setze origin_secret und origin_secret_header, damit er ablehnt, was nicht über das CDN kam. Die Health-Checks bleiben erreichbar. Siehe Anfragen ablehnen, die nicht über das CDN kamen.
Sicherheits-Header
Abschnitt betitelt „Sicherheits-Header“Jede Antwort trägt Strict-Transport-Security, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, Cross-Origin-Opener-Policy, Cross-Origin-Resource-Policy: same-site und X-Frame-Options
und, bei Antworten, die keine Dokumente sind, Content-Security-Policy: default-src 'none'; frame-ancestors 'none'; base-uri 'none'.
Ein Handler überschreibt diese bei Antworten, die andere Werte brauchen, etwa ActivityPub-JSON und öffentliche Medien.
Permissions-Policy verweigert Kamera, Geolokalisierung, Zahlung und USB. Sie verweigert auch das Mikrofon, außer solange der Voice-Chat an ist (voice ist nicht off):
dann erlaubt sie das Mikrofon nur für Seiten der eigenen Origin des Servers (microphone=(self)), damit Browser in einem Anruf sprechen können.
Das HTML des Webclients erhält eine Dokument-CSP, die keine Nonce verwendet (script-src 'self' und so weiter).
Sie verlangt Trusted Types (require-trusted-types-for 'script') und beschränkt die Policies, die erstellt werden können, auf die zwei des Clients (trusted-types my-server-sanitized-html my-service-worker).
Web-Client
Abschnitt betitelt „Web-Client“Ein Prozess, dessen role web oder all ist, liefert den in die Binärdatei eingebetteten Web-Client aus.
| Pfad | Inhalt | Cache-Control |
|---|---|---|
Jedes GET, das keine andere Route trifft (/, /@alice, /@alice/status/{id}, /settings und so weiter) |
Die HTML-Hülle der SPA. Die Instanzeinstellungen werden in <script type="application/json" id="config"> übergeben |
public, max-age=60, stale-while-revalidate=300, ETag |
GET /assets/* |
Build-Dateien mit gehashten Namen | public, max-age=31536000, immutable, ETag |
GET /manifest.webmanifest |
Das Web-App-Manifest, aus den Instanzeinstellungen gebaut | public, max-age=60, stale-while-revalidate=300, ETag |
GET /sw.js, /icon.svg und andere Dateien direkt unter dem Build |
Unverändert ausgeliefert | no-cache, ETag |
GET /licenses/* |
Die Lizenzen dessen, was der Build bündelt (npm-Pakethinweise sowie LICENSE-Unicode.txt und OFL.txt für gebündelte Nicht-npm-Daten). Als text/plain; charset=utf-8 ausgeliefert, egal welche Endung |
no-cache, ETag |
GET /robots.txt, /.well-known/tdmrep.json, /.well-known/security.txt |
Aus den Instanzeinstellungen gebaut (siehe Suchmaschinen und KI-Crawler) | public, max-age=3600, ETag |
- Pfade unter
/api,/oauth,/auth,/.well-known,/nodeinfo,/ap,/media,/uploads,/theme(das Stylesheet des Server-Designs) und/licensessowie/robots.txtliefern nie die Hülle; trifft keine andere Route, liefern sie ein 404-Problem. - Die Hülle wird nach der ActivityPub-Content-Negotiation ausgeliefert. Wer einen Hüllenpfad mit einem ActivityPub-
Acceptanfordert, erhält 404 (Beitragsseiten leiten weiter, wie unten beschrieben). Die Hülle trägt immerVary: Accept. Setzt du ein CDN davor, nimm die Art desAccept(ActivityPub oder HTML) in den Cache-Key auf, oder schließe die Hülle,/ap/*und/@*vom Caching aus. Liefere vom CDN nur/assets/*aus. - Die Textdateien des Builds (Skripte, Stylesheets, SVG-Bilder, Lizenzhinweise) sind nur komprimiert eingebettet. Eine Anfrage, die Brotli akzeptiert, erhält sie mit
Content-Encoding: br, eine, die gzip akzeptiert, mitContent-Encoding: gzip, und jede andere Anfrage erhält sie dekomprimiert, immer mitVary: Accept-Encodingund einem ETag pro Kodierung. Ein Proxy davor braucht dafür keine eigene Kompression, und ein CDN mussVary: Accept-Encoding(oder die Kodierung) in seinem Cache-Key für/assets/*behalten. - Die Hülle und die Anmeldebildschirme tragen
Link-Header, die die Stylesheets und das Einstiegsskript nennen, die die Seite zuerst lädt, woraus ein CDN wie Cloudflare (seine Funktion Early Hints) eigene Early Hints machen kann. Mitweb_early_hints=truesendet der Server sie auch zuerst in einer103 Early Hints-Antwort, damit der Browser die Dateien abruft, während der Server die Seite vorbereitet. Es ist standardmäßig aus, da ein Proxy, der ein 103 nicht weiterreichen kann, die Anfrage scheitern lassen kann:- Ein externer Application Load Balancer von Google Cloud antwortet 502 oder 503 (
backend_interim_response_not_supported): Lass es dahinter aus, wie es die Cloud-Run-Bereitstellung tut. - nginx reicht es ab 1.29.0 weiter, mit gesetztem
early_hints. - Das
reverse_proxyvon Caddy reicht es weiter; eineencode-Direktive verwirft es in Releases vor 2.8. - Browser verwenden ein 103 nur für eine Seite, zu der sie navigieren, und Chrome und Edge nur über HTTP/2 und HTTP/3.
- Ein externer Application Load Balancer von Google Cloud antwortet 502 oder 503 (
- Eine Binärdatei, die ohne den Web-Client gebaut wurde (ein einfaches
go build, ohne zuerst den Client zu bauen), protokolliert beim Start eine Warnung und liefert eine Hülle ohne Skripte aus.
Föderations-Endpunkte
Abschnitt betitelt „Föderations-Endpunkte“Ein Prozess, dessen role web oder all ist, beantwortet diese Endpunkte, die andere Fediverse-Server nutzen, um deine Konten zu finden und anzuzeigen.
| Pfad | Inhalt |
|---|---|
GET /.well-known/webfinger |
WebFinger (RFC 7033). resource ist acct:alice@{account_domain} (acct:alice@{host} funktioniert ebenfalls), eine Actor-id oder die URL /@alice. subject ist immer das Handle auf der Seite der account_domain |
GET /.well-known/host-meta, /.well-known/host-meta.json |
Die WebFinger-URI-Vorlage (XRD / JRD) |
GET /.well-known/nodeinfo, GET /nodeinfo/2.1 |
NodeInfo 2.1. metadata.sourceCode ist die Einstellung source_url, und software.repository wird bei einer https:-URL ebenfalls gesetzt (siehe Den Quellcode veröffentlichen) |
GET /ap/actors/{uuid} |
Der Actor (publicKey ist der RSA-#main-key). Eine Anfrage, die HTML bevorzugt, erhält ein 303 auf /@{username} |
GET /ap/actors/{uuid}/{outbox,followers,following,featured,featured-tags} |
Collections |
POST /ap/actors/{uuid}/inbox, POST /ap/inbox |
Die Inbox jedes lokalen Actors und die Shared Inbox. Anfragen müssen HTTP-signiert sein |
GET /@{username} |
Ein 302 auf die id des Actors bei einem ActivityPub-Accept; sonst das HTML des Webclients (siehe unten) |
GET /@{username}/status/{uuid} |
Bei einem ActivityPub-Accept ein 302 auf die id (/ap/objects/{uuid}) des Beitrags, wenn ihn ein abgemeldeter Besucher sehen kann, und 404, wenn nicht. Sonst das HTML des Webclients |
- Das Handle des Server-Actors ist
{account_domain}@{account_domain}(dieselbe Form wie bei Mastodon). - Ein Konto, das nicht existiert oder nicht gezeigt werden kann (gesperrt, deaktiviert, gelöscht oder entfernt), erhält immer dasselbe 404 (
Cache-Control: no-store). - Anonyme Antworten tragen
Cache-Control: public, max-age=60. Antworten, die nachAcceptvariieren, tragenVary: Accept. Nimm bei einem CDN, dasVary: Acceptnicht verarbeiten kann,/ap/*und/@*vom Caching aus.
Getrennte Handle- und Zustell-Domains
Abschnitt betitelt „Getrennte Handle- und Zustell-Domains“Unterscheidet sich account_domain von host, werden Anfragen an /.well-known/webfinger, /.well-known/host-meta und /.well-known/nodeinfo auf der Seite der account_domain mit einem 301 auf host umgeleitet (mit Access-Control-Allow-Origin: *).
Leitest du Anfragen für account_domain an diesen Server, liefert der Server diese Umleitung selbst.
Antwortet stattdessen ein anderer Server oder Reverse-Proxy, leite auf https://{host} um und behalte Pfad und Query-String bei.
Für LLMs und Coding-Agenten:llms.txt,llms-full.txt, llms-small.txt