Diese Seite ist eine maschinelle Übersetzung der englischen Seite, die maßgeblich ist. Englische Seite lesen
Administratoren und Rollen
So legst du den ersten Administrator an, verwaltest Rollen auf der Kommandozeile, kündigst das Ende des Dienstes an und führst es durch, verarbeitest hochgeladene Bilder erneut, baust den Suchindex neu auf, behandelst die TLS-Zertifikate, die der Server selbst ausliefert, und exportierst die Wartungsseite.
Voraussetzungen
Abschnitt betitelt „Voraussetzungen“- Die Konfiguration (
host,database,database_url,kekund so weiter) ist so gesetzt, wie die Konfigurationsreferenz es beschreibt.my config checkprüft sie. - Das Schema ist auf die Datenbank angewendet (
my schema apply; siehe database.md). hostundaccount_domainsind endgültig. Der erste Befehl, der die Datenbank verwendet, merkt sie sich, und jeder spätere Befehl weigert sich zu laufen, wenn die Konfiguration abweicht (siehe Einstellungen, die du später nicht mehr ändern kannst).
Einen Administrator anlegen
Abschnitt betitelt „Einen Administrator anlegen“my admin create -username alice -email alice@example.com- In einem Terminal fragt der Befehl zweimal nach dem Passwort, ohne es anzuzeigen.
- Ist die Standardeingabe kein Terminal, ist die erste Zeile der Standardeingabe das Passwort (zum Beispiel
my admin create ... < password.txt). Das Passwort lässt sich weder als Kommandozeilenargument noch als Umgebungsvariable übergeben, weil diese in Prozesslisten und der Shell-Historie landen. - Wo ein einmaliger Befehl weder ein Terminal noch eine Standardeingabe hat, etwa bei einem Cloud Run job, füge
-password-linkhinzu. Der Befehl liest dann kein Passwort: Er setzt ein zufälliges, das niemand erfährt, und gibt nach der Zeilecreated admineinen Link aus, der das Passwort einmalig und eine Stunde lang festlegen lässt, wiemy admin account password-reset-link(das Audit-Log verzeichnet ihn alspassword_reset_link_issued). Wer die Ausgabe des Befehls lesen kann, kann den Link verwenden, und auf einer solchen Plattform bleibt diese Ausgabe in den Logs der Plattform, bis der Link benutzt wird oder abläuft. Öffne den Link sofort. Läuft er ab, stelle mitmy admin account password-reset-link @aliceeinen neuen aus. Schlägt das Ausstellen des Links fehl, existiert der Administrator bereits: Der Befehl sagt das und endet mit Exit-Code 1, und derselbe Befehl liefert einen neuen Link. - Ein Passwort hat 8 bis 128 Zeichen. Es erscheint nie in der Ausgabe, in den Logs oder in einer Fehlermeldung.
- Eine Transaktion legt den Nutzer, das Passwort, die primäre E-Mail-Adresse, das lokale Konto (mit seinen Schlüsseln) und die Zuweisung der Rolle
adminan (ohne Vergebenden, das heißt: die CLI). Die eingebauten Rollen werden zuerst angelegt, falls sie fehlen. - Bei Erfolg gibt der Befehl
created admin @alice@<account_domain> (user <id>, account <id>)aus und endet mit Exit-Code 0. - Auf einem Ein-Personen-Server legt der Befehl kein Konto an und endet mit Exit-Code 1. Solange die Anmeldung auf Login-Anbieter beschränkt ist, warnt er außerdem, dass das Passwort nicht zum Anmelden taugt, bis die Beschränkung endet.
Erneut ausführen
Abschnitt betitelt „Erneut ausführen“- Ist der Nutzername oder die E-Mail-Adresse (jeweils ohne Unterscheidung von Groß- und Kleinschreibung) schon vergeben, ändert der Befehl nichts, gibt aus, was vergeben ist, und endet mit Exit-Code 1. Er ändert nie das Passwort oder die Rollen des vorhandenen Nutzers.
- Ein fehlgeschlagener Lauf schreibt nichts, du kannst also die Ursache beheben und denselben Befehl erneut ausführen.
- Exit-Code 2 bedeutet einen Aufruffehler.
Rollen vergeben und entziehen
Abschnitt betitelt „Rollen vergeben und entziehen“Rollen bündeln Berechtigungen. Die eingebauten Rollen sind admin (position 1000, jede Berechtigung) und
moderator (position 100, mit manage_reports, manage_accounts und view_audit).
my serve prüft die eingebauten Rollen bei jedem Start (in einem Prozess mit beliebiger role), und my admin role prüft sie bei jedem Aufruf.
Beide legen an, was fehlt, und geben admin jede Berechtigung der laufenden Version.
Wenn ein Upgrade eine Berechtigung hinzufügt, ist kein manueller Schritt nötig. Ein moderator behält die Berechtigungen und die Position, die der Administrator gesetzt hat.
my admin role list # each role's position, permissions (grouped as moderation, server administration, and member features), and holdersmy admin role list -user alice # the roles of alicemy admin role grant alice moderatormy admin role revoke alice moderator-
Berechtigungen gehören zu einer von drei Gruppen.
- Moderation:
manage_reports,manage_accounts,manage_domains,manage_invites,view_audit. - Serveradministration:
manage_settings,manage_rules,manage_roles,manage_jobs,manage_login_recovery,manage_custom_emojis,manage_webhooks,manage_announcements,manage_finance,manage_supporters,manage_oauth_apps,manage_service_closure,manage_errors,manage_login_providers. - Funktionen für Mitglieder:
view_finance,create_custom_emojis,start_voice_rooms,create_invites,keep_posts_longer,create_articles,create_events.
listgibt pro Gruppe eine Spalte aus (MODERATION,SERVER,MEMBER). Der Webclient zeigt für die ersten beiden Gruppen „Moderation“ und „Administration“ und rechnet die Funktionen für Mitglieder zu keiner von beiden (siehe moderation.md). - Moderation:
-
Eine Änderung wirkt ab der nächsten Anfrage des Benutzers. Benachrichtigungen für Moderatoren gehen an die Leute, die die Berechtigung innehaben, wenn die Benachrichtigung erstellt wird.
-
Vergaben und Entzüge werden als
role_grantedundrole_revoked(Zielartrole) in das Audit-Log geschrieben. Der Akteur einer CLI-Operation istcli(my admin audit list -target-kind role). -
Eine Rolle zu vergeben, die der Benutzer schon hat, oder eine zu entziehen, die er nicht hat, ändert und protokolliert nichts.
-
Der letzte Inhaber von
adminkann sie nicht verlieren (Exit-Code 1). Vergibadminzuerst an einen anderen Benutzer. -
Der Administrationsbildschirm „Rollen“ (
/admin/roles) listet jede Rolle auf und erstellt, ändert und löscht sie: Die Seite einer Rolle legt ihren Rang, ihre Berechtigungen und ihr Abzeichen fest. Er bietet nur an, was die folgenden Regeln erlauben: einen Rang nicht über deiner höchsten Rolle, die Berechtigungen, die du selbst hast (die übrigen, die eine Rolle hat, werden genannt und beibehalten), nur das Abzeichen vonadmin, und kein Löschen vonadminodermoderator. Beim Löschen einer Rolle musst du ihren Namen eintippen. Die Rollen eines Tarifs werden im Tarif festgelegt. -
Die Admin-API ist
GET /api/v1/admin/roles,GET /api/v1/admin/accounts/{id}/rolesundPUT/DELETE /api/v1/admin/accounts/{id}/roles/{role}, und sie braucht die Berechtigungmanage_roles. Über die API kannst du keine Rolle vergeben oder entziehen, die über der höchstenpositiondeiner eigenen Rollen liegt (403). Den letztenadminzu entziehen, liefert 409. -
Das Personal handelt nur gegenüber niedrigeren Rängen. Über die API braucht es für Moderationsmaßnahmen und deren Aufhebung, das Entscheiden über Einsprüche, das Aufheben von E-Mail-Sperren, das Einsehen privater Daten eines Kontos, das Ausstellen eines Links zum Zurücksetzen des Passworts und das Entfernen der Zwei-Faktor-Authentifizierung, dass die höchste
positionunter deinen Rollen über der jeder Rolle des Ziels liegt; ein höherer oder gleicher Rang, auch dein eigenes Konto, liefert 403. Ein Moderator kann nicht auf einen Administrator einwirken, und ein Administrator nicht auf einen anderen. Diese Befehle (my admin account ...) haben keine solche Grenze; nutze sie, wenn Administratoren uneins sind. -
Der einzige Administrator kann nicht ausgesperrt oder entfernt werden:
disable_login,suspendundbangegen ihn werden abgelehnt, über die API (409) und über diese Befehle (Exit-Code 1), und er kann sein eigenes Konto nicht löschen (409). Ein weiterer Inhaber vonadminzählt nur, solange er sich anmelden kann: nicht nach dem Löschen seines Kontos und nicht, solange er gesperrt, verbannt oder unterdisable_loginist.
Das Ende des Dienstes ankündigen
Abschnitt betitelt „Das Ende des Dienstes ankündigen“Um den Server zu schließen, kündige die Schließung zuerst an. service-closure.md beschreibt das gesamte Vorgehen, von der Ankündigung bis zum Verwerfen der Daten.
Während der Ankündigung arbeitet der Server wie gewohnt weiter. closure in GET /api/v1/instance und metadata.serviceClosure in NodeInfo zeigen den Zustand und die Termine.
my admin closure announce -closes-at 2027-01-31T15:00:00Z -message "Thank you for using this server."my admin closure announce -closes-at 2027-02-28 -export-until 2027-04-30 # change the dates (a bare date means 00:00 UTC)my admin closure status # the state and the schedule in effectmy admin closure withdraw # withdraw the announcement-closes-athat keine Untergrenze.-export-until(die Frist, bis zu der Daten mitgenommen werden können) muss am oder nach-closes-atliegen und beträgt standardmäßig 30 Tage nach dem Schließungsdatum.- Liegt das Schließungsdatum weniger als 30 Tage in der Zukunft, gibt der Befehl eine Warnung auf der Standardfehlerausgabe aus (die Ankündigung wird trotzdem verzeichnet).
- Eine Änderung der Termine wird als neue Ankündigung verzeichnet, und eine Ankündigung nach einem Widerruf ist eine neue. Sobald der Server geschlossen ist, kannst du weder ankündigen noch widerrufen (Exit-Code 1).
- Ankündigen, Termine ändern und Widerrufen werden als
service_closure_announcedundservice_closure_withdrawnins Audit-Log geschrieben (Zielartinstance; siehemy admin audit list -target-kind instance). - Die Admin-API besteht aus
GET /api/v1/admin/closure,PUT/DELETE /api/v1/admin/closure/announcement,GET /api/v1/admin/closure/checkundPOST /api/v1/admin/closure/close. Sie erfordert die Berechtigungmanage_service_closure(unter den eingebauten Rollen hat nuradminsie). - Während der Ankündigung nimmt der Server keine neuen Nutzer und keine neuen Zahlungen an.
- Der wirksame Registrierungsmodus ist
closed(der Wert vonregistration_modeändert sich nicht und gilt wieder, wenn die Ankündigung widerrufen wird). Weder Registrierungen noch Registrierungen mit Einladung funktionieren, und ausstehende Anträge können nicht genehmigt werden (409). - Das Ankündigen lehnt jeden ausstehenden Antrag ab (verzeichnet als entschieden durch
service_closure) und kündigt alle laufenden Abos zum Ende ihres Zeitraums. Die Abonnenten erhalten eine Benachrichtigung (supporter_service_closure) und eine E-Mail. Neue Abos liefern409. Der Widerruf der Ankündigung macht die Ablehnungen und Kündigungen nicht rückgängig. - Jede Ankündigung, Terminänderung und jeder Widerruf sendet die Benachrichtigung
service_closurean alle lokalen Nutzer. All das läuft als Jobs, halte den Worker also nicht an. - Jeder Nutzer mit bestätigter E-Mail-Adresse erhält eine E-Mail bei der Ankündigung, bei einer Terminänderung, bei einem Widerruf, 7 Tage und 1 Tag vor dem Schließungsdatum, bei der Schließung und 7 Tage vor der Exportfrist. Nutzer können sie nicht abbestellen (siehe email.md).
- Nach dem Schließungsdatum erhalten die Personen mit
manage_service_closuredie Benachrichtigungadmin_service_closure_due. Der Server schließt sich nicht von selbst.
- Der wirksame Registrierungsmodus ist
Schließe den Server nach dem Schließungsdatum. Das Schließen lässt sich nicht rückgängig machen.
my admin closure check # review what the closure endsmy admin closure close # show the review, then ask for y and the domain namemy admin closure close -confirm-domain social.example # for automation: pass the domain name instead of answeringcheckundclosezeigen die Anzahl der lokalen Konten, die Anzahl der Ziel-Inboxen (die bekannten Shared Inboxes), eine Schätzung der zu sendendenDelete-Aktivitäten (ihr Produkt), die Anzahl der laufenden Abos, die Anzahl der unfertigen Migrationen (Move) und die Anzahl der Konten unter Aufbewahrungssperre (retention_holds). Bleiben Migrationen übrig oder besteht eine Sperre, warnt der Befehl auf der Standardfehlerausgabe. Exportiere die Datensätze der Konten unter Sperre mitmy admin account export-moderationund bewahre sie auf, bevor du die Daten verwirfst.closeweigert sich ohne Nachfrage, wenn es keine Ankündigung gibt und vor dem Schließungsdatum (Exit-Code 1). Jede andere Antwort alsyoder eine Eingabe, die von der Domain des Servers abweicht (hostin der Konfiguration, ohne Unterscheidung von Groß- und Kleinschreibung), ändert nichts und endet mit Exit-Code 1.- Die Schließung wird als
service_closure_closedins Audit-Log geschrieben. In derselben Transaktion beendet sie jedes laufende Abo (Grundservice_closed) und stellt die Jobs in die Warteschlange, die die Abos beim Zahlungsanbieter sofort kündigen (CancelNow). - Nach der Schließung lässt die Client-API nur noch diese Anfragen durch: das Lesen des eigenen Kontos und der eigenen Einstellungen, die Exporte (
/exports,/csv_exports), Sitzungen (/sessions,/authorized_apps),GET /instanceund die Verwaltung der Schließung und der Job-Warteschlange. Alles andere wird mit403abgelehnt (/api/v1/problems/service-closed). Streams enden, und Web Push sendet nichts. Anmelden und Zurücksetzen eines Passworts funktionieren weiterhin. - Nach der Schließung stellt der Worker ein
Deletedes Akteurs jedes lokalen Kontos an die Föderationspartner zu, jeweils 100 auf einmal (migrierte Konten zuletzt). Er sendet sie auch, wennfederation_modeaufoffoderinboundsteht, und nie an eine gesperrte Domain.my admin closure status(undprogressinGET /api/v1/admin/closure) zeigt, für wie viele Konten einDeleteverzeichnet ist, wie viele Zustellungen noch aufzufächern sind und die Anzahl der Zustellungen in jedem Zustand (pending,succeeded,permanent_failure,skipped,dead). Lass den Worker während der Zustellung laufen. Sind alle Zustellungen abgeschlossen, verzeichnet eine Prüfung, die alle 10 Minuten läuft,delivery_completed(service_closure_delivery_completedim Audit-Log), und die lokalen Akteure antworten danach mit410. Der Server wiederholtdead-Zustellungen nicht von selbst; wiederhole sie mitmy job retry.
Schreibe nach Ablauf der Exportfrist die statische Abschlussseite, die deine Domain ausliefert, sobald der Server angehalten ist. Der Befehl liest die Datenbank, führe ihn also aus, bevor du die Datenbank verwirfst.
my admin closure export-html -out ./closure # every locale (the instance's default locale first)my admin closure export-html -out ./closure -lang ja,en # choose the locales and the order in index.html- Ausgabe:
<dir>/<locale>.htmlfür jede Locale und<dir>/index.htmlmit allen Locales nacheinander. Die Seiten verwenden dieselbe Vorlage wiemy maintenance exportund zeigen den Namen des Servers, das Schließungsdatum, die Nachricht des Betreibers aus der Ankündigung undstatus_page_url. Die Ausgabe enthält außerdem Konfigurationsbeispiele für das Front-End:nginx.conf,Caddyfileundcloudfront-function.js. Sie antworten mit410auf/ap/*,/inbox, WebFinger, host-meta, NodeInfo und/@*und liefern für alles andere die Abschlussseite aus. - Der Befehl weigert sich (Exit-Code 1), solange der Server nicht geschlossen ist. Vor
delivery_completedgibt er eine Warnung aus und schreibt die Seiten trotzdem. service-closure.md beschreibt, wie du das Front-End auf die statische Seite umstellst.
Hochgeladene Bilder erneut verarbeiten
Abschnitt betitelt „Hochgeladene Bilder erneut verarbeiten“Jedes hochgeladene Bild behält drei Größen, eine Animation auch ihre bewegten Versionen. Eine neue Version von my kann diese Größen oder Formate ändern, und ein vorhandenes Bild behält seine Dateien, bis du es erneut verarbeitest:
my admin media reprocess -before 2027-01-31T09:00:00Z-beforenimmt den Zeitpunkt der Änderung, etwa den des Upgrades, im Format RFC 3339. Es werden nur Bilder erfasst, die zuletzt vor diesem Zeitpunkt verarbeitet wurden, und ein Zeitpunkt, der noch nicht erreicht ist, wird abgelehnt.- Der Worker erledigt die Arbeit, 100 Bilder pro Minute, jedes in einem eigenen Job (
media.reprocess_walkundmedia.reprocessin der Job-Referenz). Lass einen Worker laufen; die Admin-Seite für Jobs (/admin/jobs) zeigt die Warteschlange. - Es ist sicher, den Befehl mit demselben Zeitpunkt erneut auszuführen. Bereits verarbeitete Bilder bleiben unberührt, und die, die der erste Lauf nicht erreicht hat, werden nachgeholt.
- Originale werden nicht aufbewahrt, deshalb wird jedes Bild aus seiner großen Version neu erzeugt. Details, die die große Version verloren hat, kommen nicht zurück, und jeder Lauf mit einem späteren Zeitpunkt kodiert die Bilder noch einmal neu und verliert etwas Qualität. Führe ihn pro Änderung nur einmal aus.
- Video- und Audiodateien werden nicht neu kodiert und bleiben unberührt. Ein Bild, das die aktuellen Grenzen nicht mehr akzeptieren, behält seine aktuelle Version, und der Worker schreibt eine Warnung ins Log.
Die neue Version eines Bildes hat neue URLs. Die alten Dateien bleiben für media_replaced_retention erhalten (standardmäßig 30 Tage, Konfigurationsreferenz), damit geöffnete Seiten und Caches weiter funktionieren; danach löscht der stündliche Job media.purge_replaced sie. Andere Server erfahren nichts von den neuen URLs: Ein Server, der noch eine alte URL hält und keine eigene Kopie hat, zeigt das Bild nach dieser Zeit nicht mehr an. Plane den zusätzlichen Speicher ein, bis die alten Dateien verschwinden.
Den Suchindex neu aufbauen
Abschnitt betitelt „Den Suchindex neu aufbauen“my search verwaltet den Index der Volltextsuche von Beiträgen auf einem Server mit Suchmaschine. Mit search = none sagt jeder Befehl das, tut nichts und endet mit Exit-Code 0.
my search rebuild # empty the index, then have the worker add every post that qualifiesmy search rebuild --keep # add them without emptying the indexmy search rebuild --rate 50 # at most 50 posts a second (20 by default, 1000 at most)my search clear # empty the index and end any rebuildmy search status # the backend and the progress and failures of the latest rebuildFühre my search rebuild erneut aus, um einen abgebrochenen Aufbau fortzusetzen. Er macht beim zuletzt bearbeiteten Beitrag weiter und leert den Index nicht noch einmal. Solange einer unfertig ist, wird der jeweils andere Modus mit Exit-Code 1 abgelehnt. Volltextsuche von Beiträgen sagt, wann du welchen verwendest.
TLS-Zertifikate
Abschnitt betitelt „TLS-Zertifikate“my tls behandelt die Zertifikate eines Servers, der HTTPS selbst ausliefert (tls = acme oder tls = files; siehe
HTTPS vom Server ausliefern).
my tls status # each host: certificate, renewal, failures, latest ordersmy tls renew -host social.example # order a certificate now, without waitingmy tls revoke -host social.example -reason key_compromise # replace, then revoke the current certificatestatuszeigt für jeden Host das aktuelle Zertifikat (Seriennummer, Aussteller, Ablauf), wann es erneuert wird, wie viele Bestellungen in Folge kein Zertifikat erbracht haben, und die letzten Bestellungen mit ihren Fehlern. Mittls = fileszeigt es das Zertifikat vontls_cert_file; mittls = offsagt es das.renewundrevokebrauchentls = acme, den laufenden Server (er beantwortet die Prüfungen der Zertifizierungsstelle) und einkvaußermemory. Sie enden mit Exit-Code 1, wenn sie fehlschlagen, wenn gerade ein anderer Prozess das Zertifikat des Hosts bestellt, und mittls = filesodertls = off.-reasonistkey_compromise, wenn der private Schlüssel anderen bekannt sein könnte, sonstsupersededoderoperator.revokeendet mit Exit-Code 0 und gibt eine Warnung aus, wenn es das Zertifikat widerrufen, aber das Ersatzzertifikat nicht bestellen konnte.
Befehle und Metriken erklärt, was jeder davon mit den laufenden Prozessen macht.
Die Wartungsseite exportieren
Abschnitt betitelt „Die Wartungsseite exportieren“my maintenance export schreibt die Seite des Wartungsmodus als statisches HTML,
damit ein Load Balancer, CDN oder Reverse-Proxy sie ausliefern kann, solange my serve selbst nicht laufen kann (ein Image wird ersetzt, eine Revision startet nicht).
Es verwendet dieselbe Vorlage wie der Wartungsmodus, sodass beide dieselben Worte und dasselbe Aussehen zeigen.
my maintenance export -out ./maintenance -lang en,ja # reads the database for at most 5 secondsmy maintenance export -out ./maintenance -lang en,ja -offline # the configuration and the default theme only- Ausgabe:
<dir>/<locale>.htmlfür jedes Locale aus-lang, für Frontends, die eine Seite nachAccept-Languagewählen, und<dir>/index.htmlmit allen Locales nacheinander, für solche, die das nicht können. Die Seiten haben Inline-CSS, kein Skript und keine externe Ressource; ihre Content-Security-Policy steht in einem<meta>-Element. - Worte: die Einstellungen
maintenance_server_name,maintenance_message,maintenance_untilundstatus_page_url(Konfigurationsreferenz). - Ohne
-offlineliest es außerdem den Namen der Instanz (wennmaintenance_server_namenicht gesetzt ist), ihr Standard-Locale (wenn-langnicht angegeben ist) und die Token-Überschreibungen ihres veröffentlichten Themes. Kann die Datenbank nicht gelesen werden, gibt es eine Warnung aus, schreibt die Seiten aus der Konfiguration und dem Standard-Theme und endet mit 0. - Führe es erneut aus, sobald sich diese Einstellungen oder das Theme ändern, und vor jeder Wartung, damit die Seiten im Frontend aktuell bleiben.
Für LLMs und Coding-Agenten:llms.txt,llms-full.txt, llms-small.txt