"운영" 태그로 연결된 33개 게시물개의 게시물이 있습니다.

데이터를 디스크에 암호화해서 저장하는 클러스터를 백업 도구가 제대로 다룰 수 있을까요? 결론부터 말하면, pg_tde로 암호화한 PostgreSQL 클러스터를 pgBackRest로 백업하고 복구하는 과정은 거의 대부분 투명하게 작동하지만, 암호화된 데이터를 백업 도구가 해석할 수 없다는 본질적 한계 때문에 몇 가지 검증/압축 옵션은 꺼야 해요.

Data Egret의 Stefan Fercot(스테판 페르코)가 pgBackRest and pg_tde 글에서 이 조합을 직접 검증했습니다. 이 블로그에서 다뤄 온 백업 시리즈의 곁가지로, 백업 도구와 암호화 extension의 궁합을 운영 관점에서 정리해 봐요.

pg_tde가 암호화하는 것​

pg_tde는 Percona가 개발 중인 투명 데이터 암호화(Transparent Data Encryption) extension입니다. 이름 그대로 애플리케이션은 암호화 여부를 신경 쓰지 않고, 디스크에 저장되는 데이터(data at rest)만 암호화합니다. 암호화 대상은 크게 두 가지입니다.

• 테이블 데이터(heap): tde_heap 접근 방식(access method)으로 만든 테이블. 기존 테이블은 ALTER TABLE ... SET ACCESS METHOD tde_heap으로 전환합니다. heap 테이블뿐 아니라 거기 딸린 index, TOAST, sequence까지 암호화됩니다.
• WAL: pg_tde.wal_encrypt GUC를 켜면 WAL 세그먼트도 암호화됩니다. 이 설정은 서버 전역이라 재시작이 필요하고, 켠 시점 이후의 WAL write부터 암호화가 적용됩니다.

다만 모든 게 암호화되지는 않습니다. 시스템 카탈로그와 통계 데이터 같은 메타데이터는 아직 암호화 대상이 아닙니다. 이름 그대로 "데이터" 암호화에 초점이 맞춰져 있습니다.

키 구조는 2계층입니다. 실제 데이터를 암호화하는 internal key는 $PGDATA/pg_tde 아래에 로컬로 저장되고, 이 internal key를 다시 암호화하는 principal key는 외부 KMS에 둡니다. principal key는 데이터베이스당 하나입니다. 검증에서는 KMS로 OpenBao를 Docker로 띄워 썼고, root 자격증명이 아니라 secret/ 경로에만 읽기/쓰기 권한을 준 최소 권한 토큰을 발급해 사용했습니다.

pgBackRest가 암호화된 클러스터를 다루는 흐름​

pgBackRest 입장에서 보면, pg_tde가 이미 암호화해 놓은 데이터 파일과 WAL을 그대로 받아 저장소로 옮깁니다. 백업 도구는 그 안을 들여다보지 않습니다. 암호화는 PostgreSQL 쪽에서 끝나 있고, pgBackRest는 암호화된 바이트 덩어리를 운반하는 역할입니다.

중요한 지점은 복구 이후입니다. pgBackRest가 복구해 놓은 PGDATA는 여전히 암호화된 상태입니다. 이걸 PostgreSQL이 다시 읽으려면 internal key를 풀 principal key가 필요하고, principal key는 외부 KMS에 있습니다. 즉 백업 파일만 들고 있어서는 복구한 클러스터를 기동할 수 없고, KMS 접근이 함께 살아 있어야 합니다.

검증 결과와 주의점​

Fercot는 pgbench로 부하를 주면서 full 백업과 incremental 백업을 뜨고, pgbench_tellers에서 1,000건을 삭제한 뒤 named restore point로 시점 복구(PITR)를 실행해 삭제된 1,000건이 되살아나는 것까지 확인했습니다. WAL 세그먼트와 데이터 파일은 백업 저장소 안에서도 암호화된 채 유지됐고, 복구 과정에서 별도의 복호화 래퍼 없이 named restore point에 깔끔하게 도달했습니다.

다만 암호화 특성 때문에 꺼야 하는 설정들이 있습니다. 정리하면 다음과 같습니다.

표의 항목들은 모두 같은 원인에서 나옵니다. pgBackRest는 암호화된 내용을 들여다볼 수 없으므로, 데이터 내부를 읽어야 성립하는 검증과 최적화가 작동하지 않습니다. 그래서 page checksum 검증과 WAL 헤더 검증을 끄고, 압축도 끄는 편이 낫습니다. 압축을 켜 두면 줄어들지도 않을 데이터를 압축하느라 CPU만 씁니다.

한 가지 더, incremental 백업 크기가 예상보다 컸습니다. block 단위 incremental은 변경된 블록만 골라 담아 용량을 아끼는데, 암호화된 데이터에서는 이 절감 효과가 크게 줄어듭니다.

검증에는 Percona Server for PostgreSQL이 쓰였습니다. pg_tde가 특정 패치에 의존하기 때문에 표준 PostgreSQL이 아닌 Percona 배포판이 필요하고, pgBackRest가 버전을 제대로 인식하도록 pg-version-force로 버전을 강제해야 했습니다.

운영 관점과 백업 시리즈 연결​

백업 도구를 고를 때는 도구 자체의 기능만 보기 쉽지만, 실제 운영에서는 암호화, 복제, 버전 같은 주변 환경과의 궁합이 더 자주 발목을 잡습니다. 이번 검증의 의미는 "pg_tde를 켜도 pgBackRest를 그대로 쓸 수 있다"는 점을 확인했다는 데 있습니다. 암호화 때문에 백업 도구를 새로 고민할 필요는 없고, 검증/압축 옵션 몇 개를 끄는 선에서 정리됩니다.

대신 복구 절차의 무게중심이 옮겨 갑니다. 평소처럼 백업 무결성만 점검하는 데서 그치지 말고, principal key를 가진 KMS까지 포함한 복구 리허설을 정기적으로 돌려야 합니다. 암호화를 도입하는 순간, 백업 전략은 "데이터 백업"에서 "데이터 백업 + 키 관리"로 확장됩니다.

pgBackRest 프로젝트의 최근 상황은 pgBackRest 컨소시엄 부활 글에 정리해 두었어요.

참고​

• pgBackRest and pg_tde — Stefan Fercot (Data Egret)
• Percona pg_tde — Encryption architecture
• pg_tde can now encrypt your WAL on PROD! — Percona Community

Oracle이 20년 넘게 유지해 온 분기 Critical Patch Update(CPU) 체제 위에 매달 발행하는 Critical Security Patch Update(CSPU)를 얹었습니다. 그 첫 릴리스가 2026년 5월 28일에 나왔습니다.

분기 CPU는 그대로 1, 4, 7, 10월에 누적본으로 나옵니다. CSPU는 그 사이 달에 셋째 화요일마다 끼어드는 소규모/고우선 전용 패치입니다. 첫 회인 5월 CSPU만 이 일정의 예외로 28일(목)에 나왔고, 6월부터 셋째 화요일(6월 16일)에 맞춰 나옵니다(Oracle 5월 CSPU advisory). 첫 CSPU는 CVE 35건을 담았고, 그중 하나는 CVSS 10.0이었습니다. Oracle이 분기 리듬을 깨고 빠른 차선을 새로 낸 이유를 Oracle Security Blog의 공지와 DBA 관점에서 정리합니다.

20년간 이어진 분기 CPU​

Oracle의 분기 CPU는 DBA에게 익숙한 행사입니다. 매년 1, 4, 7, 10월 셋째 화요일에, Oracle의 전 제품군에 걸친 보안 수정이 한 묶음으로 떨어집니다. 한 번에 수백 건이 쏟아지는 게 특징입니다. 바로 직전인 2026년 4월 CPU만 해도 450건의 취약점을 한꺼번에 고쳤습니다.

이 모델의 핵심은 누적(cumulative)이라는 점입니다. 가장 최신 CPU 하나에 그 이전의 모든 수정이 포함되므로, DBA는 사실상 최신 CPU 한 개만 적용하면 됩니다. 관리가 단순하다는 장점은 분명합니다.

문제는 주기입니다. 1월에 발표된 취약점을 표준 절차로 막으려면 4월 CPU까지 최대 석 달을 기다려야 합니다. 그 석 달 동안 취약점은 공격자에게 노출된 구간으로 남습니다.

사이를 메우는 월간 CSPU​

CSPU는 이 구간을 줄이는 장치입니다. 분기 CPU를 대체하지 않고 사이를 메웁니다.

• 발행 주기: 분기 CPU가 없는 달의 셋째 화요일 — 2, 3, 5, 6, 8, 9, 11, 12월
• 성격: 전 제품군을 대상으로 하는 게 아니라, 즉시 대응이 필요하다고 Oracle이 판단한 소수 항목만 추린 묶음
• 사전 예고: 각 CSPU 발행 직전 목요일(T-5)에 미리 공지

분기 CPU 4회와 CSPU 8회를 합치면, DBA는 1년에 12번의 예측 가능한 패치 이벤트를 갖게 됩니다(Oracle). 사실상 월 1회 리듬입니다.

분기 CPU vs 월간 CSPU​

둘은 목적이 다릅니다. 나란히 놓으면 역할이 분명해집니다.

여기서 DBA가 놓치면 안 되는 한 가지가 있습니다. CSPU는 비누적이지만, 다음 분기 CPU가 그동안의 CSPU 수정을 모두 빨아들인다는 점입니다. 즉 CSPU를 적용하지 않고 넘어갔더라도 다음 분기 CPU를 적용하면 그 사이 CSPU 수정이 따라옵니다 — 다만 그때까지 노출 구간이 길어질 뿐입니다.

5월 28일, 첫 CSPU의 내용​

첫 CSPU는 새 CVE 35건을 담았습니다(Oracle Security Blog). 분기 CPU의 수백 건과 비교하면 의도적으로 작은 묶음입니다. 제품군별 분포는 다음과 같습니다.

심각도가 가볍지 않습니다. 가장 눈에 띄는 건 ORDS의 CVE-2026-46840으로, CVSS 10.0 만점입니다. 기밀성, 무결성, 가용성이 모두 완전히 무너지는 등급입니다. E-Business Suite에도 CVSS 9.8~9.9급이 여러 건 있었고, Hospitality OPERA 5의 CVE-2026-34311은 9.8이었습니다.

집계 기준도 짚어 둘 필요가 있습니다. 새 CVE는 35건이지만, Communications 제품군에 들어간 서드파티 컴포넌트 CVE까지 합치면 이번 CSPU가 처리한 취약점은 모두 77건입니다(SecurityWeek). 그중 상당수는 인증 없이 원격으로 악용할 수 있었습니다. ORDS 7건, Communications 4건, E-Business Suite/Database Server 각 3건이 인증 없는 원격 공격에 그대로 열려 있었습니다.

묶음이 작다고 가벼운 것은 아닙니다. 오히려 분기까지 기다릴 수 없다고 Oracle이 판단한 항목만 골라 담았기 때문에, 평균 심각도는 분기 CPU보다 높다고 봐야 합니다.

20년 리듬을 깬 배경​

이 블로그가 주목하는 지점이 여기입니다. Oracle이 20년 넘게 지켜 온 분기 리듬을 굳이 깬 배경에는, 취약점이 발견되는 속도 자체가 달라졌다는 인식이 깔려 있습니다.

Oracle Database 업그레이드를 총괄하는 Mike Dietrich(마이크 디트리히)는 이 변화를 AI 기반 위협에 대한 대응으로 명시했습니다. 그는 AI 모델이 이전과 비교가 안 되는 속도로 취약점을 찾아내고 있으며, Oracle 자체도 Anthropic과 OpenAI의 모델을 취약점 탐지에 활용하고 있다고 밝혔습니다. 발견 속도가 빨라지면 노출 구간을 그만큼 줄여야 한다는 게 그의 논리입니다.

이건 지난달 Copy Fail 글에서 다룬 흐름과 정확히 같은 줄기입니다. AI 코드 감사기가 10년 묵은 커널 버그를 한 시간 만에 찾아낸 사건은, 방어자에게 한 가지를 분명히 일러 줬습니다. 오늘 멀쩡해 보이는 코드가 내일도 멀쩡하리라고 가정할 수 없다는 것입니다. 취약점이 더 빨리, 더 많이 드러나는 시대에는 패치 사이클도 그만큼 짧아져야 합니다.

분기에서 월간으로의 전환은 그 압력에 벤더가 내놓은 응답입니다. 발견과 패치 사이의 간격을 구조적으로 좁히려는 시도입니다.

[과거] 분기 모델
  취약점 발견 ───────── 최대 3개월 ─────────▶ CPU 적용
                       (노출 구간)

[현재] 월간 + 분기 모델
  취약점 발견 ─── 최대 1개월 ───▶ CSPU 적용
                  (좁힌 구간)

DBA가 지금 해야 할 일​

패치 이벤트가 연 4회에서 12회로 3배 늘었다는 건, 운영 부담도 그만큼 늘었다는 뜻입니다. 12번을 모두 같은 속도로 따라가면 검증과 변경 관리가 무너집니다. 그래서 차선을 나눠 대응해야 합니다.

1) 패치 차선을 risk로 나눈다​

모든 CSPU를 같은 속도로 처리할 필요는 없습니다. 인터넷에 노출된 ORDS/E-Business Suite처럼 공격 표면이 넓은 자산은 긴급 차선, 내부망 전용 DB는 표준 차선으로 분류합니다. 5월 CSPU의 ORDS CVSS 10.0 같은 항목은 자산 분류와 무관하게 즉시 차선입니다.

2) T-5 목요일 예고에 계획을 건다​

Oracle이 발행 5일 전 목요일에 미리 알려 주므로, 화요일 발행을 기다리지 말고 목요일 예고로 영향 자산을 먼저 추립니다. 발행 당일에 시작하면 이미 늦습니다.

