Troubleshooting on Joonlog

Jekyll Chirpy 테마 카테고리 에러 TroubleShooting(2)

Wed, 29 Oct 2025 18:00:00 +0900

문제 재발견

이전에 Jekyll Chirpy 테마 카테고리 중복/누락 TroubleShooting 글에서 _layouts/categories.html Liquid 템플릿을 수정해서 카테고리 문제를 해결했다고 생각지만, 계속해서 버그가 확인됨
- 카테고리 목록 페이지(/categories/)는 제대로 표시됨
- 하지만 개별 카테고리 페이지(/categories/kubernetes/)에 들어가면 메인 카테고리와 서브 카테고리가 전부 섞여서 표시됨
- 예시:
  - Certification > Kubernetes (서브카테고리): 1개 포스트
  - Kubernetes > Architecture (메인카테고리): 34개 포스트
  - /categories/kubernetes/ 접속 시: 35개 포스트 전부 표시

근본 원인

이전 해결책은 _layouts/categories.html (목록 페이지)만 고친 것
진짜 문제는 Jekyll Archives 플러그인

Jekyll Archives 플러그인의 동작 방식
- categories: [Certification, Kubernetes] 형태의 포스트가 있으면 site.categories['Certification']에도 포함되고 site.categories['Kubernetes']에도 포함됨
- /categories/kubernetes/ 와 같은 1단계 경로로만 페이지를 생성하고 /categories/certification/kubernetes/ 같이 2단계 이상으로는 페이지를 생성하지 않음
_layouts/category.html의 한계
1

{% raw %}{% for post in page.posts %}{% endraw %}
- page.posts는 Jekyll Archives가 이미 생성한 데이터
- Liquid 템플릿에서는 이미 섞인 데이터를 받음
- 페이지 생성 자체는 Ruby 플러그인이 하기 때문에 Liquid로는 근본 해결 불가

해결 방법

커스텀 Ruby 플러그인을 작성해서 Jekyll Archives를 대체

1. Jekyll Archives의 categories 비활성화

_config.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


# 변경 전
jekyll-archives:
 enabled: [categories, tags]
 layouts:
 category: category
 tag: tag
 permalinks:
 tag: /tags/:name/
 category: /categories/:name/

# 변경 후
jekyll-archives:
 enabled: [tags]
 layouts:
 tag: tag
 permalinks:
 tag: /tags/:name/

2. 카테고리 플러그인 작성

_plugins/hierarchical-categories.rb

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85


# frozen_string_literal: true

module Jekyll
 # Generates hierarchical category pages
 # Primary categories: /categories/primary/
 # Secondary categories: /categories/primary/secondary/
 class HierarchicalCategoryPage < Page
 def initialize(site, base, primary, secondary = nil)
 @site = site
 @base = base
 @dir = if secondary
 File.join('categories', primary.downcase.gsub(' ', '-'))
 else
 'categories'
 end
 @name = if secondary
 "#{secondary.downcase.gsub(' ', '-')}.html"
 else
 "#{primary.downcase.gsub(' ', '-')}.html"
 end

 self.process(@name)
 self.read_yaml(File.join(base, '_layouts'), 'category.html')

 # Set category name for display
 self.data['title'] = secondary || primary
 self.data['category_name'] = secondary || primary
 self.data['primary_category'] = primary
 self.data['secondary_category'] = secondary

 # Filter posts based on category hierarchy
 if secondary
 # Secondary category: posts where categories[0] == primary AND categories[1] == secondary
 self.data['posts'] = site.posts.docs.select do |post|
 post.data['categories'] &&
 post.data['categories'][0] == primary &&
 post.data['categories'][1] == secondary
 end
 else
 # Primary category: posts where categories[0] == primary
 self.data['posts'] = site.posts.docs.select do |post|
 post.data['categories'] &&
 post.data['categories'][0] == primary
 end
 end
 end
 end

 class HierarchicalCategoryPageGenerator < Generator
 safe true
 priority :low

 def generate(site)
 return unless site.layouts.key? 'category'

 # Collect all primary and secondary categories
 primary_categories = {}

 site.posts.docs.each do |post|
 next unless post.data['categories']

 categories = post.data['categories']
 primary = categories[0]
 secondary = categories[1] if categories.length > 1

 next unless primary

 primary_categories[primary] ||= Set.new
 primary_categories[primary] << secondary if secondary
 end

 # Generate pages for each primary category
 primary_categories.each do |primary, secondaries|
 # Generate primary category page
 site.pages << HierarchicalCategoryPage.new(site, site.source, primary)

 # Generate secondary category pages
 secondaries.each do |secondary|
 next if secondary.nil?
 site.pages << HierarchicalCategoryPage.new(site, site.source, primary, secondary)
 end
 end
 end
 end
end

핵심 로직:
- 메인 카테고리: post.categories[0]만 매칭
- 서브 카테고리: post.categories[0] == primary AND post.categories[1] == secondary 동시 매칭
- URL 구조:
  - 메인 카테고리: /categories/kubernetes/
  - 서브 카테고리: /categories/certification/kubernetes/

3. 카테고리 목록 페이지 링크 수정

_layouts/categories.html
- 서브카테고리 URL을 /categories/sub/에서 /categories/primary/sub/로 수정
- URL 마지막 / 제거 (Jekyll이 .html 파일을 디렉토리로 인식하는 문제 방지)

56줄 메인 카테고리 링크

1
2
3
4
5


