삼시세끼코딩

랜덤포레스트 쉽게 이해하기: 여러 나무가 함께 내리는 똑똑한 결정

코딩금융치료 — Tue, 28 Apr 2026 10:15:04 +0900

머신러닝을 공부하다 보면 랜덤포레스트(Random Forest)라는 말을 자주 듣게 됩니다.

이름만 보면 조금 어렵게 느껴집니다.

“랜덤은 무작위라는 뜻이고, 포레스트는 숲이라는 뜻인데, 머신러닝에서 숲이 왜 나올까?”

처음에는 이렇게 느낄 수 있습니다.

하지만 랜덤포레스트의 핵심 개념은 생각보다 쉽습니다.

간단히 말하면 랜덤포레스트는 여러 개의 결정트리가 함께 의견을 내고, 그 의견을 모아서 최종 결정을 내리는 머신러닝 방법입니다.

초등학생도 이해할 수 있게 비유하면 이렇습니다.

한 명의 친구에게만 물어보는 것이 아니라, 여러 친구에게 물어본 뒤 다수결로 결정하는 방법입니다.

한 명이 판단하면 틀릴 수 있습니다.
하지만 여러 명이 각자 생각하고, 그 결과를 모으면 더 안정적인 답을 낼 수 있습니다.

랜덤포레스트도 똑같습니다.

하나의 나무가 아니라, 여러 나무가 함께 판단합니다.
그래서 이름도 랜덤포레스트, 즉 무작위 숲입니다.

1. 먼저 결정트리부터 이해해보자

랜덤포레스트를 이해하려면 먼저 결정트리(Decision Tree)를 알아야 합니다.

결정트리는 말 그대로 결정을 내리는 나무입니다.

질문을 하나씩 따라가다 보면 마지막에 답이 나오는 구조입니다.

예를 들어 동물을 맞히는 문제를 생각해보겠습니다.

“털이 있나요?”
“다리가 4개인가요?”
“날개가 있나요?”

이런 질문을 차례대로 하다 보면 강아지, 토끼, 새, 물고기 같은 답을 찾을 수 있습니다.

위 그림처럼 결정트리는 질문을 따라 내려갑니다.

예를 들어 이런 식입니다.

털이 있나요?
 ├─ 예 → 다리가 4개인가요?
 │ ├─ 예 → 강아지
 │ └─ 아니오 → 토끼
 └─ 아니오 → 날개가 있나요?
 ├─ 예 → 새
 └─ 아니오 → 물고기

질문이 나뭇가지처럼 갈라지기 때문에 트리(Tree)라고 부릅니다.

결정트리는 이해하기 쉽다는 장점이 있습니다.
질문을 따라가면 왜 그런 답이 나왔는지 어느 정도 알 수 있기 때문입니다.

하지만 결정트리 하나만 사용하면 문제가 생길 수 있습니다.

하나의 나무가 너무 자기 생각만 강하게 가질 수 있습니다.
또는 학습한 데이터에만 너무 잘 맞고, 새로운 데이터에는 약할 수 있습니다.

그래서 여러 결정트리를 모아서 더 안정적인 결과를 만들자는 생각이 나오게 됩니다.

그것이 바로 랜덤포레스트입니다.

2. 랜덤포레스트는 결정트리 여러 개가 모인 숲이다

랜덤포레스트는 하나의 결정트리가 아닙니다.

여러 개의 결정트리를 만듭니다.

그리고 각각의 결정트리가 따로 판단합니다.

예를 들어 어떤 사진이 고양이인지 강아지인지 맞히는 문제가 있다고 해보겠습니다.

1번 나무: 고양이
2번 나무: 고양이
3번 나무: 강아지
4번 나무: 고양이
5번 나무: 고양이

이 경우 고양이라고 말한 나무가 더 많습니다.

그래서 랜덤포레스트는 최종 답을 고양이로 정합니다.

이처럼 여러 나무의 의견을 모아서 최종 결정을 내리는 것이 랜덤포레스트의 기본 원리입니다.

분류 문제에서는 보통 다수결 투표를 합니다.

예를 들어 고양이냐 강아지냐, 합격이냐 불합격이냐, 스팸 메일이냐 아니냐 같은 문제입니다.

반대로 숫자를 예측하는 문제에서는 보통 평균값을 사용합니다.

예를 들어 집값을 예측한다고 해보겠습니다.

1번 나무 예측: 3억 원
2번 나무 예측: 3억 2천만 원
3번 나무 예측: 2억 8천만 원

이런 식으로 여러 나무가 예측한 값을 평균 내서 최종 예측값을 정합니다.

3. 앙상블이란?

랜덤포레스트를 이해할 때 꼭 알아야 하는 용어가 있습니다.

바로 앙상블(Ensemble)입니다.

앙상블은 원래 음악에서 많이 쓰는 말입니다.

피아노 혼자 연주하는 것도 좋지만, 피아노, 바이올린, 첼로, 플루트가 함께 연주하면 더 풍성한 음악이 됩니다.

머신러닝에서도 비슷합니다.

여러 개의 모델을 함께 사용해서 더 좋은 결과를 만드는 방법을 앙상블이라고 합니다.

랜덤포레스트는 여러 개의 결정트리를 함께 사용합니다.

그래서 랜덤포레스트는 대표적인 앙상블 모델입니다.

한 명의 친구보다 여러 친구의 의견을 듣는 것이 더 안정적일 때가 있습니다.
한 명의 전문가보다 여러 전문가의 의견을 모으면 더 균형 잡힌 판단을 할 수 있습니다.

랜덤포레스트도 마찬가지입니다.

하나의 결정트리가 실수하더라도 다른 결정트리들이 그 실수를 보완할 수 있습니다.

4. 배깅이란?

랜덤포레스트에서 또 중요한 용어가 배깅(Bagging)입니다.

배깅은 쉽게 말하면 다음과 같습니다.

데이터를 여러 번 랜덤하게 뽑아서 여러 모델에게 따로 공부시키는 방법입니다.

조금 더 쉽게 설명해보겠습니다.

반에 학생이 5명 있다고 해보겠습니다.

선생님이 모든 학생에게 완전히 똑같은 문제지를 나눠주면, 학생들의 생각이 비슷해질 수 있습니다.

하지만 조금씩 다른 문제지를 나눠주면 어떻게 될까요?

학생마다 보는 문제가 조금씩 다릅니다.
그래서 각자 다른 방식으로 공부하고, 다른 답을 낼 수 있습니다.

마지막에는 학생들의 답을 모아서 최종 답을 정합니다.

이것이 배깅의 느낌입니다.

위 그림을 보면 전체 데이터가 있고, 각 나무가 조금씩 다른 데이터를 받아서 공부합니다.

그리고 각 나무가 답을 냅니다.

마지막에는 모든 답을 모아서 투표합니다.

이 과정을 통해 하나의 나무만 사용할 때보다 더 안정적인 결과를 만들 수 있습니다.

정리하면 이렇습니다.

앙상블: 여러 모델의 힘을 합치는 방법
배깅: 데이터를 랜덤하게 여러 번 뽑아 여러 모델을 학습시키는 방법
랜덤포레스트: 배깅을 이용해 여러 결정트리를 만든 앙상블 모델

5. 랜덤포레스트에서 “랜덤”은 무엇이 랜덤일까?

랜덤포레스트에는 이름 그대로 랜덤, 즉 무작위 요소가 들어갑니다.

크게 두 가지가 랜덤입니다.

첫 번째는 데이터를 랜덤으로 뽑는 것입니다.

모든 결정트리가 완전히 같은 데이터를 보고 공부하지 않습니다.
각각의 나무가 조금씩 다른 데이터를 보고 공부합니다.

두 번째는 질문에 사용할 특징을 랜덤으로 고르는 것입니다.

예를 들어 과일을 구분한다고 해보겠습니다.

사용할 수 있는 특징은 여러 가지입니다.

색깔
크기
무게
향기
껍질 모양
당도

결정트리는 이 특징들을 보고 질문을 만듭니다.

하지만 랜덤포레스트에서는 모든 나무가 매번 똑같은 특징만 보지 않습니다.
나무마다 일부 특징을 랜덤하게 보고 판단합니다.

이렇게 하면 모든 나무가 너무 비슷해지는 것을 막을 수 있습니다.

즉, 랜덤포레스트는 여러 나무가 서로 조금씩 다른 관점으로 문제를 바라보게 만듭니다.

그래서 더 다양한 의견을 모을 수 있습니다.

6. n_estimators란?

랜덤포레스트를 실제 코드로 사용하다 보면 n_estimators라는 설정을 자주 보게 됩니다.

처음 보면 낯선 단어입니다.

하지만 뜻은 간단합니다.

n_estimators는 랜덤포레스트 안에 들어가는 결정트리의 개수입니다.

예를 들어 n_estimators=100이라고 하면 결정트리 100개를 만들겠다는 뜻입니다.

RandomForestClassifier(n_estimators=100)

이 코드는 이렇게 이해하면 됩니다.

“나무 100개로 이루어진 랜덤포레스트를 만들겠다.”

나무가 1개만 있으면 한 명의 의견만 듣는 것과 비슷합니다.

