1Dev Log

프로젝트 회고록 (2) - KBO:NOTE

SoloQuest — Sat, 29 Aug 2026 23:37:32 +0900

이번 회고록은 조금 색다른 시작을 가진 프로젝트 이야기다. 팀을 직접 꾸린 것도 아니고, 학교 수업도 아니었다. 컨퍼런스에서 우연히 만난 인연으로 시작된 사이드 프로젝트, KBO:NOTE 이야기다.

우연한 시작

어느 날 갔던 컨퍼런스에서 우연히 한 분을 만났다. 사이드 프로젝트를 같이 만들 개발자를 구하고 있다고 하셨다. 야구 관련 앱이었고, 겨울방학 동안 만들어서 KBO 시즌이 시작되기 전에 런칭하는 게 목표라고 했다. 재밌겠다는 생각이 먼저 들었다.

사실 그 당시 이미 진행 중인 프로젝트가 두 개나 있어서 처음엔 부담스러워 거절했다. 그런데 이야기를 더 들어보니 작은 역할만 맡으면 될 것 같아서 결국 하게 됐다.

제안해주신 분이 PM을 맡았는데, 팀원을 각자 따로 모으다 보니 기술 스택이 다 다를 수 있다고 하셨다. 그래서 MSA(마이크로서비스 아키텍처) 방식으로 진행한다고 했다. 이게 나에게는 꽤 매력적으로 다가왔다. MSA라는 개념 자체를 잘 모르고 있었는데, 직접 경험해볼 좋은 기회라는 생각이 들었다.

마침 PM님이 프론트엔드 팀원을 구하는 데 어려움을 겪고 계셨다. 나에게 주변에 할 만한 사람이 없냐고 물어보셨고, 백엔드를 주로 하지만 프론트에도 관심이 많던 친구를 추천했다. 그렇게 나와 친구가 함께 새로운 사이드 프로젝트에 합류하게 됐다.

팀원 전원이 대학생이었는데, 학교도 다르고 역할도 다르고 기술 스택도 다르고, 심지어 얼굴 한 번 본 적 없는 사람들과 프로젝트를 하게 됐다. 지금까지와는 확실히 다른 종류의 경험이었다.

맡은 역할

내가 맡은 건 피드 페이지 조회, 피드 상세 페이지 조회, 댓글, 좋아요였다.

작은 역할이라는 걸 알고 들어간 건 맞지만, 막상 시작하니 '이 정도면 백엔드 개발자가 따로 필요 없을 정도로 누구나 금방 할 수 있는 거 아닌가' 하는 생각이 들었다.

그 고민을 그대로 이야기했더니, MSA 방식이니 하고 싶은 대로 확장해도 된다는 답이 돌아왔다. 피드 조회에 개인화 알고리즘을 써보는 건 어떠냐는 조언도 주셨다. 그래서 그걸 중심으로 개발을 이어갔다.

이 과정에서 블루그린 배포도 처음 접하게 됐다. 그동안은 자동 배포까지만 해봤지, 무중단 배포는 제대로 다뤄본 적이 없었다. 이때 처음으로 블루그린 방식의 개념과 실제 배포를 경험해볼 수 있었다.

3개월, 그리고 한 달의 공백

프로젝트는 약 3개월 정도 진행됐다. 겨울방학에 시작해서 학기가 시작된 뒤에도 계속 이어갔다. 나는 맡은 역할의 개발을 기한 내에 마쳤다.

문제는 중간고사 즈음이었다. 다들 대학생이다 보니 "어차피 사이드 프로젝트니 조금 널널하게 하자"는 이야기가 나왔다. 그런데 팀원마다 학교가 다르다 보니 중간고사 기간도 제각각이었고, 결과적으로 한 달 가까이 공백기가 생겼다. 솔직히 그 기간엔 나도 이 프로젝트에 별로 신경 쓰지 못했다.

예상치 못한 종료

시간이 지나 다시 회의를 하게 됐는데, PM님이 예상 밖의 이야기를 꺼내셨다. 한 달간 알아보니 우리 서비스와 거의 완전히 겹치는 서비스가 이미 있다는 걸 알게 됐다고 했다. 그래서 현재 완료된 MVP까지만 하고 여기서 멈추는 게 어떻겠냐고 제안하셨다. 아쉬웠지만, 그렇게 이 프로젝트는 마무리됐다.

그래도 남은 것들

프로젝트는 끝났지만, 얻은 게 없었던 건 아니다. 처음 해보는 방식이었던 만큼 몰랐던 개념을 많이 얻었다. 특히 개인화 알고리즘과 블루그린 배포는 이 프로젝트에서 얻은 가장 큰 수확이라고 생각한다.

MSA 방식도, 비록 내가 직접 로드밸런싱까지 맡지는 않았지만 어깨너머로 전체 구조가 어떻게 돌아가는지 볼 수 있었다. 겉핥기 수준이었지만 그것만으로도 꽤 도움이 됐다.

재밌게도 이번 방학 계절학기로 들었던 '클라우드 네이티브' 수업이 MSA 방식을 다루는 수업이었다. 계절학기라 처음 배우는 개념이었다면 꽤 힘들었을 텐데, KBO:NOTE에서 미리 겪어본 덕분에 훨씬 수월하게 따라갈 수 있었다. 오히려 MSA를 더 깊이 있게, 심화된 개념까지 배울 수 있어서 좋았다.

이 프로젝트는 MSA 구조라 서비스별로 레포가 나뉘어 있는데, 내가 맡았던 피드 조회·상세 페이지·댓글·좋아요 부분은 [여기]에서 볼 수 있다.

프로젝트를 한 지도 벌써 몇 개월이 지나서 기억이 온전치 않을 수도 있지만, 최대한 그때의 흐름을 되짚어 적어봤다. 얼굴도 모르는 사람들과, 서로 다른 기술 스택으로, 우연히 시작해서 예상치 못하게 끝난 프로젝트. 짧았지만 나름 밀도 있는 경험이었다.

프로젝트 회고록 (번외) - 자투리, 그 후

SoloQuest — Mon, 13 Jul 2026 00:28:00 +0900

1편에서 이어지는 이야기다. 이번 편은 화려한 결과물 이야기는 아니다. 오히려 그 반대에 가깝다. 왜 우리가 시작한 고도화가 흐지부지 끝났는지에 대한 기록이다.

다시 모인 이유

3-2학기에 자투리 프로젝트를 마쳤지만, 짧은 시간에 밀어붙이다 보니 아쉬움이 많이 남았다. 특히 디자인 쪽이 걸렸다. 그래서 방학에 다시 모여 고도화를 진행하기로 했다.

이번엔 디자이너 한 명을 새로 영입했다. 팀은 나와 편입 동기, 기존 AI 팀원, 그리고 새로 합류한 디자이너까지 총 4명이었다. 가장 큰 목표는 명확했다. 디자인이었다. 디자이너가 들어온 만큼 UI를 중심으로 확 바꾸고 싶었고, 동시에 "AI가 할루시네이션을 일으킬 수 있다"는 피드백을 받았던 터라 이를 줄이는 것도 목표로 잡았다.

결과부터 말하면, 절반은 성공이고 절반은 실패였다.

디자인 — 목표한 만큼은 해냈다

먼저 잘된 것부터 말하자면, 디자인은 확실히 달라졌다. 이전엔 베이지·브라운 톤의 다소 밋밋한 화면이었는데, 리팩토링 후에는 화이트 배경에 오렌지 포인트 컬러를 준 톤으로 바뀌면서 훨씬 산뜻해졌다. 헤더에 로고와 검색 아이콘을 통일해서 배치하니 화면마다 따로 놀던 느낌이 사라지고 하나의 앱이라는 정체성도 생겼다. 친구 목록·요청을 탭으로 묶고, 마이페이지 카드 정렬을 정돈한 것도 눈에 띄는 변화였다. "제목 추천" 같은 작은 기능이 새로 붙은 것도 이때다.

가장 큰 목표로 잡았던 디자인만큼은 디자이너 영입이라는 결정이 제대로 통했다고 생각한다. 목적의식이 흐릿했던 프로젝트치고는 이 부분만큼은 의외로 결과가 좋았다.

사용자 서비스 리펙토링 전/후

대표적으로 메인, 캘린더, 일기리스트, 친구리스트 4쌍을 가져왔다. 확실히 좀 더 깔끔해진것을 확인 할 수 있다. 바뀐 다른 부분들도 확인하고 싶다면, 1편과 부록을 확인해보시길 바란다. 1편에는 완성된 디자인과 이 글 마지막에 부록에는 리펙토링 후 완성된 디자인을 각각 첨부해 놨다.

메인화면 전/후

캘린더 전/후

일기리스트 전/후

친구 리스트 전/후

AI — 여기서는 확인조차 못 했다

문제는 AI 쪽이었다. 여기서는 패착이 두 가지 있었다.

첫 번째는 목적의식 자체가 약했다는 것. 수업은 이미 끝난 상태였다. "좀 더 고도화해보자"는 마음으로 다시 모이긴 했지만, 실제로 서비스화할 생각까지는 없었다. 목표가 흐릿하니 새로운 시도는 부담스럽게 느껴졌고, 다들 방학이라 바쁘다 보니 이 프로젝트는 자연스럽게 후순위로 밀렸다. 디자인은 그럼에도 눈에 보이는 결과물이 나왔지만, AI 쪽은 우선순위에서 더 쉽게 밀려난 셈이다.

두 번째는 AI를 올릴 GPU가 없었다는 것. 수업을 들을 때는 학교 서버를 지원받아 AI를 돌릴 수 있었다. 당연하게 여기고 있었던 부분이라 이 문제를 미리 생각하지 못했다. AI 쪽 고도화를 팀원이 다 마쳤다고는 했지만, 정작 우리가 그걸 직접 돌려서 확인할 방법이 없었다. 이때는 나도 인프라 쪽을 잘 몰랐던 시기라 클라우드를 활용하는 선택지 자체를 떠올리지 못했다.

결국 할루시네이션을 줄이겠다던 목표는 검증조차 못 한 채로 남았다.

마무리

돌아보면 이 고도화는 완전한 성공도, 완전한 실패도 아니었다. 가장 중요하게 잡았던 디자인 목표는 생각보다 잘 해냈지만, AI 쪽은 시작만 하고 끝을 보지 못했다.

이 경험에서 배운 건 두 가지다. 목적이 분명한 영역(디자인)은 사람(디자이너)을 붙이니 확실히 결과가 났다는 것, 그리고 인프라처럼 당연하게 여겼던 조건이 사라지면 아무리 코드를 다 짜놔도 검증 자체가 막힐 수 있다는 것. 다음 프로젝트에서는 이 두 가지를 미리 챙겨야겠다고 생각한다.

부록(바뀐 디자인)

012345678910111213

프로젝트 회고록 (1) - 자투리

SoloQuest — Mon, 13 Jul 2026 00:06:05 +0900

오늘부터 그동안 진행했던 프로젝트들에 대한 회고록을 하나씩 써보려고 한다. 진작 했어야 했는데, 계속 미루다 보니 지금까지 와버렸다. 많지 않은 프로젝트지만 천천히 하나씩 정리하면서 그때의 감정도 다시 꺼내보려 한다.

이번 글은 회고록 시리즈의 첫 번째, 편입 후 처음 하게 된 프로젝트 이야기다.

배경

작년에 편입을 했는데, 1학기는 학교에 적응하느라 정신이 없었다. 그렇게 1학기를 보내고 2학기가 되자 필수 수업으로 'P-실무 프로젝트'라는 수업을 듣게 됐다. 나는 백엔드를 지망하고 있었기 때문에, 팀도 백엔드 위주로 구성하고 싶었다.

팀 구성

총 5명이 함께하게 됐다. AI 1명, 프론트 2명, 백엔드 2명. 같은 편입 동기 한 명을 설득해서 함께 백엔드를 맡기로 했고, 나머지 3명은 학교 커뮤니티 에브리타임에서 구했다.

이 수업은 원래 3-2학기 12주간 정규 수업을 듣고, 13주차부터 한 달 동안 프로젝트에만 몰입해서 완성하는 방식이었다. 하지만 나와 동기는 편입생이라 챙겨야 할 15주 수업도 꽤 있었다. 한 달이라는 짧은 시간에 다 해내기엔 무리라고 판단해서, 팀원들과 합의 후 여름방학부터 조금씩 미리 진행하기로 했다.

진행 방식

방학 때 모여 가장 먼저 주제를 정했고, 이 자리에서 자연스럽게 내가 팀장을 맡았다. 학점 욕심도 있었던 터라, 내가 끌고 가서 좋은 결과를 만들고 싶은 마음에 자진했다.

막상 시작하니 쉽지 않았다. 몇 년 전 실무 경험이 있긴 했지만 AI가 등장하기 전 이야기였고, 그마저도 편입 공부하느라 다 잊은 상태였다. 팀원 대부분도 프로젝트 자체가 처음이라고 했다. 쉽지 않았지만 어떻게든 끌고 가보고 싶었다.

우리 방식은 단순했다. 2주에 한 번 정해진 날짜에 비대면 회의를 하고, 각자 역할을 기준으로 해올 것을 정한 뒤, 회의 날 완료한 것을 공유하고 다음 할 일을 다시 부여하는 방식이었다.

흔들리기 시작한 일정

문제는 수업이 시작되기 전이라 강제성이 없었다는 점이었다. 계획했던 일정이 조금씩 밀리기 시작했고, 중간에 축제까지 겹치면서 거의 한 달간 회의를 못 한 적도 있었다. 팀원들도 깃허브가 익숙하지 않아 코드 공유가 원활하지 않았다. 팀장으로서 '이대로 괜찮은 걸까' 하는 불안감이 커졌다.

그래도 다른 팀들은 아직 주제 선정도 안 됐다는 이야기를 듣고, 우리가 앞서 있다는 생각에 조금 안도하며 하던 대로 이어갔다.

13주차, 본격 시작

13주차가 되면서 수업이 시작됐다. 매주 한 번 교수님께 진행 상황을 보고하고 피드백을 받는 방식이었고, 마지막 주에는 전체 발표가 예정돼 있었다.

수업이 시작된 만큼 회의 방식도 바꿨다. 2주에 한 번 비대면 회의를, 매주 한 번 대면 회의로 전환했다. 마지막 일주일은 테스트 기간으로 잡았지만, 이마저 계속 밀려서 발표를 3일 앞두고서야 개발이 끝났다. 그런데 완성된 결과물이 내가 생각했던 기능과는 다르게 만들어져 있었다. 결국 마지막 3일은 밤새며 프론트 작업을 함께 도왔고, 마지막 발표도 내가 맡으며 수업을 마무리했다.

결과

결과적으로는 나쁘지 않았다. 팀원 모두 A+를 받았고, 장려상도 받았다.(원래는 우수상까지만 시상 예정이였으나, 교수님이 장려상까지 주셨다.)

일찍 시작한 덕에 다른 학우들이 한 달 내내 거의 매일 밤새며 회의했다는 이야기를 들었을 때, 우리는 끝까지 주 1회 회의만으로 프로젝트를 마무리할 수 있었다.

아쉬웠던 점

분명 아쉬운 점도 있었다. 팀장으로서 진행 상황과 요구사항을 더 자주 확인하지 못한 책임이 컸다고 생각한다. 우리 팀은 소통이 너무 부족했다. 서로 맞춰가며 소통했어야 했는데, 각자에게 역할만 부여하고 2주에 한 번 확인만 하다 보니 진행 상황도, 요구사항도 제대로 파악하기 어려웠다.

또 하나는, 팀원마다 목표하는 바가 달랐다는 걸 팀 구성 단계에서 제대로 확인하지 못했다는 점이다. 프로젝트 자체가 중요한 팀원이 있는가 하면, 프로젝트보다 다른 과목 학점이 더 중요한 팀원도 있었다. 서로 이해관계가 다르다 보니 유독 고생하는 팀원이 생길 수밖에 없었다.

분명 일찍 시작했지만, 그 이점을 제대로 살리지 못한 것 같아 아쉬움이 남는다. 그래도 오랜만에 하는 프로젝트였고, 처음으로 팀장을 맡아보며 많이 배운 경험이었다. 특히 팀원과 소통하는 방법에서 내가 많이 부족하다는 걸 깨달았고, 앞으로 노력으로 채워가야 할 부분이라고 생각했다.

자투리

이것이 우리가 만든 프로젝트, 자투리다.

사용자 서비스

0123456789

관리자 서비스

0123

깃허브 주소: https://github.com/jatuli-25-2

완벽한 프로젝트는 아니었지만, 처음으로 팀을 이끌며 개발보다 사람과 일정, 소통을 관리하는 일이 더 어렵다는 것을 배웠다. 이후 프로젝트를 진행할 때마다 이 경험을 기준으로 내 방식을 돌아보게 됐다. 오랜만에 하는 프로젝트라 힘들었지만, 그만큼 의미있던 첫 프로젝트였던거같다. 하지만 자투리 이야기는 여기서 완전히 끝나지 않았다. 완성된 결과에 남은 아쉬움 때문에, 방학이 되자 일부 팀원들과 다시 모여 프로젝트를 손보기 시작했다. 이 이야기는 2편에서 이어진다.

[QRoad] 서버는 빠른데 로컬만 느린 API, N+1 병목 줄이기

SoloQuest — Sat, 4 Apr 2026 04:26:55 +0900

최근 /api/admin/publications/{paperId} 상세 조회 API를 확인하던 중, 서버에서는 크게 느리지 않은데 로컬에서 유독 지연이 큰 현상을 발견했다.
처음에는 단순 환경 차이일 수 있다고 생각했지만, 데이터를 바꿔가며 호출해 보니 패턴이 분명했다.

기사 38개인 케이스: 약 18초
기사 51개인 케이스: 약 28초

측정값 자체는 환경에 따라 달라질 수 있다.
다만 기사 수가 늘어날수록 지연이 크게 증가한다는 점이 명확해서, 이 구간을 병목으로 보고 로직을 점검했다.

원인: N+1 쿼리 패턴

상세 조회 로직에서 기사 목록을 가져온 뒤, 각 기사마다 키워드를 개별 조회하고 있었다.
즉, 기사 N개면 키워드 조회가 N번 추가되는 구조였다.

이런 N+1 패턴은 데이터가 적을 때는 잘 드러나지 않지만, 데이터가 쌓일수록 응답 시간이 빠르게 나빠질 수 있다.

개선: 배치 조회로 전환

개선 방향은 단순했다.

기사별 키워드 개별 조회 제거
기사 ID 목록을 모아 IN (...)으로 키워드를 한 번에 조회
조회 결과를 articleId -> keywords 형태로 그룹핑해 DTO 조합

Before:

기사마다 키워드 조회 반복

After:

키워드 일괄 조회 후 메모리 그룹핑

핵심은 반복 조회를 묶음 조회로 바꿔 DB 왕복 횟수를 줄인 것이다.

적용 코드 (요약)

Repository: 기사 ID 목록으로 키워드 일괄 조회

@Query("""
    SELECT ak.article.id, ak.keyword.name
    FROM ArticleKeywordEntity ak
    WHERE ak.article.id IN :articleIds
""")
List<Object[]> findArticleIdAndKeywordNameByArticleIds(@Param("articleIds") List<Long> articleIds);

Service: 조회 결과를 articleId 기준으로 그룹핑

private Map<Long, List<String>> getKeywordsForArticles(List<ArticleEntity> articles) {
    if (articles == null || articles.isEmpty()) {
        return Collections.emptyMap();
    }

    List<Long> articleIds = articles.stream()
            .map(ArticleEntity::getId)
            .toList();

    List<Object[]> rows = articleKeywordRepository.findArticleIdAndKeywordNameByArticleIds(articleIds);

    Map<Long, List<String>> keywordsByArticleId = new HashMap<>();
    for (Object[] row : rows) {
        Long articleId = ((Number) row[0]).longValue();
        String keywordName = (String) row[1];
        keywordsByArticleId
                .computeIfAbsent(articleId, ignored -> new ArrayList<>())
                .add(keywordName);
    }
    return keywordsByArticleId;
}

정리

이번 개선의 핵심은 “몇 초 줄였다”보다,
데이터 증가에 따라 지연이 커지던 구조를 안정적으로 바꿨다는 점에 있다.

성능 이슈는 큰 장애가 나서 확인하기보다,
작은 이상 패턴을 보였을 때 바로 구조를 점검하는 게 훨씬 효과적이라는 걸 다시 느꼈다.

서버 git pull 배포에서 GHCR 기반 Docker 배포로 전환한 기록

SoloQuest — Mon, 30 Mar 2026 03:22:20 +0900

배포 방식을 기존의 서버에서 git pull + 빌드 방식에서,
CI에서 이미지 빌드 + GHCR 푸시 + 서버는 pull만 하는 구조로 바꿨다.

작지만 확실한 개선이었고, 실제로 겪은 오류와 해결 과정을 정리해본다.

왜 바꿨나?

기존 방식은 서버가 직접 빌드했다.

서버 상태(자바/그레이들/캐시)에 따라 결과가 달라질 수 있음
/home/ubuntu/BE 같은 경로 의존성이 큼
배포 실패 시 원인 추적이 어려움
롤백이 명확하지 않음

그래서 목표를 이렇게 잡았다.

빌드는 CI에서만
서버는 이미지 pull/run만
커밋 태그 기반 배포
실패 시 자동 롤백

기존 방식 (Before)

GitHub Actions가 SSH로 서버 접속
서버에서 git pull
./gradlew clean build -x test
기존 프로세스 kill 후 java -jar 실행

즉, 서버가 코드/빌드/실행을 모두 담당했다.

변경한 방식 (After)

핵심 구조

build_and_push Job
- Docker 이미지 빌드
- GHCR에 두 태그 푸시
  - ghcr.io/<org>/<repo>:<sha12>
  - ghcr.io/<org>/<repo>:latest
deploy Job
- SSH 허용 IP를 보안그룹에 임시 추가
- 서버에 docker-compose.prod.yml, deploy.sh 전송(scp)
- 서버에서 배포 스크립트 실행
  - commit 태그 pull 우선
  - 실패 시 latest fallback
  - docker compose up -d
  - health check 실패 시 이전 이미지 롤백
- 마지막에 보안그룹 IP 제거

서버 레포 의존성 제거

처음에는 서버에 /home/ubuntu/BE가 있어야 했는데,
배포 중 아래 오류를 만났다.

cd: /home/ubuntu/BE: No such file or directory

해결은 간단했다.

서버 고정 배포 디렉토리를 /opt/qroad로 변경
매번 필요한 파일(deploy.sh, docker-compose.prod.yml)을 CI가 scp로 전달
서버에 git clone/pull 필요 없도록 전환

로그 경로도 정리

처음엔 /log/qroad-be를 썼다가 운영 편의상 ~/log/qroad-be로 변경했다.

컨테이너 내부: /log
호스트: /home/ubuntu/log/qroad-be
파일명: YYYY-MM-DD.log

실제로 겪은 오류와 해결

1) ECR 로그인 권한 오류

기존 ECR 시도 때 ecr:GetAuthorizationToken 권한 에러 발생.

→ GHCR(private)로 전환해서 해결.

2) deploy job에서 scp 실패

오류:

scp: stat local "docker-compose.prod.yml": No such file or directory

원인:

deploy job에 checkout이 없어서 워크스페이스에 파일이 없었음

해결:

deploy job에도 actions/checkout@v4 추가

3) Logback %clr 에러로 앱 부팅 실패

오류:

There is no conversion class registered for composite conversion word [clr]

원인:

logback-spring.xml에 %clr 사용하면서 conversionRule 미등록

해결:

감정 공감 기능도 같이 개선

새로고침하면 상태가 풀리는 이슈가 있어 점검했다.

기존:

감정 식별자 기반이 IP

개선:

qroad_uid 쿠키(UUID) 기반으로 통일
기사 상세 응답에 myEmotion 추가해서 프론트가 새로고침 후 상태 복원 가능하게 변경

DB 스키마 변경은 필요 없었다.

보안 체크

배포/로깅 수정 후 gitleaks로 히스토리 스캔도 수행했다.

결과: no leaks found

전환 후 체감 효과

서버 환경 의존도 감소
배포 재현성 향상
롤백 전략 명확
경로/권한 이슈 디버깅 쉬워짐
운영 로그 관리 편해짐

이 방식이 특히 좋았던 이유

핵심은 한 줄이다.

마무리

이번 전환에서 얻은 결론:

CI에서 빌드하고
레지스트리에 버전 고정하고
서버는 pull/run만 하자

비슷한 구조를 쓰는 팀이라면, 작은 프로젝트라도 이 패턴으로 빨리 옮기는 걸 추천한다.

[KBO:NOTE] Docker Blue-Green 배포 구현 중 발생한 트러블슈팅 정리

SoloQuest — Sun, 15 Mar 2026 01:56:53 +0900

최근 KBO:NOTE 프로젝트에서 Docker + Nginx + GitHub Actions 기반 Blue-Green 무중단 배포 환경을 구축하면서 몇 가지 예상하지 못한 문제를 겪었다.

이번 글에서는 배포 과정에서 실제로 발생했던 문제와 해결 과정을 정리해보려고 한다.

1. Health Check 실패로 배포 중단

문제 상황

배포 로그에서 Health Check 단계에서 반복적으로 실패했다.

예시 로그

===== Health Check =====
Health check retry...
Health check retry...
Process exited with status 1

하지만 서버에서 직접 확인해보면 서비스는 정상적으로 실행되고 있었다.

curl localhost:8081/api/v1/feeds/health

응답

{"service":"kbo-feed-service","status":"UP"}

즉 서비스는 정상인데 배포 스크립트는 실패로 판단하는 상황이었다.

원인

Health Check 검증을 다음 코드로 구현해 두었다.