# 변경 전
{% raw %}{% capture _category_url %}/categories/{{ category_name | slugify | url_encode }}/{% endcapture %}{% endraw %}

# 변경 후
{% raw %}{% capture _category_url %}/categories/{{ category_name | slugify | url_encode }}{% endcapture %}{% endraw %}

121줄 서브 카테고리 링크

1
2
3
4
5


# 변경 전
{% raw %}{% capture _sub_ctg_url %}/categories/{{ sub_category | slugify | url_encode }}/{% endcapture %}{% endraw %}

# 변경 후
{% raw %}{% capture _sub_ctg_url %}/categories/{{ category_name | slugify | url_encode }}/{{ sub_category | slugify | url_encode }}{% endcapture %}{% endraw %}

결과

메인 카테고리 페이지: /categories/kubernetes/
- 메인이 카테고리가 kubernetes인 모든 포스트 표시
서브 카테고리 페이지: /categories/certification/kubernetes/
- 메인 카테고리가 Certification, 서브 카테고리가 Kubernetes인 포스트만 표시
카테고리 목록 페이지에서 클릭 시 올바른 URL로 이동
카테고리 버그 해결!

K8S에 구축한 GitLab Registry에 Container Image 푸시 시 blob upload unknown 에러 TroubleShooting

Sat, 27 Sep 2025 09:00:00 +0900

GitLab을 Helm Chart로 구축 + 브라우저에서 GitLab 접근 시 80 포트가 아닌 다른 포트로 접근해야 할 경우 발생하는 이슈 GitLab Helm Chart의 포트 설정이 80/443으로 고정되어 있기 때문에 발생

환경

자체 관리형 kubernetes이기에 외부용 L7 로드밸런서로 haproxy를 사용 중인 경우
helm chart로 GitLab 서버를 구축한 경우
외부에서 브라우저로 GitLab UI 접근 시 80포트가 아닌 8080과 같은 별도의 포트로만 접근해야하는 제약사항이 있는 경우

문제 상황

helm chart로 GitLab 서버 구축 후 <도메인>:<포트>로 접근 시 포트가 제거된 후 도메인으로만 강제 리다이렉션 되는 현상 발생
- 404 에러
브라우저 → HAProxy(8080) → GitLab(80) → 리다이렉트 응답

해결 방법

HAproxy 설정을 통해 포트를 포함해서 리다이렉트 하도록 설정

http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:8080/\\1

정규식 분석:
- ^http://gitlab.<도메인>/(.*)$ - 매칭 패턴
- http://gitlab.<도메인>:8080/\1 - 치환 결과
- \1 = 첫 번째 그룹 (.*) 내용 (URL 경로)
- 변환 예시:
  - 원본: Location: http://gitlab.<도메인>/users/sign_in
  - 변환: Location: http://gitlab.<도메인>/users/sign_in
외부 브라우저에서 GitLab 접근 시 포트를 붙여서 접근해야 될 경우 반드시 설정
설정하지 않으면 접근 시 자동으로 포트가 제거된 상태로 리다이렉션되어 404 에러

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


frontend unified_frontend_8080
 bind *:8080
 mode http
 option forwardfor

 # Host 기반 라우팅
 ...
 use_backend metallb_backend_gitlab if { hdr(host) -i gitlab.<도메인> }
 ...

backend metallb_backend_gitlab
 http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:8080/\\1
 server gitlab 172.27.1.102:80

결과

브라우저가 8080포트를 포함해서 리다이렉트
HAProxy를 통한 접속 유지

K8S에 구축한 Jenkins CI 파이프라인의 Dind 네트워크 에러 TroubleShooting

Sat, 27 Sep 2025 09:00:00 +0900

K8S 환경의 Jenkins에서 docker build가 Jenkins 파이프라인 파드의 dind 컨테이너에서 실행되기 때문에 발생한 이슈

환경

Jenkins 서버를 K8S에서 구축하고, 파이프라인을 K8S 파드에서 동작하도록 설정한 환경
- Jenkinsfile에서 K8S 파드 템플릿으로 파이프라인 실행하게 명시

문제 상황

Jenkinsfile의 docker build 단계에서 파이프라인 빌드 실패
- Dockerfile의 composer install 레이어에서 Could not fetch https://api.github.com/repos/ 에러 발생
- 외부에서 데이터를 받아오는 명령어에서 전부 timeout 에러 발생

에러 분석

Jenkins 파이프라인이 K8S 파드의 docker 컨테이너에서 실행되고, docker build 작업은 dind 컨테이너에서 실행됨
- dind 컨테이너 입장에서 네트워크가 격리되어 있어 GitHub API 서버로의 아웃바운드 연결 불가
따라서 composer install 와 같은 명령어 실행 시 연결 실패 에러 발생

해결 방법

Jenkinsfile의 k8s 파드 템플릿에 hostNetwork: true를 설정해서 파드의 컨테이너가 호스트 노드(현재 워커 노드)의 네트워크 네임스페이스를 사용할 수 있도록 설정
- 파드 템플릿이 아닌 docker build --network=host로 명령어 마다 옵션을 명시해서 해결도 가능하지만, 파드 레벨에서 해결하는게 관리에 용이

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


