Jak usunąć nieaktywne konta użytkowników w Matrix Synapse za pomocą interfejsu API administratora

W Matrix Synapse istnieje istotna różnica między usunięciem nieaktywnego konta a jego dezaktywacją . Udokumentowane API administratora Synapse nie zapewnia uniwersalnego punktu końcowego do trwałego usuwania wszystkich rekordów bazy danych powiązanych z użytkownikiem. Obsługiwany obieg pracy administracyjnej polega na zidentyfikowaniu konta, jego sprawdzeniu, a następnie wywołaniu punktu końcowego dezaktywacji. Opcjonalnie można ustawić "erase": trueusuwanie informacji o profilu i oznaczenie użytkownika jako usuniętego.

Dobrym rezultatem nie jest zatem „zniknięcie identyfikatora użytkownika z każdej tabeli Synapse”. Dobrym rezultatem jest utrata możliwości uwierzytelnienia użytkownika, usunięcie aktywnych tokenów i urządzeń, usunięcie konta z pokoi, usunięcie identyfikatorów osób trzecich oraz – jeśli wymaga tego polityka – usunięcie profilu. Przesłane multimedia i historyczne wiadomości to oddzielne kwestie i nie są automatycznie usuwane po dezaktywacji konta.

W tym przewodniku wykorzystano aktualną dokumentację interfejsu API administratora Synapse, dostępną w październiku 2026 roku. Zawsze porównuj przykłady z dokumentacją wersji Synapse działającej na Twoim serwerze domowym, zwłaszcza jeśli korzystasz z wdrożenia długoterminowego lub usługi uwierzytelniania Matrix. Wiarygodnymi źródłami są: dokumentacja interfejsu API administratora użytkowników Synapse , omówienie interfejsu API administratora Synapse oraz dokumentacja interfejsu API administratora multimediów Synapse .

Jaki wynik powinieneś osiągnąć?

Przed wprowadzeniem jakichkolwiek zmian zdefiniuj zasady czyszczenia. „Nieaktywny” nie oznacza stanu konta Synapse; to reguła tworzona na podstawie pól takich jak last_seen_ts, typ konta, status administracyjny i kontekst biznesowy.

Jeśli nie masz pewności, czy konto jest porzucone, nie decyduj o last_seen_tsjego jedynym kryterium. Konta usługowe, użytkownicy aplikacji, administratorzy awaryjni, boty, konta pomocy technicznej i użytkownicy powiązani z SSO mogą mieć nietypowe wzorce logowania. Niezawodny proces czyszczenia obejmuje jasną listę wykluczeń i etap weryfikacji.

Krok 1: Utwórz listę użytkowników lokalnych i zbierz dane dotyczące aktywności

Żądania do API administratora wymagają tokena dostępu należącego do administratora serwera , co różni się od bycia administratorem pokoju. W miarę możliwości należy wysłać token w Authorization: Bearernagłówku HTTP, a nie umieszczać go w adresie URL lub historii powłoki.

Synapse dokumentuje punkt końcowy listy użytkowników V3 jako:

GET /_synapse/admin/v3/users

Podstawowe żądanie wygląda następująco:

export SYNAPSE_URL="https://matrix.example.com"
export ADMIN_ACCESS_TOKEN="REDACTED"

curl -sS   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v3/users?limit=100"

Interfejs API listy użytkowników obsługuje stronicowanie. Jeśli odpowiedź zawiera next_token, żądaj następnej strony, używając tej wartości jako from. Nie zakładaj, że pierwsza strona reprezentuje cały serwer.

Interfejs API udostępnia przydatne pola do podejmowania decyzji o czyszczeniu, w tym informacje o tym, czy konto jest kontem administratora, jego typ użytkownika, czy jest już dezaktywowane, kiedy zostało utworzone i kiedy było ostatnio widoczne. Dokumentacja definiuje to last_seen_tsjako znacznik czasu ostatniej aktywności użytkownika w milisekundach od epoki Unix.

Co uznaje się za „nieaktywne”?

Powszechną zasadą jest „brak aktywności przez 180 dni”, ale właściwy próg zależy od środowiska. Mały serwer prywatny może rozsądnie wykorzystać 90 dni. Uniwersytet, organizacja sezonowa lub usługa dla absolwentów może potrzebować 365 dni lub więcej.