나무가 10개 있으면 조금 더 다양한 의견을 들을 수 있습니다.

나무가 100개 있으면 더 많은 의견을 모을 수 있습니다.

하지만 무조건 많다고 좋은 것은 아닙니다.

나무가 많아질수록 계산 시간이 오래 걸립니다.
컴퓨터가 더 많은 나무를 만들고, 더 많은 예측을 계산해야 하기 때문입니다.

그래서 보통 처음에는 이런 값들을 많이 사용합니다.

n_estimators=100
n_estimators=200
n_estimators=500

처음 공부할 때는 n_estimators=100 정도로 시작하면 이해하기 쉽습니다.

7. 가지치기란?

이번에는 가지치기(Pruning)를 알아보겠습니다.

가지치기는 실제 나무에서도 사용하는 말입니다.

나무가 너무 복잡하게 자라면 불필요한 가지를 잘라내서 깔끔하게 정리합니다.

결정트리에서도 비슷합니다.

결정트리가 너무 깊고 복잡해지면 훈련 데이터는 아주 잘 맞힐 수 있습니다.

하지만 새로운 데이터가 들어오면 오히려 잘 못 맞힐 수 있습니다.

이것을 과적합(Overfitting)이라고 합니다.

쉽게 말하면, 문제의 원리를 이해한 것이 아니라 답만 외운 상태와 비슷합니다.

예를 들어 학생이 수학 개념을 이해하지 않고 문제집 답만 외웠다고 해보겠습니다.

똑같은 문제가 나오면 맞힐 수 있습니다.
하지만 숫자나 상황이 조금만 바뀌면 틀릴 수 있습니다.

결정트리도 마찬가지입니다.

학습 데이터에만 너무 딱 맞게 자라면 새로운 데이터에 약해질 수 있습니다.

그래서 너무 복잡한 가지를 줄이고 핵심만 남기는 것이 가지치기입니다.

위 그림처럼 가지치기 전에는 나무가 너무 복잡합니다.

질문이 너무 많고, 가지가 너무 많습니다.

하지만 가지치기 후에는 핵심 질문만 남습니다.

이렇게 하면 과적합을 줄이는 데 도움이 됩니다.

랜덤포레스트에서는 여러 트리를 함께 사용하기 때문에 결정트리 하나보다 과적합에 강한 편입니다.

하지만 그래도 트리가 너무 복잡해지지 않도록 여러 설정을 조절할 수 있습니다.

대표적으로 이런 설정들이 있습니다.

max_depth
min_samples_split
min_samples_leaf

여기서 max_depth는 트리가 너무 깊게 자라지 않도록 제한하는 값입니다.

예를 들어 max_depth=5라고 하면 트리의 깊이를 5단계 정도로 제한하겠다는 뜻입니다.

8. 랜덤포레스트의 장점

랜덤포레스트는 실무에서도 많이 쓰이는 머신러닝 알고리즘입니다.

이유는 장점이 꽤 많기 때문입니다.

첫 번째 장점은 성능이 안정적이라는 점입니다.

하나의 결정트리만 사용하면 특정 데이터에 너무 치우칠 수 있습니다.
하지만 랜덤포레스트는 여러 결정트리의 의견을 모으기 때문에 더 안정적인 판단을 할 수 있습니다.

두 번째 장점은 과적합에 비교적 강하다는 점입니다.

여러 나무가 서로 다른 데이터를 보고 공부하기 때문에 하나의 나무가 잘못된 방향으로 판단해도 전체 결과가 크게 흔들리지 않을 수 있습니다.

세 번째 장점은 분류와 회귀 모두에 사용할 수 있다는 점입니다.

분류는 종류를 맞히는 문제입니다.

스팸 메일인가?
고양이인가 강아지인가?
합격인가 불합격인가?

회귀는 숫자를 예측하는 문제입니다.

집값은 얼마일까?
내일 온도는 몇 도일까?
상품 판매량은 얼마나 될까?

랜덤포레스트는 이런 문제들에 모두 사용할 수 있습니다.

네 번째 장점은 어떤 특징이 중요한지 확인할 수 있다는 점입니다.

예를 들어 집값을 예측할 때 어떤 요소가 중요했는지 확인할 수 있습니다.

위치
면적
방 개수
층수
건축 연도

이 중 어떤 특징이 예측에 더 많이 영향을 줬는지 볼 수 있습니다.

이것을 보통 특성 중요도(Feature Importance)라고 합니다.

9. 랜덤포레스트의 단점

물론 랜덤포레스트도 완벽한 알고리즘은 아닙니다.

단점도 있습니다.

첫 번째 단점은 계산 시간이 늘어날 수 있다는 점입니다.

결정트리 하나만 만드는 것보다 결정트리 100개, 200개를 만드는 것이 더 오래 걸립니다.

그래서 데이터가 아주 크거나 빠른 응답이 필요한 서비스에서는 조정이 필요합니다.

두 번째 단점은 결과를 설명하기가 조금 어려울 수 있다는 점입니다.

결정트리 하나는 질문 흐름을 따라가면 이해하기 쉽습니다.

하지만 랜덤포레스트는 수많은 결정트리의 결과를 합칩니다.
그래서 전체 판단 과정을 한눈에 설명하기는 어렵습니다.

세 번째 단점은 모델 크기가 커질 수 있다는 점입니다.

n_estimators 값을 크게 하면 나무가 많아집니다.
나무가 많아지면 모델도 커지고, 예측 시간도 늘어날 수 있습니다.

10. 주요 용어 한 번에 정리하기

용어쉬운 설명

결정트리	질문을 따라가며 답을 찾는 나무 구조
랜덤포레스트	여러 결정트리를 모아 만든 머신러닝 모델
앙상블	여러 모델의 힘을 합쳐 더 좋은 결과를 만드는 방법
배깅	데이터를 랜덤하게 여러 번 뽑아 여러 모델을 학습시키는 방법
가지치기	너무 복잡한 트리의 불필요한 가지를 줄이는 방법
n_estimators	랜덤포레스트 안에 들어가는 결정트리 개수
과적합	학습 데이터는 잘 맞히지만 새로운 데이터에는 약한 상태
max_depth	결정트리가 얼마나 깊게 자랄 수 있는지 정하는 값

11. 간단한 파이썬 코드로 보기

파이썬에서는 scikit-learn 라이브러리를 사용하면 랜덤포레스트를 쉽게 만들 수 있습니다.

from sklearn.ensemble import RandomForestClassifier

model = RandomForestClassifier(
n_estimators=100,
max_depth=5,
random_state=42
)

model.fit(X_train, y_train)

pred = model.predict(X_test)

여기서 중요한 부분은 다음과 같습니다.

n_estimators=100

결정트리 100개를 사용하겠다는 뜻입니다.

max_depth=5

각 결정트리가 너무 깊게 자라지 않도록 제한한다는 뜻입니다.

random_state=42

랜덤하게 뽑는 과정을 고정해서, 다시 실행해도 같은 결과가 나오도록 하는 설정입니다.

처음 공부할 때는 이 정도만 이해해도 충분합니다.

12. 랜덤포레스트를 한 문장으로 정리하면?

랜덤포레스트는 이렇게 정리할 수 있습니다.

여러 개의 결정트리를 만들고, 각각의 의견을 모아서 더 안정적인 결정을 내리는 머신러닝 방법입니다.

초등학생식으로 더 쉽게 말하면 이렇게 말할 수 있습니다.

한 명에게만 물어보지 않고, 여러 명에게 물어본 다음 다수결로 정하는 똑똑한 방법입니다.

랜덤포레스트는 이름은 어렵지만, 핵심은 단순합니다.

나무 하나보다 숲이 더 튼튼하듯이, 모델 하나보다 여러 모델이 함께 판단하면 더 안정적인 결과를 만들 수 있습니다.

마무리

랜덤포레스트는 머신러닝을 처음 공부할 때 꼭 알아두면 좋은 알고리즘입니다.

결정트리, 앙상블, 배깅, 가지치기, n_estimators 같은 용어가 처음에는 어렵게 느껴질 수 있습니다.

하지만 숲속의 여러 나무가 함께 의견을 내고 투표한다고 생각하면 훨씬 쉽게 이해할 수 있습니다.

정리하면 다음과 같습니다.

결정트리 = 질문을 따라 답을 찾는 나무
랜덤포레스트 = 여러 결정트리가 모인 숲
앙상블 = 여러 모델의 힘을 합치는 방법
배깅 = 데이터를 랜덤하게 나눠 여러 모델을 학습시키는 방법
n_estimators = 숲 안에 있는 나무의 개수
가지치기 = 너무 복잡한 나무를 깔끔하게 정리하는 방법

랜덤포레스트를 이해하면 머신러닝의 중요한 흐름 하나를 잡을 수 있습니다.

바로 하나의 모델에만 의존하지 않고, 여러 모델의 의견을 모아 더 좋은 결정을 내리는 방식입니다.

이 개념은 랜덤포레스트뿐만 아니라 다른 여러 머신러닝 기법을 이해하는 데도 큰 도움이 됩니다.

숫자의 함정에서 벗어나는 법: 스케일링(Scaling)과 로그(Log) 변환