kubernetes {
 yaml """
 apiVersion: v1
 kind: Pod
 spec:
 serviceAccountName: jenkins
 hostNetwork: true
 hostAliases:
 - ip: "172.27.1.9"
 hostnames:
 - "registry.<도메인>"
 - "gitlab.<도메인>"
 containers:
 - name: docker
 image: docker
 command:
 - sleep
 args:
 - 99d
 tty: true
 volumeMounts:
 - name: workspace-volume
 mountPath: /home/jenkins/agent
 - name: docker-socket
 mountPath: /var/run
 - name: docker-daemon
 image: docker:dind
 securityContext:
 privileged: true
 env:
 - name: DOCKER_TLS_CERTDIR
 value: ""
 args:
 - --insecure-registry=registry.<도메인>:8080
 volumeMounts:
 - name: docker-socket
 mountPath: /var/run
 volumes:
 - name: workspace-volume
 emptyDir: {}
 - name: docker-socket
 emptyDir: {}
 """
 }

K8S에 구축한 GitLab UI 접근 시 접근 포트가 제거된 상태로 강제 리다이렉션 TroubleShooting

Thu, 25 Sep 2025 09:00:00 +0900

GitLab을 Helm Chart로 구축 + 브라우저에서 GitLab 접근 시 80 포트가 아닌 다른 포트로 접근해야 할 경우 발생하는 이슈 GitLab Helm Chart의 포트 설정이 80/443으로 고정되어 있기 때문에 발생

환경

자체 관리형 kubernetes이기에 외부용 L7 로드밸런서로 haproxy를 사용 중인 경우
helm chart로 GitLab 서버를 구축한 경우
외부에서 브라우저로 GitLab UI 접근 시 80포트가 아닌 8080과 같은 별도의 포트로만 접근해야하는 제약사항이 있는 경우

문제 상황

helm chart로 GitLab 서버 구축 후 <도메인>:<포트>로 접근 시 포트가 제거된 후 도메인으로만 강제 리다이렉션 되는 현상 발생
- 404 에러
브라우저 → HAProxy(8080) → GitLab(80) → 리다이렉트 응답

해결 방법

HAproxy 설정을 통해 포트를 포함해서 리다이렉트 하도록 설정

http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:8080/\\1

정규식 분석:
- ^http://gitlab.<도메인>/(.*)$ - 매칭 패턴
- http://gitlab.<도메인>:8080/\1 - 치환 결과
- \1 = 첫 번째 그룹 (.*) 내용 (URL 경로)
- 변환 예시:
  - 원본: Location: http://gitlab.<도메인>/users/sign_in
  - 변환: Location: http://gitlab.<도메인>/users/sign_in
외부 브라우저에서 GitLab 접근 시 포트를 붙여서 접근해야 될 경우 반드시 설정
설정하지 않으면 접근 시 자동으로 포트가 제거된 상태로 리다이렉션되어 404 에러

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


frontend unified_frontend_8080
 bind *:8080
 mode http
 option forwardfor

 # Host 기반 라우팅
 ...
 use_backend metallb_backend_gitlab if { hdr(host) -i gitlab.<도메인> }
 ...

backend metallb_backend_gitlab
 http-response replace-value Location ^http://gitlab\.<도메인>/(.*)$ http://gitlab.<도메인>:8080/\\1
 server gitlab 172.27.1.102:80

결과

브라우저가 8080포트를 포함해서 리다이렉트
HAProxy를 통한 접속 유지

HAproxy 동시 재기동 오류 TroubleShooting

Tue, 16 Sep 2025 09:00:00 +0900

두 서버의 HAProxy를 동시에 재기동하는 과정에서 VIP FAULT 현상이 발생
- keepalived/corosync/pacemaker 같은 클러스터 프로세스가 VIP 소유권을 제어하는 앱에서 자주 있는 일
- VIP(Virtual IP) 소유권 충돌이 발생하여 이로 인해 VIP가 정상적으로 할당되지 않고 모두 FAULT 상태로 전환 이후 BACKUP 상태로 변경됨
- 이후 순차적으로 keepalived를 재기동해서 정상적으로 Master 상태로 전환 확인
  - systemctl restart keepalived

위 현상 방지하기 위해 한 HAproZxy 재기동 후, 재기동하지 않은 서버가 MASTER 승격되었는지, VIP 활성화 되었는지 확인 필수

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


# HAProxy 재기동 시 로그

Reloading HAProxy Load Balancer...
Stopping proxy haproxy-ssl...
Stopping proxy haproxy...