3) 회귀 테스트를 가볍고 결정론적으로 만든다​

월 1회 리듬에서는 매번 광범위한 수동 검증을 붙일 여유가 없습니다. 핵심 쿼리, 배치, 연동 지점만 자동으로 돌려 확인하는 최소 세트를 미리 갖춰 둬야 패치 주기를 따라갈 수 있습니다.

4) 우회책에 기대지 않는다​

Dietrich의 표현을 빌리면, virtual patching처럼 임시방편에 의존하는 건 보안이 아니라 심리적 위안에 가깝습니다. 결국 정식 패치를 빠르게 적용할 수 있는 체계를 만드는 게 유일한 답입니다.

이 변화가 남기는 신호​

이번 변화의 의미는 단순히 "Oracle 패치가 잦아졌다"가 아닙니다. 보안 패치의 기본 단위가 분기에서 월로 바뀌는 흐름이 메이저 DB 벤더에서 시작됐다는 신호입니다.

Microsoft는 오래전부터 매달 둘째 화요일 Patch Tuesday를 돌려 왔습니다. 리눅스 배포판들은 CVE가 뜨면 며칠 안에 안정 커널을 내놓습니다. 분기라는 긴 호흡을 고수하던 Oracle마저 월간 차선을 열었다는 건, AI가 취약점 발견 속도를 끌어올린 환경에서 분기 주기로는 더 이상 버틸 수 없다는 업계의 공통 인식에 합류했다는 뜻입니다.

DBA에게 이 흐름의 결론은 명확합니다. 패치를 분기에 한 번 몰아서 하는 행사가 아니라 상시로 도는 프로세스로 다시 설계해야 합니다. CSPU는 그 전환을 강제하는 첫 신호예요.

정리​

• Oracle이 분기 CPU에 더해 매달 셋째 화요일 CSPU를 발행하기 시작했습니다. 첫 릴리스는 예외적으로 2026년 5월 28일(목)에 나왔습니다.
• CSPU는 CPU를 대체하지 않고 사이 달을 메우는 소규모/고우선 패치입니다. 분기 CPU는 누적, CSPU는 비누적입니다.
• 첫 CSPU는 CVE 35건, ORDS의 CVSS 10.0(CVE-2026-46840)을 포함한 고심각도 항목 중심이었습니다.
• 전환의 배경은 AI가 끌어올린 취약점 발견 속도 — 발견과 패치 사이 노출 구간을 구조적으로 좁히려는 응답입니다.
• DBA는 패치를 분기 행사가 아니라 상시 프로세스로 재설계하고, risk 기준으로 차선을 나눠야 합니다.

참고​

• Oracle Security Blog: Monthly CSPUs Begin May 28, 2026: 전환 공지와 발행 주기
• Oracle Security Blog: May 2026 CSPU Released: 첫 CSPU 발행 공지
• Oracle Critical Security Patch Update Advisory: May 2026: 공식 어드바이저리 (제품군/CVE 상세)
• SecurityWeek: Oracle's First Monthly Patches Resolve 77 Vulnerabilities: 77건 집계와 인증 없는 원격 악용 항목
• Mike Dietrich: Patch your databases against AI-enabled cybersecurity threats: AI 동기와 운영 권고
• Cyberuptive: Oracle CSPU May 2026: What Security Teams Should Do Now: DBA 대응 플레이북
• Oracle CPU/SPU FAQ: 누적 정책 등 패치 프로그램 기본

Big 4를 한눈에​

Christophe Pettus(크리스토프 페투스)가 The Build에서 정리한 PostgreSQL 19 Beta Big 4에는 공통점이 있어요. 넷 다 피처 노트로 끝나지 않고 운영 시나리오를 바꾼다는 점이에요. 신규 syntax 한 줄에 그치지 않고, DBA의 메모리 계산식, 장애 시나리오, 튜닝 기본값을 다시 그리게 만들어요.

업데이트 (2026-06-04): PostgreSQL 19 Beta 1이 공식 릴리스됐습니다. 이 글이 예고한 Big 4는 모두 Beta 1에 그대로 담겼습니다: 64bit MultiXact members(Make multixid members 64-bit), 병렬 autovacuum worker(autovacuum_max_parallel_workers), UPDATE/DELETE FOR PORTION OF, JIT 기본 비활성화입니다. 정식 출시는 9월~10월 예정이며, 그사이 release candidate가 한 차례 이상 나옵니다.

PostgreSQL 19는 9월 정식 출시 예정입니다. 이번 글은 Pettus의 Big 4 큐레이션을 출발점으로 삼아, 거기에 DBA 점검 항목, 메모리 계산식, SQL 예시, 업그레이드 체크리스트를 보탠 글입니다. 네 가지 선정은 Pettus의 시각이고, 운영 점검, 메커니즘 해설, 업그레이드 절차는 기존 PG19 시리즈 5편이 다루지 않은 부분을 채우는 보완/확장입니다.

왜 이 Big 4인가​

PostgreSQL 19의 변경 목록은 CommitFest 5회분의 수백 건입니다. 그중 DBA가 실제로 체감하는 변화는 보통 둘 중 하나입니다.

• 장애 회피: 지금까지 운영 매뉴얼에 "이거 터지면 끝"으로 적혀 있던 시나리오가 사라집니다.
• 튜닝 기본값 변경: 업그레이드 직후 워크로드 성격에 따라 plan 시간, 메모리, 비상 상황이 달라집니다.

Pettus가 꼽은 Big 4는 정확히 그 두 축에 들어갑니다. 새 syntax나 새 알고리즘이라기보다, 기존 운영 매뉴얼을 손보게 만드는 변경들입니다.

1. 64bit MultiXact members가 없앤 긴급 vacuum 시나리오​

무엇이 바뀌었나​

MultiXact 멤버 카운터가 32bit에서 64bit로 확장됐습니다. 4 billion(약 40억) 멤버 공간 고갈 시나리오가 사실상 사라집니다.

DBA가 왜 체감하나​

PostgreSQL에는 DBA 사이에서 "이게 터지면 끝"으로 통하는 시나리오가 몇 개 있습니다. MultiXact wraparound는 거기 한참 머물러 있었습니다.

SELECT ... FOR SHARE, foreign-key check 같은 공유 row lock이 같은 행에 여러 트랜잭션에서 동시에 걸리면, PostgreSQL은 그 잠금 정보를 묶어서 MultiXact라는 별도 구조에 기록합니다. 각 MultiXact는 멤버 슬롯을 소비합니다. 그 멤버 카운터의 자료형이 PostgreSQL 19에서 처음으로 확장됐습니다.

42억은 운영 부하가 큰 워크로드(공유 lock + FK check 누적)에서 실제로 도달할 수 있는 수치입니다. 1844경은 사실상 도달이 불가능한 영역으로 넘어갑니다.

주의: XID/mxid wraparound는 그대로다​

DBA가 흔히 "wraparound"라고 묶어 부르는 경우는 사실 셋입니다. 이번 변경은 그중 하나에 한정됩니다.

PostgreSQL의 오래된 숙제인 XID wraparound와 mxid wraparound는 PostgreSQL 19에서도 살아 있습니다. autovacuum이 주기적으로 freeze를 수행해야 하는 이유가 정확히 이것입니다. 이번 글이 다루는 "해결된 wraparound"는 MultiXact members 카운터 하나뿐임을 분명히 해 둡니다.

64bit XID 확장은 2018년부터 PostgreSQL hackers 메일링 리스트에서 논의돼 왔습니다. Postgres Pro가 PostgreSQL 15 시기에 실험적 패치 시리즈로 동작 확인까지 갔지만, tuple 헤더 크기 증가, 모든 index format 재설계, WAL format 변경 같은 광범위한 ripple effect 때문에 main 브랜치 commit으로 이어지지 않았습니다. PostgreSQL 19에서도 같은 상태입니다. PostgreSQL의 가장 오래된 숙제 중 하나가 한 라운드 더 미뤄졌고, 그 사이 DBA는 autovacuum freeze 튜닝과 pg_visibility/pg_class.relfrozenxid 모니터링을 손에서 놓을 수 없습니다.

운영 영향은 이렇게 정리됩니다.

42억 한계에 도달하면 DBA가 마주하는 그림은 단순했습니다. 새 트랜잭션이 거부되고, 복구 경로는 offline emergency VACUUM 하나. Pettus의 한 줄이 이를 짚습니다.

"When exhausted, the system would refuse new transactions, and the only recovery path was an emergency VACUUM."

이론적으로 wraparound 수학은 2^64에서도 여전히 존재합니다. 다만 같은 워크로드를 우주의 나이만큼 굴려도 도달이 어렵습니다. 32bit 공간 도달 사례는 운영 사고 보고서들에 종종 등장했지만, 64bit는 실무 카탈로그에서 제외할 수 있습니다.

DBA가 할 일​

• 운영 매뉴얼/런북에서 "MultiXact wraparound" 비상 절차 항목을 "PG 19부터는 도달 불가"로 갱신
• 단, PostgreSQL 18 이하 운영 중인 클러스터는 그대로 이 시나리오가 살아 있으니 모니터링 대시보드를 유지

Beta 1에는 이 부분을 보강하는 변경도 함께 들어왔습니다. multixact 활동을 보여 주는 pg_get_multixact_stats() 함수가 추가됐고, xid/multixact wraparound 경고 임계값이 기존 4천만에서 1억 건 남았을 때로 올라갔습니다(클라이언트와 서버 로그 양쪽에 경고). 여전히 살아 있는 xid/mxid wraparound를 그만큼 더 일찍 알아챌 수 있습니다.

2. 병렬 autovacuum 인덱스 worker와 메모리 계산식​

무엇이 바뀌었나​

새 GUC autovacuum_max_parallel_workers가 추가됩니다. autovacuum이 단일 테이블의 인덱스 정리를 여러 worker로 병렬 처리합니다. PostgreSQL 13에서 도입된 manual VACUUM의 병렬 인덱스 정리가 autovacuum 경로까지 확장됐습니다.

DBA가 왜 체감하나​

인덱스가 많이 붙은 wide table을 운영해 본 사람은 압니다. autovacuum이 돌면 heap 정리는 빠른데 인덱스 정리 단계에서 한참 멈춰 있습니다. 단일 worker가 인덱스 N개를 순차로 도는 구조였기 때문입니다.

PostgreSQL 19에서는 같은 단계에 worker가 동시에 들어갑니다. wide-and-many-indexes 테이블의 autovacuum 시간이 줄어들고, vacuum 누적 부담이 풀립니다.

-- 새 GUC (값은 예시)
ALTER SYSTEM SET autovacuum_max_parallel_workers = 4;
SELECT pg_reload_conf();

주의: 최악 메모리 식이 달라진다​

같은 변경이 운영 부담을 새로 만드는 지점도 있습니다. 각 병렬 worker는 자기 몫의 maintenance_work_mem을 따로 잡습니다.

autovacuum_max_workers=3, autovacuum_max_parallel_workers=4, maintenance_work_mem=1GB인 환경에서 최악 메모리 사용량은 3 × 4 × 1GB = 12GB가 됩니다. PostgreSQL 18까지의 3GB와 4배 차입니다.

DBA는 PostgreSQL 19 업그레이드 전에 세 가지를 확인합니다.

1. maintenance_work_mem 현재 값
2. autovacuum_max_workers 현재 값
3. 위 두 값에 autovacuum_max_parallel_workers를 곱한 값이 시스템 메모리에 맞는가

maintenance_work_mem을 1GB 이상으로 키워 놓은 운영 환경(분석 워크로드/큰 인덱스 재정렬 빈도가 잦은 곳)은 특히 다시 계산해야 합니다.

"명백한 이득"이 보이는 경우는 한정적입니다. serial 인덱스 정리가 vacuum의 병목이던 wide table에서 가장 큰 폭으로 줄어듭니다.

DBA가 할 일​

• 업그레이드 전 메모리 식 재계산. RAM이 빠듯하면 autovacuum_max_parallel_workers를 기본보다 낮춰 시작
• wide table/인덱스 다수 테이블에서 autovacuum 지속 시간 모니터링 (pg_stat_progress_vacuum)
• 한꺼번에 너무 많은 worker가 깨어나 I/O 포화되지 않도록 autovacuum_vacuum_cost_limit 검토

3. UPDATE ... FOR PORTION OF, SQL:2011 시간 범위가 PostgreSQL로​

무엇이 바뀌었나​

시간 범위(period) 컬럼을 가진 테이블에서 부분 범위만 UPDATE 또는 DELETE할 수 있게 됐습니다. SQL:2011 표준 syntax입니다.

-- 가격 이력 테이블 (daterange 컬럼 사용)
CREATE TABLE price_history (
    product_id int,
    price numeric,
    valid_period daterange
);

-- 2026-06-01 ~ 2026-06-15 구간만 가격 변경
UPDATE price_history
FOR PORTION OF valid_period
FROM DATE '2026-06-01' TO DATE '2026-06-15'
SET price = price * 0.9
WHERE product_id = 42;

이전에는 DBA가 직접 row를 자르고 새 row를 끼워 넣는 SQL을 손으로 썼습니다. PostgreSQL 19부터는 한 문장으로 끝납니다. 건드리지 않은 범위의 row는 자동으로 보존됩니다.

DBA가 왜 체감하나​

가격 이력, 직원 직책 이력, 권한 이력, 보험료 이력처럼 시간 범위 컬럼을 두는 모델은 흔합니다. 매번 손으로 자르는 SQL을 짜는 대신 syntax 한 줄로 정리되는 경우가 늘어납니다.

다만 새 운영 사각지대도 함께 생깁니다.

주의: row trigger/cascading FK​

Pettus가 직접 짚습니다.

"a FOR PORTION OF update can fire row triggers on rows that did not exist when the statement started."

(FOR PORTION OF UPDATE는 문이 시작될 때 존재하지 않던 row에 대해서도 row trigger를 발화시킬 수 있다.)

