Files
Resume/portfolio.md
T

548 lines
20 KiB
Markdown

# 강동현 · 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<Kind, Value>`, 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)