STATUS=$(curl -s http://localhost:$TARGET_PORT/api/v1/feeds/health | grep '"status":"UP"')

이 방식은 문자열 매칭에 의존하기 때문에 환경에 따라 매칭이 실패할 수 있다.

특히 CI 환경에서는

JSON formatting 차이
공백 문제
grep 매칭 실패

등으로 인해 STATUS 변수가 비어있는 경우가 발생했다.

그 결과 스크립트는 다음 로직에 의해 배포 실패로 판단했다.

if [ -z "$STATUS" ]; then
    exit 1
fi

해결 방법

Health endpoint 자체가 정상인지 직접 확인하여 문제 원인을 파악했고,
Health Check 로직을 retry 기반으로 유지하여 애플리케이션 기동 시간을 고려하도록 구성했다.

2. Blue / Green 컨테이너가 동시에 실행되는 문제

문제 상황

배포 후 서버 상태를 확인했을 때 다음과 같이 두 개의 컨테이너가 동시에 실행되고 있었다.

docker ps

feed-blue
feed-green

Blue-Green 배포에서는 항상 하나의 컨테이너만 실행되는 것이 정상이다.

원인

배포 스크립트의 흐름은 다음과 같다.

새 컨테이너 실행
→ Health Check
→ Nginx 트래픽 전환
→ 이전 컨테이너 제거

하지만 Health Check 단계에서 배포가 실패하면 스크립트가 중간에서 종료된다.

exit 1

이 경우 마지막 단계인 이전 컨테이너 제거 코드가 실행되지 않는다.

docker stop $CURRENT
docker rm $CURRENT

그래서 서버에는

feed-blue
feed-green

두 컨테이너가 동시에 남게 되었다.

해결 방법

Health Check 문제를 해결한 뒤 배포가 정상적으로 끝나면서 이전 컨테이너 제거 로직이 정상적으로 실행되었다.

이후에는 항상 하나의 컨테이너만 실행되는 상태가 유지되었다.

3. Nginx 설정 파일 포트가 깨지는 문제

문제 상황

배포 과정에서 Nginx 설정 테스트 단계에서 다음과 같은 에러가 발생했다.

invalid port in "9808180818081" of the "listen" directive

또는

nginx: configuration file test failed

Nginx 설정 파일을 확인해보니 listen 포트가 다음과 같이 비정상적인 값으로 변경되어 있었다.

listen 9808180818081;

정상적인 설정은 다음과 같아야 한다.

listen 9000;

원인

배포 스크립트에서 Nginx 설정을 변경하기 위해 다음과 같은 sed 명령어를 사용하고 있었다.

sed -i "s/$CURRENT_PORT/$TARGET_PORT/g" $NGINX_CONFIG

이 명령어는 설정 파일 전체에서 해당 숫자를 모두 치환한다.

예를 들어 설정 파일이 다음과 같을 경우

listen 9000;
proxy_pass http://127.0.0.1:8081;

여러 번 배포가 반복되면서 sed 명령이 계속 실행되고 숫자가 누적되면서 다음과 같은 값이 만들어질 수 있다.

listen 9808180818081;

즉 포트 치환 범위가 너무 넓어서 Nginx 설정이 깨지는 문제가 발생했다.

임시 복구

우선 Nginx 설정 파일을 직접 수정하여 정상 값으로 복구했다.

listen 9000;
proxy_pass http://127.0.0.1:8081;

이후 설정이 정상인지 확인했다.

sudo nginx -t

정상 결과

syntax is ok
test is successful

근본 해결

문제의 원인이었던 sed 명령어를 수정했다.

기존 방식

sed -i "s/$CURRENT_PORT/$TARGET_PORT/g" $NGINX_CONFIG

이 방식은 설정 파일 전체를 치환하기 때문에 위험하다.

대신 proxy_pass 라인만 변경하도록 범위를 제한했다.

sed -i "s|proxy_pass http://127.0.0.1:$CURRENT_PORT|proxy_pass http://127.0.0.1:$TARGET_PORT|" $NGINX_CONFIG

이렇게 수정하면 listen 포트에는 영향을 주지 않고 트래픽을 전달하는 포트만 변경할 수 있다.

4. Health Check 타이밍 문제

문제 상황

새 컨테이너 실행 직후 Health Check가 실패하는 경우가 있었다.

Health check retry...
Health check retry...
서비스 정상

원인

Spring Boot 애플리케이션이 완전히 기동되기 전에
Health Check 요청이 먼저 실행되었기 때문이다.

즉 애플리케이션 startup time 문제였다.

해결 방법

Health Check 로직에 retry 구조를 적용했다.

for i in {1..10}
do
 sleep 3

최대 30초 동안 애플리케이션 기동을 기다리도록 구성했다.

마무리

Blue-Green 배포 자체는 구조가 단순해 보이지만 실제로 구현해보면 다양한 문제를 마주하게 된다.

특히 다음 세 가지가 중요하다는 것을 느꼈다.

Health Check 로직 안정성
배포 실패 시 상태 관리
Nginx 설정 변경 방식

이번 경험을 통해 무중단 배포 환경을 실제로 운영하면서 발생할 수 있는 문제들을 직접 해결해볼 수 있었다.

Docker + Nginx 기반 Blue-Green 배포 구축 (3) — GitHub Actions CI/CD와 자동 배포 스크립트 구축

SoloQuest — Sun, 15 Mar 2026 01:42:07 +0900

들어가며

이전 글에서는 Docker 이미지를 GitHub Container Registry(GHCR)에 업로드하고
Blue-Green 컨테이너 환경을 구성하여 수동 배포 방식으로 Blue-Green 전환을 검증했다.

이 과정에서 다음과 같은 작업을 완료했다.

Dockerfile 작성 및 이미지 빌드
GitHub Container Registry(GHCR) 사용
서버에서 이미지 Pull 테스트
Blue / Green 컨테이너 환경 구성
NGINX Reverse Proxy 트래픽 전환 테스트

즉 Blue-Green 배포가 실제로 동작하는 환경은 이미 구축된 상태였다.

하지만 실제 운영 환경에서는 다음과 같은 문제가 남아 있다.

코드 변경
↓
Docker 이미지 빌드
↓
이미지 Push
↓
서버 접속
↓
컨테이너 실행
↓
NGINX 전환

이 과정을 모두 수동으로 실행해야 한다는 점이다.

따라서 이번 글에서는 이 과정을 자동화하여 다음과 같은 완전한 자동 배포 파이프라인을 구축한다.

GitHub Push
↓
GitHub Actions
↓
Docker Image Build
↓
GHCR Push
↓
Server Deploy Script
↓
Blue-Green 배포
↓
NGINX 자동 전환

자동 배포 구조 설계

자동 배포의 핵심 구성 요소는 다음과 같다.

1️⃣ GitHub Actions CI/CD
2️⃣ Docker Image Version 관리
3️⃣ 서버 배포 스크립트 (deploy.sh)
4️⃣ Health Check 자동화
5️⃣ NGINX 트래픽 전환 자동화

전체 구조는 다음과 같다.

Developer
 │
 │ git push
 ▼
GitHub Repository
 │
 ▼
GitHub Actions
 │
 │ Docker Build
 │
 ▼
GitHub Container Registry (GHCR)
 │
 │ docker pull
 ▼
Server
 │
 │ deploy.sh
 ▼
Blue / Green Container
 │
 ▼
NGINX
 │
 ▼
Client

즉 코드가 Push되면 자동으로 서버까지 배포되는 구조를 만드는 것이 목표다.

Docker 이미지 버전 전략

초기에는 Docker 이미지를 다음과 같이 latest 태그로만 관리했다.

ghcr.io/kbo-note/kbo-note-feed-service:latest

하지만 이 방식에는 문제가 있다.

새로운 배포가 latest를 덮어씀
↓
기존 컨테이너 재시작 시 다른 코드 실행 가능
↓
버전 추적 어려움

이를 해결하기 위해 Commit 기반 이미지 태그 전략을 적용했다.

GitHub Actions에서 Docker 이미지를 빌드할 때 다음과 같이 두 개의 태그를 동시에 생성한다.

docker build \
 -t ghcr.io/kbo-note/kbo-note-feed-service:${{ github.sha }} \
 -t ghcr.io/kbo-note/kbo-note-feed-service:latest .

이렇게 하면 Registry에는 다음과 같은 형태로 이미지가 저장된다.

kbo-note-feed-service
 ├ latest
 ├ 3f91c2a
 ├ 8ad21f3
 └ b71d9c1

이 전략의 장점은 다음과 같다.

배포 버전 추적 가능
특정 버전 롤백 가능
이미지 변경으로 인한 코드 꼬임 방지

GitHub Actions CI/CD 구축

이제 GitHub Actions Workflow를 작성한다.

Workflow 파일 위치

.github/workflows/deploy.yml

핵심 Workflow는 다음과 같다.

name: Feed Service CI/CD

on:
 push:
 branches:
 - main

permissions:
contents: read
packages: write

jobs:
 deploy:

 runs-on: ubuntu-latest

 steps:

 - name: Checkout
 uses: actions/checkout@v4

 - name: Login to GHCR
 run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin

 - name: Build Docker Image
 run: |
 docker build \
 -t ghcr.io/kbo-note/kbo-note-feed-service:${{ github.sha }} \
 -t ghcr.io/kbo-note/kbo-note-feed-service:latest .

 - name: Push Docker Image
 run: |
 docker push ghcr.io/kbo-note/kbo-note-feed-service:${{ github.sha }}
 docker push ghcr.io/kbo-note/kbo-note-feed-service:latest

 - name: Deploy to Server
 uses: appleboy/ssh-action@v1
 with:
 host: ${{ secrets.SERVER_HOST }}
 username: ${{ secrets.SERVER_USERNAME }}
 password: ${{ secrets.SERVER_PASSWORD }}
 port: 22
 script: |
 cd ~/kbo-feed-service/deploy
 ./deploy.sh ${{ github.sha }}

이 Workflow는 다음과 같은 작업을 수행한다.

코드 Checkout
↓
Docker 이미지 빌드
↓
GHCR Push
↓
SSH 서버 접속
↓
deploy.sh 실행

Blue-Green 자동 배포 스크립트 작성

다음으로 서버에서 실행되는 자동 배포 스크립트를 작성한다.

파일 위치

~/kbo-feed-service/deploy/deploy.sh

스크립트의 주요 역할은 다음과 같다.

현재 실행 중인 컨테이너 확인
↓
반대 환경 컨테이너 실행
↓
Health Check 수행
↓
NGINX 트래픽 전환
↓
기존 컨테이너 종료

예를 들어 현재 상태가 다음과 같다면

feed-blue → 8081

배포 시 다음과 같이 진행된다.

새 버전 → feed-green (8082)
↓
Health Check
↓
NGINX 전환
↓
feed-blue 종료

Health Check 자동화

새 컨테이너가 정상적으로 실행되었는지 확인하기 위해
Health Check 로직을 추가했다.

Feed Server에는 다음과 같은 health endpoint가 존재한다.

/api/v1/feeds/health

응답 예시

{
 "service": "kbo-feed-service",
 "status": "UP"
}

deploy.sh에서는 이 값을 확인하여 서비스 상태를 검증한다.

curl http://localhost:$PORT/api/v1/feeds/health

만약 Health Check가 실패하면

NGINX 전환 중단
새 컨테이너 제거
배포 실패 처리

하도록 구성했다.

배포 로그 기록

추가로 배포 히스토리를 확인할 수 있도록 배포 로그 기록 기능도 추가했다.

echo "$(date '+%Y-%m-%d %H:%M:%S') deploy $IMAGE_TAG" >> deploy.log

이렇게 하면 서버에서 다음과 같이 배포 기록을 확인할 수 있다.

2026-03-15 01:12 deploy 3f91c2a
2026-03-15 01:40 deploy 8ad21f3

자동 배포 동작 과정

이제 실제 배포 흐름은 다음과 같다.

git push
↓
GitHub Actions 실행
↓
Docker Image Build
↓
GHCR Push
↓
SSH 서버 접속
↓
deploy.sh 실행
↓
Blue-Green 배포
↓
NGINX 트래픽 전환

즉 개발자는 단순히 다음 명령만 실행하면 된다.

git push

그러면 자동으로 서버까지 배포된다.

실제 배포 검증

자동 배포가 정상적으로 동작하는지 확인하기 위해
테스트 커밋을 Push하여 배포를 실행했다.

GitHub Actions 로그에서는 다음과 같은 단계가 확인된다.

Checkout
Login to GHCR
Build Docker Image
Push Docker Image
Deploy to Server

서버에서도 컨테이너가 정상적으로 전환되는 것을 확인했다.

docker ps

컨테이너는 다음과 같이 번갈아 실행된다.

feed-blue
feed-green

이로써 GitHub Push → 자동 Blue-Green 배포가 정상적으로 동작하는 것을 확인했다.

현재까지 진행 상황

지금까지 진행한 작업을 정리하면 다음과 같다.

✔ Docker 기반 서비스 환경 구축
✔ GitHub Container Registry 사용
✔ Blue-Green 배포 환경 구성
✔ NGINX Reverse Proxy 설정
✔ 수동 Blue-Green 배포 검증
✔ GitHub Actions CI/CD 구축
✔ Blue-Green 자동 배포 스크립트 작성
✔ Health Check 자동화
✔ 자동 배포 검증 완료

마무리

이번 글에서는 GitHub Actions를 이용해 Blue-Green 자동 배포 환경을 구축하는 과정을 정리했다.

특히 다음 세 가지가 핵심이었다.

GitHub Actions 기반 CI/CD 구축
Commit 기반 Docker Image 버전 관리
Blue-Green 자동 배포 스크립트 구현

이 구조를 통해 코드 Push만으로 서버 배포가 자동으로 이루어지는 환경을 구축할 수 있었다.

앞으로 서비스 규모가 커지더라도
이 배포 구조를 기반으로 안정적인 배포를 유지할 수 있을 것으로 기대한다

Docker + Nginx 기반 Blue-Green 배포 구축 (2) — Docker 이미지 배포와 Blue-Green 환경 구축

SoloQuest — Sun, 15 Mar 2026 01:29:48 +0900

들어가며

이전 글에서는 현재 Feed Server의 서버 구조를 분석하고
Blue-Green 배포 전략을 설계하는 과정을 정리했다.

특히 다음과 같은 사항을 확인했다.

Docker 기반 MSA 환경
NGINX Reverse Proxy 구조
Docker host network 사용
Blue-Green 포트 전략 설계 (8081 / 8082)

이번 글에서는 이 구조를 기반으로 실제 Blue-Green 배포 환경을 구축하는 과정을 정리하려고 한다.

이번 단계에서 진행한 작업은 다음과 같다.

Docker 이미지 생성
GitHub Container Registry(GHCR) 사용
서버에서 이미지 Pull 테스트
Blue / Green 컨테이너 환경 구성
NGINX 트래픽 전환 테스트

즉 Blue-Green 배포가 실제로 동작하는 환경을 구축하고 검증하는 과정이다.

Docker 이미지 생성

먼저 Feed Server를 Docker 이미지로 빌드할 수 있도록 Dockerfile을 작성했다.

이번 Dockerfile은 멀티 스테이지 빌드(Multi-stage build) 방식으로 구성했다.

FROM eclipse-temurin:17-jdk AS builder
WORKDIR /workspace

COPY gradlew gradlew
COPY gradle gradle
COPY build.gradle settings.gradle ./
RUN chmod +x gradlew

COPY src src
RUN ./gradlew clean bootJar --no-daemon

FROM eclipse-temurin:17-jre
WORKDIR /app

COPY --from=builder /workspace/build/libs/*.jar app.jar

EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

이 Dockerfile은 크게 두 단계로 구성되어 있다.

1️⃣ Build Stage

첫 번째 단계에서는 Gradle을 사용해 Spring Boot 애플리케이션을 빌드한다.

FROM eclipse-temurin:17-jdk AS builder

JDK 환경에서 Gradle Wrapper를 이용해 애플리케이션을 빌드한다.

RUN ./gradlew clean bootJar --no-daemon

이 과정이 완료되면 다음 위치에 실행 가능한 JAR 파일이 생성된다.

build/libs/

2️⃣ Runtime Stage

두 번째 단계에서는 실제 실행에 필요한 최소 환경만 포함한 이미지를 만든다.

FROM eclipse-temurin:17-jre

빌드 단계에서 생성된 JAR 파일을 복사한다.

COPY --from=builder /workspace/build/libs/*.jar app.jar

그리고 Spring Boot 애플리케이션을 실행한다.

ENTRYPOINT ["java", "-jar", "app.jar"]

멀티 스테이지 빌드를 사용하면 다음과 같은 장점이 있다.

빌드 도구(Gradle)가 포함되지 않는다
최종 이미지 크기가 작아진다
보안적으로도 더 안전하다

Docker 이미지 빌드

Dockerfile을 작성한 후 이미지를 빌드한다.

docker build -t feed-service:test .

빌드가 완료되면 로컬에서 컨테이너 실행 테스트를 진행한다.

docker run -p 8080:8080 feed-service:test

Spring Boot 애플리케이션이 정상적으로 실행되는 것을 확인했다.

GitHub Container Registry 사용

자동 배포 환경을 구축하기 위해 Docker 이미지를 Container Registry에 업로드해야 한다.

이번 프로젝트에서는 GitHub Container Registry(GHCR) 를 사용했다.

이미지 이름은 다음과 같은 형식으로 구성했다.

ghcr.io/<organization>/<repository>:latest

우리 프로젝트에서는 다음과 같은 이미지 이름을 사용했다.

ghcr.io/kbo-note/kbo-note-feed-service:latest

먼저 로컬 이미지를 GHCR 형식으로 태깅한다.

docker tag feed-service:test ghcr.io/kbo-note/kbo-note-feed-service:latest

다음으로 GitHub Container Registry에 로그인한다.

docker login ghcr.io

로그인에는 GitHub Personal Access Token(PAT)을 사용했다.

이후 이미지를 Registry에 Push한다.

docker push ghcr.io/kbo-note/kbo-note-feed-service:latest

Push가 완료되면 GitHub Organization의 Packages 영역에서 이미지가 생성된 것을 확인할 수 있다.

서버에서 이미지 Pull 테스트

다음 단계는 서버에서 이미지를 직접 가져올 수 있는지 확인하는 것이다.

먼저 서버에서 GHCR 로그인을 수행한다.

docker login ghcr.io

이후 이미지를 Pull 한다.

docker pull ghcr.io/kbo-note/kbo-feed-service:latest

이미지가 정상적으로 다운로드되면 다음 단계로 넘어갈 수 있다.

이 단계는 매우 중요한데
Container Registry → 서버 배포 경로가 정상적으로 동작하는지 확인하는 과정이기 때문이다.

Blue / Green 컨테이너 환경 구성

이제 실제 Blue-Green 환경을 구성한다.

이번 프로젝트에서는 다음과 같은 포트 전략을 사용했다.

환경	포트
Blue	8081
Green	8082

또한 컨테이너 이름도 다음과 같이 분리했다.

feed-blue
feed-green

먼저 Blue 환경을 실행한다.

docker run -d \
--name feed-blue \
--network host \
-e SERVER_PORT=8081 \
ghcr.io/kbo-note/kbo-note-feed-service:latest

컨테이너가 정상적으로 실행되는지 확인한다.

docker ps

서버에서 직접 요청을 보내 확인했다.

curl localhost:8081

Spring Boot 루트 경로가 정의되어 있지 않아 404 응답이 반환되지만
이는 서버가 정상적으로 실행되고 있다는 의미다.

Green 환경 실행

이제 동일한 이미지를 Green 환경으로 실행한다.

docker run -d \
--name feed-green \
--network host \
-e SERVER_PORT=8082 \
ghcr.io/kbo-note/kbo-feed-service:latest

현재 서버 상태는 다음과 같다.

feed-blue → 8081
feed-green → 8082

즉 두 개의 애플리케이션이 동시에 실행되는 상태다.

Green 환경도 동일하게 테스트한다.

curl localhost:8082

NGINX 트래픽 전환 테스트

현재 NGINX 설정은 다음과 같다.

proxy_pass http://127.0.0.1:8081;

즉 현재 트래픽은 Blue 환경으로 전달되고 있다.

Blue-Green 전환 테스트를 위해 NGINX 설정을 수정했다.

기존 설정

proxy_pass http://127.0.0.1:8081;

변경 후

proxy_pass http://127.0.0.1:8082;

설정을 변경한 후 NGINX 설정을 검증했다.

sudo nginx -t

문제가 없다면 설정을 reload 한다.

sudo systemctl reload nginx

이제 트래픽은 Green 환경으로 전달된다.

Client
↓
NGINX :9000
↓
Feed Server (Green :8082)

마지막으로 기존 Blue 컨테이너를 정리한다.

docker stop feed-blue
docker rm feed-blue

이로써 Blue-Green 전환이 완료되었다.

현재까지 진행 상황

지금까지 진행한 작업을 정리하면 다음과 같다.

✔ Dockerfile 작성
✔ Docker 이미지 빌드
✔ GitHub Container Registry 사용
✔ 서버에서 이미지 Pull 확인
✔ Blue / Green 컨테이너 환경 구축
✔ NGINX 트래픽 전환 테스트
✔ 수동 Blue-Green 배포 검증

즉 Blue-Green 배포가 실제로 동작하는 환경을 구축하고 검증한 상태다.

다음 글에서 다룰 내용

이번 글에서는 Blue-Green 배포를 수동으로 실행하고 검증하는 과정을 다뤘다.

하지만 실제 운영 환경에서는 배포 과정을 자동화해야 한다.

다음 글에서는 다음 내용을 정리할 예정이다.

Blue-Green 배포 스크립트 작성 (deploy.sh)
Health Check 자동화
NGINX 트래픽 자동 전환
GitHub Actions 기반 자동 배포 구축

최종 목표는 다음과 같은 자동 배포 파이프라인이다.

GitHub Push
↓
GitHub Actions
↓
Docker Image Build
↓
GHCR Push
↓
Server Deploy Script
↓
Blue-Green 배포
↓
NGINX 자동 전환

Docker + Nginx 기반 Blue-Green 배포 구축 (1) — 서버 구조 정리와 배포 전략 설계

SoloQuest — Sat, 14 Mar 2026 23:59:11 +0900

들어가며

현재 진행 중인 프로젝트는 MSA(Microservice Architecture) 기반으로 구성되어 있고,
각 서비스는 서비스별 GitHub Repository로 분리되어 관리되고 있다.

나는 이 중 Feed Server를 담당하고 있으며, 초기 개발 단계에서 Docker 컨테이너 환경도 직접 구성했다.

이번에 새로 진행하려는 작업은 Feed Server에 Blue-Green 배포 전략을 적용하고 자동 배포 환경을 구축하는 것이다.

최종적으로 목표로 하는 배포 구조는 다음과 같다.

GitHub Push
 ↓
GitHub Actions
 ↓
Docker Image Build
 ↓
Container Registry Push
 ↓
Server Pull
 ↓
Blue-Green 배포
 ↓
NGINX 트래픽 전환

하지만 자동 배포를 구축하기 전에 현재 서버 구조를 먼저 정확히 정리할 필요가 있었다.

이번 글에서는 현재 Feed Server가 어떤 구조로 운영되고 있는지 정리하고,
Blue-Green 배포 전략을 설계한 과정을 기록하려고 한다.

현재 서버 환경

먼저 서버에 접속해서 현재 실행 중인 컨테이너들을 확인했다.

docker ps

현재 서버는 여러 서비스가 동시에 실행되는 Docker 기반 MSA 환경이었다.

여러 서비스 컨테이너가 실행 중이었고,
내가 담당하는 Feed Server도 Docker 컨테이너 형태로 실행되고 있었다.

Feed Server 컨테이너 내부에서는 Spring Boot 애플리케이션이 실행되는 구조다.

즉 전체 구조는 다음과 같다.

Docker Container
 ↓
Spring Boot Application
 ↓
Feed Service

Feed Server는 처음 개발할 때 Docker 이미지로 빌드하고 컨테이너 형태로 실행되도록 구성해 두었다.

Feed Server 네트워크 구조

다음으로 컨테이너 네트워크 설정을 확인했다.

확인해 보니 Feed Server 컨테이너는 Docker host network 모드로 실행되고 있었다.

host network 모드의 특징은 다음과 같다.

컨테이너 포트 = 서버 포트

일반적인 Docker 실행 방식에서는 다음과 같이 포트를 매핑한다.

hostPort:containerPort

하지만 host network 모드에서는 컨테이너가 서버 네트워크를 그대로 사용하기 때문에 포트 매핑이 따로 존재하지 않는다.

이 구조는 설정이 단순하다는 장점이 있지만, 여러 서비스가 동시에 실행되는 환경에서는 포트 충돌에 주의해야 한다.

NGINX 트래픽 흐름 확인

다음으로 외부 요청이 Feed Server로 어떻게 전달되는지 확인했다.

현재 서버에서는 NGINX가 Reverse Proxy 역할을 하고 있다.

구조는 다음과 같다.

Client
 ↓
API Gateway
 ↓
NGINX
 ↓
Feed Server

NGINX 설정을 확인해 보니 다음과 같은 구조였다.

listen 9000
proxy_pass → 127.0.0.1:8081

즉 현재 트래픽 흐름은 다음과 같다.

API Gateway
 ↓
NGINX (9000)
 ↓
Feed Server (8081)

실제로 연결이 정상적으로 동작하는지도 확인했다.

curl localhost:9000
curl localhost:8081

Spring Boot 애플리케이션의 루트 경로가 정의되어 있지 않아 404 응답이 반환되었지만, 이는 정상적인 동작이다.

즉 NGINX → Feed Server 연결 구조는 문제없이 동작하고 있었다.

Blue-Green 배포 전략 설계

현재 구조를 기반으로 Blue-Green 배포 전략을 설계했다.

Blue-Green 배포의 핵심은 두 개의 동일한 환경을 준비한 뒤 트래픽을 전환하는 것이다.

이번 프로젝트에서는 다음과 같은 포트 전략을 사용하기로 했다.

환경	포트
Blue	8081
Green	8082

현재 상태는 다음과 같다.

NGINX → 8081

즉 현재 Feed Server는 Blue 환경으로 실행되고 있는 상태다.

Blue-Green 배포 시에는 다음과 같은 흐름으로 배포가 진행된다.

새로운 버전을 Green 환경(8082)에 실행
Health Check 수행
NGINX 트래픽을 8082로 전환
기존 Blue 환경 종료

이 방식의 가장 큰 장점은 무중단 배포가 가능하다는 것이다.

컨테이너 구조 변경 계획

기존에는 Feed Server 컨테이너가 하나의 이름으로 실행되고 있었다.

하지만 Blue-Green 배포를 위해 다음과 같이 두 개의 컨테이너 구조로 변경할 계획이다.

feed-blue
feed-green

예를 들어 다음과 같은 구조다.

feed-blue → 8081
feed-green → 8082

이렇게 구성하면 두 버전을 동시에 실행할 수 있고
트래픽을 원하는 시점에 전환할 수 있다.

컨테이너 실행 중 발생한 문제

Blue 환경을 테스트하는 과정에서 다음과 같은 문제가 발생했다.

Web server failed to start. Port 8080 was already in use.

Spring Boot 기본 포트는 8080인데
이미 서버에서 해당 포트를 사용하는 서비스가 존재했기 때문이다.

또한 Feed Server 컨테이너는 host network 모드를 사용하고 있기 때문에
컨테이너 내부 포트 역시 서버 포트와 동일하게 사용된다.

즉 포트를 명시적으로 지정하지 않으면 포트 충돌이 발생할 수 있는 구조였다.

해결 방법

이 문제는 Spring Boot 실행 포트를 명시적으로 지정하여 해결했다.

Blue 환경

SERVER_PORT=8081

Green 환경

SERVER_PORT=8082

이렇게 실행하면 두 환경이 서로 다른 포트를 사용하게 되어
충돌 없이 동시에 실행할 수 있다.

현재까지 진행 상황

지금까지 진행한 작업을 정리하면 다음과 같다.

✔ Feed Server Docker 환경 확인
✔ 서버 네트워크 구조 분석
✔ NGINX Reverse Proxy 구조 확인
✔ Blue-Green 포트 전략 설계
✔ 컨테이너 구조 변경 계획
✔ 포트 충돌 문제 해결

다음 글에서 다룰 내용

다음 글에서는 실제 Blue-Green 자동 배포 환경 구축 과정을 정리할 예정이다.

다룰 내용은 다음과 같다.

Docker 이미지 관리
Container Registry 사용
GitHub Actions CI/CD 구축
Blue-Green 자동 배포 스크립트 작성
NGINX 트래픽 자동 전환

마무리

Blue-Green 배포를 구축하기 전에 현재 서버 구조를 정확히 이해하는 과정이 매우 중요했다.

특히 이번 환경에서는

Docker host network
NGINX Reverse Proxy
여러 서비스가 동시에 실행되는 MSA 환경

이 세 가지 요소를 먼저 정리해야 했다.

다음 글에서는 이 구조를 기반으로 실제 자동 배포 파이프라인을 구축하는 과정을 정리할 예정이다.

[QRoad]운영 전 API 부하 테스트를 진행하며 403을 마주하다 (문제 추적 과정 정리)

SoloQuest — Mon, 2 Mar 2026 22:54:14 +0900

1. 배경

지역신문 QR 유입을 대비하여 운영 전 API 안정성을 점검하고자 부하 테스트를 진행했다.

프론트엔드: Vercel
백엔드: EC2 + Nginx
테스트 도구: k6
테스트 대상 API:

https://api.qroad.info/api/qr/3

목표는 다음과 같았다.

동시 사용자 30~50명 시나리오 테스트
p95 500ms 이하 유지
에러율 1% 미만 유지

2. 1차 실수: 잘못된 레이어 테스트

처음에는 다음 주소를 테스트했다.

https://www.qroad.info/a/3

하지만 curl 응답을 확인해보니:

Server: Vercel

즉, 프론트엔드 정적 페이지를 테스트한 것이었다.
DB 조회 API가 아닌 레이어를 테스트하고 있었던 것이다.

→ 테스트 대상을 api.qroad.info로 수정.

3. 실제 API 테스트 결과

k6로 /api/qr/3를 호출하자 결과는 다음과 같았다.

http_req_failed: 100%
status is 200: 실패

모든 요청이 실패로 집계되었다.

하지만 응답 시간은 매우 짧았다.

avg: 3~5ms

이는 성능 문제가 아니라 즉시 거부 응답임을 의미한다.

4. 원인 추적 과정

(1) 보안그룹 확인

443 포트 전체 허용 상태
네트워크 차단 아님

(2) nginx 설정 확인

sudo grep -R "deny" /etc/nginx

결과: 실제 deny 설정 없음

→ nginx 레벨 차단 아님

(3) curl 테스트

curl -i https://api.qroad.info/api/qr/3

결과:

HTTP/1.1 403

Origin, Referer 헤더를 추가해도 동일하게 403.

5. 현재 추정 원인

애플리케이션 레벨(Spring Security 등)에서 접근 차단
세션 또는 쿠키 기반 접근 허용 구조
브라우저 정상 흐름에서만 접근 가능하도록 설계

즉, 서버 성능 문제 이전에
API 접근 정책 설계 문제를 먼저 정리해야 하는 상태였다.

6. 배운 점

1) 부하 테스트는 단순히 트래픽을 때리는 작업이 아니다

레이어를 정확히 이해하지 못하면
엉뚱한 부분을 테스트하게 된다.

2) 403도 의미 있는 결과다

네트워크 차단인지
nginx 레벨인지
애플리케이션 레벨인지

단계적으로 좁혀가는 과정 자체가 트러블슈팅이다.

3) 운영 전 점검의 가치

실제 운영 전에:

API 접근 정책 문제 발견
인증/보안 설계 재검토 필요성 인지

이 자체가 리스크 관리 경험이다.

7. 다음 단계

Spring Security 설정 점검
/api/qr/** 접근 정책 명확화
인증 전략 정리 후 재테스트 진행

마무리

이번 부하 테스트는 성능 검증 이전에
“API 접근 구조를 재점검하는 과정”이 되었다.

단순한 부하 테스트 실행이 아니라,
문제 정의 → 가설 수립 → 원인 축소 → 구조 분석의 흐름을 경험한 사례였다.

운영 전 점검은
장애 발생 이후 대응보다 훨씬 가치 있는 작업임을 체감한 순간이었다.