diff --git a/01-java-spring-backend.feat.google-version.md b/01-java-spring-backend.feat.google-version.md index 4bb8ce3..0408499 100644 --- a/01-java-spring-backend.feat.google-version.md +++ b/01-java-spring-backend.feat.google-version.md @@ -4,86 +4,84 @@ |---|---| | 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) | --- ## Summary -Java / Spring Boot 기반 백엔드에서 인증, 계층 분리, 예외 응답 표준화, 데이터 영속성 경계에 집중해 학습해 온 신입 백엔드 개발자입니다. +Java / Spring Boot 기반 백엔드에서 인증 경계, 데이터 조회 성능, 계층 분리에 집중해 학습해 온 신입 백엔드 개발자입니다. -Spring Boot 인증 서버를 5 개 모듈 Clean / Hexagonal 구조로 나누고, `domain` 모듈이 Spring / JPA / Servlet에 의존하지 않도록 분리했습니다. 또한 ArchUnit 테스트로 계층 의존성을 검증하고, Keycloak JWT를 Resource Server로 다시 검증하는 구조를 구현했습니다. +현업 개발자의 멘토링 아래 약 6개월 동안 과제를 수행하며, 단순히 기술을 적용하는 데서 끝내지 않고 **왜 이 구조를 선택했는지, 어떤 조건에서 문제가 생기는지**를 직접 구현하고 검증했습니다. Keycloak 인증 구조에서는 token / session의 소유 경계를 비교했고, 피드 조회에서는 N+1부터 Top-N 조회와 pagination까지 실제 SQL과 실행계획으로 확인했습니다. -프로젝트는 개인 로컬 / dev 환경 기준입니다. 대신 구현 범위, 검증 범위, 아직 운영 경험으로 볼 수 없는 부분을 문서 안에서 구분했습니다. +이 과정에서 쌓인 기록을 다시 찾고 맥락대로 연결하기 위해 **TechLog**를 만들고 있습니다. 현재 frontend는 [hyeonworks.com](https://hyeonworks.com)에서 확인할 수 있으며, backend와 인프라의 최종 통합은 진행 중입니다. --- ## Skills **Core** -- Java 21, Spring Boot 4, Spring Security Resource Server, Spring Data JPA, PostgreSQL 16 +- Java 21, Spring Boot 4, Spring Security, Spring Data JPA, PostgreSQL **Architecture / Testing** -- Clean Architecture, Hexagonal Architecture, Gradle multi-project, ArchUnit, JUnit 5, AssertJ +- Clean Architecture, Gradle multi-module, ArchUnit, JUnit, Testcontainers, Flyway -**Auth / Observability** -- Keycloak, OAuth2 / OIDC, JWKS 기반 JWT 검증, Flyway, OpenAPI / Swagger UI, MDC `traceId` 기반 structured logging +**Auth / Performance** +- Keycloak, OAuth2 / OIDC, PKCE, JWT / JWKS, Redis, Hibernate Statistics, `EXPLAIN (ANALYZE, BUFFERS)` --- ## Projects -### Project-Auth-Server — Spring Boot 인증 서버 +### TechLog — 기술 학습 기록을 서비스로 연결한 프로젝트 -> 개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 설계 / 구현 / 로컬 검증 -> [github.com/donghyeon-ka/project-auth-server](https://github.com/donghyeon-ka/project-auth-server) +> 멘토링 기반 개인 프로젝트 · 약 6개월 · 1 인 · 설계 / 구현 / 검증 +> [hyeonworks.com](https://hyeonworks.com) -Spring Boot 인증 서버를 계층별 책임이 드러나도록 분리하고, 인증 위임 / JWT 검증 / 예외 응답 / DB 마이그레이션 경계를 정리한 프로젝트입니다. +인증, 성능, 아키텍처 과제를 진행하며 문서가 늘어났지만, 기록이 흩어져 **“왜 이런 결정을 했는지”를 다시 따라가기 어려운 문제**가 생겼습니다. 이를 해결하기 위해 Public / Studio 구조의 기술 기록 서비스를 만들었습니다. -- Gradle multi-project로 `domain` / `application` / `presentation` / `infrastructure` / `bootstrap` 5 개 모듈을 분리했습니다. -- `domain` 모듈은 Spring, JPA, Servlet 의존성을 두지 않고 값 객체와 도메인 규칙만 포함하도록 구성했습니다. -- ArchUnit의 `LayerDependencyArchitectureTest`로 `presentation → infrastructure` 같은 계층 위반을 빌드 단계에서 탐지하도록 했습니다. -- 로그인 플로우는 Keycloak / Ingress 계층에 위임하고, 백엔드는 `oauth2-resource-server`로 JWT issuer / signature / expiration / role claim을 다시 검증하도록 구성했습니다. -- `ErrorCode`는 비즈니스 의미만 담고, HTTP status 매핑은 presentation의 mapper가 담당하도록 분리했습니다. -- 예외 처리는 Security filter, Spring MVC 입력 검증, application, infrastructure 누수 감지로 나눴고, 응답은 `ApiResult` 형태로 통일했습니다. -- `TraceIdFilter`로 32 자리 hex `traceId`를 응답 헤더, 로그, audit 흐름에 동일하게 전파했습니다. -- Flyway V1~V5로 `auth` 스키마와 사용자 / provider 관련 변경을 단계별 마이그레이션으로 관리했습니다. +- 작성 흐름을 Create / Save / Validate / Preview / Publish 유스케이스로 분리하고 persistence / rendering 구현을 port 뒤로 분리했습니다. +- backend를 18개 Gradle module로 나누고, `modules.json`을 기준으로 허용 dependency와 runtime membership을 검증하도록 구성했습니다. +- Project / Topic / Release 관리 유스케이스를 application layer에 두어 JPA entity와 화면 DTO가 application 정책으로 직접 유출되지 않도록 분리했습니다. +- backend contract에는 값이 있지만 HTTP mapping 또는 frontend adapter에서 누락되어 화면이 비는 문제를 추적하고 contract / route / test gate를 보강했습니다. +- frontend도 `domain → application → adapter → presentation` 경계를 두고 HTTP / mock adapter를 교체할 수 있도록 구성했습니다. -`Java 21` `Spring Boot` `Spring Security` `Keycloak` `JPA` `PostgreSQL` `ArchUnit` `Flyway` +`Java 21` `Spring Boot` `JPA` `PostgreSQL` `Gradle` `ArchUnit` `React` `TypeScript` -### feed-postgresql-query-tuning — PostgreSQL 쿼리 최적화 +### Keycloak 인증 구조 — 브라우저와 서버의 credential 경계 비교 -> 개인 프로젝트 · 2025.03 ~ 2025.04 · 1 인 · 분석 / 최적화 / 검증 -> [github.com/donghyeon-ka/feed-postgresql-query-tuning](https://github.com/donghyeon-ka/feed-postgresql-query-tuning) +> 멘토링 과제 · 개인 lab · 설계 / 구현 / 검증 -피드 목록 조회 쿼리를 실행 계획 기준으로 분석하고, JOIN 구조와 인덱스 설계를 바꿔 성능을 개선한 프로젝트입니다. +같은 로그인 기능이라도 SPA, BFF, Forward-Auth에 따라 token과 session의 위치, API 호출 주체가 달라집니다. 구조 이름만 비교하지 않고 **credential이 실제로 어디에 머무는지**를 기준으로 네 가지 패턴을 구현했습니다. -- `EXPLAIN ANALYZE` 기준 피드 목록 조회 쿼리 실행 시간을 **1.77 s → 7.66 ms**로 개선했습니다. -- 4-table `LEFT JOIN`에 따른 row 폭증, 인덱스 미사용, 디스크 기반 외부 정렬을 병목으로 확인했습니다. -- `EXISTS` 서브쿼리, 페이지네이션 쿼리 분리, 복합 / 커버링 인덱스를 단계적으로 적용했습니다. -- 단일 인스턴스 환경에서 Locust 1,000 동시 사용자 시나리오를 실행해 약 **900~1,100 RPS** 구간을 확인했습니다. +- SPA / Token Mediator / BFF / Forward-Auth를 구현해 authorization code 교환 주체, refresh token 보관 위치, API caller를 비교했습니다. +- BFF에서는 브라우저 JavaScript에서 OAuth token을 제거하는 대신 server-side session, CSRF, session scale-out 문제가 새로 생기는 것을 확인했습니다. +- Forward-Auth에서는 edge가 만든 identity header를 신뢰하려면 header overwrite와 network isolation이 함께 필요하다는 점을 검증했습니다. +- 이후 2-node K3s 환경으로 확장해 Keycloak session의 실제 저장 위치를 확인했습니다. +- Keycloak 26 기본 `persistent-user-sessions` 조건에서 교차 노드 session 처리가 Infinispan 복제보다 **공유 PostgreSQL session 조회에 의존하는 경로**임을 SQL로 확인했습니다. -`PostgreSQL` `EXPLAIN ANALYZE` `Index design` `JPA` `Redis` `Locust` +`Keycloak` `OAuth2 / OIDC` `Spring Security` `PostgreSQL` `K3s` `Nginx` -### Project-Infra — Spring 앱 실행 환경 +### 피드 조회 성능 — N+1 이후의 조회 전략 비교 -> 개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 로컬 / dev 환경 구성 -> [github.com/donghyeon-ka/project-infra](https://github.com/donghyeon-ka/project-infra) +> 멘토링 과제 · PostgreSQL 16 Testcontainers 기반 측정 +> 아래 수치는 local / warm-cache 기준이며 운영 성능 수치가 아닙니다. -auth-server가 동작하는 로컬 / dev K3s 환경을 구성하면서 백엔드와 인프라의 인증 책임을 분리한 프로젝트입니다. +피드마다 최신 하이라이트와 공개 범위, pagination을 함께 처리하면서 N+1만 제거하면 끝나지 않는 문제를 확인했습니다. 쿼리 수, 반환 행, 인덱스, paging 비용을 분리해 비교했습니다. -- Traefik ForwardAuth + oauth2-proxy + Keycloak으로 로그인 / 세션 확인을 Ingress 계층에 두고, auth-server는 JWT 검증에 집중하도록 구성했습니다. -- Vault → VSO → Kubernetes Secret 흐름으로 secret 주입 책임을 애플리케이션 코드 밖으로 분리했습니다. -- Kustomize base / overlay 구조로 로컬과 dev 환경 차이를 manifest 단에서 관리했습니다. +- FeedItem 1,000개 조회에서 Hibernate Statistics 기준 PreparedStatement **2,022개**를 기준선으로 확인했습니다. +- fetch join에서 `MultipleBagFetchException`, row 증가, collection fetch + paging의 in-memory paging 문제를 재현했습니다. +- Batch Fetch 적용 후 같은 조건에서 PreparedStatement를 **2,022 → 23**으로 줄였습니다. +- 부모별 최신 3개 조회에서 Window Function / LATERAL / 2-step을 비교하고, 작은 K와 복합 인덱스 조건에서 LATERAL이 유리한 이유를 실행계획으로 확인했습니다. +- 2,000행의 깊은 페이지에서 OFFSET은 2,000행을 읽고 Keyset + 정렬키 index는 **20행**만 읽는 실행계획을 확인했습니다. -`Kubernetes` `K3s` `Kustomize` `Vault` `VSO` `Traefik` +`Spring Data JPA` `Hibernate` `PostgreSQL 16` `Testcontainers` `EXPLAIN ANALYZE` --- ## Links +- **TechLog**: [hyeonworks.com](https://hyeonworks.com) - **GitHub**: [github.com/donghyeon-ka](https://github.com/donghyeon-ka) -- **메인 프로젝트**: [project-auth-server](https://github.com/donghyeon-ka/project-auth-server) -- **인프라**: [project-infra](https://github.com/donghyeon-ka/project-infra) -- **쿼리 튜닝**: [feed-postgresql-query-tuning](https://github.com/donghyeon-ka/feed-postgresql-query-tuning) - **Blog**: [velog.io/@donghyeon2](https://velog.io/@donghyeon2) diff --git a/01-java-spring-backend.md b/01-java-spring-backend.md deleted file mode 100644 index 827da2f..0000000 --- a/01-java-spring-backend.md +++ /dev/null @@ -1,94 +0,0 @@ -# 강동현 · 백엔드 신입 (Java / Spring) - -| | | -|---|---| -| Email | donghyeonka68@gmail.com | -| GitHub | [github.com/donghyeon-ka](https://github.com/donghyeon-ka) | -| Velog | [velog.io/@donghyeon2](https://velog.io/@donghyeon2) | - ---- - -## Summary - -Java / Spring Boot 기반 백엔드 개발을 중심으로 학습하며, 인증 서버의 레이어 구조, 예외 응답 표준, 인증 위임 구조를 직접 구현해 온 신입 백엔드 개발자입니다. - -Spring Security Resource Server 와 Keycloak JWT 검증 구조를 구성했고, Clean / Hexagonal Architecture 5 개 모듈과 ArchUnit 테스트로 계층 의존성을 검증했습니다. - -프로젝트는 모두 개인 로컬 / dev 환경 기준이며, 구현 범위와 검증 범위를 구분해 문서화했습니다. - ---- - -## Skills - -**Main** -- Java 21, Spring Boot 4.0.3, Spring Security Resource Server, JPA, PostgreSQL 16 - -**Used in Projects** -- Keycloak, OAuth2 / OIDC, Nimbus JWT (JWKS), Flyway, ArchUnit, JUnit 5, AssertJ, OpenAPI / Swagger UI, MDC `traceId` 기반 structured logging - -**Infrastructure (보조)** -- Docker, K3s, Kustomize, Vault, VSO, Traefik - ---- - -## Projects - -### Project-Auth-Server — Spring Boot 인증 서버 (Clean / Hexagonal) - -> 개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 설계 / 구현 / 로컬 검증 -> [github.com/donghyeon-ka/project-auth-server](https://github.com/donghyeon-ka/project-auth-server) - -Spring Boot 인증 서버를 Clean / Hexagonal Architecture 로 분리하고, Keycloak JWT 를 Resource Server 로 검증하는 구조를 구현한 프로젝트입니다. - -- **5 모듈 Clean / Hexagonal Architecture** — `domain` / `application` / `presentation` / `infrastructure` / `bootstrap` 로 Gradle multi-project 분리. `domain` 은 Spring / JPA / Servlet 의존 0 -- **ArchUnit 으로 레이어 의존성 검증** — `LayerDependencyArchitectureTest` 가 빌드 단계에서 `presentation → infrastructure` 같은 위반을 검출. CI 연결 시 PR 게이트로 활용 가능한 구조 -- **`ErrorCode` 와 HTTP status 분리** — `BusinessException` 의 `ErrorCode` 는 비즈니스 의미만 (code + message), HTTP status 매핑은 presentation 의 `ApiErrorHttpStatusMapper` 가 담당 -- **Spring Security Resource Server + Keycloak** — `oauth2-client` 가 아니라 `oauth2-resource-server` 만 사용. Keycloak 발급 JWT 의 issuer / signature / expiration / role claim 을 백엔드에서 다시 검증 -- **Exception Handler 4 계층 분리** — 필터 단 (`SecurityExceptionHandler`) / Spring MVC 입력단 / application / infrastructure 누수 감지. 모든 응답은 `ApiResult` (success · code · message · data · traceId · timestamp) 로 통일 -- **MDC `traceId` 일관성 + Flyway 마이그레이션 관리** — `TraceIdFilter` 가 32 자리 hex traceId 를 응답 헤더 / 로그 / audit 에 동일하게 전파. `auth` schema 의 V1~V5 SQL migration 을 infrastructure 모듈에서 관리 - -`Java 21` `Spring Boot 4.0.3` `Spring Security` `JPA` `PostgreSQL` `Keycloak` `ArchUnit` `Flyway` - -### feed-postgresql-query-tuning — PostgreSQL 쿼리 튜닝 프로젝트 - -> 개인 프로젝트 · 2025.03 ~ 2025.04 · 1 인 · 분석 / 최적화 / 검증 (수치는 모두 EXPLAIN ANALYZE 기준 쿼리 실행 시간) -> [github.com/donghyeon-ka/feed-postgresql-query-tuning](https://github.com/donghyeon-ka/feed-postgresql-query-tuning) - -피드 목록 조회 쿼리를 EXPLAIN ANALYZE 기준으로 분석하고, JOIN 구조 / 인덱스 설계 / 캐시 / 부하 검증 순으로 단계적으로 개선한 프로젝트입니다. - -- 피드 목록 조회 쿼리 응답 시간 **1.77 초 → 7.66 ms** (단계적 개선 결과, EXPLAIN ANALYZE 기준) -- **원인 분석** — 4-table LEFT JOIN 데이터 폭증 + 인덱스 미사용 + 외부 정렬 발생 확인 -- **1 차 개선** — 불필요한 JOIN 을 EXISTS 서브쿼리로 교체 + 쿼리 분리 → 1.77 초 → 0.216 초 -- **2 차 개선** — 복합 인덱스 + 커버링 인덱스 → 0.216 초 → 7.66 ms -- **JPA 측면** — N+1 회피, fetch 전략 명시 (LAZY + 필요 시 명시적 join fetch) -- **부하 검증** — 단일 인스턴스 환경에서 Locust 동시 1,000 명 부하 → 900~1,100 RPS - -`PostgreSQL` `JPA` `EXPLAIN ANALYZE` `Index design` `Redis` `Locust` - -### Project-Infra — Spring 앱 실행 환경 구성 - -> 개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 로컬 / dev 환경 구성 -> [github.com/donghyeon-ka/project-infra](https://github.com/donghyeon-ka/project-infra) - -auth-server 가 동작하는 로컬 / dev K3s 환경을 Kustomize overlay 로 구성하고, Ingress 인증 게이트와 시크릿 주입 흐름을 함께 설계한 프로젝트입니다. - -- auth-server 가 동작하는 로컬 / dev K3s 실행 환경을 Kustomize overlay 로 구성 -- Traefik ForwardAuth + oauth2-proxy + Keycloak 으로 로그인 / 세션 확인 경계를 분리하고, auth-server 는 JWT 검증에 집중하도록 구성 -- Vault → VSO → Kubernetes Secret 흐름으로 secret 주입 구조 구성 - -`Kubernetes (K3s)` `Kustomize` `Vault` `VSO` `Traefik` - ---- - -## Blog - -- [Velog @donghyeon2](https://velog.io/@donghyeon2) — 기술적 의사결정 과정과 트러블슈팅 경험 기록 - ---- - -## Links - -- **GitHub**: [github.com/donghyeon-ka](https://github.com/donghyeon-ka) -- **인증 서버 (메인)**: [project-auth-server](https://github.com/donghyeon-ka/project-auth-server) -- **인프라**: [project-infra](https://github.com/donghyeon-ka/project-infra) -- **쿼리 튜닝**: [feed-postgresql-query-tuning](https://github.com/donghyeon-ka/feed-postgresql-query-tuning) diff --git a/02-platform-devops-backend.feat.google-version.md b/02-platform-devops-backend.feat.google-version.md index bc0c8e6..bd35fd9 100644 --- a/02-platform-devops-backend.feat.google-version.md +++ b/02-platform-devops-backend.feat.google-version.md @@ -4,86 +4,83 @@ |---|---| | 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) | --- ## Summary -Spring Boot 애플리케이션이 실제로 실행되는 환경까지 이해하려고, K3s 기반 로컬 / dev 플랫폼을 직접 구성해 온 신입 백엔드 개발자입니다. +Spring Boot 애플리케이션이 실제로 실행되는 경로까지 이해하기 위해 K3s, Nginx, Traefik, Keycloak, Vault를 직접 구성해 온 신입 백엔드 개발자입니다. -Ingress 인증 게이트, Vault 기반 secret 주입, default-deny NetworkPolicy, PSS Restricted baseline을 함께 구성하며 애플리케이션 코드 밖의 책임을 명확히 나누는 데 집중했습니다. 백엔드는 JWT 검증과 도메인 처리에 집중하고, 로그인 / 세션 / secret / 네트워크 경계는 플랫폼 계층에서 다루도록 설계했습니다. +물리 서버 host에 설정을 하나씩 추가하다 보니 TLS 종료 위치, proxy 신뢰 범위, secret과 session의 저장 위치를 설명하기 어려워졌습니다. 이를 정리하기 위해 **외부 요청이 Nginx를 거쳐 Kubernetes Service까지 도달하는 경로와 각 컴포넌트의 책임을 분리**했습니다. -아래 내용은 운영 경험이 아니라 로컬 / dev 환경에서 실행 구조를 검증한 결과입니다. 대신 각 결정이 어떤 책임을 분리하기 위한 것인지 드러나도록 정리했습니다. +모든 내용은 개인 home lab / dev 환경에서 검증한 결과이며 운영 경험으로 확대해 표현하지 않았습니다. 현재 [hyeonworks.com](https://hyeonworks.com)에서 TechLog frontend를 서비스하고 있으며, backend와 플랫폼의 최종 통합은 진행 중입니다. --- ## Skills **Core** -- Kubernetes (K3s 1.30), Kustomize, Traefik, NetworkPolicy default-deny, PSS Restricted +- Kubernetes / K3s, Nginx, Traefik, Kustomize, Helm / HelmChartConfig, NetworkPolicy -**Secrets / Auth Gateway** -- HashiCorp Vault 1.17.2, Vault Secrets Operator, Keycloak, oauth2-proxy, Traefik ForwardAuth, HelmChartConfig +**Secrets / Identity** +- HashiCorp Vault 1.17.2, Vault Secrets Operator, Keycloak, oauth2-proxy, Kubernetes Auth -**Validation / Backend** -- `kustomize build`, `kubeconform -strict`, `kube-linter`, Java 21, Spring Boot 4, Spring Security Resource Server, PostgreSQL, Flyway +**Data / Observability** +- PostgreSQL / CloudNativePG, Redis, Prometheus, Grafana, Loki, Tempo, Blackbox Exporter --- ## Projects -### Project-Infra — Kubernetes 기반 백엔드 실행 환경 +### Home Platform — K3s 기반 서비스 실행 환경 -> 개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 설계 / 구현 / 로컬 검증 -> [github.com/donghyeon-ka/project-infra](https://github.com/donghyeon-ka/project-infra) +> 멘토링 기반 개인 프로젝트 · home lab / dev +> [hyeonworks.com](https://hyeonworks.com) -Spring Boot 인증 서버가 동작하는 K3s 환경을 구성하고, 인증 게이트 / secret 주입 / 네트워크 정책 / manifest 검증 책임을 분리한 프로젝트입니다. +서비스를 하나씩 올리면서 host와 cluster의 책임이 섞이기 시작했습니다. 단순히 “접속된다”가 아니라 **요청이 어떤 신뢰 경계를 지나 Pod까지 도달하는지 설명할 수 있는 구조**로 다시 구성했습니다. -- Traefik ForwardAuth + oauth2-proxy + Keycloak 조합으로 미인증 요청을 Ingress 계층에서 먼저 차단하도록 구성했습니다. -- auth-server는 Ingress 뒤에서 Keycloak JWT를 Resource Server로 다시 검증하게 하여, 로그인 세션 처리와 API 권한 검증을 분리했습니다. -- Vault KV-v2 값을 VSO가 Kubernetes Secret으로 동기화하도록 구성하고, 도메인별 Vault role / policy를 나눠 secret 접근 범위를 제한했습니다. -- default-deny NetworkPolicy를 기본값으로 두고, 필요한 컴포넌트 간 통신만 명시적으로 허용했습니다. -- K3s packaged Traefik manifest를 직접 수정하지 않고 `HelmChartConfig` overlay로 설정을 관리해, 재부팅 시 설정이 사라지는 문제를 피했습니다. -- PSS Restricted baseline을 유지하기 위해 Vault의 `disable_mlock` 설정을 선택했고, 그에 따른 swap-off 운영 전제를 명시했습니다. -- 주요 overlay에 대해 `kustomize build`, `kubeconform -strict`, `kube-linter` 검증을 실행하는 스크립트를 구성했습니다. -- MinIO Operator 설치, namespace / PSS 라벨 적용, Vault init / unseal, VSO 설치 흐름을 반복 실행 가능한 bootstrap script로 분리했습니다. +- 외부 HTTPS를 Host Nginx에서 종료하고 Traefik NodePort를 loopback에만 열어 `Internet → Nginx → 127.0.0.1 NodePort → Traefik → Service` 경로로 진입점을 제한했습니다. +- 외부가 보낸 `X-Forwarded-*`를 Nginx에서 다시 쓰고, Traefik은 실제 proxy source만 신뢰하도록 범위를 줄였습니다. +- 공개 서비스와 관리용 hostname을 분리하고 관리 경로에는 LAN / Tailscale source allowlist를 적용했습니다. +- CloudNativePG / PostgreSQL, Keycloak, workload별 Local PV를 구성하고 서비스별 DB / role / Secret / NetworkPolicy를 분리했습니다. +- Prometheus / Grafana / Loki / Tempo / Blackbox Exporter를 구성해 endpoint, node, log, trace, 인증서 상태를 각각 관측했습니다. +- manifest에 선언된 설정과 live cluster에서 실제 집행되는 상태를 대조해, 선언만 존재하는 항목을 완료로 판단하지 않도록 검증했습니다. -`Kubernetes` `K3s` `Kustomize` `Traefik` `oauth2-proxy` `Keycloak` `Vault` `VSO` `NetworkPolicy` `PSS` +`K3s` `Nginx` `Traefik` `Kustomize` `CloudNativePG` `Prometheus` `Grafana` -### Project-Auth-Server — 플랫폼 뒤에서 동작하는 Spring Boot 백엔드 +### Vault Secret Delivery — 애플리케이션 밖으로 secret 책임 분리 -> 개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 설계 / 구현 / 로컬 검증 -> [github.com/donghyeon-ka/project-auth-server](https://github.com/donghyeon-ka/project-auth-server) +> 개인 lab · 현재 Vault는 single replica / file storage 구성 -플랫폼 계층이 로그인 / 세션을 처리하고, 백엔드는 Resource Server로 JWT를 검증하는 구조의 Spring Boot 인증 서버입니다. +Secret 값을 Git에서 제거하는 것만으로는 누가 Vault에 접근하고, workload가 어떤 credential을 받는지 해결되지 않았습니다. 애플리케이션이 Vault API를 직접 알지 않도록 secret 전달 경계를 분리했습니다. -- `oauth2-client`가 아니라 `oauth2-resource-server`를 사용해 백엔드 책임을 JWT 검증과 권한 매핑으로 좁혔습니다. -- Clean / Hexagonal 5 개 모듈 구조와 ArchUnit 테스트로 계층 의존성 위반을 빌드 단계에서 탐지하도록 했습니다. -- application 코드가 HTTP status 같은 web 프로토콜 세부사항을 직접 알지 않도록 `ErrorCode`와 HTTP status 매핑을 분리했습니다. -- K8s 환경에서는 공식 `flyway/flyway` 이미지를 initContainer로 실행해, 자체 migration 이미지 빌드 사이클을 줄였습니다. +- Vault KV-v2를 source of truth로 두고 **Vault → VSO → Kubernetes Secret → workload** 흐름으로 구성했습니다. +- `VaultConnection` / `VaultAuth`와 Kubernetes Auth를 사용하고 role / policy를 경로별로 분리했습니다. +- VSO controller → Vault init / unseal → auth / policy → KV seed → destination Secret → workload 순으로 bootstrap dependency를 정리했습니다. +- 실행 중 생성되는 registry credential은 생성 후 Vault에 기록하고 consumer가 VSO를 통해 다시 받도록 흐름을 분리했습니다. +- 현재 구성은 Vault 1 replica / file storage / local-path PVC 기준이며 Raft HA, auto-unseal 운영 경험으로 표현하지 않았습니다. -`Java 21` `Spring Boot` `Spring Security` `Keycloak` `JPA` `Flyway` `ArchUnit` +`Vault 1.17.2` `Vault Secrets Operator` `Kubernetes Auth` `Kustomize` -### feed-postgresql-query-tuning — PostgreSQL 성능 검증 +### Keycloak Multi-node — session과 장애의 실제 위치 확인 -> 개인 프로젝트 · 2025.03 ~ 2025.04 · 1 인 · 분석 / 최적화 / 검증 -> [github.com/donghyeon-ka/feed-postgresql-query-tuning](https://github.com/donghyeon-ka/feed-postgresql-query-tuning) +> 개인 lab · VM 2대 / 2-node K3s -플랫폼 관점에서도 애플리케이션 병목을 관찰할 수 있도록, DB 쿼리 실행 계획과 부하 테스트를 함께 정리한 프로젝트입니다. +Keycloak replica를 늘리면 session이 자동으로 공유된다고 보기 쉬웠습니다. 이를 확인하기 위해 두 VM에 Keycloak을 나눠 배치하고 DB, cache, network 조건을 바꿔가며 상태의 실제 위치를 확인했습니다. -- `EXPLAIN ANALYZE` 기준 피드 목록 조회 쿼리 실행 시간을 **1.77 s → 7.66 ms**로 개선했습니다. -- JOIN 구조 변경, 페이지네이션 쿼리 분리, 복합 / 커버링 인덱스 적용을 단계적으로 검증했습니다. -- 단일 인스턴스 Locust 1,000 동시 사용자 시나리오에서 약 **900~1,100 RPS** 구간을 확인했습니다. +- Keycloak 26 기본 `persistent-user-sessions`에서 교차 노드 session 처리가 **공유 PostgreSQL session 조회에 의존**하는 것을 SQL로 확인했습니다. +- persistent session을 끈 조건에서는 JGroups 연결, rolling restart, DB 상태가 결과에 미치는 영향이 달라지는 것을 비교했습니다. +- NetworkPolicy, iptables, `tc`를 적용했다고 바로 장애로 판단하지 않고 conntrack / packet counter / cluster state로 **장애 주입 자체가 성공했는지 먼저 검증**했습니다. +- Refresh Token Rotation 동시 경쟁과 replica별 JWKS cache 차이처럼 단일 인스턴스에서는 드러나지 않는 상태 경쟁도 확인했습니다. -`PostgreSQL` `EXPLAIN ANALYZE` `Index design` `Redis` `Locust` +`K3s` `Keycloak` `PostgreSQL` `Redis` `JGroups` `Linux networking` --- ## Links +- **TechLog**: [hyeonworks.com](https://hyeonworks.com) - **GitHub**: [github.com/donghyeon-ka](https://github.com/donghyeon-ka) -- **메인 프로젝트**: [project-infra](https://github.com/donghyeon-ka/project-infra) -- **인증 서버**: [project-auth-server](https://github.com/donghyeon-ka/project-auth-server) -- **쿼리 튜닝**: [feed-postgresql-query-tuning](https://github.com/donghyeon-ka/feed-postgresql-query-tuning) - **Blog**: [velog.io/@donghyeon2](https://velog.io/@donghyeon2) diff --git a/02-platform-devops-backend.md b/02-platform-devops-backend.md deleted file mode 100644 index 0ef942e..0000000 --- a/02-platform-devops-backend.md +++ /dev/null @@ -1,96 +0,0 @@ -# 강동현 · 백엔드 신입 (플랫폼 / DevOps 친화) - -| | | -|---|---| -| Email | donghyeonka68@gmail.com | -| GitHub | [github.com/donghyeon-ka](https://github.com/donghyeon-ka) | -| Velog | [velog.io/@donghyeon2](https://velog.io/@donghyeon2) | - ---- - -## Summary - -Spring Boot 인증 서버가 동작하는 Kubernetes 실행 환경 전체를 Kustomize 로 직접 구성해 온 신입 백엔드 개발자입니다. - -Ingress 단 (Traefik ForwardAuth + oauth2-proxy + Keycloak) 으로 인증 게이트를 분리하고, 시크릿은 Vault → VSO → K8s Secret 자동 동기화 파이프라인으로 분리했으며, default-deny NetworkPolicy 와 PSS Restricted 를 클러스터 baseline 으로 두었습니다. - -프로젝트 범위는 로컬 / dev 환경 기준이며, 실제 운영 경험이 아닌 실행 구조 검증과 문서화에 초점을 두었습니다. - ---- - -## Skills - -**Main** -- Kubernetes (K3s 1.30), Kustomize (base / components / overlays), Traefik, NetworkPolicy default-deny, PSS Restricted enforce - -**Used in Projects** -- HashiCorp Vault 1.17.2, Vault Secrets Operator (VaultStaticSecret / VaultAuth / VaultConnection), Keycloak, oauth2-proxy, Helm (HelmChartConfig), Middleware (security-headers / TLSOption) - -**Manifest / 검증** -- Kustomize overlay 분리, `kustomize build` / `kubeconform -strict` / `kube-linter` 3 단 검증 스크립트, idempotent shell script 부트스트랩 - -**Backend (보조)** -- Java 21, Spring Boot 4, Spring Security Resource Server, JPA, PostgreSQL, Flyway - ---- - -## Projects - -### Project-Infra — Kubernetes 기반 백엔드 실행 환경 구성 - -> 개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 설계 / 구현 / 로컬 검증 -> [github.com/donghyeon-ka/project-infra](https://github.com/donghyeon-ka/project-infra) - -Spring Boot 인증 서버가 동작하는 Kubernetes 실행 환경 전체를 Kustomize 로 구성하고, Ingress 인증 게이트 / Vault 시크릿 파이프라인 / NetworkPolicy 베이스라인을 함께 설계한 프로젝트입니다. - -- **Ingress 단 인증 차단 구조** — Traefik ForwardAuth + oauth2-proxy + Keycloak 조합으로 미인증 요청을 게이트에서 차단하는 구조를 구성. 백엔드 (auth-server) 는 그 뒤에서 Keycloak JWT 를 Resource Server 로 다시 검증하는 *이중 경계* 로 분리 -- **Vault + VSO 시크릿 파이프라인** — Vault KV-v2 값을 K8s Secret 으로 자동 동기화. 도메인별 Vault role / policy 를 분리 (`vso-auth-platform` / `vso-storage`) 해 auth-platform 권한으로 storage secret 경로에 접근하지 못하도록 제한 -- **default-deny NetworkPolicy 베이스라인** — 단일 namespace 안에서도 모든 Pod 간 트래픽을 기본 차단 후 컴포넌트별 명시 허용. `namespaceSelector` + `podSelector` 를 한 블록에 묶어 AND 시맨틱 작성 -- **K3s packaged Traefik 무수정 정책** — K3s 가 재부팅 시 덮어쓰는 packaged manifest 에 손대지 않고 `HelmChartConfig` overlay 로만 운영 설정 관리 → 정책이 Git 에서 사라지지 않음 -- **PSS Restricted enforce + Vault `disable_mlock` 트레이드오프** — 클러스터 baseline 을 깎지 않기 위해 Vault 한 컴포넌트에서 트레이드오프 (대신 swap-off 노드 운영 명시) -- **3 단 검증 스크립트 구성** — `validate.sh` 가 주요 overlay 에 대해 `kustomize build` / `kubeconform -strict` / `kube-linter` 검증을 수행하도록 구성 -- **부트스트랩 스크립트 구성** — MinIO Operator 설치, namespace / PSS 라벨 적용, Vault init · unseal, VSO Helm 설치, CRD 적용 흐름을 idempotent shell script 로 분리 - -`Kubernetes (K3s)` `Kustomize` `Traefik` `oauth2-proxy` `Keycloak` `Vault` `VSO` `NetworkPolicy` `PSS` - -### Project-Auth-Server — 인프라가 보호하는 백엔드 (Spring Boot) - -> 개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 설계 / 구현 / 로컬 검증 -> [github.com/donghyeon-ka/project-auth-server](https://github.com/donghyeon-ka/project-auth-server) - -Ingress 단의 oauth2-proxy + Keycloak 이 로그인 / 세션을 처리하고, 백엔드는 Resource Server 로서 JWT 를 다시 검증하는 구조의 Spring Boot 인증 서버입니다. - -- **Resource Server 단순화** — `oauth2-client` 가 아니라 `oauth2-resource-server` 만 사용. 로그인 플로우는 인프라가 처리하고 백엔드는 JWT 검증과 권한 매핑에 집중 -- **Clean / Hexagonal 5 모듈 + ArchUnit** — 레이어 의존성 위반을 빌드 단계에서 자동 차단. CI 연결 시 PR 게이트 활용 가능 -- **`ErrorCode` 와 HTTP status 분리** — application 코드가 web 프로토콜에 누설되지 않도록 분리 -- **Flyway V1~V5 마이그레이션** — K8s 에서는 공식 `flyway/flyway` 이미지를 initContainer 로 실행 (자체 migration 이미지 빌드 사이클 제거) - -`Java 21` `Spring Boot 4` `Spring Security` `Keycloak` `JPA` `Flyway` - -### feed-postgresql-query-tuning — PostgreSQL 쿼리 튜닝 프로젝트 - -> 개인 프로젝트 · 2025.03 ~ 2025.04 · 1 인 · 분석 / 최적화 / 검증 -> [github.com/donghyeon-ka/feed-postgresql-query-tuning](https://github.com/donghyeon-ka/feed-postgresql-query-tuning) - -피드 목록 조회 쿼리를 EXPLAIN ANALYZE 기준으로 분석해 응답 시간을 단계적으로 개선한 프로젝트입니다. - -- 피드 목록 조회 쿼리 응답 시간 **1.77 초 → 7.66 ms** 단축 (EXPLAIN ANALYZE 기준 쿼리 실행 시간) -- 4-table LEFT JOIN 분석 → EXISTS 서브쿼리 + 쿼리 분리 → 복합/커버링 인덱스 단계적 적용 -- 단일 인스턴스 환경 Locust 부하 검증 (1,000 동시 사용자 → 900~1,100 RPS) - -`PostgreSQL` `JPA` `EXPLAIN ANALYZE` `Index design` `Redis` `Locust` - ---- - -## Blog - -- [Velog @donghyeon2](https://velog.io/@donghyeon2) — 기술적 의사결정 과정과 트러블슈팅 경험 기록 - ---- - -## Links - -- **GitHub**: [github.com/donghyeon-ka](https://github.com/donghyeon-ka) -- **인프라 (메인)**: [project-infra](https://github.com/donghyeon-ka/project-infra) -- **인증 서버**: [project-auth-server](https://github.com/donghyeon-ka/project-auth-server) -- **쿼리 튜닝**: [feed-postgresql-query-tuning](https://github.com/donghyeon-ka/feed-postgresql-query-tuning) diff --git a/03-performance-db.feat.google-version.md b/03-performance-db.feat.google-version.md deleted file mode 100644 index 2d8f412..0000000 --- a/03-performance-db.feat.google-version.md +++ /dev/null @@ -1,88 +0,0 @@ -# 강동현 · 백엔드 신입 (성능 / DB) - -| | | -|---|---| -| Email | donghyeonka68@gmail.com | -| GitHub | [github.com/donghyeon-ka](https://github.com/donghyeon-ka) | -| Blog | [velog.io/@donghyeon2](https://velog.io/@donghyeon2) | - ---- - -## Summary - -DB 기반 백엔드 시스템에서 쿼리 실행 계획, 인덱스 설계, 애플리케이션과 인프라의 책임 경계에 관심을 두고 학습해 온 신입 백엔드 개발자입니다. - -PostgreSQL 피드 조회 튜닝 프로젝트에서 `EXPLAIN ANALYZE`로 병목을 확인하고, JOIN 구조 / 페이지네이션 흐름 / 인덱스 설계를 바꿔 쿼리 실행 시간을 **1.77 s → 7.66 ms**로 줄였습니다. 이후 Redis 캐시와 Locust 부하 테스트로 개선 경로를 검증했습니다. - -아래 성능 수치는 모두 로컬 실험 또는 단일 인스턴스 부하 테스트 기준입니다. 운영 경험처럼 과장하지 않기 위해 측정 범위를 명시했습니다. - ---- - -## Skills - -**Core** -- Java 21, Spring Boot 4, Spring Data JPA, PostgreSQL 16, Redis - -**Database / Performance** -- `EXPLAIN ANALYZE`, 복합 인덱스, 커버링 인덱스, 페이지네이션 쿼리 설계, N+1 회피, p50 / p95 / p99 latency 측정 - -**Supporting** -- Flyway, ArchUnit, Locust, Kubernetes (K3s), Kustomize, Traefik, Vault - ---- - -## Projects - -### feed-postgresql-query-tuning — PostgreSQL 쿼리 최적화 - -> 개인 프로젝트 · 2025.03 ~ 2025.04 · 1 인 · 분석 / 구현 / 검증 -> [github.com/donghyeon-ka/feed-postgresql-query-tuning](https://github.com/donghyeon-ka/feed-postgresql-query-tuning) - -피드 목록 조회 쿼리를 실행 계획 기준으로 분석하고, 실제 접근 패턴에 맞춰 쿼리 책임과 인덱스 구조를 다시 설계한 프로젝트입니다. - -- `EXPLAIN ANALYZE` 기준 피드 목록 조회 쿼리 실행 시간을 **1.77 s → 7.66 ms**로 개선했습니다. -- 주요 병목으로 4-table `LEFT JOIN`에 따른 row 폭증, 사용 가능한 인덱스 부재로 인한 sequential scan, 디스크 기반 외부 정렬(`Sort Method: external merge Disk`)을 확인했습니다. -- 불필요한 `LEFT JOIN`을 `EXISTS` 서브쿼리로 바꾸고, 페이지네이션과 상세 로딩 책임을 분리해 실행 시간을 **1.77 s → 0.216 s**로 줄였습니다. -- WHERE 조건과 정렬 키를 함께 고려한 복합 인덱스, 자주 조회되는 컬럼을 포함한 커버링 인덱스를 적용해 **0.216 s → 7.66 ms**까지 줄였습니다. -- 공개 피드에는 Redis 2 단계 캐시를 적용하고 private 피드는 캐시를 우회하도록 분리했습니다. 테스트 구간에서 약 **90% cache hit rate**를 관찰했습니다. -- 단일 인스턴스 환경에서 Locust 1,000 동시 사용자 시나리오를 실행해 약 **900~1,100 RPS** 구간을 확인했습니다. -- JPA 측면에서는 N+1을 피하고, 기본 LAZY 로딩과 필요한 지점의 명시적 fetch join을 분리했으며, `Page` 응답의 count 쿼리를 별도로 다뤘습니다. - -`PostgreSQL` `EXPLAIN ANALYZE` `Index design` `JPA` `Redis` `Locust` `Spring Boot` - -### Project-Auth-Server — Spring Boot 인증 서버의 DB 책임 경계 - -> 개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 설계 / 구현 / 로컬 검증 -> [github.com/donghyeon-ka/project-auth-server](https://github.com/donghyeon-ka/project-auth-server) - -Spring Boot 인증 서버에서 도메인 규칙, 영속성 매핑, 트랜잭션 소유권을 분리해 구현한 프로젝트입니다. - -- Flyway V1~V5로 PostgreSQL 스키마 변경을 관리하고, `auth` 스키마 생성 / 사용자 도메인 테이블 / Keycloak provider 컬럼 추가를 단계별로 분리했습니다. -- 트랜잭션 소유권을 application use case로 이동시켜 infrastructure adapter가 비즈니스 트랜잭션 범위를 결정하지 않도록 정리했습니다. -- 저장된 row를 도메인 객체로 복원하는 과정에서 잘못된 데이터가 발견되면 일반 도메인 검증 실패가 아니라 인프라 무결성 문제로 번역했습니다. -- DB row와 `UserEmail`, `UserName`, `User` 같은 도메인 값 객체를 분리해 JPA entity 관심사 밖에서 invariant를 검증했습니다. - -`Java 21` `Spring Boot` `PostgreSQL` `JPA` `Flyway` `ArchUnit` - -### Project-Infra — 저장소와 배포 책임 분리 - -> 개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 로컬 / dev 환경 구성 -> [github.com/donghyeon-ka/project-infra](https://github.com/donghyeon-ka/project-infra) - -auth-server 실행 환경을 K3s 위에 구성하면서 데이터 저장소와 배포 단계의 책임을 분리한 프로젝트입니다. - -- 애플리케이션 row 데이터는 PostgreSQL, object storage는 MinIO, Docker Registry 저장소는 MinIO S3 backend로 분리했습니다. -- Flyway 마이그레이션 실행을 애플리케이션 시작과 분리해, 스키마 변경이 앱 배포보다 먼저 실행될 수 있도록 구성했습니다. -- 외부 image push 인증은 Traefik BasicAuth, 내부 image pull은 Kubernetes `imagePullSecret`으로 나눠 인증 경계를 분리했습니다. - -`Kubernetes` `K3s` `PostgreSQL` `MinIO` `Docker Registry` `Flyway` `Kustomize` - ---- - -## Links - -- **GitHub**: [github.com/donghyeon-ka](https://github.com/donghyeon-ka) -- **메인 프로젝트**: [feed-postgresql-query-tuning](https://github.com/donghyeon-ka/feed-postgresql-query-tuning) -- **인증 서버**: [project-auth-server](https://github.com/donghyeon-ka/project-auth-server) -- **인프라**: [project-infra](https://github.com/donghyeon-ka/project-infra) -- **Blog**: [velog.io/@donghyeon2](https://velog.io/@donghyeon2) diff --git a/03-performance-db.md b/03-performance-db.md deleted file mode 100644 index 94463bc..0000000 --- a/03-performance-db.md +++ /dev/null @@ -1,94 +0,0 @@ -# 강동현 · 백엔드 신입 (성능 / DB) - -| | | -|---|---| -| Email | donghyeonka68@gmail.com | -| GitHub | [github.com/donghyeon-ka](https://github.com/donghyeon-ka) | -| Velog | [velog.io/@donghyeon2](https://velog.io/@donghyeon2) | - ---- - -## Summary - -PostgreSQL 쿼리 분석과 인덱스 설계에 관심을 두고, 피드 목록 조회 쿼리를 EXPLAIN ANALYZE 기준으로 분석해 1.77 초 → 7.66 ms 까지 단계적으로 개선한 경험이 있는 신입 백엔드 개발자입니다. - -Redis 2 단계 캐시와 Locust 부하 테스트로 검증 흐름을 정리했고, JPA fetch 전략 / Flyway 마이그레이션 / 트랜잭션 위치 등 데이터 레이어 책임 경계도 함께 정리했습니다. - -모든 성능 수치는 로컬 실험 및 단일 인스턴스 부하 테스트 기준으로 정리했습니다. - ---- - -## Skills - -**Main** -- PostgreSQL 16, EXPLAIN ANALYZE, 복합 / 커버링 인덱스 설계, Redis, Locust - -**Used in Projects** -- Spring Data JPA (fetch 전략, N+1 회피), Flyway (V1~V5), 외부 정렬 / Bitmap Heap Scan / Hash Join 분석, p50 / p95 / p99 latency 측정 - -**Backend (보조)** -- Java 21, Spring Boot 4, Spring Security Resource Server, ArchUnit - ---- - -## Projects - -### feed-postgresql-query-tuning — PostgreSQL 쿼리 튜닝 - -> 개인 프로젝트 · 2025.03 ~ 2025.04 · 1 인 · 분석 / 최적화 / 검증 -> 모든 수치는 EXPLAIN ANALYZE 기준 쿼리 실행 시간 -> [github.com/donghyeon-ka/feed-postgresql-query-tuning](https://github.com/donghyeon-ka/feed-postgresql-query-tuning) - -피드 목록 조회 쿼리를 EXPLAIN ANALYZE 기준으로 분석하고, JOIN 구조 / 인덱스 설계 / 캐시 전략 / 부하 검증 순으로 단계적으로 개선한 프로젝트입니다. - -- 피드 목록 조회 쿼리 응답 시간 **1.77 초 → 7.66 ms** 까지 단계적으로 개선 -- **원인 분석** (EXPLAIN ANALYZE) — 4-table LEFT JOIN 으로 인한 데이터 폭증, 인덱스 미사용으로 인한 sequential scan, 디스크 기반 외부 정렬 (`Sort Method: external merge Disk`) 발생 확인 -- **1 차 개선** — 불필요한 LEFT JOIN 을 `EXISTS` 서브쿼리로 교체 + 페이지네이션 쿼리 분리 → **1.77 초 → 0.216 초** (8 배) -- **2 차 개선** — 정렬 키 + WHERE 절 컬럼을 합친 복합 인덱스 + 자주 SELECT 되는 컬럼 포함 커버링 인덱스 → **0.216 초 → 7.66 ms** (28 배). 인덱스 기반 조회로 디스크 접근과 정렬 비용을 줄임 -- **캐시 전략** — Redis 2 단계 캐시 (공개 피드만 캐시, private 피드는 우회) 도입. 부하 테스트 구간에서 캐시 히트율 약 **90%** 관찰 -- **부하 검증** — 단일 인스턴스 환경에서 Locust 로 동시 1,000 명 시나리오 → **900~1,100 RPS** (구간별 latency p50 / p95 / p99 측정) -- **JPA 측면** — N+1 회피, fetch 전략 명시 (LAZY + 필요 시 명시적 join fetch), Spring Data Page 의 count 쿼리 분리 - -`PostgreSQL` `JPA` `EXPLAIN ANALYZE` `Index design` `Redis` `Locust` `Spring Boot` - -### Project-Auth-Server — Spring Boot 인증 서버 (DB 측면) - -> 개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 설계 / 구현 / 로컬 검증 -> [github.com/donghyeon-ka/project-auth-server](https://github.com/donghyeon-ka/project-auth-server) - -Spring Boot 인증 서버 프로젝트 — 본 트랙에서는 PostgreSQL 스키마 / JPA / Flyway / 트랜잭션 경계 등 데이터 레이어 관련 결정 중심으로 정리합니다. - -- **Flyway V1~V5 단계적 마이그레이션** — `auth` 스키마, 사용자 도메인 + Keycloak provider 통합 컬럼 (`provider`, `provider_subject`, `KEYCLOAK` 단일 값으로 고정) 까지 5 단계로 분리 -- **트랜잭션 경계는 application use case 가 소유** — `infrastructure` adapter 가 `@Transactional` 을 들고 있던 구조를 ADR 로 정리해 application 레이어로 이동 -- **infrastructure → domain 복원 시 무결성 보호** — `JpaUserRepositoryAdapter` 가 row → User 복원 중 `DomainException` 등이 발생하면 `InfrastructureException(PERSISTED_DATA_INVALID)` 로 번역 (잘못된 저장 데이터를 비즈니스 검증 실패가 아니라 인프라 무결성 문제로 분류) -- **DB row 와 도메인 값 객체 분리** — `User`, `UserEmail`, `UserName` 등 VO 의 invariant 가 entity 와 별도로 검증 - -`PostgreSQL` `JPA` `Flyway` `Spring Boot` `ArchUnit` - -### Project-Infra — 데이터 저장소와 책임 분리 - -> 개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 로컬 / dev 환경 구성 -> [github.com/donghyeon-ka/project-infra](https://github.com/donghyeon-ka/project-infra) - -auth-server 가 동작하는 K3s 환경에서 데이터 저장소 (PostgreSQL / MinIO / Docker Registry) 책임을 분리해 구성한 프로젝트입니다. - -- **Postgres + MinIO + Docker Registry 책임 분리** — 애플리케이션 row 데이터는 PostgreSQL, object storage 는 MinIO, Docker Registry 는 자체 PV 없이 MinIO S3 backend 위임 -- Flyway 마이그레이션 Job 을 앱보다 먼저 실행되도록 분리하고, GitOps 적용 시 PreSync / sync-wave 로 배포 순서를 제어할 수 있게 구성 -- 외부 push 인증은 Traefik Middleware BasicAuth, 내부 pull 은 K8s imagePullSecret 으로 책임 경계 분리 - -`PostgreSQL` `MinIO` `Docker Registry` `Flyway` `Kustomize` - ---- - -## Blog - -- [Velog @donghyeon2](https://velog.io/@donghyeon2) — 기술적 의사결정 과정과 트러블슈팅 경험 기록 - ---- - -## Links - -- **GitHub**: [github.com/donghyeon-ka](https://github.com/donghyeon-ka) -- **쿼리 튜닝 (메인)**: [feed-postgresql-query-tuning](https://github.com/donghyeon-ka/feed-postgresql-query-tuning) -- **인증 서버**: [project-auth-server](https://github.com/donghyeon-ka/project-auth-server) -- **인프라**: [project-infra](https://github.com/donghyeon-ka/project-infra) diff --git a/README.md b/README.md index 8f63e95..cbedc1a 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,61 @@ -# Resume +# Resume & Portfolio -직무 트랙별 이력서 모음. 모든 변형은 같은 사실 기반(같은 프로젝트 / 같은 수치 / 같은 기간) 에서 *강조점만* 다르게 정리됨. +같은 실제 경험을 기반으로 **이력서 2개와 포트폴리오 1개**를 함께 관리합니다. 이력서는 직무별 강조점을 달리하고, 포트폴리오는 대표 문제 해결 사례를 더 깊게 설명합니다. | 파일 | 대상 공고 | 강조 | |---|---|---| -| [01-java-spring-backend.md](./01-java-spring-backend.md) | Java / Spring 백엔드 | Spring Boot · Spring Security · JPA · PostgreSQL · API · 테스트 | -| [02-platform-devops-backend.md](./02-platform-devops-backend.md) | 플랫폼 / DevOps 친화 백엔드 | Kubernetes · Keycloak · Vault · Traefik · NetworkPolicy · GitOps | -| [03-performance-db.md](./03-performance-db.md) | 성능 / DB 관심 | PostgreSQL · EXPLAIN ANALYZE · Index · Redis · Locust | +| [01-java-spring-backend.feat.google-version.md](./01-java-spring-backend.feat.google-version.md) | Java / Spring 백엔드 | TechLog · Clean Architecture · Keycloak 인증 경계 · N+1 / 조회 전략 | +| [02-platform-devops-backend.feat.google-version.md](./02-platform-devops-backend.feat.google-version.md) | Platform / Infra 친화 백엔드 | K3s · Nginx / Traefik · Vault / VSO · Keycloak multi-node · Observability | +| [portfolio.md](./portfolio.md) | Backend / Platform 포트폴리오 | TechLog · 인증 경계 · 조회 성능 · Home Platform의 문제 해결 과정 | ## 작성 원칙 -- 2 페이지 이내 (PDF 출력 기준) -- 구조: Summary / Skills / Projects / Blog / Links -- 프로젝트 bullet 5~7 개 이내 -- 모든 수치는 측정 환경 명시 (로컬 / dev / EXPLAIN ANALYZE 기준) -- 운영 경험처럼 표현 금지 — 개인 프로젝트 / 학습 프로젝트 / 로컬 / dev 명시 -- 채용자가 읽었을 때 자연스럽게 면접 질문이 나오도록 *결정 narrative + 수치* 배치 +- PDF 출력 기준 2 페이지 안팎 +- 단순 기술 나열보다 **문제의 출발점 → 어려웠던 점 → 판단 → 결과**가 먼저 보이게 작성 +- “몇 번 실험했다” 같은 내부 작업량 수치는 이력서 핵심 성과로 사용하지 않음 +- local / home lab 결과를 운영 경험처럼 표현하지 않음 +- 성능 수치는 측정 조건을 함께 표시 +- 아직 확인하지 못한 영역은 완료된 성과와 구분 +- 실제 결과 서비스 링크를 함께 제공: [hyeonworks.com](https://hyeonworks.com) ---- +## 주요 경험 -## 트랙별 보강 후보 (이력서에 적지 않음, 시간 여유 시 작업) +### Backend +- TechLog: 기록이 늘어나며 맥락을 다시 찾기 어려운 문제를 서비스로 해결 +- 현재 backend 18-module registry 기반 dependency / runtime membership 검증 +- Studio Create / Save / Validate / Preview / Publish 흐름 +- Keycloak SPA / Token Mediator / BFF / Forward-Auth 구조를 credential ownership 관점에서 비교 +- Keycloak 26 multi-node에서 persistent session이 공유 PostgreSQL 조회에 의존하는 경로 확인 +- Feed 조회에서 N=1,000 기준 PreparedStatement 2,022 → 23 +- Window / LATERAL / Keyset pagination을 실제 PostgreSQL plan으로 비교 -이력서 본문은 *현재 실제로 한 작업* 만 반영. 아래는 *시니어 시각의 약점 / 다음 라운드에 채우면 좋을 항목* 정리. 작업 후 이력서에 반영하는 흐름으로 운영. +### Platform / Infra +- Host Nginx → loopback NodePort → Traefik → Kubernetes Service 요청 경로 +- Nginx TLS termination 및 Forwarded Header trust boundary 구성 +- CloudNativePG / PostgreSQL, Keycloak, Local PV, NetworkPolicy +- Vault KV-v2 → VSO → Kubernetes Secret → workload +- 2-node K3s에서 Keycloak session / DB / network / refresh 경쟁 조건 확인 +- Prometheus / Grafana / Loki / Tempo / Blackbox 기반 관측성 구성 +- 현재 Vault lab은 single replica / file storage 구성 -### 공통 (3 트랙 모두) -- **JaCoCo 커버리지 측정** — `application` / `presentation` / `infrastructure` 모듈별 % 측정 후 Skills 또는 Project bullet 에 한 줄 추가. 면접에서 *"테스트 얼마나?"* 답 강화. -- **GitHub Actions CI workflow** — 각 repo 에 `.github/workflows/ci.yml` (build + test + validate.sh) 추가 + README 상단 녹색 배지. *"체계적으로 검증한다"* 시그널. -- **Spring Boot 4.0 변경점 면접 답 준비** — JDK 21 baseline / Servlet 6 / Spring Framework 7 / observability autoconfig 분리 등 핵심 변경점 메모. (이력서 본문은 그대로, 면접 노트로만) +## 근거 -### 트랙 1 (Java / Spring) — 약점 보강 +- `/shared/document-haness/docs/TechLog/final/document.md` +- `/shared/document-haness/docs/keycloak/final/document.md` +- `/shared/document-haness/docs/keycloak-session-store/final/document.md` +- `/shared/document-haness/docs/n+1liner/final/document.md` +- `/shared/document-haness/docs/clean-architecture-backend-template/final/document.md` +- `/shared/document-haness/docs/platform-infra/final/document.md` +- `/shared/codebase/tech-log-backend` +- `/shared/codebase/tech-log-frontend` +- `/shared/codebase/project-infra` -- **Project-Auth-Server 의 다른 측면** 을 3 번째 프로젝트로 추가하면 트랙 일관성 ↑ — 후보: - - OpenAPI annotation 분리 패턴 (Controller / *ApiDocs* interface 분리) - - `@Transactional` 위치 ADR (infrastructure adapter → application use case 로 이동) - - `ApiResult` testable factory 패턴 -- 트랙 1 에서 Project-Infra 는 *"백엔드가 동작하는 환경에 대한 이해"* 한 줄로 압축하거나 제거하는 게 트랙 집중도 ↑ +## PDF 생성 -### 트랙 2 (플랫폼 / DevOps) — 약점 보강 +```bash +npm run pdf -- 01-java-spring-backend.feat.google-version.md +npm run pdf -- 02-platform-devops-backend.feat.google-version.md +npm run portfolio +``` -- **GitHub Actions CI 가 PR 게이트로 동작하는 결과물** — workflow 추가 후 *"PR 게이트"* 표현을 본문에 다시 사용 가능 (현재는 *"CI 연결 시"* 가능 형태로 약화) -- **cert-manager 정식 인증서 발급 + ssl_insecure_skip_verify 제거** — Project-Infra Limitations 의 핵심 미완 항목. 완료 시 *"E2E 인증 흐름 검증 완료"* 로 표현 강화 가능 -- **실제 ArgoCD 배포 (annotation 만 있는 현 상태 → 실제 sync)** — 또는 본문에서 *"(annotation 적용, 실제 ArgoCD 미배포)"* 한 줄 명확화 -- **Skills 에 *"GitOps source-of-truth 관리"* 키워드 명시** — ATS 검색 매칭 강화 (공고 키워드가 *"GitOps"* 일 때) - -### 트랙 3 (성능 / DB) — 약점 보강 (가장 우선순위 높음) - -- **추가 분석 사례 1~2 건 더** — 같은 EXPLAIN ANALYZE 패턴을 *다른 시나리오* (예: auth-server 의 user 조회 / Keycloak claim 매핑 / 페이지네이션 쿼리) 에 적용한 경험. 1 개월 단일 학습 프로젝트 의존을 깨는 가장 효과적인 patch. -- **측정 환경 구체화** — 현재 *"단일 인스턴스 환경"* → *"노트북 (Mac M1 / 16 GB / Postgres 16 docker container)"* 또는 사용한 실제 사양 명시. RPS 의미가 환경 따라 크게 달라짐. -- **캐시 히트율 측정 방법** — `redis-cli INFO stats` 의 `keyspace_hits` / `keyspace_misses` 비율, 워밍업 후 N 분 간 측정 같은 구체성. 현재는 결과 수치만 있음. -- **JaCoCo 또는 별도 쿼리 회귀 테스트** — 인덱스 추가 / 쿼리 변경 시 회귀를 잡는 테스트 추가. 면접 *"이 인덱스가 다른 쿼리를 느리게 만들지 않는다는 걸 어떻게 보장?"* 답 준비. - -### 적용 흐름 - -1. 위 항목 중 1 개씩 실제 작업 수행 -2. 작업 결과를 해당 repo README 에 먼저 기록 -3. 결과가 *측정 가능* 한 형태가 되면 이력서 본문에 한 줄 반영 -4. 본 README 의 해당 항목 ✅ 표시 또는 삭제 +출력은 `dist/`에 HTML / PDF로 생성됩니다. diff --git a/dist/01-java-spring-backend.feat.google-version.html b/dist/01-java-spring-backend.feat.google-version.html index 4ced743..8bae1c4 100644 --- a/dist/01-java-spring-backend.feat.google-version.html +++ b/dist/01-java-spring-backend.feat.google-version.html @@ -180,27 +180,27 @@ tr {

