문제: infra/ 43개 중 12개는 코드·테스트·workflow·스크립트 어디서도
읽지 않는다(httpclient·jpa·messaging·notification의 toxiproxy compose와
README). nginx 설정, Kubernetes PVC 인증 job, DB 역할 SQL 셋은 운영
인프라라 개발 repo에 둘 것이 아니다(소유자 결정 2026-11-07). release.yml
의 fileserver-pvc-certification job은 그 매니페스트 문자열만 grep했다.
고른 방법:
- 15개를 지운다.
- 운영 조건만 그 기능 문서에 한국어로 남긴다.
docs/fileserver/operations.md 「운영 환경이 지켜야 할 조건」(nginx
internal location·alias·X-Accel-Redirect 헤더 제거·스트리밍, PVC
ReadWriteOnce·fsGroup), storage-certification.md(인증 절차),
docs/jpa/security.md 「역할과 권한」·「서버 설정」(역할 SQL과
jpa/postgres README 내용), docs/messaging/security.md(인증서 SAN).
httpclient TLS README 내용은 docs/httpclient/security.md에 이미 있다.
- release.yml job과 needs 줄, fileserver-pr.yml·pr-adapters.yml의 지운
경로 필터를 지운다.
- fileserver 지원 표의 "Kubernetes ReadWriteOnce PVC — Limited" 행은
근거 job이 없어져 「주장하지 않음」으로 옮긴다.
버린 대안: 인프라 파일을 project-infra로 옮기기(설계 Q6). 그 repo는
특정 프로젝트용이라 범용 템플릿 파일을 받을 자리가 없다.
위험·한계: 지원 표에서 PVC 주장이 빠진다. 파생 서비스가 그 파일을
배포에 썼다면 병합이 지운다(B-50). 클러스터 인증은 이제 배포하는 쪽이
문서 절차로 한다.
검증(desktop, 트리 749a3328, ~/t1-layout-logs/):
- :composition:fileserver-platform:check :app-bootstrap:check
:app-bootstrap:documentContractTest rc=0 (repositoryContractTest,
FileserverDocumentationCoverageTest 실행)
- :verifyStrictLaneStages --dry-run rc=0
- scripts/verify-compose-profile-contracts.sh rc=0 (18 lane)
- check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/01-backend-layout.md 4.4, 6.3
BREAKING CHANGE: infra/fileserver/nginx, infra/fileserver/kubernetes, infra/jpa, infra/httpclient, infra/messaging, infra/notification/toxiproxy와 release.yml fileserver-pvc-certification job이 없어진다. docs/upgrade/2026-11-maturity-review.md B-50.
4.3 KiB
JPA Platform Runbooks
Operator procedures for the failures this platform is designed to surface rather than hide.
A transaction reported completion unknown
Signal: a write use case failed with a commit-phase error (connection lost, 57P01, class
08) from TransactionPort.
What it means: the commit may or may not have happened. It is not a rollback.
Do not re-run the use case. That is what the platform refused to do automatically, for the same reason.
Procedure:
- Take the idempotency key or operation id of the failed request.
- Check the idempotency record for that key.
- Check the business row the use case would have written.
- Check the outbox for a corresponding event.
- If all three agree the write happened, stop — the request succeeded.
- If all three agree it did not, the use case may be re-run.
- If they disagree or are inconclusive, escalate. An inconclusive answer is a legitimate outcome; guessing is not.
Deadlock or serialization rate rising
Signal: DB_DEADLOCK / serialization failures rising in the persistence error codes.
SpringTransaction does not retry, so each one reaches the caller.
- Group the failures by operation. A single operation dominating means a hot row or an inconsistent lock order.
- For deadlocks, check whether two operations take the same rows in opposite orders — that is a code fix, not a tuning one.
- For serialization failures under
SERIALIZABLE, confirm the isolation is actually required.
Pool exhaustion
Signal: connection acquisition timeouts; PoolMeasurement.pending non-zero.
- Check
REQUIRES_NEWusage. It takes a second connection while pinning the first, so the pool must satisfy(threads x (1 + depth)) + 1. - Check for streaming outside a bounded scope — a
Streamreturned past the transaction holds its connection until the pool notices. - Check for external calls inside a DB transaction. The design forbids them precisely because an HTTP timeout then holds a connection for its whole duration.
Flyway validation failed at startup
The deployment is running against a schema it was not built for. It failed closed, which is correct.
- Read the reported error codes (the messages are deliberately not propagated).
CHECKSUM_MISMATCH— an applied migration was edited afterwards. Find which change is missing from this database. Do not runrepair: it rewrites history to match the scripts, which resolves the symptom by deleting the evidence.MISSING_SCRIPT— a migration applied here is not in this build. Usually a rollback to an older artifact.
An invalid index exists
Signal: this query returns rows.
select n.nspname || '.' || i.relname as invalid_index
from pg_index x
join pg_class i on i.oid = x.indexrelid
join pg_namespace n on n.oid = i.relnamespace
where not x.indisvalid;
A concurrent build, rebuild or drop failed. The index is ignored by the planner and maintained by every write.
- Confirm no build is currently running. An in-progress build looks identical in the catalog.
- If a migration was building, rebuilding or dropping it, Flyway recorded that version as failed
(
success = false) and refuses every later deploy until that row is gone: dropping the index does not clear it. Follow migration-failed.md "Recover a failed concurrent index migration" instead of the next step. It removes the cause, drops the index a failed build or rebuild left, and deletes that one row. It leaves the index a failedDROP INDEX CONCURRENTLYleft, for the deploy again to drop: dropped by hand, that statement finds no index and fails again. - Otherwise run
DROP INDEX CONCURRENTLY IF EXISTS <invalid_index>;outside a migration, and re-apply the index migration.
The platform does not drop these automatically: on a rolling deploy every instance would race to drop an index another instance was about to finish building.
The runtime role failed verification
Startup refused because the runtime credential holds CREATE, or search_path contains an
unapproved schema.
This is not a false positive to be worked around. docs/jpa/security.md 「역할과 권한 — 운영 DB가
갖춰야 할 것」대로 권한을 다시 맞춘다. 애플리케이션 자격 증명이 DDL을 가지면 다른 schema 보장을 하나도
지킬 수 없다.