HQbird 2027 in Docker: Administratorhandbuch
Dieses Handbuch ist für den Administrator, der HQbird 2027 in Docker betreibt. Ein Container ist eine Firebird-Instanz mit allen HQbird-Komponenten:
- Firebird (der HQbird-Build einer Linie: 5.0, 4.0, 3.0 oder 2.5);
- HQbird-Agent (
fbagent): Sicherungen, Überwachung, Wartungsaufgaben, Aktualisierungen, die Verbindung zu HQCenter; - HQ Monitor: die Webkonsole der Instanz;
- Cluster-Knoten (
hqclusternode) und RCM (hqbirdrcm): der Agent installiert sie, wenn HQCenter diese Instanz einem Cluster hinzufügt oder wenn Sie dem Container eine Cluster-Rolle geben (Abschnitt 7). Ohne Rolle und ohne HQCenter führt der Container keine Cluster-Komponente aus.
Der Container installiert HQbird mit demselben Offline-Installer wie ein Server (Linux-Installationsanleitung). Der Agent aktualisiert danach Firebird, HQ Monitor, die Cluster-Komponenten und sich selbst aus HQCenter, wie auf einem Server. Ihre Daten, die Konfiguration, die Lizenz, die HQCenter-Zertifikate und die aktualisierten Programme liegen auf Volumes: sie bleiben, wenn Sie den Container neu erstellen oder das Image wechseln.
Aktuelle Ausgabe: 2027.2.33 (2026-11-16): Firebird 2.5.9, 3.0.15, 4.0.8 und 5.0.5, Agent 3.4.0, HQ Monitor 1.57.0, RCM und Knoten 2027.5.12.
Getestet am 2026-11-16 auf Ubuntu 22.04.5 (2 vCPU / 4 GB), Docker 29.10.0,
Compose 5.7.1, Image hqbird2027-fb40:2027.2.33 (erster Test: 2026-11-11,
Image 2027.2.27). Eine Installation Schritt für Schritt
für Ubuntu 22.04: hqbird2027-docker-install-fb40.ru.md
(Russisch), hqbird2027-docker-install-fb40.pt.md
(Portugiesisch).
Die Cluster-Rolle (Abschnitt 7.1) und der Switchover (Abschnitt 7.3) wurden
am 2026-11-16 auf den Images 5.0, 4.0, 3.0 und 2.5 getestet, wobei die zwei
“Hosts” zwei Adressen einer VM waren, und auf zwei getrennten Docker-Hosts
(zwei Droplets, das Image 4.0 2027.2.33). Am 2026-11-17 wurde der Rest auf
zwei Docker-Hosts mit dem Image 5.0 2027.2.33 getestet: ein von Hand
erstellter Cluster in Containern 2027.2.32, übernommen auf das neue Image
(beide Container healthy in 35 Sekunden), HQBIRD_RCM_ALLOW, die Seiten
Services der RCM-Konsole und das automatische Failover. Router (HAProxy)
starten in den Images bis einschließlich 2027.2.33 nicht (Abschnitt 9); das
nächste Image enthält die Korrektur.
1. Images
| Image | Firebird | Standardport |
|---|---|---|
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 |
Die Images liegen in der GitHub Container Registry von IBSurgeon
(https://github.com/orgs/IBSurgeon/packages). Sie sind öffentlich: Sie
müssen sich nicht anmelden. <version> ist die HQbird-Setup-Version, zum
Beispiel 2027.2.33. Der Tag 2027.2 ist das neueste Image 2027.2.x.
docker pull ghcr.io/ibsurgeon/hqbird2027-fb50:2027.2.33Die Images sind mit cosign signiert. Der öffentliche Schlüssel
hqbird-cosign.pub ist noch nicht veröffentlicht (2026-11-16). Die Images
2027.2.33 sind signiert. Wenn Sie den Schlüssel haben, prüfen Sie ein Image,
bevor Sie es verwenden:
cosign verify --key hqbird-cosign.pub ghcr.io/ibsurgeon/hqbird2027-fb50:2027.2.332. Erster Start
-
Kopieren Sie
compose.yaml(ausops/docker/der Ausgabe) in einen Ordner auf dem Docker-Host. -
Legen Sie das SYSDBA-Passwort in einer Datei ab, die nur Sie lesen können:
mkdir -p secrets && openssl rand -hex 12 > secrets/sysdba_password && chmod 600 secrets/sysdba_password -
Setzen Sie in
compose.yamlimage:,hostname:und entfernen Sie das#von densecrets:-Zeilen, die Sie verwenden. -
Starten Sie den Container:
docker compose up -d -
Beobachten Sie die Installation (beim ersten Start einige Minuten):
docker compose logs -fAuf 2 vCPU dauert die Installation etwa 20 Sekunden. Sie ist fertig, wenn das Protokoll
[hqbird-boot] ready: firebird.service=active ...zeigt unddocker compose pshealthyzeigt.
Danach:
- Firebird:
<docker host>:3050. - HQ Monitor:
http://<docker host>:23050/, Anmeldungadmin. Der Installer erzeugt das Passwort; lesen Sie es mitdocker compose exec hqbird cat /opt/hqbird/conf/access.properties. - Die Agent-Id in HQCenter: der hostname + das Installationsdatum (YYMMDD)
-fbNN, zum Beispielhqbird-fb40-3051261111-fb40.
Behalten Sie den hostname. Die Lizenzidentität der Instanz ist die
machine-id auf dem Volume state und die Agent-Id. Ein neues Volume
state ist eine neue Installation.
3. Einstellungen
Die Einstellungen werden nur beim ersten Start gelesen (bei der Installation).
| Einstellung | Wirkung |
|---|---|
HQBIRD_FB_PORT |
Firebird-Port im Container (Standard 3050). HQ Monitor verwendet 20000 + diesen Port |
HQBIRD_HQM_PORT |
ein anderer HQ-Monitor-Port |
HQBIRD_AGENT_ID |
die Agent-Id (Standard: aus Hostname, Datum und Port gebildet) |
HQBIRD_HQM_LOGIN + Secret hqmonitor_password |
die Anmeldung von HQ Monitor |
HQBIRD_TRIAL_EMAIL, HQBIRD_TRIAL_ZONE |
eine Testlizenz anfordern (Sie akzeptieren die Datenschutzrichtlinie) |
HQBIRD_DEBUG=1 |
die Firebird-Debug-Dateien installieren |
Secret sysdba_password |
das SYSDBA-Passwort eines neuen Firebird |
Secret license |
eine Lizenzdatei |
Secret attach |
attach.json von HQCenter: verbindet den Agent mit Ihrem HQCenter |
HQBIRD_CLUSTER_ROLE |
master oder replica: ein Cluster ohne HQCenter (Abschnitt 7). Leer: kein Cluster |
HQBIRD_CLUSTER_ADDRESS |
master, erforderlich: Adresse oder DNS-Name des Docker-Hosts, wie Replica und Ihr Browser ihn erreichen. Eine Liste mit Kommas; der erste Eintrag geht in die RCM-URL |
HQBIRD_CLUSTER_ID |
master: die Cluster-Id (Standard: der Hostname) |
Secret rcm_password |
master: das Passwort der RCM-Anmeldung rcmadmin (Standard: ein erzeugtes) |
HQBIRD_RCM_ALLOW |
replica: nur diese RCM dürfen den Container einladen (IP, CIDR, Hostname; Standard: beliebige). Schreiben Sie die Adresse des Docker-Hosts von master: die Replica sieht diese Adresse. Auf einem Docker-Host sieht die Replica das Gateway ihres Docker-Netzwerks |
HQBIRD_PAIRING_PORT, HQBIRD_NODE_PORT |
der Cluster-Slot: Pairing-Port 7450-7459 und Knoten-Port = Pairing-Port - 399 (Standard 7450 und 7051) |
4. Volumes
| Volume | Pfad | Inhalt |
|---|---|---|
opt |
/opt |
Firebird, der Agent, HQ Monitor, Cluster-Knoten, RCM |
state |
/var/lib/hqbird-container |
Units, sudoers, HQ-Monitor-Daten, Agent-Protokolle, machine-id, Setup-Zustand, die zur Laufzeit angelegten Betriebssystemkonten (der RCM-Dienstbenutzer) |
trust |
/usr/libexec/hqbird-fbagent |
der Update-Starter des Agents und die Vertrauensdaten |
rootwork |
/var/lib/hqbird-fbagent |
der Arbeitsordner des Update-Starters |
db |
/db |
Datenbanken (legen Sie Ihre Datenbanken hier ab) |
backup |
/backup |
Sicherungen |
Montieren Sie keine Host-Ordner auf opt, state, trust und
rootwork. Für db und backup können Sie Host-Ordner verwenden; geben
Sie sie an uid 84 (der Benutzer firebird des Images):
chown 84:84 /srv/hqbird/db /srv/hqbird/backupSichern Sie alle sechs Volumes zusammen.
5. Tägliche Arbeit
| Aufgabe | Befehl |
|---|---|
| Status der Dienste | docker compose exec hqbird systemctl list-units --type=service |
| Firebird neu starten | 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 |
| Protokolle | docker compose logs --since 1h |
| Anhalten (Firebird schließt die Datenbanken) | docker compose stop |
Im Container steuert systemctl die HQbird-Dienste. Es ist nicht
systemd: es unterstützt die Befehle, die die HQbird-Programme verwenden
(start, stop, restart, status, is-active, enable, disable,
show, list-units, daemon-reload).
6. Aktualisierungen
Es gibt zwei Wege zur Aktualisierung. Beide behalten Ihre Daten.
-
Aus HQCenter (wie auf einem Server): HQCenter aktualisiert den Agent, HQ Monitor, Firebird, den Cluster-Knoten und RCM im Container.
-
Neues Image: ändern Sie
image:auf die neue Version, danach:docker compose pull && docker compose up -dBeim Start führt der Container den Installer des neuen Images im Aktualisierungsmodus aus. Wenn HQCenter den Agent bereits auf eine neuere Version gebracht hat, als das Image sie enthält, wird der Installer nicht ausgeführt (keine Herabstufung); das Protokoll sagt das.
Ein neuer Container (ein neues Image, oder docker compose down und
up -d ohne -v) behält den Cluster: Rolle, Cluster-Id, RCM, die Knoten
und die Verbindung zum anderen Host liegen auf den Volumes. Die
Cluster-Einstellungen in der Compose-Datei werden nicht erneut gelesen.
Images bis einschließlich 2027.2.32 haben hier zwei Fehler: siehe Abschnitt
9.
7. Cluster
Es gibt zwei Wege, einen Cluster zu bilden. Mischen Sie sie nicht in einem Container.
7.1. Ohne HQCenter: zwei Container mit einer Rolle
Ein Container ist der master und führt den Cluster-Manager (RCM) mit
seiner Konsole aus. Der andere ist eine replica. Die Rolle ist eine
Einstellung des ersten Starts: HQBIRD_CLUSTER_ROLE. Ohne sie führt der
Container kein RCM und keinen Cluster-Knoten aus und öffnet keinen
Pairing-Port. Die Rolle braucht das Image 2027.2.33 oder neuer.
Zwei Docker-Hosts. Geben Sie den zwei Containern verschiedene
Hostnamen (HQBIRD_HOSTNAME in .env, oder hostname:): mit demselben
Hostnamen haben die zwei Agents dieselbe Id, und RCM weist die Replica
zurück (duplicate). Kopieren Sie compose.master.yaml auf den
Master-Host und compose.replica.yaml auf den Replica-Host, neben
compose.yaml (ops/docker/ der Ausgabe).
-
Tragen Sie auf dem Master-Host die Adresse dieses Docker-Hosts in
.envein, so wie der Replica-Host und Ihr Browser sie erreichen (nichtlocalhost, nicht die Adresse des Containers):echo 'HQBIRD_CLUSTER_ADDRESS=203.0.113.10' >> .env docker compose -f compose.yaml -f compose.master.yaml up -d -
Auf dem Replica-Host:
docker compose -f compose.yaml -f compose.replica.yaml up -d -
Lesen Sie die Cluster-Zeilen jedes Containers:
docker compose logs | grep -E 'cluster:|CA hash|Password'Der Master zeigt die Konsolenadresse und den
CA hash:[hqbird-boot] cluster: role=master id=... console=https://203.0.113.10:7444 login=rcmadmin. Die Replica zeigt ihren Pairing-Port und den Fingerabdruck:[hqbird-boot] cluster: role=replica pairing port 7450: open until ..., fingerprint sha256:.... -
Öffnen Sie die Konsole
https://<master host>:7444. Die Anmeldung istrcmadmin. Ohne das Secretrcm_passwordsteht das Passwort in einer Datei; RCM verlangt bei der ersten Anmeldung ein neues:docker compose exec hqbird sh -c 'cat /opt/hqbird/fbagent-*/clusterca/*/rcm-initial-password' -
Schreiben Sie in Settings → Link hosts zwei Zeilen: die Adresse, die Sie in
HQBIRD_CLUSTER_ADDRESSangegeben haben (der Master), und die Adresse des Docker-Hosts der Replica. Sie schreiben keinen Port: RCM liest die Pairing-Ports 7450-7459. Der Pairing-Port antwortet etwa 30 Sekunden, nachdem der Containerhealthyist. Das Fenster Initialize schlägt den Ordner/databases/replica/...vor, der außerhalb der Volumes liegt: ändern Sie ihn. Dieses Fenster ist etwa 1000 px hoch und lässt sich nicht scrollen: verkleinern Sie die Seite, wenn Sie seine Schaltflächen nicht sehen. Im Browser getestet am 2026-11-16. Vergleichen Sie den Fingerabdruck der Replica mit dem in ihrem Protokoll. Lassen Sie RCM URL leer. Fahren Sie danach mit Schritt 4 der Linux-Cluster-Anleitung fort (Datenbankordner, Registrieren, die Replica initialisieren). Für den Datenbankordner der Replica verwenden Sie einen Ordner auf dem Volumedb, zum Beispiel/db/replica. Getestet: eine auf dem Master geschriebene Zeile war nach 30 Sekunden auf der Replica.
Um die Optionen -f wegzulassen, setzen Sie
COMPOSE_FILE=compose.yaml:compose.master.yaml (oder ...replica.yaml) in
.env.
Ein Docker-Host. compose.cluster-one-host.yaml ist eine vollständige
Datei mit beiden Containern:
docker compose -f compose.cluster-one-host.yaml up -dDie Container erreichen einander über den Namen im Netz des Projekts,
daher werden die Cluster-Ports nicht veröffentlicht. Schreiben Sie in
Link hosts hqbird-master und hqbird-replica. Das Firebird des
Masters liegt auf Port 3050, das der Replica auf 3051; die Konsole ist
https://<docker host>:7444.
Regeln:
- Die Rolle und ihre Einstellungen werden nur beim ersten Start
gelesen. Später gibt ein anderes
HQBIRD_CLUSTER_ROLEeine Warnung im Protokoll aus und ändert nichts. Um den Cluster später zu ändern, verwenden Sie HQ Monitor (Clusters) oder die Befehlefbagent --cluster-initundfbagent --cluster-pairingim Container. - Eine falsche Einstellung (eine unbekannte Rolle, ein Master ohne
HQBIRD_CLUSTER_ADDRESS, eine Einstellung der anderen Rolle) stoppt den Start, bevor etwas installiert wird. Das Protokoll sagt, was Sie schreiben sollen ([hqbird-boot] error: ...); Docker startet den Container erneut und das Protokoll wiederholt die Zeile, bis Sie die Einstellung korrigieren. - Das Pairing-Fenster einer Replica ist 24 Stunden offen. Ein Neustart
eines Containers, der noch in keinem Cluster ist, öffnet es wieder. Um
den Pairing-Port gegenüber anderen Netzen zu schließen, verwenden Sie
HQBIRD_RCM_ALLOWoder Ihre Firewall; nach der Verknüpfung können Sie den Port ausports:nehmen. - Für einen Switchover (einen RCM-Dienst) braucht jeder Host einen zweiten Knoten und dessen veröffentlichten Port: siehe Abschnitt 7.3.
7.2. Mit HQCenter
HQCenter fügt die Instanz einem Cluster hinzu, wie es einen Server
hinzufügt. Setzen Sie HQBIRD_CLUSTER_ROLE nicht. Geben Sie in HQCenter
die Adresse des Docker-Hosts als Mitgliedsadresse an. Veröffentlichen
Sie in compose.yaml die Ports der Cluster-Komponenten:
| Komponente | Port | Veröffentlichen, wenn |
|---|---|---|
| Cluster-Knoten | der listen_port des Knotens (zum Beispiel 7051) |
die Instanz ist ein Cluster-Mitglied |
| RCM | 7443 | HQCenter macht diesen Agent zum RCM |
| RCM-Operatorkonsole | 7444 | wie oben; setzen Sie operator_addr in den RCM-Einstellungen auf 0.0.0.0:7444 |
Der Agent installiert den Knoten (und RCM) einige Minuten, nachdem der
Cluster gespeichert wurde. Bis dahin antwortet der Knoten-Port nicht.
Setzen Sie in HQCenter den listen_port des Knotens auf den
veröffentlichten Port. Eine Replica wartet, bis der RCM-Agent die
Cluster-CA hochlädt.
Getestet am 2026-11-16 ohne Rolle: die Agents installierten die Knoten und
RCM, und alle Mitglieder waren nach docker compose down und up -d
wieder running.
7.3. Switchover zwischen den zwei Containern
Ein RCM-Dienst verschiebt die Master-Rolle einer Datenbank von einem Host auf den anderen. Für einen Dienst braucht jeder Host zwei Knoten: einen Master-Knoten und einen Replica-Knoten. Link hosts gibt jedem Host einen Knoten, die zweiten Knoten fügen Sie selbst hinzu. Getestet am 2026-11-16 am Paar aus Abschnitt 7.1: der Switchover dauerte 25 Sekunden, der alte Master wurde eine nur lesbare Replica, und eine auf dem neuen Master geschriebene Zeile war 15 Sekunden später auf ihr.
Die Schritte verwenden die RCM-Operator-API auf dem Konsolenport. curl
fragt nach dem Passwort von rcmadmin; -k überspringt die Prüfung des
eigenen Zertifikats des Clusters:
RCM=https://203.0.113.10:7444
api() { curl -sk --digest -u rcmadmin -H 'Content-Type: application/json' "$@"; }-
Veröffentlichen Sie den zweiten Knoten-Port auf beiden Hosts: Knoten-Port + 10. Entfernen Sie in
compose.master.yamlundcompose.replica.yamldas#aus der Zeile"7061:7061"und führen Sie danachdocker compose up -dmit denselben Optionen-faus. Tun Sie das vor dem ersten Start, wenn Sie können. -
Geben Sie jedem Knoten die Adresse seines Docker-Hosts. RCM gibt diese Adresse und den Firebird-Port an die Anwendungen; ohne sie erhalten sie die Adresse des Containers:
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/nodeszeigt die Knoten-Ids (<host name>-master,<host name>-replica). -
Fügen Sie die zweiten Knoten zum Cluster-Dokument hinzu: einen Master-Knoten auf dem Replica-Host und seinen Replica-Knoten auf dem Master-Host, beide mit
listen_port7061. Lesen Sie das Dokument, fügen Sie zwei Mitglieder und einen Link hinzu und senden Sie es mit seiner Revision zurück: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.jsonDie Agents installieren dann die zwei Knoten-Dienste (30 Sekunden im Test auf zwei Hosts; es kann einige Minuten dauern).
docker compose exec hqbird systemctl list-units --type=servicezeigt danach zwei Dienstehqclusternodein jedem Container.Geben Sie danach beiden Knoten replica einen Datenbankordner auf dem Volume
db. Ohne ihn stoppt ein Switchover zurück oder ein Failover nach dem Punkt ohne Wiederkehr, und der Dienst geht auffailed: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 -
Definieren Sie den Dienst.
hostist die Agent-Id des Hosts. Der Pfad auf dem zweiten Host ist der Pfad der Replica-Datei:<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 -
Prüfen, dann umschalten:
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>
Nach dem Switchover gibt .../services/shop/master die Adresse des
anderen Docker-Hosts und dessen Firebird-Port. Die Anwendungen müssen sich
mit dieser Adresse verbinden. Ein Switchover braucht eine Replica, die
IN_SYNC ist: das ist sie nach dem ersten Schreiben auf dem Master (35
Sekunden im Test).
Router und automatisches Failover. Ein Router (HAProxy) gibt den Anwendungen eine Adresse, die dem Master folgt. In den Images bis einschließlich 2027.2.33 startet der Router nicht (Abschnitt 9); das nächste Image enthält die Korrektur. Das automatische Failover braucht einen Router als Zeugen. Getestet am 2026-11-17 im Labor, auf 2027.2.33 mit einem Behelf und auf einem Test-Image mit der Korrektur:
-
Ein Router ist ein Cluster-Mitglied mit der Rolle
router. Der Agent installiert das Pakethaproxyaus dem Debian-Repository, auch in jedem neuen Container: der Container braucht Zugriff auf das Repository. Veröffentlichen Sie den Router-Port (3051 im Beispiel). -
Mit einem Router nur auf dem RCM-Host hat RCM den Master von selbst 84 Sekunden nachdem der Container des anderen Hosts stoppte verschoben; der Vorgang dauerte 10 Sekunden. Als dieser Host zurückkam, machte
rejoinihn wieder zur Replica. -
Mit einem Router auf jedem Host startet das automatische Failover nicht: mehr als die Hälfte der Router muss melden, und einer der zwei liegt auf dem verlorenen Host.
-
Das RCM läuft im Master-Container. Wenn dieser Host verloren geht, geht auch das RCM verloren, und nichts verschiebt den Master von selbst.
8. Ports, Firewall, zweite Instanz
Veröffentlichen Sie jeden Port mit derselben Nummer außerhalb und
innerhalb des Containers (3051:3051, nicht 3051:3050). Der Agent und
der Cluster melden den Port, den sie im Container sehen.
| Port | Was | Erforderlich |
|---|---|---|
HQBIRD_FB_PORT (3050) |
Firebird | immer |
| 20000 + Firebird-Port (23050) | HQ Monitor | immer |
listen_port des Knotens (7051) |
Cluster-Knoten | Cluster-Mitglied |
| Knoten-Port + 10 (7061) | der zweite Knoten des Hosts | ein Dienst mit Switchover (Abschnitt 7.3) |
| 7443, 7444 | RCM, RCM-Operatorkonsole | dieser Agent ist das RCM (einer pro Host) |
| Pairing-Port (7450) | der Pairing-Port des Agents | eine Replica mit Rolle, bis sie verknüpft ist |
Der Agent verbindet sich selbst mit HQCenter (ausgehend); er braucht keinen eingehenden Port.
Docker veröffentlicht Ports an ufw vorbei. Getestet: als ufw nur Port
22 erlaubte, waren die Ports von Firebird und HQ Monitor aus dem Internet
offen. Verwenden Sie eine externe Firewall, veröffentlichen Sie auf einer
Host-Adresse ("10.0.0.5:23050:23050"), oder fügen Sie Regeln zur
iptables-Chain DOCKER-USER hinzu.
Eine zweite Instanz auf einem Host braucht einen eigenen Ordner, das
Projekt-name:, hostname, HQBIRD_FB_PORT und Ports. Der Projektname
bildet die Volume-Namen (<name>_opt, …): mit demselben Namen übernimmt
der zweite Start die Volumes und den Container des ersten.
| Instanz 1 | Instanz 2 | |
|---|---|---|
name:, hostname: |
hqbird-fb40-3051 |
hqbird-fb40-3052 |
HQBIRD_FB_PORT |
3051 | 3052 |
ports: |
3051, 23051, 7052 | 3052, 23052, 7053 |
Regeln für N Instanzen auf einer externen IP:
- Firebird
3050 + N, HQ Monitor20000 +der Firebird-Port, Cluster-Knoten7051 + N(setzen Sie denselbenlisten_portin HQCenter). Überspringen Sie 3050, 23050 und 7051, wenn der Host bereits ein Firebird oder HQbird außerhalb von Docker ausführt. - Nur eine Instanz pro Host kann das RCM sein (7443, 7444).
- Mit einer Cluster-Rolle (Abschnitt 7.1) braucht jede Instanz eines Hosts
ihren eigenen Slot:
HQBIRD_PAIRING_PORT=7451undHQBIRD_NODE_PORT=7052für die zweite,7452und7053für die dritte. - Eine Instanz braucht ohne Last etwa 200-250 MB Speicher. Getestet: drei FB-4.0-Instanzen auf 2 vCPU / 4 GB, eine mit Last.
- Andere Firebird-Linien auf demselben Host folgen denselben Regeln mit
ihrem eigenen Image (
hqbird2027-fb50, …) und Namen (hqbird-fb50-3054).
Fügen Sie eine Instanz hinzu (hier die dritte: 3053, 23053, 7054), ausgehend
von der compose.yaml der ersten. Das Ersetzen von 3051 ändert auch
name:, hostname:, HQBIRD_FB_PORT und den HQ-Monitor-Port:
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. Bekannte Probleme
- Nachdem Sie den Agent von Hand mit
fbagent --enrollmit HQCenter verbunden haben, führen Siefbagent --refresh-apply-launcherals root aus, sonst schlägt die Selbstaktualisierung des Agents mit “no goafts CA is pinned” fehl. - Führen Sie in Skripten
docker compose execmit-Tund</dev/nullaus. Ohne sie liest es die Standardeingabe und nimmt den Rest eines Skripts, das Sie mitssh ... bash -ssenden. - Bevor der Agent mit HQCenter verbunden ist, zeigt sein Protokoll die
Warnungen
goafts mTLS settings are incompleteundbootstrap CA not found. Das ist normal. - Der Container gibt
/opt/hqbirdnach jeder Installation an root (die Selbstaktualisierung des Agents braucht das). Der Agent schreibt eine Warnung, dass er/opt/hqbird/version.jsonnicht aktualisieren kann; Sie können sie ignorieren. - Images bis einschließlich 2027.2.32: Ordner zum Schreiben offen. In
diesen Images haben
/etc,/usrund/usr/libden Modus 0777, und einige Dateien des Containers sind für alle Konten schreibbar. Jedes Konto im Container kann ändern, was root startet. Der Agent lehnt einen solchen Ordner ebenfalls ab (root trust directory: /usr is writable by group or others): der Installer im Aktualisierungsmodus scheitert dann in einem neuen Container, und der Container startet immer wieder. Verwenden Sie das Image 2027.2.33 oder neuer. Geben Sie im Container eines älteren Images keinen Shell-Zugriff an Benutzer, denen Sie nicht vertrauen. - Images bis einschließlich 2027.2.32: von Hand erstelltes RCM startet
in einem neuen Container nicht. Wenn Sie RCM mit
fbagent --cluster-initim Container anlegen, legt der Agent das Betriebssystemkontohqbirdrcman. Ein neuer Container hat es nicht (User=hqbirdrcm: invalid userid, der Container istunhealthy). Neuere Images behalten die Konten auf dem Volumestate. Ein von HQCenter erstellter Cluster ist nicht betroffen. - Images bis einschließlich 2027.2.33: ein Router (HAProxy) startet
nicht. Für ein Cluster-Mitglied mit der Rolle
routerinstalliert der Agent das Pakethaproxyund den Router-Dienst, aberhaproxy.servicescheitert. Der Ersatz für systemd im Image setzt die Werte von$CONFIG,$PIDFILEund$EXTRAOPTSnicht in die Befehlszeile ein und liest keine Drop-in-Datei, und nichts legt den Ordner/run/haproxyan. Das nächste Image enthält die Korrektur. Geben Sie den Anwendungen bis dahin die Adresse aus.../services/<alias>/masterund fügen Sie kein Mitgliedrouterhinzu. - Image 2027.2.33: ein neuer Container startet nicht, nachdem ein Router
hinzugefügt wurde. Das Protokoll enthält
chown: invalid user: 'haproxy', und Docker startet den Container immer wieder. Um ihn zu starten, entfernen Sie die Dateiusr/lib/tmpfiles.d/haproxy.confauf dem Volumestate. Das nächste Image enthält die Korrektur.
10. Images bauen
Für das Release-Team. Melden Sie sich auf einem Windows-Host mit den
Ausgabedateien in dist\releases bei GHCR mit einem Token an, das
write:packages hat, und bauen, senden und signieren Sie danach:
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.keyEin neues Paket (der erste Push einer Linie) ist privat. Setzen Sie in den Paketeinstellungen der Organisation IBSurgeon seine Sichtbarkeit auf öffentlich.
-ContextOnly stellt nur den Build-Ordner bereit
(dist\hqbird2027-docker\fbNN-<version>) und gibt den Befehl docker build
aus, der auf einem Linux-Docker-Host auszuführen ist.
Der Build stoppt, wenn ein Ordner oder eine Datei des Images unter /etc
oder /usr für alle Konten schreibbar ist (der Build-Ordner kommt von
Windows, wo die Modi verloren gehen). Die Tests der Container-Skripte, der
Cluster-Einstellungen und der Compose-Dateien: go test ./ops/docker/.