강동현 · 백엔드 신입 (Java / Spring)

-
Emaildonghyeonka68@gmail.com
GitHubgithub.com/donghyeon-ka
Blogvelog.io/@donghyeon2
+
Emaildonghyeonka68@gmail.com
GitHubgithub.com/donghyeon-ka
TechLoghyeonworks.com
Blogvelog.io/@donghyeon2

Summary

-

Java / Spring Boot 기반 백엔드에서 인증, 계층 분리, 예외 응답 표준화, 데이터 영속성 경계에 집중해 학습해 온 신입 백엔드 개발자입니다.

-

Spring Boot 인증 서버를 5 개 모듈 Clean / Hexagonal 구조로 나누고, domain 모듈이 Spring / JPA / Servlet에 의존하지 않도록 분리했습니다. 또한 ArchUnit 테스트로 계층 의존성을 검증하고, Keycloak JWT를 Resource Server로 다시 검증하는 구조를 구현했습니다.

-

프로젝트는 개인 로컬 / dev 환경 기준입니다. 대신 구현 범위, 검증 범위, 아직 운영 경험으로 볼 수 없는 부분을 문서 안에서 구분했습니다.

+

Java / Spring Boot 기반 백엔드에서 인증 경계, 데이터 조회 성능, 계층 분리에 집중해 학습해 온 신입 백엔드 개발자입니다.

