> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # Gestione dei tenant (organizzazioni e membri) > Documentazione sulla gestione dei tenant AgentEye (organizzazioni e membri). Una singola distribuzione AgentEye serve più **organizzazioni** completamente isolate (tenant), così un'istanza può ospitare team distinti, unità aziendali o clienti senza esporre i dati di un tenant a un altro. Ogni riga di dati (eventi, valutazioni, sessioni, dashboard, query salvate, avvisi, chiavi API e membri) appartiene esattamente a un'organizzazione. L'isolamento principale è applicato nel codice dell'applicazione: ogni richiesta è limitata alla sua organizzazione con predicati espliciti `org_id`. Su ClickHouse — dove risiedono gli eventi e le valutazioni ad alto volume — questo è supportato da un'applicazione forte a livello di motore: ogni organizzazione riceve un utente ClickHouse dedicato in sola lettura con una policy per riga per organizzazione, così anche SQL analitici non attendibili non possono mai leggere le righe di un altro tenant. Su PostgreSQL, la sicurezza a livello di riga aggiunge difesa in profondità sul percorso di query in sola lettura (`/queries/run`), restringendo ciò che quel percorso può visualizzare anche se un filtro a livello di applicazione mancasse; la propria connessione di scrittura del server funziona come proprietario della tabella e quindi opera attraverso lo stesso scoping `org_id` a livello di app. Il ciclo di vita dei tenant è controllato dall'operatore, mentre tutto ciò che i membri fanno quotidianamente rimane self-service nel dashboard. Le organizzazioni e le loro appartenenze sono create e gestite con la CLI **`agenteye-orgctl`**, che è spedita all'interno dell'immagine del server ed eseguita **all'interno del pod server esistente**. La creazione e l'eliminazione dei tenant sono deliberatamente mantenute fuori dal dashboard e dall'API HTTP: non esiste **nessuna API HTTP e nessun pulsante nel dashboard** per il ciclo di vita dei tenant, quindi è protetto da un accesso shell al cluster/pod piuttosto che dalla superficie dell'applicazione. All'interno di un'organizzazione, i membri lavorano interamente nel dashboard e nell'API: accedono, passano tra le organizzazioni a cui appartengono, gestiscono le proprie chiavi API, costruiscono dashboard e query salvate, e configurano avvisi per la loro organizzazione. La divisione è netta: gli operatori forniscono e disattivano i tenant e i loro membri tramite la CLI; i membri eseguono tutto all'interno di un tenant tramite l'interfaccia utente. > **Le distribuzioni single-tenant non hanno bisogno di nulla di tutto questo.** Un'installazione single-tenant funziona senza alcuna azione dell'operatore. Tutti i dati, gli utenti e le chiavi risiedono in un'organizzazione `default` incorporata che viene fornita automaticamente. Hai bisogno di questa guida solo quando decidi di aggiungere una seconda organizzazione. *** ## Prerequisiti Prima di creare la **seconda** organizzazione (l'organizzazione `default` incorporata non ha bisogno di nulla): * **PostgreSQL 15+.** Lo schema di appartenenza dell'organizzazione utilizza una chiave esterna `ON DELETE SET NULL` con elenco di colonne che richiede PostgreSQL 15+. Aggiorna PostgreSQL prima di fornire una seconda organizzazione. * **Un `ORG_CH_SECRET` forte e stabile.** La password ClickHouse di ogni organizzazione è derivata come `HMAC(ORG_CH_SECRET, org_id)`, quindi il default di sviluppo pubblicamente noto incorporato comporterebbe credenziali per organizzazione pubblicamente derivabili. `agenteye-orgctl org create` **rifiuta di eseguire mentre `ORG_CH_SECRET` non è impostato o è lasciato al default di sviluppo incorporato**. Imposta prima il tuo valore (consulta [Deployment → environment variables](/it/agenteye/deployment) e, su Kubernetes, [§2.6 della guida Kubernetes](/it/agenteye/kubernetes-deployment#26-multi-tenant-org-isolation-key-optional)). Mantienilo identico su tutte le repliche del server e non ruotarlo casualmente; ruotarlo lascia orfano ogni utente ClickHouse dell'organizzazione fino al prossimo avvio che li fornisce di nuovo. *** ## Esecuzione della CLI `agenteye-orgctl` è spedito nella **stessa immagine del server** (insieme a `agenteye-server`). **Non** distribuisci un pod, Job o Deployment separato per questo; lo esegui all'interno del pod server già in esecuzione, così legge lo stesso `DATABASE_URL`, `CLICKHOUSE_URL` e `ORG_CH_SECRET` che usa il server. **Kubernetes:** ```bash theme={null} kubectl -n agenteye exec deploy/server -- agenteye-orgctl ``` **Docker Compose:** ```bash theme={null} docker compose exec server agenteye-orgctl ``` Gli esempi seguenti mostrano il semplice `agenteye-orgctl ` per brevità; anteponi a ciascuno la riga corrispondente tra le due sopra che corrisponde alla tua distribuzione. *** ## Riferimento dei comandi ### Organizzazioni | Comando | Cosa fa | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `org create --slug --name ` | Crea una nuova organizzazione. Rifiuta di eseguire mentre `ORG_CH_SECRET` non è impostato o è lasciato al default di sviluppo incorporato (imposta prima il tuo valore, consulta Prerequisiti). Fornisce l'utente ClickHouse in sola lettura dell'organizzazione + policy per riga. | | `org list` | Elenca tutte le organizzazioni (slug, nome e stato del ciclo di vita). | | `org rename --slug --name ` | Cambia il nome visualizzato di un'organizzazione. Lo slug (usato negli URL e nelle chiavi) rimane invariato. | | `org delete --slug ` | **Soft-delete** dell'organizzazione e rimozione del suo utente ClickHouse. I dati sono **conservati**. Questo revoca l'accesso e libera le credenziali ClickHouse per organizzazione, ma non cancella gli eventi. Reversibile da parte dei responsabili; primo passo sicuro prima di una cancellazione. | | `org purge --slug ` | **Cancellazione dei dati irreversibile.** L'organizzazione deve già essere `delete`d. Mai consentito nell'organizzazione `default` incorporata. Usa solo quando sei sicuro che i dati del tenant dovrebbero essere distrutti. | ### Membri | Comando | Cosa fa | | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `member add --org --email [--set ] [--add perm1,perm2] [--remove perm3] [--protected]` | Aggiungi un membro a un'organizzazione. Facoltativamente inizia da un set di permessi incorporato, quindi aggiungi/rimuovi autorizzazioni individuali. `--protected` fissa il membro in modo che il dashboard non possa rimuoverlo o degradarlo (vedi sotto). Il nuovo membro riceve un OTP al primo accesso al dashboard. | | `member list --org ` | Elenca i membri dell'organizzazione. Le colonne di output sono `EMAIL`, `SET` (il set incorporato da cui il membro ha iniziato, o `-`), `PROT` (se il membro è protetto), e `PERMISSIONS` (le loro autorizzazioni effettive). Un'email mostrata con un `*` finale è un amministratore dell'istanza; hanno accesso a ogni organizzazione. | | `member update --org --email [--set ...] [--add ...] [--remove ...] [--protected \| --unprotect]` | Cambia le autorizzazioni di un membro e/o il flag protetto. `--set` sostituisce da un set incorporato; `--add` / `--remove` regolano autorizzazioni individuali; `--protected` / `--unprotect` attivano la protezione. Passare solo `--protected`/`--unprotect` (nessun flag di concessione) cambia solo la protezione e lascia intatte le autorizzazioni esistenti. | | `member remove --org --email ` | Rimuovi un membro dall'organizzazione. Rifiuta se il membro è protetto; `--unprotect` prima. (Una persona può essere membro di più organizzazioni; questo colpisce solo l'organizzazione denominata.) | Una persona può essere membro di più di un'organizzazione con **autorizzazioni diverse** in ciascuna, ad es. un amministratore in un'organizzazione e sola lettura in un'altra. Ogni appartenenza è amministrata indipendentemente per organizzazione: concedere o modificare le autorizzazioni di una persona in un'organizzazione non ha alcun effetto sulla loro appartenenza in qualsiasi altra. ### Membri protetti (un amministratore dell'organizzazione rimovibile) La protezione garantisce che un'organizzazione non possa mai accidentalmente bloccarsi dalla gestione autonoma. Per impostazione predefinita, gli amministratori di un'organizzazione possono aggiungere e rimuovere l'uno l'altro attraverso la pagina self-service degli utenti del dashboard, quindi potrebbero rimuovere l'ultimo amministratore e lasciare l'organizzazione senza nessuno in grado di gestirla. La pagina Utenti: una scheda per utente del dashboard con la loro email, autorizzazioni concesse e controlli di modifica/disabilitazione Per evitare ciò, contrassegna un membro come **protetto**: ```bash theme={null} kubectl -n agenteye exec deploy/server -- \ agenteye-orgctl member add --org acme --email owner@acme.example --set admin --protected ``` Un membro protetto **non può essere rimosso o degradato tramite il dashboard**; queste azioni restituiscono un errore. Solo un operatore può modificarli, e solo tramite questa CLI: esegui prima `member update --org acme --email owner@acme.example --unprotect`, quindi rimuovi o degrada. Questo garantisce che ogni organizzazione mantenga almeno un amministratore che i suoi stessi membri non possono bloccare, mantenendo il controllo del tenant solo per l'operatore. La protezione è **per organizzazione**; proteggere qualcuno in un'organizzazione non ha alcun effetto sulla sua appartenenza in un'altra. ### Set di autorizzazioni incorporati `--set` accetta uno di tre set incorporati, applicato per organizzazione: | Set | Previsto per | | ----------- | -------------------------------------------------------------------------------------------------------------------------- | | `admin` | Accesso completo all'interno dell'organizzazione, inclusa la gestione delle chiavi API e degli utenti dell'organizzazione. | | `standard` | Uso quotidiano: lettura + esecuzione di query, creazione di dashboard, riconoscimento degli incidenti. | | `read-only` | Accesso in sola lettura ai dati e ai dashboard dell'organizzazione. | Inizia da un set con `--set`, quindi affina con `--add` / `--remove` usando i token di autorizzazione individuali elencati in [API Keys](/it/agenteye/api-keys). I token di autorizzazione stessi sono identici a quelli utilizzati per le chiavi API. *** ## Esempio pratico Fornisci un nuovo tenant `acme`, aggiungi il suo primo amministratore, consentigli di creare una chiave, quindi disattiva l'organizzazione. **1. Crea l'organizzazione** (`ORG_CH_SECRET` deve già essere impostato su un valore forte e stabile, non non impostato o il default di sviluppo incorporato): ```bash theme={null} kubectl -n agenteye exec deploy/server -- \ agenteye-orgctl org create --slug acme --name "Acme Corp" ``` **2. Aggiungi il primo membro come amministratore dell'organizzazione:** ```bash theme={null} kubectl -n agenteye exec deploy/server -- \ agenteye-orgctl member add --org acme --email alice@acme.example --set admin ``` Alice riceve un OTP la prima volta che accede al dashboard. Da allora in poi lavora interamente nell'interfaccia utente sotto il prefisso URL della sua organizzazione (ad es. `/acme/sessions`). **3. Crea una chiave API per organizzazione (nel dashboard):** L'operatore **non** crea chiavi di dati per organizzazione dalla CLI. Alice (o qualsiasi membro dell'organizzazione con `keys:create`) crea chiavi di raccoglitore / dashboard per l'organizzazione `acme` dalla pagina **Keys** del dashboard. Ogni chiave che crea è automaticamente contrassegnata con la sua organizzazione e può leggere o scrivere solo i dati dell'`acme`. Consulta [API Keys](/it/agenteye/api-keys). **4. Regola un membro in seguito:** ```bash theme={null} kubectl -n agenteye exec deploy/server -- \ agenteye-orgctl member update --org acme --email alice@acme.example --add alerts:write kubectl -n agenteye exec deploy/server -- \ agenteye-orgctl member list --org acme ``` **5. Soft-delete dell'organizzazione** (revoca l'accesso + rimuove il suo utente ClickHouse; dati conservati): ```bash theme={null} kubectl -n agenteye exec deploy/server -- \ agenteye-orgctl org delete --slug acme ``` **6. Cancella l'organizzazione** (irreversibile; solo dopo un soft-delete; mai l'organizzazione `default`): ```bash theme={null} kubectl -n agenteye exec deploy/server -- \ agenteye-orgctl org purge --slug acme ``` Su Docker Compose, sostituisci ogni prefisso `kubectl -n agenteye exec deploy/server --` con `docker compose exec server`. *** ## Divisione delle responsabilità Tutto ciò che un membro dell'organizzazione ha bisogno quotidianamente è self-service nel dashboard e nell'API, limitato automaticamente alla loro organizzazione attuale: * **Le chiavi API per organizzazione** sono create e gestite dai membri dell'organizzazione nel dashboard (o tramite l'API delle chiavi con una chiave che porta `keys:create`). La CLI **non** crea chiavi di dati. Consulta [API Keys](/it/agenteye/api-keys). * **Il cambio di organizzazione** è incorporato nel dashboard; i membri passano tra le organizzazioni a cui appartengono dal selettore di organizzazione, e le pagine limitate all'organizzazione vivono sotto `//…`. * **Dashboard, query salvate, avvisi e tutti gli usi dei dati** avvengono interamente nell'interfaccia utente e nell'API, limitati all'organizzazione corrente del membro. L'operatore, utilizzando `agenteye-orgctl`, possiede solo il **ciclo di vita** dell'organizzazione + membro: crea / rinomina / elimina / cancella un'organizzazione, e aggiungi / elenca / aggiorna / rimuovi un membro. *** ## Vedi anche * [Deployment](/it/agenteye/deployment): `ORG_CH_SECRET` e il resto dell'ambiente del server. * [Kubernetes Deployment](/it/agenteye/kubernetes-deployment): §2.6 crea il Secret `agenteye-org-ch-secret` prima della tua prima organizzazione multi-tenant. * [API Keys](/it/agenteye/api-keys): il modello di chiave per organizzazione e i token di autorizzazione utilizzati da `--add` / `--remove`. * [Troubleshooting](/it/agenteye/troubleshooting): problemi di provisioning multi-tenant e isolamento ClickHouse.