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.

Command
docker pull ghcr.io/ibsurgeon/hqbird2027-fb50:2027.2.33

Die 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:

Command
cosign verify --key hqbird-cosign.pub ghcr.io/ibsurgeon/hqbird2027-fb50:2027.2.33

2. Erster Start

  1. Kopieren Sie compose.yaml (aus ops/docker/ der Ausgabe) in einen Ordner auf dem Docker-Host.

  2. Legen Sie das SYSDBA-Passwort in einer Datei ab, die nur Sie lesen können:

    Command
    mkdir -p secrets && openssl rand -hex 12 > secrets/sysdba_password && chmod 600 secrets/sysdba_password
  3. Setzen Sie in compose.yaml image:, hostname: und entfernen Sie das # von den secrets:-Zeilen, die Sie verwenden.

  4. Starten Sie den Container:

    Command
    docker compose up -d
  5. Beobachten Sie die Installation (beim ersten Start einige Minuten):

    Command
    docker compose logs -f

    Auf 2 vCPU dauert die Installation etwa 20 Sekunden. Sie ist fertig, wenn das Protokoll [hqbird-boot] ready: firebird.service=active ... zeigt und docker compose ps healthy zeigt.

Danach:

  • Firebird: <docker host>:3050.
  • HQ Monitor: http://<docker host>:23050/, Anmeldung admin. Der Installer erzeugt das Passwort; lesen Sie es mit docker compose exec hqbird cat /opt/hqbird/conf/access.properties.
  • Die Agent-Id in HQCenter: der hostname + das Installationsdatum (YYMMDD)
    • -fbNN, zum Beispiel hqbird-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):

Command
chown 84:84 /srv/hqbird/db /srv/hqbird/backup

Sichern 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:

    Command
    docker compose pull && docker compose up -d

    Beim 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).

  1. Tragen Sie auf dem Master-Host die Adresse dieses Docker-Hosts in .env ein, so wie der Replica-Host und Ihr Browser sie erreichen (nicht localhost, nicht die Adresse des Containers):

    Command
    echo 'HQBIRD_CLUSTER_ADDRESS=203.0.113.10' >> .env
    docker compose -f compose.yaml -f compose.master.yaml up -d
  2. Auf dem Replica-Host:

    Command
    docker compose -f compose.yaml -f compose.replica.yaml up -d
  3. Lesen Sie die Cluster-Zeilen jedes Containers:

    Command
    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:....

  4. Öffnen Sie die Konsole https://<master host>:7444. Die Anmeldung ist rcmadmin. Ohne das Secret rcm_password steht das Passwort in einer Datei; RCM verlangt bei der ersten Anmeldung ein neues:

    Command
    docker compose exec hqbird sh -c 'cat /opt/hqbird/fbagent-*/clusterca/*/rcm-initial-password'
  5. Schreiben Sie in Settings → Link hosts zwei Zeilen: die Adresse, die Sie in HQBIRD_CLUSTER_ADDRESS angegeben 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 Container healthy ist. 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 Volume db, 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:

Command
docker compose -f compose.cluster-one-host.yaml up -d

Die 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_ROLE eine Warnung im Protokoll aus und ändert nichts. Um den Cluster später zu ändern, verwenden Sie HQ Monitor (Clusters) oder die Befehle fbagent --cluster-init und fbagent --cluster-pairing im 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_ALLOW oder Ihre Firewall; nach der Verknüpfung können Sie den Port aus ports: 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:

Command
RCM=https://203.0.113.10:7444
api() { curl -sk --digest -u rcmadmin -H 'Content-Type: application/json' "$@"; }
  1. Veröffentlichen Sie den zweiten Knoten-Port auf beiden Hosts: Knoten-Port + 10. Entfernen Sie in compose.master.yaml und compose.replica.yaml das # aus der Zeile "7061:7061" und führen Sie danach docker compose up -d mit denselben Optionen -f aus. Tun Sie das vor dem ersten Start, wenn Sie können.

  2. 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:

    Command
    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/nodes zeigt die Knoten-Ids (<host name>-master, <host name>-replica).

  3. 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_port 7061. Lesen Sie das Dokument, fügen Sie zwei Mitglieder und einen Link hinzu und senden Sie es mit seiner Revision zurück:

    Command
    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.json

    Die 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=service zeigt danach zwei Dienste hqclusternode in 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 auf failed:

    Command
    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
  4. Definieren Sie den Dienst. host ist 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>:

    Command
    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
  5. Prüfen, dann umschalten:

    Command
    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 Paket haproxy aus 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 rejoin ihn 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 Monitor 20000 + der Firebird-Port, Cluster-Knoten 7051 + N (setzen Sie denselben listen_port in 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=7451 und HQBIRD_NODE_PORT=7052 für die zweite, 7452 und 7053 fü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:

Command
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 --enroll mit HQCenter verbunden haben, führen Sie fbagent --refresh-apply-launcher als root aus, sonst schlägt die Selbstaktualisierung des Agents mit “no goafts CA is pinned” fehl.
  • Führen Sie in Skripten docker compose exec mit -T und </dev/null aus. Ohne sie liest es die Standardeingabe und nimmt den Rest eines Skripts, das Sie mit ssh ... bash -s senden.
  • Bevor der Agent mit HQCenter verbunden ist, zeigt sein Protokoll die Warnungen goafts mTLS settings are incomplete und bootstrap CA not found. Das ist normal.
  • Der Container gibt /opt/hqbird nach jeder Installation an root (die Selbstaktualisierung des Agents braucht das). Der Agent schreibt eine Warnung, dass er /opt/hqbird/version.json nicht aktualisieren kann; Sie können sie ignorieren.
  • Images bis einschließlich 2027.2.32: Ordner zum Schreiben offen. In diesen Images haben /etc, /usr und /usr/lib den 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-init im Container anlegen, legt der Agent das Betriebssystemkonto hqbirdrcm an. Ein neuer Container hat es nicht (User=hqbirdrcm: invalid userid, der Container ist unhealthy). Neuere Images behalten die Konten auf dem Volume state. 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 router installiert der Agent das Paket haproxy und den Router-Dienst, aber haproxy.service scheitert. Der Ersatz für systemd im Image setzt die Werte von $CONFIG, $PIDFILE und $EXTRAOPTS nicht in die Befehlszeile ein und liest keine Drop-in-Datei, und nichts legt den Ordner /run/haproxy an. Das nächste Image enthält die Korrektur. Geben Sie den Anwendungen bis dahin die Adresse aus .../services/<alias>/master und fügen Sie kein Mitglied router hinzu.
  • 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 Datei usr/lib/tmpfiles.d/haproxy.conf auf dem Volume state. 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:

Command
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.key

Ein 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/.