이 페이지는 기계 번역되었습니다. 영어 원본을 읽어보세요. English

다른 언어: Русский, Português.

이 가이드는 깨끗한 서버 두 대에서 작동하는 Firebird 5.0 복제본까지 안내합니다. 설치와 폴더 하나를 제외한 모든 작업은 브라우저의 RCM 콘솔에서 수행합니다. 스크린샷은 2026-11-17 실행에서 가져왔습니다: kit 2027.2.33, RCM 및 노드 2027.5.12, Ubuntu 24.04, 영어 UI. 이전 2026-11-08 실행의 보고서: hqbird2027-rcm-cluster-check-report.ru.md (러시아어, “Прогон 2” 섹션). 스크린샷 없이 명령만: hqbird2027-linux-cluster-runbook.md. 각 RCM 페이지 상세: RCM 사용자 가이드 (저장소 hqcluster-node, docs/user-guide/).

이 가이드는 kit 2027.2.24 이상을 대상으로 합니다. kit 2027.2.22의 경우, git 이력에서 2026-11-07자 이 파일의 판본을 참조하십시오.

다운로드할 kit은 2027.2.33 (2026-11-16)입니다: agent 3.4.0, HQ Monitor 1.57.0, RCM 및 노드 2027.5.12, Firebird 5.0.5.1917. 이 가이드는 2026-11-17에 이 kit으로 검증했습니다 (서버 두 대, Ubuntu 24.04, 3 MB 및 167 MB 데이터베이스): 모든 단계가 통과했습니다. 본문은 해당 실행의 결과를 “2026-11-17 실행"으로 지칭합니다. 스크린샷은 같은 날 같은 kit으로 진행한 두 번째 실행에서 가져왔습니다 (3 MB 및 2.88 GB 데이터베이스). 나머지 수치는 여전히 2026-11-08 실행에서 가져온 것입니다. 2027.2.27 이후 kit이 클러스터에 대해 변경한 사항:

Kit 변경 사항
2027.2.29 (agent 3.1.0, RCM 2027.5.9) 기본적으로 클러스터 없음 (아래 참조). 한 호스트의 여러 agent가 클러스터에 참여 가능: 각자 고유한 페어링 포트 (7450–7459)와 노드 포트를 가짐. fbagent --cluster-leave. HQ Monitor의 Clusters 페이지
2027.2.30 (RCM 2027.5.10) 서비스의 스위치오버 및 페일오버, 라우터
2027.2.31 (agent 3.3.0, RCM 2027.5.11) 설치 프로그램이 터미널에서 텍스트 인터페이스를 엶 (1단계). RCM의 Services 페이지. 어떤 HQCenter에도 연결되지 않은 서버는 agent, HQ Monitor, fbmcp를 스스로 업데이트함
2027.2.33 (agent 3.4.0, RCM 2027.5.12) RCM이 알림을 Telegram, 웹훅 또는 이메일로 전송 (“다음에 살펴볼 것”). Docker 컨테이너 두 개로 구성된 클러스터: Docker 안내

모든 변경 사항: What’s New.

agent (fbagent) 3.1.0 이상인 kit (2027.2.29부터)은 기본적으로 클러스터를 만들지 않습니다: RCM 없음, 페어링 창 없음, 클러스터 포트는 방화벽에서 닫힌 상태로 유지됩니다. 1단계에서 마스터에서 RCM을, 복제본에서 검색 모드를 켭니다.

소요 시간: 약 30분에 데이터베이스 복사 시간 추가 (1 Gbit/s 네트워크에서 3 GB당 약 1분).

얻게 되는 것

서버 1 서버 2
역할 마스터 + RCM 콘솔 복제본
데이터베이스 /databases/master/*.fdb /databases/replica/<replica node>/<master node>/*.fdb
서비스 firebird, hqbirdfbagent-fb50, hqbirdmonitor-fb50, fbmcp, hqbirdrcm, hqclusternode-master-p3050 동일하지만 hqclusternode-replica-p3050이며 hqbirdrcm 없음 (이전 kit은 자체 RCM을 여기에 남기며 중지됨)

필요한 것

  • Linux x86-64 서버 두 대 (Ubuntu 24.04에서 검증), 2코어, 4 GB 메모리.
  • 디스크 공간. 마스터: 여유 공간 ≥ 데이터베이스 크기의 105 % (잠금 중에 .delta 파일이 증가함). 복제본: 여유 공간 ≥ 데이터베이스 크기의 105 %에 하한 limits.free_space_floor_gb (기본값 1 GB)를 더한 값. 기존 복제본 위로 재초기화하면 끝까지 이전 파일을 유지하므로, 복제본 볼륨에는 약 2 × 데이터베이스 크기가 필요합니다. 공간이 부족하면 이전 복제본 제거 상자 (8단계)를 사용하면 105 %에 하한을 더한 값으로 충분합니다.
  • 서버 간 네트워크: 포트 3050, 7051, 7443, 7444, 7450. 이는 서버의 첫 번째 인스턴스 (슬롯 0)의 포트입니다. 서버의 두 번째 인스턴스는 페어링 포트 7451과 노드 포트 7052를 사용합니다.
  • PC에서 마스터의 포트 7444 (RCM 콘솔)에 접근 가능 (직접 또는 SSH 터널 경유).
  • sudo 권한이 있는 사용자.

방화벽. 설치 프로그램은 활성화된 firewalld 또는 ufw (모든 시스템 언어)에 포트를 엽니다: 3050과 23050은 항상, 클러스터 포트는 1단계의 옵션에 대해서만. 마스터: 7443, 7444, 7051. 복제본: 7450, 7051. agent는 페어링 창이 끝나거나 호스트가 연결되면 7450을 다시 닫습니다. Ubuntu에서는 ufw가 보통 비활성화되어 있습니다. 그 경우 설치 프로그램은 한 줄을 기록합니다. 예를 들어 마스터에서: no active firewall (firewalld or ufw): ports 3050, 23050, 7443, 7444, 7051/tcp are not opened by this install; they are reachable from every network; close them or enable a firewall. 클라우드에서는 클라우드 방화벽으로 포트를 닫으십시오: 외부에서는 본인 주소만, 서버 간에는 내부 네트워크만.

아래는 실행 시 사용한 주소입니다: 마스터 10.114.0.5, 복제본 10.114.0.6 (사설 네트워크). 본인의 주소를 사용하십시오.

1단계. 두 서버에 설치

각 서버에서:

Command
V=2027.2.33
wget https://ib-aid.com/download/hqbird/v2027/hqbird2027-fb50-linux-$V.run
wget https://ib-aid.com/download/hqbird/v2027/hqbird2027-fb50-linux-$V.run.sha256
sha256sum -c hqbird2027-fb50-linux-$V.run.sha256
sudo sh hqbird2027-fb50-linux-$V.run

터미널에서 설치 프로그램이 텍스트 인터페이스를 엽니다 (2027.2.31부터의 kit). 첫 페이지에는 Cluster RCM off, discovery mode off 줄이 있습니다. Cluster를 열고 한 줄을 변경하십시오:

Cluster 페이지의 줄 마스터 복제본
Cluster manager (RCM) on off
Discovery mode (24 h) off (이 agent가 RCM을 실행함) on

Cluster id (기본값: 호스트 이름), RCM admin password (기본값: 생성됨), Pairing port (기본값: 첫 번째 여유 포트, 7450) 줄은 그대로 둘 수 있습니다. 뒤로 가서 (Esc) Install을 선택하십시오. 설치 프로그램이 계획을 보여줍니다: Enter를 누르십시오. 그런 다음 Nothing on this host was changed yet. Start the install now?라고 묻습니다. 커서는 No에 있습니다: Yes로 이동하여 Enter를 누르십시오. 설치 프로그램이 누락된 라이브러리 (예: libtommath1)를 스스로 추가합니다. 텍스트 인터페이스 전체: hqbird2027-linux-setup-guide.md.

--no-tui 사용 시, 그리고 kit 2027.2.29–2027.2.30에서는 설치 프로그램이 질문합니다. 첫 번째는 Install as planned? Yes/No입니다: y로 답하십시오. 그런 다음 클러스터 질문 두 개를 합니다. 기본 답은 No입니다 (Enter):

질문 마스터 복제본
Install the cluster manager (RCM) on this host and make a new cluster? [y/N] y Enter (No)
Turn on discovery mode for 24 hours (an RCM on the network may invite this agent into its cluster; port 7450)? [y/N] 묻지 않음: 이 agent가 RCM을 실행함 y

또는 답을 옵션으로 제공하십시오: 터미널에서는 Cluster 페이지가 열리기 전에 값을 설정합니다. 터미널 없이 실행할 때도 사용하십시오: --yes만 사용하면 둘 다 No를 의미합니다.

Command
sudo sh hqbird2027-fb50-linux-$V.run --rcm on               # master
sudo sh hqbird2027-fb50-linux-$V.run --cluster-pairing on   # replica

설치에는 약 1분이 걸립니다 (2026-11-17 실행: 마스터 61초, 복제본 43초). kit 2027.2.33으로 마스터에서의 출력 끝부분 (해시는 여기서 축약됨; 아래 예시의 클러스터 id는 2026-11-08 실행에서 가져온 hq27d-m):

text
Done: agent hqbirdfbagent-fb50 in /opt/hqbird/fbagent-fb50, Firebird 5.0.5.1917 in /opt/firebird (port 3050).
HQ Monitor: http://localhost:23050/ (login admin; password in /opt/hqbird/conf/access.properties)
RCM:        https://10.114.0.5:7444 (cluster hq27d-m)
CA hash:    sha256:9754e0be…087cb195
Login:      rcmadmin
Password:   in /opt/hqbird/fbagent-fb50/clusterca/hq27d-m/rcm-initial-password (read it with sudo; RCM asks for a new one at the first login)
Pairing:    not needed: this agent runs the RCM; other agents link through it
fbmcp:      2027.2.24, service running; local only (remote mode: sudo fbmcp ctl hqbird-install --allow-from CIDR)

복제본에서:

text
RCM:        off; turn it on in HQbird Monitor or with fbagent --cluster-init <id>
Pairing:    port 7450 open until 2026-11-09T16:25:27Z (fingerprint sha256:0d137a71…09fe44cf); an RCM may invite this host

이전 키트는 마스터에서 Pairing: not opened (this agent runs the RCM)를 출력합니다.

마스터의 RCM: 및 CA hash: 줄과 레플리카의 Pairing: 줄을 기록하십시오. 3단계에서 fingerprint가 필요합니다.

이전 키트(3.1.0 이전 에이전트, 예를 들어 키트 2027.2.27)는 클러스터 관련 질문을 하지 않습니다. 모든 서버에 RCM을 설치하고 모든 곳에서 페어링 창을 엽니다. 마스터의 RCM을 사용하십시오. 두 번째 서버의 RCM은 링크 후에 스스로 중지됩니다.

나중에, 설치 프로그램 없이. 서버의 HQ Monitor에서 Clusters, Cluster on this server 섹션을 엽니다. 마스터에서: Enable the cluster console (RCM); HQ Monitor가 방화벽에서 7443 및 7444를 엽니다. 레플리카에서: Open the pairing window for 24 hours. 에이전트 사용자로 명령을 사용해도 동일합니다:

Command
cd /opt/hqbird/fbagent-fb50
sudo -u firebird ./fbagent --cluster-init hq27d-m     # master; open 7443 and 7444 yourself
sudo -u firebird ./fbagent --cluster-pairing on       # replica

페어링 창이 열려 있는 동안 에이전트는 방화벽에서 페어링 포트를 엽니다. 창이 끝나거나 호스트가 링크되면 포트를 닫습니다.

출력에는 비밀번호가 없습니다. RCM 비밀번호는 Password: 줄의 파일에, SYSDBA 비밀번호는 /root/fbagent-install-sysdba.txt에, HQ Monitor 비밀번호는 /opt/hqbird/conf/access.properties에 있습니다.

라이선스를 설치할 필요가 없습니다. 새 에이전트는 스스로 7일 평가판을 시작하며, 클러스터 노드가 작동합니다.

2단계. RCM에 로그인

마스터의 RCM: 줄에 있는 주소를 엽니다. PC에서 포트 7444가 닫혀 있으면 SSH 터널과 https://localhost:7444를 사용하십시오:

Command
ssh -L 7444:127.0.0.1:7444 <user>@<master>

PC에서 포트 7444가 사용 중이면 다른 로컬 포트를 사용하십시오. 예를 들어 -L 17444:127.0.0.1:7444와 https://localhost:17444입니다.

브라우저가 인증서에 대해 경고합니다. 클러스터 CA가 RCM 인증서에 서명했습니다. 로그인 페이지에 Cluster CA hash가 표시됩니다. 이를 설치 프로그램 출력의 CA hash: 줄과 비교하십시오. 일치하면 CA 인증서(같은 페이지의 Download the CA certificate (hqcluster-ca.crt) 링크)를 신뢰할 수 있는 인증서로 설치하거나 경고를 수락하십시오. 일치하지 않으면 로그인하지 말고 주소를 확인하십시오.

RCM sign-in
RCM sign-in

사용자 이름은 rcmadmin입니다. 비밀번호는 Password: 줄의 파일에 있습니다:

Command
# the path is from the Password: line of your output
sudo cat /opt/hqbird/fbagent-fb50/clusterca/hq27d-m/rcm-initial-password

RCM은 즉시 새 비밀번호(최소 12자)를 요청합니다:

New password at the first sign-in
New password at the first sign-in

2027.5.12 이전의 RCM은 이 페이지를 계속 다시 로드할 수 있었습니다. RCM 2027.5.12(키트 2027.2.33)에 수정 사항이 있습니다.

비밀번호 변경 후 마스터의 에이전트는 1분 이내에 rcm-initial-password 파일을 스스로 삭제합니다. 이전 키트의 경우 두 번째 서버에도 자체 RCM이 있습니다. 링크 후 에이전트는 해당 이전 클러스터를 cluster/left/ 폴더로 이동합니다. 에이전트 3.1.0은 그곳의 rcm-initial-password를 삭제하지만, 이전 에이전트는 삭제하지 않습니다. 그런 다음 파일을 직접 삭제하십시오:

Command
# on server 2, after step 3
sudo find /opt/hqbird -name rcm-initial-password
sudo rm <path from the find output>

/opt/hqbirdrcm/initial-admin.json 파일은 삭제하지 마십시오. 이 파일에는 이전 비밀번호의 해시만 들어 있으며, 이 파일이 없으면 사용자 파일을 잃은 RCM이 기본 비밀번호로 시작합니다.

비밀번호 변경 후 RCM은 즉시 Settings → Link hosts를 엽니다. 클러스터에는 아직 노드가 없습니다. Releases in the mirror 목록에는 에이전트가 노드를 설치하는 데 사용하는 hqbirdrcm 및 hqclusternode 릴리스가 표시됩니다.

Link hosts after the sign-in
Link hosts after the sign-in

3단계. 호스트 링크

목록의 첫 번째 행은 이미 채워져 있습니다(RCM 호스트). 두 번째 행을 추가하십시오. 마스터가 접근할 수 있는 레플리카 주소입니다. 서버에 공통 DNS가 없으면 IP를 입력하십시오. RCM은 문자열을 그대로 유지하며, 노드는 이 문자열로 서로를 찾습니다.

List of hosts
List of hosts

Check hosts를 클릭하십시오. 포트가 없는 호스트의 경우 RCM은 페어링 포트 7450–7459를 읽고 응답하는 각 에이전트에 대해 host:port 형식으로 한 행을 표시합니다(여기서는 10.114.0.6:7450). 하나의 포트만 읽으려면 host:port를 입력하십시오. RCM 호스트에는 페어링 창이 필요하지 않습니다. RCM은 자체 레지스트리에서 해당 에이전트를 찾습니다. Certificate fingerprint를 설치 프로그램 출력(레플리카의 Pairing: 줄)과 비교하십시오. 일치해야 합니다. 두 번째 호스트의 상태는 Ready to link입니다. Member ID 열에는 호스트가 클러스터에서 받는 이름이 표시됩니다: <host name>-<role>, 예를 들어 hq27d-m-master. 인스턴스 접미사(-fb50)는 호스트에 여러 에이전트가 있을 때만 추가됩니다.

Check of the hosts
Check of the hosts

각 행에는 체크박스, 포트, 인스턴스 및 노드 포트가 있습니다. Link는 체크된 행만 처리합니다. 오류 상태의 행은 체크할 수 없으며 다른 행을 중단시키지 않습니다. 표 아래에서 RCM 2027.5.12는 10.114.0.6, no agent: closed or no answer: 7451-7459와 같은 줄을 기록합니다. 이는 다른 에이전트가 응답하지 않는 호스트의 페어링 포트를 나타냅니다. 오류가 아닙니다.

마스터는 프로덕션 데이터베이스가 위치할 호스트입니다. Link를 클릭하고 확인하십시오:

Confirmation
Confirmation

진행 상황: “Joining → Joined → The node starts → Running”. 실행에서 링크는 56초가 걸렸습니다(2026-11-17 실행: 47초).

Link progress
Link progress
Done
Done

이제 Overview에 두 개의 노드(마스터와 레플리카)가 표시됩니다. 링크 직후 레플리카는 1분 동안 “stale” 상태일 수 있으며, 그 후 “online"이 됩니다.

Overview: two nodes
Overview: two nodes

이미 링크된 호스트에 대해 Check hosts를 다시 클릭하면 페어링 포트에서 응답하는 에이전트가 없거나 호스트에 접근할 수 없다고 표시됩니다. 해당 호스트의 페어링 창이 닫혀 있고 방화벽의 페어링 포트도 닫혀 있기 때문입니다. 오류가 아닙니다.

마스터가 있는 클러스터에 호스트 하나 추가. 한 행만 링크하면 lone_master와 함께 거부됩니다. 해당 행이 무엇이 되는지 지정하십시오. 해당 마스터의 레플리카로 만들려면 -replica-of <master member>를, 자체 마스터로 만들려면 -new-master(Link hosts 페이지의 체크박스)를 추가하십시오.

4단계. 마스터의 데이터베이스 폴더

마스터에서 데이터베이스는 firebird 사용자가 접근할 수 있는 폴더에 있어야 합니다:

Command
sudo install -d -o firebird -g firebird -m 0770 /databases/master
# example: the sample database from the kit
sudo cp /opt/firebird/examples/empbuild/employee.fdb /databases/master/
sudo chown firebird:firebird /databases/master/employee.fdb

레플리카에서는 아무것도 준비할 필요가 없습니다. Create folder

Initialize 대화상자의 버튼은 복사본용 폴더를 생성합니다(6단계).

5단계. 마스터에 데이터베이스 등록

Databases → Nodes 표에서 마스터의 행 → Enroll.

  • 해당 서버의 폴더 경로: /databases/master, recursive.
  • 파일 마스크 포함: *.fdb.
  • 동기화 추적 테이블: Verify 버튼이 행 수를 비교하는 테이블. 이 목록은 등록하는 각 데이터베이스마다 설정합니다. 필드를 비워 두면: 데이터베이스가 자신의 publication 테이블을 계산합니다. 이미 관리 중인 데이터베이스의 경우, 마스터 데이터베이스의 페이지에서 목록을 변경하십시오.
Enroll form
Enroll form

Preview → 데이터베이스 선택 → Enroll selected 후 확인.

Confirmation of the enrollment
Confirmation of the enrollment

결과는 “Enrolled: 2.“와 함께 마스터의 Firebird를 재시작해야 한다는 힌트가 표시됩니다. 그 아래의 “No new databases matched.” 텍스트는 오류가 아닙니다: 데이터베이스가 이미 등록된 것입니다.

Result of the enrollment
Result of the enrollment

데이터베이스가 재시작을 기다립니다:

Waits for the restart
Waits for the restart

마스터의 아무 데이터베이스 행에서 Restart Firebird of the master를 클릭하고(모두에 대해 한 번의 재시작이면 충분합니다) 확인하십시오. 마스터의 Firebird에 대한 모든 연결이 몇 초 동안(실행에서는 4초) 끊기므로 적절한 시간을 선택하십시오.

Restart of Firebird of the master
Restart of Firebird of the master

재시작 후 마스터 노드는 CONFIGURED 상태가 됩니다. 각 데이터베이스에는 publication OFF 배지가 표시되고, 복제본은 “not paired"를 표시합니다.

After the restart
After the restart

6단계. 복제본 초기화

데이터베이스 행의 복제본 열에서 → Initialize. 대화상자의 제목은 “Initialize database?“입니다.

Initialize dialog
Initialize dialog
  • Publication. 데이터베이스의 publication이 꺼져 있는 동안 Firebird는 변경 사항을 저널에 기록하지 않으며, 복제본은 아무것도 받지 못합니다. 대화상자가 이를 알려 주고 Sync publication and initialize 버튼을 표시합니다. 이를 클릭하십시오: RCM이 기본 키 또는 고유 키가 있는 모든 테이블을 publication에 추가하고 즉시 초기화를 시작합니다. publication이 꺼져 있는 동안에는 Initialize 버튼이 도움이 되지 않습니다: 마스터 노드가 거부합니다(publication_off).
  • Replica folder: 대화상자가 /databases/replica/<replica node>를 제안하며, 실행에서는 /databases/replica/hq27d-r-replica입니다. 호스트의 각 복제본 노드에는 자체 폴더가 필요합니다. 그대로 두십시오. 필드에 “✗ The folder does not exist"가 표시되면 Create folder를 클릭하십시오. 그러면 “✓ The folder was created.“가 표시됩니다. 복사본은 /databases/replica/hq27d-r-replica/hq27d-m-master/로 이동합니다. 다음 데이터베이스의 경우 폴더가 이미 설정되어 있으며 대화상자가 이를 변경하지 않습니다.
  • Method: Smooth(기본값). 잠금 전에 쓰기 트랜잭션을 확인합니다. Standard는 데이터베이스를 즉시 잠급니다.
  • 새 복제본의 경우 “Let … stop its Firebird for this reinit” 및 “Remove the old replica if space is short” 확인란은 필요하지 않습니다.

첫 publication 동기화 후 애플리케이션을 다시 연결하십시오. publication이 켜지기 전에 열린 마스터 데이터베이스 연결은 다시 연결할 때까지 저널링되지 않습니다. 2026-11-17 실행에서 Sync publication and initialize 전에 열린 연결이 복사 후 약 9,500개 행을 기록했지만 복제본은 그중 아무것도 받지 못했습니다. RCM은 양쪽 모두에 “Ok"를 표시했고, Verify(9단계)만이 “Not ok (desynced)“를 표시했습니다. 새 연결의 행은 즉시 복제되었습니다. 따라서 데이터베이스의 첫 Sync publication 후에는 애플리케이션을 다시 연결하고(또는 마스터의 Firebird를 재시작하고) 쓰기 없이 Verify를 실행하십시오. 복제본이 행을 놓치면 reinit(7단계)을 실행하십시오.

부하 상태에서의 첫 초기화. 마스터의 아카이브에 아직 저널 세그먼트가 없는 동안 데이터베이스에 쓰기가 발생하면 Smooth가 거부할 수 있습니다. 데이터베이스 행에 long_transactions: … the archive holds no segment yet와 UI 언어로 된 힌트가 표시됩니다:

Refusal of the smooth method
Refusal of the smooth method

실행에서는 Sync publication and initialize 후에도 이 문제가 발생했습니다(보고서의 발견 사항 G-04). 이 시점에는 publication이 이미 켜져 있습니다. 마스터 데이터베이스에 “archive: 1 seg” 이상이 표시될 때까지 기다린 후(실행에서는 15초), Smooth 방법으로 Initialize를 다시 클릭하십시오. 또는 Standard를 선택하십시오. 2026-11-17 실행(한 연결에서 ≈49 트랜잭션/s)에서는 Smooth가 거부되지 않았습니다.

진행 상황은 데이터베이스 행에 표시됩니다: SPACE CHECK → LOCKING → COPYING TO NODE (%) → UNLOCKING → SEEDING → RESTARTING REPLICA. 진행 상황은 페이지를 새로 고친 후에도 표시됩니다. 이 시간 동안 Initialize 버튼은 비활성화 됩니다.

Initialization progress
Initialization progress

복사 후 복제본 노드는 예정된 분에 복제본의 Firebird를 스스로 재시작합니다. 행에 시점이 표시되며, Restart Firebird of the replica 버튼을 누르면 즉시 실행됩니다. 이 순간 복제본의 Firebird에 대한 모든 연결이 끊깁니다.

Waits for the restart of Firebird of the replica
Waits for the restart of Firebird of the replica

대용량 데이터베이스도 같은 방식으로 작동합니다. 실행에서 bulk.fdb(3.13 GB)는 부하 없이 Sync publication and initialize 버튼으로 초기화되었습니다:

Copy of the large database
Copy of the large database

마스터와 복제본이 “Ok"를 표시하고 복제본의 “last applied seg"가 마스터의 “last seg"에 도달하면 완료됩니다. 새 쓰기가 없는 데이터베이스(여기서는 bulk.fdb)는 복제본에 대해 세그먼트 0과 함께 “Pending"을 표시합니다: 이는 정상입니다.

Both databases ready
Both databases ready

실행 측정값(≈55 트랜잭션/s 부하의 employee.fdb):

Database Size Master: from start to end Lock on the master Pair “Ok”
employee.fdb 4 MB 0.7 s 0.35 s after ≈1 min (waited for the replica restart)
bulk.fdb 3.13 GB 64 s (≈55 MB/s) 59 s after ≈2 min

2026-11-17 실행(킷 2027.2.33): employee.fdb(3 MB)는 3초가 걸렸습니다

마스터에서 bulk.fdb(167MB)는 15초가 걸렸습니다. 복제본 쪽은 시작 후 약 40초 뒤에 페어링되었습니다(복제본의 Firebird 재시작을 기다렸습니다).

잠금 중에도 마스터 데이터베이스는 작동합니다. 변경 사항은 .delta 파일에 기록됩니다.

나중에 발행하기. 데이터베이스에 새 테이블이 나타나면 마스터 데이터베이스의 Sync publication 버튼이 필요합니다. 이 버튼은 하나의 트랜잭션 안에서 발행 내용을 테이블과 일치시키며, Firebird는 재시작되지 않습니다.

Sync publication
Sync publication

Publication tables는 어떤 테이블이 복제되는지 보여줍니다. 키가 없는 테이블은 발행할 수 없습니다. 기본 키를 지정하십시오.

Publication tables
Publication tables

7단계. 재초기화

복제본이 마스터와 다르거나 노드가 재초기화를 요청할 때(NEEDS_REINIT) 필요합니다. 복제본 행 → Reinit, 방식은 Smooth입니다. 이미 세그먼트 아카이브가 있으며, smooth 방식은 부하 상태에서도 작동합니다. 저널 기록보다 오래된 쓰기 트랜잭션을 기다렸다가 보여줍니다.

Reinit, smooth method
Reinit, smooth method

진행 상황은 초기화 때와 같습니다. 재초기화는 보통 복제본의 Firebird 재시작이 필요하지 않습니다. 2026-11-17 실행에서는 employee.fdb의 재초기화가 복제본의 Firebird를 재시작했습니다. 복제본에 대한 연결 중단을 대비하십시오. 해당 재초기화는 마스터에서 ≈49 트랜잭션/s 상태로 4초가 걸렸으며, 쓰기가 멈춘 뒤 행 수가 일치했습니다(양쪽의 부하 테이블에 14,418행).

Copy at the reinit
Copy at the reinit

실행 측정값:

Database Load Time Lock Other
employee.fdb ≈55 트랜잭션/s 1.7초 0.32초 세그먼트에서 417개 트랜잭션 재생
bulk.fdb 없음 61초 55초 복제본의 Firebird 재시작 없음

부하 상태에서 smooth 재초기화를 한 후, 복제본은 info 경고 replication_conflict_resolved(“삽입 중인 레코드 … 가 이미 존재하므로 대신 업데이트함”)를 표시할 수 있습니다. 복제본이 이미 복사본에 있던 트랜잭션을 재생한 것입니다. 데이터는 일치합니다. 실행에서 모든 테이블의 행 수가 일치했습니다. 경고를 확인 처리할 수 있습니다 (보고서의 발견 사항 G-07).

8단계. 복제본의 디스크 공간 부족

복제본 볼륨에는 데이터베이스 크기의 ≥105%에 이전 복사본 위로 1GB의 여유가 필요합니다. 이전 복사본은 끝까지 남아 있고, 새 파일은 즉시 전체 크기를 차지합니다. 공간이 부족하면 대화 상자에 필요한 공간, 여유 공간, 이전 복사본이 차지하는 공간이 표시됩니다(RCM 추정치이며 복제본 노드가 결정). 이전 복사본 없이도 공간이 충분하면 대화 상자에서 Remove the old replica if space is short 확인란을 제안합니다.

Low space: the “Remove the old replica if space is short” box
Low space: the “Remove the old replica if space is short” box

이 확인란을 사용하면 복제본 노드는 마스터 잠금 후 복제본의 Firebird를 중지하고 이전 복사본을 삭제한 뒤 Firebird를 다시 시작합니다. 실행에서(여유 2.97GB, 새 복사본에 3.29GB 필요, 이전 복사본 3.13GB) 확인란을 사용한 bulk.fdb의 재초기화는 65초가 걸렸습니다. 확인란을 사용하지 않으면 노드는 insufficient disk space on replica로 거부합니다.

대화 상자는 1GB의 최소 기준만 부족할 때 숫자를 표시하지 않을 수 있습니다. 2026-11-17 실행에서(여유 1.1GB, 데이터베이스 167MB) 대화 상자는 추정치를 표시하지 않았고, 확인란 없이 한 재초기화는 3초 만에 실패했습니다. 데이터베이스 행과 Commands 페이지에 이유가 표시되었습니다: insufficient disk space on replica: need 184125850 bytes (105% of the database) + 1073741824 bytes free_space_floor_gb; free 1152950272 … Removing the old replica copy would free 175357952 bytes: ask again with remove_old_replica. 확인란을 사용한 같은 재초기화는 9초가 걸렸습니다.

확인란의 위험. 복사가 진행되는 동안 이 데이터베이스의 복제본이 없습니다. 재초기화가 실패하면 페어는 NEEDS_REINIT 상태가 되고, 복제본에는 replica_removed_for_reinit(warn) 경고가 표시되며, 재시도는 새로운 전체 재초기화입니다. 자동 재초기화는 RCM 키 auto_reinit.remove_old_replica_when_short가 켜져 있을 때만 이전 복사본을 삭제합니다(기본값은 꺼짐).

9단계. 검증

복제본 행의 Verify는 마스터와 복제본의 추적 테이블 COUNT(*)를 비교합니다. 행 자체는 비교하지 않습니다. “Table list source” 줄은 목록을 나타냅니다: 데이터베이스 자체 목록, 노드의 목록, 발행 테이블 또는 RDB$FIELDS. 행 수에는 자릿수 구분이 있습니다.

부하 상태에서는 복제본이 몇 초 뒤처지며, Verify는 쓰기가 진행 중인 테이블에 대해 “Not ok"를 표시합니다:

Verify under load
Verify under load

쓰기가 없으면 수가 일치합니다:

Verify without load
Verify without load

어느 데이터베이스에도 없는 테이블은 “not in the database"입니다. 이는 불일치가 아닙니다. 한쪽에만 있는 테이블은 “no table"입니다. 이는 불일치입니다.

더 안전한 확인은 쓰기가 멈춘 뒤 양쪽의 모든 테이블 행 수를 비교하는 것입니다 (스크립트는 hqbird2027-linux-cluster-runbook.md에 있습니다). 실행에서 11개 테이블이 모두 일치했습니다(employee.fdb: 10개, bulk.fdb: 1개, 2,800,000행).

주기적 확인(Data check)은 기본적으로 꺼져 있습니다. Turn on for all nodes를 클릭하고 확인하십시오. 각 노드가 행 수를 세고, 마스터가 수를 비교합니다. 재시작은 필요하지 않습니다. RCM은 “Saved and in force now: the node needs no restart.“를 표시합니다. 첫 확인은 한 간격 뒤에 실행됩니다(기본값 2시간).

Periodic check
Periodic check

다음에 확인할 사항

  • Overview: 노드, 상태, 데이터베이스 루트, 디스크 공간.

    Overview
    Overview
  • Alerts: 노드와 데이터베이스의 문제. 실행에는 두 개의 경고가 있었고 둘 다 확인 처리할 수 있습니다: smooth 재초기화 후의 replication_conflict_resolved(7단계)와 마스터의 parse_no_observations ("/opt/firebird/replication.log에서 파싱된 이벤트 없음”). 마스터의 Firebird는 replication.log에 오류만 기록하므로 빈 로그는 정상입니다 (보고서의 발견 사항 G-06).

    Alerts
    Alerts

    RCM 2027.5.12 이상(킷 2027.2.33)은 심각도 warn 이상의 경고를 자체 Telegram 봇, 웹훅 또는 이메일로 보낼 수 있습니다. 채널은 /opt/hqbirdrcm/rcm.json 파일의 notify.channels 키에 설정하고 RCM을 재시작합니다(sudo systemctl restart hqbirdrcm). 이 페이지의 Notification channels 블록은 채널을 나열하며, 각 채널에는 Send test 버튼이 있습니다. 채널이 없으면 “No channel is configured: RCM sends its alerts nowhere.“라고 표시됩니다. Telegram 채널:

json
  "notify": { "channels": [ { "name": "ops", "type": "telegram",
      "token_file": "secrets/telegram-ops.token", "chat_id": "-1001234567890" } ] }

2026-11-17 실행에서는 채널 없이 블록을 확인했으며, 메시지는 전송되지 않았습니다.

  • 서비스 (RCM 2027.5.11 이상, 2027.2.31부터의 키트): 서비스의 마스터, 레플리카, 라우터, 그리고 운영 전환(switchover), 장애 조치(failover), 재합류(rejoin)를 다룹니다. 이 가이드에서는 다루지 않습니다: RCM 사용자 가이드를 참고하십시오. 사용하기 전에 RCM과 노드를 동일한 버전으로 업데이트하십시오.

  • 명령: 결과와 함께 표시되는 각 RCM 작업입니다. 시간은 브라우저의 로컬 시간과 해당 시간대입니다(예: 17:59:45 UTC+1). 툴팁에는 UTC 시간이 표시됩니다. 노드 로그는 UTC를 사용합니다.

    Commands
    Commands
  • HQ Monitor: http://<server>:23050/, 사용자 이름 admin, 비밀번호는 /opt/hqbird/conf/access.properties에 있습니다. 서버와 데이터베이스를 표시합니다. 에이전트 3.1.0 이상이 포함된 키트에서 HQ Monitor에는 Clusters 페이지가 있습니다. 마스터(RCM 호스트)에서는 에이전트를 통해 클러스터를 표시하며, HQ Monitor에는 RCM 설정이 없습니다. 레플리카에서는 RCM의 호스트를 표시하고 해당 콘솔로 연결되는 링크를 제공합니다. HQ Monitor 1.49.0에는 복제 상태와 RCM 링크가 없습니다. 키트 2027.2.33(에이전트 3.4.0)부터 에이전트는 해당 서버의 문제를 사용자의 채널로도 전송합니다: Servers → Notifications.

클러스터 업데이트

HQbird RCM을 먼저 업데이트한 다음 노드를 업데이트하십시오. 키트 2027.2.31부터 HQCenter에 연결되지 않은 서버는 에이전트, HQ Monitor, fbmcp를 스스로 업데이트합니다( hqbird2027-linux-setup-guide.md의 “Updates without HQCenter”); HQCenter에 연결된 서버는 해당 HQCenter에서 업데이트를 받습니다.

클러스터에서 호스트 제거

Command
cd /opt/hqbird/fbagent-fb50
sudo ./fbagent --cluster-leave

에이전트가 중지되고 노드 서비스의 등록이 해제되며, 해당 노드 포트가 닫히고, 클러스터 인증서가 삭제되며 cluster.source가 none으로 설정됩니다. 노드 폴더는 유지됩니다(--remove-data를 사용하면 삭제됩니다). RCM을 실행하는 에이전트는 거부됩니다. RCM이 에이전트를 해지하거나 마지막 멤버를 제거할 때도 에이전트는 스스로 클러스터를 떠납니다. 제거 시에는 항상 클러스터를 떠납니다: 같은 폴더에 재설치하면 자유 상태로 시작합니다. 2026-11-17 실행에서 명령은 Cluster: left <cluster id>를 출력했고, 레플리카 데이터베이스는 해당 폴더에 남아 있었으며, RCM은 1분 후에도 해당 호스트의 노드를 여전히 표시했습니다. 클러스터 서버에서, 그리고 RCM을 실행하는 서버에서도 HQbird를 제거하는 방법: hqbird2027-removal-guide.md, 섹션 4.

일반적인 오류

표시되는 내용 원인 해결 방법
초기화 시 publication_off publication이 꺼져 있거나, 데이터베이스에 키가 있는 테이블이 있음에도 publication에 테이블이 없음 Sync publication and initialize 버튼(6단계)
long_transactions … the archive holds no segment yet 데이터베이스에 쓰기가 진행 중인 상태에서 smooth 방식으로 처음 초기화했으며, 마스터의 아카이브가 비어 있음 “archive: 1 seg"를 기다린 후 Smooth를 다시 시도하거나 Standard를 선택
reinit_pre_publication_transactions publication이 켜지기 전에 시작된 쓰기 트랜잭션이 1분 넘게 열려 있음 해당 트랜잭션을 종료(COMMIT 또는 ROLLBACK)한 후 다시 시도
대화 상자에 “✗ The folder does not exist on …” 아무도 레플리카 폴더를 생성하지 않음 대화 상자의 Create folder 버튼, 또는 레플리카에서 install -d -o firebird -g firebird -m 0770 <folder> 실행
Verify에 “Not ok (desynced)” 데이터베이스에 쓰기가 진행 중이며 레플리카가 몇 초 뒤처져 있음 부하 없이 다시 시도하고 Match 열 확인
쓰기가 없는데도 Verify에 “Not ok (desynced)“가 표시되고 양쪽 모두 “Ok"로 표시됨 publication이 켜지기 전에 애플리케이션 연결이 열려 있어 저널링되지 않음 애플리케이션을 다시 연결한 후 Reinit 실행(6단계, 첫 publication 동기화에 관한 참고 사항)
Link hosts에서 호스트가 “unreachable” 또는 “no agent"로 표시됨 호스트의 페어링 창이 닫혀 있음(기본적으로 꺼져 있거나 24시간이 지남), 또는 서버 간 방화벽이 7450–7459를 차단함 호스트에서 창 열기: HQ Monitor → Clusters → Open the pairing window for 24 hours, 또는 fbagent --cluster-pairing on; 클라우드 방화벽에서 포트 열기
reinit 시 insufficient disk space on replica 이전 레플리카가 끝까지 유지되며 새 파일이 전체 크기를 차지함 레플리카 볼륨의 이전 파일 위에 데이터베이스 크기의 ≥ 105 % + 1 GB를 확보하거나, Remove the old replica if space is short 상자 선택(8단계)
Link hosts 후에도 노드가 나타나지 않음 RCM 미러에 서명된 hqclusternode 릴리스가 없음 Link hosts 페이지의 Releases in the mirror(2단계)