CI / Build and test (SQLite) (pull_request) Successful in 55s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 5s
CI / Docker image (pull_request) Failing after 2m4s
The instance now starts on its own from KHAEMHAT_* variables: it migrates the system and company databases, creates the super user and the first company, and only then reports ready. Users sign in with password and TOTP through revocable database sessions, and licences decide which modules and how many companies are available. - Configuration: every wrong variable reported at once (exit code 2), _FILE variants - Accounts, password policy and lockout, TOTP with recovery codes, session states with token rotation, security audit with a hash chain - Sign-in pages (mockups 001-003), authorization attributes, security headers and a CSP without inline scripts, login rate limit - Signed licences, activation codes, test mode, licence tool - DataProtection keys in the system database, encrypted with the instance key - Memory or Redis cache (in-house RESP client) that falls back to memory - Database log by section with trace id; cron scheduler with locks and system jobs; record history (audit_log) - Company creation, states, company context and X-Company, 503 in maintenance - In-memory SQLite databases stay alive for the process (tests, demo) - Tests for all of the above, ADR 0019, wiki, SECURITY, CHANGELOG, STATUS, DATA-MODEL Refs #15 #16 #17 #18 #19 #20 #21 #22 #23 #24 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
227 lines
13 KiB
Markdown
227 lines
13 KiB
Markdown
# Istanza e database
|
|
|
|
> **Stato:** parziale · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.2.0 (milestone M2 e M12)
|
|
> **Modulo di licenza:** CORE (aziende oltre la prima: MULTI) · **Livello richiesto:** amministratore; azioni distruttive solo super utente · **Specifica:** SPEC §5.3, §5.4, §7.1, §12.1, §13
|
|
|
|
> **Nella versione 0.2.0** ci sono la creazione della prima azienda al primo avvio, la creazione e il collegamento
|
|
> di altre aziende (dal codice, con il modulo MULTI), gli stati *attiva / manutenzione / sola lettura / disattivata*
|
|
> con le sessioni chiuse quando un'azienda va in manutenzione e il contesto azienda per pagine e API (header
|
|
> `X-Company`). Le schermate descritte qui arrivano in M12.
|
|
|
|
## A cosa serve
|
|
|
|
Un'installazione di Khaemhat (una **istanza**, cioè un container) può servire più aziende. Ogni azienda ha il
|
|
**proprio database**; tutte condividono un unico **database di sistema** che contiene solo l'amministrazione.
|
|
La pagina **Istanza e database** è il punto da cui si vedono tutti i database dell'istanza e da cui si creano,
|
|
collegano, clonano, migrano, mantengono ed eliminano le aziende.
|
|
|
|
| Database | Nome | Cosa contiene |
|
|
|---|---|---|
|
|
| **Database di sistema** | `khaemhat_system` (variabile `KHAEMHAT_SYSTEM_DB`) | elenco delle aziende con la loro connessione (cifrata), super utente e amministratori, modelli dei ruoli, impostazioni di sistema, licenze e storico attivazioni, attività programmate e loro esecuzioni, politiche e insiemi di backup, log applicativo, audit di sicurezza, chiavi di protezione dei cookie, chiavi API di istanza, notifiche e sessioni degli account di istanza |
|
|
| **Database aziendale** | `khaemhat_<codice>` (es. `khaemhat_demo`) | tutti i dati operativi dell'azienda (anagrafiche, documenti, magazzino, contabilità…), i suoi **utenti**, ruoli e permessi, sessioni, preferenze, chiavi API, notifiche, allegati, storico delle modifiche (`audit_log`) e profilo azienda |
|
|
|
|
Le aziende condividono **solo** l'amministrazione: un utente aziendale vive nel database della sua azienda e non
|
|
vede le altre. Le tabelle operative non hanno un campo "azienda": la separazione è data dal database stesso.
|
|
|
|
## Dove si trova
|
|
|
|
**Amministrazione → Istanza e database**. Il menu **Amministrazione** è visibile solo agli account di istanza
|
|
(super utente e amministratori). Facendo doppio clic su un database si apre il suo **dettaglio** in una nuova scheda.
|
|
|
|
## Schermate
|
|
|
|

|
|
|
|
*Mockup 078 — elenco dei database dell'istanza (sistema, aziende, ambiente di prova, archivio SQLite in sola
|
|
lettura) con server, dimensione, stato dello schema, ultimo backup e stato; sotto, le informazioni sul server
|
|
PostgreSQL e i riquadri informativi (anteprima ridotta)*
|
|
|
|