코딩금융치료 — Tue, 28 Apr 2026 09:55:14 +0900

데이터 분석이나 머신러닝 공부를 시작하면 가장 먼저 마주치는 벽이 있습니다. 바로 "데이터 전처리"죠. 그중에서도 "왜 멀쩡한 숫자에 로그를 취하나요?", "스케일링은 왜 꼭 해야 하나요?"라는 질문에 대한 답을 오늘 완벽하게 정리해 보겠습니다.

1. 로그(Log) 변환: "폭발적인 숫자를 잠재우는 마법"

머신러닝 모델은 '숫자의 크기'에 굉장히 민감합니다. 하지만 우리가 사는 세상의 데이터는 그리 고르지 않습니다.

집값 데이터의 예시

대부분의 집은 3억~10억 사이에 몰려 있지만, 가끔 100억이 넘는 초고가 펜트하우스가 등장합니다. 이를 데이터 시각화해보면 왼쪽으로 치우치고 오른쪽 꼬리가 아주 긴(Right-Skewed) 모양이 됩니다.

로그를 왜 취하나요?

데이터의 격차 해소: 로그는 큰 숫자를 작게 만들고, 작은 숫자들 사이의 간격은 상대적으로 넓게 만듭니다. 100억이라는 거대한 숫자를 로그의 세계로 가져오면 다른 데이터들과 '대화가 가능한 수준'으로 차분해집니다.
종 모양(정규분포)으로 만들기: 머신러닝 모델(특히 선형 회귀)은 데이터가 예쁜 종 모양일 때 학습 성능이 가장 좋습니다. 로그는 삐져나온 꼬리를 안으로 당겨 데이터를 종 모양에 가깝게 펴주는 역할을 합니다.
비율(%)의 관점: 1억에서 2억이 되는 것(2배)과 10억에서 20억이 되는 것(2배)을 동일한 '성장'으로 인식하게 합니다. 이는 복리나 성장률이 중요한 금융 데이터에서 필수적입니다.

꿀팁: 데이터에 0이 있으면 로그값은 정의되지 않습니다(마이너스 무한대). 그래서 보통 log(x + 1)을 해주는 np.log1p() 함수를 사용합니다.

2. 데이터 스케일링(Scaling): "공평한 운동장을 만드는 과정"

스케일링은 한마디로 "단위(Unit)의 통일"입니다.

‍♂️ 유치원생과 거인의 달리기 시합

데이터셋에 '방의 개수(1~5개)'와 '거실 면적(100~3000sqft)'이라는 두 변수가 있다고 가정해 봅시다.

방이 1개 늘어나는 것은 엄청난 변화지만, 수치상으로는 겨우 '+1'입니다.
면적이 조금 넓어지는 것은 사소할 수 있지만, 수치상으로는 '+100'이 훌쩍 넘습니다.

모델은 바보같이 "오! 숫자가 큰 면적이 훨씬 중요한 변수구나!"라고 오해하게 됩니다. 이를 막기 위해 모든 변수를 동일한 체급으로 맞춰주는 것이 스케일링입니다.

대표적인 스케일링 3대장

① StandardScaler (표준화)

방식: 평균을 0, 표준편차를 1로 만듭니다.
특징: 데이터를 '평균 근처에 얼마나 모여 있는가'로 재배치합니다.
단점: 이상치(Outlier)가 있으면 평균이 확 변해서 성능이 떨어질 수 있습니다.

② MinMaxScaler (정규화)

방식: 최솟값을 0, 최댓값을 1로 압축합니다.
특징: 모든 데이터를 0과 1 사이의 좁은 감옥에 가둡니다.
단점: 이상치가 '1억'처럼 크다면, 나머지 데이터들은 0.0001 근처에 닥닥 붙게 되어 변별력을 잃습니다.

③ RobustScaler (이상치 해결사)

방식: 평균 대신 중앙값(Median)과 사분위수(IQR)를 사용합니다.
특징: 이상치에 매우 강합니다. 튀는 값이 한두 개 있어도 대다수 데이터의 체급을 아주 예쁘게 잘 맞춰줍니다.
결론: 실제 현업 데이터나 캐글 집값 데이터처럼 튀는 값이 많은 경우 가장 정석적인 선택입니다.

블로그 요약 노트

로그 변환은 데이터의 분포를 고르게 만들고(정규화), 비율의 관점을 도입하기 위해 쓴다.
스케일링은 서로 다른 단위를 가진 변수들을 공평하게 비교하기 위해 필수적이다.
이상치가 걱정된다면 고민 말고 RobustScaler를 선택하자.

Nginx로 HTTPS(SSL) 구축하기 (Reverse Proxy + Let’s Encrypt)

코딩금융치료 — Fri, 20 Mar 2026 11:17:31 +0900

예전에는 HTTPS를 붙인다고 하면 꽤 부담스러운 작업처럼 느껴졌다.

인증서 발급, CSR 생성, 인증서 파일 적용, 웹서버 설정, 갱신 관리까지 손이 많이 갔고, 작은 서비스 하나 올리는데도 진입장벽이 있었다.

그런데 Nginx + Let’s Encrypt + Certbot 조합으로 구성해보니 생각보다 훨씬 간단했다.

특히 개인 서버나 소규모 서비스에서는 “도메인 연결 + Nginx reverse proxy + certbot 실행” 정도만으로도 HTTPS 서비스를 빠르게 올릴 수 있다.

이번 글에서는 Nginx를 이용해 SSL(HTTPS)을 붙이는 전체 흐름을 실제 적용 순서대로 정리한다.

1. 구성 목표

이번에 목표로 한 형태는 다음과 같다.

도메인: example.com (본인 도메인으로 변경)
웹서버: nginx
내부 서비스: 웹 애플리케이션 (예: 127.0.0.1:3000)
외부 접속: https://example.com
방식: Nginx가 80/443 포트를 받고, 내부 서비스로 reverse proxy

구조는 아래와 같다.

사용자 브라우저
    ↓
<https://example.com>
    ↓
Nginx (80/443)
    ↓
내부 서비스 (예: 127.0.0.1:3000)

이 구조의 장점은 명확하다.

외부에는 80/443만 공개
내부 서비스는 로컬 포트로만 유지 가능
SSL 처리는 Nginx에서 일괄 담당
서비스가 늘어나도 도메인만 추가해 확장 가능

2. 먼저 도메인 연결부터

HTTPS를 붙이기 전에 가장 먼저 해야 할 일은 도메인이 서버를 정확히 가리키도록 DNS를 설정하는 것이다.

예를 들어 example.com를 쓰려면 DNS에서 A 레코드를 등록한다.

호스트: @ 또는 서브도메인(예: app)
타입: A
값: 서버 공인 IP

TTL은 처음에는 짧게 두면 변경 반영 여부를 확인하기 편하다.

3. Nginx reverse proxy 먼저 구성 (HTTP)

SSL을 붙이기 전에 먼저 HTTP로 서비스가 정상 연결되는지 확인하는 것이 좋다.

처음부터 HTTPS까지 한 번에 보려고 하면 DNS 문제인지, Nginx 문제인지, 애플리케이션 문제인지 구분이 어렵다.

아래는 가장 단순한 reverse proxy 예시다.

server {
    listen 80;
    listen [::]:80;

    server_name example.com;

    location / {
        proxy_pass <http://127.0.0.1:3000>;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 등 업그레이드가 필요한 서비스라면 아래 헤더가 필요할 수 있음
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_buffering off;
        proxy_read_timeout 3600;
        proxy_send_timeout 3600;
    }
}

설정 후에는 아래처럼 테스트한다.

sudo nginx -t
sudo systemctl reload nginx

그리고 브라우저에서 접속해본다.

<http://example.com>

여기서 서비스가 정상적으로 뜨면, 그 다음이 HTTPS 단계다.

. 중간에 만난 문제: 정적 파일 404

처음에는 reverse proxy만 걸면 끝날 줄 알았는데, 실제로는 하위 리소스(정적 파일)들이 404가 나는 문제가 있었다.

예를 들면 아래 같은 요청이 계속 실패했다.

<http://example.com/static/loader.js>

원인을 확인해보니 Nginx 설정에 남아 있던 정적 웹서버 설정(root 등)이 요청을 가로채고 있었다.

예를 들어 server 블록에 아래 설정이 남아 있으면:

root /var/www/html;

Nginx는 /static/loader.js 요청을 upstream으로 넘기지 않고 로컬 파일 경로에서 먼저 찾는다.

기대했던 동작: /static/loader.js → upstream(내부 서비스)로 전달
실제 동작: /static/loader.js → Nginx 로컬 경로에서 파일 검색 → 404

그래서 reverse proxy 전용 server 블록에서는 root, index, try_files 같은 정적 웹서버 설정을 빼고,

요청을 전부 proxy_pass로 넘기는 구조가 더 깔끔했다.

5. Certbot으로 HTTPS 적용

HTTP가 정상이라면 이제 SSL 인증서를 붙이면 된다.

지금은 Certbot이 발급과 Nginx 설정 변경까지 대부분을 자동화해준다.

(1) 설치 (Ubuntu 예시)

