Hướng dẫn này dành cho quản trị viên chạy HQbird 2027 trong Docker. Một container là một instance Firebird với mọi thành phần HQbird:

  • Firebird (bản dựng HQbird của một dòng: 5.0, 4.0, 3.0 hoặc 2.5);
  • HQbird agent (fbagent): sao lưu, giám sát, các tác vụ bảo trì, cập nhật, kết nối tới HQCenter;
  • HQ Monitor: bảng điều khiển web của instance;
  • nút cluster (hqclusternode) và RCM (hqbirdrcm): agent cài chúng khi HQCenter thêm instance này vào một cluster, hoặc khi bạn gán cho container một vai trò cluster (mục 7). Không có vai trò và không có HQCenter, container không chạy thành phần cluster nào.

Container cài HQbird bằng cùng trình cài đặt ngoại tuyến như một máy chủ (hướng dẫn cài đặt Linux). Agent sau đó cập nhật Firebird, HQ Monitor, các thành phần cluster và chính nó từ HQCenter, như trên một máy chủ. Dữ liệu, cấu hình, giấy phép, chứng chỉ HQCenter và các chương trình đã cập nhật nằm trên các volume: chúng còn đó khi bạn tạo lại container hoặc đổi image.

Bản phát hành hiện tại: 2027.2.33 (2026-11-16): Firebird 2.5.9, 3.0.15, 4.0.8 và 5.0.5, agent 3.4.0, HQ Monitor 1.57.0, RCM và node 2027.5.12.

Đã kiểm tra ngày 2026-11-16 trên Ubuntu 22.04.5 (2 vCPU / 4 GB), Docker 29.10.0, Compose 5.7.1, image hqbird2027-fb40:2027.2.33 (lần kiểm tra đầu: 2026-11-11, image 2027.2.27). Cài đặt từng bước cho Ubuntu 22.04: hqbird2027-docker-install-fb40.ru.md (tiếng Nga), hqbird2027-docker-install-fb40.pt.md (tiếng Bồ Đào Nha).

Vai trò cluster (mục 7.1) và việc chuyển vai trò (mục 7.3) đã được kiểm tra ngày 2026-11-16 trên các image 5.0, 4.0, 3.0 và 2.5, với hai “máy chủ” là hai địa chỉ của một máy ảo, và trên hai máy chủ Docker riêng (hai droplet, image 4.0 2027.2.33). Ngày 2026-11-17 phần còn lại được kiểm tra trên hai máy chủ Docker với image 5.0 2027.2.33: một cluster tạo bằng tay trong các container 2027.2.32 và chuyển sang image mới (cả hai container healthy trong 35 giây), HQBIRD_RCM_ALLOW, các trang Services của bảng điều khiển RCM và chuyển đổi dự phòng tự động. Các router (HAProxy) không khởi động trong các image đến 2027.2.33 (mục 9); image tiếp theo có bản sửa.

1. Các image

Image Firebird Cổng mặc định
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