+

현업 개발자의 멘토링 아래 약 6개월 동안 과제를 수행하며, 단순히 기술을 적용하는 데서 끝내지 않고 왜 이 구조를 선택했는지, 어떤 조건에서 문제가 생기는지를 직접 구현하고 검증했습니다. Keycloak 인증 구조에서는 token / session의 소유 경계를 비교했고, 피드 조회에서는 N+1부터 Top-N 조회와 pagination까지 실제 SQL과 실행계획으로 확인했습니다.

+

이 과정에서 쌓인 기록을 다시 찾고 맥락대로 연결하기 위해 TechLog를 만들고 있습니다. 현재 frontend는 hyeonworks.com에서 확인할 수 있으며, backend와 인프라의 최종 통합은 진행 중입니다.


Skills

Core

-
  • Java 21, Spring Boot 4, Spring Security Resource Server, Spring Data JPA, PostgreSQL 16
+
  • Java 21, Spring Boot 4, Spring Security, Spring Data JPA, PostgreSQL

Architecture / Testing

-
  • Clean Architecture, Hexagonal Architecture, Gradle multi-project, ArchUnit, JUnit 5, AssertJ
-

Auth / Observability

-
  • Keycloak, OAuth2 / OIDC, JWKS 기반 JWT 검증, Flyway, OpenAPI / Swagger UI, MDC traceId 기반 structured logging