배포판/환경에 따라 설치 방식이 다를 수 있으니, 공식 문서를 함께 확인하는 것을 권장한다.

sudo apt update
sudo apt install -y snapd
sudo snap install core
sudo snap refresh core
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

(2) 인증서 발급 및 Nginx 설정 자동 반영

sudo certbot --nginx -d example.com

실행 중 이메일, 약관 동의, HTTP→HTTPS 리다이렉트 여부 등을 묻는다.

리다이렉트를 선택하면 Certbot이 Nginx 설정까지 자동으로 수정해준다.

6. 최종 구성 형태 (HTTPS + 리다이렉트)

최종적으로는 아래와 같은 형태가 된다.

인증서 경로는 Certbot이 발급한 도메인 기준으로 자동 생성되며, 환경에 따라 다를 수 있다.

server {
    listen 80;
    listen [::]:80;

    server_name example.com;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    server_name example.com;

    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    location / {
        proxy_pass <http://127.0.0.1:3000>;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_buffering off;
        proxy_read_timeout 3600;
        proxy_send_timeout 3600;
    }
}

이제 사용자는 https://example.com로 접속하고,

Nginx가 SSL을 종료한 뒤 내부 서비스로 안전하게 전달한다.

7. 자동 갱신 확인

SSL 구축이 쉬워진 가장 큰 이유는 갱신 관리까지 자동화가 가능하다는 점이다.

아래처럼 dry-run으로 갱신 테스트를 해볼 수 있다.

sudo certbot renew --dry-run

이게 성공하면 운영 중 인증서 만료로 인한 사고 가능성이 크게 줄어든다.

8. 여러 서비스로 확장하기

이 구조는 한 서비스에서 끝나지 않고, 서비스가 늘어나도 쉽게 확장할 수 있다.

app.example.com → 웹 서비스
api.example.com → API 서버
admin.example.com → 관리자 페이지

즉 Nginx를 진입점으로 두고, 뒤쪽 서비스들을 reverse proxy로 나누면 된다.

소규모 환경에서는 호스트에 Nginx를 설치해 SSL과 라우팅을 담당하게 하는 방식이 특히 실용적이다.

마무리

정리하면 흐름은 단순하다.

도메인을 서버 IP에 연결
Nginx reverse proxy로 내부 서비스 연결
HTTP로 정상 동작 확인
Certbot으로 SSL 적용
HTTPS 리다이렉트 및 자동 갱신 확인

예전에는 SSL이 어렵게 느껴졌지만,

지금은 오히려 기본 인프라 작업 중 가장 빠르게 끝나는 편에 가까워졌다.

클라우드 없이 로컬 LLM 환경 구축하기 (Ubuntu + Ollama + Open WebUI, GTX 1080 테스트)

코딩금융치료 — Thu, 19 Mar 2026 09:52:33 +0900

로컬 LLM을 서비스나 개인 프로젝트에 붙이려면 결국 비용 문제가 따라옵니다. 처음에는 “API로 일단 써보자”로 시작하지만, 프롬프트를 조금만 바꾸고 결과를 비교하는 과정을 반복하면 호출량이 금방 쌓입니다.

이번에는 방향을 바꿔 클라우드 없이 Ubuntu 서버에 로컬 LLM 환경을 직접 구성해봤습니다. 특히 집에 남는 **GTX 1080 장비를 재활용해서 ‘가볍게 테스트’**해보는 게 목적이었습니다.

목표

Ubuntu에 Ollama 설치
모델 1개 다운로드 후 실행
Open WebUI까지 붙여 브라우저에서 테스트
GTX 1080 환경에서 “쓸 만한지” 가볍게 확인

왜 로컬 LLM을 써보려고 했나

로컬 LLM을 보게 된 이유는 단순히 비용 통제 때문입니다.

제가 테스트하려는 방향은 자유 채팅형 서비스라기보다, 정해진 데이터를 넣고 요약하거나 설명을 만들어내는 내부 분석형 구조에 가깝습니다.

예를 들면 이런 작업입니다.

문서 요약
핵심 포인트 정리
쉬운 표현으로 다시 설명하기
입력 데이터 기반 요약 문구 생성

이런 작업은 꼭 비싼 클라우드 모델이 아니어도 어느 정도 처리할 수 있습니다.
오히려 중요한 건 아래에 더 가까웠습니다.

내가 가진 데이터를 잘 정리하느냐
응답 속도가 감당 가능한 수준이냐
운영비를 통제할 수 있느냐

그래서 이번에는 “최고 성능 모델”보다 “운영 가능한 로컬 환경” 쪽에 초점을 맞췄습니다.

Ollama는 정확히 뭘까

Ollama 홈페이지

처음에 헷갈리기 쉬운데 Ollama는 모델 자체가 아닙니다.

정리하면 아래처럼 이해하는 게 가장 편합니다.

Qwen, Llama, EXAONE → 실제 모델
Ollama → 로컬에서 모델을 실행하게 해주는 런타임(실행 도구)

즉 Ollama를 설치한다고 바로 AI가 완성되는 것은 아니고, 설치 후에 어떤 모델을 쓸지 골라서 다운로드해야 합니다.

예:

ollama run qwen2.5:7b

어떤 장비면 테스트가 가능할까

처음부터 RTX 4090이나 서버급 GPU가 꼭 필요한 건 아닙니다. 가볍게 테스트하는 수준이라면 문턱이 생각보다 낮습니다.

1) 가볍게 설치/동작 확인

GTX 1080
RAM 16GB 이상
7B급 경량 모델

이 정도면 “설치가 되는지”, “모델이 뜨는지”, “요약이 어느 정도 되는지”는 충분히 확인할 수 있었습니다.

nvidia-smi 실행 화면

2) 조금 더 무난하게 써보기

RTX 4070 SUPER / RTX 5070
RAM 32GB 이상
7B~8B급 모델 운영

테스트를 넘어서 로컬 실사용도 현실적인 구간입니다.

3) 여유 있게 실험해보기

VRAM 16GB 이상
14B급 모델까지 검토 가능

물론 실제 체감은 모델 크기, 컨텍스트 길이, 동시 요청 수에 따라 달라집니다. 다만 출발점으로는 GTX 1080 + 7B급도 충분히 의미가 있었습니다.

Ubuntu에 Ollama 설치

설치 자체는 단순했습니다. 공식 설치 스크립트를 그대로 실행하면 됩니다.

curl -fsSL <https://ollama.com/install.sh> | sh

설치 후 버전 확인:

ollama -v

GPU가 Ubuntu에서 정상적으로 잡히는지도 확인했습니다.

nvidia-smi

여기까지는 크게 어렵지 않았습니다. 진짜 시간은 “설치”보다 연결해서 실제로 쓰는 과정에서 더 들었습니다.

모델은 설치 후 따로 받아야 한다

Ollama는 실행기이기 때문에, 설치 후 바로 응답이 오지 않습니다. 실제로 쓸 모델을 하나 받아야 합니다.

처음에는 경량 테스트용으로 Qwen 계열을 받아봤습니다.

ollama pull qwen2.5:7b

설치된 모델 확인:

ollama list

직접 실행:

ollama run qwen2.5:7b

여기서 느낀 점이 하나 있었습니다.

로컬 모델은 최신 데이터를 알고 있는 모델이 아니다.

실제로 IPO 관련 질문을 던졌을 때 예전 시점 정보처럼 보이는 답이 나오기도 했고, Qwen 계열은 중국어가 섞이는 경우도 있었습니다.

이 지점에서 “로컬 LLM은 최신 사실 기억용이 아니라 내가 넣어준 데이터를 정리하는 엔진으로 봐야겠구나”라는 생각이 확실해졌습니다.

브라우저에서 테스트하려고 Open WebUI도 붙였다

터미널에서만 테스트하는 것도 가능하지만, 브라우저에서 ChatGPT처럼 확인할 수 있는 UI가 있으면 훨씬 편합니다. 그래서 Open WebUI를 같이 붙였습니다.

Docker Compose 설정은 대략 아래처럼 구성했습니다.

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    restart: always
    ports:
      - "3000:8080"
    environment:
      OLLAMA_BASE_URL: "<http://192.168.0.3:11434>"
      WEBUI_SECRET_KEY: "(원하는 값으로 변경)"
    volumes:
      - open-webui:/app/backend/data

volumes:
  open-webui:

실행:

docker compose up -d

브라우저에서 아래 주소로 접속하면 됩니다.

http://서버IP:3000

실제 접속 화면

아래는 실제로 Ubuntu 서버에 올린 Open WebUI에 브라우저로 접속한 화면입니다.

open webui 로그인

브라우저에서도 기본적인 채팅 UI가 정상적으로 열리는 것을 확인할 수 있었고,
“일단 로컬 LLM 환경을 웹으로 붙여서 어디서든 접속 가능한 형태로 만들 수 있겠구나” 하는 감이 왔습니다.

아직 이 단계는 완성된 서비스라기보다 테스트 환경에 가깝지만,
Ollama와 Open WebUI 조합만으로도 생각보다 꽤 그럴듯한 로컬 AI 채팅 환경이 만들어졌습니다.

