LedgerCore

계좌 간 자금 이동을 기록하는 시스템의 유일한 요구사항은 절대 틀리지 않는 것입니다. 요청이 같은 순간에 도착하든, 클라이언트가 재시도하든, 처리 도중 프로세스가 죽든 돈이 새로 생기거나 사라지면 안 되고, 같은 이체가 두 번 적용되어서도 안 됩니다.

API(NestJS 10 모듈러 모놀리스)가 사용자와 계좌, 입금과 출금, 이체, 취소(reversal), 잔액, 내역, 대사(reconciliation)를 처리합니다. 같은 코드베이스의 별도 워커 프로세스가 outbox 이벤트를 FOR UPDATE SKIP LOCKED로 가져와 HMAC 서명 웹훅으로 보냅니다. 불변식은 PostgreSQL 16의 deferred constraint trigger가 검사하므로 애플리케이션 코드의 실수로 우회할 수 없습니다. 운영 콘솔(React + Vite)은 계좌, 이체, outbox 전달 상태를 보여 줍니다.

크게 보기

무엇을 바꿨나

잔액 엔드포인트가 BEGIN READ ONLY → 계좌 확인 → SUM → COMMIT으로 DB를 4번 오가며 연결을 잡고 있었습니다(HTTP p95 141ms, SQL 자체는 약 0.3ms). READ COMMITTED에서는 statement마다 snapshot을 따로 잡아 이 트랜잭션은 일관성도 보장하지 않았습니다. pool을 20에서 40으로 늘려도 7%만 빨라져 원인은 pool이 아니었고, 20만 행 DB의 EXPLAIN ANALYZE는 두 방식 모두 같은 55 buffer와 같은 인덱스를 보였습니다. accounts + CROSS JOIN LATERAL(SUM …) 단일 statement로 바꾸고(404 유지), DB 호출이 한 번인지 확인하는 회귀 테스트를 추가했습니다. 고정 속도 100 iter/s, 3+3회 측정이며 내역과 이체 p95 차이는 잡음 범위입니다.

증상

전체 벤치마크 중 500 3건과 409 3건이 나왔습니다. 원장은 균형을 유지했습니다.

원인

Postgres는 04:00:52.7에 lock_timeout을 냈는데 API는 그 응답을 10초 뒤에 기록했고, 같은 순간 40ms 안에 500이 몰려 나왔습니다. Node 프로세스 자체가 멈춰 있었던 것입니다. 원인은 모든 요청을 info 수준으로 로깅한 것으로, Windows에서 stdout 파이프 쓰기는 동기이고 PowerShell 리다이렉션이 따라가지 못했습니다.

해결

LOG_LEVEL=warn으로 같은 시나리오에서 fault 0, 409 0, 처리량 +37%. lock_timeout 3s, statement_timeout 5s, idle_in_transaction_session_timeout 10s가 락을 풀어 주었고, 그때 500 INTERNAL_ERROR를 돌려주던 timeout을 503 DATABASE_TIMEOUT(retryable: true)으로 바꿨습니다 (8c30dba).

재발 방지

실제 Postgres와 pg-pool로 timeout → 503 테스트 3개를 작성했습니다. 프로덕션에는 비동기 logger나 sampling이 필요하다는 점을 제약에 기록했습니다.

테스트 수

392

커버리지

—

CI

GitHub Actions (커밋 메시지, 포맷, lint, typecheck, Postgres 서비스로 테스트, 빌드; billing 문제로 현재 중단)

테스트 도구

Vitest, supertest, 실제 PostgreSQL 16 (mock 없음), k6 + bench.ps1

배포 환경

iwinv VPS, Docker Compose. web(Caddy)만 외부 proxy 네트워크에 있고 /v1/*을 API로 넘깁니다. Postgres와 Redis 포트는 열지 않습니다. deploy.sh: 충돌 표시 검사 → git merge --ff-only → migrate, api, web 이미지를 SHA 태그로 빌드(worker는 api 이미지 사용) → migrate 성공 뒤 API와 worker 기동 → /v1/health/ready를 최대 60초 대기 → 준비된 버전만 APP_TAG와 .deploy-history에 기록, 실패하면 rollback 명령을 출력.

백업

cron이 매일 03:00에 서버의 모든 Postgres 컨테이너를 pg_dump -Fc로 백업하고 7일 보관합니다. restore-test.sh가 최신 백업을 임시 DB에 복원해 테이블 수를 비교하고, LedgerCore는 VERIFY_SQL로 복식부기 불변식까지 확인합니다: 68K 덤프, 14/14 테이블, 복원 0.68초, 20 entries imbalance=0.

롤백

rollback.sh는 빌드 없이 api, worker, web을 이전(또는 지정한) SHA로 되돌리고 health를 확인합니다. Postgres와 Redis는 건드리지 않으며 마이그레이션은 되돌리지 않습니다. 프로덕션에서 2066318 → d10826f → 2066318로 시험해 매번 ready였습니다(약 1초).

모니터링

postgresql.prod.conf: lock_timeout 3s, statement_timeout 5s, idle_in_transaction_session_timeout 10s, 500ms 넘는 쿼리 로깅, pg_stat_statements 활성화, 모니터링 네트워크로 PG Insight에 연결. /v1/health/ready

• db/migrations/1737000200000_enforce-double-entry-invariant.sql

  차변 = 대변을 COMMIT에서 검사하는 deferred constraint trigger

• db/migrations/1737000300000_make-ledger-immutable.sql

  엔트리 수정과 삭제를 DB에서 금지

• apps/api/src/modules/ledger/infrastructure/transaction.repository.ts

  계좌를 id 순서로 FOR UPDATE

• apps/api/src/modules/ledger/application/transfer.service.ts

  락, 잔액 확인, 엔트리, outbox를 한 트랜잭션에서

• apps/api/src/modules/ledger/application/reversal.service.ts

  락을 잡은 뒤 상태를 다시 읽는 reversal (race 수정)

• apps/api/src/modules/ledger/infrastructure/balance.repository.ts

  단일 statement 잔액 조회

• apps/api/src/shared/database/transaction.manager.ts

  AsyncLocalStorage 트랜잭션, 40001/40P01 재시도

• apps/api/src/shared/errors/postgres-error.translator.ts

  SQLSTATE → 도메인 오류, timeout → 503

• apps/api/test/concurrency/transfer-concurrency.test.ts

  동시성 테스트 10개

• load-tests/bench.ps1

  warm-up, 3회, 중앙값, 유효성 규칙

최종 코드의 부하 테스트 12회가 모두 유효했고 fault 0, deadlock 0, contention 0, 매 실행 뒤 원장 균형이 맞았습니다. 잔액 조회를 단일 statement로 줄여 고정 속도 A/B에서 p95를 24.9ms에서 13.4ms로 낮췄습니다. 그 밖에 동시 reversal 두 건 중 두 번째가 409 대신 422를 돌려주던 race(ccee39b), .env.test가 gitignore에 있어 깨끗한 클론에서 테스트가 아예 돌지 않던 문제(e0e6884), k6 스크립트의 __ITER와 teardown 오류(0f76291)를 숫자를 믿기 전에 찾아 고쳤습니다.