Configura un alias personalizzato per una stanza Matrix sul tuo dominio

Per assegnare a una stanza Matrix un indirizzo come #support:example.com, crea un alias locale per la stanza sull'homeserver il cui nome server configurato è example.com, quindi seleziona tale alias come indirizzo principale della stanza in Element. Non è necessario un record DNS separato per ogni alias di stanza, ma non è possibile modificare il dominio alias di un homeserver esistente semplicemente puntando il DNS verso di esso.

Comprendere cosa sono i controlli del dominio personalizzato

L' alias di una stanza è un indirizzo leggibile che si risolve nell'ID permanente di una stanza Matrix , un identificatore che di solito inizia con !. Una stanza può avere più alias, ad esempio #support:example.come #help:example.com, entrambi puntanti alla stessa stanza. Il testo dopo i due punti identifica l'homeserver responsabile della risoluzione di quell'alias, non necessariamente il server che ospita ogni partecipante.

Matrix definisce gli alias nel formato #localpart:server-name. Per Synapse, l' server_nameimpostazione determina il dominio utilizzato per gli indirizzi delle stanze creati localmente e Synapse documenta che questa impostazione non può essere modificata dopo la configurazione iniziale. Se il server esistente si chiama matrix.example.com, Element non trasformerà i suoi alias locali in #support:example.comsolo perché si possiede example.com. Consultare la specifica dell'identificatore Matrix e il manuale di configurazione di Synapse .

Verifica i prerequisiti

  • Un homeserver Matrix funzionante: questo esempio presuppone che Synapse stia già gestendo le richieste API dei client all'indirizzo https://matrix.example.commentre la sua configurazione server_nameè example.com. L'URL del client e il nome del server potrebbero essere diversi.
  • Una stanza esistente: crea prima la stanza, se necessario. Scegli un alias breve e riconoscibile, localpart, ad esempio support. Un alias deve essere univoco sul server che lo crea.
  • Autorizzazione alla gestione degli indirizzi: accedi con un account autorizzato a creare l'alias locale e a modificare l'indirizzo principale della stanza. Le policy del server relative alla creazione di alias e i livelli di potenza della stanza possono limitare queste azioni.
  • Un metodo per effettuare un test: tenete a disposizione un secondo account Matrix, idealmente su un altro server domestico, in modo da poter verificare il rilevamento indipendentemente dalla sessione di amministratore.

Crea l'alias in Element Web

Il percorso seguente corrisponde alla terminologia relativa alle impostazioni della stanza presente nella documentazione di Element relativa alle impostazioni della stanza, verificata nell'ottobre 2026. La posizione dei menu può variare a seconda della versione di Element e dei client Matrix.

1. Apri le impostazioni della stanza

In Element Web o Element Desktop, apri la stanza di destinazione. Seleziona Impostazioni stanza dal pannello Informazioni stanza oppure utilizza il menu con i tre puntini della stanza e scegli Impostazioni . Se in seguito ti serve l'ID interno della stanza per la risoluzione dei problemi, cercalo nella sezione Avanzate e copialo senza modificarne alcun carattere.

2. Aggiungi un indirizzo locale

Nella pagina delle impostazioni generali , individua Indirizzi stanza , quindi Indirizzi locali . Inserisci l'alias localpart, ad esempio support, nel campo Indirizzo stanza e seleziona Aggiungi o il comando di salvataggio equivalente. Verifica che l'indirizzo completo risultante sia #support:example.com. Se invece termina con :matrix.example.com, interrompi: si tratta di un problema relativo al nome del server home, non di un errore di battitura che le impostazioni della stanza possono correggere.

3. Scegli l'indirizzo principale

Sempre nella sezione Indirizzi stanza , trova Indirizzi pubblicati e imposta Indirizzo principale su #support:example.com. La documentazione di Element afferma che il primo indirizzo locale creato viene normalmente selezionato automaticamente come indirizzo principale. Selezionarlo esplicitamente è utile quando la stanza ha già diversi alias.