내부적으로 UPDATE ... FOR PORTION OF는 원본 row에 UPDATE를 적용해 범위를 대상 구간으로 좁히고, 대상 밖에 남는 구간은 새 보존 row(최대 두 개)로 INSERT합니다. 그 결과 UPDATE 트리거가 원본 row에, INSERT 트리거가 새 보존 row마다 발화합니다. 기능 추가 커밋의 트리거 문서는 BEFORE UPDATE, BEFORE INSERT, AFTER INSERT, AFTER UPDATE 순서로 설명합니다.

cascading foreign-key 동작은 한 단계 더 복잡해집니다. parent 행의 시간 범위가 잘리면 child의 FK 동작이 어떻게 따라가는지 production에서 테스트하지 않고 올리면 사고 가능성이 큽니다. parent의 부분 UPDATE가 child를 DELETE해야 하는가, CASCADE해야 하는가, RESTRICT해야 하는가. 이런 운영 정책 결정이 SQL 한 줄 안에 묻혀 들어갑니다.

DBA가 할 일​

• FOR PORTION OF를 production에 올리기 전에 row trigger, FK, audit trigger 동작을 staging에서 전부 확인
• 트리거가 row 단위로 카운트를 세는 코드(예: audit row 개수 검증)는 PostgreSQL 19에서 결과가 다를 수 있으니 재검토

4. jit = off 기본값, PostgreSQL 12 이후 처음의 방향 전환​

무엇이 바뀌었나​

Just-in-time compilation 기본값이 off로 바뀝니다. PostgreSQL 12에서 jit = on이 기본값으로 들어온 이후 처음 있는 방향 전환입니다.

DBA가 왜 체감하나​

이 변경은 워크로드 성격에 따라 정반대 결과를 만듭니다.

Pettus는 OLAP 회귀의 크기를 한 줄로 묘사합니다.

"a six-minute report now takes nineteen."

(6분짜리 리포트가 19분 걸리게 된다.)

3배 회귀 사례를 예고하는 대목입니다. OLAP 클러스터를 PostgreSQL 19로 올리면서 jit = on을 명시 설정하지 않으면, 출시 직후 가장 먼저 받는 분기 보고서가 평소보다 한참 늦게 도착합니다.

DBA가 할 일​

OLTP 클러스터는 그대로 두면 plan 효율이 자연스럽게 개선되므로 별도 설정이 필요 없습니다. OLAP/분석 클러스터는 업그레이드 직후 ALTER SYSTEM SET jit = on;을 실행하거나, 분석 사용자에게 ALTER ROLE ... SET jit = on;으로 user-level 설정을 지정합니다. 혼합 워크로드는 pgBouncer 등의 connection pool에서 분석 트래픽을 분리한 뒤 그쪽에만 jit = on을 적용합니다.

왜 방향이 바뀌었는가​

PostgreSQL 12에서 JIT를 기본 활성화한 동기는 "분석 쿼리에서 측정 가능한 가속이 있다"였습니다. 하지만 운영 통계가 쌓이면서, OLTP가 절대 다수인 PostgreSQL 운영 현실에서 plan 시간 오버헤드 손실이 컴파일 가속 이득을 자주 초과한다는 점이 드러났습니다. 6년 만에 측정에 근거해 기본값을 되돌린 것입니다.

PostgreSQL 19 업그레이드 체크리스트 (이번 Big 4)​

업그레이드 전 다음을 점검합니다.

업그레이드 직후에는 다음을 즉시 확인합니다.

-- 1. autovacuum 동작 확인
SELECT * FROM pg_stat_progress_vacuum;

-- 2. JIT 설정 확인 (OLAP면 명시 on)
SHOW jit;

-- 3. 새 GUC 확인
SHOW autovacuum_max_parallel_workers;

정리​

앞의 표에서 정리했듯 64bit MultiXact members는 최악 wraparound 시나리오를 제거하지만 PG 18 이하 클러스터 모니터링은 유지해야 하고, 병렬 autovacuum 인덱스 worker는 wide table autovacuum 시간을 단축하지만 최악 메모리 사용량 식이 달라집니다. UPDATE/DELETE FOR PORTION OF는 시간 범위 SQL을 한 줄로 정리하는 대신 row trigger/cascading FK 동작을 재검증해야 하고, 기본 jit = off는 OLTP plan 시간을 단축하지만 OLAP는 명시 활성화 안 하면 회귀합니다.

PostgreSQL 19는 화려한 신기능보다 운영 매뉴얼을 다시 쓰게 만드는 쪽에 가까운 릴리스예요. DBA 입장에서 이번 Big 4는 9월 정식 출시 전에 staging에서 한 번 돌려 보고, 메모리 식, 튜닝 기본값, 운영 매뉴얼 세 가지를 같이 갱신해야 해요.

기존 PostgreSQL 19 새 기능 총정리와 PostgreSQL 19 시리즈 4편이 "어떤 기능이 들어오는가"를 봤다면, 이번 글은 "어떤 운영이 달라지는가"를 봅니다. 두 글을 같이 두면 PostgreSQL 19를 올리기 전 점검할 항목이 한곳에 모입니다.

참고​

• PostgreSQL News — PostgreSQL 19 Beta 1 Released! (2026-06-04)
• PostgreSQL Docs — Release 19
• The Build — PostgreSQL 19 Beta: The Four Features You'll Actually Feel
• PostgreSQL 19 Open Items (PostgreSQL Wiki)
• JIT Compilation (PostgreSQL Docs)
• autovacuum (PostgreSQL Docs)
• PostgreSQL 19 새 기능 총정리 (본 블로그)
• PostgreSQL 19 EXPLAIN ANALYZE RDTSC (본 블로그), 파티션 MERGE/SPLIT, SQL/PGQ, wal_level 동적화

PostgreSQL 19에서 wal_level이 의미를 바꿨어요: 더 이상 "이 서버가 항상 쓰는 WAL 레벨"이 아니라 하한값이며, 실제 effective level은 그 위에서 slot 상태에 따라 자동으로 움직여요. logical replication slot이 하나 생기면 effective level이 logical로 올라가고, 마지막 slot이 사라지면 다음 checkpoint에서 내려가요.

이 글에서는 The Build의 Christophe Pettus(크리스토프 페투스)가 다룬 "The wal_level You Set Is Not the wal_level You Get"을 한국어로 풀고, cascading standby와 archived WAL에서 운영자가 한 번은 부딪힐 자리들을 함께 살펴봅니다.

보험성 wal_level=logical 의 비용​

기존 PostgreSQL에서 wal_level은 minimal, replica, logical 셋 중 하나로 고정돼 있었습니다. 변경하려면 서버를 재시작해야 했습니다.

운영 패턴이 자연스럽게 굳어졌습니다. 지금 당장 logical replication을 쓰지 않더라도, 나중에 쓸 가능성이 조금이라도 있으면 일단 logical로 잡아둡니다. 그래야 그날 새벽에 슬롯 하나 만들면서 재시작을 잡을 일이 없습니다. "혹시 모르니까" 라는 안전망입니다.

이 안전망에는 비용이 붙습니다.

• wal_level = logical은 모든 변경에 대해 추가 메타데이터를 WAL에 적습니다. row의 이전 이미지, replica identity 정보, 다중행 변경의 stream 표식 등입니다.
• 실제로 logical replication slot이 단 하나도 없어도 적힙니다. "지금 안 쓰는데 적어두는 값"이 분 단위로 디스크에 흐릅니다.
• 운영 환경에 따라 다르지만, replica 대비 WAL 볼륨이 10~30% 더 늘어나는 케이스가 흔히 보고됩니다.
• WAL 볼륨이 늘면 archive 비용, streaming replication 대역폭, PITR 복구 시간이 같이 늘어납니다.

"The right thing has corners." — Christophe Pettus, The Build

PostgreSQL 19는 이 안전망의 비용을 덜기 위해 wal_level을 "고정 레벨"에서 "최소 보장"으로 바꿨습니다.

PG19의 configured wal_level과 effective wal_level​

PostgreSQL 19에서 서버는 두 개의 WAL level을 가집니다.

configured wal_level은 postgresql.conf에 적힌 값입니다. 여전히 재시작 파라미터이며, "이 서버가 어떤 경우에도 떨어지지 않을 하한값"을 뜻합니다. effective wal_level은 서버가 실제로 지금 WAL에 쓰는 레벨이며, configured 값보다 위로 올라갈 수 있습니다.

규칙은 단순합니다.

즉, configured를 replica로 잡아두고도 logical replication slot을 만드는 순간 서버가 알아서 logical로 올라갑니다. 마지막 slot이 사라지면 다음 checkpoint에서 다시 내려갑니다.

상태 전이도​

중요한 지점은 두 군데입니다 — logical 진입 시점은 forced checkpoint 직후이고, 다시 내려가는 시점은 그다음 일반 checkpoint입니다. 두 시점은 비대칭입니다.

동작 단계​

올라갈 때와 내려갈 때를 따로 봅니다.

올라갈 때: logical로의 전이

1. 운영자(또는 CREATE SUBSCRIPTION)가 첫 logical replication slot 생성을 요청합니다.
2. 서버는 effective level이 logical 미만이면 즉시 forced checkpoint를 돕니다.
3. 이 checkpoint 직후의 LSN을 "guaranteed LSN"으로 기록하고, slot은 그 지점부터 시작합니다.
4. 그 LSN 이후의 WAL은 logical 레벨 메타데이터를 함께 적기 시작합니다.

내려갈 때: replica로의 하강

1. 마지막 logical slot이 사라집니다.
2. 서버는 다음 일반 checkpoint까지 그대로 logical을 유지합니다. 즉시 내리지 않습니다.
3. 그 checkpoint가 돌고 나면 effective level이 configured 값으로 복귀합니다.
4. 이후 WAL은 다시 replica 메타데이터로 가벼워집니다.

이 비대칭은 의도된 설계입니다. 올라갈 때는 slot이 막 만들어진 WAL을 읽지 못하면 안 되므로 checkpoint를 즉시 실행합니다. 내려갈 때는 별도 checkpoint를 잡아 운영 영향을 만들 이유가 없습니다.

운영 영향​

가장 큰 효과는 WAL 볼륨 절감입니다.

• "혹시 모르니까 logical"로 잡아둔 클러스터는, configured를 replica로 내리고 PG19로 올리면 그대로 WAL이 줄어듭니다. 실제로 logical을 쓸 일이 생기면 그 순간 자동으로 올라가니 운영 부담은 늘지 않습니다.
• archive 비용, streaming replication 대역폭, PITR 복구 시간이 모두 따라 줄어듭니다.
• 클라우드 관리형 PostgreSQL에서는 archive 저장 비용이 매월 청구되는 항목이라 체감이 큽니다.

부차 효과는 logical replication을 사용 중인 동안에만 그 비용을 낸다는 점입니다. 일회성 마이그레이션을 위해 logical을 켰다가 작업을 마치면 비용이 자동으로 사라집니다.

함정과 주의사항​

네 가지를 짚습니다.

첫째, standby의 logical slot입니다. standby는 primary가 만든 WAL을 재생하므로, standby에 만든 logical slot은 primary의 effective level에 기대어 동작합니다. PostgreSQL 19 문서는 configured wal_level이 replica일 때 primary의 마지막 logical slot을 제거하거나 무효화하면 primary의 logical decoding이 꺼지고, 그 결과 standby의 logical slot이 무효화된다고 경고합니다. 무효화는 standby가 WAL 스트림에서 이 변화를 감지하는 즉시 일어납니다. Pettus의 원문은 standby의 effective level이 primary의 slot 상태와 독립적이라고 설명하지만, 이 부분은 공식 문서의 경고를 기준으로 봐야 합니다. standby에서 logical slot을 운영한다면 primary의 마지막 slot을 정리하기 전에 이 영향을 먼저 확인해야 합니다.

둘째, archive에 mixed-level WAL이 섞입니다. 같은 archive 디렉토리에 replica 시기의 WAL과 logical 시기의 WAL이 함께 쌓입니다. archive 자체가 깨지는 것은 아니지만, "이 archive는 통째로 logical이다" 같은 가정을 두고 작성한 PITR script가 있다면 다시 봐야 합니다.

셋째, prepared transaction입니다. 2-phase commit 자체의 동작은 변하지 않습니다. 다만 prepared transaction이 많은 환경에서는 logical 전이 시점의 forced checkpoint가 의외로 오래 걸릴 수 있습니다. 테스트 환경에서 한 번은 의도적으로 재현해 보고 timeout 설정을 검토하는 편이 좋습니다.

넷째, 첫 slot 생성 시 checkpoint 대기입니다. 새 subscription이 publisher에 logical slot을 만들면 그 호출이 forced checkpoint를 기다립니다. 평소 checkpoint 부담이 큰 시스템에서는 수십 초가 걸릴 수도 있습니다. 자동화 script가 CREATE SUBSCRIPTION 호출에 짧은 timeout을 걸어뒀다면 PG19 업그레이드 직후 한 번 흔들릴 가능성이 있습니다.

PITR / archive script 점검 포인트​

PostgreSQL 19로 올라가기 전에 한 번씩 확인할 자리들입니다.

archive level과 관련해서는 script가 "이 archive는 logical 레벨"임을 전제로 메타데이터를 파싱하지 않는지 확인합니다. slot 생성 timeout은 자동화 도구의 CREATE SUBSCRIPTION / pg_create_logical_replication_slot 호출에 30초 미만으로 설정되어 있지 않은지 살펴봅니다.

WAL 볼륨 모니터링에서는 PG19로 올린 직후 WAL 생성률이 줄어드는 변화를 정상으로 인식하는지 확인합니다. 감소를 장애로 판단해 알람을 보내지 않도록 해야 합니다. cascading 구성에서는 어느 standby에 logical slot이 있는지, primary의 effective level이 내려갈 때 그 slot이 어떤 영향을 받는지 그림으로 한 번 정리해 두는 편이 좋습니다.