여기까지 오면 끝난 줄 알았는데, 실제로는 이 지점에서 Linux 특유의 네트워크 이슈를 한 번 겪었습니다.

설치보다 오래 걸린 건 “연결 문제”였다

처음에는 Open WebUI에서 Ollama를 바로 읽어올 줄 알았는데 연결이 안 됐습니다.

1) host.docker.internal 이슈

Windows 등에서는 자주 쓰는 host.docker.internal 방식이 Ubuntu에서는 기본으로 바로 동작하지 않는 경우가 있습니다.

그래서 호스트의 실제 내부 IP를 직접 넣는 방식으로 바꿨습니다.

예: 192.168.0.3

2) 더 큰 문제: Ollama가 127.0.0.1에만 바인딩

결정적인 문제는 Ollama가 기본적으로 127.0.0.1:11434에만 바인딩되어 있었던 점입니다.

즉, 호스트 자신은 접근할 수 있지만 Docker 컨테이너는 접근할 수 없는 상태였습니다.

이 문제를 해결하려면 Ollama를 모든 인터페이스에 열리도록 다시 실행해야 했습니다.

pkill ollama
OLLAMA_HOST=0.0.0.0:11434 ollama serve

이제 Open WebUI에서 Ollama에 정상적으로 붙을 수 있었습니다.

systemd에도 영구 반영하기

테스트할 때는 셸에서 OLLAMA_HOST=0.0.0.0:11434로 띄우면 되지만, 이 상태로 두면 재부팅 후 원래대로 돌아갈 수 있습니다.

그래서 systemd override로 영구 반영했습니다.

sudo systemctl edit ollama

아래 내용을 추가합니다.

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

반영:

sudo systemctl daemon-reload
sudo systemctl restart ollama

연결은 됐는데 모델이 안 보일 때

Open WebUI까지 연결하고 나면, 이번에는 모델 목록이 안 보이는 경우가 있습니다.

ollama list
curl http://127.0.0.1:11434/api/tags

여기서 모델이 실제로 설치되어 있지 않으면, 당연히 Open WebUI에서도 목록이 비어 있습니다.
그래서 ollama pull을 먼저 하고, 브라우저를 새로고침하거나 Open WebUI를 재기동하면 해결되는 경우가 많았습니다.

docker compose restart

또는 로그아웃 후 다시 로그인해도 반영되는 경우가 있습니다.

관리자 계정에서는 보이는데 다른 사용자에게는 모델이 안 보일 때

이건 조금 더 헷갈리는 경우입니다.
관리자 계정으로 접속하면 모델이 잘 보이는데, 일반 사용자 계정에서는 모델 목록이 비어 있거나 선택이 안 되는 경우가 있습니다.

처음에는 Ollama 연결 문제로 생각하기 쉬운데,
실제로는 Open WebUI 내부 설정이나 사용자 노출 범위 문제인 경우가 많습니다.

이럴 때는 아래 순서로 보는 게 가장 빠릅니다.

1) 모델이 실제로 설치돼 있는지 먼저 확인

가장 기본적인 점검입니다.

ollama list

여기서 모델이 없으면 관리자든 일반 사용자든 안 보여야 정상입니다.

2) 관리자 계정에서는 보이는지 확인

관리자 화면에서 모델이 보인다면, Ollama 연결과 모델 설치는 대체로 정상이라고 볼 수 있습니다.
이 경우는 네트워크 문제보다는 Open WebUI 설정 문제일 가능성이 높습니다.

3) 일반 사용자 세션을 새로고침한다

새 모델을 pull 한 뒤 일반 사용자 세션에는 바로 반영되지 않는 경우도 있습니다.

이럴 때는 아래 순서가 의외로 잘 먹힙니다.

브라우저 새로고침
로그아웃 후 재로그인
새 채팅 화면으로 다시 진입
그래도 안 되면 Open WebUI 재기동

4) 사용자 권한이나 모델 노출 설정을 확인한다

관리자 계정에서는 보이는데 일반 사용자에게만 안 보인다면,
대부분은 Open WebUI 쪽의 사용자 노출 설정이나 권한 범위를 먼저 의심하는 것이 맞습니다.

즉 이런 문제는 보통 GPU나 Ollama 문제라기보다
**“모델은 있는데 사용자 화면에 노출되지 않는 문제”**에 가깝습니다.

정리하면, 이런 경우에는 아래 순서로 점검하면 됩니다.

ollama list 로 모델 설치 확인
관리자 계정에서 모델 보이는지 확인
일반 사용자 새로고침/재로그인
Open WebUI 권한 및 노출 설정 확인
필요 시 Open WebUI 재기동

써보니 느낀 점 (핵심 정리)

Ollama 설치 자체는 어렵지 않았습니다. 진짜 중요한 건 설치 후 어떻게 연결해서 실제로 쓰느냐였습니다.

특히 Linux에서는 아래 3가지를 꼭 확인해야 합니다.

Ollama가 어느 인터페이스에 바인딩되어 있는지
Docker 컨테이너가 호스트를 어떻게 바라보는지
Open WebUI가 실제로 어느 주소를 호출하는지

이 부분만 맞추면, 이후에는 생각보다 편하게 로컬 LLM 환경을 쓸 수 있습니다.

모델 비교 테스트
프롬프트 실험
백엔드 연동
로컬 AI 채팅 환경 구성

마무리

이번 작업의 목적은 “최고 성능의 AI 서비스”가 아니라, 클라우드 없이도 돌아가는 로컬 LLM 테스트 환경을 직접 구축해보는 것이었습니다.

Ubuntu에 Ollama를 설치하고, GTX 1080 장비에서 가볍게 모델을 실행한 뒤, Open WebUI까지 붙여 브라우저에서 테스트해보니 꽤 실용적이라는 느낌을 받았습니다.

개인 프로젝트나 초기 MVP 단계에서 “일단 클라우드 비용 없이 한 번 돌려보고 싶다”는 생각이 있다면, Ollama + Open WebUI 조합은 좋은 출발점이 될 수 있습니다.

open web ui 채팅창

Jenkins 기반 CI/CD 1차 검증 정리 (정적 웹 + Docker 배포)

코딩금융치료 — Fri, 13 Mar 2026 14:47:03 +0900

들어가며

배포서버를 Jenkins 기반 CI/CD 전용 서버로 활용하기 위한 1차 검증 내용을 정리했습니다.

목표는 정적 웹 샘플 프로젝트를 기준으로, 아래의 End-to-End 흐름이 실제로 한 번 끝까지 정상 동작하는지 확인하는 것입니다.

브랜치 작업 → Git push
Jenkins Pipeline 실행
Docker 이미지 빌드
이미지 tar 산출물 생성
개발서버 전송
개발서버에서 이미지 로드 및 컨테이너 기동
개발서버 내부에서 curl로 응답 확인

검증 범위

포함

Jenkins 설치 및 기동 확인
Jenkins 실행 Java 21 적용
Git 설치 및 저장소 연동
개발서버 배포 계정 생성 및 SSH 키 기반 접속 구성
Pipeline 기반 checkout
Docker 이미지 빌드
이미지 tar 생성
개발서버 전송(SCP)
개발서버에서 docker load 및 테스트 컨테이너 기동
개발서버 내부 curl 검증

제외

운영서버 배포
Git webhook 또는 polling 자동 트리거
Spring Boot 및 Maven 빌드
무중단 배포
스테이징 환경
사설 Docker Registry

검증 환경

배포서버( Jenkins 서버 )

역할: CI/CD 실행 및 빌드 서버

Jenkins, Java 21, Git, Docker 설치
Pipeline 실행
Docker 이미지 빌드 및 산출물 생성
개발서버로 산출물 전송

개발서버

역할: 1차 배포 및 검증 대상 서버

배포용 계정 devops 생성
공개키 등록
Docker 설치 및 기동
테스트 컨테이너 별도 실행

사전 준비(체크리스트)

Jenkins 설치 및 기동 완료
Jenkins 접속 포트 9090 적용
Java 21 적용 완료
Git 설치 완료
Docker 설치 완료
Jenkins Credentials에 개발서버 SSH 키 등록 완료
- Kind: SSH Username with private key
- Username: devops
- Credential ID: ssh-devops-devserver
배포서버에서 devops@개발서버 SSH 접속 확인 완료

Git 저장소 및 샘플 구조

브랜치

feature/static-cicd-test

디렉터리 구조(예시)

project-root/
 ├─ Jenkinsfile
 ├─ (기존 Java 프로젝트 파일)
 └─ cicd-static-sample/
     ├─ index.html
     └─ Dockerfile

샘플 파일

index.html

<!DOCTYPE html>
<html>
<head>
	<meta charset="UTF-8" />
	<title>Hello Jenkins</title>
</head>
<body>
	<h1>Hello Jenkins CI/CD</h1>
	<p>Static Web Deploy Success</p>
</body>
</html>

Dockerfile

FROM nginx:alpine
COPY index.html /usr/share/nginx/html/index.html

전체 흐름(중요 개념)

이번 1차 검증에서 핵심은 작업 위치가 서로 다르다는 점입니다.

