HQbird 2027 in Docker: 관리자 안내
이 안내는 Docker에서 HQbird 2027을 운영하는 관리자를 위한 것입니다. 컨테이너 하나는 HQbird의 모든 구성 요소를 갖춘 Firebird 인스턴스 하나입니다.
- Firebird(한 계열의 HQbird 빌드: 5.0, 4.0, 3.0 또는 2.5).
- HQbird agent(
fbagent): 백업, 모니터링, 유지보수 작업, 업데이트, HQCenter 연결. - HQ Monitor: 인스턴스의 웹 콘솔.
- 클러스터 노드(
hqclusternode)와 RCM(hqbirdrcm): HQCenter가 이 인스턴스를 클러스터에 추가할 때, 또는 컨테이너에 클러스터 역할을 줄 때(7절), 에이전트가 설치합니다. 역할도 없고 HQCenter도 없으면, 컨테이너는 클러스터 구성 요소를 실행하지 않습니다.
컨테이너는 서버와 같은 오프라인 설치 프로그램으로 HQbird를 설치합니다(Linux 설치 안내). 그다음 에이전트는 서버에서와 같이 HQCenter에서 Firebird, HQ Monitor, 클러스터 구성 요소, 그리고 자기 자신을 업데이트합니다. 데이터, 구성, 라이선스, HQCenter 인증서, 업데이트된 프로그램은 볼륨에 있습니다. 컨테이너를 다시 만들거나 이미지를 바꿔도 그대로 남습니다.
현재 릴리스: 2027.2.33(2026-11-16): Firebird 2.5.9, 3.0.15, 4.0.8 및 5.0.5, agent 3.4.0, HQ Monitor 1.57.0, RCM과 노드 2027.5.12.
Ubuntu 22.04.5(2 vCPU / 4 GB), Docker 29.10.0, Compose 5.7.1, 이미지 hqbird2027-fb40:2027.2.33에서 2026-11-16에 검증했습니다(첫 검증: 2026-11-11, 이미지 2027.2.27). Ubuntu 22.04용 단계별 설치: hqbird2027-docker-install-fb40.ru.md(러시아어), hqbird2027-docker-install-fb40.pt.md(포르투갈어).
클러스터 역할(7.1절)과 스위치오버(7.3절)는 2026-11-16에 5.0, 4.0, 3.0, 2.5 이미지에서 검증했습니다. 두 “호스트”는 가상 머신 한 대의 주소 두 개였고, 서로 다른 Docker 호스트 두 대(droplet 두 개, 4.0 이미지 2027.2.33)에서도 검증했습니다. 2026-11-17에는 나머지를 Docker 호스트 두 대에서 5.0 이미지 2027.2.33으로 검증했습니다. 2027.2.32 컨테이너에서 손으로 만든 클러스터를 새 이미지로 옮긴 것(두 컨테이너 모두 35초 만에 healthy), HQBIRD_RCM_ALLOW, RCM 콘솔의 Services 페이지, 그리고 자동 페일오버입니다. router(HAProxy)는 2027.2.33까지의 이미지에서 시작하지 않습니다(9절). 다음 이미지에 수정이 들어 있습니다.
1. 이미지
| 이미지 | Firebird | 기본 포트 |
|---|---|---|
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 |
이미지는 IBSurgeon의 GitHub Container Registry에 있습니다(https://github.com/orgs/IBSurgeon/packages). 공개되어 있으므로 로그인할 필요가 없습니다. <version>은 HQbird 설치 버전입니다. 예: 2027.2.33. 태그 2027.2는 가장 새로운 2027.2.x 이미지입니다.
docker pull ghcr.io/ibsurgeon/hqbird2027-fb50:2027.2.33이미지는 cosign으로 서명되어 있습니다. 공개 키 hqbird-cosign.pub는 아직 게시되지 않았습니다(2026-11-16). 2027.2.33 이미지는 서명되어 있습니다. 키를 받으면, 사용하기 전에 이미지를 확인합니다.
cosign verify --key hqbird-cosign.pub ghcr.io/ibsurgeon/hqbird2027-fb50:2027.2.332. 첫 시작
-
릴리스의
ops/docker/에 있는compose.yaml을 Docker 호스트의 폴더로 복사합니다. -
SYSDBA 비밀번호를, 자신만 읽을 수 있는 파일에 넣습니다.
mkdir -p secrets && openssl rand -hex 12 > secrets/sysdba_password && chmod 600 secrets/sysdba_password -
compose.yaml에서image:,hostname:을 설정하고, 사용하는secrets:줄에서#을 제거합니다. -
컨테이너를 시작합니다.
docker compose up -d -
설치를 지켜봅니다(첫 시작은 몇 분이 걸릴 수 있습니다).
docker compose logs -f2 vCPU에서 설치는 약 20초입니다. 로그에
[hqbird-boot] ready: firebird.service=active ...가 나오고,docker compose ps가healthy를 보이면 끝난 것입니다.
그다음:
- Firebird:
<docker host>:3050. - HQ Monitor:
http://<docker host>:23050/, 로그인admin. 설치 프로그램이 비밀번호를 만듭니다. 다음으로 읽습니다.docker compose exec hqbird cat /opt/hqbird/conf/access.properties. - HQCenter의 에이전트 id: 호스트 이름 + 설치 날짜(YYMMDD) +
-fbNN. 예:hqbird-fb40-3051261111-fb40.
호스트 이름을 유지하십시오. 인스턴스의 라이선스 식별 정보는 state 볼륨의 machine-id와 에이전트 id입니다. 새 state 볼륨은 새 설치입니다.
3. 설정
설정은 첫 시작(설치) 때만 읽힙니다.
| 설정 | 하는 일 |
|---|---|
HQBIRD_FB_PORT |
컨테이너 안의 Firebird 포트(기본 3050). HQ Monitor는 20000 + 이 포트를 사용합니다 |
HQBIRD_HQM_PORT |
다른 HQ Monitor 포트 |
HQBIRD_AGENT_ID |
에이전트 id(기본값: 호스트 이름, 날짜, 포트로 만듭니다) |
HQBIRD_HQM_LOGIN + secret hqmonitor_password |
HQ Monitor 로그인 |
HQBIRD_TRIAL_EMAIL, HQBIRD_TRIAL_ZONE |
체험 라이선스를 요청합니다(개인정보 처리방침에 동의합니다) |
HQBIRD_DEBUG=1 |
Firebird 디버그 파일을 설치합니다 |
secret sysdba_password |
새 Firebird의 SYSDBA 비밀번호 |
secret license |
라이선스 파일 |
secret attach |
HQCenter의 attach.json: 에이전트를 자신의 HQCenter에 연결합니다 |
HQBIRD_CLUSTER_ROLE |
master 또는 replica: HQCenter 없는 클러스터(7절). 비움: 클러스터 없음 |
HQBIRD_CLUSTER_ADDRESS |
master, 필수: replica와 브라우저가 도달하는 Docker 호스트의 주소 또는 DNS 이름. 쉼표로 구분한 목록. 첫 값이 RCM URL에 들어갑니다 |
HQBIRD_CLUSTER_ID |
master: 클러스터 id(기본값: 호스트 이름) |
secret rcm_password |
master: RCM 로그인 rcmadmin의 비밀번호(기본값: 생성된 값) |
HQBIRD_RCM_ALLOW |
replica: 이 RCM만 컨테이너를 초대할 수 있습니다(IP, CIDR, 호스트 이름. 기본값: 아무나). master의 Docker 호스트 주소를 적습니다. replica는 그 주소를 봅니다. Docker 호스트가 하나일 때 replica는 자신의 Docker 네트워크 게이트웨이를 봅니다 |
HQBIRD_PAIRING_PORT, HQBIRD_NODE_PORT |
클러스터 슬롯: 페어링 포트 7450-7459, 노드 포트 = 페어링 포트 - 399(기본 7450과 7051) |
4. 볼륨
| 볼륨 | 경로 | 내용 |
|---|---|---|
opt |
/opt |
Firebird, 에이전트, HQ Monitor, 클러스터 노드, RCM |
state |
/var/lib/hqbird-container |
unit, sudoers, HQ Monitor 데이터, 에이전트 로그, machine-id, 설치 상태, 실행 중에 만들어지는 OS 계정(RCM 서비스 사용자) |
trust |
/usr/libexec/hqbird-fbagent |
에이전트의 업데이트 런처와 trust |
rootwork |
/var/lib/hqbird-fbagent |
업데이트 런처의 작업 폴더 |
db |
/db |
데이터베이스(데이터베이스는 여기에 둡니다) |
backup |
/backup |
백업 |
opt, state, trust, rootwork에는 호스트 폴더를 마운트하지 마십시오. db와 backup에는 호스트 폴더를 쓸 수 있습니다. 이미지의 firebird 사용자인 uid 84에 주십시오.
chown 84:84 /srv/hqbird/db /srv/hqbird/backup볼륨 여섯 개를 함께 백업합니다.
5. 일상 작업
| 작업 | 명령 |
|---|---|
| 서비스 상태 | docker compose exec hqbird systemctl list-units --type=service |
| 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 |
| 로그 | docker compose logs --since 1h |
| 중지(Firebird가 데이터베이스를 닫습니다) | docker compose stop |
컨테이너 안에서 systemctl이 HQbird 서비스를 제어합니다. 이것은 systemd가 아닙니다. HQbird 프로그램이 사용하는 명령을 지원합니다(start, stop, restart, status, is-active, enable, disable, show, list-units, daemon-reload).
6. 업데이트
업데이트 방법은 두 가지입니다. 둘 다 데이터를 유지합니다.
-
HQCenter에서(서버에서와 같이): HQCenter는 컨테이너 안의 에이전트, HQ Monitor, Firebird, 클러스터 노드, RCM을 업데이트합니다.
-
새 이미지:
image:를 새 버전으로 바꾼 뒤 다음을 실행합니다.docker compose pull && docker compose up -d시작할 때 컨테이너는 새 이미지의 설치 프로그램을 업데이트 모드로 실행합니다. HQCenter가 이미 에이전트를 이미지가 가진 것보다 새 버전으로 업데이트했다면, 설치 프로그램은 실행되지 않습니다(다운그레이드하지 않습니다). 로그에 그 내용이 나옵니다.
새 컨테이너(새 이미지, 또는 -v 없이 docker compose down과 up -d)는 클러스터를 유지합니다. 역할, 클러스터 id, RCM, 노드, 다른 호스트로의 링크는 볼륨에 있습니다. compose 파일의 클러스터 설정은 다시 읽히지 않습니다. 2027.2.32까지의 이미지에는 여기에 결함 두 가지가 있습니다. 9절을 보십시오.
7. 클러스터
클러스터를 만드는 방법은 두 가지입니다. 한 컨테이너에서 섞지 마십시오.
7.1. HQCenter 없이: 역할이 있는 컨테이너 두 개
한 컨테이너가 master이고, 콘솔이 있는 클러스터 관리자(RCM)를 실행합니다. 다른 하나는 replica입니다. 역할은 첫 시작의 설정 HQBIRD_CLUSTER_ROLE입니다. 이것이 없으면 컨테이너는 RCM도 클러스터 노드도 실행하지 않고, 페어링 포트도 열지 않습니다. 역할에는 이미지 2027.2.33 이상이 필요합니다.
Docker 호스트 두 대. 두 컨테이너에 서로 다른 호스트 이름을 주십시오(.env의 HQBIRD_HOSTNAME, 또는 hostname:). 호스트 이름이 같으면 두 에이전트의 id가 같아지고, RCM은 replica를 거부합니다(duplicate). compose.master.yaml을 master 호스트로, compose.replica.yaml을 replica 호스트로, compose.yaml 옆에 복사합니다(릴리스의 ops/docker/).
-
master 호스트에서, 그 Docker 호스트의 주소를
.env에 넣습니다. replica 호스트와 브라우저가 도달하는 주소입니다(localhost가 아니고, 컨테이너의 주소도 아닙니다).echo 'HQBIRD_CLUSTER_ADDRESS=203.0.113.10' >> .env docker compose -f compose.yaml -f compose.master.yaml up -d -
replica 호스트에서:
docker compose -f compose.yaml -f compose.replica.yaml up -d -
각 컨테이너의 클러스터 줄을 읽습니다.
docker compose logs | grep -E 'cluster:|CA hash|Password'master는 콘솔 주소와
CA hash를 보여 줍니다.[hqbird-boot] cluster: role=master id=... console=https://203.0.113.10:7444 login=rcmadmin. replica는 페어링 포트와 지문을 보여 줍니다.[hqbird-boot] cluster: role=replica pairing port 7450: open until ..., fingerprint sha256:.... -
콘솔
https://<master host>:7444를 엽니다. 로그인은rcmadmin입니다. secretrcm_password가 없으면 비밀번호는 파일에 있습니다. RCM은 첫 로그인 때 새 비밀번호를 요청합니다.docker compose exec hqbird sh -c 'cat /opt/hqbird/fbagent-*/clusterca/*/rcm-initial-password' -
Settings → Link hosts에 두 줄을 적습니다.
HQBIRD_CLUSTER_ADDRESS에 준 주소(master)와, replica의 Docker 호스트 주소입니다. 포트는 적지 않습니다. RCM은 페어링 포트 7450-7459를 읽습니다. 페어링 포트는 컨테이너가healthy가 된 뒤 약 30초 후에 응답합니다. Initialize 창이 제안하는 폴더는/databases/replica/...이며, 이것은 볼륨 밖입니다. 바꾸십시오. 그 창은 높이가 약 1000 px이고 스크롤되지 않습니다. 버튼이 보이지 않으면 페이지를 축소합니다. 브라우저에서 2026-11-16에 검증했습니다. replica의 지문을 그 로그에 있는 것과 비교합니다. RCM URL은 비워 둡니다. 그다음 Linux 클러스터 안내의 4단계로 계속합니다(데이터베이스 폴더, enroll, replica 초기화). replica의 데이터베이스 폴더에는db볼륨의 폴더를 사용합니다. 예:/db/replica. 검증에서, master에 쓴 행은 30초 만에 replica에 있었습니다.
-f 옵션을 생략하려면, .env에 COMPOSE_FILE=compose.yaml:compose.master.yaml(또는 ...replica.yaml)을 넣습니다.
Docker 호스트 한 대. compose.cluster-one-host.yaml은 두 컨테이너를 모두 담은 완전한 파일입니다.
docker compose -f compose.cluster-one-host.yaml up -d컨테이너는 프로젝트의 네트워크에서 이름으로 서로 도달합니다. 그래서 클러스터 포트는 게시되지 않습니다. Link hosts에 hqbird-master와 hqbird-replica를 적습니다. master의 Firebird는 포트 3050, replica의 Firebird는 3051입니다. 콘솔은 https://<docker host>:7444입니다.
규칙:
- 역할과 그 설정은 첫 시작 때만 읽힙니다. 나중에 다른
HQBIRD_CLUSTER_ROLE을 주면 로그에 경고가 나오고, 아무것도 바뀌지 않습니다. 나중에 클러스터를 바꾸려면 HQ Monitor(Clusters)나, 컨테이너 안의fbagent --cluster-init및fbagent --cluster-pairing명령을 사용합니다. - 잘못된 설정(알 수 없는 역할,
HQBIRD_CLUSTER_ADDRESS가 없는 master, 다른 역할의 설정)은 아무것도 설치되기 전에 시작을 멈춥니다. 로그가 무엇을 써야 하는지 알려 줍니다([hqbird-boot] error: ...). Docker는 컨테이너를 다시 시작하고, 설정을 고칠 때까지 로그가 그 줄을 반복합니다. - replica의 페어링 창은 24시간 열려 있습니다. 아직 어떤 클러스터에도 들어 있지 않은 컨테이너를 다시 시작하면, 창이 다시 열립니다. 페어링 포트를 다른 네트워크에 대해 닫으려면
HQBIRD_RCM_ALLOW또는 방화벽을 사용합니다. 링크한 뒤ports:에서 그 포트를 뺄 수 있습니다. - 스위치오버(RCM 서비스)에서는 각 호스트에 두 번째 노드와 그 게시 포트가 필요합니다. 7.3절을 보십시오.
7.2. HQCenter와 함께
HQCenter는 서버를 추가할 때와 같이 인스턴스를 클러스터에 추가합니다. HQBIRD_CLUSTER_ROLE을 설정하지 마십시오. HQCenter에서 구성원 주소로 Docker 호스트의 주소를 주십시오. compose.yaml에서 클러스터 구성 요소의 포트를 게시합니다.
| 구성 요소 | 포트 | 게시할 때 |
|---|---|---|
| 클러스터 노드 | 노드의 listen_port(예: 7051) |
인스턴스가 클러스터 구성원일 때 |
| RCM | 7443 | HQCenter가 이 에이전트를 RCM으로 만들 때 |
| RCM 운영자 콘솔 | 7444 | 위와 같음. RCM 설정에서 operator_addr을 0.0.0.0:7444로 설정합니다 |
에이전트는 클러스터가 저장된 뒤 몇 분 후에 노드(와 RCM)를 설치합니다. 그때까지 노드 포트는 응답하지 않습니다. HQCenter에서 노드의 listen_port를 게시한 포트로 설정합니다. replica는 RCM 에이전트가 클러스터 CA를 업로드할 때까지 기다립니다.
2026-11-16에 역할 없이 검증했습니다. 에이전트가 노드와 RCM을 설치했고, docker compose down과 up -d 뒤에 모든 구성원이 다시 running이 되었습니다.
7.3. 두 컨테이너 사이의 스위치오버
RCM 서비스는 데이터베이스의 master 역할을 한 호스트에서 다른 호스트로 옮깁니다. 서비스에서는 각 호스트에 노드 두 개가 필요합니다. master 노드와 replica 노드입니다. Link hosts는 각 호스트에 노드를 하나씩 주므로, 두 번째 노드는 직접 추가합니다. 2026-11-16에 7.1절의 쌍에서 검증했습니다. 스위치오버는 25초가 걸렸고, 이전 master는 읽기 전용 replica가 되었으며, 새 master에 쓴 행은 15초 뒤에 거기에 있었습니다.
단계는 콘솔 포트의 RCM 운영자 API를 사용합니다. curl은 rcmadmin의 비밀번호를 묻습니다. -k는 클러스터 자신의 인증서 확인을 건너뜁니다.
RCM=https://203.0.113.10:7444
api() { curl -sk --digest -u rcmadmin -H 'Content-Type: application/json' "$@"; }-
두 번째 노드 포트를 게시합니다. 두 호스트 모두에서 노드 포트 + 10입니다.
compose.master.yaml과compose.replica.yaml에서"7061:7061"줄의#을 제거하고, 같은-f옵션으로docker compose up -d를 실행합니다. 할 수 있다면 첫 시작 전에 하십시오. -
각 노드에 그 Docker 호스트의 주소를 줍니다. RCM은 이 주소와 Firebird 포트를 애플리케이션에 줍니다. 이것이 없으면 애플리케이션은 컨테이너의 주소를 받습니다.
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는 노드 id를 보여 줍니다(<host name>-master,<host name>-replica). -
두 번째 노드를 추가합니다. 클러스터 문서에, replica 호스트의 master 노드와 master 호스트의 그 replica 노드를 추가합니다. 둘 다
listen_port는 7061입니다. 문서를 읽고, 구성원 두 개와 링크 하나를 추가한 뒤, 리비전과 함께 돌려보냅니다.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그다음 에이전트가 노드 서비스 두 개를 설치합니다(호스트 두 대에서의 검증에서는 30초. 몇 분이 걸릴 수도 있습니다). 그다음
docker compose exec hqbird systemctl list-units --type=service를 실행하면, 각 컨테이너에hqclusternode서비스가 두 개 보입니다.그다음 두 replica 노드 모두에
db볼륨의 데이터베이스 폴더를 줍니다. 이것이 없으면, 되돌리는 스위치오버나 페일오버는 되돌릴 수 없는 지점 뒤에서 멈추고, 서비스는failed가 됩니다.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 -
서비스를 정의합니다.
host는 호스트의 에이전트 id입니다. 두 번째 호스트의 경로는 replica 파일의 경로입니다.<database folder of the replica>/<master member id>/<file>:cat > service.json <<'J' {"alias":"shop","router_port":3051,"members":[ {"host":"<agent id of host A>","master_node":"<host A>-master","replica_node":"<host A>-replica","path":"/db/shop.fdb","priority":100}, {"host":"<agent id of host B>","master_node":"<host B>-master","replica_node":"<host B>-replica","path":"/db/replica/<host A>-master/shop.fdb","priority":50}]} J api -X PUT "$RCM/v1/services/shop?check=1" --data-binary @service.json # a check, nothing is stored api -X PUT $RCM/v1/services/shop --data-binary @service.json -
확인한 다음 전환합니다:
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>
스위치오버 뒤에 .../services/shop/master는 다른 Docker 호스트의 주소와 그 Firebird 포트를 줍니다. 애플리케이션은 그 주소에 연결해야 합니다. 스위치오버에는 IN_SYNC인 replica가 필요합니다. master에 첫 쓰기를 한 뒤에 그렇게 됩니다(검증에서는 35초).
router와 자동 페일오버. router(HAProxy)는 master를 따라가는 주소 하나를 애플리케이션에 줍니다. 2027.2.33까지의 이미지에서는 router가 시작하지 않습니다(9절). 다음 이미지에 수정이 들어 있습니다. 자동 페일오버에는 증인으로서의 router가 필요합니다. 2026-11-17에 실험실에서, 우회 방법을 넣은 2027.2.33과 수정이 들어간 테스트 이미지로 검증했습니다.
- router는 역할
router인 클러스터 구성원입니다. 에이전트는 Debian 저장소에서haproxy패키지를 설치합니다. 새 컨테이너마다 마찬가지입니다. 컨테이너는 저장소에 접근할 수 있어야 합니다. router 포트를 게시합니다(예에서는 3051). - RCM 호스트에만 router가 있을 때, 다른 호스트의 컨테이너가 멈춘 뒤 84초 후에 RCM이 스스로 master를 옮겼습니다. 작업은 10초가 걸렸습니다. 그 호스트가 돌아오자
rejoin이 그것을 다시 replica로 만들었습니다. - 각 호스트에 router가 있으면 자동 페일오버는 시작하지 않습니다. router의 절반보다 많이 보고해야 하는데, 둘 중 하나는 잃은 호스트에 있기 때문입니다.
- RCM은 master 컨테이너 안에서 실행됩니다. 그 호스트를 잃으면 RCM도 함께 잃고, master를 스스로 옮기는 것은 아무것도 없습니다.
8. 포트, 방화벽, 두 번째 인스턴스
각 포트는 컨테이너 밖과 안에서 같은 번호로 게시합니다(3051:3051. 3051:3050이 아닙니다). 에이전트와 클러스터는 컨테이너 안에서 보는 포트를 보고합니다.
| 포트 | 내용 | 필요할 때 |
|---|---|---|
HQBIRD_FB_PORT(3050) |
Firebird | 항상 |
| 20000 + Firebird 포트(23050) | HQ Monitor | 항상 |
노드 listen_port(7051) |
클러스터 노드 | 클러스터 구성원 |
| 노드 포트 + 10(7061) | 호스트의 두 번째 노드 | 스위치오버가 있는 서비스(7.3절) |
| 7443, 7444 | RCM, RCM 운영자 콘솔 | 이 에이전트가 RCM일 때(호스트당 하나) |
| 페어링 포트(7450) | 에이전트의 페어링 포트 | 역할이 있는 replica. 링크될 때까지 |
에이전트는 스스로 HQCenter에 연결합니다(송신). 수신 포트는 필요하지 않습니다.
Docker는 ufw를 지나 포트를 게시합니다. 검증에서, ufw가 포트 22만 허용해도 Firebird와 HQ Monitor 포트는 인터넷에서 열려 있었습니다. 외부 방화벽을 쓰거나, 호스트 주소 하나에 게시하거나("10.0.0.5:23050:23050"), iptables 체인 DOCKER-USER에 규칙을 추가하십시오.
호스트 한 대의 두 번째 인스턴스에는 자신의 폴더, 프로젝트 name:, hostname, HQBIRD_FB_PORT, 포트가 필요합니다. 프로젝트 이름이 볼륨 이름을 만듭니다(<name>_opt, …). 이름이 같으면 두 번째 시작이 첫 인스턴스의 볼륨과 컨테이너를 가져갑니다.
| 인스턴스 1 | 인스턴스 2 | |
|---|---|---|
name:, hostname: |
hqbird-fb40-3051 |
hqbird-fb40-3052 |
HQBIRD_FB_PORT |
3051 | 3052 |
ports: |
3051, 23051, 7052 | 3052, 23052, 7053 |
외부 IP 하나 위의 N개 인스턴스 규칙:
- Firebird는
3050 + N, HQ Monitor는20000 +Firebird 포트, 클러스터 노드는7051 + N입니다(HQCenter에서 같은listen_port를 설정합니다). 호스트가 이미 Docker 밖에서 Firebird 또는 HQbird를 실행 중이면 3050, 23050, 7051을 건너뜁니다. - 호스트당 RCM이 될 수 있는 인스턴스는 하나뿐입니다(7443, 7444).
- 클러스터 역할(7.1절)에서는 호스트의 각 인스턴스에 자신의 슬롯이 필요합니다. 두 번째는
HQBIRD_PAIRING_PORT=7451과HQBIRD_NODE_PORT=7052, 세 번째는7452와7053입니다. - 인스턴스 하나는 부하가 없을 때 약 200-250 MB의 메모리를 사용합니다. 검증: 2 vCPU / 4 GB에서 FB 4.0 인스턴스 세 개, 그중 하나에 부하.
- 같은 호스트의 다른 Firebird 계열도 자신의 이미지(
hqbird2027-fb50, …)와 이름(hqbird-fb50-3054)으로 같은 규칙을 따릅니다.
첫 인스턴스의 compose.yaml에서 인스턴스를 추가합니다(여기서는 세 번째: 3053, 23053, 7054). 3051을 바꾸면 name:, hostname:, HQBIRD_FB_PORT, HQ Monitor 포트도 바뀝니다.
sudo ss -ltnp | grep -E ':(3053|23053|7054)\b' # must print nothing
sudo mkdir -p /srv/hqbird-fb40-3053/secrets
cd /srv/hqbird-fb40-3053
sudo sh -c 'openssl rand -hex 12 > secrets/sysdba_password && chmod 600 secrets/sysdba_password'
sudo sed -e 's/3051/3053/g' -e 's/7052/7054/g' /srv/hqbird-fb40-3051/compose.yaml | sudo tee compose.yaml >/dev/null
sudo docker compose config | grep -E '^name:|hostname:|HQBIRD_FB_PORT|published:'
sudo docker compose up -d
sudo docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'9. 알려진 문제
- 에이전트를 손으로
fbagent --enroll하여 HQCenter에 연결한 뒤, root로fbagent --refresh-apply-launcher를 실행하십시오. 그렇지 않으면 에이전트의 자체 업데이트가 “no goafts CA is pinned"로 실패합니다. - 스크립트에서는
docker compose exec를-T와</dev/null과 함께 실행합니다. 이것이 없으면 표준 입력을 읽고,ssh ... bash -s로 보낸 스크립트의 나머지를 가져갑니다. - 에이전트가 HQCenter에 연결되기 전에, 로그에 경고
goafts mTLS settings are incomplete와bootstrap CA not found가 나옵니다. 이것은 정상입니다. - 컨테이너는 설치할 때마다
/opt/hqbird를 root에 줍니다(에이전트의 자체 업데이트에 필요합니다). 에이전트는/opt/hqbird/version.json을 업데이트할 수 없다는 경고를 씁니다. 무시해도 됩니다. - 2027.2.32까지의 이미지: 쓰기가 열린 폴더. 이 이미지에서는
/etc,/usr,/usr/lib의 모드가 0777이고, 컨테이너의 일부 파일은 모든 계정이 쓸 수 있습니다. 컨테이너 안의 어떤 계정도 root가 시작하는 것을 바꿀 수 있습니다. 에이전트도 그런 폴더를 거부합니다(root trust directory: /usr is writable by group or others). 그러면 새 컨테이너에서 업데이트 모드의 설치 프로그램이 실패하고, 컨테이너는 거듭 다시 시작합니다. 이미지 2027.2.33 이상을 사용하십시오. 더 오래된 이미지의 컨테이너에서는, 신뢰하지 않는 사용자에게 셸 접근을 주지 마십시오. - 2027.2.32까지의 이미지: 손으로 만든 RCM은 새 컨테이너에서 시작하지 않습니다. 컨테이너 안에서
fbagent --cluster-init으로 RCM을 만들면, 에이전트는 OS 계정hqbirdrcm을 만듭니다. 새 컨테이너에는 그것이 없습니다(User=hqbirdrcm: invalid userid, 컨테이너는unhealthy). 더 새 이미지는 계정을state볼륨에 유지합니다. HQCenter가 만든 클러스터는 영향을 받지 않습니다. - 2027.2.33까지의 이미지: router(HAProxy)가 시작하지 않습니다. 역할
router인 클러스터 구성원에 대해 에이전트는haproxy패키지와 router 서비스를 설치하지만,haproxy.service는 실패합니다. 이미지 안의 systemd 대용은$CONFIG,$PIDFILE,$EXTRAOPTS의 값을 명령줄에 넣지 않고, drop-in 파일도 읽지 않으며,/run/haproxy폴더를 만드는 것도 없습니다. 다음 이미지에 수정이 들어 있습니다. 그때까지는 애플리케이션에.../services/<alias>/master의 주소를 주고,router구성원을 추가하지 마십시오. - 이미지 2027.2.33: router를 추가한 뒤 새 컨테이너가 시작하지 않습니다. 로그에
chown: invalid user: 'haproxy'가 있고, Docker는 컨테이너를 거듭 시작합니다. 시작하게 하려면state볼륨의 파일usr/lib/tmpfiles.d/haproxy.conf를 제거합니다. 다음 이미지에 수정이 들어 있습니다.
10. 이미지 빌드
릴리스 팀을 위한 것입니다. Windows 호스트에서 릴리스 파일이 dist\releases에 있을 때, write:packages가 있는 토큰으로 GHCR에 로그인한 다음, 빌드하고, push하고, 서명합니다.
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새 패키지(한 계열의 첫 push)는 비공개입니다. IBSurgeon 조직의 패키지 설정에서 공개 범위를 public으로 설정합니다.
-ContextOnly는 빌드 폴더만 준비하고(dist\hqbird2027-docker\fbNN-<version>), Linux Docker 호스트에서 실행할 docker build 명령을 출력합니다.
이미지의 /etc 또는 /usr 아래에 있는 폴더나 파일을 모든 계정이 쓸 수 있으면 빌드가 멈춥니다(빌드 폴더는 Windows에서 오며, 거기서 모드가 사라집니다). 컨테이너 스크립트, 클러스터 설정, compose 파일의 테스트: go test ./ops/docker/.