|
|
|
|
*Mockup 079 — dettaglio del database `khaemhat_demo`: schede Backup e ripristino, Manutenzione, Migrazioni, Utenti
|
|
dell'azienda, Connessione; politica di backup, backup disponibili, verifica integrità e ricostruzioni (anteprima
|
|
ridotta)*
|
|
|
|
### L'elenco dei database (078)
|
|
|
|
| Colonna | Significato |
|
|
|---|---|
|
|
| **Database** | nome fisico (`khaemhat_system`, `khaemhat_demo`, …); clic per aprire il dettaglio |
|
|
| **Azienda / uso** | ragione sociale o uso (sistema, ambiente di prova, archivio) |
|
|
| **Server** | motore e versione (PostgreSQL o SQLite) e indirizzo del server o percorso del file |
|
|
| **Dimensione** | spazio occupato |
|
|
| **Schema** | *Allineato* oppure numero di migrazioni in attesa |
|
|
| **Ultimo backup** | data e ora dell'ultimo backup riuscito |
|
|
| **Stato** | *Attiva*, *Manutenzione*, *Sola lettura*, *Disattivata*; per le aziende attive anche gli utenti collegati |
|
|
| **Note** | ad esempio *predefinita*, *clonata da…*, modulo richiesto |
|
|
|
|
In alto a destra: **Nuova azienda (database)** e **Collega database esistente**. Nella barra a icone: **Backup
|
|
adesso**, **Clona**, **Elimina** e le altre azioni sul database selezionato.
|
|
|
|
### Il dettaglio del database (079)
|
|
|
|
Intestazione con dimensione, numero di migrazioni applicate e ultimo backup. Azioni principali: **Backup adesso**,
|
|
**Ripristina…**, **Prova di ripristino**. Schede:
|
|
|
|
- **Backup e ripristino** — politica di backup, elenco dei backup, ripristino: vedi [Backup e ripristino](Backup-e-ripristino).
|
|
- **Manutenzione** — verifica integrità, ricostruzioni, operazioni sul motore (vedi sotto).
|
|
- **Migrazioni** — migrazioni applicate e in attesa per modulo.
|
|
- **Utenti dell'azienda** — gli utenti che vivono in quel database (vedi [Utenti e permessi](Utenti-e-permessi)).
|
|
- **Connessione** — motore e parametri di connessione (la stringa di connessione è conservata cifrata).
|
|
|
|
## Chi può fare cosa
|
|
|
|
| Operazione | Amministratore | Super utente |
|
|
|---|---|---|
|
|
| Vedere l'elenco dei database e i dettagli | sì | sì |
|
|
| Applicare le migrazioni | sì | sì |
|
|
| Manutenzione del database, verifica integrità, ricostruzioni, statistiche | sì | sì |
|
|
| Backup, copie remote, verifica e prova di ripristino | sì | sì |
|
|
| Ripristino di un backup | avvia la richiesta | **conferma** (notifica + codice TOTP) |
|
|
| **Nuova azienda**, **Collega database esistente**, **Clona** | no | sì |
|
|
| **Modalità manutenzione** di un'azienda | no | sì |
|
|
| **Elimina** un database aziendale | no | sì |
|
|
|
|
La tabella segue SPEC §7.1. Il server verifica sempre il livello: un pulsante non disponibile non compare.
|
|
|
|
## Come si usa
|
|
|
|
### Creare una nuova azienda
|
|
|
|
1. Apri **Amministrazione → Istanza e database** e premi **Nuova azienda (database)**.
|
|
2. Indica **codice** e **ragione sociale** dell'azienda e il **motore**: PostgreSQL (consigliato) oppure SQLite.
|
|
3. Conferma. Khaemhat:
|
|
- su PostgreSQL esegue `CREATE DATABASE khaemhat_<codice>` sul server indicato da `KHAEMHAT_DB_SERVER` (il ruolo
|
|
deve avere il privilegio `CREATEDB`); con SQLite crea il file nella cartella dati;
|
|
- applica le migrazioni dell'azienda;
|
|
- carica le **tabelle di base** (paesi, comuni, codici IVA, piano dei conti…; vedi [Dati di base e di esempio](Dati-di-base-e-esempio)).
|
|
4. Completa il profilo nella nuova azienda (**Tabelle azienda → Profilo azienda**, vedi [Tabelle azienda](Tabelle-azienda))
|
|
e crea i suoi utenti.
|
|
|
|
Oltre la prima azienda serve il modulo **MULTI** e la licenza deve consentire il numero di aziende
|
|
(`maxCompanies`); senza, il pulsante segnala il modulo mancante. Vedi [Licenze e moduli](Licenze-e-moduli).
|
|
|
|
### Collegare un database esistente
|
|
|
|
Serve per riportare nell'istanza un database già pronto (ad esempio spostato da un altro server).
|
|
|
|
1. Premi **Collega database esistente**.
|
|
2. Inserisci codice, ragione sociale e **stringa di connessione** del database.
|
|
3. Khaemhat verifica la connessione e lo stato dello schema; se mancano migrazioni le propone.
|
|
|
|
La stringa di connessione viene salvata **cifrata** (AES-256-GCM con la chiave `KHAEMHAT_SECRET_KEY`).
|
|
|
|
### Clonare un'azienda (ambiente di prova)
|
|
|
|
1. Seleziona l'azienda e premi **Clona**.
|
|
2. Scegli il backup da cui partire.
|
|
3. Khaemhat ripristina il backup in un nuovo database chiamato `khaemhat_<codice>_test` e lo aggiunge all'elenco
|
|
come ambiente di prova (nota *clonata da…*).
|
|
|
|
Il clone è un'azienda a tutti gli effetti, utile per provare procedure (chiusura d'esercizio, import) senza toccare i
|
|
dati reali. Ricordati che i canali SDI e le e-mail del clone vanno controllati prima di usarlo.
|
|
|
|
### Eliminare un'azienda
|
|
|
|
1. Seleziona l'azienda e premi **Elimina** (solo super utente).
|
|
2. Khaemhat esegue **automaticamente un backup preventivo**.
|
|
3. Conferma **scrivendo il nome del database**.
|
|
4. Il database viene eliminato; il file del backup preventivo resta nel **cestino per 30 giorni**.
|
|
|
|
**Attenzione:** è l'unica operazione che cancella un intero database. Prima di procedere verifica che il backup
|
|
preventivo sia andato a buon fine e, se l'azienda è un archivio, valuta lo stato *Sola lettura* invece
|
|
dell'eliminazione.
|
|
|
|
### Applicare le migrazioni
|
|
|
|
Le migrazioni sono gli aggiornamenti dello schema del database portati da una nuova versione di Khaemhat.
|
|
|
|
- Il **database di sistema** viene migrato sempre all'avvio del container.
|
|
- I **database aziendali** vengono migrati all'avvio oppure dal pannello, secondo un'impostazione di sistema.
|
|
- Dal pannello: seleziona il database (colonna **Schema** con *N migrazioni in attesa*) e scegli **Applica
|
|
migrazioni**; durante l'operazione l'azienda è messa in **modalità manutenzione**.
|
|
- Ogni database tiene la propria tabella `schema_version` (modulo, versione, nome, data, checksum). L'esito finisce
|
|
nel [Log](Log), sezione *Migrazioni*.
|
|
- Le migrazioni sono transazionali e idempotenti. **Il ritorno a una versione precedente non è supportato**: se un
|
|
database contiene migrazioni sconosciute alla versione in esecuzione (ad esempio dopo un downgrade dell'immagine),
|
|
Khaemhat si rifiuta di partire. Per tornare indietro serve il ripristino di un backup (vedi [Aggiornamento](Aggiornamento)).
|
|
|
|
### Manutenzione del database
|
|
|
|
Nella scheda **Manutenzione** del dettaglio:
|
|
|
|
| Operazione | Cosa fa |
|
|
|---|---|
|
|
| **Verifica integrità** | controlli applicativi: chiavi esterne orfane, totali documento = righe, giacenze = movimenti, partite = scadenze - incassi, registrazioni non quadrate; mostra l'esito e il numero di anomalie |
|
|
| **Ricostruzioni** | ricalcolo di giacenze, partite, totali documenti, numeratori, saldi dei conti |
|
|
| **Manutenzione del motore** | PostgreSQL: `VACUUM ANALYZE`, `REINDEX`; SQLite: `integrity_check` |
|
|
| **Statistiche tabelle** | righe e spazio per tabella |
|
|
|
|
Queste operazioni possono essere pianificate come [Attività programmate](Attivita-programmate) di tipo *verifica* o
|
|
*script di manutenzione* (sempre dal catalogo interno, mai comandi liberi).
|
|
|
|
### Modalità manutenzione di un'azienda
|
|
|
|
La modalità manutenzione mette un'azienda "a riposo" per operazioni delicate (migrazioni, ripristino):
|
|
|
|
- gli utenti collegati vengono **disconnessi** e non possono rientrare;
|
|
- le chiamate API per quell'azienda ricevono **503**;
|
|
- le altre aziende dell'istanza continuano a funzionare.
|
|
|
|
La attiva il super utente; Khaemhat la attiva da solo durante migrazioni dal pannello e ripristini. Il pulsante
|
|
**Modalità manutenzione** è disponibile anche in [Stato sistema](Stato-sistema).
|
|
|
|
## Stati di un'azienda
|
|
|
|
| Stato | Significato |
|
|
|---|---|
|
|
| **Attiva** | uso normale |
|
|
| **Manutenzione** | accesso sospeso agli utenti, API 503 (vedi sopra) |
|
|
| **Sola lettura** | i dati si consultano ma non si modificano: tipico per archivi di esercizi passati (ad esempio un archivio SQLite) |
|
|
| **Disattivata** | l'azienda resta registrata ma non è utilizzabile |
|
|
|
|
Un'azienda può essere marcata **predefinita**: è quella proposta alla pagina di accesso.
|
|
|
|
## Informazioni sul server PostgreSQL
|
|
|
|
Il riquadro **Server PostgreSQL** (078) mostra:
|
|
|
|
| Voce | Esempio nel mockup |
|
|
|---|---|
|
|
| Server e versione | `khaemhat-db:5432` · PostgreSQL 17 (minima richiesta 16) |
|
|
| Ruolo applicativo | `khaemhat` — `CREATEDB` sì, superuser no |
|
|
| Connessioni | in uso sul massimo, con il pool per database |
|
|
| Spazio dati | occupazione del volume di PostgreSQL |
|
|
| Spazio `/data` | occupazione della cartella dati di Khaemhat (allegati, backup, inbox) |
|
|
| Versione client | `pg_dump` / `pg_restore` 17 inclusi nell'immagine |
|
|
| Estensioni | estensioni presenti (es. `pg_stat_statements`) |
|
|
|
|
Se la versione del server è **inferiore a 16** compare un avviso. Il client nell'immagine è la versione 17:
|
|
funziona con server 16 e 17; per un server 18 serve un'immagine aggiornata.
|
|
|
|
Il server può essere sullo stesso host Docker o remoto/gestito: basta la stringa di connessione. **SQLite** è
|
|
pensato per demo, prova e archivi in sola lettura; per le installazioni reali si usa PostgreSQL.
|
|
|
|
## Il primo avvio
|
|
|
|
Al primo avvio il container: migra il database di sistema → crea il super utente da `KHAEMHAT_SUPERUSER*` → crea
|
|
la prima azienda da `KHAEMHAT_COMPANY_CODE` / `KHAEMHAT_COMPANY_NAME` → la migra → carica le tabelle di base → carica
|
|
i dati di esempio se richiesto. Le variabili vengono rilette solo se la tabella corrispondente è vuota: dopo il
|
|
primo avvio le aziende si gestiscono da questa pagina. Dettagli in [Primi passi](Primi-passi).
|
|
|
|
## Domande frequenti e attenzione
|
|
|
|
- **Posso ripristinare il database di sistema dal pannello?** No: il database di sistema si ripristina solo da riga
|
|
di comando (`scripts/restore-system.sh`) con l'istanza ferma. Vedi [Backup e ripristino](Backup-e-ripristino).
|
|
- **Perché non vedo "Elimina" o "Nuova azienda"?** Sono riservati al super utente.
|
|
- **Il codice dell'azienda si può cambiare?** Il codice determina il nome del database: comportamento in caso di
|
|
modifica da definire in sviluppo.
|
|
- **Il numero massimo di connessioni per database** si regola nelle impostazioni di sistema (pool separato per
|
|
database).
|
|
|
|
## Pagine correlate
|
|
|
|
[Backup e ripristino](Backup-e-ripristino) · [Licenze e moduli](Licenze-e-moduli) · [Utenti e permessi](Utenti-e-permessi) ·
|
|
[Stato sistema](Stato-sistema) · [Impostazioni](Impostazioni) · [Dati di base e di esempio](Dati-di-base-e-esempio) ·
|
|
[Aggiornamento](Aggiornamento) · [Architettura](Architettura)
|