L'indirizzo principale è l' alias canonico della stanza : l'indirizzo preferito pubblicizzato nello stato della stanza. Creare un alias e scegliere l'alias canonico sono azioni correlate ma distinte. Matrix supporta anche alias pubblicizzati alternativi. Un alias canonico deve già risolversi in quella stanza prima di essere pubblicizzato.

4. Decidi se la stanza deve essere inclusa in un elenco

Abilita l'opzione "Pubblica questa stanza nella directory pubblica" solo se desideri effettivamente che la directory sia visibile. Impostare un indirizzo non rende automaticamente pubblica una stanza, e la pubblicazione di una stanza è separata dalle sue regole di accesso. Una stanza privata o accessibile solo su invito può avere un alias memorabile senza concedere a tutti il ​​permesso di accedervi. Per le stanze pubbliche della community, verifica sia le impostazioni della directory che le regole di accesso della stanza prima di condividere ampiamente l'indirizzo.

Utilizzare l'API Matrix se il client non riesce ad aggiungere l'indirizzo

Gli amministratori e gli strumenti di automazione possono utilizzare l' API client-server standard di Matrix . L'esempio seguente crea lo stesso alias; non eseguirlo se l'elemento è già stato creato #support:example.com. Sostituisci l'ID della stanza reale e un token di accesso valido per un utente autorizzato dalla policy degli alias del server domestico. Tratta il token come una password.

curl --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data '{"room_id":"!yourRoomId:example.com"}' \
  'https://matrix.example.com/_matrix/client/v3/directory/room/%23support%3Aexample.com'

Una richiesta andata a buon fine restituisce HTTP 200con un oggetto JSON vuoto. Le parti %23e %3Asono codifica URL per #e :. La richiesta PUT crea una mappatura alias-stanza; non modifica necessariamente l'alias canonico della stanza. Dopo una creazione solo tramite API, tornare al controllo Indirizzo principale di Element se si desidera che tale alias venga pubblicizzato come primario. Non incollare un token bearer reale in un comando shell condiviso, in uno screenshot o in un ticket di supporto.

Verifica che la mappatura si risolva

La ricerca nella directory non richiede l'accesso. Sostituisci l'host URL con il tuo endpoint API client accessibile:

curl --fail-with-body --silent --show-error \
  'https://matrix.example.com/_matrix/client/v3/directory/room/%23support%3Aexample.com'

La risposta dovrebbe contenere una room_idcorrispondenza con la stanza di destinazione e un serversarray. Questo test verifica la risoluzione degli alias, non se ogni server remoto può federarsi con il tuo.

Risolvere i guasti più comuni

L'alias ha il dominio sbagliato

Verifica la configurazione di Synapse server_name. Non modificare questo valore su un server esistente nel tentativo di rinominare i suoi alias: la sua identità e gli identificatori Matrix esistenti dipendono da esso. Per una nuova implementazione, pianifica il nome del server desiderato prima di creare utenti e stanze. Se operi già con un altro nome, utilizzare il suo dominio alias effettivo potrebbe essere la scelta più sicura, a meno che tu non possa predisporre un homeserver con un nome appropriato che gestisca i nuovi alias.

Creazione non riuscita con errore 403 o 409

HTTP 403in genere indica un'autorizzazione negata o una policy del server applicabile. Verifica i privilegi della stanza dell'utente e alias_creation_rulesle regole di Synapse; queste vengono valutate in ordine e un elenco esplicitamente vuoto impedisce la creazione di qualsiasi alias. HTTP 409significa che l'alias esiste già. Scegli un localpart diverso o esamina la mappatura esistente anziché sovrascriverla ciecamente. Il manuale di configurazione di Synapse documenta le opzioni della policy degli alias.

Gli utenti su altri server non riescono a trovare la stanza

Innanzitutto, verifica che l'alias sia risolvibile localmente. Se la risoluzione locale ha esito positivo ma il rilevamento esterno fallisce, controlla la federazione per il dominio alias , inclusi i certificati HTTPS, la delega pertinente /.well-known/matrix/servere il listener di federazione esposto. Un nome host utilizzato per il traffico client non stabilisce automaticamente la federazione per un nome server Matrix diverso. L' API Server-Server di Matrix descrive il rilevamento e la delega dei server. Verifica inoltre che agli utenti remoti sia consentito l'accesso; una stanza accessibile solo su invito può essere risolta correttamente pur rifiutando l'accesso.