"혹시 모르니까"라는 비용​

logical replication을 본격적으로 쓰기 시작한 계기는 zero-downtime upgrade와 CDC 파이프라인입니다. 한 번 켜놓으면 끝나는 것이 아니라 "혹시 다음 마이그레이션 때 또 쓸지 모르니까" wal_level = logical 그대로 두는 패턴이 굳어졌습니다. 그 사이 WAL 볼륨이 10~30% 더 흐르고, archive 비용과 streaming replication 대역폭이 같이 늘어납니다. 평소에는 의식하지 못하지만 PITR 복구 시간을 재 보면 한 번씩 드러납니다. PostgreSQL 19의 동적 wal_level은 이 "보험 비용"을 시점성 비용으로 바꿉니다. 일회성 마이그레이션이 끝나면 slot만 정리해도 effective level이 자동으로 내려가고 WAL이 가벼워집니다. 운영자가 wal_level을 내릴지 말지 회의에 올릴 일이 없어진다는 점이 PG19가 일상에 주는 가장 큰 차이입니다.

정리​

PostgreSQL 19는 운영자가 "혹시 모르니까"라는 이유로 영구히 짊어졌던 비용을 시점성 비용으로 바꿔, logical replication이 필요한 그 순간에만 그 비용을 내게 해요. 기본 동작이 더 똑똑해진 변화지만, standby의 logical slot과 archive처럼 effective level 변화의 영향을 받는 곳에서는 모서리가 한 번씩 보여요.

참고 자료​

• The wal_level You Set Is Not the wal_level You Get: The Build
• PostgreSQL 19 Release Notes
• WAL Configuration: PostgreSQL Documentation
• Logical Replication: PostgreSQL Documentation
• PostgreSQL 19 새 기능 총정리: 이 블로그
• pgBackRest의 종료, 그리고 Barman/CNPG로 이어지는 길: 이 블로그
• PostgreSQL 18의 autovacuum_worker_slots: 이 블로그
• Barman 시작하기, 5개 명령어로 첫 백업과 PITR 복구까지: 이 블로그

PostgreSQL 18에서 autovacuum_max_workers가 드디어 SIGHUP로 받아지는 파라미터가 됐어요. 정확히는 한 파라미터가 둘로 쪼개졌어요 — 시작 시 한 번 예약하는 autovacuum_worker_slots(재시작 필요)와 그 범위 안에서 자유롭게 움직이는 autovacuum_max_workers(reload만으로 적용)예요. 운영자가 vacuum 부하를 보다가 worker 수를 늘리려고 maintenance window를 잡아야 했던 시대가 끝났어요.

이 글은 The Build의 Christophe Pettus(크리스토프 페투스)가 "All Your GUCs in a Row" 시리즈에서 다룬 autovacuum_worker_slots 편을 한국어로 풀고, 함정 한두 가지를 더 짚습니다.

왜 max_workers는 재시작 파라미터였나​

PostgreSQL의 autovacuum launcher는 postmaster가 띄우는 백그라운드 프로세스입니다. launcher가 깨운 worker는 별도 프로세스로 동작하는데, 이 worker들이 자리 잡을 shared memory 구조는 postmaster가 시작될 때 한 번에 예약됩니다. autovacuum_max_workers가 그 크기를 결정했고, 따라서 변경하려면 재시작이 필요했습니다.

이 설정이 운영에서 만든 압박은 두 가지입니다.

첫째, 초기 과다 provisioning. "혹시 모르니 worker 16개 정도 확보해두자"는 식의 보수적 설정이 일반적이었습니다. 평소엔 절반도 안 쓰면서 shared memory를 점유합니다.

둘째, 워크로드 변동 대응 실패. 새 큰 테이블 N개를 한꺼번에 적재하는 야간 배치를 추가하면 vacuum 부담이 갑자기 커집니다. worker를 5개에서 10개로 늘리고 싶어도 그건 다음 maintenance window에서나 가능했습니다. 그동안 dead tuple은 쌓이고, bloat는 자라고, query latency는 흔들립니다.

"The cost of being wrong is a SIGHUP, not an outage." — Christophe Pettus, The Build

PostgreSQL 18은 이 비용을 SIGHUP 한 번으로 줄였습니다.

PG18의 worker_slots와 max_workers 분리​

원래 하나였던 GUC가 둘로 쪼개집니다.

• autovacuum_worker_slots: postmaster가 시작할 때 예약할 shared memory worker slot의 개수이며 재시작 파라미터입니다.
• autovacuum_max_workers: 위 slot 범위 안에서 실제로 동시에 깨어 있을 수 있는 worker의 상한이며 SIGHUP로 받아집니다.

쉽게 말하면 worker_slots는 주차장 크기, max_workers는 지금 동시에 받을 차의 수입니다. 주차장은 미리 지어둬야 하지만, 진입 제한은 그때그때 바꾸면 됩니다.

Before / After​

기본값이 worker_slots = 16으로 잡혀 있는 점에 주목할 만합니다. "어차피 사후에 늘리지 못 하니 처음부터 넉넉히 잡아두자"는 의도된 권장입니다.

구조도​

worker_slots는 부팅 때 한 번 결정되고, max_workers는 SIGHUP로 그때그때 위아래로 움직입니다.

동작 메커니즘​

세 가지를 짚어두면 충분합니다.

1. slot 예약은 postmaster 시작 시 한 번: worker_slots = 16이면 shared memory에 16개의 worker 자리가 잡힙니다. 이 크기는 실행 중 바꿀 수 없습니다.
2. max_workers > slots는 자동 capping: worker_slots = 16인데 max_workers = 20으로 reload하면 PostgreSQL은 16으로 capping하고 서버 로그에 경고를 남깁니다. 에러가 아니어서 reload는 성공하지만, 의도대로 동작하지 않는다는 신호입니다.
3. max_workers는 SIGHUP로 즉시 반영: pg_reload_conf() 한 번이면 다음 worker 사이클부터 새 상한이 적용됩니다.

maintenance window 없는 운영 튜닝 흐름​

새 흐름은 단순합니다.

설치할 때 worker_slots는 "최악의 상황에서 필요할 worker 수"에 맞춰 넉넉히 잡습니다. 16이면 대부분 충분하며, shared memory 비용은 worker 1개당 수 KB 수준이라 부담이 작습니다.

평상시에는 max_workers를 보수적으로 설정합니다(예: 3~5). vacuum이 늦지 않으면 그대로 유지합니다. 큰 테이블 적재, partition 증가, dead tuple 누적이 보이면 postgresql.conf에서 max_workers를 올리고 pg_reload_conf()를 실행합니다. 다음 vacuum 사이클부터 worker가 늘어납니다. 부하가 진정되면 다시 max_workers를 내리고 reload하며, shared memory는 그대로 두면 됩니다.

이 흐름에서 중요한 변화는 부하 증가에 대응하는 3번째 단계가 SIGHUP라는 점입니다. vacuum 부하를 더 받기 위해 데이터베이스를 내리고 다시 띄울 필요가 없습니다.

함정과 주의사항​

크게 넷입니다.

첫째, worker_slots의 hard ceiling. 설치 시점에 worker_slots를 짜게 잡으면 사후에 그 위로 올릴 수 없습니다. 16이 적당해 보여도, partition 1만 개에 야간 배치까지 도는 환경이라면 32로 잡아두는 편이 낫습니다. shared memory 예약 비용이 vacuum 지연 비용보다 훨씬 쌉니다.

둘째, worker_slots를 거꾸로 줄이고 싶을 때. 재시작이 필요합니다. "지금 max_workers = 5로 줄어들었으니 slot도 8 정도면 충분하지 않을까"는 자연스러운 생각이지만, 그 효과는 다음 재시작 때만 봅니다. 평소에는 그냥 두고, 다른 재시작 사유가 생겼을 때 함께 조정하는 게 실무적입니다.

셋째, parallel autovacuum과의 관계. PostgreSQL 19에서는 autovacuum_max_parallel_workers가 추가됩니다. 한 vacuum이 인덱스 정리를 위해 추가로 끌어쓰는 worker는 별도 카운팅이라, 동시에 도는 worker 수를 셀 때는 둘을 함께 봐야 합니다. 자세한 내용은 같은 저자의 "Parallel Autovacuum: It's Not About The CPU"에 잘 정리돼 있습니다.

넷째, max_workers를 올릴 때의 메모리 곱셈. worker_slots가 차지하는 shared memory는 slot 1개당 대략 5~20KB 수준입니다 — PGPROC 슬롯, PgBackendStatus 엔트리, LWLock 같은 자투리를 합산한 값입니다. worker_slots = 16으로 잡아도 총 수백 KB 안쪽이라 셋업 부담은 거의 없습니다. 하지만 slot이 깨어나서 실제 vacuum을 도는 동안에는 별도 비용이 붙습니다. autovacuum_work_mem(미설정 시 maintenance_work_mem, 기본 64MB)이 worker 프로세스의 private memory로 잡힙니다. max_workers = 16으로 올린 상태에서 16개가 동시에 도는 순간 OS RSS에 약 1GB가 추가된다는 뜻입니다. 정리하면 worker_slots는 넉넉히 키워도 무방하지만, max_workers는 RAM과 maintenance_work_mem의 곱셈을 같이 보고 결정합니다. "주차장은 크게, 동시 진입은 천천히"가 기준입니다.

maintenance window라는 비용​

OLTP 클러스터를 운영해 봤다면 maintenance window의 무게를 압니다. 사용자에게 공지를 띄우고, 야간 새벽 시간대를 잡고, 운영자 두세 명이 대기하는 비용입니다. autovacuum_max_workers 하나 늘리겠다고 그 비용을 다 치르기는 어렵습니다. 그래서 한참을 견딥니다 — dead tuple이 쌓이고, 큰 테이블이 bloat로 1.5배쯤 부풀고, query plan이 흔들리기 시작한 다음에야 다음 정기 점검에 끼워 넣습니다. PostgreSQL 18의 분리는 이 견디는 구간이 사라진다는 뜻입니다. dead tuple 알람이 뜨면 그날 안에 worker를 두세 개 더 풀어 vacuum을 따라잡게 한 뒤, 부하가 가라앉으면 다시 줄여둡니다. 운영자 입장에서는 vacuum 튜닝이 처음으로 "회의 없이 가능한 일"이 됐습니다.

정리​

PostgreSQL 18은 "worker 풀은 사전에 크게, 사용량은 그때그때"라는 평범한 운영 패턴을 vacuum에도 들여왔어요. 작은 변화 같지만 운영 자동화 관점에서는 큰 차이예요. 한밤중 dead tuple 누적 알림에 더 이상 maintenance window를 잡지 않아도 됩니다.

참고 자료​

• All Your GUCs in a Row: autovacuum_worker_slots (The Build)
• Parallel Autovacuum: It's Not About The CPU (The Build)
• Do not change autovacuum age settings (The Build, 2019)
• PostgreSQL 18 Release Notes
• Routine Vacuuming (PostgreSQL Documentation)
• PostgreSQL 18의 비동기 I/O (이 블로그)
• PostgreSQL 19의 wal_level: 동적 floor 값으로

정책 한 줄이 디스크와 PITR을 결정한다​

보존 정책을 잘못 설정하면 두 방향 중 하나로 사고가 납니다. 너무 좁게 설정해서 PITR을 원하는 시점이 이미 사라져 있는 경우이거나, 너무 넓게 설정해서 Barman 서버 디스크가 폭발하는 경우입니다. 둘 다 운영에서 흔히 만나는 시나리오입니다.

이 글에서는 Barman의 두 가지 보존 정책인 REDUNDANCY n과 RECOVERY WINDOW OF n DAYS를 같은 lab에서 차례로 적용하며 어떤 backup이 언제 사라지는가를 직접 확인합니다. 처음 보는 독자도 따라올 수 있게 환경을 짧게 정리합니다.

환경 셋업이 처음이라면 2편을 먼저 보고 오는 게 빠릅니다.

두 정책 한눈에​

Barman은 운영 환경에서 RECOVERY WINDOW OF 4 WEEKS를 기본 권장합니다. 운영자가 "몇 개 보관"보다 "몇 주간 PITR 보장"으로 사고하는 게 자연스럽기 때문입니다.

WAL은 backup 정책에 종속된다​

이 원리를 모르고 보존 정책을 만지면 함정에 빠집니다. wal_retention_policy = main(기본값)일 때, Barman은 살아 있는 가장 오래된 backup의 시작점까지 WAL을 보존합니다.

즉 보존 정책이 backup 5개를 남기라고 하면, 가장 오래된 backup의 시작 LSN부터 현재까지의 WAL이 모두 보관됩니다. backup 1개가 OBSOLETE로 정리되는 순간, 그 backup이 의존하던 WAL도 같이 정리 후보가 됩니다.

이 원리 때문에 보존 정책이 넓으면 가장 오래된 backup부터 현재까지의 WAL이 모두 남아 디스크 사용량이 크게 늘 수 있습니다.

시나리오 A: REDUNDANCY 3​

backup 5개를 떠 둔 상태에서 REDUNDANCY 3을 적용해 봅니다.

/etc/barman.d/pg01.conf:

retention_policy = REDUNDANCY 3

sudo -u barman barman cron      # 정책 적용 트리거
sudo -u barman barman list-backup pg01

기대 출력 (요약):

pg01 20260506T130005 - F - Wed May  6 13:00:35 2026 - Size: 41.5 MiB - WAL Size: 16.0 MiB - VALID
pg01 20260506T120005 - F - Wed May  6 12:00:35 2026 - Size: 41.5 MiB - WAL Size: 16.0 MiB - VALID
pg01 20260506T110005 - F - Wed May  6 11:00:35 2026 - Size: 41.5 MiB - WAL Size: 16.0 MiB - VALID

