HQbird 2027 in Docker: guida dell'amministratore
Questa guida è per l’amministratore che esegue HQbird 2027 in Docker. Un container è un’istanza Firebird con tutti i componenti di HQbird:
- Firebird (la compilazione HQbird di una linea: 5.0, 4.0, 3.0 o 2.5);
- agente HQbird (
fbagent): backup, monitoraggio, lavori di manutenzione, aggiornamenti, la connessione a HQCenter; - HQ Monitor: la console web dell’istanza;
- nodo di cluster (
hqclusternode) e RCM (hqbirdrcm): li installa l’agente quando HQCenter aggiunge questa istanza a un cluster, oppure quando assegni al container un ruolo di cluster (sezione 7). Senza un ruolo e senza HQCenter, il container non esegue alcun componente di cluster.
Il container installa HQbird con lo stesso installatore offline di un server (guida all’installazione su Linux). L’agente aggiorna poi Firebird, HQ Monitor, i componenti del cluster e se stesso da HQCenter, come su un server. I dati, la configurazione, la licenza, i certificati di HQCenter e i programmi aggiornati sono sui volumi: restano quando ricrei il container o cambi l’immagine.
Versione attuale: 2027.2.33 (2026-11-16): Firebird 2.5.9, 3.0.15, 4.0.8 e 5.0.5, agente 3.4.0, HQ Monitor 1.57.0, RCM e nodo 2027.5.12.
Testato il 2026-11-16 su Ubuntu 22.04.5 (2 vCPU / 4 GB), Docker 29.10.0,
Compose 5.7.1, immagine hqbird2027-fb40:2027.2.33 (prima prova: 2026-11-11,
immagine 2027.2.27). Un’installazione passo per passo
per Ubuntu 22.04: hqbird2027-docker-install-fb40.ru.md
(russo), hqbird2027-docker-install-fb40.pt.md
(portoghese).
Il ruolo di cluster (sezione 7.1) e lo switchover (sezione 7.3) sono stati testati
il 2026-11-16 sulle immagini 5.0, 4.0, 3.0 e 2.5, con i due «host»
come due indirizzi di una VM, e su due host Docker separati (due droplets, l’immagine
4.0 2027.2.33). Il 2026-11-17 il resto è stato testato su due host Docker
con l’immagine 5.0 2027.2.33: un cluster fatto a mano in container 2027.2.32
e spostato sulla nuova immagine (entrambi i container healthy in 35
secondi), HQBIRD_RCM_ALLOW, le pagine Services della console RCM e
il failover automatico. I router (HAProxy) non si avviano nelle immagini fino a
2027.2.33 (sezione 9); l’immagine successiva contiene la correzione.
1. Immagini
| Immagine | Firebird | Porta predefinita |
|---|---|---|
ghcr.io/ibsurgeon/hqbird2027-fb50:<version> |
5.0 | 3050 |
ghcr.io/ibsurgeon/hqbird2027-fb40:<version> |
4.0 | 3050 |
ghcr.io/ibsurgeon/hqbird2027-fb30:<version> |
3.0 | 3050 |
ghcr.io/ibsurgeon/hqbird2027-fb25:<version> |
2.5 | 3050 |
Le immagini sono nel GitHub Container Registry di IBSurgeon
(https://github.com/orgs/IBSurgeon/packages). Sono pubbliche: non serve
accedere. <version> è la versione di setup di HQbird, per esempio
2027.2.33. L’etichetta 2027.2 è l’immagine 2027.2.x più recente.
docker pull ghcr.io/ibsurgeon/hqbird2027-fb50:2027.2.33Le immagini sono firmate con cosign. La chiave pubblica hqbird-cosign.pub non è
ancora pubblicata (2026-11-16). Le immagini 2027.2.33 sono firmate. Quando hai la chiave, controlla un’immagine
prima di usarla:
cosign verify --key hqbird-cosign.pub ghcr.io/ibsurgeon/hqbird2027-fb50:2027.2.332. Primo avvio
-
Copia
compose.yaml(daops/docker/della versione) in una cartella sull’host Docker. -
Metti la password SYSDBA in un file, leggibile solo da te:
mkdir -p secrets && openssl rand -hex 12 > secrets/sysdba_password && chmod 600 secrets/sysdba_password -
In
compose.yaml, impostaimage:,hostname:e togli il#dalle righesecrets:che usi. -
Avvia il container:
docker compose up -d -
Segui l’installazione (qualche minuto al primo avvio):
docker compose logs -fSu 2 vCPU l’installazione richiede circa 20 secondi. È finita quando il log mostra
[hqbird-boot] ready: firebird.service=active ...edocker compose psmostrahealthy.
Poi:
- Firebird:
<docker host>:3050. - HQ Monitor:
http://<docker host>:23050/, utenteadmin. L’installatore crea la password; leggila condocker compose exec hqbird cat /opt/hqbird/conf/access.properties. - L’id dell’agente in HQCenter: il nome host + la data di installazione (YYMMDD) +
-fbNN, per esempiohqbird-fb40-3051261111-fb40.
Conserva il nome host. L’identità di licenza dell’istanza è il
machine-id sul volume state e l’id dell’agente. Un nuovo volume state è
una nuova installazione.
3. Impostazioni
Le impostazioni si leggono solo al primo avvio (l’installazione).
| Impostazione | Che cosa fa |
|---|---|
HQBIRD_FB_PORT |
Porta Firebird dentro il container (predefinito 3050). HQ Monitor usa 20000 + questa porta |
HQBIRD_HQM_PORT |
un’altra porta di HQ Monitor |
HQBIRD_AGENT_ID |
l’id dell’agente (predefinito: ricavato dal nome dell’host, dalla data e dalla porta) |
HQBIRD_HQM_LOGIN + segreto hqmonitor_password |
l’utente di HQ Monitor |
HQBIRD_TRIAL_EMAIL, HQBIRD_TRIAL_ZONE |
chiedere una licenza di prova (accetti l’informativa sulla privacy) |
HQBIRD_DEBUG=1 |
installare i file di debug di Firebird |
segreto sysdba_password |
la password SYSDBA di un nuovo Firebird |
segreto license |
un file di licenza |
segreto attach |
attach.json da HQCenter: collegare l’agente al tuo HQCenter |
HQBIRD_CLUSTER_ROLE |
master o replica: un cluster senza HQCenter (sezione 7). Vuoto: nessun cluster |
HQBIRD_CLUSTER_ADDRESS |
master, obbligatorio: l’indirizzo o il nome DNS dell’host Docker, come li raggiungono il replica e il browser. Un elenco separato da virgole; il primo entra nel RCM URL |
HQBIRD_CLUSTER_ID |
master: l’id del cluster (predefinito: il nome dell’host) |
segreto rcm_password |
master: la password dell’utente RCM rcmadmin (predefinito: una generata) |
HQBIRD_RCM_ALLOW |
replica: solo questi RCM possono invitare il container (IP, CIDR, nome host; predefinito: qualunque). Scrivi l’indirizzo dell’host Docker del master: il replica vede quell’indirizzo. Su un solo host Docker il replica vede il gateway della sua rete Docker |
HQBIRD_PAIRING_PORT, HQBIRD_NODE_PORT |
lo slot del cluster: porta di pairing 7450-7459 e porta del nodo = porta di pairing - 399 (predefinito 7450 e 7051) |
4. Volumi
| Volume | Percorso | Contenuto |
|---|---|---|
opt |
/opt |
Firebird, l’agente, HQ Monitor, nodo di cluster, RCM |
state |
/var/lib/hqbird-container |
units, sudoers, dati di HQ Monitor, log dell’agente, machine-id, stato del setup, gli account del sistema operativo creati durante l’esecuzione (l’utente di servizio RCM) |
trust |
/usr/libexec/hqbird-fbagent |
il programma di avvio degli aggiornamenti dell’agente e la fiducia |
rootwork |
/var/lib/hqbird-fbagent |
la cartella di lavoro del programma di avvio degli aggiornamenti |
db |
/db |
database (metti qui i tuoi database) |
backup |
/backup |
copie di backup |
Non montare cartelle dell’host su opt, state, trust e rootwork. Puoi
usare cartelle dell’host per db e backup; dalle all’uid 84 (l’utente firebird
dell’immagine):
chown 84:84 /srv/hqbird/db /srv/hqbird/backupFai il backup di tutti e sei i volumi insieme.
5. Lavoro quotidiano
| Attività | Comando |
|---|---|
| Stato dei servizi | docker compose exec hqbird systemctl list-units --type=service |
| Riavviare Firebird | docker compose exec hqbird systemctl restart firebird (Firebird 3.0: firebird-superserver) |
| isql | docker compose exec hqbird /opt/firebird/bin/isql -user SYSDBA localhost/<port>:/db/my.fdb |
| Log | docker compose logs --since 1h |
| Arresto (Firebird chiude i database) | docker compose stop |
Dentro il container, systemctl controlla i servizi HQbird. Non è
systemd: supporta i comandi che i programmi HQbird usano (start, stop,
restart, status, is-active, enable, disable, show,
list-units, daemon-reload).
6. Aggiornamenti
Ci sono due modi per aggiornare. Entrambi conservano i dati.
-
Da HQCenter (come su un server): HQCenter aggiorna l’agente, HQ Monitor, Firebird, il nodo di cluster e RCM dentro il container.
-
Nuova immagine: cambia
image:alla nuova versione, poi:docker compose pull && docker compose up -dAll’avvio, il container esegue l’installatore della nuova immagine in modalità di aggiornamento. Se HQCenter ha già aggiornato l’agente a una versione più recente di quella dell’immagine, l’installatore non viene eseguito (senza scendere di versione); il log lo dice.
Un nuovo container (una nuova immagine, oppure docker compose down e up -d senza
-v) conserva il cluster: il ruolo, l’id del cluster, RCM, i nodi e il
collegamento all’altro host sono sui volumi. Le impostazioni del cluster nel
file compose non vengono rilette. Le immagini fino a 2027.2.32 hanno due difetti
qui: vedi la sezione 9.
7. Cluster
Ci sono due modi per fare un cluster. Non mescolarli in uno stesso container.
7.1. Senza HQCenter: due container con un ruolo
Un container è il master ed esegue il gestore del cluster (RCM) con la sua
console. L’altro è un replica. Il ruolo è un’impostazione del primo
avvio: HQBIRD_CLUSTER_ROLE. Senza di esso il container non esegue RCM, non esegue
un nodo di cluster e non apre alcuna porta di pairing. Il ruolo richiede l’immagine 2027.2.33 o
successiva.
Due host Docker. Dai ai due container nomi host diversi
(HQBIRD_HOSTNAME in .env, oppure hostname:): con lo stesso nome host
i due agenti hanno lo stesso id, e RCM rifiuta il replica
(duplicate). Copia compose.master.yaml sull’host master e
compose.replica.yaml sull’host replica, accanto a compose.yaml
(ops/docker/ della versione).
-
Sull’host master, metti l’indirizzo di quell’host Docker in
.env, come lo raggiungono l’host replica e il browser (nonlocalhost, non l’indirizzo del container):echo 'HQBIRD_CLUSTER_ADDRESS=203.0.113.10' >> .env docker compose -f compose.yaml -f compose.master.yaml up -d -
Sull’host replica:
docker compose -f compose.yaml -f compose.replica.yaml up -d -
Leggi le righe di cluster di ogni container:
docker compose logs | grep -E 'cluster:|CA hash|Password'Il master mostra l’indirizzo della console e il
CA hash:[hqbird-boot] cluster: role=master id=... console=https://203.0.113.10:7444 login=rcmadmin. Il replica mostra la sua porta di pairing e l’impronta:[hqbird-boot] cluster: role=replica pairing port 7450: open until ..., fingerprint sha256:.... -
Apri la console
https://<master host>:7444. L’utente èrcmadmin. Senza il segretorcm_passwordla password è in un file; RCM ne chiede una nuova al primo accesso:docker compose exec hqbird sh -c 'cat /opt/hqbird/fbagent-*/clusterca/*/rcm-initial-password' -
In Settings → Link hosts scrivi due righe: l’indirizzo che hai indicato in
HQBIRD_CLUSTER_ADDRESS(il master) e l’indirizzo dell’host Docker del replica. Non scrivi una porta: RCM legge le porte di pairing 7450-7459. La porta di pairing risponde circa 30 secondi dopo che il container èhealthy. La finestra Initialize propone la cartella/databases/replica/..., che è fuori dai volumi: cambiala. Quella finestra è alta circa 1000 px e non scorre: riduci lo zoom della pagina se non ne vedi i pulsanti. Testato nel browser il 2026-11-16. Confronta l’impronta del replica con quella del suo log. Lascia RCM URL vuoto. Poi continua con il passaggio 4 della guida al cluster su Linux (cartella dei database, registrazione, inizializzare il replica). Per la cartella dei database del replica, usa una cartella del volumedb, per esempio/db/replica. Testato: una riga scritta sul master era sul replica in 30 secondi.
Per saltare le opzioni -f, metti
COMPOSE_FILE=compose.yaml:compose.master.yaml (oppure ...replica.yaml) in
.env.
Un host Docker. compose.cluster-one-host.yaml è un file completo
con entrambi i container:
docker compose -f compose.cluster-one-host.yaml up -dI container si raggiungono per nome sulla rete del progetto, quindi
le porte del cluster non sono pubblicate. In Link hosts scrivi
hqbird-master e hqbird-replica. Il Firebird del master è sulla porta
3050, quello del replica sulla 3051; la console è https://<docker host>:7444.
Regole:
- Il ruolo e le sue impostazioni si leggono solo al primo avvio. In seguito un
HQBIRD_CLUSTER_ROLEdiverso scrive un avviso nel log e non cambia nulla. Per cambiare il cluster in seguito, usa HQ Monitor (Clusters) oppure i comandifbagent --cluster-initefbagent --cluster-pairingdentro il container. - Un’impostazione errata (un ruolo sconosciuto, un master senza
HQBIRD_CLUSTER_ADDRESS, un’impostazione dell’altro ruolo) ferma l’avvio prima che venga installato qualcosa. Il log dice che cosa scrivere ([hqbird-boot] error: ...); Docker avvia di nuovo il container e il log ripete la riga finché non correggi l’impostazione. - La finestra di pairing di un replica resta aperta 24 ore. Un riavvio di un
container che non è ancora in nessun cluster la riapre. Per chiudere la
porta di pairing verso le altre reti, usa
HQBIRD_RCM_ALLOWo il firewall; dopo il collegamento puoi togliere la porta daports:. - Per uno switchover (un servizio RCM), ogni host ha bisogno di un secondo nodo e della sua porta pubblicata: vedi la sezione 7.3.
7.2. Con HQCenter
HQCenter aggiunge l’istanza a un cluster come aggiunge un server. Non impostare
HQBIRD_CLUSTER_ROLE. In HQCenter, indica l’indirizzo dell’host Docker
come indirizzo del membro. In compose.yaml, pubblica le porte dei
componenti del cluster:
| Componente | Porta | Pubblicare quando |
|---|---|---|
| nodo di cluster | il listen_port del nodo (per esempio 7051) |
l’istanza è un membro del cluster |
| RCM | 7443 | HQCenter fa di questo agente l’RCM |
| console operatore RCM | 7444 | come sopra; imposta operator_addr a 0.0.0.0:7444 nelle impostazioni di RCM |
L’agente installa il nodo (e RCM) qualche minuto dopo che il cluster è
salvato. Fino ad allora la porta del nodo non risponde.
In HQCenter, imposta il listen_port del nodo sulla porta pubblicata. Un replica aspetta finché l’agente RCM non carica la CA del cluster.
Testato il 2026-11-16 senza un ruolo: gli agenti hanno installato i nodi e RCM,
e tutti i membri erano di nuovo running dopo docker compose down e
up -d.
7.3. Switchover tra i due container
Un servizio RCM sposta il ruolo master di un database da un host all’altro. Per un servizio, ogni host ha bisogno di due nodi: un nodo master e un nodo replica. Link hosts dà a ogni host un nodo, quindi aggiungi tu i secondi nodi. Testato il 2026-11-16 sulla coppia della sezione 7.1: lo switchover ha richiesto 25 secondi, il vecchio master è diventato un replica in sola lettura, e una riga scritta sul nuovo master c’era 15 secondi dopo.
I passaggi usano l’API operatore di RCM sulla porta della console. curl chiede
la password di rcmadmin; -k salta il controllo del certificato proprio
del cluster:
RCM=https://203.0.113.10:7444
api() { curl -sk --digest -u rcmadmin -H 'Content-Type: application/json' "$@"; }-
Pubblica la porta del secondo nodo su entrambi gli host: porta del nodo + 10. In
compose.master.yamlecompose.replica.yaml, togli il#dalla riga"7061:7061", poi eseguidocker compose up -dcon le stesse opzioni-f. Fallo prima del primo avvio quando puoi. -
Dai a ogni nodo l’indirizzo del suo host Docker. RCM dà questo indirizzo e la porta Firebird alle applicazioni; senza di esso ottengono l’indirizzo del container:
api -X PUT $RCM/v1/nodes/<master node id>/config -d '{"advertise_addr":"203.0.113.10"}' api -X PUT $RCM/v1/nodes/<replica node id>/config -d '{"advertise_addr":"203.0.113.20"}'api $RCM/v1/nodesmostra gli id dei nodi (<host name>-master,<host name>-replica). -
Aggiungi i secondi nodi al documento del cluster: un nodo master sull’host replica e il suo nodo replica sull’host master, entrambi con
listen_port7061. Leggi il documento, aggiungi due membri e un link, e rimandalo con la sua revisione:api $RCM/v1/admin/clusters/<cluster id> > cluster.json # note "revision" # add to "members": # {"member_id":"<host B>-master","agent_id":"<agent id of host B>","role":"master","addresses":["203.0.113.20"],"listen_port":7061} # {"member_id":"<host A>-replica","agent_id":"<agent id of host A>","role":"replica","addresses":["203.0.113.10"],"listen_port":7061} # add to "links": {"from":"<host B>-master","to":"<host A>-replica"} api -X POST $RCM/v1/admin/clusters/<cluster id>/validate --data-binary @cluster.json api -X PUT -H 'If-Match: <revision>' $RCM/v1/admin/clusters/<cluster id> --data-binary @cluster.jsonGli agenti installano allora i due servizi di nodo (30 secondi nel test su due host; può richiedere alcuni minuti).
docker compose exec hqbird systemctl list-units --type=servicemostra allora due servizihqclusternodein ogni container.Poi dai a entrambi i nodi replica una cartella di database sul volume
db. Senza di essa, uno switchover di ritorno o un failover si ferma dopo il punto di non ritorno, e il servizio va afailed:for n in <host A>-replica <host B>-replica; do api -X POST $RCM/v1/nodes/$n/databases/root/prepare -d '{"root":"/db/replica"}' api -X PUT $RCM/v1/nodes/$n/config -d '{"databases":{"root":"/db/replica"}}' done -
Definisci il servizio.
hostè l’id dell’agente dell’host. Il percorso sul secondo host è il percorso del file del replica:<database folder of the replica>/<master member id>/<file>:cat > service.json <<'J' {"alias":"shop","router_port":3051,"members":[ {"host":"<agent id of host A>","master_node":"<host A>-master","replica_node":"<host A>-replica","path":"/db/shop.fdb","priority":100}, {"host":"<agent id of host B>","master_node":"<host B>-master","replica_node":"<host B>-replica","path":"/db/replica/<host A>-master/shop.fdb","priority":50}]} J api -X PUT "$RCM/v1/services/shop?check=1" --data-binary @service.json # a check, nothing is stored api -X PUT $RCM/v1/services/shop --data-binary @service.json -
Controlla, poi commuta:
api $RCM/v1/services/shop/master # the master now, the replicas, problems api -X POST $RCM/v1/services/shop/switchover/check -d '{}' api -X POST $RCM/v1/services/shop/switchover -d '{}' # gives "operation_id" api $RCM/v1/operations/<operation id>
Dopo lo switchover, .../services/shop/master dà l’indirizzo dell’altro
host Docker e la sua porta Firebird. Le applicazioni devono connettersi a
quell’indirizzo. Uno switchover ha bisogno di un replica che sia IN_SYNC: lo è, dopo
la prima scrittura sul master (35 secondi nel test).
Router e failover automatico. Un router (HAProxy) dà alle applicazioni un indirizzo che segue il master. Nelle immagini fino a 2027.2.33 il router non si avvia (sezione 9); l’immagine successiva contiene la correzione. Il failover automatico ha bisogno di un router come testimone. Testato il 2026-11-17 in laboratorio, su 2027.2.33 con una soluzione di ripiego e su un’immagine di test con la correzione:
-
Un router è un membro del cluster con il ruolo
router. L’agente installa il pacchettohaproxydal repository Debian, anche in ogni nuovo container: il container ha bisogno di accesso al repository. Pubblica la porta del router (3051 nell’esempio). -
Con un router solo sull’host RCM, RCM ha spostato il master da solo 84 secondi dopo che il container dell’altro host si è fermato; l’operazione ha richiesto 10 secondi. Quando quell’host è tornato,
rejoinlo ha reso di nuovo il replica. -
Con un router su ogni host il failover automatico non parte: più della metà dei router deve riferire, e uno dei due è sull’host perso.
-
L’RCM gira nel container master. Quando quell’host si perde, si perde anche l’RCM, e niente sposta il master da solo.
8. Porte, firewall, seconda istanza
Pubblica ogni porta con lo stesso numero fuori e dentro il container
(3051:3051, non 3051:3050). L’agente e il cluster riportano la porta
che vedono dentro il container.
| Porta | Cosa | Necessario |
|---|---|---|
HQBIRD_FB_PORT (3050) |
Firebird | sempre |
| 20000 + porta Firebird (23050) | HQ Monitor | sempre |
listen_port del nodo (7051) |
nodo di cluster | membro del cluster |
| porta del nodo + 10 (7061) | il secondo nodo dell’host | un servizio con switchover (sezione 7.3) |
| 7443, 7444 | RCM, console operatore RCM | questo agente è l’RCM (uno per host) |
| porta di pairing (7450) | la porta di pairing dell’agente | un replica con un ruolo, finché non è collegato |
L’agente si collega a HQCenter da solo (in uscita); non gli serve una porta in ingresso.
Docker pubblica le porte oltre ufw. Testato: con ufw che consentiva solo la porta 22,
le porte di Firebird e di HQ Monitor erano aperte da internet. Usa un
firewall esterno, pubblica su un indirizzo dell’host ("10.0.0.5:23050:23050"),
o aggiungi regole alla catena iptables DOCKER-USER.
Una seconda istanza su un host ha bisogno della propria cartella, del name: del progetto,
hostname, HQBIRD_FB_PORT e delle porte. Il nome del progetto forma i nomi dei
volumi (<name>_opt, …): con lo stesso nome, il secondo avvio prende i
volumi e il container del primo.
| Istanza 1 | Istanza 2 | |
|---|---|---|
name:, hostname: |
hqbird-fb40-3051 |
hqbird-fb40-3052 |
HQBIRD_FB_PORT |
3051 | 3052 |
ports: |
3051, 23051, 7052 | 3052, 23052, 7053 |
Regole per N istanze su un IP esterno:
- Firebird
3050 + N, HQ Monitor20000 +la porta Firebird, nodo di cluster7051 + N(imposta lo stessolisten_portin HQCenter). Salta 3050, 23050 e 7051 quando l’host esegue già un Firebird o HQbird fuori da Docker. - Solo un’istanza per host può essere l’RCM (7443, 7444).
- Con un ruolo di cluster (sezione 7.1), ogni istanza di un host ha bisogno del proprio
slot:
HQBIRD_PAIRING_PORT=7451eHQBIRD_NODE_PORT=7052per la seconda,7452e7053per la terza. - Un’istanza usa circa 200-250 MB di memoria senza carico. Testato: tre istanze FB 4.0 su 2 vCPU / 4 GB, una con carico.
- Le altre linee Firebird sullo stesso host seguono le stesse regole con la
propria immagine (
hqbird2027-fb50, …) e i nomi (hqbird-fb50-3054).
Aggiungi un’istanza (qui la terza: 3053, 23053, 7054) dal
compose.yaml della prima. Sostituire 3051 cambia anche name:, hostname:,
HQBIRD_FB_PORT e la porta di HQ Monitor:
sudo ss -ltnp | grep -E ':(3053|23053|7054)\b' # must print nothing
sudo mkdir -p /srv/hqbird-fb40-3053/secrets
cd /srv/hqbird-fb40-3053
sudo sh -c 'openssl rand -hex 12 > secrets/sysdba_password && chmod 600 secrets/sysdba_password'
sudo sed -e 's/3051/3053/g' -e 's/7052/7054/g' /srv/hqbird-fb40-3051/compose.yaml | sudo tee compose.yaml >/dev/null
sudo docker compose config | grep -E '^name:|hostname:|HQBIRD_FB_PORT|published:'
sudo docker compose up -d
sudo docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'9. Problemi noti
- Dopo aver collegato l’agente a HQCenter con
fbagent --enrolla mano, eseguifbagent --refresh-apply-launchercome root, oppure l’autoaggiornamento dell’agente fallisce con “no goafts CA is pinned”. - Negli script, esegui
docker compose execcon-Te</dev/null. Senza di essi legge lo standard input e prende il resto di uno script che invii conssh ... bash -s. - Prima che l’agente sia collegato a HQCenter, il suo log mostra gli avvisi
goafts mTLS settings are incompleteebootstrap CA not found. Questo è normale. - Il container assegna
/opt/hqbirda root dopo ogni installazione (l’autoaggiornamento dell’agente ne ha bisogno). L’agente scrive un avviso: non può aggiornare/opt/hqbird/version.json; puoi ignorarlo. - Immagini fino a 2027.2.32: cartelle aperte in scrittura. In queste immagini
/etc,/usre/usr/libhanno il modo 0777, e alcuni file del container sono scrivibili da tutti gli account. Qualsiasi account nel container può cambiare ciò che root avvia. L’agente rifiuta anche una cartella del genere (root trust directory: /usr is writable by group or others): l’installatore in modalità di aggiornamento fallisce allora in un nuovo container, e il container si avvia di continuo. Usa l’immagine 2027.2.33 o successiva. Non dare accesso shell nel container di un’immagine più vecchia a utenti di cui non ti fidi. - Immagini fino a 2027.2.32: un RCM creato a mano non si avvia in un nuovo
container. Quando crei RCM con
fbagent --cluster-initdentro il container, l’agente crea l’account del sistema operativohqbirdrcm. Un nuovo container non lo ha (User=hqbirdrcm: invalid userid, il container èunhealthy). Le immagini più recenti conservano gli account sul volumestate. Un cluster creato da HQCenter non è interessato. - Immagini fino a 2027.2.33: un router (HAProxy) non si avvia. Per un
membro del cluster con il ruolo
routerl’agente installa il pacchettohaproxye il servizio del router, mahaproxy.servicefallisce. Il sostituto di systemd nell’immagine non mette i valori di$CONFIG,$PIDFILEe$EXTRAOPTSnella riga di comando e non legge alcun file drop-in, e niente crea la cartella/run/haproxy. L’immagine successiva contiene la correzione. Fino ad allora, dai alle applicazioni l’indirizzo da.../services/<alias>/mastere non aggiungere un membrorouter. - Immagine 2027.2.33: un nuovo container non si avvia dopo che è stato aggiunto un router. Il log contiene
chown: invalid user: 'haproxy', e Docker avvia il container di continuo. Per avviarlo, rimuovi il fileusr/lib/tmpfiles.d/haproxy.confsul volumestate. L’immagine successiva contiene la correzione.
10. Costruire le immagini
Per il team della versione. Su un host Windows con i file della versione in
dist\releases, accedi a GHCR con un token che ha write:packages,
poi costruisci, invia e firma:
Get-Content token.txt | docker login ghcr.io -u <GitHub user> --password-stdin
.\ops\docker\Build-HqbirdImage.ps1 -Line 50 -SetupVersion 2027.2.33 -Registry ghcr.io/ibsurgeon -Tag 2027.2 -Push -CosignKey cosign.keyUn pacchetto nuovo (il primo invio di una linea) è privato. Nelle impostazioni del pacchetto dell’organizzazione IBSurgeon, imposta la visibilità su pubblica.
-ContextOnly prepara solo la cartella di costruzione
(dist\hqbird2027-docker\fbNN-<version>) e stampa il comando docker build
da eseguire su un host Docker Linux.
La costruzione si ferma quando una cartella o un file dell’immagine sotto /etc o /usr
è scrivibile da tutti gli account (la cartella di costruzione arriva da Windows, dove i
modi si perdono). I test degli script del container, delle impostazioni del cluster
e dei file compose: go test ./ops/docker/.