원격 Git 저장소: 소스 원본
배포서버 Jenkins Workspace: checkout 된 소스가 존재하는 작업 공간
배포서버 Docker 엔진: 이미지 빌드 수행 위치
개발서버: 컨테이너 실행 및 검증 위치

즉 Pipeline은 저장소에서 파일을 직접 조작하는 것이 아니라,

소스를 Jenkins Workspace로 가져온 뒤(Checkout) 배포서버에서 빌드하고, 산출물을 개발서버로 전달하는 구조입니다.

Jenkins Workspace 확인 팁

Jenkins 서버 쉘

ls -al /var/lib/jenkins/workspace
ls -al /var/lib/jenkins/workspace/작업명

Pipeline에서 확인

sh 'pwd'

dir('cicd-static-sample') 의미

아래 구문은 셸의 cd cicd-static-sample과 같습니다.

dir('cicd-static-sample') {
	sh 'docker build -t sample-static-web:static-cicd-test .'
}

정적 웹 샘플과 Dockerfile이 프로젝트 루트가 아니라 하위 폴더에 있으므로, docker build의 기준 경로를 맞추기 위해 필요합니다.

산출물(Artifact) 관리 정책

저장 경로

/data/jenkins-artifacts/static-web

파일 예시

/data/jenkins-artifacts/static-web/sample-static-web-static-cicd-test.tar

운영 방식

최신 테스트 산출물 1개 기준으로 덮어쓰기
이미지 이름과 태그는 충돌 방지를 위해 테스트용으로 분리

Jenkins Pipeline 스크립트(예시)

Stage 구성:

Checkout
Check Files
Build Image
Save Image
Transfer Image
Deploy To Dev
Verify On Dev

아래 스크립트의 원격저장소URL, 개발서버IP는 실제 값으로 교체하세요.

pipeline {
	agent any

	stages {
		stage('Checkout') {
			steps {
				git branch: 'feature/static-cicd-test',
					credentialsId: 'git-sample-creds',
					url: '원격저장소URL'
			}
		}

		stage('Check Files') {
			steps {
				sh 'pwd'
				sh 'ls -al'
				sh 'ls -al cicd-static-sample'
				sh 'cat cicd-static-sample/index.html'
			}
		}

		stage('Build Image') {
			steps {
				dir('cicd-static-sample') {
					sh 'docker build -t sample-static-web:static-cicd-test .'
				}
			}
		}

		stage('Save Image') {
			steps {
				sh '''
					rm -f /data/jenkins-artifacts/static-web/sample-static-web-static-cicd-test.tar
					docker save -o /data/jenkins-artifacts/static-web/sample-static-web-static-cicd-test.tar sample-static-web:static-cicd-test
					ls -lh /data/jenkins-artifacts/static-web/
				'''
			}
		}

		stage('Transfer Image') {
			steps {
				withCredentials([sshUserPrivateKey(
					credentialsId: 'ssh-devops-devserver',
					keyFileVariable: 'SSH_KEY',
					usernameVariable: 'SSH_USER'
				)]) {
					sh '''
						ssh -o StrictHostKeyChecking=no -i "$SSH_KEY" ${SSH_USER}@개발서버IP 'mkdir -p /home/devops/deploy'
						scp -o StrictHostKeyChecking=no -i "$SSH_KEY" \\
							/data/jenkins-artifacts/static-web/sample-static-web-static-cicd-test.tar \\
							${SSH_USER}@개발서버IP:/home/devops/deploy/
					'''
				}
			}
		}

		stage('Deploy To Dev') {
			steps {
				withCredentials([sshUserPrivateKey(
					credentialsId: 'ssh-devops-devserver',
					keyFileVariable: 'SSH_KEY',
					usernameVariable: 'SSH_USER'
				)]) {
					sh '''
						ssh -o StrictHostKeyChecking=no -i "$SSH_KEY" ${SSH_USER}@개발서버IP '
							docker load -i /home/devops/deploy/sample-static-web-static-cicd-test.tar &&
							docker rm -f sample-static-web-test || true &&
							docker run -d --name sample-static-web-test -p 8082:80 sample-static-web:static-cicd-test &&
							docker ps | grep sample-static-web-test
						'
					'''
				}
			}
		}

		stage('Verify On Dev') {
			steps {
				withCredentials([sshUserPrivateKey(
					credentialsId: 'ssh-devops-devserver',
					keyFileVariable: 'SSH_KEY',
					usernameVariable: 'SSH_USER'
				)]) {
					sh '''
						ssh -o StrictHostKeyChecking=no -i "$SSH_KEY" ${SSH_USER}@개발서버IP '
							curl -o /dev/null -s -w "%{http_code}\\n" <http://127.0.0.1:8082>
						'
					'''
				}
			}
		}
	}
}

개발서버에서 수동 검증 명령(필요 시)

# 컨테이너 확인
docker ps

# 응답 확인
curl -s <http://127.0.0.1:8082>

# HTTP 상태코드만 확인
curl -o /dev/null -s -w "%{http_code}\\n" <http://127.0.0.1:8082>

# 이미지 확인
docker images

테스트 컨테이너 운영 정책

기존 개발 컨테이너와 충돌을 피하기 위해 테스트용으로 분리했습니다.

이미지: sample-static-web:static-cicd-test
컨테이너: sample-static-web-test
포트: 8082:80

검증 결과

확인된 사항

Jenkins 기동 정상
Java 21 적용 정상
Git checkout 정상
Docker 이미지 빌드 정상
tar 산출물 생성 정상
배포서버 → 개발서버 전송 정상
개발서버에서 이미지 로드 및 컨테이너 기동 정상
개발서버 내부 curl 검증에서 HTTP 200 확인

결론

정적 웹 샘플 기준으로 Jenkins 기반 CI/CD 1차 검증은 정상 완료되었습니다.

다음 단계(2차 목표)

다음 단계에서는 Spring Boot + Maven + Docker로 확장하여 검증할 예정입니다.

Spring Boot 샘플 구성
Maven compile 및 package
Docker 이미지 생성 및 배포
Git webhook 또는 polling 기반 자동 트리거 검토

젠킨스 환경 구축 가이드

코딩금융치료 — Thu, 12 Mar 2026 10:45:37 +0900

도커 컨테이너를 사용하지 않고 서버에 젠킨스 설치 과정으로 진행 했다.

실제 설치 과정을 참고 하고 싶은 분들에게 권장합니다.

기준 환경

작성일: 2026-03-12
OS: Rocky Linux 8.0
패키지 매니저: dnf

1) 관리자 실계정 생성

ci/cd 관리 계정을 생성한다. root가 아닌 sudo 권한으로 진행 하기 위해 생성 했다.

sudo useradd -m -s /bin/bash devops
sudo passwd devops
sudo usermod -aG wheel devops
id devops

2) Java 설치 (OpenJDK 21)

sudo dnf install -y java-21-openjdk java-21-openjdk-devel
java -version

3) Jenkins 공식 저장소 등록

sudo rpm --import <https://pkg.jenkins.io/redhat-stable/jenkins.io-2026.key>

sudo tee /etc/yum.repos.d/jenkins.repo > /dev/null <<'EOF'
[jenkins]
name=Jenkins-stable
baseurl=https://pkg.jenkins.io/redhat-stable
gpgcheck=1
repo_gpgcheck=1
enabled=1
gpgkey=https://pkg.jenkins.io/redhat-stable/jenkins.io-2026.key
EOF

sudo dnf repolist | grep jenkins

4) Jenkins 설치

sudo dnf install -y jenkins

5) Jenkins 기동

sudo systemctl daemon-reload
sudo systemctl enable jenkins
sudo systemctl start jenkins
sudo systemctl status jenkins --no-pager

6) 계정 및 경로 확인

id jenkins
getent passwd jenkins
ls -ld /var/lib/jenkins
ls -ld /var/log/jenkins

7) 초기 비밀번호 확인

sudo cat /var/lib/jenkins/secrets/initialAdminPassword

8) 방화벽 오픈 (8080)

방화벽 기동시에만 추가한다. firewalld 를 쓰지 않는다면 해당 없음

sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload
sudo firewall-cmd --list-ports

아래 부터는 필수 진행 조건은 아니니 필요하면 추가하도록 한다.

9) Jenkins 포트 변경 (예: 9090)

젠킨스 포트를 기본 포트 말고 다른 포트로 변경시에만 진행

sudo systemctl edit jenkins

아래 내용을 추가:

[Service]
Environment="JENKINS_PORT=9090"

적용:

sudo systemctl daemon-reload
sudo systemctl restart jenkins
sudo systemctl status jenkins --no-pager

10) 호스트 등록

192.168.1.92 jenkins.dev.local

http://jenkins.dev.local:9090 으로 접속 확인

호스트 등록하지 않고 기본 접속 으로 사용시 http://localhost:8080 접속

11) 초기비밀번호 확인

sudo cat /var/lib/jenkins/secrets/initialAdminPassword

초기비밀번호를 copy 하여 그대로 web 화면에 붙여넣고 진행 한다.

하이퍼렛저 패브릭

코딩금융치료 — Mon, 9 Mar 2026 17:49:47 +0900

1. 하이퍼렛저 패브릭이란?