+
  • Clean Architecture, Gradle multi-module, ArchUnit, JUnit, Testcontainers, Flyway
+

Auth / Performance

+
  • Keycloak, OAuth2 / OIDC, PKCE, JWT / JWKS, Redis, Hibernate Statistics, EXPLAIN (ANALYZE, BUFFERS)

Projects

-

Project-Auth-Server — Spring Boot 인증 서버

개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 설계 / 구현 / 로컬 검증 github.com/donghyeon-ka/project-auth-server

Spring Boot 인증 서버를 계층별 책임이 드러나도록 분리하고, 인증 위임 / JWT 검증 / 예외 응답 / DB 마이그레이션 경계를 정리한 프로젝트입니다.

  • Gradle multi-project로 domain / application / presentation / infrastructure / bootstrap 5 개 모듈을 분리했습니다.
  • domain 모듈은 Spring, JPA, Servlet 의존성을 두지 않고 값 객체와 도메인 규칙만 포함하도록 구성했습니다.
  • ArchUnit의 LayerDependencyArchitectureTest로 presentation → infrastructure 같은 계층 위반을 빌드 단계에서 탐지하도록 했습니다.
  • 로그인 플로우는 Keycloak / Ingress 계층에 위임하고, 백엔드는 oauth2-resource-server로 JWT issuer / signature / expiration / role claim을 다시 검증하도록 구성했습니다.
  • ErrorCode는 비즈니스 의미만 담고, HTTP status 매핑은 presentation의 mapper가 담당하도록 분리했습니다.
  • 예외 처리는 Security filter, Spring MVC 입력 검증, application, infrastructure 누수 감지로 나눴고, 응답은 ApiResult<T> 형태로 통일했습니다.
  • TraceIdFilter로 32 자리 hex traceId를 응답 헤더, 로그, audit 흐름에 동일하게 전파했습니다.
  • Flyway V1~V5로 auth 스키마와 사용자 / provider 관련 변경을 단계별 마이그레이션으로 관리했습니다.