Keepalived_vrrp[####]: (VI_1) received an invalid passwd!
Keepalived_vrrp[####]: (VI_1) Dropping received VRRP packet...
Keepalived_vrrp[####]: VRRP_Instance(VI_1) Entering FAULT STATE
Keepalived_vrrp[####]: VRRP_Script(chk_haproxy) failed
Keepalived_vrrp[####]: VRRP_Instance(VI_1) Now in FAULT state
Keepalived_vrrp[####]: VRRP_Instance(VI_1) Entering BACKUP STATE

# haproxy_test.sh 실행 결과
/keepalived/haproxy_test.sh exited with status 1
/keepalived/haproxy_test.sh exited with status 0

# BACKUP 전환 확인
Keepalived_vrrp[####]: VRRP_Instance(VI_1) Entering BACKUP STATE

HikariCP connection is closed 에러 TroubleShooting

Wed, 10 Sep 2025 09:00:00 +0900

MySQL은 wait_timeout 설정값에 따라 커넥션 중 일정 시간이상 사용하지 않은 커넥션을 종료
HikariCP는 maxLifetime 설정값에 따라 스스로 미사용된 커넥션을 제거하고 새로 생성하는 방식으로 동작
- 커넥션 누수 발생 시 connection closed 되지 않으므로 Hikari는 커넥션을 activate 상태로 파악하여 maxLifetime 에 따른 커넥션 갱신하지 않음
  - 따라서 wait_timeout 으로 인해 닫힌 커넥션을 재사용하려다 connection is closed 오류가 발생
  - HikariCP는 maxLifetime값을 DB의 wait_timeout보다 몇 초 정도 짧게 설정하라고 권장

connection is closed 에러 히스토리

connection pool 수치 점검
- default 10개, 필요시 20~30개로 설정
1

spring.datasource.hikari.maximum-pool-size=30
- 현재 실행 중인 쿼리의 Que 값이 connection Pool 최대 값까지 도달하여 다음 실행할 쿼리를 처리하지 못해 발생
- APM 솔루션으로 Connection Pool 자원 모니터링을 통해 증설이 필요할 시 즉시 증설, 쿼리 최적화 필요 언급
  - 이건 임시 조치만 반복할 뿐, 커넥션 누수는 코드를 수정해야 함
db 파라미터 wait_timeout = 500 설정

이후 재발

1
2
3
4
5
6
7


spring.datasource.hikari.minimum-idle=10 // 최소 커넥션 수
spring.datasource.hikari.idle-timeout=300000 // 유휴 커넥션 타임아웃 (5분)
spring.datasource.hikari.max-lifetime=1800000 // 최대 커넥션 생명 주기 (30분)
spring.datasource.hikari.connection-timeout=30000 // 커넥션 대기 시간 (30초)

# db 파라미터 max_connection = 2000으로 확인됨
spring.datasource.hikari.maximum-pool-size=60 // 30에서 60으로 변경

이후 재발
- HikariCP는 maxLifetime값을 DB의 wait_timeout보다 몇 초 정도 짧게 설정하라고 권장
  1
  
  spring.datasource.hikari.max-lifetime=497000 // 최대 커넥션 생명 주기 (497초)

이후 재발

was 서버 로그 확인 시 maxLifetime 값을 더 짧게 설정하는 것을 권장하는 로그 확인

1

[WARN ] [PoolBase.javalisConnectionAlive(184) : HikariPool-1 - Failed to connection org.mariadb.jdbc.MariaDbConnection@14441ec9 ((conn=8360) Connection.setNetworkTimeout cannot be called on a closed connection). Possibly consider using a shorter maxLifetime value.

maxLifetime 값 변경

1

spring.datasource.hikari.max-lifetime=470000 // 최대 커넥션 생명 주기 (470초)

동일오류 재발
- spring.datasource.hikari.connection-init-sql 프로퍼티를 추가하여 세션 wait_timeout을 설정
- wait_timeout 값을 설정된 hikari MaxLifetime 값 + 5초 형식으로 설정
  1
  
  spring.datasource.hikari.connection-init-sql=SET wait_timeout = 500

커넥션 누수 사례

https://jaehoney.tistory.com/337

wait_timeout 이 15초로 설정되어 있는데 레거시 코드 때문에 높이지 못함

따라서 세션의 wait_timeout을 설정

1

spring.datasource.hikari.connection-init-sql=SET wait_timeout = 500

https://do-study.tistory.com/97

EntityManager를 Bean으로 설정함
- EntityManager는 스레드간 절대 공유하면 안됨
QueryDSL 구현 Resitory에서 특정 datasource의 EntityManager를 받기 위해 setEntityManager를 재정의하지 않고 별도 setting 메소드 작성

Jekyll Chirpy 테마 카테고리 에러 TroubleShooting(1)

Sat, 30 Aug 2025 09:00:00 +0900

문제 확인

깃허브 블로그 템플릿으로 Jekyll Chirpy 테마를 사용 중이었는데, 쓰다 보니 카테고리가 내가 설정한 것과 다르게 동작하는 것을 발견했다.

EX 1) AWS를 상위 카테고리로 설정한 글을 작성했는데 실제 블로그에 AWS 카테고리가가 없는 경우
EX 2) Kubernetes는 상위 카테고리로만 설정했었는데, Kubernetes 하위 카테고리로 Kubernetes가 생기고 이전 글들이 똑같이 복사돼서 들어가 있는 경우
EX 3) 하위 카테고리로 AWS를 정했는데 AWS 상위 카테고리에 글이 들어가 있는 경우

원인

Jekyll Chirpy의 _layouts/categories.html 템플릿에서 site.categories를 사용하는 방식의 문제

site.categories의 동작 방식

site.categories는 모든 포스트의 모든 카테고리를 수집
categories : [Certification, AWS]인 글이 있으면 site.categories['AWS']에도 포함됨

결과적으로 같은 글이 여러 상위 카테고리에 중복 표시

1
2
3
4


&#123;% for category in sort_categories %&#125;
 &#123;% assign category_name = category | first %&#125;
 &#123;% assign posts_of_category = category | last %&#125;
 &#123;% if category_name == first_post.categories[0] %&#125;

해결 방법

_layouts/categories.html 상위 카테고리 로직

site.categories 대신 site.posts 직접 순회
첫 번째 카테고리(post.categories[0])만 상위 카테고리로 수집
해당 상위 카테고리를 가진 글들만 대상으로 처리

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


&#123;% assign group_index = 0 %&#125;

&#123;% comment %&#125; Collect all primary categories from posts &#123;% endcomment %&#125;
&#123;% assign primary_categories = '' | split: '' %&#125;
&#123;% for post in site.posts %&#125;
 &#123;% assign primary_cat = post.categories[0] %&#125;
 &#123;% if primary_cat %&#125;
 &#123;% unless primary_categories contains primary_cat %&#125;
 &#123;% assign primary_categories = primary_categories | push: primary_cat %&#125;
 &#123;% endunless %&#125;
 &#123;% endif %&#125;
&#123;% endfor %&#125;
&#123;% assign primary_categories = primary_categories | sort %&#125;

&#123;% for category_name in primary_categories %&#125;
 &#123;% comment %&#125; Get posts that have this as primary category &#123;% endcomment %&#125;
 &#123;% assign posts_of_category = '' | split: '' %&#125;
 &#123;% for post in site.posts %&#125;
 &#123;% if post.categories[0] == category_name %&#125;
 &#123;% assign posts_of_category = posts_of_category | push: post %&#125;
 &#123;% endif %&#125;
 &#123;% endfor %&#125;

_layouts/categories.html 하위 카테고리 로직

해당 상위 카테고리를 첫 번째로 가진 글들의 두 번째 카테고리만 수집

중복 제거 로직 유지

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


&#123;% comment %&#125; Collect subcategories &#123;% endcomment %&#125;
&#123;% assign sub_categories = '' | split: '' %&#125;
&#123;% for post in posts_of_category %&#125;
 &#123;% assign second_category = post.categories[1] %&#125;
 &#123;% if second_category %&#125;
 &#123;% unless sub_categories contains second_category %&#125;
 &#123;% assign sub_categories = sub_categories | push: second_category %&#125;
 &#123;% endunless %&#125;
 &#123;% endif %&#125;
&#123;% endfor %&#125;

_layouts/categories.html 포스트 수 계산 로직

site.categories[category_name] 대신 실제 해당 카테고리 글 개수 계산

하위 카테고리도 정확한 개수 표시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Primary category
&#123;% assign top_posts_size = posts_of_category | size %&#125;

# Subcategory
&#123;% comment %&#125; Count posts for this subcategory under current primary category &#123;% endcomment %&#125;
&#123;% assign posts_size = 0 %&#125;
&#123;% for post in posts_of_category %&#125;
 &#123;% if post.categories[1] == sub_category %&#125;
 &#123;% assign posts_size = posts_size | plus: 1 %&#125;
 &#123;% endif %&#125;
&#123;% endfor %&#125;

빌드 에러 발생 시

Liquid syntax error (line 150): ’endif’ is not a valid delimiter for for tags. use endfor

불필요한 {% endif %} 제거 (for 루프에는 {% endfor %}만 필요)

1
2


&#123;% assign group_index = group_index | plus: 1 %&#125;
&#123;% endfor %&#125;

해결

각 카테고리가 첫 번째 상위 카테고리 기준으로만 분류하도록 수정
중복 포스팅 문제 해결!

Tomcat Thread Stuck으로 인한 사이트 접근 불가 TroubleShooting

Thu, 24 Jul 2025 09:00:00 +0900

문제 개요

최근 특정 새벽 시간에 웹 서비스 접근 불가 현상이 반복 발생
Tomcat 로그 확인 시 Thread Stuck으로 요청 처리가 지연되었으며, 일정 시간 지난 후 자동 해소

1
2


WARNING argo.server.valves.LenaStuckThreadDetectionValve.notifyStuckThreadDetected ...
at com.tmax.tibero.jdbc.common.TbStream.readMsgDs(Unknown Source)

원인 추적

왜 Thread Stuck이 발생했는가?

Tibero DB를 사용 중인 DB 서버의 문제 발생 시간대에 sys.log에서 대량의 임시 테이블이 생성된 것을 확인
매일 01시에 tbexport full=Y 명령어를 수행하는 cronjob 설정된 상태
Full 백업 시 전체 용량이 몇백 GB가 넘는데, 백업 간 DB 리소스 고갈로 인해 Tomcat의 스레드가 응답 받지 못해 Thread Stuck이 발생한 것으로 확인

조치

백업 방식을 아래와 같이 논리적(tbexport) → 물리적 백업으로 전환
- 대용량의 DB 백업 시에는 물리적 백업이 모든 면에서 유리
  - 무중단 Hot Backup 가능
    - 단, Hot Backup은 archive log 모드에서만 가능
  - 내부 자원 사용 최소화
  - 복구 및 운영 안정성 향상

물리적 백업 방안

tbrmgr

사용해보니 매일 풀백업을 사용하는 현재의 환경에선 맞지 않고, 백업한 파일을 압축하지 않고 그대로 보관하면서 증분 백업을 통해 보관하는 환경에서 맞는 방안인 것으로 확인
- 현재는 매일 풀백업 + 풀백업한 파일 압축하여 보관하는 환경에서 사용 가능한 방법 필요

begin/end 백업

백업 모드 시작 - 데이터파일 복사 - 백업 모드 종료의 구조로 백업하는 방식
이 방식으로 해결

직렬화 기능을 사용중인 Tomcat의 세션 만료로 인한 강제 로그아웃 Troubleshooting

Mon, 23 Jun 2025 09:00:00 +0900

문제 상황

웹 서비스 사용 중 세션이 갑자기 만료되며 강제 로그아웃되는 현상 발생

원인 분석

Catalina 로그에서 ClassNotFoundException 확인

1
2
3
4
5
6
7


SEVERE [Catalina-utility-1] org.apache.catalina.session.StoreBase.processExpires
Error processing session expiration for key [BA8BFEFE...JVM1]
java.lang.ClassNotFoundException: egovframework.com.utl.slm.EgovHttpSessionBindingListener
 at org.apache.catalina.session.StandardSession.doReadObject(StandardSession.java:1268)
 at org.apache.catalina.session.StandardSession.readObjectData(StandardSession.java:846)
 at org.apache.catalina.session.FileStore.load(FileStore.java:203)
 at org.apache.catalina.session.StoreBase.processExpires(StoreBase.java:138)

Tomcat의 세션 직렬화 기능으로 인해, 서버가 재기동되거나 일정 시간이 경과한 후 세션 정보가 디스크에 저장된 파일(SESSIONS.ser)을 통해 복원 중
SESSIONS.ser에는 EgovHttpSessionBindingListener라는 클래스가 포함되어 있었으나, 현재 애플리케이션에는 이 클래스가 존재하지 않아 역직렬화 과정에서 오류 발생한 것으로 추정
Tomcat이 해당 세션을 복원하지 못해 세션을 강제 만료 처리 → 사용자 입장에서는 강제 로그아웃으로 인식됨

조치 내용

세션 복원 실패에 따른 반복적인 오류를 차단하기 위해 다음과 같은 조치 수행

Tomcat 세션 파일 SESSIONS.ser 삭제
Tomcat 재기동

→ 이후 세션 관련 오류 재발 없음, 사용자 세션 정상 유지 확인

결론

Tomcat은 세션 정보를 디스크에 저장 후 복원하는 과정에서, 클래스 누락 등으로 인해 세션 역직렬화에 실패할 수 있음
이 경우 해당 세션이 강제 만료되는 문제 발생
이후에도 세션 직렬화 기능을 사용한다면, 애플리케이션 배포 전 ser 파일 삭제 권장

죽은 Connection 사용 중인 Tomcat Troubleshooting

Thu, 19 Jun 2025 09:00:00 +0900

문제 상황

웹 서비스 접근 시 500 에러 출력

원인 분석

웹 서비스에 DB 서버 2대를 이중화하여 구성 중, 2번 서버로 DB Failover된 후 장애 발생

application log 확인

1
2
3
4


org.springframework.jdbc.support.SQLErrorCodesFactory] Error while extracting database product name - falling back to empty error codes
org.springframework.jdbc.support.SQLStateSQLExceptionTranslator] Extracted SQL state class 'JD' from value 'JDBC-90405:ERRJD'
org.springframework.transaction.interceptor.TransactionInterceptor] Application exception overridden by rollback exception
org.apache.catalina.core.StandardWrapperValve.invoke Servlet.service() for servlet [...] threw exception [...] with root cause

Tomcat에서 Failover 이전 DB 서버로의 Connection을 계속 사용해서 SQLException 오류 발생하여 500 에러 출력

조치 내용

즉각적인 웹 서비스 정상화를 위한 임시 조치

Tomcat 재기동 후 웹 서비스 정상 접근 확인

추가 조치 방안

Tomcat의 server.xml 혹은 context.xml에서 testWhileIdle 설정
- testWhileIdl: Tomcat이 Connection을 반환하기 전, 주기적으로 유휴 Connection 생존 여부를 검사
- timeBetweenEvictionRunsMillis: 30초마다 검사

1
2


testWhileIdle="true"
timeBetweenEvictionRunsMillis="30000"

결론

Tomcat의 JDBC Connection Pool은 testWhileIdle 옵션이 false일 경우, 장애 이후에도 죽은 Connection을 계속 사용할 수 있어 장애가 지속됨. 이 설정을 true로 변경하고 timeBetweenEvictionRunsMillis를 설정해서 DB Failover 시 자동적으로 Connection을 복구하도록 설정

참고

https://blog.naver.com/wasgosu-2010/90189771881

Apache AJP Localhost 연결 에러 TroubleShooting

Sat, 07 Jun 2025 09:00:00 +0900

증상

웹 접속 시 503 오류 발생

mod_jk.log에 AJP 연결 실패 로그 다수 출력

1
2
3


[error] ajp_connect_to_endpoint::jk_ajp_common.c (127.0.0.1:8009) (errno=111)
[error] jk_open_socket::jk_connect.c Failed socket to (127.0.0.1:8009)
[error] ajp_send_request::jk_ajp_common.c (worker1) Connecting to backend failed

netstat 기준으로 Tomcat은 AJP 포트(8009)를 정상적으로 Listen 중
1

tcp 0 0 127.0.0.1:8009 ::1 LISTEN [java 프로세스]

workers.properties 설정

기존 설정
1 2

worker.worker1.type=ajp13 worker.worker1.host=localhost
- host가 정상적으로 localhost로 되어 있는데, mod_jk.log에서는 ajp 연동 오류가 나오고, netstat은 IPv6에서만 LISTEN중
- /etc/hosts에도 정상적으로 localhost와 127.0.0.1이 명시된 것으로 확인
  - localhost를 127.0.0.1로 변경
이후 설정
1 2

worker.worker1.type=ajp13 worker.worker1.host=127.0.0.1
- host 값 변경 후 httpd 재기동 시 503 에러 해결

결론

로그를 종합했을 때, Tomcat은 127.0.0.1:8009에서 AJP를 수신하고 있었지만, workers.properties에 설정된 localhost가 내부적으로 ::1(IPv6)로 해석되어 연결이 실패한 것으로 추정

RSA Key를 사용한 SSH 불가 TroubleShooting

Tue, 20 May 2025 09:00:00 +0900

문제 요약

Ubuntu 24.04, Amazon Linux 2023 등 최신 리눅스에서 기존 RSA 키로 접속 불가
특히 SecureCRT는 ssh-rsa 알고리즘만 사용해서 오류 발생
Putty는 rsa-sha2-256 지원 → 같은 키로도 접속 가능

원인

최신 OpenSSH는 ssh-rsa (SHA-1 기반) 비활성화 → 보안상 위험
Amazon Linux 2023은 /etc/crypto-policies/back-ends/opensshserver.config를 통해 강제로 막음
Ubuntu는 기본 정책에선 막히진 않지만, OpenSSH 자체가 기본으로 제외시킴

해결 방법 (서버 측 설정 변경)

1

vim /etc/ssh/sshd_config

아래 두 줄을 추가
- Amazon Linux 2023: 반드시 Include보다 위쪽에
- Ubuntu 24.04: 위치는 무관 (보통 맨 아래 추가)

1
2


HostkeyAlgorithms +ssh-rsa
PubkeyAcceptedAlgorithms +ssh-rsa

1
2
3


# 설정 확인 및 sshd 재시작
sshd -t
systemctl restart sshd

주의사항

ssh-rsa는 보안 취약점 있음 (SHA-1 기반)
이 설정은 임시 방편일 뿐, 장기적으론 권장되지 않음

대안: 새 키 생성 시 최신 알고리즘 사용

1
2

ssh-keygen -t ed25519 -C "your@email.com"

추후 key 생성 시 RSA 보단 ESDSA 같은 알고리즘 사용 필요

Apache OPTIONS * 루프백 요청으로 인한 CPU 과부하 TroubleShooting

Fri, 25 Apr 2025 09:00:00 +0900

문제 상황

운영 중인 CentOS 서버에서 너무 많은 수의 httpd 프로세스가 CPU를 과점유하고, Load Average가 30 이상까지 치솟는 현상이 발생

원인 분석

access_log 확인 결과, 루프백 주소(::1)에서 OPTIONS * HTTP/1.0 요청이 수 초 간격으로 다수 발생
User-Agent는 "Apache/... (internal dummy connection)"으로, Apache 자체가 생성하는 dummy connection임을 확인
- 이 요청은 Apache의 internal dummy connection이며, 일반적으로는 MPM이 유휴 프로세스를 관리하기 위해 보내는 내부 테스트용 요청
- 하지만 일정 이상 발생하게 되면, 해당 요청을 처리하기 위한 httpd 프로세스가 과도하게 생성되고 정리되지 않아, 리소스를 점유

1
2
3
4
5
6
7
8


# tail -n 1000 /var/log/httpd/access_log | grep "::1"

::1 - - [22/Apr/2025:07:01:55 +0000] "OPTIONS * HTTP/1.0" 200 - "-" "Apache/2.4.6 (CentOS) OpenSSL/1.0.2k-fips (internal dummy connection)"
::1 - - [22/Apr/2025:07:02:34 +0000] "OPTIONS * HTTP/1.0" 200 - "-" "Apache/2.4.6 (CentOS) OpenSSL/1.0.2k-fips (internal dummy connection)"
::1 - - [22/Apr/2025:07:02:35 +0000] "OPTIONS * HTTP/1.0" 200 - "-" "Apache/2.4.6 (CentOS) OpenSSL/1.0.2k-fips (internal dummy connection)"
::1 - - [22/Apr/2025:07:02:36 +0000] "OPTIONS * HTTP/1.0" 200 - "-" "Apache/2.4.6 (CentOS) OpenSSL/1.0.2k-fips (internal dummy connection)"
::1 - - [22/Apr/2025:07:02:42 +0000] "OPTIONS * HTTP/1.0" 200 - "-" "Apache/2.4.6 (CentOS) OpenSSL/1.0.2k-fips (internal dummy connection)"
::1 - - [22/Apr/2025:07:02:56 +0000] "OPTIONS * HTTP/1.0" 200 - "-" "Apache/2.4.6 (CentOS) OpenSSL/1.0.2k-fips (internal dummy connection)"

1
2
3
4


# httpd -V | grep MPM

[Fri Apr 25 04:35:44.665826 2025] [so:warn] [pid 31382] AH01574: module rewrite_module is already loaded, skipping
Server MPM: prefork

MPM 관련 설정(StartServers, MaxRequestWorkers)이 명시되지 않은 상태
- Apache 기본값(최대 256개 프로세스)이 적용된 것으로 추정

조치 내용

하기 내용은 Apache 설정을 수정하지 않고 즉시 대응 가능한 임시 조치

IPv6 루프백 dummy connection 차단을 위한 ip6tables 규칙 추가

루프백(::1)에서 들어오는 OPTIONS * 요청만 차단
외부 요청이나 정상적인 HTTP 트래픽에는 영향 없음

1

ip6tables -I INPUT -s ::1 -p tcp --dport 80 -m string --algo bm --string "OPTIONS *" -j DROP

Apache 재기동

이미 생성되어 남아 있는 과도한 httpd 프로세스를 정리하고 초기화
신규 요청부터는 차단 규칙이 적용된 상태로 운영

1

systemctl restart httpd

CPU 사용률 및 Load Average 수 분 내로 정상화

결론

httpd 프로세스 수 안정화, 더 이상 루프백 OPTIONS * 요청 발생하지 않음

추가 조치 방안

문제의 근본 원인을 해결하기 위해서는 Apache 설정 최적화 필요
특히, 현재 서버는 prefork MPM을 사용하고 있으며, 기본 설정값으로 운영중
이로 인해 부하 상황에서 과도한 프로세스 생성 및 dummy connection 폭주 현상이 발생한 것으로 분석됨
mpm 설정 추가
- MaxRequestWorkers를 서버 사양에 맞게 제한

1
2
3
4
5
6
7
8
9


# /etc/httpd/conf.modules.d/00-mpm.conf

<IfModule mpm_prefork_module>
 StartServers 5
 MinSpareServers 5
 MaxSpareServers 10
 MaxRequestWorkers 150
 ServerLimit 150
</IfModule>

GitHub 블로그(Jekyll Chirpy) 오류 TroubleShooting

Sun, 29 Dec 2024 09:00:00 +0900

Jekyll - Chirpy 테마

로컬 테스트 오류

Unable to monitor directories for changes because iNotify max watches exceeded.
Linux의 inotify 파일 시스템 감시자의 최대 수 제한을 초과했기 때문에 발생

1코어 1기가로 실행 중이기 때문에 제한인 것으로 추정
inotify 값 변경해서 해결
1
2
3
cat /proc/sys/fs/inotify/max_user_watches

sudo sysctl fs.inotify.max_user_watches=524288

GitHub Action 의존성 오류

git push 후에 github action에서 발생한 오류

의존성 누락으로 인해 _sass/main.bundle.scss에서 @use ‘vendors/bootstrap’ 참조 불가

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


Error: Can't find stylesheet to import.
 ╷
1 │ @use 'vendors/bootstrap';
 │ ^^^^^^^^^^^^^^^^^^^^^^^^
 ╵
 main.bundle.scss 1:1 @use
 /home/runner/work/joonlog.github.io/joonlog.github.io/assets/css/jekyll-theme-chirpy.scss 1:1 root stylesheet
 Conversion error: Jekyll::Converters::Scss encountered an error while converting 'assets/css/jekyll-theme-chirpy.scss':
 Can't find stylesheet to import.
 ------------------------------------------------
 Jekyll 4.3.4 Please append `--trace` to the `build` command
 for any additional information or backtrace.
 ------------------------------------------------

참고: https://github.com/cotes2020/jekyll-theme-chirpy/discussions/1809

ci 파일에 npm 의존성 주입 추가로 해결 가능
아래 코드를 jekyll.yml의 Build with Jekyll Step 위에 작성

1
2


name: npm build
run: npm install && npm run build

GitHub Action 의존성 오류2

git push 후에 github action에서 발생한 오류

7시간 전까지 정상 동작 했는데 GitHub Action 중 오류

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


...
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE package: '@semantic-release/npm@12.0.1',
npm warn EBADENGINE required: { node: '>=20.8.1' },
npm warn EBADENGINE current: { node: 'v18.20.5', npm: '10.8.2' }
npm warn EBADENGINE }
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE package: '@semantic-release/release-notes-generator@14.0.1',
npm warn EBADENGINE required: { node: '>=20.8.1' },
npm warn EBADENGINE current: { node: 'v18.20.5', npm: '10.8.2' }
npm warn EBADENGINE }
...
[js] [!] Error: Cannot find module '/home/runner/work/joonlog.github.io/joonlog.github.io/node_modules/@jridgewell/gen-mapping/dist/gen-mapping.umd.js'
[js] at createEsmNotFoundErr (node:internal/modules/cjs/loader:1177:15)
[js] at finalizeEsmResolution (node:internal/modules/cjs/loader:1165:15)
[js] at resolveExports (node:internal/modules/cjs/loader:590:14)
[js] at Function.Module._findPath (node:internal/modules/cjs/loader:664:31)
[js] at Function.Module._resolveFilename (node:internal/modules/cjs/loader:1126:27)
[js] at Function.Module._load (node:internal/modules/cjs/loader:981:27)
[js] at Module.require (node:internal/modules/cjs/loader:1231:19)
[js] at require (node:internal/modules/helpers:177:18)
[js] at Object.<anonymous> (/home/runner/work/joonlog.github.io/joonlog.github.io/node_modules/@jridgewell/source-map/dist/source-map.cjs:6:18)
[js] at Module._compile (node:internal/modules/cjs/loader:1364:14)

