Ten podręcznik jest dla administratora, który uruchamia HQbird 2027 w Dockerze. Jeden kontener to jedna instancja Firebird ze wszystkimi składnikami HQbird:

  • Firebird (kompilacja HQbird jednej linii: 5.0, 4.0, 3.0 lub 2.5);
  • agent HQbird (fbagent): kopie zapasowe, monitoring, zadania konserwacji, aktualizacje, połączenie z HQCenter;
  • HQ Monitor: konsola webowa instancji;
  • węzeł klastra (hqclusternode) i RCM (hqbirdrcm): instaluje je agent, gdy HQCenter dodaje tę instancję do klastra albo gdy nadajesz kontenerowi rolę w klastrze (sekcja 7). Bez roli i bez HQCenter kontener nie uruchamia składnika klastra.

Kontener instaluje HQbird tym samym instalatorem offline co serwer (instrukcja instalacji na Linuxie). Agent aktualizuje potem Firebird, HQ Monitor, składniki klastra i siebie z HQCenter, tak jak na serwerze. Twoje dane, konfiguracja, licencja, certyfikaty HQCenter i zaktualizowane programy leżą na wolumenach: zostają, gdy tworzysz kontener od nowa albo zmieniasz obraz.

Bieżące wydanie: 2027.2.33 (2026-11-16): Firebird 2.5.9, 3.0.15, 4.0.8 i 5.0.5, agent 3.4.0, HQ Monitor 1.57.0, RCM i węzeł 2027.5.12.

Sprawdzone 2026-11-16 na Ubuntu 22.04.5 (2 vCPU / 4 GB), Docker 29.10.0, Compose 5.7.1, obraz hqbird2027-fb40:2027.2.33 (pierwszy test: 2026-11-11, obraz 2027.2.27). Instalacja krok po kroku dla Ubuntu 22.04: hqbird2027-docker-install-fb40.ru.md (rosyjski), hqbird2027-docker-install-fb40.pt.md (portugalski).

Rola w klastrze (sekcja 7.1) i przełączenie (sekcja 7.3) zostały sprawdzone 2026-11-16 na obrazach 5.0, 4.0, 3.0 i 2.5, gdy dwa „hosty” były dwoma adresami jednej maszyny wirtualnej, oraz na dwóch osobnych hostach Docker (dwa droplets, obraz 4.0 2027.2.33). 2026-11-17 resztę sprawdzono na dwóch hostach Docker z obrazem 5.0 2027.2.33: klaster złożony ręcznie w kontenerach 2027.2.32 i przeniesiony na nowy obraz (oba kontenery healthy w 35 sekund), HQBIRD_RCM_ALLOW, strony Services konsoli RCM i automatyczne przejęcie. Routers (HAProxy) nie uruchamiają się w obrazach do 2027.2.33 włącznie (sekcja 9); następny obraz ma poprawkę.

1. Obrazy

Obraz Firebird Port domyślny
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