Java 21 Spring Boot Spring Security Keycloak JPA PostgreSQL ArchUnit Flyway

-

feed-postgresql-query-tuning — PostgreSQL 쿼리 최적화

개인 프로젝트 · 2025.03 ~ 2025.04 · 1 인 · 분석 / 최적화 / 검증 github.com/donghyeon-ka/feed-postgresql-query-tuning

피드 목록 조회 쿼리를 실행 계획 기준으로 분석하고, JOIN 구조와 인덱스 설계를 바꿔 성능을 개선한 프로젝트입니다.

  • EXPLAIN ANALYZE 기준 피드 목록 조회 쿼리 실행 시간을 1.77 s → 7.66 ms로 개선했습니다.
  • 4-table LEFT JOIN에 따른 row 폭증, 인덱스 미사용, 디스크 기반 외부 정렬을 병목으로 확인했습니다.
  • EXISTS 서브쿼리, 페이지네이션 쿼리 분리, 복합 / 커버링 인덱스를 단계적으로 적용했습니다.
  • 단일 인스턴스 환경에서 Locust 1,000 동시 사용자 시나리오를 실행해 약 900~1,100 RPS 구간을 확인했습니다.

PostgreSQL EXPLAIN ANALYZE Index design JPA Redis Locust

-

Project-Infra — Spring 앱 실행 환경