정상 동작 하던 커밋으로 롤백했는데도 같은 에러 발생 ⇒ GitHub 쪽 버전 문제?

warn 발생하는 node 문제인가 싶어 jekyll.yml에 아래 코드 추가해서 node 22이상으로 사용 후 해결됨 - npm 설치 후 빌드 시 node 20 이상이 필요하게 변경된 것으로 추정 ⇒ 버전 지정 안하면 깃허브는 node를 18버전으로 사용

1
2
3
4


 - name: Setup Node.js
 uses: actions/setup-node@v3
 with:
 node-version: '22.x' # Node 22 이상 사용

GitHub 잔디 누락 TroubleShooting

Fri, 27 Dec 2024 09:00:00 +0900

커밋을 해도 깃허브에 잔디가 보이지 않아서 찾아보니 잔디가 심어지는 것에 조건이 있었다.

github 이메일 계정과 로컬의 이메일 정보가 같아야 한다
branch는 main 혹은 gh-pages 둘 중 하나에서 커밋해야 한다
forked repo가 아니어야 한다

내 경우에는 git config에 이메일이 등록되어 있지 않아서 잔디가 심어지지 않았다.

1
2


git config --global --list
git config --global user.email “<email>”

이메일 추가 후 해결

참고

공식문서: https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile