신입개발자

‍ Springframwork Mig 기록 - GitLab CI/CD 빌드 환경 맞추기 (feat. Gradle 프로필 빌드)

김춘덕⸝ဗီူ⸜ — Wed, 20 May 2026 21:08:52 +0900

인트로

레거시 Spring Framework 기반 프로젝트를 Spring Boot 3와 Gradle 기반으로 고도화하면서

GitLab CI/CD 빌드 환경을 맞춰야 하는 일이 생겼다.

처음에는 단순히 “JDK 버전과 Gradle 버전만 알려주면 되는 일”이라고 생각했다.

하지만 메일을 다시 읽고 .gitlab-ci.yml을 따라가다 보니

내가 제대로 이해해야 하는 것은 빌드 도구 버전이 아니라

소스가 어떤 서버에서 빌드되고, 어떤 프로필로 WAR가 만들어지고, 어떤 경로로 운영 서버까지 이동하는지였다.

이 글은 사내 프로젝트의 실제 값은 모두 익명화하고, GitLab CI/CD와 Gradle 프로필 빌드를

이해해 간 과정을 공개 가능한 수준으로 정리한 기록이다.

개발환경

구분	AS-IS	TO-BE
Java	Java 1.7 계열	Java 17
프레임워크	Spring Framework 4 계열	Spring Boot 3 계열
빌드 도구	Maven	Gradle
배포 단위	WAR	WAR
CI/CD	일부 수동 빌드/배포	GitLab CI/CD 기반 자동화
운영 방식	운영 서버 직접 배포	빌드 산출물 생성 후 운영 공유 저장소를 거쳐 배포

문제 상황

CI/CD 담당자로부터 빌드 환경을 맞추기 위한 요청을 받았다. 요청의 핵심은 다음과 같았다.

개발용 빌드 실행 서버에서 WAR 파일을 생성한 뒤,
운영 공유 저장소를 거쳐 운영 서버의 배포 경로로 복사하는 구조다.
기존 Maven 빌드 때처럼, 이번 Gradle 빌드도
개발자 로컬 환경과 빌드 실행 서버 환경을 맞추고 싶다.
Gradle 빌드에 필요한 환경 정보를 공유해 달라.

처음에는 이 문장을 보고 세 가지가 헷갈렸다.

“개발용 빌드 실행 서버”가 내가 평소 접속하는 DEV 서버와 같은 의미인지 헷갈렸다.
예시로 받은 java -version, mvn -version 결과가 빌드 서버의 값인지 담당자 로컬 PC의 값인지 헷갈렸다.
.gitlab-ci.yml 안에 git pull이 없는데, GitLab Runner가 어떻게 최신 소스를 받아 빌드하는지 몰랐다.

이때 내가 놓친 핵심은 GitLab CI/CD에서는 개발자 PC,

GitLab 서버, GitLab Runner가 설치된 서버,

운영 서버의 역할이 서로 다르다는 점이었다.

[개발자 PC]
  - git push

[GitLab 서버]
  - push 이벤트 감지
  - .gitlab-ci.yml 해석
  - Runner에 job 할당

[빌드 실행 서버]
  - GitLab Runner가 job 실행
  - 소스 checkout
  - Gradle 빌드
  - WAR artifact 생성

[운영 서버 A/B]
  - WAR 교체
  - 애플리케이션 재기동
  - 헬스체크

즉 “빌드 환경을 맞춘다”는 말은 단순히 내 PC 정보를 알려주는 일이 아니었다.

내 PC에서 성공하는 빌드가 GitLab Runner가 실행되는 서버에서도

같은 방식으로 성공하도록 보장하는 작업이었다.

1번째 시도: 담당자 로컬 PC 환경을 빌드 서버 환경으로 이해하기 (실패)

시도한 이유

처음에는 요청 메일에 포함된 명령 결과를 보고, 그것이 빌드 서버의 환경이라고 생각했다.

C:\Users\[계정]>java -version
openjdk version "17"

C:\Users\[계정]>mvn -version
Apache Maven 3.x.x

그래서 “Java 17은 이미 맞춰져 있으니 Gradle만 확인하면 되겠다”고 답하려고 했다.

문제점

다시 보니 프롬프트가 Windows 형식이었다.

C:\Users\[계정]>

반면 실제 빌드와 배포가 일어나는 서버는 Linux 계열 서버였다.

이 값은 빌드 실행 서버의 값이 아니라, 담당자 로컬 PC에서 확인한 값이었다.

이 상태로 답했다면 “빌드 서버에는 Java 17이 있다”고 잘못 전제했을 수 있었다.

빌드 환경 확인에서 가장 위험한 실수는 어디에서 실행한 명령인지 확인하지 않고 결과만 보는 것이다.

배운 점
버전 확인 결과를 공유받으면, 먼저 실행 위치를 확인해야 한다.
java -version보다 중요한 질문은 “이 명령을 어느 서버에서 실행했는가”다.

2번째 시도: GitLab Runner가 하는 일을 직접 따라가기 (성공)

시도한 이유

.gitlab-ci.yml에는 git pull 명령이 보이지 않았다.

그런데도 GitLab CI/CD에서는 push한 코드가 빌드 대상이 된다.

이 부분을 이해하지 못하면, 빌드 실행 서버의 작업 디렉터리와 최신 소스 반영 방식을 계속 오해할 수밖에 없었다.

확인한 내용

GitLab Runner는 job을 실행하기 전에 저장소 준비 단계를 수행한다.

프로젝트 설정과 Runner 설정에 따라 clone, fetch, none, empty 같은 Git 전략을 사용할 수 있다.

우리 프로젝트에서는 기존 작업 디렉터리를 재사용하면서 변경분을 가져오는 방식으로 동작하고 있었다.

공개용으로 단순화하면 흐름은 다음과 같다.

1. 개발자가 main 또는 develop 브랜치에 push한다.
2. GitLab 서버가 .gitlab-ci.yml의 rules를 평가한다.
3. 조건이 맞으면 build-runner 태그를 가진 Runner에 job을 할당한다.
4. Runner가 빌드 실행 서버의 작업 디렉터리에서 소스를 준비한다.
5. Runner가 script 블록에 적힌 Gradle 명령을 실행한다.
6. 생성된 WAR 파일을 GitLab artifact로 업로드한다.
7. deploy job이 artifact를 내려받아 운영 배포를 진행한다.

이제 .gitlab-ci.yml에 git pull이 없어도 최신 소스로 빌드되는 이유가 이해됐다.

script 블록은 전체 CI 작업 중 “내가 직접 적은 명령”에 해당하고, 그 앞뒤로 Runner가 수행하는 준비 단계와 정리 단계가 존재한다.

결과

CI/CD가 더 이상 “GitLab 안에서 알아서 되는 일”처럼 보이지 않았다. GitLab Runner는 GitLab 서버의 지시를 받아, 정해진 서버에서 정해진 명령을 실행하는 실행자였다.

배운 점
.gitlab-ci.yml을 읽을 때는 script 블록만 보면 안 된다.
Runner가 job을 받기 전후로 수행하는 저장소 준비, artifact 처리, cache 처리까지 함께 봐야 한다.

3번째 시도: 운영 프로필을 하나로 묶어 빌드하기 (실패 직전)

시도한 이유

처음 CI 설정을 봤을 때 운영 빌드 프로필이 하나로 잡혀 있었다.

variables:
  APP_MODULE: "sample-web"
  PROFILE_PROD: "prod"
  GRADLE_OPTS: "-Dorg.gradle.daemon=false -Dorg.gradle.jvmargs=-Xmx2g"
  GRADLE_USER_HOME: "$CI_PROJECT_DIR/.gradle"
  ARTIFACT_GLOB: "sample-web/build/libs/*.war"

build:sample-web:prod:
  stage: build
  tags:
    - build-runner
  script:
    - chmod +x ./gradlew
    - ./gradlew :${APP_MODULE}:clean :${APP_MODULE}:build -Pprofile=${PROFILE_PROD}

겉으로 보기에는 자연스러웠다. 운영 환경이니 prod 프로필로 빌드하면 될 것 같았다.

문제점

문제는 Gradle에서 프로필별 리소스를 가져오는 방식이었다.

프로젝트의 build.gradle은 공개용으로 단순화하면 다음 구조였다.

def profile = project.hasProperty("profile") ? project.getProperty("profile") : "local"

sourceSets {
    main {
        resources {
            srcDir "src/main/resources"
            srcDir "src/main/resources-${profile}"
        }
    }
}

이 구조에서는 -Pprofile=prod로 빌드하면

Gradle이 다음 디렉터리를 리소스 대상으로 추가한다.

src/main/resources
src/main/resources-prod

그런데 실제 프로젝트에는 운영 서버별 리소스 디렉터리가 따로 있었다.

sample-web/src/main/
├── resources
├── resources-local
├── resources-dev
├── resources-prod-a
└── resources-prod-b

resources-prod 디렉터리가 없다면 빌드가 바로 실패한다고 단정할 수는 없다.

Gradle은 존재하지 않는 리소스 디렉터리를 조용히 지나갈 수 있기 때문이다.

더 위험한 점은 빌드는 성공했는데 운영에 필요한 설정 파일이 WAR 안에 빠질 수 있다는 것이었다.

예를 들어 운영 서버 A와 운영 서버 B가 서로 다른 외부 연동 주소나 서버별 설정을 사용한다면,

하나의 prod 프로필로 만든 WAR를 두 서버에 그대로 배포하는 방식은 맞지 않을 수 있다.

배운 점
Gradle의 -Pprofile=prod는 Spring의 spring.profiles.active=prod와 같은 개념으로 자동 연결되는 값이 아니다. build.gradle에서 그 값을 어떻게 사용하는지 반드시 확인해야 한다.

최종 해결: 운영 서버별 Gradle 프로필 빌드로 분리하기

최종적으로는 운영 서버별 리소스 디렉터리 구조에 맞춰

빌드 job도 분리하는 방향이 가장 안전하다고 판단했다.

공개용으로 단순화한 예시는 다음과 같다.

stages:
  - build
  - deploy

variables:
  APP_MODULE: "sample-web"
  GRADLE_OPTS: "-Dorg.gradle.daemon=false -Dorg.gradle.jvmargs=-Xmx2g"
  GRADLE_USER_HOME: "$CI_PROJECT_DIR/.gradle"

cache:
  key: "${CI_PROJECT_NAME}-${CI_COMMIT_REF_SLUG}"
  paths:
    - .gradle/wrapper
    - .gradle/caches

.build_template: &build_template
  stage: build
  tags:
    - build-runner
  script:
    - chmod +x ./gradlew
    - ./gradlew :${APP_MODULE}:clean :${APP_MODULE}:build -Pprofile=${BUILD_PROFILE}
  artifacts:
    name: "${BUILD_PROFILE}-${CI_PROJECT_NAME}-${CI_COMMIT_SHORT_SHA}"
    paths:
      - ${APP_MODULE}/build/libs/*.war
    expire_in: 30 days

build:sample-web:prod-a:
  <<: *build_template
  variables:
    BUILD_PROFILE: "prod-a"
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      changes:
        - sample-web/**/*
      when: on_success
    - when: never

build:sample-web:prod-b:
  <<: *build_template
  variables:
    BUILD_PROFILE: "prod-b"
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      changes:
        - sample-web/**/*
      when: on_success
    - when: never

배포 job도 각 서버가 자신에게 맞는 artifact를 사용하도록 분리한다.

.deploy_template: &deploy_template
  stage: deploy
  tags:
    - build-runner
  resource_group: "production-deploy-lock"
  environment:
    name: production
  script:
    - test -n "$TARGET_HOST"
    - test -n "$DEPLOY_USER"
    - WAR_FILE=$(find "${APP_MODULE}/build/libs" -name "*.war" | head -n 1)
    - test -n "$WAR_FILE"
    - scp "$WAR_FILE" "${DEPLOY_USER}@${TARGET_HOST}:/deployments/sample-web/new/ROOT.war"
    - ssh "${DEPLOY_USER}@${TARGET_HOST}" "/opt/sample-web/bin/deploy_app.sh"

deploy:sample-web:prod-a:
  <<: *deploy_template
  needs:
    - job: build:sample-web:prod-a
      artifacts: true
  variables:
    TARGET_HOST: "$PROD_SSH_HOST_A"
  when: manual

deploy:sample-web:prod-b:
  <<: *deploy_template
  needs:
    - job: build:sample-web:prod-b
      artifacts: true
    - job: deploy:sample-web:prod-a
  variables:
    TARGET_HOST: "$PROD_SSH_HOST_B"

여기서 중요한 점은 IP, 계정, 비밀번호, SSH 키 같은 민감 정보가

.gitlab-ci.yml에 직접 들어가지 않는다는 것이다.

이런 값은 GitLab CI/CD Variables에 저장하고,

yml에서는 $PROD_SSH_HOST_A처럼 변수명만 참조한다.

또 하나의 안전장치는 resource_group이다.

운영 배포처럼 동시에 실행되면 위험한 job에는 같은 resource group을 지정해,

같은 환경으로 향하는 배포가 겹치지 않도록 제한할 수 있다.

다만 이 구조만으로 완전한 무중단 배포가 보장된다고 말할 수는 없다.

운영 서버 A를 재기동하는 동안 운영 서버 B가 트래픽을 정상 처리하려면

로드밸런서, 헬스체크, 세션 처리 방식까지 함께 맞아야 한다.

그래서 이 글에서는 “무중단 배포”라고 단정하기보다

운영 서버 A/B를 순차적으로 배포하는 구조라고 정리하는 것이 정확하다.

Maven 프로필과 Gradle 프로필이 달랐던 지점

이번에 가장 크게 배운 부분은 Maven과 Gradle의 프로필 처리 방식 차이였다.

Maven에서는 pom.xml 안에 <profiles>를 정의하고,

특정 프로필이 활성화되면 해당 설정이 빌드 모델에 반영된다.

<profiles>
  <profile>
    <id>prod-a</id>
    <properties>
      <db.url>jdbc:mariadb://[DB_HOST_A]:3306/app</db.url>
    </properties>
  </profile>

  <profile>
    <id>prod-b</id>
    <properties>
      <db.url>jdbc:mariadb://[DB_HOST_B]:3306/app</db.url>
    </properties>
  </profile>
</profiles>

반면 이번 Gradle 프로젝트에서는 -Pprofile=prod-a 값을

build.gradle에서 직접 읽고, 그 값으로 리소스 디렉터리를 조립하고 있었다.

./gradlew :sample-web:build -Pprofile=prod-a

포함 대상:
- src/main/resources
- src/main/resources-prod-a

그래서 Maven을 오래 사용한 사람에게는 “

프로필별 빌드 파일이 어디 있느냐”는 질문이 자연스러울 수 있었다.

하지만 이 프로젝트의 Gradle 구조에서는 프로필별 빌드 파일이 따로 있는 것이 아니라

프로필 값에 맞는 리소스 디렉터리를 동적으로 포함하는 방식이었다.

구분	Maven	Gradle
프로필 활성화	`mvn -Pprod-a`	`./gradlew -Pprofile=prod-a`
설정 위치	`pom.xml`의 `<profiles>`	`build.gradle`의 로직과 리소스 디렉터리
환경별 리소스	filtering으로 값 치환	`resources-${profile}` 디렉터리 포함
확인 포인트	활성화된 profile의 properties	`sourceSets`와 `processResources` 대상

이 차이를 이해하고 나니, CI/CD 담당자에게 공유해야 할 정보도 명확해졌다.

필요한 것은 “prod 빌드 명령어” 하나가 아니라,
운영 서버별로 어떤 Gradle profile 값을 사용해야 하는지다.

빌드 실행 서버를 DEV 서버와 함께 쓰는 구조에서 주의할 점

이번 환경에서는 별도 빌드 전용 서버가 아니라,

개발용 서버와 같은 장비에서 GitLab Runner가 함께 동작하는 구조였다.

이 방식은 현실적인 장점이 있지만, 주의할 점도 분명했다.

항목	주의할 점
CPU/메모리	Gradle 빌드 중 애플리케이션 서버 성능에 영향을 줄 수 있다.
디스크	Gradle cache, GitLab 작업 디렉터리, WAR artifact가 누적될 수 있다.
권한	Runner 계정이 필요한 배포 경로에 접근할 수 있어야 한다.
장애 영향	개발용 서버 장애가 CI/CD 장애로 이어질 수 있다.

그래서 CI 설정에는 최소한의 안전장치가 필요했다.

variables:
  GRADLE_OPTS: "-Dorg.gradle.daemon=false -Dorg.gradle.jvmargs=-Xmx2g"
  GRADLE_USER_HOME: "$CI_PROJECT_DIR/.gradle"

resource_group: "production-deploy-lock"

-Dorg.gradle.daemon=false는 CI처럼 일회성 빌드가 반복되는 환경에서

Gradle 데몬을 계속 남기지 않기 위한 설정이다.

-Xmx2g는 빌드 JVM의 메모리 상한을 두기 위한 설정이다.

GRADLE_USER_HOME을 프로젝트 디렉터리 아래로 잡으면

GitLab cache 설정과 함께 관리하기 쉬워진다.

다만 cache는 빌드 속도를 높이는 최적화 수단이지, 항상 존재한다고 가정하면 안 된다.

배운 점

첫째, CI/CD에서 “환경을 맞춘다”는 말은 JDK 버전 하나를 맞춘다는 뜻이 아니었다.

개발자 로컬, GitLab Runner, 빌드 명령어, 리소스 프로필, artifact 경로가 모두 같은 전제 위에서 움직이도록 맞추는 일이었다.

둘째, .gitlab-ci.yml은 배포팀만 보는 파일이 아니었다.

애플리케이션을 개발하는 사람도 최소한 빌드 job과 deploy job의 흐름은 읽을 수 있어야 했다.

특히 어떤 프로필로 빌드되는지는 런타임 장애와 바로 연결될 수 있었다.

셋째, Gradle의 -Pprofile 값은 프로젝트마다 의미가 다르다.

Spring profile과 같은 이름을 쓴다고 해서 자동으로 같은 동작을 한다고 보면 안 된다.

build.gradle에서 그 값이 어디에 쓰이는지 확인해야 한다.

넷째, “잘 모르겠다”고 멈춰서 확인한 덕분에 더 큰 실수를 피할 수 있었다.

담당자 로컬 PC의 버전 정보를 빌드 서버 정보로 착각한 것도, prod 프로필 하나로

운영 서버 A/B를 모두 빌드할 뻔한 것도, 다시 확인하지 않았다면 그냥 지나쳤을 수 있었다.

이번 일을 통해 CI/CD는 더 이상 “운영 쪽에서 알아서 돌아가는 영역”이 아니라,

내가 읽고 검증해야 하는 코드라는 감각이 생겼다.

결국 파이프라인도 코드이고, 빌드도 코드이고, 배포도 코드다.

참고 링크

주니어 백엔드 개발자가 반드시 알아야 할 실무 지식 : 신입이 알아야 할 DB 성능·풀스캔·인덱스 9가지

김춘덕⸝ဗီူ⸜ — Sat, 16 May 2026 23:10:15 +0900

인트로

최근 주니어 백엔드 개발자가 반드시 알아야 할 실무 지식을 읽으면서

DB 성능과 인덱스에 대한 내용을 다시 정리하게 됐다.

처음에는 DB 성능 문제가 생기면 “인덱스를 추가하면 되지 않을까?”라고 단순하게 생각했다.

하지만 책을 읽고 실무 상황에 대입해보니, 인덱스는 정답이라기보다

조회 패턴에 맞춰 설계해야 하는 도구에 가까웠다.

특히 풀스캔, LIKE 검색, COUNT, 정규화와 비정규화,

오래된 데이터 분리, 캐시, 장비 확장은 각각 따로 떨어진 주제가 아니었다.

결국 하나의 질문으로 이어졌다.

지금 이 API는 DB에서 읽을 필요가 있는 데이터만 읽고 있는가?

이번 글은 풀스캔을 줄이기 위해 내가 먼저 확인해야 할
DB 성능 항목 9가지를 정리한 기록이다.

특정 회사 시스템을 그대로 설명한 글은 아니고,
실무에서 자주 만나는 조회 API를 기준으로 재구성한 예시다.

수집 대상

이 글은 ORM이나 SQL 매퍼 사용법보다는

순수 DB 레벨에서 조회 성능을 떨어뜨리는 패턴과 대응 기준을 정리한 글이다.

내가 특히 기억해두려는 항목은 아래 9가지다.

번호	항목	먼저 볼 질문
1	풀스캔	실행 계획에서 읽는 row가 과하게 많지 않은가
2	단일 인덱스와 복합 인덱스	조회 조건이 어떤 컬럼 조합으로 반복되는가
3	`LIKE` 검색	일반 인덱스로 처리할 검색인가, 전문 검색이 필요한가
4	커버링 인덱스	테이블 row 접근 없이 인덱스만으로 끝낼 수 있는가
5	인덱스 개수	읽기 성능 때문에 쓰기 비용을 과하게 늘리고 있지 않은가
6	정규화와 비정규화	조인 비용과 정합성 비용 중 무엇이 더 큰가
7	시간 조건	기본 조회 범위가 너무 넓지 않은가
8	`COUNT` 집계	전체 개수가 정말 필요한가
9	데이터 분리, 캐시, 장비 확장	쿼리 튜닝 이후에도 구조적 한계가 남는가

개발환경

예시는 아래 환경을 기준으로 작성했다.

구분	내용
언어	Java 17
프레임워크	Spring Boot 3 계열
DB	MySQL 8.x 기준 예시
조회 방식	게시글 목록, 검색, 상세 조회
확인 도구	`EXPLAIN`, 실행 시간 로그, slow query log

DBMS마다 옵티마이저와 인덱스 동작은 다를 수 있다.

그래서 이 글의 SQL은 개념을 설명하기 위한 예시이며, 실제 적용 전에는

반드시 운영 DB와 유사한 데이터 분포에서 실행 계획을 확인해야 한다.

문제 상황

게시글 목록 API가 있다고 가정한다.

처음에는 아래처럼 검색어, 상태, 작성 기간을 모두 받을 수 있는 API를 만들었다.

SELECT id, title, writer_name, status, created_at
FROM article
WHERE status = 'PUBLISHED'
  AND title LIKE '%spring%'
  AND created_at >= '2026-05-01 00:00:00'
ORDER BY created_at DESC
LIMIT 20 OFFSET 0;

기능만 보면 자연스러운 쿼리다. 하지만 데이터가 많아지면 문제가 생길 수 있다.

status나 created_at에 인덱스가 있어도 title LIKE '%spring%' 조건은

일반적인 B-Tree 인덱스로 효율적인 검색을 하기 어렵다.

앞에 %가 붙으면 문자열의 시작점을 알 수 없기 때문이다.

결국 DB는 많은 row를 읽고, 그중에서 조건에 맞는 데이터를 골라내야 할 수 있다.

이때 실행 계획에서 type=ALL이 보이면 전체 테이블을 훑는 풀 테이블 스캔 가능성을 의심해야 한다.

내가 처음 헷갈렸던 부분은

“컬럼에 인덱스가 있으면 무조건 빠르다”는 생각이었다.

하지만 인덱스가 있어도 조건 형태, 컬럼 순서, 조회 범위,

데이터 분포에 따라 옵티마이저는 인덱스를 쓰지 않을 수 있다.

1번째 시도: 검색 조건마다 인덱스 추가하기

가장 먼저 떠올린 방법은 조건에 등장하는 컬럼마다 인덱스를 추가하는 것이었다.

CREATE INDEX idx_article_status ON article(status);
CREATE INDEX idx_article_title ON article(title);
CREATE INDEX idx_article_created_at ON article(created_at);

겉으로 보면 괜찮아 보인다. WHERE에 등장하는 컬럼마다 인덱스가 있기 때문이다.

하지만 이 방식은 문제를 정확히 해결하지 못할 수 있다.

첫째, 단일 인덱스 여러 개가 항상 복합 인덱스 하나와 같은 효과를 내지는 않는다.

DB 옵티마이저가 index merge를 선택할 수도 있지만,

자주 실행되는 핵심 조회라면 조회 패턴에 맞춘 복합 인덱스가 더 명확할 때가 많다.

둘째, LIKE '%keyword%' 검색은 일반적인 B-Tree 인덱스와 잘 맞지 않는다.

LIKE 'spring%'처럼 앞부분이 고정된 검색은

범위 검색으로 인덱스를 활용할 가능성이 있지만,

%spring%처럼 앞뒤를 모두 열어둔 검색은 일반 인덱스로 시작 위치를 잡기 어렵다.

셋째, 인덱스가 많아질수록 쓰기 비용이 늘어난다.

INSERT, UPDATE, DELETE가 발생할 때 테이블 데이터뿐 아니라

인덱스도 함께 갱신해야 한다.

그래서 인덱스는 많이 만들수록 좋은 것이 아니라 필요한 만큼만 만들어야 한다.

예를 들어 이미 (status, created_at) 복합 인덱스가 있는데

status 단일 인덱스를 또 추가하는 경우를 생각할 수 있다.

MySQL에서는 복합 인덱스의 선행 컬럼을 활용할 수 있기 때문에 단일 인덱스가 중복일 수 있다.

물론 인덱스 크기, 조회 빈도, 옵티마이저 선택에 따라 예외가 있을 수 있으므로

실행 계획과 실제 사용량을 보고 판단해야 한다.

접근	장점	한계
조건 컬럼마다 단일 인덱스 추가	만들기 쉽다	실제 조회 패턴과 맞지 않을 수 있다
무조건 복합 인덱스 추가	특정 조회에는 빠를 수 있다	컬럼 순서가 틀리면 효과가 작다
전문 검색 없이 `LIKE '%keyword%'` 유지	구현이 단순하다	데이터가 많아지면 풀스캔 가능성이 커진다

이 시도에서 배운 점은 단순했다.

인덱스는 컬럼 기준이 아니라 조회 패턴 기준으로 설계해야 한다.

2번째 시도: 조회 패턴 기준으로 복합 인덱스 설계하기

다음으로는 실제 API가 어떤 방식으로 조회되는지 먼저 정리했다.

예를 들어 게시글 목록 조회의 핵심 패턴이 아래와 같다고 가정한다.

공개 상태의 게시글만 조회한다.
최신순으로 정렬한다.
대부분 최근 3개월 데이터만 조회한다.
한 페이지에 20개씩 가져온다.

이 경우에는 단순히 status, created_at 각각에 인덱스를 거는 것보다

아래처럼 자주 함께 쓰이는 조건과 정렬을 고려한 복합 인덱스를 검토할 수 있다.

CREATE INDEX idx_article_status_created_at
ON article(status, created_at DESC);

그리고 조회 쿼리도 범위를 제한한다.

SELECT id, title, writer_name, status, created_at
FROM article
WHERE status = 'PUBLISHED'
  AND created_at >= '2026-02-01 00:00:00'
  AND created_at <  '2026-05-01 00:00:00'
ORDER BY created_at DESC
LIMIT 20;

복합 인덱스에서는 컬럼 순서가 중요하다.

MySQL 기준으로 (status, created_at) 인덱스는 status만 쓰는 조회나

status + created_at을 함께 쓰는 조회에 활용될 수 있다.

하지만 created_at만 조건으로 쓰는 조회에는 같은 방식으로 잘 활용되지 않을 수 있다.

선행 컬럼을 고를 때는 카디널리티도 함께 본다.

카디널리티는 값의 종류가 얼마나 다양한지를 의미한다.

보통 후보 row를 많이 줄일 수 있는 컬럼이 앞에 오면 유리하지만,

실제 인덱스 순서는 동등 조건, 범위 조건, 정렬 조건, 데이터 분포를 함께 보고 결정해야 한다.

이때 중요한 것은 EXPLAIN으로 확인하는 것이다.

EXPLAIN
SELECT id, title, writer_name, status, created_at
FROM article
WHERE status = 'PUBLISHED'
  AND created_at >= '2026-02-01 00:00:00'
  AND created_at <  '2026-05-01 00:00:00'
ORDER BY created_at DESC
LIMIT 20;

실행 계획에서 특히 아래 항목을 먼저 본다.

항목	확인할 내용
`type`	`ALL`이면 풀 테이블 스캔 가능성을 의심한다
`key`	실제 선택된 인덱스가 무엇인지 확인한다
`rows`	DB가 읽을 것으로 예상하는 row 수를 확인한다
`Extra`	`Using index`, `Using filesort`, `Using temporary` 등을 확인한다

여기서 Using index는 “인덱스를 아예 안 쓴다”는 뜻이 아니다.

MySQL에서는 쿼리에 필요한 컬럼을 인덱스만으로 가져올 수 있을 때

Using index가 표시될 수 있다. 흔히 말하는 커버링 인덱스 상황이다.

예를 들어 아래 쿼리는 필요한 컬럼이 모두 인덱스에 포함되어 있다면

테이블 row까지 추가로 접근하지 않고 인덱스에서 값을 가져올 수 있다.

CREATE INDEX idx_article_status_created_id
ON article(status, created_at DESC, id);

SELECT id, status, created_at
FROM article
WHERE status = 'PUBLISHED'
ORDER BY created_at DESC
LIMIT 20;

반대로 인덱스에 없는 컬럼을 함께 조회하면

DB는 인덱스로 후보 row를 찾은 뒤 실제 테이블 row에 접근해야 할 수 있다.

SELECT id, title, content, status, created_at
FROM article
WHERE status = 'PUBLISHED'
ORDER BY created_at DESC
LIMIT 20;

content가 인덱스에 없다면 이 값을 읽기 위해 테이블 row 접근이 필요하다.

그렇다고 모든 조회 컬럼을 인덱스에 넣어야 한다는 뜻은 아니다.

인덱스 크기와 쓰기 비용이 커지기 때문에, 목록 화면처럼 정말 자주 호출되고

필요한 컬럼이 적은 조회에만 신중하게 검토해야 한다.

그래서 목록 조회에서는 SELECT *를 습관적으로 쓰지 않는 것이 중요하다.

화면에 필요한 컬럼만 고르면 네트워크 전송량도 줄고, 커버링 인덱스를 검토할 여지도 생긴다.

3번째 시도: `LIKE` 검색을 전문 검색으로 분리하기

검색어가 제목이나 본문 중간에 포함되는지를 찾아야 한다면

LIKE '%keyword%'는 기능 요구사항에는 맞지만

성능 요구사항에는 불리할 수 있다.

이때 선택지는 크게 세 가지다.

선택지	적합한 상황	주의할 점
`LIKE 'keyword%'`	접두어 검색이면 충분한 경우	중간 단어 검색에는 맞지 않는다
DB 전문 검색 인덱스	DB 안에서 검색을 처리하고 싶은 경우	형태소, 언어, stopword, 정렬 품질을 확인해야 한다
Elasticsearch 같은 검색 엔진	검색 품질, 랭킹, 다중 필드 검색이 중요한 경우	동기화 구조와 운영 복잡도가 늘어난다

MySQL에서는 FULLTEXT 인덱스와

MATCH() AGAINST() 문법을 사용할 수 있다.

CREATE FULLTEXT INDEX ft_article_title_content
ON article(title, content);

SELECT id, title, created_at
FROM article
WHERE MATCH(title, content) AGAINST ('spring boot' IN NATURAL LANGUAGE MODE)
ORDER BY created_at DESC
LIMIT 20;

Oracle을 사용한다면 Oracle Text 같은 기능을 검토할 수 있다.

검색 품질과 확장성이 더 중요하다면 Elasticsearch 같은 별도 검색 엔진을 두는 방식도 있다.

다만 검색 엔진을 붙인다고 모든 문제가 끝나는 것은 아니다.

DB와 검색 엔진 사이의 데이터 동기화, 장애 시 재처리,

검색 결과와 원본 데이터의 정합성, 색인 지연을 함께 설계해야 한다.

내가 정리한 기준은 이렇다.

단순 관리자 화면에서 가끔 쓰는 검색이면 LIKE를 유지할 수도 있다.

하지만 사용자가 자주 검색하고 데이터가 계속 늘어나는 핵심 기능이라면

일반 인덱스가 아니라 전문 검색 구조를 검토해야 한다.

정규화와 비정규화는 언제 고민해야 할까?

정규화는 데이터 중복을 줄이고 변경 정합성을 지키기 위한 설계다.

예를 들어 사용자 이름을 user 테이블에만 두고 게시글에서는

user_id만 참조하면, 사용자 이름이 바뀌어도 한 곳만 수정하면 된다.

하지만 조회 API가 매번 여러 테이블을 조인해야 하고,

그 조회가 매우 자주 호출된다면 비정규화를 검토할 수 있다.

예를 들어 게시글 목록에서 항상 작성자 이름이 필요하다고 가정한다.

SELECT a.id, a.title, u.name, a.created_at
FROM article a
JOIN users u ON a.writer_id = u.id
WHERE a.status = 'PUBLISHED'
ORDER BY a.created_at DESC
LIMIT 20;

이 조인이 성능 병목이 되고 작성자 이름 변경이 드문 요구사항이라면,

article.writer_name처럼 조회용 컬럼을 중복 저장하는 방법을 검토할 수 있다.

구분	정규화	비정규화
목적	중복 제거, 정합성 유지	조회 성능, 쿼리 단순화
장점	수정 지점이 적다	조인을 줄일 수 있다
단점	조회 시 조인이 늘 수 있다	데이터 불일치 가능성이 생긴다
적용 기준	변경이 잦고 정합성이 중요한 데이터	조회가 매우 많고 변경이 적은 데이터

비정규화는 성능 최적화 수단이지만, 동시에 정합성 비용을 만드는 선택이다.

그래서 “조인이 싫다”가 아니라 “이 조회가 병목이고,

중복 데이터의 동기화 규칙을 관리할 수 있다”는 근거가 있을 때 적용해야 한다.

조회 범위를 줄이는 것도 성능 개선이다

인덱스를 잘 설계해도 조회 범위가 너무 넓으면

DB가 읽어야 할 데이터가 많아진다.

실무에서는 “전체 기간 조회”가 생각보다 위험하다.

사용자는 단순히 검색 버튼을 눌렀지만,

서버 입장에서는 몇 년치 데이터를 대상으로 정렬과 필터링을 수행할 수 있다.

그래서 목록 API에는 기간 조건을 기본값으로 두는 것이 도움이 된다.

SELECT id, title, status, created_at
FROM article
WHERE status = 'PUBLISHED'
  AND created_at >= CURRENT_DATE - INTERVAL 3 MONTH
ORDER BY created_at DESC
LIMIT 20;

조회 범위를 제한하면 인덱스가 후보 row를 줄이기 쉬워진다.

또한 사용자도 실제로 필요한 최근 데이터부터 확인하게 된다.

물론 모든 화면에 임의로 기간 제한을 걸면 안 된다.

감사, 정산, 법적 보관 데이터처럼 전체 기간 조회가 필요한 기능은

별도 화면이나 배치성 조회로 분리하는 편이 낫다.

전체 개수를 세지 않는 것도 방법이다

페이징을 만들 때 습관적으로 전체 개수를 함께 조회하는 경우가 있다.

SELECT COUNT(*)
FROM article
WHERE status = 'PUBLISHED'
  AND title LIKE '%spring%';

문제는 COUNT도 공짜가 아니라는 점이다.

특히 검색 조건이 복잡하고 필터링 대상이 많으면 DB는 개수를 구하기 위해 많은 row를 확인해야 한다.

사용자에게 반드시 “총 12,345건”이 필요한지 먼저 확인해야 한다.

필요하지 않다면 hasNext 방식으로 바꿀 수 있다.

SELECT id, title, created_at
FROM article
WHERE status = 'PUBLISHED'
ORDER BY created_at DESC
LIMIT 21;

한 페이지 크기가 20개라면 21개를 조회해서 다음 페이지 존재 여부만 판단한다.

이렇게 하면 전체 개수를 세지 않아도 된다.

이 방식은 무한 스크롤이나 “더보기” UI와 잘 맞는다.

반대로 정확한 전체 페이지 수가 꼭 필요한 관리자 화면에서는

COUNT를 유지하되, 검색 조건과 인덱스를 더 신중하게 봐야 한다.

정확한 숫자가 중요하지 않은 화면이라면 추정값이나 캐시를 쓰는 방법도 있다.

예를 들어 통계 테이블에 일정 주기로 집계한 값을 저장하거나,

자주 반복되는 카운트 결과를 짧은 시간 동안 캐싱할 수 있다.

다만 이 경우에는 사용자에게 보여주는 숫자가

실시간 정확값이 아닐 수 있다는 점을 화면 요구사항과 맞춰야 한다.

오래된 데이터는 삭제하거나 분리 보관해야 한다

성능 문제는 쿼리만의 문제가 아닐 때가 많다.

테이블이 너무 커져서 어떤 조회를 해도 부담이 되는 상황이 있다.

예를 들어 로그인 이력, 알림 이력, API 호출 로그처럼 계속 쌓이는 데이터는

시간이 지나면 조회 빈도가 낮아진다.

이런 데이터는 보관 정책을 정하고 삭제하거나 별도 보관 테이블로 분리할 수 있다.

데이터	운영 테이블	보관 테이블
최근 3개월 로그인 이력	자주 조회	유지
3개월 이전 로그인 이력	거의 조회하지 않음	archive 테이블 또는 별도 저장소
법적 보관 대상	삭제 불가	접근 빈도에 맞춰 분리

삭제나 분리는 기능팀 혼자 결정할 수 없다.

보관 기간, 감사 요건, 장애 분석 필요성, 개인정보 정책을 함께 확인해야 한다.

DB 장비 확장과 캐시는 마지막 카드가 아니다

DB 성능을 이야기하면 장비 확장이나 캐시 서버도 자주 나온다.

장비 확장은 분명 효과가 있다.

CPU, 메모리, 디스크 I/O가 부족한 상황에서는 스케일업이나

읽기 전용 복제 DB 구성이 필요할 수 있다.

캐시도 강력하다.

자주 조회되지만 자주 바뀌지 않는 데이터는 Redis 같은

별도 캐시 서버에 두면 DB 부하를 줄일 수 있다.

하지만 둘 다 쿼리와 데이터 구조를 보지 않고

바로 적용하면 문제를 늦게 발견하게 만들 수 있다.

방법	효과	먼저 확인할 점
DB 스케일업	CPU, 메모리, I/O 여유 증가	비효율 쿼리가 그대로 남는지 확인
Read replica	읽기 트래픽 분산	복제 지연과 읽기 정합성 확인
Redis 캐시	반복 조회 부하 감소	만료 정책과 데이터 무효화 전략 확인
검색 엔진	검색 부하 분리	색인 동기화와 장애 복구 전략 확인

캐시는 특히 무효화 전략이 중요하다.

데이터를 수정했는데 캐시를 지우지 않으면 사용자는 오래된 값을 보게 된다.

그래서 캐시를 넣을 때는 “언제 저장할지”보다 “언제 지울지”를 먼저 설계해야 한다.

내가 기억하려는 우선순위는

쿼리 확인 → 인덱스 설계 → 데이터 분리 → 캐시 → 장비 확장이다.

인덱스도 확인하지 않은 상태에서 캐시나 장비 확장부터 적용하면,

느린 원인을 가린 채 운영 비용만 키울 수 있다.

최종 정리: DB 성능을 볼 때의 순서

내가 이번에 정리한 순서는 아래와 같다.

핵심은 인덱스를 먼저 만들기 전에 조회 패턴을 먼저 보는 것이다.

내가 기억하려는 기준은 아래와 같다.

풀스캔을 줄이려면 WHERE, ORDER BY, LIMIT을 함께 보고 인덱스를 설계한다.
복합 인덱스는 컬럼 순서가 중요하며, leftmost prefix를 이해해야 한다.
LIKE '%keyword%'는 일반 인덱스보다 전문 검색 구조가 필요한 신호일 수 있다.
인덱스에 포함된 컬럼만 조회하면 커버링 인덱스로 테이블 접근을 줄일 수 있다.
인덱스에 없는 컬럼까지 조회하면 후보 row를 찾은 뒤 실제 row 접근이 필요할 수 있다.
인덱스는 읽기 성능을 돕지만 쓰기 비용과 저장 공간 비용을 만든다.
비정규화는 조인을 줄일 수 있지만 데이터 불일치 비용을 만든다.
전체 개수가 꼭 필요하지 않다면 COUNT 대신 hasNext 방식을 검토한다.
오래된 데이터는 운영 테이블에서 계속 들고 있을수록 조회와 관리 비용이 커진다.
캐시와 장비 확장은 효과가 있지만, 비효율 쿼리를 덮는 방식으로 쓰면 안 된다.

배운 점

이번 내용을 정리하면서 DB 성능 개선은

“빠른 쿼리 하나 만들기”가 아니라는 생각이 들었다.

성능 문제는 보통 여러 층이 겹쳐서 생긴다. 조회 범위가 넓고,

검색 조건은 인덱스를 타기 어렵고, 전체 개수까지 세고,

오래된 데이터도 같은 테이블에 계속 쌓이면 느려질 수밖에 없다.

그래서 내가 실무에서 먼저 할 일은 인덱스를 추가하는 것이 아니라,

느린 API의 조회 패턴을 문장으로 설명하는 일이다.

이 API는 어떤 사용자가, 어떤 조건으로, 어느 기간의 데이터를, 몇 건이나 필요로 하는가?

이 질문에 답할 수 있어야 인덱스도 설계할 수 있고,

전문 검색도 검토할 수 있고, 캐시나 장비 확장도 근거 있게 이야기할 수 있다.

참고 링크

‍ Springframwork Mig 기록 : 화면에는 없는데 서버에는 필요한 값들 (feat. 세션 기반 파라미터)

김춘덕⸝ဗီူ⸜ — Tue, 28 Apr 2026 23:51:50 +0900

인트로

레거시 시스템을 Spring Boot 3 기반으로 옮기면서

Controller 응답 방식과 세션 접근 방식을 함께 정리했다.

처음에는 요청 파라미터만 잘 넘기면 기능이 그대로 동작할 거라고 생각했다.

그런데 일부 기능에서 NullPointerException이 발생했다.

이상했던 점은 화면에서 넘기는 값은 빠진 게 없어 보였다는 점이다.

화면에는 없지만 서버 로직에는 꼭 필요한 값이 있었다.

바로 세션에서 꺼내 쓰던 사용자 식별값이었다.

이번 글은 레거시 코드에서 암묵적으로 사용하던 세션 기반 값을 어떻게 추적했고

마이그레이션 후에는 어떻게 NPE를 방어했는지 정리한 기록이다.

개발환경

AS-IS	TO-BE
Java 1.7	Java 17
Spring Framework 4 계열	Spring Boot 3 계열
JSP + Spring MVC	JSP + Spring MVC
`ModelAndView` + jsonView	`Map<String, Object>` 직접 반환
레거시 세션 핸들러 직접 호출	세션 유틸리티 기반 접근

이 글의 예제 코드는 회사 소스코드가 아니다.

실제 업무에서 겪은 문제 흐름만 비슷하게 재구성한 독립 실행 예제다.

문제 상황

마이그레이션 중 특정 등록 API를 테스트했다.

요청에는 deviceName 같은 화면 입력값이 들어왔다.

그런데 서비스 로직에서는 요청값뿐 아니라
userSeq, empId 같은 사용자 식별값도 필요했다.

처음에는 프론트에서 파라미터를 누락한 줄 알았다.
하지만 JSP와 JavaScript를 확인해도 해당 값은 화면에서 보내는 값이 아니었다.

레거시 구조에서는 Controller가 세션에서 사용자 정보를 꺼내 DTO에 직접 채우고 있었다.

즉, 이 값들은 요청 파라미터가 아니라 세션 기반 파라미터였다.

내가 헷갈렸던 지점은 여기였다.

구분	화면에서 보이는가	서버에서 필요한가
`deviceName`	보인다	필요하다
`userSeq`	보이지 않는다	필요하다
`empId`	보이지 않는다	필요하다
`companyCode`	보이지 않는다	일부 로직에서 필요하다

결국 문제는 “파라미터가 안 넘어왔다”가 아니라
“세션에서 채워야 하는 값을 마이그레이션 과정에서 놓쳤다”에 가까웠다.

1번째 시도: 요청 파라미터만 확인하기 (실패)

시도한 이유

API가 실패하면 가장 먼저 요청값을 의심하게 된다.

나도 브라우저 네트워크 탭과 서버 로그에서 요청 파라미터를 먼저 확인했다.

화면에서 입력한 값은 정상적으로 넘어오고 있었다.

그래서 처음에는 name 속성 오타나 JavaScript 객체 생성 문제를 찾으려고 했다.

적용 방법

요청 파라미터를 기준으로만 보면 코드는 대략 이런 흐름이었다.

Map<String, String> requestParams = Map.of("deviceName", "phone");

String deviceName = requestParams.get("deviceName");

이 값은 정상적으로 존재했다.

문제점/한계

문제의 핵심은 요청 파라미터가 아니었다.

서버 로직은 deviceName만으로 동작하지 않았다.

등록 로직에는 “누가 등록했는가”가 필요했다.

이 정보는 화면에서 보내지 않고 로그인 이후 서버 세션에 저장된 값을 사용하고 있었다.

요청 파라미터만 보면 원인을 찾을 수 없었다.

배운 점
마이그레이션 QA에서 입력값을 확인할 때는 request parameter만 보면 안 된다. session attribute, request attribute, interceptor에서 주입하는 값까지 함께 봐야 한다.

2번째 시도: 세션에서 암묵적으로 채우던 값 추적하기 (성공)

시도한 이유

레거시 Controller를 다시 보니 요청값을 DTO에 넣은 뒤

세션 사용자 정보도 함께 DTO에 넣고 있었다.

즉, 화면에서는 보이지 않지만 Controller 안에서 조립되는 값이 있었다.

적용 방법

레거시 구조를 공개용 예제로 단순화하면 아래와 같다.

SessionUser sessionUser = LegacySessionHandler.getLoginInfo(request);

RegisterCommand command = new RegisterCommand(
        sessionUser.userSeq(),
        sessionUser.empId(),
        requestParams.get("deviceName")
);

이 코드는 세션이 항상 있다고 가정한다.

로그인 상태에서 정상 흐름만 테스트하면 문제가 없어 보인다.

하지만 세션이 없거나 만료된 상태에서 접근하면

sessionUser가 null이 되고, 바로 NPE가 발생한다.

Cannot invoke "SessionUser.userSeq()" because sessionUser is null

실제 업무에서도 이와 비슷하게

“화면에서 보이지 않는 값”이 세션에서 채워지고 있었다.

결과

원인은 프론트 파라미터 누락이 아니었다.

마이그레이션하면서 세션 접근 방식을 바꾸는 과정에서

세션 사용자 정보가 필요한 기능과 그렇지 않은 기능을 구분해야 했다.

배운 점
레거시 코드는 Controller 안에서 요청값과 세션값을 섞어 DTO를 만드는 경우가 많다. 이때 세션값은 화면에 보이지 않기 때문에 QA 목록에 따로 적어두지 않으면 놓치기 쉽다.

최종 해결: 세션 유틸리티로 접근을 통일하고 NPE를 먼저 막기

최종적으로는 세션 접근을 한 곳으로 모으고

세션이 없을 때 바로 명확한 응답을 반환하는 방식으로 정리했다.

핵심은 두 가지였다.

Controller마다 세션을 직접 꺼내지 않고 SessionUtils 같은 유틸리티를 통해 접근한다.
세션이 없으면 서비스 로직으로 내려가기 전에 LOGIN_REQUIRED 같은 명확한 응답을 반환한다.

아래 코드는 회사 소스코드가 아니라 실행 가능한 예제다. Java 17 기준으로 작성했다.

실행 방법

javac SessionHiddenParameterExample.java
java -ea SessionHiddenParameterExample

-ea 옵션은 Java assertion을 활성화하는 옵션이다.

실행 가능한 예제 코드

import java.util.HashMap;
import java.util.Map;
import java.util.Optional;

public class SessionHiddenParameterExample {
    public static void main(String[] args) {
        legacyControllerThrowsNullPointerExceptionWhenSessionIsMissing();
        migratedControllerReturnsUnauthorizedWhenSessionIsMissing();
        migratedControllerMergesRequestParameterAndSessionValue();
        System.out.println("All tests passed");
    }

    static void legacyControllerThrowsNullPointerExceptionWhenSessionIsMissing() {
        LegacyController controller = new LegacyController(new RegisterService());

        try {
            controller.registerDevice(Map.of("deviceName", "phone"), RequestContext.empty());
            throw new AssertionError("NullPointerException이 발생해야 한다");
        } catch (NullPointerException expected) {
            assert expected.getMessage().contains("null") : expected.getMessage();
        }
    }

    static void migratedControllerReturnsUnauthorizedWhenSessionIsMissing() {
        MigratedController controller = new MigratedController(new RegisterService());

        ApiResponse response = controller.registerDevice(
                Map.of("deviceName", "phone"),
                RequestContext.empty()
        );

        assert response.status() == 401 : response;
        assert "LOGIN_REQUIRED".equals(response.body().get("message")) : response;
    }

    static void migratedControllerMergesRequestParameterAndSessionValue() {
        MigratedController controller = new MigratedController(new RegisterService());
        RequestContext request = RequestContext.withSession(
                new SessionUser(10L, "E1001", "C01")
        );

        ApiResponse response = controller.registerDevice(
                Map.of("deviceName", "phone"),
                request
        );

        assert response.status() == 200 : response;
        assert Long.valueOf(10L).equals(response.body().get("userSeq")) : response;
        assert "E1001".equals(response.body().get("empId")) : response;
        assert "phone".equals(response.body().get("deviceName")) : response;
    }

    static class LegacyController {
        private final RegisterService registerService;

        LegacyController(RegisterService registerService) {
            this.registerService = registerService;
        }

        ApiResponse registerDevice(Map<String, String> requestParams, RequestContext request) {
            SessionUser sessionUser = LegacySessionHandler.getLoginInfo(request);

            RegisterCommand command = new RegisterCommand(
                    sessionUser.userSeq(),
                    sessionUser.empId(),
                    requestParams.get("deviceName")
            );

            return ApiResponse.ok(registerService.register(command));
        }
    }

    static class MigratedController {
        private final RegisterService registerService;

        MigratedController(RegisterService registerService) {
            this.registerService = registerService;
        }

        ApiResponse registerDevice(Map<String, String> requestParams, RequestContext request) {
            Optional<SessionUser> sessionUser = SessionUtils.currentUser(request);
            if (sessionUser.isEmpty()) {
                return ApiResponse.of(401, Map.of("message", "LOGIN_REQUIRED"));
            }

            String deviceName = requestParams.get("deviceName");
            if (deviceName == null || deviceName.isBlank()) {
                return ApiResponse.of(400, Map.of("message", "DEVICE_NAME_REQUIRED"));
            }

            RegisterCommand command = RegisterCommand.from(requestParams, sessionUser.get());
            return ApiResponse.ok(registerService.register(command));
        }
    }

    static class LegacySessionHandler {
        static SessionUser getLoginInfo(RequestContext request) {
            return request.sessionUser();
        }
    }

    static class SessionUtils {
        static Optional<SessionUser> currentUser(RequestContext request) {
            return Optional.ofNullable(request.sessionUser());
        }
    }

    static class RegisterService {
        Map<String, Object> register(RegisterCommand command) {
            Map<String, Object> result = new HashMap<>();
            result.put("userSeq", command.userSeq());
            result.put("empId", command.empId());
            result.put("deviceName", command.deviceName());
            return result;
        }
    }

    record RegisterCommand(Long userSeq, String empId, String deviceName) {
        static RegisterCommand from(Map<String, String> requestParams, SessionUser sessionUser) {
            return new RegisterCommand(
                    sessionUser.userSeq(),
                    sessionUser.empId(),
                    requestParams.get("deviceName")
            );
        }
    }

    record ApiResponse(int status, Map<String, Object> body) {
        static ApiResponse ok(Map<String, Object> body) {
            return new ApiResponse(200, body);
        }

        static ApiResponse of(int status, Map<String, Object> body) {
            return new ApiResponse(status, body);
        }
    }

    record SessionUser(Long userSeq, String empId, String companyCode) {
    }

    record RequestContext(SessionUser sessionUser) {
        static RequestContext empty() {
            return new RequestContext(null);
        }

        static RequestContext withSession(SessionUser sessionUser) {
            return new RequestContext(sessionUser);
        }
    }
}

실행 결과는 아래와 같다.

All tests passed

이 예제에서 중요한 부분은 MigratedController다.

Optional<SessionUser> sessionUser = SessionUtils.currentUser(request);
if (sessionUser.isEmpty()) {
    return ApiResponse.of(401, Map.of("message", "LOGIN_REQUIRED"));
}

세션이 없으면 DTO를 만들지 않는다.

서비스도 호출하지 않는다.

먼저 인증 상태를 확인하고, 실패 응답을 명확하게 반환한다.

그 다음 요청 파라미터와 세션값을 합쳐 Command 객체를 만든다.

RegisterCommand command = RegisterCommand.from(requestParams, sessionUser.get());

이렇게 정리하면 “화면에서 넘어온 값”과 “서버 세션에서 채운 값”의 경계가 분명해진다.

마이그레이션 QA에서 추가한 체크 포인트

이번 일을 겪고 나서 QA 시나리오에 세션 기반 값을 별도로 적었다.

검증 항목	확인 내용
정상 세션	로그인 후 `userSeq`, `empId` 같은 사용자 값이 정상 추출되는지 확인한다
세션 없음	NPE가 아니라 명확한 인증 실패 응답이 내려오는지 확인한다
세션 만료	만료된 세션으로 접근했을 때 로그인 페이지 또는 인증 실패 응답으로 흐르는지 확인한다
요청값 누락	화면 입력값이 없을 때 400 계열 응답 또는 명확한 메시지가 내려오는지 확인한다
세션값 + 요청값 조합	DTO나 Command 객체에 두 종류의 값이 모두 들어가는지 확인한다

이 체크리스트를 만들고 나니 “기능이 된다”와