Użyj bezwzględnego znacznika czasu zamiast porównywać sformatowane daty. Na przykład, zadanie w Pythonie może obliczyć próg w milisekundach:

from datetime import datetime, timezone, timedelta

cutoff = datetime.now(timezone.utc) - timedelta(days=180)
cutoff_ms = int(cutoff.timestamp() * 1000)

Użytkownika uważa się za nieaktywnego tylko wtedy, gdy konto jest aktywne, nie ma uprawnień administracyjnych, nie jest chronione przez zasady i jest last_seen_tsstarsze niż próg.

Brak lub wartość null w ostatniej wyświetlanej wartości należy traktować konserwatywnie. Może to oznaczać, że konto nigdy nie wygenerowało oczekiwanych danych o aktywności, ale niekoniecznie oznacza, że ​​można je bezpiecznie usunąć. Przed dodaniem konta sprawdź czas utworzenia, typ konta, mapowanie logowania jednokrotnego (SSO) i własność firmy.

Krok 2: Utwórz listę kandydatów nieaktywnych, a nie listę automatycznie usuwanych

Jakość tego kroku jest ważniejsza niż szybkość wywołań API. Twoim celem powinna być zweryfikowana lista kandydatów zawierająca wyłącznie konta, które można bezpiecznie dezaktywować.

Wyklucz co najmniej:

• administratorzy serwerów domowych;
• znane konta aplikacji-usług i integracji;
• boty i konta wsparcia, które są celowo uśpione;
• konta awaryjne lub do rozbijania szyb;
• konta znajdujące się na liście wyjątków dotyczących wstrzymania postępowania prawnego lub przechowywania;
• użytkownicy, którzy niedawno zmienili dostawcę tożsamości lub mapowanie konta;
• już dezaktywowanych użytkowników, chyba że audytujesz poprzednie prace czyszczące.

Prosty rekord kandydata powinien zawierać identyfikator użytkownika Matrix last_seen_ts, znacznik czasu utworzenia, flagę administratora, typ konta oraz powód, dla którego reguła braku aktywności została zaakceptowana. Zachowanie tych dowodów znacznie ułatwia późniejszą weryfikację i podejmowanie decyzji o wycofaniu.

Skąd wiesz, że wybór kandydatów jest wystarczająco dobry?

Zwróć uwagę na trzy oznaki:

• Kompletność: Twój skrypt jest podzielony na strony obejmujące całą listę użytkowników lokalnych.
• Możliwość wyjaśnienia: każdy kandydat ma widoczny powód, na przykład „ostatnio widziano 242 dni temu, nie jest administratorem, nie jest kontem usługowym”.
• Niskie ryzyko fałszywie pozytywnych wyników: konta specjalne i wyjątki biznesowe zostały odfiltrowane przed każdym destrukcyjnym wywołaniem.

Jeśli nie możesz spełnić tych wymagań, zmień proces, zanim przejdziesz dalej. Na przykład dodaj etap zatwierdzania przez człowieka, wyślij ostrzeżenie o braku aktywności lub zacznij od zawieszenia zamiast dezaktywacji.

Krok 3: Sprawdź każde konto przed dezaktywacją

Dla konkretnego użytkownika lokalnego Synapse dokumentuje:

GET /_synapse/admin/v2/users/<user_id>

Przykład:

USER_ID="@olduser:example.com"

curl -sS   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v2/users/$USER_ID"

Odpowiedź może obejmować stan administracyjny konta, flagi dezaktywacji i usunięcia, znaczniki czasu utworzenia i ostatniej widoczności, tożsamości zewnętrzne oraz identyfikatory stron trzecich. W tym miejscu należy zweryfikować, czy dane konto jest tym, którego dotyczy zmiana.

Czy powinieneś użyć erasme true czy erasme false?

Użyj tej opcji "erase": false, gdy celem operacyjnym jest wyłączenie dostępu z zachowaniem informacji o profilu. Zgodnie z aktualną dokumentacją Synapse, standardowa dezaktywacja usuwa aktywne tokeny dostępu, skrót hasła, urządzenia i klucze szyfrowania end-to-end, narzędzia push, identyfikatory stron trzecich, członkostwa w pokojach, dane konta, oczekujące zaproszenia i powiązane informacje o ważności konta.

