# 강동현 · Backend / Platform Engineering Portfolio | | | |---|---| | Email | donghyeonka68@gmail.com | | GitHub | [github.com/donghyeon-ka](https://github.com/donghyeon-ka) | | TechLog | [hyeonworks.com](https://hyeonworks.com) | | Blog | [velog.io/@donghyeon2](https://velog.io/@donghyeon2) | --- ## About Java / Spring Boot를 중심으로 백엔드를 공부하고 있습니다. 현업 개발자의 멘토링 아래 약 6개월 동안 인증, 데이터 조회, 아키텍처, Kubernetes 인프라를 직접 구현하고 검증했습니다. 제가 가장 많이 시간을 쓴 부분은 **기술을 적용하는 것보다 실제 동작을 설명할 수 있게 만드는 과정**이었습니다. - BFF를 적용했다면 브라우저에서 사라진 token은 어디로 갔는지 - N+1을 없앴다면 쿼리 수 대신 다른 비용이 커지지는 않았는지 - Kubernetes manifest에 설정이 있다면 실제 runtime에서도 집행되고 있는지 - API 계약이 맞다면 값이 왜 화면까지 도착하지 않는지 이 포트폴리오에는 그 질문이 가장 잘 드러나는 네 가지 사례만 담았습니다. --- ## 한눈에 보기 | 주제 | 시작한 질문 | 핵심 판단 | |---|---|---| | **TechLog** | 계약을 한 곳에서 관리하는데 왜 화면에서는 값이 사라질까? | 계약 자체보다 **값이 지나가는 경계와 수동 목록**이 더 자주 깨졌다 | | **Keycloak 인증 경계** | 브라우저에서 token을 없애면 더 좋은 구조일까? | token이 사라지는 것이 아니라 **다른 계층이 state와 검증 책임을 가져간다** | | **피드 조회 성능** | N+1은 fetch join으로 해결하면 끝일까? | 쿼리 수뿐 아니라 **row 수, paging, index, Top-N 비용**을 같이 봐야 했다 | | **Home Platform** | 서비스가 접속되면 인프라 구성이 끝난 걸까? | TLS, proxy trust, secret, state의 **실제 경로를 runtime에서 확인할 수 있어야 했다** | --- # 01. TechLog ## 기술 기록을 다시 읽을 수 있는 서비스로 만들기 인증, 성능, 인프라 과제를 진행하면서 문서가 계속 늘었습니다. 문제는 기록이 부족한 것이 아니라 **나중에 왜 이런 결정을 했는지 다시 따라가기 어려운 것**이었습니다. 그래서 단순 블로그가 아니라 프로젝트 → 주제 → 기록의 맥락을 유지하면서 작성·검증·미리보기·게시까지 할 수 있는 TechLog를 만들기 시작했습니다. 현재 공개 화면은 [hyeonworks.com](https://hyeonworks.com)에서 확인할 수 있습니다. ### 구조 ```text OpenAPI contract │ ├── Backend │ domain / application / inbound / outbound │ └── Frontend domain / application / adapter / presentation Studio Create → Save → Validate → Preview → Publish │ ▼ Public ``` Backend는 현재 **18개 Gradle module**로 나누고, module registry를 기준으로 허용 dependency와 runtime membership을 검증하도록 구성했습니다. ### 가장 어려웠던 문제 — 계약은 맞는데 값이 사라졌다 처음에는 OpenAPI 계약을 한 저장소에서 관리하고 Backend와 Frontend가 같은 계약을 사용하면 서로 어긋날 일이 적을 것이라고 생각했습니다. 실제 문제는 다른 곳에서 나왔습니다. ```text PostgreSQL → SQL adapter → application view → response mapper → generated DTO → HTTP → frontend gateway → application port → component ``` 값 하나가 화면에 도착하기까지 여러 경계를 지나면서 **어느 한 곳이 값을 조용히 버려도 타입 검사나 화면에서 오류가 나지 않는 경우**가 있었습니다. 예를 들어 DB에는 값이 있고 API 계약에도 필드가 존재하지만, 중간 mapper가 해당 필드를 전달하지 않아 화면에서는 빈 값으로 보였습니다. 화면은 이를 오류가 아니라 “데이터가 없음”으로 표현했습니다. ### 문제를 어떻게 좁혔는가 증상을 “화면이 비었다”로 보지 않고 **값의 이동 경로를 끝까지 따라갔습니다.** - DB row에 값이 있는지 - persistence adapter가 읽었는지 - application model에 남아 있는지 - HTTP response mapper가 전달했는지 - generated contract type에 필드가 있는지 - frontend adapter가 mapping했는지 - 최종 component가 받은 값이 무엇인지 이 방식으로 contract 자체의 오류와 **contract 이후의 연결 오류**를 분리했습니다. ### 반복해서 깨진 것 — 손으로 관리한 목록 Record 종류나 route 종류를 배열·삼항식으로 직접 나열한 곳에서는 새 종류를 추가할 때 누락이 반복됐습니다. ```ts // 이런 구조에서는 새 종류를 빠뜨려도 마지막 분기로 조용히 떨어질 수 있다. const path = kind === "CASE" ? "/cases/" : kind === "REFERENCE" ? "/references/" : "/projects/"; ``` 이를 `Record`, exhaustive switch, contract coverage test처럼 **누락 자체를 실패로 만드는 구조**로 바꿨습니다. 핵심은 “사람이 잘 기억하자”가 아니라 **컴파일러나 테스트가 목록의 완전성을 확인하도록 만드는 것**이었습니다. ### 이 프로젝트에서 남은 기준 - 값은 중간 layer가 아니라 **최종 사용자에게 보이는 지점까지 확인한다.** - 종류를 수동으로 나열해야 한다면 completeness를 검증할 방법을 같이 둔다. - “없음”과 “읽지 못함”을 같은 UI 상태로 표현하지 않는다. - 테스트가 존재하는 것보다 실제 CI / verification 경로에서 그 테스트가 실행되는지가 중요하다. ### Stack `Java 21` `Spring Boot` `JPA` `PostgreSQL` `Gradle` `ArchUnit` `React` `TypeScript` `OpenAPI` `Vitest` `Playwright` --- # 02. Keycloak 인증 경계 ## “브라우저에서 token을 없애면 더 안전하다”를 구조로 확인하기 OAuth2 / OIDC를 공부할 때 SPA, BFF, Forward-Auth라는 이름은 많이 볼 수 있었습니다. 하지만 이름만으로는 다음 질문에 답하기 어려웠습니다. - authorization code는 누가 token으로 교환하는가? - access token과 refresh token은 어디에 남는가? - 실제 API caller는 browser인가, server인가? - Resource Server는 JWT를 검증하는가, trusted header를 믿는가? 같은 기능 요구사항을 두고 네 가지 구조를 직접 구현해 비교했습니다. ### 네 패턴을 credential 소유권으로 비교 | 구조 | Browser | Server / Edge | API가 받는 값 | |---|---|---|---| | **SPA** | access / refresh token 관리 | 없음 | Bearer JWT | | **Token Mediator** | access token 사용 | refresh token / client state 관리 | Browser가 보낸 Bearer JWT | | **BFF** | session cookie | OAuth token + server session | BFF가 만든 Bearer JWT | | **Forward-Auth** | proxy session cookie | OAuth login + identity projection | trusted identity header | 처음에는 SPA → BFF → Forward-Auth로 갈수록 token이 브라우저에서 멀어지므로 더 좋은 구조처럼 보였습니다. 직접 구현해보니 **없어진 책임은 없었습니다.** ### BFF — token 대신 state를 운영한다 BFF에서는 JavaScript가 OAuth token을 받지 않습니다. 대신 Backend가 다음을 맡습니다. - server-side session - authorized client / refresh token 저장 - CSRF 검증 - downstream API 호출 - logout 시 session과 token state 정리 - replica가 늘어났을 때 state 공유 즉 브라우저 token 노출을 줄이는 대신 **stateful backend를 운영하는 비용**이 생겼습니다. ### Forward-Auth — JWT 대신 header를 믿는다 Forward-Auth에서는 upstream이 OAuth token을 직접 이해하지 않아도 됩니다. 하지만 edge가 만든 identity header를 신뢰하려면 조건이 필요했습니다. - backend로 직접 들어가는 외부 경로를 닫는다. - browser가 보낸 인증 관련 header를 edge에서 덮어쓴다. - edge와 upstream 사이의 신뢰 범위를 제한한다. - endpoint가 늘어나도 동일한 인가 검증을 적용할 수 있어야 한다. 결국 “token이 없다”가 아니라 **신뢰할 credential의 형태가 JWT에서 header로 바뀐 것**이었습니다. --- ## 단일 인스턴스 설명에서 2-node 환경으로 인증 구조를 구현한 뒤에는 다음 질문이 남았습니다. > Keycloak replica를 늘리면 session은 실제로 어디에 존재하는가? 물리 서버 위에 VM 2대를 만들고 K3s server / agent로 구성해 Keycloak 두 인스턴스와 PostgreSQL, Redis를 배치했습니다. ### 예상과 달랐던 session 경로 Keycloak 26의 기본 `persistent-user-sessions` 조건에서 교차 노드 session 처리는 단순히 “Infinispan이 session을 복제해서” 설명되지 않았습니다. 실제 SQL과 runtime 상태를 확인하면서 **두 인스턴스가 공유 PostgreSQL의 persistent session state를 사용할 수 있다는 점**을 확인했습니다. 반대로 persistent session을 끈 조건에서는 JGroups, cache, restart, DB 장애가 결과에 미치는 영향이 달라졌습니다. ### 장애 명령을 실행했다고 장애가 만들어진 것은 아니었다 NetworkPolicy, iptables, `tc`를 이용해 network fault를 만들면서 가장 크게 바뀐 습관은 이것이었습니다. > 장애 결과를 보기 전에 **장애 자체가 실제로 주입됐는지 먼저 확인한다.** 기존 connection이 conntrack에 남아 있거나 rule 방향이 틀리면 명령은 성공했지만 통신은 계속될 수 있었습니다. 그래서 결과를 보기 전에 다음을 따로 확인했습니다. - cluster membership - active connection / conntrack - packet counter - process / PID 상태 - 실제 요청 결과 ### 다중 replica에서만 보인 문제 - Refresh Token Rotation 경쟁에서는 동시에 같은 refresh token을 사용했을 때 client session 자체가 무효화되는 조건을 확인했습니다. - Resource Server replica별 JWKS cache 상태가 다르면 같은 old token이 replica에 따라 다른 결과를 낼 수 있었습니다. - Session store와 OAuth2 Authorized Client store는 조회 key가 달라 **session만 Redis로 옮긴다고 token state까지 해결되는 것은 아니었습니다.** ### 이 실습에서 남은 기준 인증 구조를 볼 때 이제는 패턴 이름보다 먼저 다음을 확인합니다. 1. credential의 실제 소유자는 누구인가 2. state는 어느 저장소에 남는가 3. replica가 늘어나면 그 state를 어떻게 찾는가 4. 보호 자원이 최종적으로 무엇을 신뢰하는가 5. 실패했을 때 어느 계층이 401 / 403 / 재로그인을 결정하는가 ### Stack `Keycloak` `OAuth2 / OIDC` `Spring Security` `PKCE` `JWT / JWKS` `K3s` `PostgreSQL` `Redis` `JGroups` `Nginx` `oauth2-proxy` --- # 03. 피드 조회 성능 ## N+1을 없앤 뒤에도 느릴 수 있는 이유 피드에서 각 항목의 최신 Highlight와 공개 범위, pagination을 함께 조회하는 과제를 진행했습니다. 처음 문제는 명확했습니다. > FeedItem을 N개 읽으면 연관 데이터를 가져오기 위한 SQL도 N에 비례해 증가한다. PostgreSQL 16 Testcontainers와 Hibernate Statistics를 이용해 실제 쿼리 수를 측정했습니다. ### 기준선 FeedItem 1,000개를 조회했을 때: - PreparedStatement: **2,022** - Highlight collection fetch: **1,000** - local warm-cache 기준 median 약 **193.7ms** 중요했던 것은 시간보다 **왜 2,022개의 SQL이 발생했는지 분리하는 것**이었습니다. --- ## Fetch Join이 항상 답은 아니었다 N+1 해결책으로 가장 먼저 떠올릴 수 있는 fetch join을 적용했지만 다른 문제가 생겼습니다. ### 두 collection을 동시에 fetch `MultipleBagFetchException`으로 실패했습니다. ### collection 하나만 fetch 쿼리 수는 줄었지만 join으로 인해 DB가 보내는 row 수가 늘어났습니다. ### fetch join + pagination 응답은 한 page였지만 SQL에는 기대한 `LIMIT`이 없고, 부모 데이터를 더 많이 읽은 뒤 memory에서 page를 잘라내는 문제가 나타났습니다. 즉 **쿼리 수가 줄었다는 사실만으로 개선이라고 판단할 수 없었습니다.** --- ## Batch Fetch — 단순 조회를 유지하면서 쿼리 수 줄이기 Batch Fetch를 적용한 뒤 같은 N=1,000 조건에서: **PreparedStatement 2,022 → 23** 으로 줄었습니다. 엔티티 조회 구조를 크게 바꾸지 않고 N+1과 pagination을 함께 다루기에는 유효했습니다. 하지만 여전히 화면에 필요하지 않은 entity까지 로드하는 비용이 남았습니다. 그래서 다음 단계로 DTO Projection을 비교했습니다. - entity load 0 - N이 증가해도 고정된 수의 query - 필요한 컬럼 중심의 읽기 경로 --- ## 부모마다 최신 3개 — Window vs LATERAL vs 2-step 다음 요구사항은 단순 LIMIT으로 해결되지 않았습니다. > “전체에서 3개”가 아니라 **각 FeedItem마다 최신 Highlight 3개** 세 가지 접근을 같은 데이터에서 비교했습니다. - Window Function - LATERAL - 2-step query 현재 데이터에서는 **작은 K=3과 복합 인덱스 seek가 가능한 조건**에서 LATERAL이 유리했습니다. 하지만 인덱스를 제거하거나 K가 커지면 이점이 줄었습니다. 따라서 결론을 “LATERAL이 빠르다”가 아니라 다음처럼 정리했습니다. > LATERAL의 이점은 문법 자체보다 **부모별로 적은 수의 row를 index seek할 수 있는 조건**에서 나온다. --- ## 깊은 페이지 — OFFSET vs Keyset 2,000행 데이터의 100번째 page를 비교했습니다. - OFFSET: 앞의 row를 포함해 **2,000행** 탐색 - Keyset + 정렬키 index: 다음 page에 필요한 **20행** 탐색 실행계획에서도 scan-then-discard와 index seek의 차이를 확인했습니다. Keyset 역시 항상 정답은 아니었습니다. 정렬 조건을 만족하는 index가 없으면 장점이 크게 줄었습니다. ### 이 실습에서 남은 기준 조회 성능을 볼 때 다음 순서로 확인합니다. 1. query count 2. DB가 실제 읽고 반환한 row 3. entity materialization 4. sort / index 사용 여부 5. pagination이 DB에서 일어나는지 memory에서 일어나는지 6. 데이터 분포와 K가 바뀌어도 같은 결론인지 ### Stack `Spring Data JPA` `Hibernate` `PostgreSQL 16` `Testcontainers` `Flyway` `EXPLAIN (ANALYZE, BUFFERS)` --- # 04. Home Platform ## “서비스가 뜬다”에서 “요청 경계를 설명할 수 있다”로 개인 서버에 서비스를 하나씩 올리면서 처음에는 host에 Nginx 설정을 추가하고 K3s 안에 필요한 workload를 배치했습니다. 서비스가 늘어나자 다음 질문에 바로 답하기 어려워졌습니다. - TLS는 어디에서 종료되는가? - 외부 요청이 Kubernetes로 들어가는 문은 몇 개인가? - `X-Forwarded-*`는 누가 만들고 누가 신뢰하는가? - DB와 object storage는 외부에서 직접 접근 가능한가? - Secret은 어디가 원본인가? - manifest에 적힌 설정과 실제 cluster state가 같은가? 그래서 저장소 설정, 문서, live cluster를 대조하며 현재 구조를 다시 정리했습니다. --- ## 요청 경로 ```text Client │ HTTPS ▼ Host Nginx :443 │ TLS termination │ forwarded header overwrite │ source allowlist ▼ 127.0.0.1:30080 │ ▼ Traefik NodePort │ ▼ Kubernetes Service │ ├── Gitea ├── Keycloak ├── Grafana ├── pgAdmin └── Object Storage Console ``` 핵심은 두 가지였습니다. ### TLS는 Host Nginx에서 한 번만 종료 Nginx 뒤의 cluster 진입은 HTTP로 단순화했습니다. ### NodePort를 loopback에 제한 Traefik NodePort를 LAN 전체에 노출하지 않고 `127.0.0.1` 경로로 제한해 **클러스터 진입점을 Host Nginx 뒤로 고정**했습니다. 또한 외부에서 들어온 `X-Forwarded-*`를 Nginx가 다시 작성하고, Traefik은 실제 upstream source만 trusted proxy로 인정하도록 범위를 좁혔습니다. --- ## 상태를 어디에 둘 것인가 같은 cluster 안에서도 state의 성격을 분리했습니다. - PostgreSQL — CloudNativePG - Keycloak — PostgreSQL 기반 identity state - Gitea — PostgreSQL + Local PV - Object Storage — 별도 XFS 영역 - Observability — Prometheus / Loki / Tempo 등 각 저장 경로 Local PV는 노드와 디스크에 강하게 묶입니다. 따라서 `Retain`이나 PVC가 있다고 해서 이를 백업이나 HA로 표현하지 않았습니다. 현재 환경은 단일 노드 home lab이므로 노드 자체가 사라지면 플랫폼 전체가 영향을 받습니다. 오프사이트 백업도 별도 과제로 남아 있습니다. --- ## Secret Delivery — Vault를 쓰는 이유를 경로로 설명하기 Secret을 Git에서 제거하는 것만으로는 secret 관리가 끝나지 않았습니다. 누가 Vault에 접근하고 workload는 무엇을 읽는지까지 분리했습니다. ```text Vault KV-v2 │ ▼ Vault Secrets Operator │ ▼ Kubernetes Secret │ ▼ Workload ``` 애플리케이션이 Vault API를 직접 호출하지 않고 Kubernetes Secret만 소비하도록 구성했습니다. - Kubernetes Auth - role / policy 분리 - VaultConnection / VaultAuth - VaultStaticSecret - bootstrap dependency 현재 lab Vault는 1 replica / file storage 기준이며 이를 HA 구성으로 표현하지 않습니다. --- ## 관측 — 선언과 runtime을 구분하기 인프라를 정리하면서 가장 중요하게 둔 기준은 다음 다섯 가지였습니다. | 표현 | 의미 | |---|---| | **관측** | 실제 host / cluster에서 명령을 실행해 확인 | | **선언** | manifest나 설정 파일에 존재 | | **기록** | 과거 문서에서 확인한 상태 | | **추론** | 관측과 선언을 근거로 판단 | | **미확인** | 아직 확인하지 못함 | 예를 들어 NetworkPolicy YAML이 저장소에 있다는 사실만으로 실제 통신이 막힌다고 판단하지 않았습니다. Prometheus / Grafana / Loki / Tempo / Blackbox Exporter를 구성하고, 필요한 경우 실제 endpoint와 cluster state를 함께 확인했습니다. ### 이 프로젝트에서 남은 기준 - manifest는 **의도**이고 runtime은 **결과**다. - `1/1 Ready`는 HA를 의미하지 않는다. - `Retain`은 backup을 의미하지 않는다. - proxy header를 신뢰하려면 proxy를 우회할 경로도 같이 닫아야 한다. - 장애나 보안 정책은 “설정했다”가 아니라 실제 상태 변화로 확인한다. ### Stack `K3s` `Kubernetes` `Nginx` `Traefik` `Kustomize` `CloudNativePG` `Vault` `VSO` `Prometheus` `Grafana` `Loki` `Tempo` --- ## 제가 문제를 확인하는 방식 네 프로젝트의 주제는 다르지만 문제를 확인하는 순서는 비슷했습니다. ```text 1. 먼저 기준선을 만든다. ↓ 2. 내가 예상한 동작을 적는다. ↓ 3. 실제 요청 / SQL / packet / runtime state를 본다. ↓ 4. 예상과 다른 지점을 가장 작은 경계까지 좁힌다. ↓ 5. 수정 후 같은 관측 지점에서 다시 확인한다. ↓ 6. 아직 확인하지 않은 범위를 따로 남긴다. ``` 이 방식 때문에 결과가 기대와 다르게 나와도 실습을 실패했다고 보지 않습니다. 오히려 **예상과 실제가 갈리는 지점이 다음 설계 판단의 근거**가 되었습니다. --- ## Additional Work ## Clean Architecture Backend Template Java / Spring 기반 프로젝트에서 domain과 application policy가 framework detail에 끌려가지 않도록 multi-module template을 구성하고 있습니다. Gradle에는 module dependency direction을 두고, application / adapter / bootstrap의 책임을 분리하며 ArchUnit과 테스트로 경계를 검증하는 방향으로 개선했습니다. ## Virtualization CPU virtualization에서 시작해 Network, Storage, Memory까지 실제 host 관점에서 학습하고 문서화했습니다. KVM / QEMU, vCPU와 VM-exit, virtio / vhost-net / TAP / Linux Bridge, NAT, IOMMU / VFIO 등의 흐름을 명령과 실제 구성 기준으로 정리했습니다. --- ## Links - **TechLog** — [https://hyeonworks.com](https://hyeonworks.com) - **GitHub** — [https://github.com/donghyeon-ka](https://github.com/donghyeon-ka) - **Blog** — [https://velog.io/@donghyeon2](https://velog.io/@donghyeon2)