“기능이 같은 방식으로 된다”를 더 구분해서 볼 수 있었다.

레거시 마이그레이션에서는 이 차이가 중요했다.

화면에서 같은 버튼을 눌렀을 때 결과가 같아 보여도

내부에서 필요한 값이 누락되면 특정 예외 케이스에서 바로 깨질 수 있기 때문이다.

배운 점

요청 파라미터에 보이지 않는 값도 서버 로직에서는 필수값일 수 있다.
레거시 Controller는 요청값, 세션값, 공통 유틸 값을 한 번에 조립하는 경우가 많다.
마이그레이션할 때는 request parameter뿐 아니라 session attribute도 QA 항목으로 분리해야 한다.
세션이 없을 때 NPE가 나는 코드는 정상 케이스 테스트만으로는 발견하기 어렵다.
세션 접근을 유틸리티로 통일하면 null 방어와 응답 정책을 한 곳에서 맞추기 쉬워진다.

이번 작업을 하면서 “화면에 없는데 서버에는 필요한 값”을 보는 눈이 조금 생겼다.

처음에는 프론트에서 값을 안 넘긴 줄 알고 한참을 요청 파라미터만 봤다.

그런데 실제 원인은 세션에서 암묵적으로 채우던 값을 놓친 것이었다.

레거시 마이그레이션은 코드를 새 문법으로 바꾸는 작업만은 아니었다.

기존 코드가 어디에서 값을 가져오고 있었는지, 그 값이 어떤 전제 위에서 동작했는지 다시 확인하는 작업이었다.

참고 링크

⚡️개발자가 자주 사용하는 NANO명령어 (알쓸나잡) : Vim 유저도 당황하지 않는 Nano 편집기 완벽 가이드 (설정부터 커스텀까지)

김춘덕⸝ဗီူ⸜ — Fri, 24 Apr 2026 00:56:39 +0900

시작에 앞서

회사에서 리눅스 서버를 운영하다 보면 Vim이 손에 익어있음에도 불구하고,

특정 배포판 환경이나 인프라 설정 때문에 Nano 편집기를 써야 하는 상황이 생기곤 합니다.

"Vim은 되는데 Nano는 왜 안 되지?"라고 답답해하셨던 분들을 위해

Nano를 Vim처럼 강력하게 만드는 설정법과 필수 명령어들을 정리했습니다. ‍♀️

한눈에 보는 에디터 비교: Nano vs Vim

두 에디터의 가장 큰 차이는 '모드(Mode)'의 존재 여부입니다. 아래 표를 통해 나에게 맞는 도구를 확인해 보세요.

구분	Nano (직관적인 메모장)	Vim (강력한 모달 편집기)
핵심 컨셉	Modeless: 보이는 대로 입력	Modal: 모드 전환을 통한 조작
진입 장벽	매우 낮음 (메모장 수준)	높음 (학습 곡선 존재)
주요 장점	하단 단축키 도움말 상시 표시	키보드만으로 압도적인 편집 속도
추천 상황	간단한 설정 파일 수정, 초보자	대규모 코드 수정, 서버 상주 작업
결정적 차이	입력과 명령이 동시에 가능	입력(Insert)과 명령(Normal) 모드 분리

"Vim이 '운전면허가 필요한 스포츠카'라면, Nano는 '누구나 탈 수 있는 자전거'와 같습니다."

1. Nano의 첫인상을 바꾸는 `~/.nanorc` 설정

Nano가 불편하게 느껴지는 가장 큰 이유는 '익숙한 개발 환경' 세팅이 안 되어 있기 때문입니다. 홈 디렉토리에 .nanorc 파일을 수정하여 Nano를 현대적인 에디터로 변환해 보세요.

# 설정 파일 열기 (또는 생성)
nano ~/.nanorc

필수 추천 설정값

## 1. 시각적 요소 설정
set linenumbers        # 줄 번호 표시
set constantshow       # 하단에 항상 커서 위치(줄/열) 표시
set mouse              # 마우스 클릭으로 커서 이동 및 스크롤 활성화

## 2. 편집 효율 설정
set tabsize 4          # 탭 크기를 4칸으로 설정
set tabstospaces       # 탭을 스페이스로 자동 변환
set softwrap           # 화면 너비를 넘어가는 긴 줄 자동 줄바꿈
set autoindent         # 자동 들여쓰기 활성화

## 3. 구문 강조 (Syntax Highlighting)
include "/usr/share/nano/*.nanorc"

2. Vim 유저를 위한 "Nano에서 Vim 맛내기"

Vim의 단축키가 손가락에 박혀있는 분들을 위해, Nano에서도 유사한 경험을 할 수 있도록 bind 설정을 추가할 수 있습니다.

목표 동작	Nano 바인딩 설정 (in .nanorc)	설명
저장 (Vim의 :w)	`bind ^S savefile main`	Ctrl+S로 즉시 저장
종료 (Vim의 :q)	`bind ^Q exit main`	Ctrl+Q로 종료
줄 삭제 (Vim의 dd)	`bind ^D cut main`	Ctrl+D로 현재 줄 전체 삭제

3. Nano 핵심 명령어 Cheat Sheet

(표기: ^ = Ctrl, M- = Alt)

✂️ 편집 및 검색 (가장 중요!)

M-A (Mark): 블록 선택 시작 (Vim의 visual mode와 유사)
^K / ^U: 잘라내기 / 붙여넣기
M-U / M-E: 실행 취소(Undo) / 재실행(Redo)
^\ (M-R): 검색 및 치환 (Replace)

파일 관리

^O: 파일 저장 (파일명 확인 가능)
^X: 편집기 종료
M-G: 특정 줄 번호로 이동

4. 실전 팁: 멀티 버퍼 활용하기

Vim에서 :tabnew를 쓰듯 Nano에서도 여러 파일을 동시에 열어두고 전환할 수 있습니다.

nano -F 파일1 파일2 처럼 여러 파일을 함께 엽니다.
M-. (Alt + 마침표): 다음 파일로 전환
M-, (Alt + 쉼표): 이전 파일로 전환

마치며

에디터 하나에 종속되지 않고 Vim과 Nano를 자유자재로 오가는 유연함은 숙련된 개발자의 증거이기도 합니다.

이 가이드가 여러분의 터미널 작업을 조금 더 쾌적하게 만들어주길 바랍니다!

⚡️개발자가 자주 사용하는 VIM 명령어 모음 : 알아두면 쓸데있는 Vim 잡학지식(알쓸빔잡)

김춘덕⸝ဗီူ⸜ — Thu, 23 Apr 2026 03:14:30 +0900

1. 모드 전환 (Mode Switching)

명령어	설명
`i`	커서 앞 삽입 모드 진입
`I`	줄 맨 앞에서 삽입 모드 진입
`a`	커서 뒤 삽입 모드 진입
`A`	줄 맨 끝에서 삽입 모드 진입
`o`	아래 줄 새로 추가 후 삽입 모드 진입
`O`	위 줄 새로 추가 후 삽입 모드 진입
`v`	비주얼 모드 (문자 단위 선택)
`V`	비주얼 라인 모드 (줄 단위 선택)
`Ctrl+v`	비주얼 블록 모드 (블록 단위 선택)
`Esc`	노멀 모드로 복귀

2. 커서 이동 - 기본 (Basic Movement)

명령어	설명
`h`	왼쪽으로 이동
`j`	아래로 이동
`k`	위로 이동
`l`	오른쪽으로 이동
`0`	줄 맨 앞으로 이동
`^`	줄 첫 번째 비공백 문자로 이동
`$`	줄 맨 끝으로 이동
`gg`	파일 맨 처음으로 이동
`G`	파일 맨 끝으로 이동
`{숫자}G`	특정 줄 번호로 이동 (예: `10G`)

3. 커서 이동 - 단어 (Word Movement)

명령어	설명
`w`	다음 단어 첫 글자로 이동
`W`	공백 기준 다음 단어 첫 글자로 이동
`b`	이전 단어 첫 글자로 이동
`B`	공백 기준 이전 단어 첫 글자로 이동
`e`	현재/다음 단어 끝 글자로 이동
`E`	공백 기준 현재/다음 단어 끝 글자로 이동
`ge`	이전 단어 끝 글자로 이동
`f{문자}`	현재 줄에서 해당 문자 위치로 이동 (앞 방향)
`F{문자}`	현재 줄에서 해당 문자 위치로 이동 (뒤 방향)
`t{문자}`	현재 줄에서 해당 문자 바로 앞으로 이동

4. 커서 이동 - 화면/파일 (Screen/File Movement)

명령어	설명
`Ctrl+d`	반 페이지 아래로 스크롤
`Ctrl+u`	반 페이지 위로 스크롤
`Ctrl+f`	한 페이지 아래로 스크롤
`Ctrl+b`	한 페이지 위로 스크롤
`H`	화면 맨 위 줄로 이동
`M`	화면 중간 줄로 이동
`L`	화면 맨 아래 줄로 이동
`zz`	현재 줄을 화면 중앙에 위치
`zt`	현재 줄을 화면 맨 위에 위치
`zb`	현재 줄을 화면 맨 아래에 위치

5. 삭제 (Delete)

명령어	설명
`x`	현재 문자 삭제
`X`	커서 앞 문자 삭제 (백스페이스)
`dd`	현재 줄 삭제
`{숫자}dd`	N줄 삭제 (예: `3dd`)
`dw`	커서부터 다음 단어 전까지 삭제
`db`	커서부터 이전 단어 전까지 삭제
`d0`	커서부터 줄 맨 앞까지 삭제
`d$` / `D`	커서부터 줄 끝까지 삭제
`dgg`	커서부터 파일 처음까지 삭제
`dG`	커서부터 파일 끝까지 삭제

6. 복사 & 붙여넣기 (Yank & Paste)

명령어	설명
`yy` / `Y`	현재 줄 복사 (yank)
`{숫자}yy`	N줄 복사 (예: `3yy`)
`yw`	현재 단어 복사
`y$`	커서부터 줄 끝까지 복사
`y0`	커서부터 줄 맨 앞까지 복사
`p`	커서 아래/뒤에 붙여넣기
`P`	커서 위/앞에 붙여넣기
`"ayy`	레지스터 a에 현재 줄 복사
`"ap`	레지스터 a 내용 붙여넣기
`"+p`	시스템 클립보드에서 붙여넣기

7. 변경 (Change)

명령어	설명
`r{문자}`	현재 문자를 다른 문자로 교체
`R`	교체 모드 진입 (타이핑한 내용으로 덮어쓰기)
`cw`	현재 단어 변경 (삭제 후 삽입 모드)
`cc`	현재 줄 내용 변경
`c$` / `C`	커서부터 줄 끝까지 변경
`ci{`	`{}` 내부 내용 변경 (Change Inside)
`ci(`	`()` 내부 내용 변경
`ci"`	`""` 내부 내용 변경
`ca{`	`{}` 포함 내용 변경 (Change Around)
`~`	현재 문자 대/소문자 전환

8. 실행 취소 & 반복 (Undo & Repeat)

명령어	설명
`u`	실행 취소 (undo)
`Ctrl+r`	재실행 (redo)
`.`	마지막 변경 명령 반복
`{숫자}.`	마지막 변경 명령 N번 반복
`@:`	마지막 Ex 명령 반복

9. 검색 (Search)

명령어	설명
`/{패턴}`	아래 방향으로 패턴 검색
`?{패턴}`	위 방향으로 패턴 검색
`n`	다음 검색 결과로 이동
`N`	이전 검색 결과로 이동
`*`	현재 단어 아래 방향으로 검색
`#`	현재 단어 위 방향으로 검색
`:noh`	검색 하이라이트 해제
`%`	매칭되는 괄호로 이동 (`{`, `(`, `[`)

10. 치환 (Substitute)

명령어	설명
`:s/old/new/`	현재 줄 첫 번째 old를 new로 치환
`:s/old/new/g`	현재 줄 전체 old를 new로 치환
`:%s/old/new/g`	파일 전체 old를 new로 치환
`:%s/old/new/gc`	파일 전체 치환 (각 항목 확인 요청)
`:%s/old/new/gi`	파일 전체 대소문자 무시하고 치환
`:{범위}s/old/new/g`	특정 줄 범위 치환 (예: `:1,10s/old/new/g`)

11. 파일 & 버퍼 (File & Buffer)

명령어	설명
`:w`	현재 파일 저장
`:w {파일명}`	다른 이름으로 저장
`:q`	종료
`:q!`	저장하지 않고 강제 종료
`:wq` / `ZZ`	저장 후 종료
`:e {파일명}`	다른 파일 열기
`:e!`	현재 파일 다시 불러오기 (변경사항 버림)
`:bn`	다음 버퍼로 이동
`:bp`	이전 버퍼로 이동
`:ls`	열린 버퍼 목록 표시

12. 창 분할 (Window Split)

명령어	설명
`:sp` / `Ctrl+w s`	수평 분할
`:vsp` / `Ctrl+w v`	수직 분할
`Ctrl+w w`	다음 창으로 이동
`Ctrl+w h/j/k/l`	방향키로 창 이동
`Ctrl+w =`	모든 창 크기 균등하게 조정
`:close` / `Ctrl+w c`	현재 창 닫기
`:only` / `Ctrl+w o`	현재 창만 남기고 모두 닫기

13. 탭 (Tab)

명령어	설명
`:tabnew {파일명}`	새 탭에서 파일 열기
`gt`	다음 탭으로 이동
`gT`	이전 탭으로 이동
`:tabclose`	현재 탭 닫기
`:tabs`	열린 탭 목록 표시

14. 들여쓰기 & 포매팅 (Indent & Format)

명령어	설명
`>>`	현재 줄 들여쓰기
`<<`	현재 줄 내어쓰기
`{숫자}>>`	N줄 들여쓰기 (예: `3>>`)
`=G`	커서부터 파일 끝까지 자동 들여쓰기 정렬
`gg=G`	파일 전체 자동 들여쓰기 정렬
`>` (비주얼)	선택 영역 들여쓰기
`<` (비주얼)	선택 영역 내어쓰기

15. 매크로 & 기타 (Macro & Others)

명령어	설명
`q{문자}`	매크로 녹화 시작 (예: `qa`)
`q`	매크로 녹화 종료
`@{문자}`	매크로 실행 (예: `@a`)
`@@`	마지막 매크로 재실행
`{숫자}@{문자}`	매크로 N번 반복 실행
`:set number`	줄 번호 표시
`:set nonumber`	줄 번호 숨기기
`:set hlsearch`	검색 하이라이트 활성화
`Ctrl+a`	현재 커서의 숫자 1 증가
`Ctrl+x`	현재 커서의 숫자 1 감소

팁

숫자 조합: 대부분의 명령어 앞에 숫자를 붙여 반복 실행 가능
- 5j → 5줄 아래 이동
- 3dd → 3줄 삭제
- 2yy → 2줄 복사

텍스트 오브젝트: ci(, da", yi{ 등 조합으로 강력한 편집 가능
- i = inner (내부만), a = around (포함)
- 대상: w(단어), s(문장), p(단락), ", ', `, (, {, [

레지스터: "a ~ "z 26개의 레지스터로 여러 내용 관리 가능

️ 실무 : StrictHttpFirewall이 동작하는 원리 (feat. PROPFIND, WebDAV) | PROPFIND가 뭐예요 ?

김춘덕⸝ဗီူ⸜ — Tue, 21 Apr 2026 02:05:36 +0900

작년 10월 말부터 진행했던 고도화 프로젝트가 개발 서버에서 통합 QA를 진행하고 있다.

그리고 우리 프로젝트는 네이티브 개발자 분들이 WebView 사용과 API호출 등 연결을 해주고 있다.

그래서 개발서버의 QA중인 고도화 서비스는 네이티브 개발자 분들 , 그리고 관계사 관리자 분들이 요즘 사용해 주고 있어서

매일 개발서버 로그를 검수하며 문제는 없는 지 체크를 해보고 있다.

오늘도 로그를 보면서 Exception 걸린 부분이 있는지 검토하고 있었다.

그러다 PROPFIND 라는 Exception 문구가 있는 게 아닌가?

이건 또 뭐다냐 하면서 구글에 검색해 보았다.

내용을 알게 되고 서비스 운영 하는 개발자 분들이 알고 있으면 좋은 내용인 것 같아 오늘도 포스팅을 써본다 ‍♀️

주제 정의

Spring Security의 StrictHttpFirewall이 비표준 HTTP 메서드를 차단하는 원리와, 폐쇄망 서버에서 PROPFIND 요청이 간헐적으로 발생하는 이유를 분석한다.
단순히 에러를 끄는 방법이 아니라, 왜 이 에러가 발생하는지, Spring Security 내부에서 어떤 흐름으로 차단이 일어나는지를 중심으로 정리한다.

원전 / 공식 스펙 요약

HttpFirewall 인터페이스

Spring Security는 HttpFirewall이라는 인터페이스를 통해 요청 유효성 검사를 추상화한다.

public interface HttpFirewall {
    FirewalledRequest getFirewalledRequest(HttpServletRequest request)
        throws RequestRejectedException;

    HttpServletResponse getFirewalledResponse(HttpServletResponse response);
}

구현체는 두 가지다.

구현체	설명
`DefaultHttpFirewall`	최소한의 검사만 수행. 레거시 호환용
`StrictHttpFirewall`	Spring Security 4.2.4+부터 기본값. 엄격한 검사 수행

공식 문서 - HttpFirewall

StrictHttpFirewall의 검사 항목

StrictHttpFirewall은 요청이 필터 체인에 진입하기 전, 아래 항목을 순서대로 검사한다.

1. HTTP 메서드 검사

허용 목록에 없는 메서드는 즉시 차단한다.

// StrictHttpFirewall 내부 기본 허용 목록
private static final Set<String> ALLOW_ANY_HTTP_METHOD = Collections.unmodifiableSet(
    new HashSet<>(Arrays.asList(
        "DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT"
    ))
);

PROPFIND, MKCOL, COPY 등 WebDAV 전용 메서드는 이 목록에 포함되지 않는다.

2. URL 정규화 검사

비정규화된 경로를 차단한다. 디렉터리 트래버설 공격 방지가 목적이다.

/normal/path       → 허용
/path/../secret    → 차단 (Path Traversal)
//double/slash     → 차단
/path/%2F/encoded  → 차단 (URL 인코딩 우회 시도)

3. 헤더 / 파라미터 CR·LF 검사

HTTP Response Splitting 공격을 방지하기 위해 헤더와 파라미터 값에 \r, \n이 포함되면 차단한다.

4. 호스트 헤더 검사

허용된 호스트 목록을 설정한 경우, 목록 외 호스트로의 요청을 차단한다.

StrictHttpFirewall JavaDoc

PROPFIND와 WebDAV

PROPFIND는 HTTP/1.1을 확장한 WebDAV 프로토콜에서 정의하는 메서드다.

WebDAV는 웹 서버를 파일 시스템처럼 다룰 수 있게 하는 프로토콜로

HTTP를 기반으로 파일 생성·수정·삭제·이동이 가능하다.

WebDAV가 추가한 주요 메서드는 아래와 같다.

메서드	역할
`PROPFIND`	리소스의 속성(메타데이터) 조회
`PROPPATCH`	리소스 속성 수정
`MKCOL`	컬렉션(디렉터리) 생성
`COPY`	리소스 복사
`MOVE`	리소스 이동
`LOCK` / `UNLOCK`	리소스 잠금

이 중 PROPFIND는 클라이언트가 서버에 접근할 때 가장 먼저 보내는 탐색 요청이기 때문에

WebDAV를 사용하는 클라이언트라면 반드시 발생한다.

공식 스펙 - RFC 4918 (WebDAV)

실무 해석 및 분석

요청 차단 흐름 상세 분석

실제 에러 스택을 기준으로 흐름을 따라가 본다.

at StrictHttpFirewall.rejectForbiddenHttpMethod(StrictHttpFirewall.java:531)
at StrictHttpFirewall.getFirewalledRequest(StrictHttpFirewall.java:508)
at FilterChainProxy.doFilterInternal(FilterChainProxy.java:211)
at FilterChainProxy.doFilter(FilterChainProxy.java:191)
at CompositeFilter$VirtualFilterChain.doFilter(CompositeFilter.java:113)
at HandlerMappingIntrospector.lambda$createCacheFilter$3(HandlerMappingIntrospector.java:195)

흐름을 단계별로 정리하면 다음과 같다.

HTTP 요청 수신
      ↓
FilterChainProxy.doFilter()
      ↓
FilterChainProxy.doFilterInternal()
      ↓
StrictHttpFirewall.getFirewalledRequest()   ← 여기서 검사 시작
      ↓
rejectForbiddenHttpMethod()                 ← PROPFIND 감지
      ↓
RequestRejectedException 발생
      ↓
클라이언트 → 400 Bad Request 응답

mermaid를 사용중이 신 분은

아래 소스를 복사하여 사용하시면 흐름도를 깔끔하게 볼 수 있습니다.❤️

```mermaid
flowchart TD
    A([  HTTP 요청 수신]) --> B[FilterChainProxy.doFilter]
    B --> C[FilterChainProxy.doFilterInternal]
    C --> D[StrictHttpFirewall.getFirewalledRequest]

    D --> E{HTTP 메서드\n허용 목록 검사}

    E -- "❌ 비허용 메서드\nPROPFIND 등" --> F[rejectForbiddenHttpMethod]
    F --> G[RequestRejectedException 발생]
    G --> H([  400 Bad Request 응답])

    E -- "✅ 허용 메서드\nGET / POST 등" --> I{URL 정규화\n검사}

    I -- "❌ 비정규화 경로\n/../ // 등" --> G
    I -- "✅ 정상 경로" --> J{헤더·파라미터\nCR·LF 검사}

    J -- "❌ CR·LF 포함" --> G
    J -- "✅ 정상" --> K{호스트 헤더\n검사}

    K -- "❌ 비허용 호스트" --> G
    K -- "✅ 정상" --> L[FilterChain 진입]

    L --> M[Security Filter들 순차 실행]
    M --> N[DispatcherServlet]
    N --> O[HandlerMapping → Controller]
    O --> P([  정상 응답])

    style A fill:#4A90D9,color:#fff,stroke:none
    style H fill:#E05C5C,color:#fff,stroke:none
    style P fill:#5BAD72,color:#fff,stroke:none
    style F fill:#E8A838,color:#fff,stroke:none
    style G fill:#E05C5C,color:#fff,stroke:none
```

핵심은 컨트롤러는커녕 서블릿 필터 체인에도 진입하지 못한 채 차단된다는 점이다.

DispatcherServlet, HandlerMapping, @RequestMapping 어디에도 도달하지 않는다.

왜 폐쇄망 서버에서 간헐적으로 발생하는가?

외부 인터넷이 차단된 폐쇄망이라도, 내부 네트워크에는 WebDAV를 사용하는 클라이언트가 다수 존재한다.

간헐적으로 발생하는 이유는, 이 클라이언트들이 사용자의 명시적 행동 없이 자동으로 요청을 보내기 때문이다.

발생 주체	발생 조건	설명
Windows 탐색기	네트워크 드라이브 연결 시	서버 URL을 탐색기에 입력하면 자동으로 `PROPFIND` 전송
Microsoft Office	파일 열기/저장 경로에 서버 URL 사용 시	Word, Excel이 서버를 WebDAV 스토리지로 인식하고 탐색
보안 장비 (IDS/IPS)	주기적 헬스체크 / 포트 스캐닝 시	비표준 메서드로 서버 응답 유형을 판별
내부 모니터링 도구	서버 상태 점검 시	일부 도구가 WebDAV 프로토콜 기반 점검을 수행
개발자 로컬 환경	IDE나 REST 클라이언트 설정 오류 시	IntelliJ HTTP Client, Postman 설정 실수로 발생하기도 함

이 로그는 위험한가?

결론부터 말하면, 위험하지 않다.

StrictHttpFirewall이 설계된 대로 동작하고 있다는 증거다.

서버는 허용하지 않은 메서드를 정상적으로 거부했고, 실제 비즈니스 로직에는 전혀 영향을 주지 않는다.

다만 두 가지 상황에서는 대응이 필요하다.

로그가 과도하게 쌓여 실제 장애 로그를 가리는 경우
내부 서비스가 WebDAV를 실제로 사용해야 하는 경우

DefaultHttpFirewall과의 차이

레거시 프로젝트에서 DefaultHttpFirewall을 사용 중이라면 이 에러가 발생하지 않는다.

DefaultHttpFirewall은 메서드 허용 목록 검사를 수행하지 않기 때문이다.

Spring Boot 3, Spring Security 6으로 마이그레이션하는 과정에서

StrictHttpFirewall이 기본값으로 바뀌면서 이런 로그가 새로 등장하는 경우가 많다.

고도화 프로젝트 진행 중이라면 이 지점을 눈여겨볼 필요가 있다.

결론 및 실무 팁

상황에 따라 세 가지 기준으로 대응을 선택한다.

Case 1. WebDAV가 전혀 필요 없고, 로그 양도 감당 가능한 경우 → 방치

보안 측면에서 정상 동작 중이다. 별도 조치 없이 모니터링만 유지한다.

Case 2. 로그만 억제하고 싶은 경우 → RequestRejectedHandler 등록

Spring Security 5.7부터 RequestRejectedHandler를 빈으로 등록하면 처리 방식을 커스텀할 수 있다.

기본 구현체인 HttpStatusRequestRejectedHandler는 400 응답만 내리고 스택 트레이스를 남기지 않는다.

@Configuration
public class SecurityConfig {

    /**
     * RequestRejectedException 발생 시 스택 트레이스 없이 400만 응답한다.
     * Spring Security 5.7+ 기준
     */
    @Bean
    public RequestRejectedHandler requestRejectedHandler() {
        return new HttpStatusRequestRejectedHandler();
    }
}

로그 레벨만 조정하는 방법도 있다.

# application.properties
logging.level.org.springframework.security.web.firewall=ERROR

단, 이 방법은 다른 방화벽 관련 경고도 함께 억제하므로 주의한다.

Case 3. 내부 서비스가 WebDAV를 실제로 사용하는 경우 → 허용 메서드 명시적 추가

StrictHttpFirewall에 허용 메서드를 추가하고, WebSecurityCustomizer에 등록한다.

@Configuration
public class SecurityConfig {

    /**
     * PROPFIND 메서드를 허용 목록에 추가한다.
     * WebDAV를 실제로 사용하는 경우에만 적용한다.
     */
    @Bean
    public HttpFirewall allowWebDavFirewall() {
        StrictHttpFirewall firewall = new StrictHttpFirewall();
        firewall.setAllowedHttpMethods(
            Arrays.asList(
                "HEAD", "DELETE", "POST", "GET",
                "OPTIONS", "PATCH", "PUT", "PROPFIND"
            )
        );
        return firewall;
    }

    @Bean
    public WebSecurityCustomizer webSecurityCustomizer() {
        return web -> web.httpFirewall(allowWebDavFirewall());
    }
}

허용 메서드를 넓히면 공격 표면이 넓어진다.

PROPFIND 요청의 출처를 먼저 파악하고, 실제로 필요한 경우에만 적용한다.

참고 링크

‍ Springframwork Mig 기록 : OKTA SAML 로그인 무한 루프 디버깅기 (feat. 백엔드·프론트 환장의 콜라보)

김춘덕⸝ဗီူ⸜ — Fri, 17 Apr 2026 04:13:30 +0900

INTRO

Spring Framework 4에서 Spring Boot 3으로 마이그레이션하는 고도화 프로젝트 중
OKTA SAML 인증 연동을 붙이고 테스트 서버에 배포했다.
설레는 마음으로 로그인을 시도했는데, 화면이 계속 새로고침되며 멈추지 않았다.
처음에는 "배포를 잘못했나?" 싶어서 서버를 재시작해봤고, 로그를 다시 확인해봤다. 그런데 아무리 봐도 배포 자체는 정상이었다.

Fiddler 네트워크 로그를 열어서 트랜잭션 흐름을 직접 추적해보고 나서야 원인이 보였다.
백엔드에서 터진 HTTP 500 에러와, 그 에러 상황을 전혀 고려하지 않은 프론트엔드 리다이렉트 로직이 서로 맞물려 만들어낸
그야말로 환장의 콜라보였다.

처음에는 백엔드 문제라고 확신했는데, 백엔드를 고쳐도 루프는 계속됐다.
두 레이어를 동시에 수정하고 나서야 루프를 끊을 수 있었다.

문제 상황

처음에 Fiddler 로그를 펼쳐놨을 때는 솔직히 어디서부터 봐야 할지 막막했다.
요청이 수십 개 쌓여 있었고, 다 비슷하게 생긴 리다이렉트가 반복되고 있었다.
하나씩 따라가다 보니 아래처럼 5단계가 계속 순환하는 패턴이 보였다.

무한 루프 흐름도

로그인 페이지 진입 → 로그인 페이지 JS가 무조건 OKTA SAML 인증 URL로 리다이렉트
OKTA 서버에서 아이디/비밀번호 인증 성공 → SAML 콜백 엔드포인트로 POST
LoginController가 콜백을 수신해 처리하던 중 HTTP 500 에러 발생 (SAML 파싱 오류)
Tomcat 에러 페이지가 렌더링되고, 해당 에러 페이지에 포함된 공통 스크립트가 로드되면서 인덱스 페이지로 302 리다이렉트
인덱스 페이지는 세션이 없으므로 다시 로그인 페이지로 이동 → 1번으로 복귀

흐름을 정리하고 나서 처음 든 생각은 "3번에서 500이 나는 게 문제다. 저걸 잡으면 되겠다"였다.
백엔드 개발자니까 서버 에러부터 고치면 된다는 생각이 자연스럽게 들었다.

그런데 그게 아니었다. 1번 단계의 자바스크립트는 에러 여부를 따지지 않고 무조건 OKTA로 튕겨냈다.
백엔드에서 500이 나든 302가 나든, 결국 다시 로그인 페이지로 돌아오면 JS가 또 OKTA로 보내버리는 구조였다.
백엔드 에러를 아무리 잡아도 프론트엔드가 루프를 계속 만들고 있었던 것이다.

더불어, 기존 코드를 보다가 예외 처리 리다이렉트 경로가 이렇게 되어 있다는 것도 눈에 걸렸다.

// 기존 코드: .jsp 확장자를 직접 지정
return "redirect:/login.jsp?error=true";

Spring MVC를 공부하면서 ViewResolver가 뷰 이름을 실제 경로로 변환해준다는 건 알고 있었는데
이렇게 직접 .jsp로 리다이렉트하면 ViewResolver를 아예 우회한다는 것은 그때 처음 제대로 인식했다.
Model에 세팅해야 할 기본값들이 전부 날아가버려서 빈 화면이나 404가 뜰 수 있는 상태였다.

1번째 시도: 백엔드 try-catch만 적용 (실패)

시도한 이유

"서버에서 500이 안 나면, 에러 페이지가 렌더링되지 않고

에러 페이지 안에 있는 공통 스크립트도 실행되지 않을 것이다.
그러면 루프가 끊기지 않을까?" 라는 논리였다. 콜백 핸들러에 try-catch를 감싸서 예외를 잡고
에러 코드를 파라미터로 담아 명시적으로 로그인 페이지로 리다이렉트했다.
백엔드 개발자로서 할 수 있는 가장 직관적인 대응이었고
이 정도면 해결되지 않을까 생각했다.

적용 방법

@PostMapping("/saml-callback")
public String samlCallback(HttpServletRequest request, Model model) {
    try {
        // SAML Assertion 파싱 및 사용자 검증 로직
        return "redirect:/main";
    } catch (Exception e) {
        logger.error("[OKTA_ERROR] SAML 인증 콜백 처리 중 오류 발생:", e);
        return "redirect:/login?error=SAML_PARSE_FAILED";
    }
}

문제점/한계

배포하고 다시 테스트했는데 루프는 그대로였다. 로그를 보니 이번엔 500 대신 302가 찍혔는데
결국 로그인 페이지로 이동하자마자 JS가 다시 OKTA로 튕겨버렸다.
"분명히 에러를 잡았는데 왜 여전히 루프가 도는 거지?"라는 생각이 들었다.

그때 다시 Fiddler 로그를 열어서 흐름을 처음부터 다시 봤다.
서버는 분명 302를 잘 보내고 있었다.

문제는 로그인 페이지 JS가 error 파라미터가 있는지 없는지 확인 자체를 하지 않는다는 것이었다.
에러가 붙어서 돌아오든, 정상으로 돌아오든 무조건 OKTA로 리다이렉트하는 코드가 거기 있었다.
백엔드를 아무리 고쳐봤자 소용없는 구조였다. 이 순간 "아, 이건 내가 담당하는 레이어만의 문제가 아니구나"를 체감했다.

배운 점: 서버에서 에러를 우아하게 처리하는 것과, 사용자 흐름의 루프를 실제로 차단하는 것은 다른 문제다.
백엔드만 고치면 된다는 생각이 얼마나 단편적이었는지 느꼈다.
버그를 분석할 때는 내가 담당하는 레이어가 아니라, 요청이 흘러가는 전체 경로를 먼저 그려봐야 한다.

최종 해결: 백엔드 예외 처리 + 프론트엔드 루프 차단 (2중 방어)

루프를 끊으려면 두 레이어를 반드시 함께 수정해야 한다는 것을 파악했다.
그런데 막상 수정 방향을 잡고 나니 또 다른 걱정이 생겼다.

"내가 고치려는 방식이 혹시 다른 곳을 망가뜨리지 않을까?"

신입으로서 가장 무서운 순간이 이런 때다.

특히 공통 스크립트나 에러 처리 로직은 전체 시스템에 영향을 줄 수 있어서 섣불리 건드리기가 꺼려졌다.
그래서 수정 전에 예상되는 사이드 이펙트를 먼저 정리해보고, 각각에 대한 대응책을 같이 준비했다.

해결책 1: 백엔드 예외 방어 (에러 은폐 방지 포함)

콜백 처리 중 예외가 발생하면 에러 코드를 담아 로그인 페이지로 리다이렉트한다.
그런데 여기서 처음에는 단순하게 catch로 잡고 302로 보내면 된다고 생각했다.
그러다가 "이렇게 하면 운영 중에 에러가 나도 500 알람이 안 뜨는 거 아닌가?" 하는 의문이 들었다.

실제로 그랬다.

try-catch로 모든 예외를 잡아버리면 APM 모니터링 도구 입장에서는 정상 응답처럼 보인다.
운영 중 SAML 파싱이 계속 실패하고 있어도, 담당자가 아무도 인지를 못하게 되는 것이다.
화면을 깔끔하게 처리하려다가 오히려 장애 대응 체계를 무력화할 뻔했다.

그래서 화면 흐름은 302로 처리하되, 서버 로그에는 반드시 전체 스택 트레이스를 남기는 방식으로 보완했다.

// LoginController.java
@PostMapping("/samlCallback")
public String samlCallback(HttpServletRequest request, Model model) {
    try {
        // SAML Assertion 파싱 및 사용자 검증 로직
        return "redirect:/main";
    } catch (Exception e) {
        // [핵심] 화면 흐름은 302로 제어하되, 서버 로그에는 스택 트레이스를 반드시 남긴다
        // → APM 모니터링 체계를 무력화하지 않기 위한 방어 코딩
        logger.error("[OKTA_ERROR] SAML 인증 콜백 처리 중 치명적 오류 발생:", e);
        return "redirect:/login?error=SAML_PARSE_FAILED";
    }
}

기존의 .jsp 직접 리다이렉트도 이 기회에 함께 수정했다.
앞서 문제 상황에서 발견했던 부분인데, 단독으로는 루프와 직접 연결된 버그는 아니었지만
언제든 빈 화면이 뜰 수 있는 잠재적인 결함이었다.
발견한 김에 같이 고치는 게 맞다고 판단했다.

// AS-IS: ViewResolver를 우회, Model 데이터 누락 위험
return "redirect:/login.jsp?error=true";

// TO-BE: ViewResolver를 정상 경유
return "redirect:/login?error=true";

해결책 2: 프론트엔드 루프 차단 (화이트 스크린 방지 포함)

로그인 페이지 JSP에서 OKTA 자동 리다이렉트를 실행하기 전
URL에 error 파라미터가 있는지 먼저 확인하도록 분기를 추가했다.

그런데 여기서도 단순하게 "에러 있으면 리다이렉트 스크립트 멈추면 되겠네" 라고 생각했다가
한 가지를 놓쳤다는 걸 깨달았다.

OKTA 전용 로그인 페이지에는 ID/PW 입력 폼 자체가 없다.

그러니 리다이렉트 스크립트만 멈춰버리면 사용자는 에러 알림을 확인하고 나서
아무것도 없는 빈 화면에 갇혀버리게 된다.

사용자 반응 예상

사용자 입장에서는 "내가 뭘 해야 하지?" 가 되는 상황이다.
기능 구현에만 집중하다 보면 이런 UX적인 부분을 놓치기 쉬운데
수정하기 전에 직접 시나리오를 따라가 본 게 도움이 됐다.

에러 발생 시 안내 팝업을 띄운 뒤
지정된 서비스 안내 페이지로 Fallback 처리하는 방식으로 대응했다.

// login.jsp: OKTA 자동 리다이렉트 스크립트 (수정 후)
$(document).ready(function() {
    var errorParam = new URLSearchParams(window.location.search).get('error');

    if (errorParam) {
        // [핵심] 루프를 멈추되, 사용자가 빈 화면에 갇히지 않도록 Fallback 처리
        alert("로그인 처리 중 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.");
        location.href = '/notice';
        return; // OKTA 리다이렉트 중단
    }

    // 정상 흐름: OKTA SAML 인증 URL로 리다이렉트
    location.href = "${oktaSamlAuthUrl}";
});

최종 흐름 정리

[정상 흐름]
로그인 페이지 → OKTA 인증 → SAML 콜백 처리 → 메인 페이지

[에러 발생 시 흐름 (수정 후)]
로그인 페이지 → OKTA 인증 → SAML 콜백 처리
    → (Exception 발생) → 서버 로그 기록 → 로그인 페이지?error=SAML_PARSE_FAILED
    → (error 파라미터 감지) → 안내 팝업 → 서비스 안내 페이지
    [루프 차단됨]

배운 점

복합 버그는 레이어 하나만 고쳐서는 해결되지 않는다.
백엔드 500 에러와 프론트엔드 무조건 리다이렉트 로직이 맞물리면, 각각은 정상처럼 보여도 합쳐지면 무한 루프를 만든다.
버그를 분석할 때 "내 담당 레이어"에만 집중하는 것이 얼마나 좁은 시야인지 이번에 실감했다.
요청 흐름 전체를 먼저 그리는 습관을 들여야 한다.
try-catch로 예외를 잡아 사용자 화면을 깔끔하게 처리하는 것과, 서버 로그에 에러를 남기는 것은 반드시 동시에 해야 한다.
처음에는 "어차피 에러 페이지 보여주면 되지"라고 단순하게 생각했는데, 그 판단이 운영 중 장애를 아무도 인지하지 못하게 만드는 함정이었다.
기능이 동작하는지 확인하는 것과, 사용자가 에러 상황에서 갇히지 않는지 확인하는 것은 다른 테스트다.
수정 후 반드시 에러 시나리오를 직접 따라가 보는 것이 중요하다.
빈 화면에 방치되는 사용자를 만들지 않으려면, 정상 흐름만큼 에러 흐름도 꼼꼼하게 설계해야 한다.

️ 실무 : GCP to OCI 이전 구축기 및 504 Gateway Time-out 해결기 (feat. Swap Memory)

김춘덕⸝ဗီူ⸜ — Sat, 4 Apr 2026 03:41:53 +0900

INTRO

여느 때와 다름없는 평화로운 금요일
결혼식을 한다고 2년 가까이 길었던 머리를
단발로 싹-둑 자르고 파마를 하러 미용실에 방문했다.
꾸벅꾸벅 졸고 있던 찰나, 휴대폰이 '징- 징-' 울렸다.
무심코 화면을 켰는데 순간 내 눈을 의심했다.
구글 클라우드 ~~~ 52,150원 결제 완료 카드사 결제 알림이 떠 있었다.

"대체 내가 뭘 돌렸길래 5만 원이나 결제가 된 거지?"
머리에 약을 바른 채 구글 클라우드 콘솔 앱을 켜고 한참을 뒤적거리며 찾아봤다.

네트워크 트래픽 과금인가? 무료 티어 기준을 초과한 사용량이 무엇 때문인지 분명치 않았다.

안 그래도 기존에 사용하던 GCP 무료 티어 서버는 너무 버벅거리고
접근할 때마다 느려서 개발하고 테스트하기가 여간 불편한 게 아니었다.

이 요금 과금 문자를 시작으로 평소 자주 떠들떠들 하는 개발자 오톡방에 클라우드 추천을 받았고
사람들이 추천한 오라클 클라우드(OCI)로 서버를 아예 이전하기로 했다.

무사히(?) OCI에 인프라 환경을 처음부터 새롭게 구축하고
모든 설정을 보란 듯이 마쳤지만, 기쁨도 잠시...

Admin 로그인 페이지에 접속하자마자 서버 전체가 완전히 뻗어버리는 치명적인 문제를 마주하게 되었다.

온갖 삽질 끝에 서버 가상 메모리(Swap Space) 할당이라는 인프라적 조치를 통해 이 사태를 해결해냈다.
Gemini랑 새벽 3시까지 작업한 인프라 이전 과정과 트러블슈팅의 전체 과정을 생생하게 기록해두려 한다.

~~(또 언제 할 줄 모르잖아 ?)~~

개발환경 및 클라우드 비교

이번 마이그레이션을 진행하며 기존의 AS-IS 환경과 새로운 TO-BE 환경의 차이는 꽤 컸다.
특히 단순 반복 배포에서 벗어나 최신 트렌드에 맞춘 Docker 환경을 추가 도입했다.

구분	AS-IS (GCP 환경)	TO-BE (OCI 환경)
운영체제 및 인프라	Google Cloud Platform (무료 티어)	Oracle Cloud Infrastructure (무료 티어)
배포 패러다임	jar 파일 수동 빌드 > 업로드 등 단순 배포	Docker Compose 기반 다중 컨테이너 자동화 환경
웹 프론트 엔드	웹 서버 부재 8080 등 개별 포트 직접 접근	Nginx 리버스 프록시 적용 (80/443 포트 브릿지)
서버 시스템 자원	물리 RAM 1GB (빈번한 스와핑 발생)	물리 RAM 1GB + Swap Memory 2GB 강제 할당 추가

사용 기술: Java 17, Spring Boot 3.3.2, PostgreSQL 15, RabbitMQ, Nginx, Certbot

무료 티어 최강자 비교: GCP vs OCI

나처럼 토이 프로젝트나 레거시 개선 연습용 개인 서버를 찾는 개발자에게 무료 클라우드는 사막의 오아시스다.❤️
하지만 벤더사마다 제공하는 자원에는 명확한 차이가 존재한다.

항목	GCP (e2-micro) 무료 티어	OCI (VM.Standard.E2.1.Micro) 무료 티어
RAM (메모리)	1GB	1GB (ARM 기반 Ampere는 24GB까지 주기도함)
CPU 코어	2 vCPU (0.25 코어 제한을 둔 버스팅)	1/8 OCPU (AMD 마이크로 인스턴스 기준) (ARM 선택 시 최대 4 OCPU)
네트워크 트래픽	북미 리전만 무료 (아시아는 과금) 월 1GB 무료	서울/춘천 리전 선택 가능 월 10TB까지 무료
디스크(스토리지)	30GB 고정 (Standard HDD 수준 속도)	최대 200GB 무료 제공 (Boot Volume 성능 압도적)
총평	간단한 Node.js나 파이썬 연습용. 무거운 Java(Spring) + DB 버티기 힘듦.	한국 리전을 무료로 주어 체감 접속 속도 빠름 디스크가 넉넉함. Java 프로젝트의 새로운 은신처로 각광.

비교표를 보면 알겠지만, 한국 리전이 무료로 제공되면서
트래픽이 10TB나 허용되는 OCI는 개인 서버 용도로는 현재 적수가 없다.

OCI 환경 구축: 밑바닥부터 Nginx까지

가장 먼저 맞이한 과제는 그야말로 아무것도 깔려있지 않은
텅 빈 OCI 서버 깡통을, 내 프로젝트가 살아 숨 쉬며 운영 가능한 인프라로 탈바꿈시키는 것이었다.
이 과정은 다음 순서로 진행되었다.

OCI 회원가입 및 우분투 인스턴스 생성
OCI에 가입하는 것부터가 난관이라고들 하지만 운 좋게 한 번에 통과했다.
이후 무료 티어(Always Free)가 제공되는VM.Standard.E2.1.Micro 인스턴스를 하나 파냈다.
운영체제는 패키지 관리가 제일 편하고 레퍼런스가 방대한 Ubuntu 22.04 LTS 버전을 선택했다.
고정 IP 할당 및 도메인 연결
클라우드 인스턴스는 재부팅을 하거나 중지했다가 켜면 가상 IP가 바뀌어버리는 현상이 발생한다.
이렇게 되면 도메인과 연결이 끊어지기 때문에 OCI 콘솔 메뉴에서
예약된 공용 IP(Reserved Public IP)를 하나 발급받아
내 인스턴스의 가상 네트워크(VCN)에 고정으로 물려주었다.
그 후 내가 소유한 호스팅케이알(내 도메인 관리처) 관리자 페이지에 로그인해
이 새로운 고정 IP 주소로 도메인(http://[내부도메인])의 A 레코드를 매핑 연결해주었다.
도커(Docker) 및 인프라 필수 패키지 설치
서버 내부의 폴더들이 파편화되고 의존성 라이브러리가 꼬이는 현상을 막고자
모든 컴포넌트를 Docker 컨테이너 위에서 깔끔하게 통제하기로 했다.
맥북 터미널을 키고 SSH로 우분투에 진입 sudo apt-get update와 함께
Docker 데몬 및 여러 컨테이너를 한방에 띄워줄 수 있는 Docker Compose 패키지를 순차적으로 설치했다.
OCI 방화벽(보안 목록) 포트 개방
내부적으로 애플리케이션의 8080 포트와 웹 서버의 80 포트가 돌고 있어도
OCI 자체가 지닌 방화벽(Security List)이 꽉 막고 있다면 외부 인터넷에서는 절대 접속할 수가 없다.
OCI VCN의 서브넷 설정에 들어가서, HTTP 통신을 위한 80 포트와
HTTPS를 위한 443 포트, 원격 접속을 위한 22 포트에 대한 Ingress(수신) 규칙을
모두 0.0.0.0/0 (전 세계 누구든) 상태로 허용 포트를 개방해주었다.
Nginx 리버스 프록시 설정 및 서버 적용
기존에는 프론트에 WAS가 직접 노출되어 있어서
http://[도메인]:8080 처럼 주소 뒤에 포트 번호를 지저분하게 붙여야만 했다.
이를 개선하고자, 사용자는 깔끔하게 80 포트로 들어오고 그 트래픽을 백엔드의 8080 포트로 자연스럽게 토스해주는
'리버스 프록시(Reverse Proxy)' 설정을 위해 Nginx 웹 서버를 도입했다.

소스코드 레포지토리 루트에 nginx 폴더를 파고
default.conf 설정 파일을 만들어 아래와 같은 설정을 부여했다.

server {
    listen 80;
    listen [::]:80;
    server_name [내부도메인];

    location / {
        # app은 Docker Compose에서 명명한 Spring Boot 컨테이너 이름
        proxy_pass http://app:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

이후 루트의 docker-compose.yml 파일에
Nginx 이미지를 받아오는 컨테이너 정의를 추가하고
호스트의 ./nginx 디렉토리를 컨테이너 속 /etc/nginx/conf.d 로 마운트하여
이 설정 파일을 자동으로 읽어오도록 구성했다.

GitHub Actions 자동 배포 세팅 완료
손으로 매번 코드를 빌드하고 옮기고 재시작하는 수동 배포의 번거로움을 덜기 위해
.github/workflows/deploy.yml 파일을 작성해 CI/CD 파이프라인을 구축했다.

appleboy/ssh-action 플러그인을 활용해 OCI 서버에 은밀하게 접속한 다음
docker-compose down -v 로 기존 컨테이너를 내리고
변경된 코드들과 함께 docker-compose up -d --build 명령어가
자동으로 실행되도록 스크립트를 조율했다.

설정한 모든 세팅을 마치고 떨리는 마음으로 크롬 브라우저에 http://[내부도메인] 주소를 쳐서 엔터를 눌렀다.
드디어 로컬 컴퓨터에서만 보던 우리 프로젝트의 반가운 웰컴 페이지가 OCI 망을 타고 아름답게 나타났다!

문제 상황 통보: 죽음의 무한 로딩

Nginx 경로 세팅이며 Docker 배포 자동화까지 모든 것이 너무도 교과서처럼 완벽하게 끝났다고 생각했다.
아주 흐뭇한 마음으로 개발 서버 대시보드를 둘러보기 위해 Admin 계정으로 로그인을 시도하는 버튼을 클릭했다.

그런데 화면 중앙의 로그인 로딩 스피너 창이 빙글빙글 돌기 시작했다.

처음엔 클라우드 데이터베이스 초기 로딩이 유독 느린가 싶어 기다려 보았다.
개발자 도구 네트워크 탭을 열어보니 pending 상태로 응답을 애타게 기다리고 있었다.
요상함을 느끼고 요청을 Esc 키로 강제 취소한 뒤 다시 가벼운 웰컴 페이지로 접속을 시도했으나
이제는 아예 빈 화면만 뜨고 브라우저가 아무런 반응조차 하지 않았다.

그렇게 하염없이 1분여를 기다리자
브라우저에는 504 Gateway Time-out 에러 화면이 출력되었다.

Nginx는 살아서 어떻게든 앞단을 지키고 있었지만 뒤에서 답을 줘야 할 Spring Boot가 기절했다는 확실한 표식이었다.

설상가상으로 구체적인 원인을 파악하기 위해 서버에 SSH 접속 툴(Mac의 iTerm)을 켜고 터미널 접근을 시도했지만

웬걸...

Connection timed out 에러 문구만 덩그러니 내뱉으며 심지어 터미널은 내 키보드 입력을 모두 무시했다.

어플리케이션(Spring Boot)만 죽은 게 아니었다.

OCI 리눅스(Ubuntu) 운영체제 껍데기 전체가 완전히 동태가 되버린 Kernel Freeze 상태인 것이다.

첫 번째 시도: 코드 변경 로그 확인 및 재배포 모니터링 (실패)

시도한 이유 ⁇

가장 처음 드는 합리적 의심은 방금 내가 직접 작성한 Nginx의 라우팅 설정 파일(default.conf)이

오타나 논리 오류로 인해 내부에서 통신 무한 루프 상태에 빠졌을 가능성이었다.

또는 JWT 인증이나 Spring Security 로직에서 토큰을 빙빙 돌리며
자원을 독식하는 결함이 배포 과정에서 함께 숨어 들어갔다고 의심했다.

적용 방법

터미널조차 연결되지 않는 이 깡통 상태를 풀기 위해 OCI 클라우드 콘솔 홈페이지에 직접 접속했다.
인스턴스 전원을 차단(Force Stop)하는 메뉴를 눌러 가상머신을 물리적으로 재부팅하고 다시 시작(Start)시켰다.
서버가 간신히 켜지자마자, 다음 다운이 오기 전에
도커 컨테이너들의 로그 스트림(docker-compose logs -f) 명령어를 띄웠다.
그리고 Nginx proxy_pass 설정에 잘못된 헤더나 Loop 옵션이 있는지 두 눈에 불을 켜고 확인했다.

문제점 및 한계

하지만 까보면 깔수록 Nginx 설정은 문법적 오류 하나 없이 너무나 완벽했다.
(Gemini가 써준거라 완벽한 줄 알았다 )

에러 로그 한 줄 보이지 않았다.

서버가 막 재부팅된 직후에는 웰컴 페이지 접속이 아주 평온하고 빠르게 잘 진행되었다.

그러나, 다시 브라우저 창을 열고 Admin 인증을 거쳐 수많은 회원 테이블과 가입 통계를 조인해서 불러오는
'강력한 DB 내부 로직'이 담긴 API를 호출하는 순간

또다시 어김없이 터미널의 커서가 정지해버리며 서버 전체가 기절해버렸다.
예외(Exception) 추적 로그를 살펴보고 자시고 할 여유조차 주지 않고

또 다시 빵- 하고 OCI 서버가 마비된 것이다.

배운 점
Nginx 컨테이너가 끝끝내 사용자 브라우저에 에러 응답(504)을 잘 던져주고
뒷단 시스템 전체가 통제 불능이 된다는 것은
단순한 프록시 규칙 에러나 코드의 무한 연산 문제가 아니라는 걸 깨달았다.
이는 그 뒤에서 구동 중인 대형 WAS(Spring Boot) 및 다른 요소들이 서로 경합하다가
물리적인 서버의 핵심 리소스를 아예 고갈시켜버린 인프라 레벨의 치명상이라는 뜻이다.

최종 해결: 인공호흡기 가상 메모리(Swap File) 할당

근본적 원인 분석 (OOM 패닉 현상)
문제의 본질은 OCI 무료 티어 인스턴스가 가진 치명적인 사양적 한계 때문이었다.
CPU 아키텍처나 엄청난 디스크 용량이 전부가 아니다.
가장 중요한 워크스페이스인 물리적 메모리(RAM)가 단 1GB에 불과하다는 점이 재앙의 씨앗이었다.

현재 돌리고 있는 우리 프로젝트의 사양을 계산해보면 답이 나온다.
무거운 JVM 기반의 거대한 Spring Boot WAS 컨테이너 하나가 기본 400MB 이상을 점유하고

PostgreSQL 데이터베이스가 200MB, 비동기 통신을 제어하는 RabbitMQ가 또 200MB...

게다가 트래픽 앞단을 지키는 Nginx와 GitHub 배포를 위한 데몬 서비스들까지...
무려 5마리의 덩치 큰 프로세스들이 좁디좁은 1GB RAM 공간(자취방) 안에서 숨 막히게 공존하고 있었다.

평온하게 대기 중일 때는 이들이 어떻게든 구겨져서 아슬아슬하게 적재되어 있다.

~~(대만의 구룡성채나 다름없는 듯 )~~

하지만, 내가 '로그인'을 진행한 순간 Spring Data JPA 구현체가 대량의 테이블을 읽어
영속성 컨텍스트(메모리 캐시) 공간에 엔티티들을 대거 적재하려 든다.

이때 RAM 사용량이 순식간에 100% 임계점을 뚫고 나갈 기세로 되는 것 이다.

Linux 운영체제(커널)는 물리 메모리가 극도로 부족해 시스템이 위험해지면
가용한 공간을 확보하기 위해 가장 RAM을 많이 먹고 있는 녀석을 골라
강제로 사살해버리는 OOM(Out of Memory) 킬러 메커니즘을 발동시킨다.

이때 보통 Java(+Spring Boot) 프로세스가 제일 첫 번째 타깃 이 되어 죽는다.

더 심각한 문제는 OCI 서버의 초기 우분투 세팅에는 스토리지 디스크(SSD)의 빈 공간을 잠시 빌려 쓰는
가상 메모리 영역인 Swap 메모리가 단 1Byte도 존재하지 않는 0B로 세팅되어 있었다는 점이다.
RAM 용량이 초과되었을 때 잠시 피난 갈 수 있는 최후의 보류(인공호흡기) 공간이 아예 없어서
OOM 킬러마저도 프로세스를 정리하지 못하고 커널 패닉에 빠져

서버 전체가 쇼크사(System Freeze) 해버린 것이다.

최종 적용 방법 및 구현 코드
이를 해결하기 위한 조치는 간단명료하다.

돈을 쓰면 된다.

정말 미니PC를 살까 고민도 했다.

그래도 일단 , 무료 티어로 버텨보자 싶었다.

그래서 하드디스크(SSD)의 넉넉한 200GB 무료 공간 중 자투리 2GB를 강제로 빼앗아 잘라내고
이를 가상 RAM처럼 작동하게 만들어주는 리눅스 Swap 영역 할당 설정을 수동으로 진행하면 된다.

OCI 콘솔에서 서버 강제 재부팅을 또다시 먹인 직후 도커 컨테이너들이 모두 구동되며

메모리를 잡아먹기 전의 골든 타임(약 2분) 안에 터미널을 열고 재빨리 아래 명령어들을 순차적으로 쏟아부었다.

# 1. 시스템 루트 파티션에 2GB 크기의 커다란 빈 파일(스왑용) 생성
# fallocate는 dd 명령어보다 할당 속도가 훨씬 빠르다
sudo fallocate -l 2G /swapfile

# 2. 스왑 파일의 권한 변경
# 관리자(root) 계정만 읽고 쓰기가 가능하도록 권한을 600으로 막아야 보안 경고가 뜨지 않는다.
sudo chmod 600 /swapfile

# 3. 방금 만든 일반 빈 파일을 스왑 공간 구조로 내부 포맷
sudo mkswap /swapfile

# 4. 포맷된 해당 공간을 가상 메모리로 리눅스 커널에 활성화 명령!
sudo swapon /swapfile

# 5. 마운트 테이블(/etc/fstab)에 영구 등록
# 이 설정을 잊으면 다음 재부팅 때 스왑 메모리가 날아간다.
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# 6. 최종 할당 상태 확인
free -h

저 명령어들을 실행한 후 마지막으로 free -h를 입력하여 상태표를 보았을 때
눈앞에 나타난 글자는 이제 잘 수 있구나를 외쳤다 !

기존 Swap: 0 자리에 Swap: 2.0Gi 라는 수치가 뚜렷하게 잡혀
시스템에 든든한 보조 메모리 공간이 확보된 것이다.

이후 다시 Admin 환경에 접속하여 대략 2만건의 데이터를 긁어오는 복잡한 조인 쿼리 로직 버튼을 과감히 눌러 보았다.
터미널 모니터링 창에서 RAM 활용도가 1GB의 한계치인 95%를 뛰어넘으려 할 때마다

눈치 빠른 시스템이 즉각 백그라운드 프로세스들을 방금 만든 2GB의 Swap 영역으로 밀어내주기(Paging) 시작했다.

그 결과, 단 한 번의 에러 스파이크나 타임아웃 멈춤 현상 없이
Spring Boot 서비스가 마치 16GB 메모리 서버에 있는 양 아주 쾌적하게 끝까지 동작을 무사히 마쳤다!

한눈에 보는 OCI 서버 인프라 전체 설정 순서표

이번 인프라 환경 이전 및 요금 청구 사태로 시작된 OCI 마이그레이션과 장애 대응 전체 이력 타임라인을 적어보았다.
다음에 또 내가 서버를 구성할 때 참고하실 수 있도록 하나의 테이블으로 정리해 본다.

진행 순서	핵심 작업 항목	작업 상세 내용 요약
Step 1	OCI 회원가입 및 서버 세팅	오라클 클라우드 가입 후, Ubuntu 22.04 LTS 이미지를 사용 무료 제공 규격인 `VM.Standard.E2.1.Micro` 인스턴스 신규 생성함.
Step 2	네트워크 및 고정 IP 설정	재부팅 시 IP 유실 방지로 Reserved Public IP 발급 인스턴스에 고정 할당함. 발급받은 IP는 구매한 도메인 DNS에 A 레코드로 직접 매핑 연결.
Step 3	서버 필수 의존 패키지 설치	SSH 원격 접속 후 인스턴스 내부에 패키지 관리자를 통해 Docker 데몬 Docker Compose 오케스트레이션 툴 Git을 설치
Step 4	OCI 보안 정책 및 방화벽 개방	OCI VCN의 Security List 수정 메뉴에 접근 HTTP(80), 443 포트& SSH(22) 수신 룰 완전히 오픈
Step 5	앞단 Nginx 웹 프록시 구성	루트 `nginx/default.conf` 파일을 작성 사용자의 80 포트 요청을 백엔드 스프링부트 컨테이너 8080 포트로 내부에서 패스하도록 브릿지 생성.
Step 6	인프라 CI/CD 배포 파이프라인	Github Actions의 deploy 스크립트를 작성 메인 브랜치 푸시 시 자동 서버 SSH 접속 및 `docker-compose up` 갱신 구동 파이프라인 구축 완료.
Step 7	치명적 메모리 부족 장애 발생	OCI 환경 구축 완료 후 첫 관리자 로그인 시도 시 화면 무한 로딩, 504 Time-out 발생 및 서버 OOM 판정 우분투 전체가 다운되는 등 완전 먹통 현상 마주.
Step 8	Swap 메모리 영역 강제 추가	장애 해결의 핵심! 터미널 접속 후 `fallocate`로 2GB 공간 스왑 영역 지정 권한 부여 및 `fstab` 영구 등록 , 이후 모든 프로세스 정상 동작 확인!

배운 점

인프라 관리는 코드 너머의 숲을 보는 것이다.
백엔드 개발자라 할지라도 단순히 자바 코드와 어플리케이션 아키텍처 결함만 볼 게 아니다.
배포되는 클라우드 인스턴스의 베어메탈 급 물리적 시스템 리소스(RAM 사용률, CPU Idle 상태, Disk I/O)도
반드시 htop이나 top 명령어로 직접 들여다보는 모니터링 습관을 길러야 한다.

504 에러의 숨은 함정
Nginx 등 리버스 프록시 앞단을 세웠을 때 클라이언트 브라우저에서 맞는 504 Gateway Time-out은
주로 백엔드 서버(WAS) 환경 시스템 자체가 아예 기절해서 응답을 줄 컴퓨팅 리소스가 없기 때문에 흔히 발생한다.
에러를 보자마자 다짜고짜 애먼 네트워크 인증 통신이나 라우팅 구성만 의심하고
파싱 코드를 뒤지면 하루 종일 답도 없는 삽질을 하게 된다.

무료 티어 클라우드의 현실적인 생존 필수값
해외 클라우드 벤더사(GCP, AWS, OCI 등)가 홍보성으로 제공하는 제일 저렴한 무료 마이크로 1GB 인스턴스는
RAM이 지독하게 쪼들린다. 만약 로컬에선 잘 되던 프로젝트가 이곳에 배포했을 때 수시로 죽는다면
Docker 여러 개와 무거운 JVM 기반 프레임워크를 올릴 땐 Swap 가상 메모리 우회 세팅을 하는 것이
선택 옵션이 아니라 그냥 생존을 위한 필수 전제조건임을 아주 뼈아프게 극복해내며 배웠다.

나의 삽질 및 실수 모음집 & 해결 팁

이번 인프라 구축 과정에서 정말 자잘하고 어이없는 실수들을 많이 저질렀다.
나름 잘 설정했다고 생각했는데 안 되어서 당황했던 포인트들을 모아 보았다.

1️⃣ Nginx 443 포트 매핑 누락
Nginx 설정 파일(default.conf)에는 listen 443 ssl; 이라고 적었다.
Nginx 자체가 HTTPS 포트를 열어두도록 완벽하게 잘 만들었다.
그런데 서버에 제일 바깥에서 컨테이너를 띄우는 docker-compose.yml 파일에서
정작 443:443 포트를 외부로 개방(매핑)하는 설정을 빼먹었다.

해결 팁
도어락은 바꿨는데 현관문을 안 열어준 격이다.
docker-compose.yml 파일의 ports 설정에 꼭 443 포트를 추가하자.

2️⃣ 도커 빌드 실패(Build failed) - .jar 파일 2개 오지랖
로컬에서 잘 빌드되던 도커가 서버에서 자꾸 죽길래 봤더니
빌드 결과물 폴더에 기본 .jar 파일과 함께 -plain.jar 파일까지 2개가 생성되어 있었다.
도커 데몬 입장에서는 어떤 jar 파일을 카피해서 구동해야 할지 몰라 빌드가 실패한 것이다.

해결 팁
로컬 프로젝트의 build.gradle 파일에 -plain.jar 파일은 아예 생성되지 않도록 설정
(jar { enabled = false })을 딱 한 줄 추가해 두어 깔끔하게 해결했다.

3️⃣ docker compose vs docker-compose 버전 충돌
어떤 가이드 문서에는 띄어쓰기가 있고 어떤 건 하이픈(-)이 있어서 헷갈렸는데,
결국 내가 설치한 서버 환경(구버전 호환)에서는 띄어쓰기를 한 docker compose 명령어가 작동하지 않았다.

해결 팁
배포 스크립트의 명령어를 모두 docker-compose 구문으로 바꿔서 구동시켰다.

4️⃣ GitHub Actions Nginx 폴더 누락
CI/CD를 통해 배포가 쫙쫙 잘 된 줄 알았는데, Nginx 컨테이너가 켜지자마자 죽어버렸다.
로그를 까보니 호스트 서버에 nginx/default.conf 파일이 존재하지 않는다는 에러였다.

해결 팁
deploy.yml 배포 스크립트 안에서 scp 커맨드로 파일을 클라우드 서버에 복사해 넘길 때
docker-compose.yml만 넘기고 nginx 디렉터리는 안 넘기고 있었다.
scp -r에 ./nginx 폴더를 포함시켜서 해결했다.

5️⃣ .env 파일 무자비한 덮어쓰기 대면책
서버 DB 비밀번호 같은 환경변수를 GitHub Actions의 Secrets로 주입할 때 초보적인 실수를 저질렀다.
echo "${{ secrets.DB_PASS }}" > .env 형식처럼 꺾쇠 화살표 한 개(>)를 쓰는 바람에,
기존에 만들어 둔 수많은 .env 속 변수들을 모두 싹둑 날려버리고 저거 단 한 줄만 덮어써 버린 것이다.

해결 팁
파일 내용을 덮어쓰는 게 아니라 맨 밑에 '내용 추가' 만 하려면 꼭 화살표 두 개(>>)를
붙여서 써야 한다는 리눅스 커맨드의 무서움을 깨달았다.

인프런(인프랩) 방문기 | 공약은 반드시 지킨다 (feat. 카파도키아 파우치)

김춘덕⸝ဗီူ⸜ — Wed, 1 Apr 2026 22:00:55 +0900

공약의 시작

2월 인프런 챌린지가 한창 진행 중이던 어느 날

나는 생각나는 데로 공약을 걸었다.

"만약 제가 상금을 받게 되면, 3월 신혼여행에서 도라님 선물 사올게요."

챌린지를 열심히 하다 보면 그런 기분이 드는 순간이 있다.

이걸 해낼 수 있을 것 같다는 근거 없는 자신감.

그래서 던진 공약이었는데, 상금도 받고 꿈도 꾸지 못한 MVP가 되어버렸다.

MVP가 되면 인프런 수강권 6개월권을 받는데

정말 받아버렸다 !!!!!!!!!

기쁘기도 했지만 솔직히 공약이 더 머릿속에 남았다.

뭘 사다드려야 하지?!

카파도키아에서 파우치를 샀다

신혼여행지는 튀르키예였다.

인천 ➡️ 이스탄불 ➡️ 카파도키아 ➡️ 이스탄불 ➡️ 인천

열기구 타고 하늘 뜨는 곳, 드라마 세트장 같은 절벽 마을들.

정신없이 다니면서도 머릿속 한켠에는 계속 생각이 있었다.

도라님 선물 사야 하는데 . .

그렇게 카파도키아 기념품 가게를 기웃거리다가 파우치를 하나 집어들었다.

튀르키예 특유의 알록달록한 풍선 그림이 자수로 들어간 파우치.

보자마자 오! 딱 좋겠다 싶었다❤️

파우치만 가져가면 좀 허전하니까, 튀르키예 차 티팩도 몇 개 넣었다.

현지에서 마셨는데 맛이 좋았거든.

거기에 결혼 답례품도 챙겨서 같이 드리기로 했다.

공약 하나가 나를 카파도키아까지 생각나게 한 셈이다.

신행 후, 드디어 인프랩으로

튀르키예에서 돌아오고 나서 며칠은 재택을 했다.

시차 적응도 해야 하고, 몸도 좀 쉬어야 했다.

그러다 오랜만에 회사에 출근하는 날

도라님 선물과 회사 분들 선물짐을 챙겨서

출근을 했다.

가슴이 콩닥콩닥

퇴근시간이 되서 바로 인프랩으로 향했다.

회사에서 버스를타고 약 30분. 생각보다 멀지 않았다.

(사실 집에 가는 길목이기도 함ㅋㅋ)

인프랩 문 앞에 섰을 땐, 기분이 좀 묘했다.

인프런 마크는 모니터에서만 보던 것 인데,

내가 실제로 여기 와 있구나 하는 감각.

뭔가 팬 미팅에 온 것 같기도 하고. .

아니면 취업 준비할 때 가보고 싶던 회사에 처음 들어가는 느낌 같기도 했다.

향로님,시몬님,도라님을 실물로 뵀다❤️

챌린지 때마다 화면 너머로 뵙던 도라님을 드디어 실물로 뵀다.

진짜로 있는 분이었다.

(당연히 있는 분이지만, 그 감격이 있잖아.)

시몬님도 함께 나와주셔서 인프랩 내부를 구경시켜 주셨다.

여기저기 돌아보면서 "와, 여기서 근무하시는 거구나" 하는 생각이 계속 들었다.

그중에 챌린지 때 방송하시던 방도 보았는데,

그때 당시엔 집에서 하시는 줄 알았다. 알고 보니 사무실이었다.

구경하다 보니 직원들을 세심하게 챙겨주는 부분들이

곳곳에 눈에 들어왔다. 솔직히 부러웠다. . . . (우리 회사도 . . 크흡. .)

특히 놀란 건, 도라님이 갑자기 대표님을 소개시켜 주셨던 순간이었다.

누가 봐도 그냥 자기 자리에서 조용히 일하고 계신 일반 직원분처럼 보이셨는데

그분이 대표님이라고 하셔서 깜짝 놀랐다.

캐주얼한 분위기도 놀라웠지만, 전혀 티가 안 나신 것도 놀라웠다.

수평하고 자유로운 분위기, 정말 페어한 곳이구나 싶었다.

잠시 휴게실에 앉아 도라님께 카파도키아에서 사온 파우치와 티팩, 결혼 답례품도 드렸다.

작은 거지만 공약을 지켰다는 뿌듯함이 있었다.

그리고 개발계의 아이돌, 향.로.님❤️

사실 인프랩에 들어갔을 때부터 회의 중이셔서 못 뵙고 갈 것 같았다.

퇴근 시간도 임박해오고, 아쉬움을 달래며 슬슬 돌아서려던

그 순 ‼ 간 ‼ 향로님이 나타나셨다.

그래서 악수도 하고 사진도 찍었다.

너무 좋았다. (이만하면 성덕 인정인가?)

도라님이 챙겨주신 인프런 굿즈도 너무 좋았다.

짱짱한 티셔츠에, 컴팩트해서 소지하기 좋은 우산, 그리고 인프런 스티커까지.

~~(오늘 출근할 때 인프런 티셔츠 입은 건 비밀이다.)~~

인프런과 나의 인연

생각해 보면 인프런이랑 인연이 꽤 길다.

늦은 나이에 개발자 공부를 시작했다.

직장을 다니면서 사이버대도 병행하면서. 솔직히 힘들었다.

그냥 포기하고 싶은 순간도 있었다.

그때 개발바닥 유튜브를 보면서 많이 버텼다.

"나만 힘든 게 아니구나, 다들 이렇게 시작하는 거구나" 하는 안도감 같은 게 있었다.

개발바닥을 보다가 김영한 선생님의 존재를 알게 됐다.

그리고 어느 날 인스타에서 인프런 광고가 떴다.

개발바닥에서 보던 향로님이 계신 곳이라는 걸 알고 있었기 때문에 자연스럽게 가입했다.

처음엔 나도코딩님의 무료 강의 몇 개를 봤다.

그러다 김영한 선생님의 자바 기초 강의가 한번 무료로 풀린 적이 있었는데, 그게 시작이었다.

강의가 너무 좋았다. 설명이 너무 명확하고, 왜 이렇게 하는지를 알려주는 방식이 마음에 들었다.

그다음 강의, 또 그다음 강의.

지금 돌이켜보면 영한 선생님 강의는 안 들어도 이미 좋은 가격이고 좋은 내용이면

일단 구매 가 나의 기준이 됐다.

현재 총 13개를 구매했고, 그중 완강은 7개 정도 됐다.

나머지도 서서히 다 들을 예정이다.

제로초님, 토비님 강의도 결제해서 보고 있다.

인프런이 내 개발 공부의 거의 대부분을 차지하게 됐다.

챌린지가 나를 다시 일으켰다

개발자로 취업한 이후, 한동안 성장하고 있다는 느낌이 안 들었다.

그냥 출퇴근하고 주어진 일만 하다 보니까 어느 순간 공부도 손에서 놓게 됐다.

그러다 다시 정신 차리고 공부를 재개할 무렵, 자극이 필요하다는 걸 느꼈다.

혼자 하는 공부의 한계 같은 거.

그렇게 인프런에서 처음 챌린지를 접하게 됐다.

향로님이 진행하던 챌린지였다.

해내고 나서의 그 희열감이 지금도 기억난다.

내가 뭔가를 완수했다는 감각.

다른 사람들의 글을 보고, 서로 응원하고.

혼자 공부할 때는 느끼기 어려운 감각이었다.

그게 좋아서 계속 챌린지에 참여하게 됐고, 그 끝에 2월 MVP가 됐다.

챌린지를 거치면서 공부에 다시 재미를 붙이게 되니, 이것저것 덩달아 다시 살아나기 시작했다.

미뤄두기만 했던 개인 프로젝트도 시작했고, 손 놓고 있던 티스토리도 다시 글을 올리기 시작했다.

그리고 한동안 황량했던 깃 잔디가 조금씩 푸릇푸릇해지고 있다.ㅋㅋ

gayulz - Overview

rebase했다가 과거를 바꿨습니다. gayulz has 8 repositories available. Follow their code on GitHub.

github.com

그리고 이 글을 통해 막간 홍보를 하자면

4월 챌린지가 지금 시작했다❤️

내일부터 시작이니 빨리 같이 시작할 사람들은

링크를 타고 들어가서 빨리들 가입하시라 . .

[인프런 챌린지] 4월 봄 맞이 인프런 운동회 챌린지 | 인프런 - 인프런

789명이 수강했던 챌린지, 지금 바로 살펴보세요. 혼자 하는 공부는 오래가기 어렵습니다! 그렇다고 단순한 인증 챌린지도 오래 남지 않죠. 4월, 인프런에서 팀전으로 참여할 수 있는 ‘봄 맞이

www.inflearn.com

마무리

인프랩에서 나오면서 드는 생각은 하나였다.

참 감사하다. 인프런이란 플랫폼에서 나는 정말 많은 걸 얻고 있다.

공부도 하고, 랠릿을 통해 이력서도 작성하고 업데이트하고, 완강한 수강증을 하나씩 모으면서

트로피를 수집하는 것 같은 뿌듯함도 얻는다.

단순히 강의 플랫폼이라고만 생각했는데, 챌린지를 통해 공부를 이어갈 동력을 얻고

거기서 만난 분들 덕분에 이런 방문까지 하게 됐다.

앞으로도 계속 인프런을 이용할 것 같다.

남은 영한 선생님 강의들도 꾸준히 들을 예정이고, 챌린지도 기회가 되면 또 참여해 볼 생각이다.

공약 하나가 카파도키아 파우치가 되고, 인프랩 방문이 되고, 이 글이 됐다. . .

뭔가 좋은 인연이 계속 이어지고 있는 것 같아서 기분이 좋다.

그리고 언젠가, 더 성장해서 인프런에 꼭 들어가고 싶다.

️ 실무 : Referer로 망분리를 시도했다가 배운 것들 (feat. Stateless vs Stateful)

김춘덕⸝ဗီူ⸜ — Mon, 30 Mar 2026 22:59:01 +0900

⟡ 인트로

OKTA로 인증 방식을 전환하면서 기존 SSO 인증서가 담당하던 내/외부망 구분 기능이 사라졌다.

처음에는 HTTP Referer 헤더를 이용해 내부망 사용자를 판별하려 했으나,

즐겨찾기 접속·OKTA 리다이렉트·forward 등 실제 운영 환경에서 Referer가 소실되는 경우가 너무 많아

정상 내부망 사용자까지 차단되는 문제가 발생했다.

결국 Stateless한 Referer를 버리고, 서버가 상태를 기억하는 세션 플래그(Session Flag) 방식으로 전환하여 문제를 해결했다. 이 글은 그 과정에서 Referer가 무엇이고 왜 접근 제어의 신뢰 기반이 될 수 없는지를 정리한 기록이다.

⟡ 개발환경

AS-IS TO-BE

SSO PKI 인증서 기반 내/외부 구분	OKTA SAML 인증 기반
인증서 유무로 VDI 여부 판단	세션 플래그(INTERNAL_VERIFIED)로 판단
UserInterceptor (비활성, 데드코드)	AuthenticationInterceptor (활성)
Java 1.7 / Spring Framework 4.x	Java 17 / Spring Boot 3.x

⟡ 문제 상황

기존 방식이 사라진 이유

레거시 코드의 인터셉터에는 SSO 인증서를 검증하는 로직이 있었다.

사용자 PC(또는 VDI)에 설치된 사내 인증서 모듈을 호출해서 VDI 여부를 판별했던 것이다.

VDI 사용자  → 인증서 모듈 실행 성공 → SSO 통과 ✅
외부 사용자 → PC에 사내 인증서 없음 → 모듈 로드 실패 → 차단 ❌

브라우저가 보내는 헤더(텍스트)를 믿은 게 아니라, PC 자체에 설치된 암호화된 인증서라는 물리적 증거를 검사했기 때문에

망 분리가 가능했다. 하지만 OKTA로 전환되면서 이 인증서 검증 로직이 사라졌고,

애플리케이션 입장에서는 "이 사람이 VDI 안에 있는가"를 판단할 방법이 없어진 상태가 됐다.

왜 Referer를 먼저 시도했는가

팀 내에서 최초로 나온 아이디어는 HTTP Referer 헤더를 이용하는 것이었다.

요구사항은 아래 두 조건 중 하나를 만족하면 내부 사용자로 보자는 것이었다.

Referer 헤더에 내부망 포털 도메인([내부망 포털])이 포함되어 있음
특정 관문 경로(/main.do)로 직접 접근함

코드로 표현하면 아래와 같다.

private boolean isInternalAccess(String referer, String requestPath) {
    // 조건 A: Referer 체크
    if (referer != null && referer.contains("[내부망 포털]")) {
        return true;
    }
    // 조건 B: 관문 경로 체크
    if (requestPath != null && requestPath.startsWith("/main")) {
        return true;
    }
    return false;
}

겉보기에는 합리적인 것 같았다. 하지만 실제 배포 테스트를 해보니 두 가지 구조적 문제가 드러났다.

⟡ 1번째 시도: Referer 헤더 기반 내/외부 판단 (실패)

시도한 이유

내부망 포털에서 링크를 클릭해 들어오는 경우, 브라우저가 자동으로 출발지 URL을 Referer 헤더에 담아 전송한다.

이 헤더를 인터셉터에서 읽어서 내부망 도메인 포함 여부를 판별하는 방식이다.

문제점 1: 즐겨찾기·주소창 직접 입력 시 Referer는 null

VDI 사용자라도 크롬을 새로 켜고 주소창에 직접 URL을 입력하거나 즐겨찾기로 접속하면,

브라우저는 Referer 헤더를 아예 보내지 않는다. 서버에 도착하는 HTTP 요청을 보면 이렇다.

GET /main.do HTTP/1.1
Host: [내부서버]
User-Agent: Mozilla/5.0 ...
Cookie: JSESSIONID=...
(Referer 헤더 없음)

인터셉터 입장에서는 Referer가 null이므로 "출발지가 없다 → 외부망이다"라고 오판하게 된다.

정상 VDI 사용자가 차단되는 것이다.

문제점 2: forward 또는 OKTA 리다이렉트 시 Referer 증발

/main.do 조건을 통과해 세션 검증 없이 인터셉터를 통과했다고 하자.

이후 forward:/view/p/login.do로 내부 포워딩되는 순간, 서버 내부에서 새로운 요청이 생성되기 때문에

Referer가 비어버린다. OKTA 302 리다이렉트 이후에도 동일한 현상이 발생한다.

/main.do (통과) → forward → /view/p/login.do
→ 인터셉터 재진입
→ Referer: null
→ 차단 ❌

어느 레이어에서 검사해도 결과는 동일하다.

검사 위치 실행 코드 결과

Filter	request.getHeader("Referer")	null → 차단
Interceptor	request.getHeader("Referer")	null → 차단
Controller	request.getHeader("Referer")	null → 차단
JSP/JS	document.referrer	"" → 차단

핵심은 코드의 위치 문제가 아니라, 데이터의 부재 문제다.

브라우저가 제공하지 않는 정보는 서버의 어떤 레이어에서도 만들어낼 수 없다.

배운 점

Referer는 Stateless 방식이다. "지금 이 순간의 요청"이 어디서 왔는지만 알 뿐"
이 사람이 아까 어떤 경로로 들어왔는지"는 기억하지 못한다.
접근 제어처럼 연속적인 상태를 기억해야 하는 로직에는 태생적으로 부적합하다.

⟡ 최종 해결: 세션 플래그(Session Flag) 방식

Referer를 버리고 세션(Session)으로 관점을 바꿨다.

세션은 브라우저를 닫기 전까지 상태를 기억하는 Stateful한 저장소다.

아이디어는 단순하다.

/main.do 관문을 통과한 사람의 세션에 "내부망 인증 완료" 도장을 찍어두고,
이후 모든 요청에서는 Referer를 보지 않고 이 도장의 유무만 확인한다.

핵심 설계

1. 상수 정의 — 관문 URL 변경 시 이 한 곳만 수정하면 된다.

public final static class NetworkAccess {
    public static final String GATEWAY_PATH                  = "/main.do";
    public static final String OKTA_SAML_CALLBACK_PATH       = "/login/okta-saml-check.do";
    public static final String SESSION_KEY_INTERNAL_VERIFIED = "INTERNAL_VERIFIED";
}

2. 관문 컨트롤러 — /main.do 진입 시 세션에 플래그를 세팅한다.

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.servlet.ModelAndView;
import javax.servlet.http.HttpServletRequest;

@Controller
public class MainRedirectController {

    @RequestMapping(NetworkAccess.GATEWAY_PATH)
    public ModelAndView redirectMainToLogin(HttpServletRequest request) {
        // 내부망 진입 도장 찍기
        request.getSession().setAttribute(
            NetworkAccess.SESSION_KEY_INTERNAL_VERIFIED,
            Boolean.TRUE
        );
        return new ModelAndView("forward:/view/p/login.do");
    }
}

3. 인터셉터 판단 로직 — Referer 대신 세션 플래그만 본다.

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;

private boolean isInternalAccess(HttpServletRequest request, String requestPath) {

    // 1. /main.do 관문 진입: 무조건 통과 (세팅은 컨트롤러에서)
    if (requestPath != null
            && requestPath.indexOf(NetworkAccess.GATEWAY_PATH) > -1) {
        return true;
    }

    // 2. OKTA SAML 콜백: 세션이 재생성되므로 이 시점에 플래그 재세팅
    if (requestPath != null
            && requestPath.indexOf(NetworkAccess.OKTA_SAML_CALLBACK_PATH) > -1) {
        request.getSession().setAttribute(
            NetworkAccess.SESSION_KEY_INTERNAL_VERIFIED,
            Boolean.TRUE
        );
        return true;
    }

    // 3. 그 외 모든 요청: 세션 플래그 유무만 확인
    HttpSession session = request.getSession(false);
    return session != null
        && session.getAttribute(NetworkAccess.SESSION_KEY_INTERNAL_VERIFIED) != null;
}

처리 흐름

VDI 사용자 → /main.do 접속
  → 세션에 INTERNAL_VERIFIED=true 세팅
  → OKTA 인증 완료 (세션 재생성 시 콜백에서 재세팅)
  → 이후 모든 요청: 세션 플래그 확인 → 통과 ✅

외부 사용자 → /view/p/login.do 직접 접속
  → 세션 플래그 없음
  → external-notice.jsp 차단 화면 ❌

왜 OKTA 콜백에서 플래그를 재세팅해야 하는가

OKTA SAML 인증이 완료되면 Session Fixation 공격 방지를 위해 세션 ID가 교체된다.

기존 세션에 저장해둔 INTERNAL_VERIFIED 플래그도 함께 사라지게 된다.

이를 방치하면 로그인 직후 AJAX 요청이 전부 차단된다.

/login/okta-saml-check.do 콜백 진입 시점에 플래그를 재세팅하면 이 문제를 방어할 수 있다.

⟡ 배운 점

Referer는 "지금"만 알고 세션은 "흐름 전체"를 기억한다.
접근 제어처럼 요청 간의 맥락이 필요한 로직은 Stateless한 헤더가 아니라
Stateful한 세션을 신뢰 기반으로 삼아야 한다.
데이터의 부재는 코드의 위치로 해결할 수 없다.
Referer 검사를 Filter·Interceptor·Controller·JSP 어디로 옮겨도 결과는 동일하다.
"어디서 검사하는가"가 아니라 "검사할 값이 존재하는가"의 문제이기 때문이다.
완벽한 망분리를 원한다면 클라이언트 IP 화이트리스트나 인프라 레벨 정책이 유일한 해답이다.
브라우저가 선택적으로 전송하는 헤더(Referer)에 의존하는 방식은 언제든 우회될 수 있다.
세션 플래그 방식은 현실적인 절충안이지, 완벽한 보안 솔루션이 아니다.

신입개발자

‍ Springframwork Mig 기록 - GitLab CI/CD 빌드 환경 맞추기 (feat. Gradle 프로필 빌드)

인트로

개발환경

문제 상황

1번째 시도: 담당자 로컬 PC 환경을 빌드 서버 환경으로 이해하기 (실패)

2번째 시도: GitLab Runner가 하는 일을 직접 따라가기 (성공)

3번째 시도: 운영 프로필을 하나로 묶어 빌드하기 (실패 직전)

최종 해결: 운영 서버별 Gradle 프로필 빌드로 분리하기

Maven 프로필과 Gradle 프로필이 달랐던 지점

빌드 실행 서버를 DEV 서버와 함께 쓰는 구조에서 주의할 점

배운 점

참고 링크

주니어 백엔드 개발자가 반드시 알아야 할 실무 지식 : 신입이 알아야 할 DB 성능·풀스캔·인덱스 9가지

인트로

수집 대상

개발환경

문제 상황

1번째 시도: 검색 조건마다 인덱스 추가하기

2번째 시도: 조회 패턴 기준으로 복합 인덱스 설계하기

3번째 시도: LIKE 검색을 전문 검색으로 분리하기

정규화와 비정규화는 언제 고민해야 할까?

조회 범위를 줄이는 것도 성능 개선이다

전체 개수를 세지 않는 것도 방법이다

오래된 데이터는 삭제하거나 분리 보관해야 한다

DB 장비 확장과 캐시는 마지막 카드가 아니다

최종 정리: DB 성능을 볼 때의 순서

배운 점

참고 링크

‍ Springframwork Mig 기록 : 화면에는 없는데 서버에는 필요한 값들 (feat. 세션 기반 파라미터)

인트로

개발환경

문제 상황

1번째 시도: 요청 파라미터만 확인하기 (실패)

2번째 시도: 세션에서 암묵적으로 채우던 값 추적하기 (성공)

최종 해결: 세션 유틸리티로 접근을 통일하고 NPE를 먼저 막기

실행 방법

실행 가능한 예제 코드

마이그레이션 QA에서 추가한 체크 포인트

배운 점

참고 링크

⚡️개발자가 자주 사용하는 NANO명령어 (알쓸나잡) : Vim 유저도 당황하지 않는 Nano 편집기 완벽 가이드 (설정부터 커스텀까지)

시작에 앞서

한눈에 보는 에디터 비교: Nano vs Vim

1. Nano의 첫인상을 바꾸는 ~/.nanorc 설정

필수 추천 설정값

2. Vim 유저를 위한 "Nano에서 Vim 맛내기"

3. Nano 핵심 명령어 Cheat Sheet

✂️ 편집 및 검색 (가장 중요!)

파일 관리

4. 실전 팁: 멀티 버퍼 활용하기

마치며

⚡️개발자가 자주 사용하는 VIM 명령어 모음 : 알아두면 쓸데있는 Vim 잡학지식(알쓸빔잡)

1. 모드 전환 (Mode Switching)

2. 커서 이동 - 기본 (Basic Movement)

3. 커서 이동 - 단어 (Word Movement)

4. 커서 이동 - 화면/파일 (Screen/File Movement)

5. 삭제 (Delete)

6. 복사 & 붙여넣기 (Yank & Paste)

7. 변경 (Change)

8. 실행 취소 & 반복 (Undo & Repeat)

9. 검색 (Search)

10. 치환 (Substitute)

11. 파일 & 버퍼 (File & Buffer)

12. 창 분할 (Window Split)

13. 탭 (Tab)

14. 들여쓰기 & 포매팅 (Indent & Format)

15. 매크로 & 기타 (Macro & Others)

팁

️ 실무 : StrictHttpFirewall이 동작하는 원리 (feat. PROPFIND, WebDAV) | PROPFIND가 뭐예요 ?

주제 정의

원전 / 공식 스펙 요약

HttpFirewall 인터페이스

StrictHttpFirewall의 검사 항목

PROPFIND와 WebDAV

실무 해석 및 분석

요청 차단 흐름 상세 분석

왜 폐쇄망 서버에서 간헐적으로 발생하는가?

이 로그는 위험한가?

DefaultHttpFirewall과의 차이

3번째 시도: `LIKE` 검색을 전문 검색으로 분리하기

1. Nano의 첫인상을 바꾸는 `~/.nanorc` 설정