하이퍼렛저 패브릭은 기업/기관 간 거래를 신뢰성 있게 기록하고 검증하기 위한 허가형 블록체인 플랫폼이다.

아무나 참여하는 공개 블록체인이 아니라 허가받은 회사/기관만 참여 거래내역을 여러 참여자가 함께 검증하고 공유 위변조가 어렵고, 거래 이력을 투명하게 남길 수 있는 구조

2. 핵심 구성 요소

2.1 원장(Ledger)

원장은 블록체인에서 거래내역이 저장되는 장부다.

패브릭의 원장은 크게 두 부분으로 생각하면 쉽다.

Blockchain
- 거래가 블록 단위로 차곡차곡 쌓이는 영역
- 과거 이력이 계속 남음
- 변경 이력 추적 가능
World State
- 현재 시점의 최종 상태를 따로 저장한 영역
- 예: 현재 주문 상태가 APPROVED 인지 SETTLED 인지 바로 조회 가능

2.2 블록(Block)

블록은 여러 거래를 묶어서 저장하는 단위다.

예를 들어:

거래 1: 주문 생성
거래 2: 주문 승인
거래 3: 정산 완료

이런 거래 여러 개가 하나의 블록에 들어간다.

블록은 이전 블록과 연결되므로

중간의 내용을 바꾸면 전체 연결이 깨지게 된다.

그래서 위변조가 어렵다.

2.3 트랜잭션(Transaction)

트랜잭션은 원장에 기록되는 하나의 업무 행위다.

예:

주문 등록
승인 처리
상태 변경
정산 처리
거래 취소

즉, 거래시스템에서는

사용자의 업무 요청 하나하나가 패브릭의 트랜잭션이 된다.

2.4 피어(Peer)

피어는 블록체인 네트워크에 참여하는 서버다.

역할은 다음과 같다.

원장 보관
체인코드 실행
거래 검증
블록 수신 및 반영

쉽게 말하면 피어는

“실제 데이터를 들고 있으면서 거래를 검사하는 서버” 다.

회사 A, 회사 B가 각각 피어를 운영할 수 있다.

그러면 서로 같은 거래를 공유하게 된다.

2.5 오더러(Orderer)

오더러는 거래의 순서를 정리해서 블록으로 묶는 역할을 한다.

블록체인에서는 거래가 동시에 많이 들어오므로 순서를 정해줘야 한다.

오더러가 하는 일은:

거래 요청 수집
순서 정렬
블록 생성
각 피어에게 블록 전달

쉽게 말하면 오더러는 “거래를 정렬해서 블록으로 만들어 배포하는 서버” 다.

2.6 채널(Channel)

채널은 참여자별로 원장을 분리하는 논리적 공간이다.

예를 들어:

A기관과 B기관만 보는 거래 채널
A기관, B기관, 감독기관이 함께 보는 감사 채널

이렇게 나눌 수 있다.

즉, 같은 패브릭 네트워크 안에서도

모든 데이터를 모두가 보는 것이 아니라, 필요한 참여자끼리만 공유할 수 있다.

거래시스템에서는 매우 중요한 개념이다.

2.7 체인코드(Chaincode)

체인코드는 패브릭에서 실행되는 업무 로직이다.

쉽게 말하면 블록체인용 프로그램이다.

예를 들어 체인코드 안에 이런 로직을 넣을 수 있다.

주문 생성
이미 존재하는 주문번호인지 검증
승인 권한 체크
상태 전이 검증
정산 완료 처리

즉, 일반 시스템의 서비스 로직 중

공동 검증이 필요한 핵심 규칙을 체인코드로 넣는다고 보면 된다.

패브릭의 체인코드는 흔히 “스마트 컨트랙트”라고도 부른다.

2.8 조직(Organization)

패브릭은 여러 기관이 참여하는 구조라서

각 참여 주체를 조직(Org) 으로 구분한다.

예:

Org1 = 거래기관 A
Org2 = 거래기관 B
Org3 = 정산기관
Org4 = 감사기관

각 조직은 자기 피어, 사용자, 인증서를 가진다.

2.9 MSP(Membership Service Provider)

MSP는 네트워크 참가자의 신원을 식별하는 체계다.

쉽게 말하면:

이 사용자가 누구인지
이 서버가 어느 조직 소속인지
이 요청이 믿을 수 있는 인증서인지

를 판단하는 기준이다.

즉 MSP는

“패브릭에서 신분 확인을 담당하는 체계” 다.

2.10 CA(Certificate Authority)

CA는 인증서를 발급하는 기관이다.

패브릭에서는 사용자나 피어에게 인증서를 발급해서

누가 누구인지 증명하게 한다.

예:

관리자 인증서
애플리케이션 사용자 인증서
피어 서버 인증서
오더러 인증서

즉 CA는

“참여자에게 전자신분증을 발급하는 기관” 이다.

참조: Network vs Channel (Hyperledger Fabric)

네트워크(Network): Fabric 기반 인프라 전체
- 구성: Orderer, Peer, CA, 조직, 인증 체계
- 비유: 도로, 건물, 전기 같은 기반 시설
채널(Channel): 네트워크 위에 만들어지는 업무별 공동 원장
- 의미: 실제 거래가 기록되는 논리적 공간
- 비유: 오피스 빌딩 안의 회의실
비유 정리
- 네트워크 = 오피스 빌딩
- 채널 = 빌딩 안의 회의실
- 피어 = 회의에 참가하는 사람 또는 장비
- 원장 = 회의록 </aside>

Java GC(Garbage Collection) 기초 개념 정리

코딩금융치료 — Thu, 7 Aug 2025 10:53:55 +0900

Java에서의 메모리 관리는 자동으로 이루어지며, 그 중심에는 Garbage Collector(GC)가 있습니다. 이번 글에서는 GC의 기본 원리와 각 영역의 역할, 그리고 객체가 살아가는 흐름에 대해 정리합니다.

1. GC란 무엇인가?

GC(Garbage Collection)는 프로그램 실행 중 더 이상 사용되지 않는 객체를 자동으로 메모리에서 제거하여, 메모리를 효율적으로 관리하는 JVM의 기능입니다. Java에서는 개발자가 명시적으로 메모리를 해제하지 않아도 GC가 이를 대신해줍니다.

2. JVM 메모리 구조와 GC 관련 영역

JVM의 힙(Heap)은 다음과 같이 나뉩니다:

Young Generation
- Eden 영역: 새로 생성된 객체들이 저장됨
- Survivor 영역(S0, S1): Eden에서 살아남은 객체들이 이동하는 공간
Old Generation
- 여러 번의 GC를 견디고 살아남은 객체가 승격(promote)되어 저장됨
Metaspace
- 클래스 메타데이터가 저장되는 공간 (JDK 8부터 PermGen을 대체)

3. GC의 동작 원리

(1) 객체 생성과 Minor GC

새로 생성된 객체는 Eden 영역에 저장됩니다.
Eden이 가득 차면 Minor GC가 발생하여,
- GC Root에서 참조되지 않는 객체는 제거되고,
- 살아남은 객체는 Survivor 영역으로 이동합니다.
이 과정을 거치며 객체는 age(생존 횟수) 를 증가시키게 됩니다.

(2) Survivor → Old 영역으로의 승격

Survivor 영역에 있던 객체가 여러 번의 Minor GC에서도 살아남으면,
→ 일정 age 이상일 경우 Old 영역으로 승격됩니다.
Old 영역은 장기적으로 참조되는 객체들이 모이는 곳입니다.

(3) Full GC

Old 영역이 가득 차거나,
System.gc()와 같은 명시적 호출이 있거나,
Metaspace가 부족해질 경우

→ Full GC가 발생하여 Young, Old, Metaspace 영역까지 모두 GC의 대상이 됩니다.

4. GC Root와 객체 생존 여부

GC는 단순히 "얼마나 오래 있었는가"를 기준으로 객체를 제거하지 않습니다.
대신 GC Root에서 참조 가능한지(Reachable) 여부를 기준으로 객체 생존 여부를 판단합니다.

대표적인 GC Root 예시:

현재 실행 중인 쓰레드의 스택 프레임 (지역 변수 등)
static 변수
JNI(Global references)

5. 정리된 객체의 생존 흐름 요약

Eden → Survivor → Old

Eden에 생성된 객체 중 GC Root에서 참조되지 않는 객체는 GC에 의해 제거
살아남은 객체는 Survivor로 이동하고 age 증가
age가 기준 이상이면 Old 영역으로 승격
Old 영역이 가득 차면 Full GC 발생 가능

마무리

Java의 GC는 매우 똑똑하게 설계되어 있지만, 정확히 이해하고 있어야 성능 병목을 줄이고, 적절한 튜닝도 가능해집니다. 이번 글에서는 기본적인 흐름만 정리했지만, 이후에는 다양한 GC 알고리즘(Serial, Parallel, G1 등)과 튜닝 방법까지 확장해볼 수 있습니다.

이 포스트는 Java GC 개념을 정리하고 싶을 때 참고하기 위한 목적으로 작성되었습니다.
필요하신 분들께 도움이 되기를 바랍니다.

Docker "Failed to start docker.service: Unit docker.service not found" 오류