두 번째 칸의 F는 backup 유형(full)입니다. 줄 끝의 VALID가 보존 정책 평가 결과입니다. 정책 밖으로 밀려난 20260506T100005와 20260506T090005는 목록에 없습니다. retention_policy_mode = auto(기본값)에서는 barman cron이 OBSOLETE로 판정한 backup과 그에 종속된 WAL을 같은 실행 안에서 디스크에서 제거하기 때문입니다. cron을 실행하기 전에 list-backup을 보면 두 backup 줄 끝에 OBSOLETE가 붙어 있습니다.

여기에는 함정이 있습니다. backup 빈도가 시간당이라면 REDUNDANCY 3은 지난 3시간만 PITR이 가능하다는 뜻입니다. 사고가 6시간 전에 발생했다면 이미 늦습니다.

시나리오 B: RECOVERY WINDOW OF 7 DAYS​

같은 5개 backup을 가진 상태에서 정책을 시간 기반으로 바꿉니다.

retention_policy = RECOVERY WINDOW OF 7 DAYS

sudo -u barman barman cron
sudo -u barman barman list-backup pg01

이번에는 지난 7일 동안의 어느 시점으로도 PITR이 가능하도록 backup과 WAL이 함께 보존됩니다. 보존 기간 밖에 있는 backup만 OBSOLETE로 마크됩니다.

이 정책의 강점은 backup 빈도와 무관하게 PITR 보장이 일정하다는 점입니다. 시간당으로 떠도 일주일치, 일일로 떠도 일주일치를 유지하므로 운영자는 몇 개보다 얼마나 오래된 시점까지 보장할지를 정할 수 있습니다.

다만 디스크 사용량은 backup 빈도/크기에 따라 들쭉날쭉합니다. 시간당 backup으로 7일치를 보관하면 168개의 backup이 누적됩니다(reuse_backup = link로 dedup해도 작지 않습니다).

시나리오 C: minimum_redundancy 안전망​

정책이 너무 공격적으로 잡혀 있으면 모든 backup이 사라지는 사고도 가능합니다. 이를 막는 설정이 minimum_redundancy입니다.

retention_policy = RECOVERY WINDOW OF 1 DAY
minimum_redundancy = 2

RECOVERY WINDOW OF 1 DAY만 있으면 어제 backup 한 개만 남는 시점도 가능한데, minimum_redundancy = 2가 최소 2개는 항상 유지하도록 강제합니다. 정책과 안전망이 충돌할 때 안전망이 이깁니다.

기본값은 0, 즉 안전망이 없습니다. 운영 환경에서는 항상 1 이상으로 두는 편이 안전합니다.

시나리오 D: barman keep으로 영구 보존​

특정 backup을 retention 정책에서 영구 제외하려는 경우가 있습니다. 예를 들면 마이그레이션 직전의 안전 base나 분기 마감 시점입니다.

sudo -u barman barman keep pg01 20260506T090005 --target full

--target 옵션:

# 보존 대상 확인
sudo -u barman barman list-backup pg01
# → 'KEEP' 마크가 붙은 backup은 retention 정책에서 자동 제외된다

barman keep --release pg01 <backup_id>로 보호를 해제합니다. 운영 가이드에 "위험한 마이그레이션 직전엔 keep --target full을 걸어둔다"를 정착시키면 한 단계 단단해집니다.

OBSOLETE 판정에서 삭제까지​

list-backup 줄 끝에 붙는 보존 상태는 VALID, OBSOLETE, KEEP:FULL, KEEP:STANDALONE 등입니다. backup 자체의 상태(DONE, FAILED 등)와는 별개로, 보존 정책을 평가할 때마다 계산되는 값입니다. DELETED라는 상태는 따로 없습니다. 삭제된 backup은 목록에서 사라질 뿐입니다.

DONE (VALID)  ──(barman cron 정책 평가)──▶  OBSOLETE  ──(같은 cron 실행)──▶  삭제 (디스크 정리)

barman cron은 매 분 한 번 도는데(/etc/cron.d/barman 기본 설정), retention_policy_mode = auto이면 한 번 실행할 때마다:

1. 보존 정책을 평가해 정책 밖의 backup을 OBSOLETE로 판정
2. OBSOLETE로 판정된 backup을 같은 실행 안에서 삭제
3. 종속된 WAL도 같이 정리

정책을 바꾼 뒤 디스크가 줄어드는 시점은 다음 barman cron 실행입니다. 정책을 바꾸고 cron이 돌기 전에 list-backup을 보면 OBSOLETE 표시만 있고 디스크는 그대로라 헷갈리기 쉽습니다.

수동으로 즉시 삭제하려면:

sudo -u barman barman delete pg01 20260506T090005

상황별 결정 가이드​

정리​

보존 정책의 초점은 몇 개를 남기느냐보다 얼마나 오래 PITR을 보장하느냐에 있습니다. 운영자에게는 개수보다 기간으로 사고하는 편이 대체로 자연스럽습니다.

참고 자료​

• Barman 3.18: Configuration / Retention Policies (공식)
• Barman 3.18: User Guide
• Barman 시리즈 1편: 14년의 발자취
• Barman 시리즈 2편: 5명령어 quickstart
• Barman 시리즈 3편: rsync 모드와 하드링크 dedup
• Barman 시리즈 5편: PITR 워크북

백업이 아니라 복구가 시험이다​

2편 마지막에 이렇게 적었어요. "백업의 가치는 백업이 아니라 복구에서 결정됩니다." 이 글은 그 한 줄을 직접 돌려보는 워크북이에요. Barman의 PITR target 옵션 4가지를 한 lab에서 한 번씩 시도해 봐요.

처음 보는 독자도 따라올 수 있게 환경을 짧게 정리합니다.

pg01은 Barman 서버 라벨이고, demo-pg01은 실제 호스트네임이므로 두 이름은 별개입니다. 환경 셋업이 처음이라면 2편을 먼저 보는 편이 빠릅니다.

참고로 barman recover와 barman restore는 같은 명령입니다. Barman 3.x에서는 restore가 새 권장 이름이지만 recover도 그대로 동작합니다. 이 글은 2편과 톤을 맞춰 recover로 통일했습니다.

시나리오 준비​

지웠다가 살릴 데이터를 만듭니다.

PITR을 그럴듯하게 돌려 보려면 의도적으로 손상된 시점이 필요합니다. 다음 SQL을 demo-pg01에서 미리 실행해 둡니다.

# T0: 기준 데이터
sudo -u postgres psql <<'SQL'
CREATE TABLE notes (
  id   int PRIMARY KEY,
  body text,
  ts   timestamptz default now()
);
INSERT INTO notes(id, body)
  SELECT g, 'note-' || g FROM generate_series(1, 1000) g;
SQL

# T1 (예: 14:30:00): 안전 시점 — 이후로 되감을 라벨 생성 + XID 기록
sudo -u postgres psql <<'SQL'
BEGIN;
SELECT pg_create_restore_point('safe-state');     -- 시나리오 C 용
SELECT pg_current_xact_id();                       -- 시나리오 B 용 — 예: 12345
COMMIT;
SQL

# T2 (예: 14:32:00 이후): 사고 — 테이블 삭제
sudo -u postgres psql -c "DROP TABLE notes;"

이제 notes 테이블이 사라졌습니다. base backup이 T0 이전에 떠 있고 WAL이 계속 수집되고 있다고 가정합니다(2편의 lab 그대로). 이 base backup과 WAL을 가지고 T1 직후 / XID 12345 직후 / 명시 라벨 / base backup 직후 4가지 시점으로 되감아 봅니다.

복원 대상은 빈 디렉토리입니다. 매 시나리오 사이에 비우고 시작합니다.

sudo -u barman rm -rf /var/lib/barman/restore && \
  sudo -u barman mkdir -p /var/lib/barman/restore

시나리오 A: --target-time​

시계로 되감는 방식이 가장 직관적입니다. 사고 직전 시각으로 돌립니다.

sudo -u barman barman recover pg01 latest /var/lib/barman/restore \
  --target-time "2026-05-06 14:32:00"

기대 동작은 14:32:00 시점까지 WAL을 replay한 뒤 멈추는 것입니다. notes 테이블은 살아 있고, DROP TABLE에는 도달하지 않습니다.

타임존은 Barman 서버의 시스템 시간대가 기본입니다. 다른 TZ로 명시하려면 2026-05-06 14:32:00+09 형태로 붙입니다. 운영에서는 항상 명시하는 편이 안전합니다.

"Recovery targets must be a value after the end of the backup." — base backup 종료(End time) 이전 시점으로는 복구할 수 없습니다. 시점이 End time보다 이르면 즉시 실패합니다.

시나리오 B: --target-xid​

트랜잭션 ID로 되감습니다.

시계는 누적된 운영 환경에서 의외로 부정확합니다. Barman 호스트와 PostgreSQL 호스트의 시계가 살짝 어긋나 있거나, 동시에 여러 트랜잭션이 들어올 수 있기 때문입니다. 트랜잭션 ID(XID)가 가장 정확한 좌표입니다.

sudo -u barman barman recover pg01 latest /var/lib/barman/restore \
  --target-xid 12345

XID 12345가 commit된 직후까지 replay하고 멈추는 동작을 기대합니다. T1 시점에 기록해 둔 XID가 사고 직전 마지막 안전 트랜잭션이므로 여기에서 멈추면 notes는 살아 있습니다.

--exclusive 플래그를 같이 주면 그 XID 직전까지만 replay합니다(그 트랜잭션 자체는 제외). 기본값은 그 XID 포함입니다.

시나리오 C: --target-name​

명시한 라벨로 되감습니다.

운영 중 위험한 작업 직전에 라벨을 만들어 두는 패턴입니다.

-- 사고 직전(T1)에 미리 만들어 둔 라벨
SELECT pg_create_restore_point('safe-state');

sudo -u barman barman recover pg01 latest /var/lib/barman/restore \
  --target-name 'safe-state'

safe-state restore point까지 replay하고 멈추는 동작을 기대합니다.

이 옵션의 가치는 언어가 자연스럽다는 점입니다. 시각/XID는 사고 후 재구성해야 하지만 라벨은 팀이 기억할 만한 이름입니다. before-migration-2026q2, pre-DROP-INDEX-experiment 같은 이름을 쓸 수 있습니다. 운영 가이드를 "위험한 ALTER 직전엔 restore point부터 만든다"로 정착시키면 PITR이 한층 평이해집니다.

시나리오 D: --target-immediate​

base backup 직후로 되감습니다.

가장 단순한 옵션입니다. 마지막 base backup이 일관성을 확보하는 그 시점까지만 replay하고 멈춥니다. 즉 base backup 종료 직후의 클러스터 상태로 일어섭니다.

sudo -u barman barman recover pg01 latest /var/lib/barman/restore \
  --target-immediate

"가장 최근 base backup의 그 순간으로 일단 돌려놓고, 이후 사고 영향을 분리해 분석하고 싶다" 같은 forensic 시나리오에서 사용합니다. WAL replay를 최소화해 빠르게 일관성 상태에 도달합니다.

그 외 옵션 빠른 참조​

--target-action이 특히 중요합니다. 지정하지 않으면 paused 상태가 되어, 운영자가 SELECT pg_wal_replay_resume()을 직접 호출할 때까지 새 트랜잭션이 돌지 않습니다. 이걸 모르면 "왜 안 살아나지" 하고 한참 헤매게 됩니다.

backup_id=auto(가장 최근 backup 자동 선택)일 때는 제약이 있습니다. --target-time, --target-lsn, --target-tli만 허용됩니다. --target-xid나 --target-name을 쓰려면 명시적인 backup-id를 지정해야 합니다(barman list-backup pg01로 확인).

시점을 정하는 법​

barman show-backup과 pg_waldump로 좌표를 찾습니다.

PITR의 절반은 어디로 되감을지 정하는 일입니다. 두 명령어가 그 좌표를 줍니다.

sudo -u barman barman show-backup pg01 latest

출력에서 다음 항목을 봅니다.

WAL을 더 세밀하게 보려면 pg_waldump로 commit 레코드를 확인합니다. streaming/에는 수신 중인 .partial 파일만 머물고, 완성된 WAL은 wals/<앞 16자리>/ 아래로 아카이브됩니다. 아래 명령은 Barman 호스트에 PostgreSQL 17 클라이언트 패키지(pg_waldump 포함)가 설치돼 있다는 전제입니다. Barman에 WAL 압축을 설정했다면 파일을 먼저 풀어야 합니다.

sudo -u barman /usr/pgsql-17/bin/pg_waldump \
  /var/lib/barman/pg01/wals/0000000100000000/000000010000000000000004 \
  | grep COMMIT | head

각 줄에 LSN, XID, timestamp가 함께 나오므로, 사고 직전의 어떤 좌표를 사용할지 골라잡기 쉬워집니다.

자주 만나는 함정 5가지​

정리​

PITR은 두 단계로 나뉘어요. 시점을 정하는 일이 반이고 복구하는 일이 반인데, 보통은 시점을 정하는 쪽이 더 어려워요.

참고 자료​

• Barman 3.18: Recovery (공식)
• PostgreSQL 17: Recovery Target Settings
• PostgreSQL 17: pg_create_restore_point
• PostgreSQL 17: pg_waldump
• Barman 시리즈 1편: 14년의 발자취
• Barman 시리즈 2편: 5명령어 quickstart
• Barman 시리즈 3편: rsync 모드와 하드링크 dedup

streaming은 알겠고, rsync는 언제 쓰나​

2편에서 Barman의 streaming-only 모델을 셋업했어요. 이 글에서는 같은 lab을 rsync 모델로 바꾸거나 처음부터 rsync로 셋업하고, 왜 rsync를 골랐는지 정리해 보려고 해요.

처음 보는 독자도 따라올 수 있게 환경을 짧게 정리합니다.

pg01은 Barman 서버 라벨이고, demo-pg01은 실제 호스트네임입니다. 환경 셋업이 처음이라면 2편을 먼저 보고 오는 편이 빠릅니다.

rsync 모델 vs streaming 모델 한눈에​

이 글의 주제는 다섯/여섯 번째 행에 있는 하드링크 dedup과 parallel_jobs입니다. 둘 다 rsync 모델 고유의 강점입니다.

양방향 SSH 셋업​

rsync 모델은 두 방향의 SSH가 필요합니다.

비밀번호 없이 통과해야 cron이 자동으로 돌므로 SSH 키 기반입니다.

첫 번째 방향은 demo-barman01의 barman 사용자에서 설정합니다.

sudo -u barman ssh-keygen -t ed25519 -N "" -f ~barman/.ssh/id_ed25519 \
  -C "barman@demo-barman01"

# 공개키를 demo-pg01의 ~postgres/.ssh/authorized_keys에 등록
sudo -u barman ssh-copy-id postgres@demo-pg01

# 검증 — 비밀번호 없이 통과해야 함
sudo -u barman ssh postgres@demo-pg01 'echo ok'

두 번째 방향은 demo-pg01의 postgres 사용자에서 설정합니다.

sudo -u postgres ssh-keygen -t ed25519 -N "" -f ~postgres/.ssh/id_ed25519 \
  -C "postgres@demo-pg01"
sudo -u postgres ssh-copy-id barman@demo-barman01
sudo -u postgres ssh barman@demo-barman01 'echo ok'

운영 환경에서는 authorized_keys에 from="..." 호스트 제약이나 command="..." 락다운을 거는 편이 안전합니다. 이 글은 lab이라 단순화했습니다.

PostgreSQL 측의 archive_command 활성화​

/var/lib/pgsql/17/data/postgresql.conf 핵심 항목:

listen_addresses = '*'
wal_level = replica
archive_mode = on
archive_command = 'barman-wal-archive -U barman demo-barman01 pg01 %p'

barman-wal-archive는 barman-cli 패키지의 명령이라 demo-pg01에 따로 설치해야 archive_command가 동작합니다.

# demo-pg01에서 실행
sudo dnf install -y barman-cli

내부적으로 SSH로 barman@demo-barman01에 접속해 WAL 파일을 /var/lib/barman/pg01/incoming/에 정확히 전달합니다 — cp나 직접 scp하는 것보다 안전합니다.

pg_hba.conf에는 Barman의 conninfo 접속을 열어 둡니다. replication slot은 rsync 모델에서 필수가 아니지만, barman check가 PostgreSQL 메타데이터를 읽으려면 이 접속이 필요합니다.

host    postgres        barman       demo-barman01        scram-sha-256

PostgreSQL 재시작 후 사용자 생성:

sudo systemctl restart postgresql-17
sudo -u postgres psql <<'SQL'
CREATE USER barman WITH ENCRYPTED PASSWORD 'changeme';
GRANT pg_read_all_settings, pg_read_all_stats TO barman;
GRANT EXECUTE ON FUNCTION pg_backup_start(text, boolean) TO barman;
GRANT EXECUTE ON FUNCTION pg_backup_stop(boolean) TO barman;
GRANT EXECUTE ON FUNCTION pg_switch_wal() TO barman;
GRANT EXECUTE ON FUNCTION pg_create_restore_point(text) TO barman;
SQL

streaming 모델과 달리 REPLICATION 속성/replication slot은 생성하지 않습니다.

Barman 측의 backup_method = rsync 설정​

/etc/barman.d/pg01.conf를 다음과 같이 설정합니다.

[pg01]
description = "Production PostgreSQL primary (rsync mode)"
ssh_command = ssh postgres@demo-pg01
conninfo = host=demo-pg01 user=barman dbname=postgres
backup_method = rsync
parallel_jobs = 2
reuse_backup = link
archiver = on
retention_policy = RECOVERY WINDOW OF 4 WEEKS

핵심 다섯 줄의 의미는 이렇습니다.

streaming 모델의 streaming_conninfo, streaming_archiver, slot_name 키는 모두 사용하지 않습니다.

설정 검증:

sudo -u barman barman check pg01

receive-wal running은 streaming 모델 전용이므로 rsync 모드에서는 항목이 빠지거나 disabled로 나옵니다. 그 외 항목이 모두 OK면 셋업이 끝난 것입니다.

첫 backup + 하드링크 dedup 측정​

# 첫 base backup
sudo -u barman barman backup pg01

기대 출력 (요약):

Starting backup using rsync-over-ssh method for server pg01 ...
Copy done (time: 12 seconds)
Backup size: 41.5 MiB

이번에는 의도적으로 작은 변경만 만든 뒤 두 번째 backup을 수행합니다.

# 데이터 일부 변경 (작은 테이블 하나 추가)
sudo -u postgres psql -c "CREATE TABLE dedup_test AS SELECT g AS id FROM generate_series(1, 1000) g;"

# 두 번째 base backup — reuse_backup = link 가 동작
sudo -u barman barman backup pg01
sudo -u barman barman list-backup pg01

이제 디스크 사용량을 두 가지 방식으로 잽니다.

# 실제 디스크 사용량 (하드링크는 한 번만 카운트)
sudo du -sh /var/lib/barman/pg01/base/
# 예: 42.0 MiB

# 논리 사용량 (-l: 하드링크를 중복 카운트해 backup별로 따로 합산)
sudo du -shl /var/lib/barman/pg01/base/
# 예: 83 MiB

두 측정값의 차이인 41 MiB ≈ 첫 backup 크기가 dedup으로 절약된 디스크 공간입니다. 두 번째 backup은 변경된 파일만 새로 복사되고 나머지는 첫 backup 파일에 hardlink로 연결되므로, backup 횟수가 늘수록 누적 절약 효과가 커집니다.

rsync를 선택하는 기준 4가지​

베어메탈/VM에서 디스크 효율과 병렬 복사가 중요하면 rsync가 잘 맞습니다. 컨테이너/K8s에서 SSH를 피하고 운영을 단순화하려면 streaming이 유리합니다. 둘 다 가능한 환경이라면 운영자의 SSH 키 관리 부담이 적은 streaming이 무난합니다.

streaming과 rsync 사이의 전환​

같은 라벨로 두 모델을 동시에 운영할 수는 없습니다. backup_method는 하나만 지정할 수 있기 때문입니다. 전환 절차는 다음과 같습니다.

# 1단계: 기존 라벨 비활성화
[pg01]
active = false
...

# 2단계: 새 conf 파일로 다른 라벨 만들기 (예: pg01-rsync)
[pg01-rsync]
backup_method = rsync
...

새 라벨에 backup이 안정적으로 들어오는 것이 확인되면, 보통 1주일+ 경과/복구 리허설 1회 이상을 기준으로 기존 라벨을 폐기합니다.

운영 환경에서는 기존 backup을 즉시 버리지 않습니다. 보존 정책에 따라 자연 만료될 때까지 두 라벨을 함께 보관하면 이전 시점 PITR이 필요할 때 안전망이 됩니다.

정리​

streaming은 운영 단순화에 강하고 rsync는 디스크 효율과 병렬화에 강해요. 환경 때문에 한쪽을 골라야 하는 상황이 아니라면 streaming부터 시도해 보는 편이 무난해요.

참고 자료​

• Barman 3.18: Configuration (공식)
• Barman 3.18: User Guide
• PostgreSQL 17: archive_command
• Barman 시리즈 1편: 14년의 발자취
• Barman 시리즈 2편: 5명령어 quickstart
• Barman 시리즈 5편: PITR 워크북

어떻게 Barman인가​

1편이 "왜 Barman인가"였다면, 이 글은 "어떻게 Barman인가"예요. 1편에서 Barman의 14년 궤적과 아키텍처를 정리했어요. 이번에는 같은 자리에서 한 발짝 더 들어가 두 대의 Rocky Linux 머신을 준비하고, streaming-only 모드로 PostgreSQL을 설정한 뒤, 5개 명령어로 첫 백업과 PITR 복구까지 끝내 봅니다.

이번에 다룰 시나리오를 한 화면에 펼치면 다음과 같습니다.

읽으면서 따라 할 수 있도록 모든 명령어와 설정 파일 내용을 그대로 옮겨 둡니다.

사전 준비​

두 호스트로 lab 환경을 구성합니다.

두 호스트가 hostname으로 서로 통신한다고 가정합니다(DNS 또는 /etc/hosts). 단일 머신에서 시험하려면 demo-pg01과 demo-barman01을 모두 localhost로 두고 진행해도 됩니다.

설치​

PGDG 저장소에서 설치합니다.

demo-pg01과 demo-barman01 양쪽에 PGDG 저장소를 등록합니다.

sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo dnf -qy module disable postgresql

demo-pg01에서 PostgreSQL 17 설치/초기화:

sudo dnf install -y postgresql17-server postgresql17-contrib
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
sudo systemctl enable --now postgresql-17

demo-barman01에 Barman 3.18 설치:

sudo dnf install -y barman barman-cli

설치 시 barman 시스템 사용자가 자동 생성되며, 백업 카탈로그 기본 경로는 /var/lib/barman입니다. /etc/cron.d/barman도 함께 깔리므로 별도 systemd timer 설정 없이 cron이 매 분 한 번 barman cron을 돌립니다.

설정 1: PostgreSQL 측 (demo-pg01)​

streaming 백업은 PostgreSQL의 replication 프로토콜 위에서 동작하므로, replication user와 replication slot이 필요합니다.

/var/lib/pgsql/17/data/postgresql.conf 핵심 항목:

listen_addresses = '*'
wal_level = replica
max_wal_senders = 10
max_replication_slots = 10

/var/lib/pgsql/17/data/pg_hba.conf에 Barman 측 접속을 열어 둡니다.

# TYPE  DATABASE        USER         ADDRESS              METHOD
host    replication     barman       demo-barman01        scram-sha-256
host    postgres        barman       demo-barman01        scram-sha-256

PostgreSQL을 재시작한 후 사용자와 슬롯을 생성합니다.

sudo systemctl restart postgresql-17
sudo -u postgres psql <<'SQL'
CREATE USER barman WITH REPLICATION ENCRYPTED PASSWORD 'changeme';
GRANT EXECUTE ON FUNCTION pg_backup_start(text, boolean) TO barman;
GRANT EXECUTE ON FUNCTION pg_backup_stop(boolean) TO barman;
GRANT EXECUTE ON FUNCTION pg_switch_wal() TO barman;
GRANT EXECUTE ON FUNCTION pg_create_restore_point(text) TO barman;
GRANT pg_read_all_settings, pg_read_all_stats TO barman;
SELECT pg_create_physical_replication_slot('barman');
SQL

실제 운영에서는 changeme을 비밀 관리자(Vault, AWS Secrets Manager 등)로 옮기고 .pgpass 또는 환경변수로 분리해야 합니다.

설정 2: Barman 측 (demo-barman01)​

/etc/barman.conf는 default 값 그대로 두는 편이 무난합니다. 서버별 설정만 추가합니다(default 항목 자체는 별도 글에서 다룹니다).

/etc/barman.d/pg01.conf:

[pg01]
description = "Production PG primary"
conninfo = host=demo-pg01 user=barman dbname=postgres
streaming_conninfo = host=demo-pg01 user=barman
backup_method = postgres
streaming_archiver = on
slot_name = barman
create_slot = manual
retention_policy = RECOVERY WINDOW OF 4 WEEKS

[pg01]은 Barman 서버 라벨이자 서버 식별자입니다. CLI(barman backup pg01), 카탈로그 디렉토리(/var/lib/barman/pg01/...), conf 파일명(pg01.conf)에 같은 값을 씁니다. 실제 호스트네임 demo-pg01과는 별개이며, Barman이 부르는 이름과 네트워크가 부르는 이름을 분리한 것입니다.

conninfo = host=demo-pg01 ...에는 Barman이 PostgreSQL에 접속할 때 사용하는 실제 호스트네임을 지정하므로 라벨과 달라도 자연스럽습니다. backup_method = postgres는 pg_basebackup을 통한 streaming 백업을 뜻하고, streaming_archiver = on은 WAL을 pg_receivewal 방식으로 받도록 설정합니다. slot_name = barman은 앞에서 만든 replication slot을 사용합니다. create_slot = manual로 지정한 이유는 슬롯을 SQL로 이미 만들었으므로 Barman이 자동 생성하지 않게 하기 위해서입니다.

비밀번호는 barman 사용자의 ~/.pgpass로 분리합니다.

sudo -u barman tee ~barman/.pgpass > /dev/null <<'EOF'
demo-pg01:5432:*:barman:changeme
EOF
sudo chmod 600 ~barman/.pgpass
sudo chown barman:barman ~barman/.pgpass

5개 명령어 시나리오​

이제부터는 모든 명령어를 barman 사용자로 실행합니다. sudo -i -u barman으로 barman 셸에 들어가거나, 명령어마다 sudo -u barman을 앞에 붙입니다.

1. barman check pg01​

셋업을 검증합니다.

sudo -u barman barman check pg01

기대 출력 (요약):

Server pg01:
        PostgreSQL: OK
        wal_level: OK
        replication slot: OK
        directories: OK
        retention policy settings: OK
        pg_basebackup: OK
        pg_basebackup compatible: OK
        systemid coherence: OK
        pg_receivexlog: OK
        receive-wal running: OK
        archiver errors: OK

한 줄이라도 FAILED가 나오면 그 항목에 셋업 단계의 문제가 있습니다. 가장 자주 보이는 receive-wal running: FAILED는 cron이 아직 한 번도 돌지 않았거나 slot 이름이 어긋났다는 뜻입니다. 한 번 강제로 돌려 두는 편이 빠릅니다.

sudo -u barman barman cron

2. barman backup pg01​

첫 base backup을 실행합니다.

sudo -u barman barman backup pg01

기대 출력 (요약):