개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 로컬 / dev 환경 구성 github.com/donghyeon-ka/project-infra

auth-server가 동작하는 로컬 / dev K3s 환경을 구성하면서 백엔드와 인프라의 인증 책임을 분리한 프로젝트입니다.

  • Traefik ForwardAuth + oauth2-proxy + Keycloak으로 로그인 / 세션 확인을 Ingress 계층에 두고, auth-server는 JWT 검증에 집중하도록 구성했습니다.
  • Vault → VSO → Kubernetes Secret 흐름으로 secret 주입 책임을 애플리케이션 코드 밖으로 분리했습니다.
  • Kustomize base / overlay 구조로 로컬과 dev 환경 차이를 manifest 단에서 관리했습니다.

Kubernetes K3s Kustomize Vault VSO Traefik


+

TechLog — 기술 학습 기록을 서비스로 연결한 프로젝트

멘토링 기반 개인 프로젝트 · 약 6개월 · 1 인 · 설계 / 구현 / 검증 hyeonworks.com

인증, 성능, 아키텍처 과제를 진행하며 문서가 늘어났지만, 기록이 흩어져 “왜 이런 결정을 했는지”를 다시 따라가기 어려운 문제가 생겼습니다. 이를 해결하기 위해 Public / Studio 구조의 기술 기록 서비스를 만들었습니다.

  • 작성 흐름을 Create / Save / Validate / Preview / Publish 유스케이스로 분리하고 persistence / rendering 구현을 port 뒤로 분리했습니다.
  • backend를 18개 Gradle module로 나누고, modules.json을 기준으로 허용 dependency와 runtime membership을 검증하도록 구성했습니다.
  • Project / Topic / Release 관리 유스케이스를 application layer에 두어 JPA entity와 화면 DTO가 application 정책으로 직접 유출되지 않도록 분리했습니다.
  • backend contract에는 값이 있지만 HTTP mapping 또는 frontend adapter에서 누락되어 화면이 비는 문제를 추적하고 contract / route / test gate를 보강했습니다.
  • frontend도 domain → application → adapter → presentation 경계를 두고 HTTP / mock adapter를 교체할 수 있도록 구성했습니다.

Java 21 Spring Boot JPA PostgreSQL Gradle ArchUnit React TypeScript

+

Keycloak 인증 구조 — 브라우저와 서버의 credential 경계 비교

멘토링 과제 · 개인 lab · 설계 / 구현 / 검증

같은 로그인 기능이라도 SPA, BFF, Forward-Auth에 따라 token과 session의 위치, API 호출 주체가 달라집니다. 구조 이름만 비교하지 않고 credential이 실제로 어디에 머무는지를 기준으로 네 가지 패턴을 구현했습니다.

  • SPA / Token Mediator / BFF / Forward-Auth를 구현해 authorization code 교환 주체, refresh token 보관 위치, API caller를 비교했습니다.
  • BFF에서는 브라우저 JavaScript에서 OAuth token을 제거하는 대신 server-side session, CSRF, session scale-out 문제가 새로 생기는 것을 확인했습니다.
  • Forward-Auth에서는 edge가 만든 identity header를 신뢰하려면 header overwrite와 network isolation이 함께 필요하다는 점을 검증했습니다.
  • 이후 2-node K3s 환경으로 확장해 Keycloak session의 실제 저장 위치를 확인했습니다.
  • Keycloak 26 기본 persistent-user-sessions 조건에서 교차 노드 session 처리가 Infinispan 복제보다 공유 PostgreSQL session 조회에 의존하는 경로임을 SQL로 확인했습니다.

Keycloak OAuth2 / OIDC Spring Security PostgreSQL K3s Nginx

+

피드 조회 성능 — N+1 이후의 조회 전략 비교

멘토링 과제 · PostgreSQL 16 Testcontainers 기반 측정 아래 수치는 local / warm-cache 기준이며 운영 성능 수치가 아닙니다.

피드마다 최신 하이라이트와 공개 범위, pagination을 함께 처리하면서 N+1만 제거하면 끝나지 않는 문제를 확인했습니다. 쿼리 수, 반환 행, 인덱스, paging 비용을 분리해 비교했습니다.

  • FeedItem 1,000개 조회에서 Hibernate Statistics 기준 PreparedStatement 2,022개를 기준선으로 확인했습니다.
  • fetch join에서 MultipleBagFetchException, row 증가, collection fetch + paging의 in-memory paging 문제를 재현했습니다.
  • Batch Fetch 적용 후 같은 조건에서 PreparedStatement를 2,022 → 23으로 줄였습니다.
  • 부모별 최신 3개 조회에서 Window Function / LATERAL / 2-step을 비교하고, 작은 K와 복합 인덱스 조건에서 LATERAL이 유리한 이유를 실행계획으로 확인했습니다.
  • 2,000행의 깊은 페이지에서 OFFSET은 2,000행을 읽고 Keyset + 정렬키 index는 20행만 읽는 실행계획을 확인했습니다.

Spring Data JPA Hibernate PostgreSQL 16 Testcontainers EXPLAIN ANALYZE


Links