Użyj tej opcji, "erase": truegdy Twoja polityka wymaga również usunięcia nazwy wyświetlanej, adresu URL awatara, niestandardowych pól profilu oraz oznaczenia użytkownika jako usuniętego. Usunięcie nie oznacza zniszczenia wszystkich historycznych artefaktów. Synapse wyraźnie dokumentuje, że wcześniej wysłane wiadomości nie są usuwane przez to API, a przesłane media również nie są automatycznie usuwane.

To rozróżnienie jest kluczowe. Jeśli Twoja polityka wymaga usunięcia treści wykraczającego poza usunięcie profilu, sama dezaktywacja konta nie wystarczy.

Krok 4: Przeprowadź próbę, dezaktywuj i zweryfikuj

Przed wprowadzeniem zmian zapisz ostateczne identyfikatory użytkowników w pliku tekstowym lub JSON i przejrzyj je. Próba powinna być niezmienna przez cały czas trwania okna zmian: jeśli skrypt generowania kandydatów ulegnie zmianie podczas dezaktywacji użytkowników, zatrzymaj go i ponownie wygeneruj listę zatwierdzonych użytkowników.

Dla każdego zatwierdzonego użytkownika lokalnego należy wywołać udokumentowany punkt końcowy dezaktywacji:

POST /_synapse/admin/v1/deactivate/<user_id>

Przykład bez usuwania profilu:

curl -sS -X POST   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   -H "Content-Type: application/json"   --data '{"erase": false}'   "$SYNAPSE_URL/_synapse/admin/v1/deactivate/@olduser:example.com"

Przykład usuwania profilu:

curl -sS -X POST   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   -H "Content-Type: application/json"   --data '{"erase": true}'   "$SYNAPSE_URL/_synapse/admin/v1/deactivate/@olduser:example.com"

Następnie ponownie przeszukaj konto:

curl -sS   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v2/users/@olduser:example.com"

Pomyślny wynik operacji powinien wyświetlić "deactivated": true. Jeśli zażądano usunięcia, należy również to sprawdzić "erased": true. Nie należy używać „API zwróciło HTTP 2xx” jako jedynego kryterium sukcesu; należy odczytać rekord użytkownika po wprowadzeniu zmiany.

Co tak naprawdę usuwa dezaktywacja?

Aktualna dokumentacja Synapse wymienia kilka skutków dezaktywacji. Należą do nich m.in. usunięcie aktywnych tokenów dostępu, identyfikatorów stron trzecich, urządzeń, kluczy szyfrowania end-to-end, pusherów, skrótów haseł, członkostwa w pokojach, oczekujących zaproszeń i danych konta. Dezaktywacja powoduje również usunięcie użytkownika z katalogu użytkowników.

Dzięki erase: trueSynapse możesz dodatkowo usunąć nazwę wyświetlaną, adres URL awatara, pola profilu niestandardowego i oznaczyć konto jako usunięte.

Synapse dokumentuje również ważne elementy, które nie są usuwane podczas tej operacji. Należą do nich wysłane i odebrane wiadomości, przesłane multimedia, mapowania SSO, znaczniki czasu utworzenia, obejścia limitów przepustowości, miesięczne rekordy aktywnych użytkowników oraz niektóre informacje o zgodach. Udokumentowana lista nie jest koniecznie wyczerpująca, dlatego dezaktywację należy traktować jako zamknięcie konta, a nie jako uniwersalne usunięcie danych.

Czy muszę również usunąć przesłane przez użytkownika materiały multimedialne?

Jeśli Twoja polityka przechowywania danych wymaga usunięcia lokalnie przechowywanych multimediów przesłanych przez użytkownika, Synapse zapewnia osobny punkt końcowy:

DELETE /_synapse/admin/v1/users/<user_id>/media

Przykład:

curl -sS -X DELETE   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v1/users/@olduser:example.com/media"

Interfejs API multimediów użytkownika usuwa lokalne multimedia i miniatury przechowywane w repozytorium multimediów Synapse. W dokumentacji wskazano dwa ograniczenia, które mają znaczenie operacyjne. Po pierwsze, interfejs API nie ma wpływu na multimedia przechowywane w zewnętrznym repozytorium multimediów. Po drugie, jeśli nie zostanie ustawiony limit, punkt końcowy usunie 100 plików na żądanie, więc użytkownicy z dużą historią multimediów mogą wymagać wielokrotnych wywołań.