Obrazy są w GitHub Container Registry organizacji IBSurgeon (https://github.com/orgs/IBSurgeon/packages). Są publiczne: nie musisz się logować. <version> to wersja instalacji HQbird, na przykład 2027.2.33. Tag 2027.2 to najnowszy obraz 2027.2.x.

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

Obrazy są podpisane przez cosign. Klucz publiczny hqbird-cosign.pub nie jest jeszcze opublikowany (2026-11-16). Obrazy 2027.2.33 są podpisane. Gdy masz klucz, sprawdź obraz, zanim go użyjesz:

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

2. Pierwsze uruchomienie

  1. Skopiuj compose.yaml (z ops/docker/ wydania) do folderu na hoście Docker.

  2. Wpisz hasło SYSDBA do pliku, który możesz czytać tylko ty:

    Command
    mkdir -p secrets && openssl rand -hex 12 > secrets/sysdba_password && chmod 600 secrets/sysdba_password
  3. W compose.yaml ustaw image:, hostname: i usuń # z wierszy secrets:, których używasz.

  4. Uruchom kontener:

    Command
    docker compose up -d
  5. Obserwuj instalację (kilka minut przy pierwszym uruchomieniu):

    Command
    docker compose logs -f

    Na 2 vCPU instalacja trwa około 20 sekund. Jest skończona, gdy dziennik pokazuje [hqbird-boot] ready: firebird.service=active ..., a docker compose ps pokazuje healthy.

Potem:

  • Firebird: <docker host>:3050.
  • HQ Monitor: http://<docker host>:23050/, logowanie admin. Instalator tworzy hasło; odczytaj je przez docker compose exec hqbird cat /opt/hqbird/conf/access.properties.
  • Identyfikator agenta w HQCenter: nazwa hosta + data instalacji (YYMMDD) + -fbNN, na przykład hqbird-fb40-3051261111-fb40.

Zachowaj nazwę hosta. Tożsamość licencji instancji to machine-id na wolumenie state i identyfikator agenta. Nowy wolumen state to nowa instalacja.

3. Ustawienia

Ustawienia są czytane tylko przy pierwszym uruchomieniu (instalacja).

Ustawienie Co robi
HQBIRD_FB_PORT port Firebird wewnątrz kontenera (domyślnie 3050). HQ Monitor używa 20000 + ten port
HQBIRD_HQM_PORT inny port HQ Monitor
HQBIRD_AGENT_ID identyfikator agenta (domyślnie: z nazwy hosta, daty i portu)
HQBIRD_HQM_LOGIN + sekret hqmonitor_password logowanie HQ Monitor
HQBIRD_TRIAL_EMAIL, HQBIRD_TRIAL_ZONE poproś o licencję próbną (akceptujesz politykę prywatności)
HQBIRD_DEBUG=1 zainstaluj pliki diagnostyczne Firebird
sekret sysdba_password hasło SYSDBA nowej instalacji Firebird
sekret license plik licencji
sekret attach attach.json z HQCenter: połącz agenta ze swoim HQCenter
HQBIRD_CLUSTER_ROLE master albo replica: klaster bez HQCenter (sekcja 7). Puste: bez klastra
HQBIRD_CLUSTER_ADDRESS master, wymagane: adres lub nazwa DNS hosta Docker, tak jak docierają do niego replica i przeglądarka. Lista rozdzielona przecinkami; pierwszy trafia do RCM URL
HQBIRD_CLUSTER_ID master: identyfikator klastra (domyślnie: nazwa hosta)
sekret rcm_password master: hasło logowania RCM rcmadmin (domyślnie: wygenerowane)
HQBIRD_RCM_ALLOW replica: tylko te RCM mogą zaprosić kontener (IP, CIDR, nazwa hosta; domyślnie: dowolny). Wpisz adres hosta Docker dla master: replica widzi ten adres. Na jednym hoście Docker replica widzi bramę swojej sieci Docker
HQBIRD_PAIRING_PORT, HQBIRD_NODE_PORT slot klastra: port parowania 7450-7459 i port węzła = port parowania - 399 (domyślnie 7450 i 7051)

4. Woluminy

Wolumen Ścieżka Zawartość
opt /opt Firebird, agent, HQ Monitor, węzeł klastra, RCM
state /var/lib/hqbird-container unity, sudoers, dane HQ Monitor, dzienniki agenta, machine-id, stan instalacji, konta systemu operacyjnego tworzone w czasie działania (użytkownik usługi RCM)
trust /usr/libexec/hqbird-fbagent program uruchamiający aktualizacje agenta i materiał zaufania
rootwork /var/lib/hqbird-fbagent folder roboczy programu uruchamiającego aktualizacje
db /db bazy danych (tu włóż swoje bazy)
backup /backup kopie zapasowe

Nie montuj folderów hosta na opt, state, trust i rootwork. Możesz użyć folderów hosta dla db i backup; oddaj je uid 84 (użytkownik firebird obrazu):

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

Rób kopię zapasową wszystkich sześciu wolumenów razem.

5. Codzienna praca

Zadanie Polecenie
Stan usług docker compose exec hqbird systemctl list-units --type=service
Restart 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
Dzienniki docker compose logs --since 1h
Zatrzymanie (Firebird zamyka bazy danych) docker compose stop

Wewnątrz kontenera systemctl steruje usługami HQbird. To nie jest systemd: obsługuje polecenia, których używają programy HQbird (start, stop, restart, status, is-active, enable, disable, show, list-units, daemon-reload).

6. Aktualizacje

Są dwa sposoby aktualizacji. Oba zachowują twoje dane.

  • Z HQCenter (jak na serwerze): HQCenter aktualizuje agenta, HQ Monitor, Firebird, węzeł klastra i RCM wewnątrz kontenera.

  • Nowy obraz: zmień image: na nową wersję, a potem:

    Command
    docker compose pull && docker compose up -d

    Przy starcie kontener uruchamia instalator nowego obrazu w trybie aktualizacji. Jeśli HQCenter już zaktualizował agenta do wersji nowszej niż ta w obrazie, instalator się nie uruchamia (bez zejścia do starszej wersji); dziennik o tym mówi.

Nowy kontener (nowy obraz albo docker compose down i up -d bez -v) zachowuje klaster: rola, identyfikator klastra, RCM, węzły i połączenie z drugim hostem są na wolumenach. Ustawienia klastra w pliku Compose nie są czytane ponownie. Obrazy do 2027.2.32 włącznie mają tu dwie usterki: zobacz sekcję 9.

7. Klaster

Są dwa sposoby utworzenia klastra. Nie mieszaj ich w jednym kontenerze.

7.1. Bez HQCenter: dwa kontenery z rolą

Jeden kontener jest master i uruchamia menedżera klastra (RCM) z jego konsolą. Drugi jest replica. Rola jest ustawieniem pierwszego uruchomienia: HQBIRD_CLUSTER_ROLE. Bez niej kontener nie uruchamia RCM ani węzła klastra i nie otwiera portu parowania. Rola wymaga obrazu 2027.2.33 lub nowszego.

Dwa hosty Docker. Nadaj dwóm kontenerom różne nazwy hosta (HQBIRD_HOSTNAME w .env albo hostname:): przy tej samej nazwie hosta dwaj agenci mają ten sam identyfikator i RCM odmawia przyjęcia replica (duplicate). Skopiuj compose.master.yaml na host master i compose.replica.yaml na host replica, obok compose.yaml (ops/docker/ wydania).

  1. Na hoście master wpisz w .env adres tego hosta Docker, tak jak docierają do niego host replica i przeglądarka (nie localhost, nie adres kontenera):

    Command
    echo 'HQBIRD_CLUSTER_ADDRESS=203.0.113.10' >> .env
    docker compose -f compose.yaml -f compose.master.yaml up -d
  2. Na hoście replica:

    Command
    docker compose -f compose.yaml -f compose.replica.yaml up -d
  3. Odczytaj wiersze klastra każdego kontenera:

    Command
    docker compose logs | grep -E 'cluster:|CA hash|Password'

    Master pokazuje adres konsoli i CA hash: [hqbird-boot] cluster: role=master id=... console=https://203.0.113.10:7444 login=rcmadmin. Replica pokazuje swój port parowania i odcisk: [hqbird-boot] cluster: role=replica pairing port 7450: open until ..., fingerprint sha256:....

  4. Otwórz konsolę https://<master host>:7444. Nazwa logowania to rcmadmin. Bez sekretu rcm_password hasło jest w pliku; RCM prosi o nowe przy pierwszym logowaniu:

    Command
    docker compose exec hqbird sh -c 'cat /opt/hqbird/fbagent-*/clusterca/*/rcm-initial-password'
  5. W Settings → Link hosts wpisz dwa wiersze: adres podany w HQBIRD_CLUSTER_ADDRESS (master) i adres hosta Docker dla replica. Nie wpisujesz portu: RCM czyta porty parowania 7450-7459. Port parowania odpowiada około 30 sekund po tym, jak kontener jest healthy. Okno Initialize proponuje folder /databases/replica/..., który leży poza wolumenami: zmień go. To okno ma około 1000 px wysokości i się nie przewija: zmniejsz skalę strony, jeśli nie widzisz jego przycisków. Sprawdzone w przeglądarce 2026-11-16. Porównaj odcisk replica z tym w jego dzienniku. Zostaw RCM URL puste. Potem kontynuuj od kroku 4 w instrukcja klastra na Linuxie (folder bazy danych, rejestracja, inicjalizacja replica). Na folder bazy danych replica użyj folderu na wolumenie db, na przykład /db/replica. Sprawdzone: wiersz zapisany na master był na replica po 30 sekundach.

Aby pominąć opcje -f, wpisz COMPOSE_FILE=compose.yaml:compose.master.yaml (albo ...replica.yaml) do .env.

Jeden host Docker. compose.cluster-one-host.yaml to kompletny plik z obydwoma kontenerami:

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

Kontenery sięgają siebie po nazwie w sieci projektu, więc porty klastra nie są publikowane. W Link hosts wpisz hqbird-master i hqbird-replica. Firebird kontenera master jest na porcie 3050, Firebird kontenera replica na 3051; konsola to https://<docker host>:7444.

Zasady:

  • Rola i jej ustawienia są czytane tylko przy pierwszym uruchomieniu. Później inna wartość HQBIRD_CLUSTER_ROLE daje ostrzeżenie w dzienniku i nie zmienia niczego. Aby później zmienić klaster, użyj HQ Monitor (Clusters) albo poleceń fbagent --cluster-init i fbagent --cluster-pairing wewnątrz kontenera.
  • Złe ustawienie (nieznana rola, master bez HQBIRD_CLUSTER_ADDRESS, ustawienie drugiej roli) zatrzymuje start, zanim cokolwiek zostanie zainstalowane. Dziennik mówi, co wpisać ([hqbird-boot] error: ...); Docker uruchamia kontener ponownie, a dziennik powtarza wiersz, aż poprawisz ustawienie.
  • Okno parowania replica jest otwarte przez 24 godziny. Restart kontenera, który nie jest jeszcze w żadnym klastrze, otwiera je znowu. Aby zamknąć port parowania przed innymi sieciami, użyj HQBIRD_RCM_ALLOW albo zapory; po powiązaniu możesz usunąć port z ports:.
  • Do przełączenia (usługa RCM) każdy host potrzebuje drugiego węzła i jego opublikowanego portu: zobacz sekcję 7.3.

7.2. Z HQCenter

HQCenter dodaje instancję do klastra tak, jak dodaje serwer. Nie ustawiaj HQBIRD_CLUSTER_ROLE. W HQCenter podaj adres hosta Docker jako adres członka. W compose.yaml opublikuj porty składników klastra:

Składnik Port Publikuj, gdy
węzeł klastra listen_port węzła (na przykład 7051) instancja jest członkiem klastra
RCM 7443 HQCenter robi z tego agenta RCM
konsola operatora RCM 7444 jak wyżej; ustaw operator_addr na 0.0.0.0:7444 w ustawieniach RCM

Agent instaluje węzeł (i RCM) kilka minut po zapisaniu klastra. Do tego czasu port węzła nie odpowiada. W HQCenter ustaw listen_port węzła na opublikowany port. Replica czeka, aż agent RCM wgra CA klastra.

Sprawdzone 2026-11-16 bez roli: agenci zainstalowali węzły i RCM, a wszyscy członkowie byli znowu running po docker compose down i up -d.

7.3. Przełączenie między dwoma kontenerami

Usługa RCM przenosi rolę master bazy danych z jednego hosta na drugi. Dla usługi każdy host potrzebuje dwóch węzłów: węzła master i węzła replica. Link hosts daje każdemu hostowi jeden węzeł, więc drugie węzły dodajesz sam. Sprawdzone 2026-11-16 na parze z sekcji 7.1: przełączenie trwało 25 sekund, dotychczasowy master stał się replica tylko do odczytu, a wiersz zapisany na nowym master pojawił się na tej replica 15 sekund później.

Kroki używają operatorskiego API RCM na porcie konsoli. curl pyta o hasło rcmadmin; -k pomija sprawdzenie własnego certyfikatu klastra:

Command
RCM=https://203.0.113.10:7444
api() { curl -sk --digest -u rcmadmin -H 'Content-Type: application/json' "$@"; }
  1. Opublikuj port drugiego węzła na obu hostach: port węzła + 10. W compose.master.yaml i compose.replica.yaml usuń # z wiersza "7061:7061", a potem uruchom docker compose up -d z tymi samymi opcjami -f. Zrób to przed pierwszym uruchomieniem, jeśli możesz.

  2. Podaj każdemu węzłowi adres jego hosta Docker. RCM podaje ten adres i port Firebird aplikacjom; bez niego dostają adres kontenera:

    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 pokazuje identyfikatory węzłów (<host name>-master, <host name>-replica).

  3. Dodaj drugie węzły do dokumentu klastra: węzeł master na hoście replica i jego węzeł replica na hoście master, oba z listen_port 7061. Odczytaj dokument, dodaj dwóch członków i jedno powiązanie i odeślij go z jego rewizją:

    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

    Agenci instalują potem dwie usługi węzła (30 sekund w teście na dwóch hostach; może to potrwać kilka minut). docker compose exec hqbird systemctl list-units --type=service pokazuje potem dwie usługi hqclusternode w każdym kontenerze.

    Następnie daj obu węzłom replica folder bazy danych na wolumenie db. Bez niego przełączenie z powrotem albo przejęcie awaryjne zatrzymuje się po punkcie bez powrotu, a usługa przechodzi w 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. Zdefiniuj usługę. host to identyfikator agenta hosta. Ścieżka na drugim hoście to ścieżka pliku replica: <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. Sprawdź, a potem przełącz:

    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>

Po przełączeniu .../services/shop/master podaje adres drugiego hosta Docker i jego port Firebird. Aplikacje muszą łączyć się z tym adresem. Przełączenie potrzebuje replica, która jest IN_SYNC: jest nią po pierwszym zapisie na master (35 sekund w teście).

Routers i automatyczne przejęcie. Router (HAProxy) daje aplikacjom jeden adres, który podąża za master. W obrazach do 2027.2.33 włącznie router się nie uruchamia (sekcja 9); następny obraz ma poprawkę. Automatyczne przejęcie potrzebuje router jako świadka. Sprawdzone 2026-11-17 w laboratorium, na 2027.2.33 z obejściem i na obrazie testowym z poprawką:

  • Router jest członkiem klastra z rolą router. Agent instaluje pakiet haproxy z repozytorium Debian, także w każdym nowym kontenerze: kontener potrzebuje dostępu do repozytorium. Opublikuj port router (3051 w przykładzie).

  • Gdy router był tylko na hoście RCM, RCM sam przeniósł master 84 sekundy po zatrzymaniu kontenera drugiego hosta; operacja trwała 10 sekund. Gdy ten host wrócił, rejoin zrobił z niego znowu replica.

  • Gdy router jest na każdym hoście, automatyczne przejęcie się nie zaczyna: zgłosić się musi więcej niż połowa router, a jeden z dwóch jest na utraconym hoście.

  • RCM działa w kontenerze master. Gdy ten host przepada, RCM przepada razem z nim i nic nie przenosi master samodzielnie.

8. Porty, zapora, druga instancja

Publikuj każdy port z tym samym numerem na zewnątrz i wewnątrz kontenera (3051:3051, nie 3051:3050). Agent i klaster zgłaszają port, który widzą wewnątrz kontenera.

Port Co Potrzebny
HQBIRD_FB_PORT (3050) Firebird zawsze
20000 + port Firebird (23050) HQ Monitor zawsze
listen_port węzła (7051) węzeł klastra członek klastra
port węzła + 10 (7061) drugi węzeł hosta usługa z przełączeniem (sekcja 7.3)
7443, 7444 RCM, konsola operatora RCM ten agent jest RCM (jeden na host)
port parowania (7450) port parowania agenta replica z rolą, aż zostanie powiązana

Agent sam łączy się z HQCenter (ruch wychodzący); nie potrzebuje portu przychodzącego.

Docker publikuje porty z pominięciem ufw. Sprawdzone: gdy ufw przepuszczał tylko port 22, porty Firebird i HQ Monitor były otwarte z internetu. Użyj zapory zewnętrznej, publikuj na jednym adresie hosta ("10.0.0.5:23050:23050") albo dodaj reguły do łańcucha iptables DOCKER-USER.

Druga instancja na jednym hoście potrzebuje własnego folderu, name: projektu, hostname, HQBIRD_FB_PORT i portów. Nazwa projektu tworzy nazwy wolumenów (<name>_opt, …): przy tej samej nazwie drugie uruchomienie bierze wolumeny i kontener pierwszego.

Instancja 1 Instancja 2
name:, hostname: hqbird-fb40-3051 hqbird-fb40-3052
HQBIRD_FB_PORT 3051 3052
ports: 3051, 23051, 7052 3052, 23052, 7053

Zasady dla N instancji na jednym zewnętrznym adresie IP:

  • Firebird 3050 + N, HQ Monitor 20000 + port Firebird, węzeł klastra 7051 + N (ustaw ten sam listen_port w HQCenter). Pomiń 3050, 23050 i 7051, gdy host już uruchamia Firebird albo HQbird poza Dockerem.
  • Tylko jedna instancja na host może być RCM (7443, 7444).
  • Z rolą w klastrze (sekcja 7.1) każda instancja hosta potrzebuje własnego slotu: HQBIRD_PAIRING_PORT=7451 i HQBIRD_NODE_PORT=7052 dla drugiej, 7452 i 7053 dla trzeciej.
  • Jedna instancja zużywa około 200-250 MB pamięci bez obciążenia. Sprawdzone: trzy instancje FB 4.0 na 2 vCPU / 4 GB, jedna z obciążeniem.
  • Inne linie Firebird na tym samym hoście idą tymi samymi zasadami, z własnym obrazem (hqbird2027-fb50, …) i nazwami (hqbird-fb50-3054).

Dodaj instancję (tu trzecią: 3053, 23053, 7054) z compose.yaml pierwszej. Zamiana 3051 zmienia też name:, hostname:, HQBIRD_FB_PORT i port HQ Monitor:

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. Znane problemy

  • Po ręcznym połączeniu agenta z HQCenter przez fbagent --enroll uruchom fbagent --refresh-apply-launcher jako root, inaczej samodzielna aktualizacja agenta kończy się błędem “no goafts CA is pinned”.
  • W skryptach uruchamiaj docker compose exec z -T i </dev/null. Bez nich czyta standardowe wejście i zabiera resztę skryptu, który wysyłasz przez ssh ... bash -s.
  • Zanim agent zostanie połączony z HQCenter, jego dziennik pokazuje ostrzeżenia goafts mTLS settings are incomplete i bootstrap CA not found. To jest normalne.
  • Kontener oddaje /opt/hqbird użytkownikowi root po każdej instalacji (potrzebuje tego samodzielna aktualizacja agenta). Agent zapisuje ostrzeżenie, że nie może zaktualizować /opt/hqbird/version.json; możesz je zignorować.
  • Obrazy do 2027.2.32 włącznie: foldery otwarte do zapisu. W tych obrazach /etc, /usr i /usr/lib mają tryb 0777, a niektóre pliki kontenera może zapisywać każde konto. Każde konto w kontenerze może zmienić to, co uruchamia root. Agent odmawia też takiego folderu (root trust directory: /usr is writable by group or others): instalator w trybie aktualizacji pada wtedy w nowym kontenerze, a kontener uruchamia się raz za razem. Użyj obrazu 2027.2.33 lub nowszego. Nie dawaj dostępu do powłoki w kontenerze starszego obrazu użytkownikom, którym nie ufasz.
  • Obrazy do 2027.2.32 włącznie: RCM utworzone ręcznie nie uruchamia się w nowym kontenerze. Gdy tworzysz RCM przez fbagent --cluster-init wewnątrz kontenera, agent tworzy konto systemu operacyjnego hqbirdrcm. Nowy kontener go nie ma (User=hqbirdrcm: invalid userid, kontener jest unhealthy). Nowsze obrazy trzymają konta na wolumenie state. Klaster utworzony przez HQCenter nie jest tym dotknięty.
  • Obrazy do 2027.2.33 włącznie: router (HAProxy) nie uruchamia się. Dla członka klastra z rolą router agent instaluje pakiet haproxy i usługę router, ale haproxy.service pada. Zastępnik systemd w obrazie nie wstawia wartości $CONFIG, $PIDFILE i $EXTRAOPTS do wiersza polecenia i nie czyta pliku uzupełniającego, a nic nie tworzy folderu /run/haproxy. Następny obraz ma poprawkę. Do tego czasu podawaj aplikacjom adres z .../services/<alias>/master i nie dodawaj członka router.
  • Obraz 2027.2.33: nowy kontener nie uruchamia się po dodaniu router. Dziennik ma chown: invalid user: 'haproxy', a Docker uruchamia kontener raz za razem. Aby go uruchomić, usuń plik usr/lib/tmpfiles.d/haproxy.conf na wolumenie state. Następny obraz ma poprawkę.

10. Budowanie obrazów

Dla zespołu wydania. Na hoście Windows z plikami wydania w dist\releases zaloguj się do GHCR tokenem, który ma write:packages, a potem zbuduj, wyślij do rejestru i podpisz:

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

Nowy pakiet (pierwsze wysłanie linii) jest prywatny. W ustawieniach pakietu organizacji IBSurgeon ustaw jego widoczność na publiczną.

-ContextOnly przygotowuje tylko folder budowania (dist\hqbird2027-docker\fbNN-<version>) i wypisuje polecenie docker build do uruchomienia na hoście Docker z Linuksem.

Budowanie zatrzymuje się, gdy folder albo plik obrazu pod /etc lub /usr może zapisywać każde konto (folder budowania pochodzi z Windows, gdzie tryby giną). Testy skryptów kontenera, ustawień klastra i plików Compose: go test ./ops/docker/.