Starting backup using postgres method for server pg01 in /var/lib/barman/pg01/base/20260504T143012
Backup start at LSN: 0/3000028
Starting backup copy via pg_basebackup for 20260504T143012
Copy done (time: 12 seconds)
Backup size: 41.5 MiB
Backup end at LSN: 0/4000060
Marking backup as DONE
Backup completed (start time: 2026-05-04 14:30:12, elapsed time: 14 seconds)

/var/lib/barman/pg01/base/<timestamp>/ 아래에 base backup이 쌓입니다. WAL은 /var/lib/barman/pg01/streaming/으로 수신된 뒤 /var/lib/barman/pg01/wals/ 아래에 아카이브됩니다.

3. barman list-backup pg01​

카탈로그를 조회합니다.

sudo -u barman barman list-backup pg01

기대 출력:

pg01 20260504T143012 - F - 2026-05-04 14:30:26 - Size: 41.5 MiB - WAL Size: 16 MiB

F는 full backup입니다. backup-id는 timestamp 기반(20260504T143012)이며, latest 키워드를 별칭으로 쓸 수 있습니다.

상세 보기:

sudo -u barman barman show-backup pg01 latest

Begin time / End time / Begin LSN / End LSN 등 PITR 타깃을 결정할 때 필요한 값이 모두 여기에 있습니다.

4. barman recover​

최신 백업으로 복원합니다.

복원 대상은 빈 디렉토리여야 합니다. PostgreSQL이 새로 기동할 자리를 미리 비워 둡니다.

sudo mkdir -p /var/lib/barman/restore
sudo chown barman:barman /var/lib/barman/restore

sudo -u barman barman recover pg01 latest /var/lib/barman/restore

복원이 끝나면 그 디렉토리 안에 base backup이 풀리고, recovery.signal과 postgresql.auto.conf의 restore_command 항목이 자동 생성됩니다. PostgreSQL을 그 데이터 디렉토리로 띄우면 곧장 기동합니다.

다른 호스트로 직접 복원하려면 --remote-ssh-command "ssh postgres@<host>"를 추가합니다. 이때 barman 사용자에서 그 호스트의 postgres로 SSH 키 기반 접속이 미리 설정되어 있어야 합니다.

5. barman recover --target-time​

특정 시점으로 되감는 PITR을 실행합니다.

sudo -u barman barman recover pg01 latest /var/lib/barman/restore \
  --target-time "2026-05-04 15:00:00"

복원 시점은 base backup 종료(End time) 이후, 가장 마지막에 받은 WAL 이전 사이여야 합니다. 정확한 경계가 헷갈리면 barman show-backup pg01 latest의 Begin time / End time을 기준으로 잡습니다.

다른 PITR 타깃 옵션도 같은 자리에 지정합니다.

일상 운영​

cron 한 줄과 보존 정책을 설정합니다.

설치 시 동봉된 /etc/cron.d/barman이 매 분 barman cron을 실행합니다(WAL 수신과 아카이브 정리 담당). 정기 백업은 별도 cron 한 줄로 잡는 방식이 표준입니다.

# /etc/cron.d/barman-backup — 매일 02:00에 모든 등록 서버 백업
0 2 * * * barman /usr/bin/barman backup all

보존 정책은 서버별 conf 한 줄로 끝납니다.

retention_policy = RECOVERY WINDOW OF 4 WEEKS
# 또는 개수 기반:
# retention_policy = REDUNDANCY 5

RECOVERY WINDOW는 "이 시점부터 N 단위(WEEKS/DAYS) 전까지 PITR이 가능하도록 보장"한다는 의미입니다. 지난 4주 동안 임의 시점으로 되감을 수 있도록 base backup과 WAL을 함께 보존합니다. 정책에서 벗어난 backup은 barman cron이 자동으로 정리합니다.

자주 만나는 에러 빠른 가이드​

barman check는 한 번에 끝내려 들기보다 "FAIL 한 줄씩 잡아 나가는 도구"로 보면 마음이 편합니다. 위 4개를 해결하면 첫 셋업의 90%가 끝납니다.

정리​

백업의 가치는 백업이 아니라 복구에서 결정돼요. 셋업 직후 PITR을 한 번은 반드시 돌려봐요.

참고 자료​

• Barman Manual (docs.pgbarman.org)
• Barman GitHub — EnterpriseDB/barman
• PGDG RPM Repository
• PostgreSQL 17: Continuous Archiving and PITR
• Barman 14년의 발자취 (1편)
• pgBackRest의 종료 (시리즈 모편)
• Barman rsync 모드 (3편)
• CNPG Barman Cloud Plugin (후속 편 후보)

1편의 잔상​

Claude Code Switcher(1편)가 표면의 글이었어요. CCS가 왜 등장했는지, 무엇을 풀고 있는지, 누구에게 언제 맞고 안 맞는지를 다뤘어요. 그 글의 한 단락을 그대로 옮기면 이렇습니다.

CCS는 Claude Code가 환경변수 두 개로 정의되는 도구라는 사실을 그대로 받아들인 도구입니다. 그 두 변수를 프로파일이라는 단위로 정리하고, OAuth 우회와 다중 계정까지 한 명령 표면 위로 올려놓았습니다.

2편은 그 표면 아래를 다룹니다. ~/.ccs/ 한 디렉토리에 무엇이 어떻게 사는지, config.yaml의 어느 키가 무엇을 결정하는지, instance와 shared가 어떻게 갈리는지, 로컬 프록시는 정확히 어떤 변환을 거치는지 살펴봅니다. 1편에서 표 한 줄로만 끝낸 부분을 시스템의 그림으로 풀어 봅니다.

이 글의 모든 디렉토리/키 이름은 사용자 머신의 실제 CCS 설치를 직접 들여다본 결과입니다. 토큰/세션 같은 민감한 값은 보지 않고 구조만 인용합니다.

~/.ccs/ 한 장 지도​

CCS가 머신에 자리 잡으면 홈 디렉토리에 ~/.ccs/ 한 폴더가 생깁니다. 그 안의 트리가 사실상 CCS의 운영 모델 전부인데, 진짜 그림은 심볼릭 링크 체인입니다.

~/.claude/                       ← 사용자의 기존 Claude Code 글로벌 (canonical)
├── settings.json
├── commands/, skills/, agents/, plugins/
└── projects/

~/.ccs/                          ← CCS 영역
├── config.yaml                  ← 메인 설정 (YAML, 11K 정도)
├── .session-secret              ← 세션 비밀 (64B, 절대 공유 금지)
├── .claude/                     ← CCS *번들* (ccs.md, ccs-delegation 스킬 등 자체 주입)
├── cliproxy/bin/                ← CLIProxyAPI 바이너리 (자동 다운로드)
├── cache/, completions/, logs/
│
├── shared/                      ← 사용자 정의 공유 영역
│   ├── settings.json    → ~/.claude/settings.json   (symlink)
│   ├── commands         → ~/.claude/commands         (symlink)
│   ├── skills           → ~/.claude/skills           (symlink)
│   ├── agents           → ~/.claude/agents           (symlink)
│   ├── plugins          → ~/.claude/plugins          (symlink)
│   └── context-groups/default/projects/              (실 디렉토리)
│
└── instances/                   ← per-account 격리 영역
    ├── team/                    ← 회사 Team account
    │   ├── settings.json   → ~/.ccs/shared/settings.json     (symlink)
    │   ├── commands        → ~/.ccs/shared/commands           (symlink)
    │   ├── skills          → ~/.ccs/shared/skills             (symlink)
    │   ├── agents          → ~/.ccs/shared/agents             (symlink)
    │   ├── projects        → ~/.ccs/shared/context-groups/default/projects/  (symlink)
    │   ├── plugins/, .anthropic/, sessions/, session-env/    ← 실 디렉토리
    │   ├── todos/, file-history/, shell-snapshots/, logs/    ← 실
    │   ├── backups/, cache/, debug/, image-cache/, paste-cache/, plans/   ← 실
    │   └── .claude.json, history.jsonl, .session-stats.json,
    │       mcp-needs-auth-cache.json, policy-limits.json, remote-settings.json
    └── enterprise/              ← 회사 Enterprise account (구조 동일)

여기서 눈여겨볼 것은 두 가지입니다. 하나는 2단계 symlink 체인입니다. instances/team/settings.json을 따라가면 ~/.ccs/shared/settings.json으로, 다시 ~/.claude/settings.json으로 이어집니다. 사용자의 기존 Claude Code 글로벌 설정이 모든 인스턴스에 자동 반영된다는 뜻이며, 한 번 만든 슬래시 커맨드, 스킬, MCP가 team과 enterprise 양쪽에서 살아 있는 이유도 여기에 있습니다.

다른 하나는 projects/만 체인이 한 단계라는 점입니다. 대화 히스토리는 instances/team/projects에서 ~/.ccs/shared/context-groups/default/projects/(실 디렉토리)까지만 가고 ~/.claude/projects/까지는 이어지지 않습니다. CCS가 자기 context-group 단위로 대화를 모아 사용자의 평소 Claude Code 대화와 자연히 분리해 두는 것으로, 회사 대화가 개인용 Claude Code에 섞이지 않도록 의도한 끊음입니다.

이 2단계 체인이 이중 구조라고 표현했던 것의 실제 메커니즘이며, 1편의 "공유 vs 분리"가 단일 축이 아니라 어느 단위까지 체인을 잇느냐의 문제였다는 뜻입니다. 5~6절에서 이 단위들을 풀어 봅니다.

config.yaml의 9개 영역​

설정의 거의 전부는 ~/.ccs/config.yaml 한 파일에 모입니다. JSON이 아니라 YAML인 점이 의외인데, 사람이 손으로 읽고 고치기 좋은 쪽을 택한 것으로 보입니다.

최상위 키는 15개이고, 역할이 같은 키를 묶으면 9개 영역으로 나뉩니다. 메타(version, default), 계정(accounts), 프로바이더 프로파일(profiles), OAuth 프록시(cliproxy), 로컬 프록시(proxy), CLIProxy 서버(cliproxy_server), 로그와 환경설정(logging, preferences), 웹 검색(websearch), 외부 도구 통합(copilot부터 global_env까지)입니다.

version:                # 메타
default:                # 기본 프로파일

accounts:               # *instance 단위* 메타
  team:
    context_mode:       # isolated | shared
    context_group:      # shared 일 때 그룹 이름
    continuity_mode:    # 추가 공유 정책
  enterprise:
    ...

profiles:               # 프로바이더 프로파일 (glm, kimi, ollama, ...)

cliproxy:               # OAuth 프록시 백엔드 설정
  backend:
  oauth_accounts:
  providers:
  routing:
    strategy:           # round-robin / fill-first
    session_affinity:
    session_affinity_ttl:

proxy:                  # 로컬 OpenAI-호환 프록시
  profile_ports:        # 프로파일별 포트 매핑
  routing:
    longContextThreshold:

cliproxy_server:        # 원격/로컬 CLIProxy 서버
  remote: { enabled, host, protocol, auth_token }
  fallback: { enabled, auto_start }
  local:   { port, auto_start }

logging:                # 로그 회전·보관
preferences:            # theme, telemetry, auto_update

websearch:              # ★ 8개 fallback 프로바이더
  providers:
    exa, tavily, brave, searxng, duckduckgo, gemini, opencode, grok

# --- 통합 (Claude Code 외부 도구들) ---
copilot:                # GitHub Copilot 라우팅
cursor:                 # Cursor 통합 (ghost_mode 포함)
channels:               # Telegram/Discord/iMessage
thinking:               # opus/sonnet/haiku 별 thinking 기본값
global_env:             # DISABLE_TELEMETRY 등 전역 env 자동 주입

이 9개 영역을 한 번 살펴보면 CCS가 단순 스위처가 아니라 Claude Code 주변의 운영 표면 전체를 흡수해 가고 있다는 인상이 분명해집니다. 12절에서 이 중 안 알려진 부분을 따로 추립니다.

Instance 시스템, symlink와 실 상태의 갈림​

instances/<name>/ 디렉토리는 언뜻 보면 Claude Code의 모든 상태를 담은 통 같지만, ls -la로 열어 보면 절반은 shared/로의 symlink이고 나머지 절반만 인스턴스별 실 상태입니다. 둘을 갈라 두면 멘탈 모델이 명확해집니다.

먼저 모든 인스턴스가 공유하는 symlink 항목입니다.

settings.json의 최상위 키 9개는 체인을 따라가 본 결과 다음과 같습니다. 사용자의 기존 ~/.claude/settings.json 스키마 그대로입니다.

alwaysThinkingEnabled
enabledPlugins
env
extraKnownMarketplaces
hooks
permissions
skipAutoPermissionPrompt
skipDangerousModePermissionPrompt
statusLine

다음은 인스턴스별로 격리된 실 상태입니다.

CCS는 보이지 않게 CLAUDE_CONFIG_DIR 같은 환경변수로 인스턴스 컨텍스트를 끼워 넣습니다.

enterprise 인스턴스는 team보다 가볍게 비어 있는 상태였는데, 활성 사용 중인지 아닌지가 디렉토리 충실도에 그대로 드러납니다. CCS는 인스턴스를 만들 때 symlink와 빈 디렉토리만 만들어 두고, 실제로 사용해야 실 데이터가 채워지는 lazy 모델입니다.

shared/와 context-groups로 1편의 빈칸 메우기​

1편의 "설정/대화는 공유하면서 계정만 분리하고 싶다면" 단락의 진짜 답이 여기 있습니다. CCS는 이 시나리오를 shared/라는 별도 영역과 context_mode/context_group 설정으로 정식 지원합니다.

config.yaml의 accounts: 섹션:

accounts:
  team:
    context_mode: isolated          # 또는 shared
    context_group: default          # shared 일 때만 의미
    continuity_mode: deeper         # 또는 default
  enterprise:
    context_mode: shared
    context_group: default
    continuity_mode: deeper

세 키의 역할:

context_mode: isolated | shared는 인스턴스가 자기 디렉토리에만 사는지, 같은 그룹의 다른 인스턴스와 공유하는지를 정합니다. context_group은 shared일 때 쓸 그룹 이름이며, ~/.ccs/shared/context-groups/<group>/가 그 그룹의 공유 데이터 자리입니다. continuity_mode: deeper는 공유의 깊이를 정하며, deeper는 더 많은 디렉토리를 공유 대상에 포함합니다.

이 셋을 조합해 보면 1편에서 "공유 vs 분리"라고 단순화한 구도가 사실 세 축의 조합임이 드러납니다.

무엇이 공유 가능하고 무엇이 항상 격리되는가​

README는 이 부분을 강조하지 않지만, 저장소의 docs/session-sharing-technical-analysis.md에는 이렇게 적혀 있습니다.

CCS only shares workspace context paths (project/session context files). It does not merge or copy authentication credentials between accounts.

— docs/session-sharing-technical-analysis.md

요약 표:

인증은 어떤 경우에도 섞이지 않습니다. 한 인스턴스의 OAuth 토큰이 실수로 다른 인스턴스의 요청에 흘러갈 일이 구조적으로 없으므로, 회사 환경에서 가장 큰 사고 가능성을 시스템 자체가 막아 둡니다.

ccs -r (resume)는 현재 활성 lane만 이어가고, ccs <account> -r은 그 인스턴스의 lane만 이어갑니다. 두 인스턴스 모두 다른 continuity 인벤토리를 가질 수 있다는 점을 의식하고 운영해야 합니다.

4가지 진입점: Target Adapter System​

ccs가 Claude Code만 호출하는 게 아닙니다. CCS는 runtime 자체를 바꾸는 4가지 바이너리를 노출합니다.

내부적으로는 각 바이너리가 CCS_INTERNAL_ENTRY_TARGET 환경변수를 세팅한 후 target resolver에 위임합니다. resolver의 우선순위:

1. CLI 플래그 (--target)
2. 진입 바이너리 자체
3. argv[0] 이름 검출
4. 프로파일별 config
5. 기본값

이 추상화 덕분에 "Claude Code로 GLM 돌리기"와 "Droid로 GLM 돌리기"가 같은 명령 표면 위에서 가능합니다(ccs glm vs ccs --target droid glm). Codex의 경우 자기 ~/.codex/ 상태를 별도 보존하려고 환경변수만 임시로 덮어쓰는 식으로 신경을 더 씁니다.

로컬 프록시 (127.0.0.1:포트)의 5단계 흐름​

OpenRouter, DeepSeek 같은 OpenAI-호환 프로바이더 프로필로 요청이 들어오면 다음 5단계를 거칩니다(docs/openai-compatible-providers.md 정리).

1. 127.0.0.1에서 그 프로파일의 로컬 포트 바인딩 (포트는 proxy.profile_ports에서 할당)
2. Claude Code가 보내는 Anthropic 형식 /v1/messages 요청 수신
3. OpenAI chat-completions 형식으로 변환
4. 업스트림 프로바이더로 포워드
5. 스트리밍 응답을 다시 Anthropic SSE로 역변환해 Claude Code에 돌려줌

정리하면 Claude Code는 자기가 Anthropic과 이야기하는 줄 알고, 변환은 프록시 한 점에서만 일어나므로 디버깅 지점도 한 곳으로 모입니다.

Anthropic-호환 엔드포인트는 프록시를 우회합니다. https://api.anthropic.com이나 Z.AI의 /api/anthropic으로 가는 요청은 변환이 필요 없어 그냥 직통하고, 이 분기 덕분에 GLM 사용은 추상화 비용이 거의 0입니다.

CLIProxyAPI 서버 자체는 기본적으로 port 8317에서 동작하는데, cliproxy_server.local.port로 바꿀 수 있고 remote.host를 켜면 다른 머신의 CLIProxy를 쓸 수도 있습니다.

시나리오 라우팅 4종​

CCS가 수동으로 프로바이더를 명시하지 않아도 자동으로 라우팅하는 4가지 시나리오가 있습니다.

config.yaml에 proxy.routing.longContextThreshold 키가 실제로 있어 임계값을 손으로 조절합니다. 자동화의 깊이는 워크로드에 따라 잘 맞기도 하고 헷갈리기도 하므로, 처음부터 라우팅 룰을 복잡하게 짜기보다 한 주 동안 단순하게 운영한 뒤 패턴을 보고 추가하는 편이 낫습니다(1편 실전 팁 참조).

CLIProxy 서브시스템, OAuth 프로바이더의 자리​

API 키가 없는 OAuth 기반 프로바이더(Gemini, GitHub Copilot, AWS Kiro 등)는 별도 서브시스템이 책임집니다. ~/.ccs/cliproxy/bin/에 자동 다운로드되는 CLIProxyAPI 바이너리가 그 핵심입니다.

이 서브시스템의 Account manager는 OAuth 토큰의 lifecycle(발급, 갱신, 만료)을 관리하고, Quota manager와 Quota fetcher는 각각 프로바이더별 quota 추적과 자동 failover, 사용량 실시간 동기화를 맡습니다. Auth handler는 Anthropic, Gemini, Copilot, Kiro 등 각 프로바이더의 OAuth 흐름을 처리합니다. Model catalogs에는 프로바이더별 모델 목록과 compatibility 가드가 있으며, codex-plan-compatibility.ts 같은 파일이 plan별로 맞지 않는 모델 조합을 막아 줍니다. Hybrid quota strategy는 round-robin 또는 fill-first(cliproxy.routing.strategy) 방식으로 같은 프로바이더의 여러 OAuth 계정을 어떻게 분산할지 정합니다.

config.yaml의 cliproxy.oauth_accounts가 등록된 OAuth 계정 목록을 담는데, 이 부분은 토큰을 포함하므로 git에 올리면 안 되는 영역입니다. 다음 11절에서 정리합니다.

파일 관리 실전: symlink가 dotfiles의 답입니다​

2절의 symlink 체인을 보고 나면 자연스레 이런 질문이 나옵니다. 내 CCS 환경을 다른 머신에 어떻게 옮기는지, ~/.ccs/를 통째로 git에 넣어도 되는지 궁금해집니다. ~/.ccs/를 versioning하지 않고 ~/.claude/를 versioning해 CCS가 그쪽을 끌어들이게 하면 됩니다.

멘탈 모델: ~/.claude/가 source of truth​

체인의 시작점은 ~/.claude/입니다. CCS의 shared/와 instance들은 그쪽으로 가는 포인터일 뿐입니다. 따라서 dotfiles의 운용 원칙은 하나로 압축됩니다. ~/.claude/를 git으로 관리해 두면, 새 머신에 CCS를 설치하더라도 shared/만 같은 symlink로 다시 걸어 모든 인스턴스가 같은 환경을 보게 됩니다.

git에 올리기 좋은 자산 (~/.claude/ 쪽)​

~/.claude/commands/, ~/.claude/skills/, ~/.claude/agents/에는 각각 슬래시 커맨드, 스킬, 에이전트 정의가 들어가므로 git에 올리기 좋습니다. 글로벌 메모리인 ~/.claude/CLAUDE.md도 관리 대상입니다. ~/.claude/settings.json은 토큰을 직접 적어 두지 않은 경우에만 포함해야 하며, env 필드에 비밀이 있다면 settings.local.json 패턴으로 분리합니다. 실 디렉토리인 ~/.ccs/shared/context-groups/default/에서는 projects/를 빼고 CCS의 그룹 메타만 versioning하는 식으로 관리합니다.

~/.ccs/.claude/ (CCS 번들)은 npm 패키지 일부라 install 시 자동으로 따라옵니다. 직접 versioning 할 필요 없습니다.

절대 git 금지 (자격증명, 세션, 트랜스크립트)​

~/.ccs/config.yaml에는 OAuth 토큰/refresh_token이 있으므로 머신별로 보관하고, 세션 비밀인 ~/.ccs/.session-secret도 제외합니다. ~/.ccs/instances/*/.anthropic/의 Anthropic OAuth와 계정 식별자를 포함한 ~/.ccs/instances/*/.claude.json도 올리면 안 됩니다.

~/.ccs/instances/*/sessions/, session-env/에는 세션과 세션별 env가 있어 토큰 환경변수가 들어갈 가능성이 있습니다. ~/.ccs/instances/*/history.jsonl, file-history/에는 명령과 파일 history가 남아 회사 코드의 흔적이 섞일 수 있습니다. 대화 히스토리 본체인 ~/.ccs/shared/context-groups/*/projects/도 PII나 회사 코드를 포함할 가능성이 있으므로 제외합니다. 바이너리와 휘발성 데이터가 담긴 ~/.ccs/cliproxy/, cache/, logs/, 평소 Claude Code 대화 히스토리인 ~/.claude/projects/도 git에 올리지 않습니다.

새 머신 부트스트랩 4단계​

dotfiles가 ~/.claude/만 들고 있다고 할 때 새 머신에서 같은 환경을 만들려면:

1. dotfiles를 clone해 ~/.claude/를 채웁니다.
2. npm install -g @kaitranntt/ccs로 CCS를 설치합니다.
3. ccs config로 초기 ~/.ccs/ 골격을 생성합니다.
4. symlink를 재구성합니다. ~/.ccs/shared/{commands,skills,agents,plugins,settings.json}을 ~/.claude/의 동명 항목으로 link하며, 한 줄 스크립트로 자동화하기를 권장합니다.

ln -sf ~/.claude/commands       ~/.ccs/shared/commands
ln -sf ~/.claude/skills         ~/.ccs/shared/skills
ln -sf ~/.claude/agents         ~/.ccs/shared/agents
ln -sf ~/.claude/plugins        ~/.ccs/shared/plugins
ln -sf ~/.claude/settings.json  ~/.ccs/shared/settings.json

이 다섯 줄로 새 머신에서도 1편의 instance들이 평소 환경을 그대로 봅니다. OAuth 인증만 각 인스턴스에서 새로 하면 끝입니다.

격리의 운영 이점​

한 인스턴스가 망가져도(plugins/ 깨짐, policy-limits.json 누락 등) 다른 인스턴스는 그대로이므로 단일 장애점이 줄어드는 부수 효과가 있습니다. 인스턴스 단위 백업에는 tar czf team-backup.tgz -C ~/.ccs/instances team을 씁니다. symlink는 그대로 보존하며, 옵션 -h를 추가하면 링크가 가리키는 파일까지 따라가 archive합니다. 복원할 때 같은 dotfiles 환경을 가정하므로 보통은 symlink를 그대로 두는 편이 의미 있습니다.

config.yaml의 비공식 영역들​

CCS의 README가 강조하지 않지만 config.yaml 키만 봐도 드러나는, 단순 스위처라기엔 풍부한 통합이 여럿입니다.

가장 눈에 띄는 것은 WebSearch fallback입니다. websearch.providers 아래에 exa, tavily, brave, searxng, duckduckgo, gemini, opencode, grok 여덟 곳이 등록돼 있어, Claude Code의 WebSearch가 Anthropic 밖 8개 프로바이더로 넘어갈 수 있습니다. docs/websearch.md가 별도 문서로 있을 만큼 일급 통합입니다. 외부 에디터/툴 통합도 넓어서, copilot.account_type, rate_limit, model로 GitHub Copilot을 프로바이더 한 슬롯처럼 다루고 cursor.ghost_mode/cursor.port로 Cursor의 ghost-mode까지 건드립니다. channels.selected, channels.unattended를 통해 Telegram, Discord, iMessage로 Claude에게 일을 시키는 통합도 있습니다(1편의 free-claude-code 텔레그램 봇 사례와 같은 결입니다).

세밀한 정책 키도 있습니다. thinking.tier_defaults는 opus, sonnet, haiku별로 thinking 기본 모드를 다르게 잡게 해주고(Opus는 항상 deep thinking, Haiku는 끄는 식), global_env.env의 DISABLE_BUG_COMMAND, DISABLE_ERROR_REPORTING, DISABLE_TELEMETRY는 보안, 프라이버시에 민감한 회사 환경에서 텔레메트리를 자동으로 꺼줍니다. cliproxy.routing.session_affinity와 session_affinity_ttl은 같은 세션을 같은 OAuth 계정으로 sticky하게 묶는 정책입니다. 이런 영역들은 CCS가 단순 스위처에서 운영 플랫폼으로 진화 중이라는 신호입니다.

한 줄로​

1편이 CCS의 표면이었다면 2편은 안쪽입니다. 안쪽을 보고 나면 "프로파일로 옮겨 다닌다"는 1편의 단순한 설명이 사실은 instance 격리, shared 공유, OAuth 분리, OpenAI와 Anthropic 사이의 변환, 시나리오 라우팅, 여러 통합 지점이라는 축들로 짜여 있다는 게 보입니다. 추상화가 두껍다는 1편의 단점 평가는 그래서 정확하지만, 그 두께가 풀고 있는 문제도 같이 두껍다는 사실이 디렉토리 한 통에 적나라하게 드러납니다.

다음 편이 있다면 두 갈래 중 하나일 가능성이 커요. proxy.routing 시나리오를 실제 워크로드로 맞춰 보는 측정 기반 운영 글이거나, CCS와 dotfiles, Anthropic Workspaces를 엮는 멀티-머신 계정 운영 글일 거예요. 어느 쪽이 먼저 나올지는 다음 글에서 정할게요.

참고​

• Claude Code Switcher(1편)
• CCS 홈페이지
• kaitranntt/ccs: GitHub
• docs/codebase-summary.md: 아키텍처 4 레이어
• docs/session-sharing-technical-analysis.md: 공유/격리 모델(이 글의 5~6절 출처)
• docs/openai-compatible-providers.md: 로컬 프록시 변환 흐름
• docs/project-overview-pdr.md: 5 서브시스템 개요
• docs/websearch.md: WebSearch 8 fallback 상세
• Z.AI Claude Code 가이드: Anthropic-호환 엔드포인트의 공식 출처