Các image nằm trong GitHub Container Registry của IBSurgeon (https://github.com/orgs/IBSurgeon/packages). Chúng công khai: bạn không cần đăng nhập. <version> là phiên bản bộ cài HQbird, ví dụ 2027.2.33. Thẻ 2027.2 là image 2027.2.x mới nhất.

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

Các image được ký bằng cosign. Khóa công khai hqbird-cosign.pub chưa được công bố (2026-11-16). Các image 2027.2.33 đã được ký. Khi bạn có khóa, hãy kiểm tra image trước khi dùng:

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

2. Lần khởi động đầu tiên

  1. Sao chép compose.yaml (từ ops/docker/ của bản phát hành) vào một thư mục trên máy chủ Docker.

  2. Đặt mật khẩu SYSDBA vào một tệp mà chỉ bạn đọc được:

    Command
    mkdir -p secrets && openssl rand -hex 12 > secrets/sysdba_password && chmod 600 secrets/sysdba_password
  3. Trong compose.yaml, đặt image:, hostname:, và bỏ # khỏi các dòng secrets: mà bạn dùng.

  4. Khởi động container:

    Command
    docker compose up -d
  5. Theo dõi quá trình cài đặt (vài phút ở lần khởi động đầu):

    Command
    docker compose logs -f

    Trên 2 vCPU, việc cài đặt mất khoảng 20 giây. Xong khi nhật ký hiện [hqbird-boot] ready: firebird.service=active ... và docker compose ps hiện healthy.

Sau đó:

  • Firebird: <docker host>:3050.
  • HQ Monitor: http://<docker host>:23050/, đăng nhập admin. Trình cài đặt tạo mật khẩu; hãy đọc nó bằng docker compose exec hqbird cat /opt/hqbird/conf/access.properties.
  • Id của agent trong HQCenter: tên máy chủ + ngày cài đặt (YYMMDD) + -fbNN, ví dụ hqbird-fb40-3051261111-fb40.

Giữ tên máy chủ. Danh tính giấy phép của instance là machine-id trên volume state và id của agent. Một volume state mới là một lần cài đặt mới.

3. Thiết lập

Các thiết lập chỉ được đọc ở lần khởi động đầu (lúc cài đặt).

Thiết lập Việc nó làm
HQBIRD_FB_PORT Cổng Firebird bên trong container (mặc định 3050). HQ Monitor dùng 20000 + cổng này
HQBIRD_HQM_PORT một cổng HQ Monitor khác
HQBIRD_AGENT_ID id của agent (mặc định: tạo từ tên máy chủ, ngày và cổng)
HQBIRD_HQM_LOGIN + bí mật hqmonitor_password tên đăng nhập HQ Monitor
HQBIRD_TRIAL_EMAIL, HQBIRD_TRIAL_ZONE yêu cầu giấy phép dùng thử (bạn chấp nhận chính sách quyền riêng tư)
HQBIRD_DEBUG=1 cài các tệp gỡ lỗi Firebird
bí mật sysdba_password mật khẩu SYSDBA của một Firebird mới
bí mật license một tệp giấy phép
bí mật attach attach.json từ HQCenter: kết nối agent với HQCenter của bạn
HQBIRD_CLUSTER_ROLE master hoặc replica: một cluster không có HQCenter (mục 7). Để trống: không có cluster
HQBIRD_CLUSTER_ADDRESS master, bắt buộc: địa chỉ hoặc tên DNS của máy chủ Docker, theo cách replica và trình duyệt của bạn tới được nó. Một danh sách cách nhau bằng dấu phẩy; mục đầu đi vào RCM URL
HQBIRD_CLUSTER_ID master: id của cluster (mặc định: tên máy chủ)
bí mật rcm_password master: mật khẩu của tên đăng nhập RCM rcmadmin (mặc định: một mật khẩu được tạo)
HQBIRD_RCM_ALLOW replica: chỉ những RCM này được phép mời container (IP, CIDR, tên máy chủ; mặc định: bất kỳ). Hãy ghi địa chỉ máy chủ Docker của master: replica nhìn thấy địa chỉ đó. Trên một máy chủ Docker, replica nhìn thấy gateway của mạng Docker của nó
HQBIRD_PAIRING_PORT, HQBIRD_NODE_PORT khe cluster: cổng ghép nối 7450-7459 và cổng nút = cổng ghép nối - 399 (mặc định 7450 và 7051)

4. Các volume

Volume Đường dẫn Nội dung
opt /opt Firebird, agent, HQ Monitor, nút cluster, RCM
state /var/lib/hqbird-container các unit, sudoers, dữ liệu HQ Monitor, nhật ký agent, machine-id, trạng thái cài đặt, các tài khoản hệ điều hành được tạo lúc chạy (người dùng dịch vụ RCM)
trust /usr/libexec/hqbird-fbagent trình khởi chạy cập nhật của agent và kho tin cậy
rootwork /var/lib/hqbird-fbagent thư mục làm việc của trình khởi chạy cập nhật
db /db cơ sở dữ liệu (đặt cơ sở dữ liệu của bạn ở đây)
backup /backup các bản sao lưu

Không gắn thư mục của máy chủ lên opt, state, trust và rootwork. Bạn có thể dùng thư mục của máy chủ cho db và backup; hãy giao chúng cho uid 84 (người dùng firebird của image):

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

Hãy sao lưu cả sáu volume cùng nhau.

5. Công việc hằng ngày

Tác vụ Lệnh
Trạng thái của các dịch vụ docker compose exec hqbird systemctl list-units --type=service
Khởi động lại 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
Nhật ký docker compose logs --since 1h
Dừng (Firebird đóng các cơ sở dữ liệu) docker compose stop

Bên trong container, systemctl điều khiển các dịch vụ HQbird. Đó không phải systemd: nó hỗ trợ các lệnh mà các chương trình HQbird dùng (start, stop, restart, status, is-active, enable, disable, show, list-units, daemon-reload).

6. Cập nhật

Có hai cách cập nhật. Cả hai đều giữ dữ liệu của bạn.

  • Từ HQCenter (như trên một máy chủ): HQCenter cập nhật agent, HQ Monitor, Firebird, nút cluster và RCM bên trong container.

  • Image mới: đổi image: sang phiên bản mới, rồi:

    Command
    docker compose pull && docker compose up -d

    Khi khởi động, container chạy trình cài đặt của image mới ở chế độ cập nhật. Nếu HQCenter đã cập nhật agent lên phiên bản mới hơn phiên bản image có, trình cài đặt không chạy (không hạ phiên bản); nhật ký nói vậy.

Một container mới (một image mới, hoặc docker compose down và up -d không có -v) giữ cluster: vai trò, id của cluster, RCM, các nút và liên kết tới máy chủ kia nằm trên các volume. Các thiết lập cluster trong tệp compose không được đọc lại. Các image đến 2027.2.32 có hai khiếm khuyết ở đây: xem mục 9.

7. Cluster

Có hai cách tạo một cluster. Đừng trộn chúng trong một container.

7.1. Không có HQCenter: hai container với một vai trò

Một container là master và chạy trình quản lý cluster (RCM) cùng bảng điều khiển của nó. Container kia là một replica. Vai trò là một thiết lập của lần khởi động đầu: HQBIRD_CLUSTER_ROLE. Không có nó, container không chạy RCM, không chạy nút cluster và không mở cổng ghép nối. Vai trò cần image 2027.2.33 hoặc mới hơn.

Hai máy chủ Docker. Hãy cho hai container các tên máy chủ khác nhau (HQBIRD_HOSTNAME trong .env, hoặc hostname:): với cùng tên máy chủ hai agent có cùng id, và RCM từ chối replica (duplicate). Sao chép compose.master.yaml sang máy chủ master và compose.replica.yaml sang máy chủ replica, cạnh compose.yaml (ops/docker/ của bản phát hành).

  1. Trên máy chủ master, đặt địa chỉ của máy chủ Docker đó vào .env, theo cách máy chủ replica và trình duyệt của bạn tới được nó (không phải localhost, không phải địa chỉ của container):

    Command
    echo 'HQBIRD_CLUSTER_ADDRESS=203.0.113.10' >> .env
    docker compose -f compose.yaml -f compose.master.yaml up -d
  2. Trên máy chủ replica:

    Command
    docker compose -f compose.yaml -f compose.replica.yaml up -d
  3. Đọc các dòng cluster của từng container:

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

    Master hiện địa chỉ bảng điều khiển và CA hash: [hqbird-boot] cluster: role=master id=... console=https://203.0.113.10:7444 login=rcmadmin. Replica hiện cổng ghép nối và dấu vân tay của nó: [hqbird-boot] cluster: role=replica pairing port 7450: open until ..., fingerprint sha256:....

  4. Mở bảng điều khiển https://<master host>:7444. Tên đăng nhập là rcmadmin. Không có bí mật rcm_password thì mật khẩu nằm trong một tệp; RCM yêu cầu mật khẩu mới ở lần đăng nhập đầu:

    Command
    docker compose exec hqbird sh -c 'cat /opt/hqbird/fbagent-*/clusterca/*/rcm-initial-password'
  5. Trong Settings → Link hosts hãy viết hai dòng: địa chỉ bạn đã ghi trong HQBIRD_CLUSTER_ADDRESS (master) và địa chỉ máy chủ Docker của replica. Bạn không ghi cổng: RCM đọc các cổng ghép nối 7450-7459. Cổng ghép nối trả lời khoảng 30 giây sau khi container healthy. Cửa sổ Initialize đề xuất thư mục /databases/replica/..., nằm ngoài các volume: hãy đổi nó. Cửa sổ đó cao khoảng 1000 px và không cuộn: hãy thu nhỏ trang nếu bạn không thấy các nút của nó. Đã kiểm tra trong trình duyệt ngày 2026-11-16. Hãy so sánh dấu vân tay của replica với dấu vân tay trong nhật ký của nó. Hãy để RCM URL trống. Sau đó tiếp tục với bước 4 của hướng dẫn cluster Linux (thư mục cơ sở dữ liệu, ghi danh, khởi tạo replica). Với thư mục cơ sở dữ liệu của replica, hãy dùng một thư mục trên volume db, ví dụ /db/replica. Đã kiểm tra: một hàng ghi trên master có trên replica sau 30 giây.

Để bỏ các tùy chọn -f, hãy đặt COMPOSE_FILE=compose.yaml:compose.master.yaml (hoặc ...replica.yaml) vào .env.

Một máy chủ Docker. compose.cluster-one-host.yaml là một tệp đầy đủ với cả hai container:

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

Các container tới nhau theo tên trên mạng của dự án, nên các cổng cluster không được công bố. Trong Link hosts hãy viết hqbird-master và hqbird-replica. Firebird của master ở cổng 3050, Firebird của replica ở 3051; bảng điều khiển là https://<docker host>:7444.

Quy tắc:

  • Vai trò và các thiết lập của nó được đọc chỉ ở lần khởi động đầu tiên. Sau đó một HQBIRD_CLUSTER_ROLE khác ghi một cảnh báo vào nhật ký và không đổi gì. Để đổi cluster sau này, hãy dùng HQ Monitor (Clusters) hoặc các lệnh fbagent --cluster-init và fbagent --cluster-pairing bên trong container.
  • Một thiết lập sai (vai trò không biết, một master không có HQBIRD_CLUSTER_ADDRESS, một thiết lập của vai trò kia) dừng việc khởi động trước khi có gì được cài. Nhật ký nói phải viết gì ([hqbird-boot] error: ...); Docker khởi động lại container và nhật ký lặp lại dòng đó cho đến khi bạn sửa thiết lập.
  • Cửa sổ ghép nối của một replica mở trong 24 giờ. Việc khởi động lại một container chưa ở trong cluster nào sẽ mở lại cửa sổ. Để đóng cổng ghép nối với các mạng khác, hãy dùng HQBIRD_RCM_ALLOW hoặc tường lửa của bạn; sau khi liên kết bạn có thể bỏ cổng khỏi ports:.
  • Với một lần chuyển vai trò (một dịch vụ RCM), mỗi máy chủ cần một nút thứ hai và cổng đã công bố của nó: xem mục 7.3.

7.2. Với HQCenter

HQCenter thêm instance vào một cluster như cách nó thêm một máy chủ. Đừng đặt HQBIRD_CLUSTER_ROLE. Trong HQCenter, hãy đưa địa chỉ của máy chủ Docker làm địa chỉ thành viên. Trong compose.yaml, hãy công bố các cổng của các thành phần cluster:

Thành phần Cổng Khi nào công bố
nút cluster listen_port của nút (ví dụ 7051) instance là thành viên cluster
RCM 7443 HQCenter biến agent này thành RCM
bảng điều khiển toán tử RCM 7444 như trên; đặt operator_addr thành 0.0.0.0:7444 trong thiết lập RCM

Agent cài nút (và RCM) vài phút sau khi cluster được lưu. Đến lúc đó cổng nút không trả lời. Trong HQCenter, hãy đặt listen_port của nút bằng cổng đã công bố. Một replica chờ đến khi agent RCM tải CA của cluster lên.

Đã kiểm tra ngày 2026-11-16 không có vai trò: các agent đã cài các nút và RCM, và mọi thành viên lại running sau docker compose down và up -d.

7.3. Chuyển vai trò giữa hai container

Một dịch vụ RCM chuyển vai trò master của một cơ sở dữ liệu từ máy chủ này sang máy chủ kia. Với một dịch vụ, mỗi máy chủ cần hai nút: một nút master và một nút replica. Link hosts cho mỗi máy chủ một nút, nên bạn tự thêm các nút thứ hai. Đã kiểm tra ngày 2026-11-16 trên cặp của mục 7.1: việc chuyển vai trò mất 25 giây, master cũ trở thành một replica chỉ đọc, và một hàng ghi trên master mới có trên nó 15 giây sau.

Các bước dùng API toán tử RCM trên cổng bảng điều khiển. curl hỏi mật khẩu của rcmadmin; -k bỏ qua việc kiểm tra chứng chỉ riêng của cluster:

Command
RCM=https://203.0.113.10:7444
api() { curl -sk --digest -u rcmadmin -H 'Content-Type: application/json' "$@"; }
  1. Công bố cổng nút thứ hai trên cả hai máy chủ: cổng nút + 10. Trong compose.master.yaml và compose.replica.yaml, bỏ # khỏi dòng "7061:7061", rồi chạy docker compose up -d với cùng các tùy chọn -f. Hãy làm việc này trước lần khởi động đầu khi bạn có thể.

  2. Cho mỗi nút địa chỉ máy chủ Docker của nó. RCM đưa địa chỉ này và cổng Firebird cho các ứng dụng; không có nó, chúng nhận địa chỉ của container:

    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 hiện các id nút (<host name>-master, <host name>-replica).

  3. Thêm các nút thứ hai vào tài liệu cluster: một nút master trên máy chủ replica và nút replica của nó trên máy chủ master, cả hai với listen_port 7061. Đọc tài liệu, thêm hai thành viên và một liên kết, rồi gửi lại cùng bản sửa đổi của nó:

    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

    Các agent sau đó cài hai dịch vụ nút (30 giây trong lần kiểm tra trên hai máy chủ; có thể mất vài phút). docker compose exec hqbird systemctl list-units --type=service sau đó hiện hai dịch vụ hqclusternode trong mỗi container.

    Sau đó hãy cho cả hai nút replica một thư mục cơ sở dữ liệu trên volume db. Không có nó, một lần chuyển vai trò trở lại hoặc một lần chuyển đổi dự phòng dừng sau điểm không thể quay lại, và dịch vụ chuyển sang 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. Định nghĩa dịch vụ. host là id agent của máy chủ. Đường dẫn trên máy chủ thứ hai là đường dẫn của tệp 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. Kiểm tra, rồi chuyển:

    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>

Sau khi chuyển vai trò, .../services/shop/master đưa địa chỉ của máy chủ Docker kia và cổng Firebird của nó. Các ứng dụng phải kết nối tới địa chỉ đó. Một lần chuyển vai trò cần một replica đang IN_SYNC: nó là vậy, sau lần ghi đầu trên master (35 giây trong lần kiểm tra).

Các router và chuyển đổi dự phòng tự động. Một router (HAProxy) đưa cho các ứng dụng một địa chỉ đi theo master. Trong các image đến 2027.2.33, router không khởi động (mục 9); image tiếp theo có bản sửa. Chuyển đổi dự phòng tự động cần một router làm nhân chứng. Đã kiểm tra ngày 2026-11-17 trong phòng thí nghiệm, trên 2027.2.33 với một cách khắc phục tạm và trên một image thử có bản sửa:

  • Một router là thành viên cluster với vai trò router. Agent cài gói haproxy từ kho Debian, cả trong mỗi container mới: container cần truy cập được kho. Hãy công bố cổng router (3051 trong ví dụ).

  • Với một router chỉ trên máy chủ RCM, RCM tự chuyển master 84 giây sau khi container của máy chủ kia dừng; thao tác mất 10 giây. Khi máy chủ đó trở lại, rejoin biến nó thành replica lần nữa.

  • Với một router trên mỗi máy chủ, chuyển đổi dự phòng tự động không bắt đầu: hơn một nửa số router phải báo cáo, và một trong hai nằm trên máy chủ đã mất.

  • RCM chạy trong container master. Khi máy chủ đó mất, RCM cũng mất, và không có gì tự chuyển master.

8. Cổng, tường lửa, instance thứ hai

Hãy công bố mỗi cổng với cùng một số ở ngoài và ở trong container (3051:3051, không phải 3051:3050). Agent và cluster báo cổng chúng nhìn thấy bên trong container.

Cổng Là gì Khi cần
HQBIRD_FB_PORT (3050) Firebird luôn luôn
20000 + cổng Firebird (23050) HQ Monitor luôn luôn
listen_port của nút (7051) nút cluster thành viên cluster
cổng nút + 10 (7061) nút thứ hai của máy chủ một dịch vụ có chuyển vai trò (mục 7.3)
7443, 7444 RCM, bảng điều khiển toán tử RCM agent này là RCM (một trên mỗi máy chủ)
cổng ghép nối (7450) cổng ghép nối của agent một replica có vai trò, cho đến khi được liên kết

Agent tự kết nối tới HQCenter (đi ra); nó không cần cổng đi vào.

Docker công bố cổng bỏ qua ufw. Đã kiểm tra: khi ufw chỉ cho phép cổng 22, các cổng Firebird và HQ Monitor mở từ Internet. Hãy dùng một tường lửa bên ngoài, công bố trên một địa chỉ máy chủ ("10.0.0.5:23050:23050"), hoặc thêm quy tắc vào chuỗi iptables DOCKER-USER.

Một instance thứ hai trên một máy chủ cần thư mục riêng, name: của dự án, hostname, HQBIRD_FB_PORT và các cổng. Tên dự án tạo tên volume (<name>_opt, …): với cùng tên, lần khởi động thứ hai lấy các volume và container của lần đầu.

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

Quy tắc cho N instance trên một IP bên ngoài:

  • Firebird 3050 + N, HQ Monitor 20000 + cổng Firebird, nút cluster 7051 + N (đặt cùng listen_port trong HQCenter). Bỏ qua 3050, 23050 và 7051 khi máy chủ đã chạy một Firebird hoặc HQbird bên ngoài Docker.
  • Chỉ một instance trên mỗi máy chủ có thể là RCM (7443, 7444).
  • Với một vai trò cluster (mục 7.1), mỗi instance của một máy chủ cần khe riêng: HQBIRD_PAIRING_PORT=7451 và HQBIRD_NODE_PORT=7052 cho instance thứ hai, 7452 và 7053 cho instance thứ ba.
  • Một instance dùng khoảng 200-250 MB bộ nhớ khi không tải. Đã kiểm tra: ba instance FB 4.0 trên 2 vCPU / 4 GB, một instance có tải.
  • Các dòng Firebird khác trên cùng máy chủ theo cùng quy tắc với image riêng (hqbird2027-fb50, …) và tên riêng (hqbird-fb50-3054).

Thêm một instance (ở đây là instance thứ ba: 3053, 23053, 7054) từ compose.yaml của instance đầu. Thay 3051 cũng đổi name:, hostname:, HQBIRD_FB_PORT và cổng 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. Các vấn đề đã biết

  • Sau khi bạn kết nối agent với HQCenter bằng fbagent --enroll làm bằng tay, hãy chạy fbagent --refresh-apply-launcher với quyền root, nếu không việc tự cập nhật của agent thất bại với “no goafts CA is pinned”.
  • Trong các script, hãy chạy docker compose exec với -T và </dev/null. Không có chúng, lệnh đọc đầu vào chuẩn và lấy phần còn lại của một script mà bạn gửi bằng ssh ... bash -s.
  • Trước khi agent được kết nối với HQCenter, nhật ký của nó hiện các cảnh báo goafts mTLS settings are incomplete và bootstrap CA not found. Điều này là bình thường.
  • Container giao /opt/hqbird cho root sau mỗi lần cài đặt (việc tự cập nhật của agent cần vậy). Agent viết một cảnh báo rằng nó không thể cập nhật /opt/hqbird/version.json; bạn có thể bỏ qua.
  • Các image đến 2027.2.32: thư mục mở để ghi. Trong các image này /etc, /usr và /usr/lib có chế độ 0777, và một số tệp của container có thể bị mọi tài khoản ghi. Bất kỳ tài khoản nào trong container cũng có thể đổi những gì root khởi động. Agent cũng từ chối một thư mục như vậy (root trust directory: /usr is writable by group or others): trình cài đặt ở chế độ cập nhật khi đó thất bại trong một container mới, và container khởi động lại hết lần này đến lần khác. Hãy dùng image 2027.2.33 hoặc mới hơn. Đừng cấp quyền truy cập shell trong container của một image cũ cho những người dùng mà bạn không tin.
  • Các image đến 2027.2.32: RCM tạo bằng tay không khởi động trong một container mới. Khi bạn tạo RCM bằng fbagent --cluster-init bên trong container, agent tạo tài khoản hệ điều hành hqbirdrcm. Một container mới không có tài khoản đó (User=hqbirdrcm: invalid userid, container là unhealthy). Các image mới hơn giữ các tài khoản trên volume state. Một cluster do HQCenter tạo không bị ảnh hưởng.
  • Các image đến 2027.2.33: một router (HAProxy) không khởi động. Với một thành viên cluster có vai trò router, agent cài gói haproxy và dịch vụ router, nhưng haproxy.service thất bại. Lớp thay thế systemd trong image không đưa các giá trị $CONFIG, $PIDFILE và $EXTRAOPTS vào dòng lệnh và không đọc tệp drop-in, và không có gì tạo thư mục /run/haproxy. Image tiếp theo có bản sửa. Đến lúc đó, hãy đưa cho các ứng dụng địa chỉ từ .../services/<alias>/master và đừng thêm một thành viên router.
  • Image 2027.2.33: một container mới không khởi động sau khi một router đã được thêm. Nhật ký có chown: invalid user: 'haproxy', và Docker khởi động container lại hết lần này đến lần khác. Để khởi động nó, hãy xóa tệp usr/lib/tmpfiles.d/haproxy.conf trên volume state. Image tiếp theo có bản sửa.

10. Xây dựng các image

Dành cho nhóm phát hành. Trên một máy chủ Windows với các tệp bản phát hành trong dist\releases, hãy đăng nhập vào GHCR bằng một token có write:packages, rồi xây dựng, đẩy và ký:

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

Một gói mới (lần đẩy đầu của một dòng) là riêng tư. Trong thiết lập gói của tổ chức IBSurgeon, hãy đặt khả năng hiển thị thành công khai.

-ContextOnly chỉ chuẩn bị thư mục xây dựng (dist\hqbird2027-docker\fbNN-<version>) và in lệnh docker build để chạy trên một máy chủ Docker Linux.

Quá trình xây dựng dừng khi một thư mục hoặc một tệp của image dưới /etc hoặc /usr có thể bị mọi tài khoản ghi (thư mục xây dựng đến từ Windows, nơi các chế độ quyền bị mất). Các kiểm tra script của container, thiết lập cluster và các tệp compose: go test ./ops/docker/.