Cum se șterg conturile de utilizator inactive în Matrix Synapse prin intermediul API-ului de administrare

În Matrix Synapse, există o distincție importantă între ștergerea unui cont inactiv și dezactivarea acestuia . API-ul de administrare documentat al Synapse nu oferă un endpoint de ștergere definitivă cu scop general care să elimine fiecare înregistrare din baza de date asociată cu un utilizator. Fluxul de lucru administrativ acceptat este de a identifica un cont, de a-l revizui, apoi de a apela endpoint-ul de dezactivare. Opțional, puteți seta "erase": trueeliminarea informațiilor de profil și marcarea utilizatorului ca șters.

Prin urmare, un rezultat bun nu este „dispariția ID-ului utilizatorului din fiecare tabel Synapse”. Un rezultat bun este că utilizatorul nu se mai poate autentifica, token-urile și dispozitivele active sunt eliminate, contul este scos din camere, identificatorii terți sunt eliminați și - dacă politica dvs. o impune - profilul este șters. Fișierele media încărcate și mesajele istorice sunt aspecte separate și nu sunt șterse automat prin dezactivarea contului.

Acest ghid utilizează documentația actuală a API-ului Synapse Admin, disponibilă în octombrie 2026. Comparați întotdeauna exemplele cu documentația pentru versiunea Synapse care rulează pe serverul dvs. de acasă, mai ales dacă operați o implementare de lungă durată sau utilizați Matrix Authentication Service. Referințele autorizate sunt documentația API-ului Synapse User Admin , prezentarea generală a API-ului Synapse Admin și documentația API-ului Synapse Media Admin .

Ce rezultat ar trebui să urmărești?

Înainte de a modifica orice, definește politica de curățare. „Inactiv” nu este o stare a contului Synapse; este o regulă pe care o creezi din câmpuri precum last_seen_ts, tipul de cont, starea administrativă și contextul de business.

Dacă nu sunteți sigur dacă un cont este abandonat, nu- last_seen_tsl face singurul criteriu. Conturile de serviciu, utilizatorii de servicii de aplicații, administratorii de urgență, boții, conturile de asistență și utilizatorii conectați prin SSO pot avea modele de conectare neobișnuite. Un proces de curățare fiabil include o listă de excludere explicită și o etapă de revizuire.

Pasul 1: Enumerați utilizatorii locali și colectați date despre activitate

Cererile API de administrare necesită un token de acces aparținând unui administrator de server , ceea ce este diferit de a fi un administrator de sală. Trimiteți tokenul în Authorization: Bearerantetul HTTP, în loc să îl plasați într-o adresă URL sau într-un istoric shell, acolo unde este posibil.

Synapse documentează endpoint-ul listei de utilizatori V3 astfel:

GET /_synapse/admin/v3/users

O cerere de bază arată astfel:

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"

API-ul listei de utilizatori acceptă paginarea. Când răspunsul conține next_token, solicitați pagina următoare folosind acea valoare ca from. Nu presupuneți că prima pagină reprezintă întregul server.

API-ul expune câmpuri utile pentru deciziile de curățare, inclusiv dacă un cont este de administrator, tipul său de utilizator, dacă este deja dezactivat, când a fost creat și când a fost văzut ultima dată. Documentația definește last_seen_tsca fiind ultima marcaj temporal al activității utilizatorului, în milisecunde, de la epoca Unix.

Ce se consideră „inactiv”?

O politică obișnuită este „nicio activitate timp de 180 de zile”, dar pragul corect depinde de mediu. Un server privat mic poate folosi în mod rezonabil 90 de zile. O universitate, o organizație sezonieră sau un serviciu pentru absolvenți poate avea nevoie de 365 de zile sau mai mult.

Folosește o marcă de timp limită absolută în loc să compari date formatate. De exemplu, un job Python poate calcula pragul în milisecunde:

from datetime import datetime, timezone, timedelta

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

Apoi, considerați un utilizator inactiv numai atunci când contul este activ, nu are drepturi de administrator, nu este protejat de politică și este last_seen_tsmai vechi decât pragul.

Tratați o valoare lipsă sau nulă, ultima dată văzută, cu prudență. Aceasta poate însemna că respectivul cont nu a generat niciodată datele de activitate așteptate, nu neapărat că este sigur să fie eliminat. Verificați ora creării, tipul contului, maparea SSO și proprietatea afacerii înainte de a o include.

Pasul 2: Creați o listă de candidați inactivi, nu o listă de ștergere automată

Calitatea acestui pas contează mai mult decât viteza apelurilor API. Obiectivul tău ar trebui să fie o listă de candidați revizuiți care să conțină doar conturi care pot fi dezactivate în siguranță.

Cel puțin, excludeți:

• administratori de servere de acasă;
• conturi de servicii de aplicații și integrare cunoscute;
• boți și conturi de asistență care sunt intenționat inactive;
• conturi pentru geam spart sau conturi de urgență;
• conturi aflate pe o listă de excepții de reținere sau suspendare legală;
• utilizatori care au schimbat recent furnizorul de identitate sau maparea contului;
• utilizatori deja dezactivați, cu excepția cazului în care auditați lucrările de curățare anterioare.

O înregistrare simplă a unui candidat ar trebui să conțină ID-ul utilizatorului Matrix, last_seen_tsmarcajul temporal al creării, flag-ul de administrator, tipul de cont și motivul pentru care a trecut regula de inactivitate. Păstrarea acestor dovezi facilitează mult deciziile ulterioare de revizuire și anulare.

De unde știi că selecția candidaților este suficient de bună?

Căutați trei semne:

• Completitudine: scriptul tău a paginat întreaga listă de utilizatori locali.
• Explicabilitate: fiecare candidat are un motiv vizibil, cum ar fi „ultima vizită acum 242 de zile, non-administrator, cont non-service”.
• Risc redus de rezultate fals pozitive: conturile speciale și excepțiile de business au fost filtrate înainte de orice apel distructiv.

Dacă nu puteți îndeplini aceste verificări, modificați procesul înainte de a continua. De exemplu, adăugați o etapă de aprobare umană, trimiteți un avertisment de inactivitate sau începeți cu suspendarea în loc de dezactivare.

Pasul 3: Inspectați fiecare cont înainte de dezactivare

Pentru un anumit utilizator local, documentele Synapse:

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

Exemplu:

USER_ID="@olduser:example.com"

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

Răspunsul poate include starea administrativă a contului, semnalizările de dezactivare și ștergere, marcajele temporale de creare și de ultima conectare, identitățile externe și identificatorii terților. Acesta este punctul în care trebuie să verificați dacă respectivul cont este cel pe care intenționați să îl afectați.

Ar trebui să folosești „erase true” sau „erase false”?

Se utilizează "erase": falseatunci când obiectivul operațional este de a dezactiva accesul, păstrând în același timp informațiile de profil. Conform documentației Synapse actuale, dezactivarea normală elimină token-urile de acces active, hash-ul parolei, dispozitivele și cheile de criptare end-to-end, distribuitorii, ID-urile terților, apartenența la camere, datele contului, invitațiile în așteptare și informațiile aferente validității contului.

Folosește această "erase": trueopțiune atunci când politica ta solicită și eliminarea numelui afișat, a adresei URL a avatarului, a câmpurilor personalizate ale profilului și marcarea utilizatorului ca șters. Ștergerea nu înseamnă că fiecare artefact istoric este distrus. Synapse documentează în mod explicit faptul că mesajele trimise anterior nu sunt șterse de acest API, iar fișierele media încărcate nu sunt șterse automat.

Această distincție este esențială. Dacă politica dumneavoastră impune ștergerea conținutului dincolo de ștergerea profilului, dezactivarea contului în sine nu este suficientă.

Pasul 4: Executarea simulată, dezactivarea și verificarea

Înainte de a executa modificări, scrieți ID-urile finale ale utilizatorilor într-un fișier text simplu sau JSON și revizuiți-l. O simulare ar trebui să fie imuabilă pe durata ferestrei de modificare: dacă scriptul de generare a candidaților se modifică în timp ce dezactivați utilizatorii, opriți și regenerați lista aprobată.

Pentru fiecare utilizator local aprobat, apelați endpoint-ul de dezactivare documentat:

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

Exemplu fără ștergerea profilului:

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"

Exemplu cu ștergerea profilului:

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"

Ulterior, interogați din nou contul:

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

Un rezultat operațional reușit ar trebui să fie afișat "deactivated": true. Dacă ați solicitat ștergerea, verificați și "erased": true. Nu utilizați „API-ul a returnat HTTP 2xx” ca unic criteriu de succes; citiți înregistrarea utilizatorului după modificare.

Ce elimină de fapt dezactivarea?

Documentația actuală Synapse enumeră mai multe efecte ale dezactivării. Printre acestea se numără eliminarea token-urilor de acces active, a identificatorilor terți, a dispozitivelor, a cheilor de criptare end-to-end, a pusher-elor, a hash-urilor de parole, a apartenențelor la camere, a invitațiilor în așteptare și a datelor contului. De asemenea, elimină utilizatorul din directorul de utilizatori.

Cu erase: true, Synapse elimină suplimentar numele afișat, adresa URL a avatarului, câmpurile personalizate ale profilului și marchează contul ca șters.