Nie dodawaj automatycznego usuwania multimediów, chyba że Twoja polityka przechowywania tego wymaga. Jest to znacznie bardziej destrukcyjne niż dezaktywacja konta i może mieć wpływ na multimedia, do których nadal odwołują się historyczne pokoje.

Kiedy należy zastosować zawieszenie?

Synapse dokumentuje również API zawieszenia konta. Zawieszenie blokuje takie czynności, jak wysyłanie wiadomości, dołączanie do pokojów, wysyłanie zaproszeń, zmiana informacji w profilu i większość operacji usuwania, zachowując jednocześnie inną ścieżkę odzyskiwania niż dezaktywacja.

Zawieszenie jest lepszym rozwiązaniem, gdy potrzebujesz odwracalnego zawieszenia administracyjnego, gdy brak aktywności jest niepewny lub gdy proces wyrejestrowania jest nadal w toku. Dezaktywacja jest lepszym rozwiązaniem, gdy dostęp powinien zostać zablokowany, a tokeny, urządzenia, członkostwa w pokojach i dane konta powinny zostać usunięte.

W przypadku automatycznego czyszczenia, procedura etapowa jest często bezpieczniejsza:

1. oznacz konto po przekroczeniu progu bezczynności;
2. powiadomić lub przejrzeć;
3. zawiesić, jeśli nie ma pewności co do własności;
4. dezaktywować dopiero po upływie okresu przechowywania lub zatwierdzania.

Jak bezpiecznie zautomatyzować sprzątanie?

Utrzymuj wykrywanie i dezaktywację jako oddzielne zadania. Zadanie wykrywania powinno być tylko do odczytu i generować plik kandydata. Zadanie wykonania powinno pobierać tylko zatwierdzony plik i rejestrować każde żądanie oraz status odpowiedzi.

Przepływ pracy zapewniający jakość produkcji powinien również:

• podążaj za wszystkimi tokenami paginacji;
• ograniczenie liczby żądań masowych zamiast wysyłania tysięcy żądań jednocześnie;
• domyślnie wyklucz administratorów serwera i nazwane konta usługowe;
• przechowuj znaczniki czasu w formacie UTC;
• zapisz wersję zasad czyszczenia, która została wybrana dla każdego konta;
• zatrzymanie w przypadku uwierzytelnienia, autoryzacji lub powtarzających się błędów serwera;
• ponowne zapytanie każdego użytkownika po dezaktywacji;
• nie udostępniaj tokenów dostępu administracyjnego kodowi źródłowemu ani logom.

Jeśli weryfikacja po zmianie nie jest zgodna z żądanym stanem, nie kontynuuj bezmyślnie z pozostałą partią. Zbadaj pierwsze błędy i ustal, czy problem dotyczy uprawnień, zgodności wersji API, konfiguracji serwera proxy, integracji usługi Matrix Authentication Service, czy też warunku specyficznego dla konta.

Ostateczna lista kontrolna

• Użyj tokena nośnika serwera-administratora.
• Wypisz wszystkie strony użytkowników lokalnych, a nie tylko pierwszych 100 użytkowników.
• Zdefiniuj bezczynność za pomocą udokumentowanego progu i wykluczeń.
• Przed podjęciem działań należy osobno sprawdzić konta wysokiego ryzyka.
• Wygeneruj i zatwierdź listę próbną.
• Zamiast zakładać, że Synapse obsługuje pełne, trwałe usunięcie konta, należy użyć punktu końcowego dezaktywacji.
• Wybierz erase: truetylko wtedy, gdy usuwanie profilu jest częścią polityki.
• Jeśli zachodzi taka potrzeba, obsługuj przesłane media osobno.
• Sprawdź deactivatedi jeśli to możliwe, erasedpo każdej zmianie.

Najbardziej niezawodne czyszczenie to takie, które można później wyjaśnić: która reguła braku aktywności wybrała konto, które wyjątki zostały sprawdzone, która akcja API została wykonana i które pole po zmianie potwierdziło pożądany stan. Ten standard jest bardziej przydatny niż po prostu maksymalizacja liczby kont przetworzonych w jednym przebiegu.