- +
diff --git a/dist/01-java-spring-backend.feat.google-version.pdf b/dist/01-java-spring-backend.feat.google-version.pdf index 261b478..4008a07 100644 Binary files a/dist/01-java-spring-backend.feat.google-version.pdf and b/dist/01-java-spring-backend.feat.google-version.pdf differ diff --git a/dist/02-platform-devops-backend.feat.google-version.html b/dist/02-platform-devops-backend.feat.google-version.html index 4f3eec3..7691fcc 100644 --- a/dist/02-platform-devops-backend.feat.google-version.html +++ b/dist/02-platform-devops-backend.feat.google-version.html @@ -180,27 +180,27 @@ tr {

강동현 · 백엔드 신입 (Platform / DevOps 친화)

-
Emaildonghyeonka68@gmail.com
GitHubgithub.com/donghyeon-ka
Blogvelog.io/@donghyeon2
+
Emaildonghyeonka68@gmail.com
GitHubgithub.com/donghyeon-ka
TechLoghyeonworks.com
Blogvelog.io/@donghyeon2

Summary

-

Spring Boot 애플리케이션이 실제로 실행되는 환경까지 이해하려고, K3s 기반 로컬 / dev 플랫폼을 직접 구성해 온 신입 백엔드 개발자입니다.

-

Ingress 인증 게이트, Vault 기반 secret 주입, default-deny NetworkPolicy, PSS Restricted baseline을 함께 구성하며 애플리케이션 코드 밖의 책임을 명확히 나누는 데 집중했습니다. 백엔드는 JWT 검증과 도메인 처리에 집중하고, 로그인 / 세션 / secret / 네트워크 경계는 플랫폼 계층에서 다루도록 설계했습니다.

-

아래 내용은 운영 경험이 아니라 로컬 / dev 환경에서 실행 구조를 검증한 결과입니다. 대신 각 결정이 어떤 책임을 분리하기 위한 것인지 드러나도록 정리했습니다.

+

Spring Boot 애플리케이션이 실제로 실행되는 경로까지 이해하기 위해 K3s, Nginx, Traefik, Keycloak, Vault를 직접 구성해 온 신입 백엔드 개발자입니다.

+

물리 서버 host에 설정을 하나씩 추가하다 보니 TLS 종료 위치, proxy 신뢰 범위, secret과 session의 저장 위치를 설명하기 어려워졌습니다. 이를 정리하기 위해 외부 요청이 Nginx를 거쳐 Kubernetes Service까지 도달하는 경로와 각 컴포넌트의 책임을 분리했습니다.

+

모든 내용은 개인 home lab / dev 환경에서 검증한 결과이며 운영 경험으로 확대해 표현하지 않았습니다. 현재 hyeonworks.com에서 TechLog frontend를 서비스하고 있으며, backend와 플랫폼의 최종 통합은 진행 중입니다.


Skills

Core

-
  • Kubernetes (K3s 1.30), Kustomize, Traefik, NetworkPolicy default-deny, PSS Restricted
-

Secrets / Auth Gateway

-
  • HashiCorp Vault 1.17.2, Vault Secrets Operator, Keycloak, oauth2-proxy, Traefik ForwardAuth, HelmChartConfig
-

Validation / Backend

-
  • kustomize build, kubeconform -strict, kube-linter, Java 21, Spring Boot 4, Spring Security Resource Server, PostgreSQL, Flyway
+
  • Kubernetes / K3s, Nginx, Traefik, Kustomize, Helm / HelmChartConfig, NetworkPolicy
+

Secrets / Identity

+
  • HashiCorp Vault 1.17.2, Vault Secrets Operator, Keycloak, oauth2-proxy, Kubernetes Auth
+

Data / Observability

+
  • PostgreSQL / CloudNativePG, Redis, Prometheus, Grafana, Loki, Tempo, Blackbox Exporter

Projects

-

Project-Infra — Kubernetes 기반 백엔드 실행 환경

개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 설계 / 구현 / 로컬 검증 github.com/donghyeon-ka/project-infra

Spring Boot 인증 서버가 동작하는 K3s 환경을 구성하고, 인증 게이트 / secret 주입 / 네트워크 정책 / manifest 검증 책임을 분리한 프로젝트입니다.

  • Traefik ForwardAuth + oauth2-proxy + Keycloak 조합으로 미인증 요청을 Ingress 계층에서 먼저 차단하도록 구성했습니다.
  • auth-server는 Ingress 뒤에서 Keycloak JWT를 Resource Server로 다시 검증하게 하여, 로그인 세션 처리와 API 권한 검증을 분리했습니다.
  • Vault KV-v2 값을 VSO가 Kubernetes Secret으로 동기화하도록 구성하고, 도메인별 Vault role / policy를 나눠 secret 접근 범위를 제한했습니다.
  • default-deny NetworkPolicy를 기본값으로 두고, 필요한 컴포넌트 간 통신만 명시적으로 허용했습니다.
  • K3s packaged Traefik manifest를 직접 수정하지 않고 HelmChartConfig overlay로 설정을 관리해, 재부팅 시 설정이 사라지는 문제를 피했습니다.
  • PSS Restricted baseline을 유지하기 위해 Vault의 disable_mlock 설정을 선택했고, 그에 따른 swap-off 운영 전제를 명시했습니다.
  • 주요 overlay에 대해 kustomize build, kubeconform -strict, kube-linter 검증을 실행하는 스크립트를 구성했습니다.
  • MinIO Operator 설치, namespace / PSS 라벨 적용, Vault init / unseal, VSO 설치 흐름을 반복 실행 가능한 bootstrap script로 분리했습니다.

Kubernetes K3s Kustomize Traefik oauth2-proxy Keycloak Vault VSO NetworkPolicy PSS

-

Project-Auth-Server — 플랫폼 뒤에서 동작하는 Spring Boot 백엔드

개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 설계 / 구현 / 로컬 검증 github.com/donghyeon-ka/project-auth-server

플랫폼 계층이 로그인 / 세션을 처리하고, 백엔드는 Resource Server로 JWT를 검증하는 구조의 Spring Boot 인증 서버입니다.

  • oauth2-client가 아니라 oauth2-resource-server를 사용해 백엔드 책임을 JWT 검증과 권한 매핑으로 좁혔습니다.
  • Clean / Hexagonal 5 개 모듈 구조와 ArchUnit 테스트로 계층 의존성 위반을 빌드 단계에서 탐지하도록 했습니다.
  • application 코드가 HTTP status 같은 web 프로토콜 세부사항을 직접 알지 않도록 ErrorCode와 HTTP status 매핑을 분리했습니다.
  • K8s 환경에서는 공식 flyway/flyway 이미지를 initContainer로 실행해, 자체 migration 이미지 빌드 사이클을 줄였습니다.

Java 21 Spring Boot Spring Security Keycloak JPA Flyway ArchUnit

-

feed-postgresql-query-tuning — PostgreSQL 성능 검증

개인 프로젝트 · 2025.03 ~ 2025.04 · 1 인 · 분석 / 최적화 / 검증 github.com/donghyeon-ka/feed-postgresql-query-tuning

플랫폼 관점에서도 애플리케이션 병목을 관찰할 수 있도록, DB 쿼리 실행 계획과 부하 테스트를 함께 정리한 프로젝트입니다.

  • EXPLAIN ANALYZE 기준 피드 목록 조회 쿼리 실행 시간을 1.77 s → 7.66 ms로 개선했습니다.
  • JOIN 구조 변경, 페이지네이션 쿼리 분리, 복합 / 커버링 인덱스 적용을 단계적으로 검증했습니다.
  • 단일 인스턴스 Locust 1,000 동시 사용자 시나리오에서 약 900~1,100 RPS 구간을 확인했습니다.

PostgreSQL EXPLAIN ANALYZE Index design Redis Locust


+

Home Platform — K3s 기반 서비스 실행 환경

멘토링 기반 개인 프로젝트 · home lab / dev hyeonworks.com

서비스를 하나씩 올리면서 host와 cluster의 책임이 섞이기 시작했습니다. 단순히 “접속된다”가 아니라 요청이 어떤 신뢰 경계를 지나 Pod까지 도달하는지 설명할 수 있는 구조로 다시 구성했습니다.

  • 외부 HTTPS를 Host Nginx에서 종료하고 Traefik NodePort를 loopback에만 열어 Internet → Nginx → 127.0.0.1 NodePort → Traefik → Service 경로로 진입점을 제한했습니다.
  • 외부가 보낸 X-Forwarded-*를 Nginx에서 다시 쓰고, Traefik은 실제 proxy source만 신뢰하도록 범위를 줄였습니다.
  • 공개 서비스와 관리용 hostname을 분리하고 관리 경로에는 LAN / Tailscale source allowlist를 적용했습니다.
  • CloudNativePG / PostgreSQL, Keycloak, workload별 Local PV를 구성하고 서비스별 DB / role / Secret / NetworkPolicy를 분리했습니다.
  • Prometheus / Grafana / Loki / Tempo / Blackbox Exporter를 구성해 endpoint, node, log, trace, 인증서 상태를 각각 관측했습니다.
  • manifest에 선언된 설정과 live cluster에서 실제 집행되는 상태를 대조해, 선언만 존재하는 항목을 완료로 판단하지 않도록 검증했습니다.

K3s Nginx Traefik Kustomize CloudNativePG Prometheus Grafana

+

Vault Secret Delivery — 애플리케이션 밖으로 secret 책임 분리

개인 lab · 현재 Vault는 single replica / file storage 구성

Secret 값을 Git에서 제거하는 것만으로는 누가 Vault에 접근하고, workload가 어떤 credential을 받는지 해결되지 않았습니다. 애플리케이션이 Vault API를 직접 알지 않도록 secret 전달 경계를 분리했습니다.

  • Vault KV-v2를 source of truth로 두고 Vault → VSO → Kubernetes Secret → workload 흐름으로 구성했습니다.
  • VaultConnection / VaultAuth와 Kubernetes Auth를 사용하고 role / policy를 경로별로 분리했습니다.
  • VSO controller → Vault init / unseal → auth / policy → KV seed → destination Secret → workload 순으로 bootstrap dependency를 정리했습니다.
  • 실행 중 생성되는 registry credential은 생성 후 Vault에 기록하고 consumer가 VSO를 통해 다시 받도록 흐름을 분리했습니다.
  • 현재 구성은 Vault 1 replica / file storage / local-path PVC 기준이며 Raft HA, auto-unseal 운영 경험으로 표현하지 않았습니다.

Vault 1.17.2 Vault Secrets Operator Kubernetes Auth Kustomize

+

Keycloak Multi-node — session과 장애의 실제 위치 확인

개인 lab · VM 2대 / 2-node K3s

Keycloak replica를 늘리면 session이 자동으로 공유된다고 보기 쉬웠습니다. 이를 확인하기 위해 두 VM에 Keycloak을 나눠 배치하고 DB, cache, network 조건을 바꿔가며 상태의 실제 위치를 확인했습니다.

  • Keycloak 26 기본 persistent-user-sessions에서 교차 노드 session 처리가 공유 PostgreSQL session 조회에 의존하는 것을 SQL로 확인했습니다.
  • persistent session을 끈 조건에서는 JGroups 연결, rolling restart, DB 상태가 결과에 미치는 영향이 달라지는 것을 비교했습니다.
  • NetworkPolicy, iptables, tc를 적용했다고 바로 장애로 판단하지 않고 conntrack / packet counter / cluster state로 장애 주입 자체가 성공했는지 먼저 검증했습니다.
  • Refresh Token Rotation 동시 경쟁과 replica별 JWKS cache 차이처럼 단일 인스턴스에서는 드러나지 않는 상태 경쟁도 확인했습니다.

K3s Keycloak PostgreSQL Redis JGroups Linux networking


Links

- +
diff --git a/dist/02-platform-devops-backend.feat.google-version.pdf b/dist/02-platform-devops-backend.feat.google-version.pdf index 3cb88c7..ae59b47 100644 Binary files a/dist/02-platform-devops-backend.feat.google-version.pdf and b/dist/02-platform-devops-backend.feat.google-version.pdf differ diff --git a/dist/03-performance-db.feat.google-version.html b/dist/03-performance-db.feat.google-version.html deleted file mode 100644 index 28e6b12..0000000 --- a/dist/03-performance-db.feat.google-version.html +++ /dev/null @@ -1,206 +0,0 @@ - - - - - - 03-performance-db.feat.google-version - - - -
-

강동현 · 백엔드 신입 (성능 / DB)

-
Emaildonghyeonka68@gmail.com
GitHubgithub.com/donghyeon-ka
Blogvelog.io/@donghyeon2
-
-

Summary

-

DB 기반 백엔드 시스템에서 쿼리 실행 계획, 인덱스 설계, 애플리케이션과 인프라의 책임 경계에 관심을 두고 학습해 온 신입 백엔드 개발자입니다.

-

PostgreSQL 피드 조회 튜닝 프로젝트에서 EXPLAIN ANALYZE로 병목을 확인하고, JOIN 구조 / 페이지네이션 흐름 / 인덱스 설계를 바꿔 쿼리 실행 시간을 1.77 s → 7.66 ms로 줄였습니다. 이후 Redis 캐시와 Locust 부하 테스트로 개선 경로를 검증했습니다.

-

아래 성능 수치는 모두 로컬 실험 또는 단일 인스턴스 부하 테스트 기준입니다. 운영 경험처럼 과장하지 않기 위해 측정 범위를 명시했습니다.

-
-

Skills

-

Core

-
  • Java 21, Spring Boot 4, Spring Data JPA, PostgreSQL 16, Redis
-

Database / Performance

-
  • EXPLAIN ANALYZE, 복합 인덱스, 커버링 인덱스, 페이지네이션 쿼리 설계, N+1 회피, p50 / p95 / p99 latency 측정
-

Supporting

-
  • Flyway, ArchUnit, Locust, Kubernetes (K3s), Kustomize, Traefik, Vault
-
-

Projects

-

feed-postgresql-query-tuning — PostgreSQL 쿼리 최적화

개인 프로젝트 · 2025.03 ~ 2025.04 · 1 인 · 분석 / 구현 / 검증 github.com/donghyeon-ka/feed-postgresql-query-tuning

피드 목록 조회 쿼리를 실행 계획 기준으로 분석하고, 실제 접근 패턴에 맞춰 쿼리 책임과 인덱스 구조를 다시 설계한 프로젝트입니다.

  • EXPLAIN ANALYZE 기준 피드 목록 조회 쿼리 실행 시간을 1.77 s → 7.66 ms로 개선했습니다.
  • 주요 병목으로 4-table LEFT JOIN에 따른 row 폭증, 사용 가능한 인덱스 부재로 인한 sequential scan, 디스크 기반 외부 정렬(Sort Method: external merge Disk)을 확인했습니다.
  • 불필요한 LEFT JOIN을 EXISTS 서브쿼리로 바꾸고, 페이지네이션과 상세 로딩 책임을 분리해 실행 시간을 1.77 s → 0.216 s로 줄였습니다.
  • WHERE 조건과 정렬 키를 함께 고려한 복합 인덱스, 자주 조회되는 컬럼을 포함한 커버링 인덱스를 적용해 0.216 s → 7.66 ms까지 줄였습니다.
  • 공개 피드에는 Redis 2 단계 캐시를 적용하고 private 피드는 캐시를 우회하도록 분리했습니다. 테스트 구간에서 약 90% cache hit rate를 관찰했습니다.
  • 단일 인스턴스 환경에서 Locust 1,000 동시 사용자 시나리오를 실행해 약 900~1,100 RPS 구간을 확인했습니다.
  • JPA 측면에서는 N+1을 피하고, 기본 LAZY 로딩과 필요한 지점의 명시적 fetch join을 분리했으며, Page 응답의 count 쿼리를 별도로 다뤘습니다.

PostgreSQL EXPLAIN ANALYZE Index design JPA Redis Locust Spring Boot

-

Project-Auth-Server — Spring Boot 인증 서버의 DB 책임 경계

개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 설계 / 구현 / 로컬 검증 github.com/donghyeon-ka/project-auth-server

Spring Boot 인증 서버에서 도메인 규칙, 영속성 매핑, 트랜잭션 소유권을 분리해 구현한 프로젝트입니다.

  • Flyway V1~V5로 PostgreSQL 스키마 변경을 관리하고, auth 스키마 생성 / 사용자 도메인 테이블 / Keycloak provider 컬럼 추가를 단계별로 분리했습니다.
  • 트랜잭션 소유권을 application use case로 이동시켜 infrastructure adapter가 비즈니스 트랜잭션 범위를 결정하지 않도록 정리했습니다.
  • 저장된 row를 도메인 객체로 복원하는 과정에서 잘못된 데이터가 발견되면 일반 도메인 검증 실패가 아니라 인프라 무결성 문제로 번역했습니다.
  • DB row와 UserEmail, UserName, User 같은 도메인 값 객체를 분리해 JPA entity 관심사 밖에서 invariant를 검증했습니다.

Java 21 Spring Boot PostgreSQL JPA Flyway ArchUnit

-

Project-Infra — 저장소와 배포 책임 분리

개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 로컬 / dev 환경 구성 github.com/donghyeon-ka/project-infra

auth-server 실행 환경을 K3s 위에 구성하면서 데이터 저장소와 배포 단계의 책임을 분리한 프로젝트입니다.

  • 애플리케이션 row 데이터는 PostgreSQL, object storage는 MinIO, Docker Registry 저장소는 MinIO S3 backend로 분리했습니다.
  • Flyway 마이그레이션 실행을 애플리케이션 시작과 분리해, 스키마 변경이 앱 배포보다 먼저 실행될 수 있도록 구성했습니다.
  • 외부 image push 인증은 Traefik BasicAuth, 내부 image pull은 Kubernetes imagePullSecret으로 나눠 인증 경계를 분리했습니다.

Kubernetes K3s PostgreSQL MinIO Docker Registry Flyway Kustomize


-

Links

- -
- - diff --git a/dist/03-performance-db.feat.google-version.pdf b/dist/03-performance-db.feat.google-version.pdf deleted file mode 100644 index 3382ac9..0000000 Binary files a/dist/03-performance-db.feat.google-version.pdf and /dev/null differ diff --git a/dist/03-performance-db.html b/dist/03-performance-db.html deleted file mode 100644 index 10c53b8..0000000 --- a/dist/03-performance-db.html +++ /dev/null @@ -1,209 +0,0 @@ - - - - - - 03-performance-db - - - -
-

강동현 · 백엔드 신입 (성능 / DB)

-
Emaildonghyeonka68@gmail.com
GitHubgithub.com/donghyeon-ka
Velogvelog.io/@donghyeon2
-
-

Summary

-

PostgreSQL 쿼리 분석과 인덱스 설계에 관심을 두고, 피드 목록 조회 쿼리를 EXPLAIN ANALYZE 기준으로 분석해 1.77 초 → 7.66 ms 까지 단계적으로 개선한 경험이 있는 신입 백엔드 개발자입니다.

-

Redis 2 단계 캐시와 Locust 부하 테스트로 검증 흐름을 정리했고, JPA fetch 전략 / Flyway 마이그레이션 / 트랜잭션 위치 등 데이터 레이어 책임 경계도 함께 정리했습니다.

-

모든 성능 수치는 로컬 실험 및 단일 인스턴스 부하 테스트 기준으로 정리했습니다.

-
-

Skills

-

Main

-
  • PostgreSQL 16, EXPLAIN ANALYZE, 복합 / 커버링 인덱스 설계, Redis, Locust
-

Used in Projects

-
  • Spring Data JPA (fetch 전략, N+1 회피), Flyway (V1~V5), 외부 정렬 / Bitmap Heap Scan / Hash Join 분석, p50 / p95 / p99 latency 측정
-

Backend (보조)

-
  • Java 21, Spring Boot 4, Spring Security Resource Server, ArchUnit
-
-

Projects

-

feed-postgresql-query-tuning — PostgreSQL 쿼리 튜닝

개인 프로젝트 · 2025.03 ~ 2025.04 · 1 인 · 분석 / 최적화 / 검증 모든 수치는 EXPLAIN ANALYZE 기준 쿼리 실행 시간 github.com/donghyeon-ka/feed-postgresql-query-tuning

피드 목록 조회 쿼리를 EXPLAIN ANALYZE 기준으로 분석하고, JOIN 구조 / 인덱스 설계 / 캐시 전략 / 부하 검증 순으로 단계적으로 개선한 프로젝트입니다.

  • 피드 목록 조회 쿼리 응답 시간 1.77 초 → 7.66 ms 까지 단계적으로 개선
  • 원인 분석 (EXPLAIN ANALYZE) — 4-table LEFT JOIN 으로 인한 데이터 폭증, 인덱스 미사용으로 인한 sequential scan, 디스크 기반 외부 정렬 (Sort Method: external merge Disk) 발생 확인
  • 1 차 개선 — 불필요한 LEFT JOIN 을 EXISTS 서브쿼리로 교체 + 페이지네이션 쿼리 분리 → 1.77 초 → 0.216 초 (8 배)
  • 2 차 개선 — 정렬 키 + WHERE 절 컬럼을 합친 복합 인덱스 + 자주 SELECT 되는 컬럼 포함 커버링 인덱스 → 0.216 초 → 7.66 ms (28 배). 인덱스 기반 조회로 디스크 접근과 정렬 비용을 줄임
  • 캐시 전략 — Redis 2 단계 캐시 (공개 피드만 캐시, private 피드는 우회) 도입. 부하 테스트 구간에서 캐시 히트율 약 90% 관찰
  • 부하 검증 — 단일 인스턴스 환경에서 Locust 로 동시 1,000 명 시나리오 → 900~1,100 RPS (구간별 latency p50 / p95 / p99 측정)
  • JPA 측면 — N+1 회피, fetch 전략 명시 (LAZY + 필요 시 명시적 join fetch), Spring Data Page 의 count 쿼리 분리

PostgreSQL JPA EXPLAIN ANALYZE Index design Redis Locust Spring Boot

-

Project-Auth-Server — Spring Boot 인증 서버 (DB 측면)

개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 설계 / 구현 / 로컬 검증 github.com/donghyeon-ka/project-auth-server

Spring Boot 인증 서버 프로젝트 — 본 트랙에서는 PostgreSQL 스키마 / JPA / Flyway / 트랜잭션 경계 등 데이터 레이어 관련 결정 중심으로 정리합니다.

  • Flyway V1~V5 단계적 마이그레이션 — auth 스키마, 사용자 도메인 + Keycloak provider 통합 컬럼 (provider, provider_subject, KEYCLOAK 단일 값으로 고정) 까지 5 단계로 분리
  • 트랜잭션 경계는 application use case 가 소유 — infrastructure adapter 가 @Transactional 을 들고 있던 구조를 ADR 로 정리해 application 레이어로 이동
  • infrastructure → domain 복원 시 무결성 보호 — JpaUserRepositoryAdapter 가 row → User 복원 중 DomainException 등이 발생하면 InfrastructureException(PERSISTED_DATA_INVALID) 로 번역 (잘못된 저장 데이터를 비즈니스 검증 실패가 아니라 인프라 무결성 문제로 분류)
  • DB row 와 도메인 값 객체 분리 — User, UserEmail, UserName 등 VO 의 invariant 가 entity 와 별도로 검증

PostgreSQL JPA Flyway Spring Boot ArchUnit

-

Project-Infra — 데이터 저장소와 책임 분리

개인 프로젝트 · 2025.11 ~ 현재 · 1 인 · 로컬 / dev 환경 구성 github.com/donghyeon-ka/project-infra

auth-server 가 동작하는 K3s 환경에서 데이터 저장소 (PostgreSQL / MinIO / Docker Registry) 책임을 분리해 구성한 프로젝트입니다.

  • Postgres + MinIO + Docker Registry 책임 분리 — 애플리케이션 row 데이터는 PostgreSQL, object storage 는 MinIO, Docker Registry 는 자체 PV 없이 MinIO S3 backend 위임
  • Flyway 마이그레이션 Job 을 앱보다 먼저 실행되도록 분리하고, GitOps 적용 시 PreSync / sync-wave 로 배포 순서를 제어할 수 있게 구성
  • 외부 push 인증은 Traefik Middleware BasicAuth, 내부 pull 은 K8s imagePullSecret 으로 책임 경계 분리

PostgreSQL MinIO Docker Registry Flyway Kustomize


-

Blog

- -
-

Links

- -
- - diff --git a/dist/03-performance-db.pdf b/dist/03-performance-db.pdf deleted file mode 100644 index a72441e..0000000 Binary files a/dist/03-performance-db.pdf and /dev/null differ diff --git a/dist/portfolio.html b/dist/portfolio.html new file mode 100644 index 0000000..c7ead22 --- /dev/null +++ b/dist/portfolio.html @@ -0,0 +1,404 @@ + + + + + + portfolio + + + +
+

강동현 · Backend / Platform Engineering Portfolio

+
Emaildonghyeonka68@gmail.com
GitHubgithub.com/donghyeon-ka
TechLoghyeonworks.com
Blogvelog.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에서 확인할 수 있습니다.

+

구조

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가 같은 계약을 사용하면 서로 어긋날 일이 적을 것이라고 생각했습니다.

실제 문제는 다른 곳에서 나왔습니다.

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 종류를 배열·삼항식으로 직접 나열한 곳에서는 새 종류를 추가할 때 누락이 반복됐습니다.

// 이런 구조에서는 새 종류를 빠뜨려도 마지막 분기로 조용히 떨어질 수 있다.
+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 소유권으로 비교

구조BrowserServer / EdgeAPI가 받는 값
SPAaccess / refresh token 관리없음Bearer JWT
Token Mediatoraccess token 사용refresh token / client state 관리Browser가 보낸 Bearer JWT
BFFsession cookieOAuth token + server sessionBFF가 만든 Bearer JWT
Forward-Authproxy session cookieOAuth login + identity projectiontrusted 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를 대조하며 현재 구조를 다시 정리했습니다.

+
+

요청 경로

+
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는 무엇을 읽는지까지 분리했습니다.

+
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


+

제가 문제를 확인하는 방식

+

네 프로젝트의 주제는 다르지만 문제를 확인하는 순서는 비슷했습니다.

+
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

+ +
+ + diff --git a/dist/portfolio.pdf b/dist/portfolio.pdf new file mode 100644 index 0000000..31fa7b8 Binary files /dev/null and b/dist/portfolio.pdf differ diff --git a/package.json b/package.json index 9f24479..dae842a 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,6 @@ { "scripts": { - "pdf": "node scripts/md-to-pdf.mjs" + "pdf": "node scripts/md-to-pdf.mjs", + "portfolio": "PDF_CSS=portfolio.css node scripts/md-to-pdf.mjs portfolio.md dist/portfolio.pdf" } } diff --git a/portfolio.css b/portfolio.css new file mode 100644 index 0000000..1e79743 --- /dev/null +++ b/portfolio.css @@ -0,0 +1,199 @@ +:root { + color-scheme: light; + --ink: #1f2933; + --muted: #52616b; + --rule: #d8dee4; + --accent: #0f766e; + --soft: #eef7f5; + --code-bg: #f5f7f8; +} + +@page { + size: A4; + margin: 11mm 13mm 12mm; +} + +* { + box-sizing: border-box; +} + +body { + margin: 0; + background: #ffffff; + color: var(--ink); + font-family: "Noto Sans CJK KR", "Noto Sans KR", "Apple SD Gothic Neo", "Malgun Gothic", Arial, sans-serif; + font-size: 9pt; + line-height: 1.48; + word-break: keep-all; + overflow-wrap: break-word; +} + +main { + max-width: 184mm; + margin: 0 auto; +} + +h1, +h2, +h3 { + margin: 0; + line-height: 1.28; + letter-spacing: 0; +} + +main > h1:first-of-type { + padding-bottom: 3mm; + border-bottom: 2px solid var(--accent); + font-size: 19pt; + font-weight: 800; +} + +main > h1:not(:first-of-type) { + break-before: page; + margin-top: 0; + padding-bottom: 2.2mm; + border-bottom: 2px solid var(--accent); + color: var(--ink); + font-size: 16.5pt; + font-weight: 800; +} + +h2 { + margin-top: 5mm; + padding-bottom: 1mm; + border-bottom: 1px solid var(--rule); + color: var(--accent); + font-size: 12.5pt; + font-weight: 800; +} + +h3 { + margin-top: 3.5mm; + font-size: 10.4pt; + font-weight: 800; +} + +p { + margin: 1.8mm 0; +} + +a { + color: #0b5cad; + text-decoration: none; +} + +hr { + height: 1px; + margin: 3.3mm 0; + border: 0; + background: var(--rule); +} + +table { + width: 100%; + margin: 2.2mm 0 3.4mm; + border-collapse: collapse; + font-size: 8.45pt; + line-height: 1.4; +} + +td, +th { + padding: 1.25mm 1.6mm; + border-bottom: 1px solid var(--rule); + text-align: left; + vertical-align: top; +} + +tr:first-child td { + color: var(--muted); + font-weight: 800; +} + +td:first-child { + width: 27mm; + font-weight: 700; +} + +blockquote { + margin: 2mm 0; + padding: 1.7mm 2.4mm; + border-left: 3px solid var(--accent); + background: var(--soft); + color: #334e4a; +} + +blockquote p { + margin: 0.8mm 0; +} + +ul, +ol { + margin: 1.5mm 0 2.4mm; + padding-left: 5mm; +} + +li { + margin: 0.8mm 0; + padding-left: 0.4mm; +} + +strong { + font-weight: 800; +} + +code { + padding: 0.1mm 0.65mm; + border-radius: 2px; + background: #f3f4f6; + color: #1f2937; + font-family: "JetBrains Mono", "D2Coding", Consolas, monospace; + font-size: 0.91em; +} + +pre { + margin: 2.2mm 0 3mm; + padding: 2.2mm 2.6mm; + overflow: hidden; + border: 1px solid #e0e5e9; + border-radius: 4px; + background: var(--code-bg); + white-space: pre-wrap; + break-inside: avoid; +} + +pre code { + padding: 0; + background: transparent; + font-size: 7.8pt; + line-height: 1.42; + white-space: pre-wrap; +} + +.project { + display: block; +} + +h2, +h3, +blockquote, +table, +pre { + break-after: avoid; +} + +li, +blockquote, +tr { + break-inside: avoid; +} + +main > h1 + h2 { + margin-top: 3.8mm; +} + +@media print { + a { + color: #0b5cad; + } +} diff --git a/portfolio.md b/portfolio.md new file mode 100644 index 0000000..5800963 --- /dev/null +++ b/portfolio.md @@ -0,0 +1,547 @@ +# 강동현 · 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) diff --git a/scripts/md-to-pdf.mjs b/scripts/md-to-pdf.mjs index 5600a2b..2a7fedc 100644 --- a/scripts/md-to-pdf.mjs +++ b/scripts/md-to-pdf.mjs @@ -13,7 +13,7 @@ if (!inputArg) { const inputPath = resolve(inputArg); const outputPath = resolve(process.argv[3] ?? `dist/${basename(inputPath, extname(inputPath))}.pdf`); const htmlPath = outputPath.replace(/\.pdf$/i, ".html"); -const cssPath = resolve("resume.css"); +const cssPath = resolve(process.env.PDF_CSS ?? "resume.css"); const markdown = readFileSync(inputPath, "utf8"); const css = readFileSync(cssPath, "utf8"); @@ -67,7 +67,16 @@ async function printPdfWithChrome(sourceHtmlPath, targetPdfPath) { process.exitCode = 1; } finally { chromeProcess.kill("SIGTERM"); - rmSync(userDataDir, { recursive: true, force: true }); + if (chromeProcess.exitCode === null) { + await new Promise((resolveExit) => chromeProcess.once("exit", resolveExit)); + } + try { + rmSync(userDataDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); + } catch (error) { + if (error?.code !== "ENOTEMPTY" && error?.code !== "EBUSY") { + throw error; + } + } } if (process.exitCode) { @@ -222,6 +231,23 @@ function renderMarkdown(source) { continue; } + if (/^\`\`\`/.test(line.trim())) { + const fence = line.trim(); + const language = fence.slice(3).trim(); + const codeLines = []; + index += 1; + while (index < lines.length && !/^\`\`\`/.test(lines[index].trim())) { + codeLines.push(lines[index]); + index += 1; + } + if (index < lines.length) { + index += 1; + } + const languageClass = language ? ` class="language-${escapeHtml(language)}"` : ""; + blocks.push(`
${escapeHtml(codeLines.join("\n"))}
`); + continue; + } + if (isTableStart(lines, index)) { const rows = []; rows.push(parseTableRow(lines[index])); @@ -254,14 +280,26 @@ function renderMarkdown(source) { continue; } + if (/^\d+\.\s+/.test(line)) { + const items = []; + while (index < lines.length && /^\d+\.\s+/.test(lines[index])) { + items.push(lines[index].replace(/^\d+\.\s+/, "")); + index += 1; + } + blocks.push(`
    ${items.map((item) => `
  1. ${inline(item)}
  2. `).join("")}
`); + continue; + } + const paragraph = []; while ( index < lines.length && lines[index].trim() && !/^(#{1,3})\s+/.test(lines[index]) && !/^---+$/.test(lines[index].trim()) && + !/^\`\`\`/.test(lines[index].trim()) && !lines[index].startsWith(">") && !/^- /.test(lines[index]) && + !/^\d+\.\s+/.test(lines[index]) && !isTableStart(lines, index) ) { paragraph.push(lines[index].trim()); @@ -286,6 +324,7 @@ function groupProjectSections(blocks) { const section = []; while ( index < blocks.length && + !blocks[index].startsWith("

") && !blocks[index].startsWith("

") && (section.length === 0 || !blocks[index].startsWith("

")) ) {