Synapse documentează, de asemenea, elemente importante care nu sunt eliminate de această operațiune. Acestea includ mesajele trimise și primite, fișierele media încărcate, mapările SSO, marcajele temporale de creare, suprascrierile limitelor de viteză, înregistrările lunare ale utilizatorilor activi și unele informații privind consimțământul. Lista documentată nu este neapărat exhaustivă, așadar tratați dezactivarea ca o închidere a contului - nu ca o eliminare universală a datelor.

Trebuie să ștergi și fișierele media încărcate de utilizator?

Dacă politica dvs. de retenție impune ștergerea fișierelor media stocate local și încărcate de utilizator, Synapse oferă un endpoint separat:

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

Exemplu:

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

API-ul media pentru utilizatori șterge fișierele media locale și miniaturile stocate de depozitul media Synapse. Documentația menționează două limite importante din punct de vedere operațional. În primul rând, fișierele media stocate într-un depozit media extern nu sunt afectate de acest API. În al doilea rând, dacă nu setați o limită, endpoint-ul șterge 100 de fișiere per solicitare, astfel încât utilizatorii cu istoric media extins pot necesita apeluri repetate.

Nu adăugați ștergerea automată a fișierelor media decât dacă politica dvs. de păstrare o impune. Este semnificativ mai distructivă decât dezactivarea contului și poate afecta fișierele media la care se face încă referire în sălile istorice.

Când ar trebui să folosești suspensia în schimb?

Synapse documentează și o API pentru suspendarea contului. Suspendarea blochează activități precum trimiterea de mesaje, intrarea în camere, trimiterea de invitații, modificarea informațiilor de profil și majoritatea eliminărilor, păstrând în același timp o cale de recuperare diferită de dezactivare.

Suspendarea este o opțiune mai potrivită atunci când aveți nevoie de o suspendare administrativă reversibilă, când inactivitatea este incertă sau când o revizuire a dezactivării este încă în curs de desfășurare. Dezactivarea este opțiunea mai bună atunci când accesul trebuie reziliat și token-urile, dispozitivele, abonamentele la camere și datele contului trebuie eliminate.

Pentru curățarea automată, o politică etapizată este adesea mai sigură:

1. semnalează un cont după pragul de inactivitate;
2. a o notifica sau a o revizui;
3. suspendați-l dacă proprietatea este incertă;
4. dezactivați numai după ce a trecut fereastra de păstrare sau aprobare.

Cum ar trebui să automatizezi curățenia în siguranță?

Păstrați descoperirea și dezactivarea ca joburi separate. Jobul de descoperire ar trebui să fie doar pentru citire și să producă un fișier candidat. Jobul de execuție ar trebui să consume doar un fișier aprobat și să înregistreze fiecare stare a cererii și a răspunsului.

Un flux de lucru care asigură calitatea producției ar trebui, de asemenea:

• urmați toate jetoanele de paginare;
• solicitări în bloc cu limită de rată, în loc să se trimită mii de solicitări simultan;
• excludeți administratorii de server și conturile de servicii denumite în mod implicit;
• stocează marcajele temporale în UTC;
• înregistrați versiunea politicii de curățare care a selectat fiecare cont;
• oprire la autentificare, autorizare sau erori repetate ale serverului;
• reinterogarea fiecărui utilizator după dezactivare;
• păstrați token-urile de acces administrativ în afara codului sursă și a jurnalelor.

Dacă verificarea post-modificare nu corespunde stării solicitate, nu continuați orbește cu lotul rămas. Investigați primele erori și determinați dacă problema constă în permisiuni, compatibilitatea versiunii API, o problemă de configurare a proxy-ului, integrarea Matrix Authentication Service sau o condiție specifică contului.

Listă de verificare finală

• Folosește un token purtător de administrator de server.
• Enumerați fiecare pagină a utilizatorului local, nu doar primii 100 de utilizatori.
• Definiți inactivitatea cu un prag documentat și excluderi.
• Inspectați individual conturile cu risc ridicat înainte de a lua măsuri.
• Generați și aprobați o listă de teste preliminare.
• Folosește endpoint-ul de dezactivare în loc să presupui că Synapse acceptă ștergerea completă a contului.
• Alegeți erase: truedoar atunci când ștergerea profilului face parte din politică.
• Gestionați fișierele media încărcate separat, atunci când este necesar.
• Verificați deactivatedși, dacă este cazul, eraseddupă fiecare modificare.

Cea mai fiabilă curățare este cea pe care o puteți explica ulterior: ce regulă de inactivitate a selectat un cont, ce excepții au fost verificate, ce acțiune API a fost efectuată și ce câmp post-modificare a dovedit starea dorită. Acest standard este mai util decât simpla maximizare a numărului de conturi procesate într-o singură rundă.