코딩금융치료 — Tue, 5 Aug 2025 10:02:29 +0900

Docker가 snap 기반으로 설치 되어 서비스가 정상 기동이 되지 않을 경우 해결 방법

1. docker가 Snap인지 확인

#which docker

/snap/bin/docker로 나오면 Snap 기반

2. Snap으로 설치된 Docker 제거

sudo snap remove docker

3. Snap 대신 Docker 공식 설치로 전환

- Docker 공식 리포지터리를 통한 설치 (Ubuntu 24.04 기준)

sudo apt update
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) \
  signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

4. 서비스 기동

sudo systemctl enable --now docker

5. 도커 테스트

sudo docker run hello-world

> Hello from Docker !

Snap으로 Docker를 사용할 때의 주요 문제점

항목	문제 내용
보안 격리	Snap 앱은 sandbox 환경에서 실행되므로, 시스템 리소스 접근(예: /var/run/docker.sock, 특정 마운트 경로 등)에 제한이 있습니다.
경로 문제	docker.sock 파일이 표준 경로(/var/run/docker.sock)가 아닌 Snap 전용 경로에 위치하기 때문에, 기존 스크립트나 도구들이 정상 작동하지 않을 수 있습니다. 예: docker-compose, Portainer, Jenkins 등과의 연동 실패.
도커 Compose 연동 문제	docker-compose가 Docker 데몬에 접근하지 못해 Cannot connect to the Docker daemon 등의 오류가 발생할 수 있습니다.
서비스 제어 불가	일반적으로 사용하는 systemctl start docker 등의 명령어가 작동하지 않으며, 대신 snap start docker 등의 Snap 전용 명령어를 사용해야 합니다.
서드파티 도구와 호환성 저하	일부 서드파티 툴은 Snap Docker를 인식하지 못하거나, 특수 경로 문제로 인해 실행에 실패합니다.
리눅스 커널 기능 제한	Snap 환경의 제한으로 인해 Cgroups, OverlayFS 등 특정 커널 기능 사용이 제한되어 Docker의 일부 기능이 정상적으로 작동하지 않을 수 있습니다.
버전 제어 어려움	Docker 공식 릴리스와 버전 차이가 있으며, 특정 버전으로 고정하기도 어렵습니다.
볼륨 및 마운트 제한	Snap 외부 경로에 대한 볼륨 마운트 시 권한 이슈가 발생하며, 별도의 권한 부여가 필요하거나 마운트에 실패할 수 있습니다.

Snap Docker는 일반 사용자/테스트 용도로는 괜찮을 수 있지만, 실제 개발/운영 환경에서는 문제 발생 가능성이 높기 때문에 비추천

자바 클래스 로더와 WAS에서의 로딩 우선순위 — 충돌 없이 이해하기

코딩금융치료 — Mon, 16 Jun 2025 16:33:39 +0900

클래스 충돌, 왜 발생할까요?

Java 웹 애플리케이션을 개발하다 보면
"이 클래스 왜 안 불러와지지?", "같은 이름인데 충돌이 나네?"
이런 현상을 자주 겪게 됩니다.

특히 WAS(Web Application Server)를 사용하는 경우, Java SE와는 다른 클래스 로딩 구조를 가지고 있어서
충돌이나 예외가 발생하는 원인을 이해하지 못하면 디버깅에 큰 어려움을 겪습니다.

이 글에서는 다음 내용을 중심으로 개념을 정리해 봅니다.

Java 클래스 로딩 순서와 부모 위임 모델
시스템 클래스 오버라이드 가능 여부
WAS에서 클래스 우선순위가 달라지는 이유
같은 클래스가 classes, JAR, WAS 모듈에 있을 때 어떤 게 로딩될까?

Java의 기본 클래스 로딩 구조

Java는 기본적으로 부모 위임 모델 (Parent Delegation Model) 을 사용합니다.
즉, 클래스 로더가 클래스 로딩 요청을 받으면 자기 자신이 처리하기 전에 부모에게 먼저 위임합니다.

클래스 로딩 위임 순서

Bootstrap ClassLoader (JDK의 핵심 클래스, java.lang 등)
Platform ClassLoader (Java 9 이전에는 Extension ClassLoader)
Application ClassLoader (classpath, WEB-INF/classes, lib/*.jar 등)

부모가 클래스를 로딩할 수 있으면 자식은 로딩하지 않고, 이미 로드된 클래스를 그대로 사용합니다.

시스템 클래스는 오버라이드할 수 없다

예를 들어 내가 직접 만든 java/util/ArrayList.class 파일을 넣었다 하더라도,
JVM은 해당 클래스를 무조건 Bootstrap ClassLoader에서 로딩합니다.

사용자 정의 클래스는 무시되며,
잘못하면 SecurityException, LinkageError 같은 예외가 발생합니다.

이는 JVM 보안 정책 때문이며,
java.* 또는 javax.* 계열의 클래스는 절대로 오버라이드할 수 없습니다.

WAS에서는 클래스 로딩 방식이 다르다

대부분의 WAS(Web Application Server)는 Java SE와는 다르게
클래스 로더 격리 정책(ClassLoader Isolation)을 사용합니다.

즉, 부모 위임보다는 애플리케이션 자체의 classes나 lib JAR 파일을 먼저 로딩합니다.
이런 정책은 애플리케이션 간의 충돌을 방지하고, 서버 안정성을 높이기 위해 사용됩니다.

WAS 클래스 로딩 우선순위

다음은 일반적인 WAS에서의 클래스 로딩 우선순위입니다:

WEB-INF/classes (애플리케이션 클래스)
WEB-INF/lib/*.jar (애플리케이션 라이브러리)
서버 공통 모듈 또는 공유 클래스 (예: WAS 내장 모듈)
JDK 시스템 클래스 (java.*)

즉, 같은 클래스가 서버 모듈과 애플리케이션 양쪽에 동시에 존재할 경우,
WAS는 보통 애플리케이션 쪽 클래스를 먼저 로딩합니다.

충돌이 발생하는 대표적인 사례

ClassCastException: 같은 클래스인데 로더가 달라서 타입 호환이 안 됨
LinkageError: 패키지 이름 중복, 클래스 정의 충돌 등
SecurityException: 시스템 클래스를 잘못 오버라이드하려고 시도했을 때

클래스 로딩 흐름도

클래스 로딩이 실제로 어떤 경로를 따라 진행되는지를 시각적으로 이해하고 싶다면
아래의 흐름도를 참고하세요.

항목 Java SE WAS 환경

로딩 모델	부모 위임	애플리케이션 우선 (격리 정책)
시스템 클래스 오버라이드	불가	불가
사용자 클래스 오버라이드	가능	가능 (보통 classes가 우선)
충돌 가능성	낮음	중복 시 높음 (주의 필요)

WAS에서 시스템 모듈 클래스가 먼저 로딩되는 이유

지금까지는 일반적인 로딩 우선순위를 다뤘지만, 실제 WAS 환경에서는 서버 모듈 클래스가 먼저 로딩되어 lib 클래스가 무시되는 경우가 존재합니다.

예를 들어 WAS에는 다음과 같은 시스템 모듈이 존재합니다:

org.jboss.logging.Logger → WildFly 로깅 시스템
javax.transaction.UserTransaction → 서버 트랜잭션 모듈 등

이런 클래스들은 WAS 부팅 시점에 시스템 모듈로 먼저 메모리에 로딩됩니다.
이후 애플리케이션이 동일한 FQCN의 클래스를 lib 경로에 포함하더라도,
JVM은 이미 로딩된 클래스를 우선 사용하기 때문에 무시됩니다.

왜 이런 일이 발생할까?

JVM은 같은 이름의 클래스(FQCN)가 이미 로딩되었으면,
하위 로더에 있더라도 다시 로딩하지 않습니다.

그리고 WAS는 시스템 모듈을 **상위 클래스 로더(ModuleClassLoader)**에서 먼저 로딩하기 때문에,
애플리케이션 레벨(lib/*.jar)은 상위에 의해 이미 로딩된 클래스를 덮어쓸 수 없습니다.

실제로 발생하는 문제들

slf4j, logback 등 로깅 설정이 무시되고, WAS 기본 로깅(jboss-logging)만 동작
기대한 log4j 버전이 아닌 시스템 모듈 버전이 사용됨
인터페이스 충돌로 인해 ClassCastException 발생

어떻게 대응하면 좋을까?

같은 FQCN(전체 클래스 이름)을 가진 클래스가 여러 위치에 존재하지 않도록 관리하세요.
서버 공용 모듈과 충돌 가능성이 있는 경우, WAS 설정 파일(deployment-structure.xml 등)을 통해 모듈 제외 처리를 고려하세요.
로딩 순서나 위치를 정확히 확인하고 싶다면 -verbose:class 옵션이나 getClass().getClassLoader() 메서드를 활용하세요.

마치며

클래스 로더는 이해하기 어렵지만, 한 번 구조를 파악하고 나면
WAS 환경에서 발생하는 많은 충돌 문제를 쉽게 해결할 수 있습니다.

이 글이 클래스 로딩 우선순위를 이해하는 데 도움이 되었기를 바랍니다.