Verifica l'indirizzo della camera personalizzata

  1. Verifica che #support:example.comappaia sotto Indirizzi locali e come indirizzo principale previsto in Element.
  2. Esegui la richiesta GET non autenticata alla directory riportata sopra e confronta il risultato room_idcon l'ID visualizzato nelle impostazioni avanzate della stanza di Element.
  3. Da un altro account, prova ad aprire https://matrix.to/#/%23support%3Aexample.com. Il link dovrebbe reindirizzare alla stanza prevista; la possibilità di accesso dipende comunque dalle regole di accesso della stanza stessa.

Il riferimento al formato room-alias e matrix.to di Matrix definisce il formato codificato del link di condivisione. Se tutti e tre i controlli hanno esito positivo, il nuovo indirizzo è pronto per la condivisione, mentre l'ID della stanza originale rimane invariato.

Lascia un commento

Configura un alias personalizzato per una stanza Matrix sul tuo dominio

Assegna a una stanza Matrix un indirizzo facile da condividere sul tuo dominio utilizzando Element o l'API Matrix, con controlli per le autorizzazioni, la denominazione Synapse e la federazione.

Configura coturn per chiamate vocali e video Matrix affidabili.

Configurare coturn e Synapse con le credenziali TURN corrispondenti, aprire le porte relay necessarie e verificare che i client Matrix possano ottenere i candidati relay.

Distribuisci Matrix Synapse con Docker Compose e PostgreSQL

Distribuisci Matrix Synapse con Docker Compose e PostgreSQL

Configura un server domestico Synapse persistente con Docker Compose, PostgreSQL, una configurazione privata ed effettua i controlli necessari prima di esporlo tramite HTTPS.

Personalizza il tema e l'immagine coordinata di Element Web

Imposta un nome personalizzato, colori e elementi di accesso per la tua implementazione di Element Web, tenendo presente quali parti rimangono a marchio Element.

Aumenta il limite di file di Systemd in Synapse senza dover fare supposizioni.

Aumenta il limite di file di Systemd in Synapse senza dover fare supposizioni.

Diagnostica se Synapse ha raggiunto il limite di file aperti per processo, imposta un comando systemd specifico per il servizio o il worker corretto e verifica il limite effettivo.

Element mostra "Decrittazione non riuscita"? Ripristina la chiave della stanza mancante

Element mostra "Decrittazione non riuscita"? Ripristina la chiave della stanza mancante

Scopri se l'errore è limitato a un singolo browser o a un singolo evento, quindi utilizza la chiave di ripristino di Element o un dispositivo attendibile senza rischiare di perdere la cronologia crittografata rimanente.

Elimina i vecchi messaggi e file multimediali di Synapse senza perdere dati.

Utilizza le API di Synapse per la cancellazione della cronologia e dei supporti di memorizzazione o le impostazioni di conservazione per rimuovere in modo sicuro i dati obsoleti, quindi verifica il completamento dell'operazione e il recupero dello spazio su disco.

Crea un bot di tipo Matrix Echo in Python con Simple-Matrix-Bot-Lib

Crea un bot di tipo Matrix Echo in Python con Simple-Matrix-Bot-Lib

Installa la libreria corrente, collega un account Matrix dedicato ed esegui un piccolo bot !echo con una gestione più sicura delle credenziali e un test chiaro.

Collega Matrix a WhatsApp, Telegram e Discord con bridge separati.

Collega Matrix a WhatsApp, Telegram e Discord con bridge separati.

Configura tre bridge Mautrix con registrazioni, accessi e test separati, ed evita sorprese legate alla rete Docker, alle policy degli account e alla sincronizzazione.

Recupera spazio su disco in Synapse Media senza compromettere i file condivisi.

Scopri cosa occupa spazio di archiviazione in Synapse, imposta la conservazione sicura dei file multimediali e svuota la cache remota senza eliminare i file direttamente dal disco.