truthgarnet

CHIP-8 에뮬레이터 만들기(1)

truthgarnet — Wed, 15 Jul 2026 10:35:35 +0900

CHIP-8에 대해 공부하게 된 계기

CHIP-8은 가상 머신에서 실행되는 저수준 명령어 체계입니다. 운영체제를 공부하면서 CPU, 메모리, 레지스터 같은 컴퓨터 구조의 개념을 접하게 되었고, 이를 직접 구현해보며 더 깊게 이해하고 싶어 CHIP-8을 공부하게 되었습니다.

CHIP-8 에뮬레이터라고 부르지만, 실제 하드웨어를 에뮬레이션하는 것이 아니라 CHIP-8 명령어를 해석하고 실행하는 인터프리터를 작성하는 작업에 가깝습니다.

역사

1977년 당시 게임을 개발하는 과정은 매우 어려웠습니다. 게임을 만들기 위해서는 CPU가 직접 이해할 수 있는 복잡한 기계어를 사용해야 했기 때문입니다.

이를 더 쉽게 만들기 위해 RCA의 엔지니어인 조 웨이스베커(Joseph Weisbecker)는 CHIP-8이라는 새로운 실행 환경을 만들었습니다.

여기까지만 들으면 CHIP-8이 프로그래밍 언어라고 생각할 수도 있습니다. 하지만 CHIP-8은 단순한 언어가 아니라 가상의 작은 컴퓨터 시스템입니다.

┌──────────────────┐
│ CHIP-8 │
│ │
│ CPU │
│ 메모리 │
│ 화면 │
│ 키보드 │
└──────────────────┘

실제 컴퓨터에서는 다음과 같은 구조로 동작합니다.

실제 컴퓨터

↓

CHIP-8 인터프리터 실행

↓

그 안에서 CHIP-8 게임 실행

구성 요소

메모리(RAM)

CHIP-8은 총 4096개의 메모리 공간을 가지고 있습니다.

이 메모리에는 다음과 같은 데이터가 저장됩니다.

게임

그림

숫자

즉, 게임 실행에 필요한 모든 정보가 메모리에 저장됩니다.

레지스터

CHIP-8에는 16개의 8비트 범용 레지스터가 존재합니다.

V0

V1

V2

...

VF

각 레지스터는 개발자가 원하는 값을 저장하는 용도로 사용할 수 있습니다.

예를 들어

V0 = 플레이어 X좌표

V1 = 플레이어 Y좌표

V2 = 점수

처럼 사용할 수 있습니다.

프로그램 카운터(PC)

프로그램 카운터(Program Counter)는 현재 실행해야 하는 명령어의 위치를 저장합니다.

예를 들어

PC = 200

이라면 메모리 주소 200에 있는 명령어를 실행한다는 의미입니다.

CHIP-8의 명령어는 항상 2바이트 크기이기 때문에 명령어를 실행한 후 PC는 다음과 같이 증가합니다.

PC = 200 → PC = 202

인덱스 레지스터(I)

인덱스 레지스터 I는 특정 데이터가 저장된 메모리 주소를 가리킬 때 사용합니다.

예를 들어 메모리 0x300부터 그림 데이터가 저장되어 있다고 가정해봅시다.

주소

0x300   11110000

0x301   10010000

0x302   10010000

0x303   11110000

컴퓨터는 그림이 어디에 저장되어 있는지 알아야 화면에 출력할 수 있습니다.

따라서,

I = 0x300

으로 저장하면 I는 그림 데이터가 시작되는 위치를 기억하게 됩니다.

스택

처음에는 CHIP-8에 스택이 왜 필요한지 의문이 들었습니다. 하지만 함수 호출 과정을 이해하면서 스택이 중요한 역할을 한다는 것을 알게 되었습니다.

예를 들어 슈팅 게임의 실행 흐름이 다음과 같다고 가정해봅시다.

게임 시작

플레이어 이동

적 이동

총알 쏘기

점수 계산

다음 프레임

총알을 발사하는 과정에서는 여러 작업이 필요합니다.

총알 위치 정하기

총알 방향 정하기

총알 효과음 재생하기

총알 애니메이션 재생하기

이 작업들을 하나의 함수로 만들어 관리할 수 있습니다.

0x500: ShootBullet()

- 총알 생성
- 위치 설정
- 방향 설정
- 효과음 재생
- 종료

게임을 실행중:

0x200 게임 시작

0x202 플레이어 이동

0x204 적 이동

0x206 ShootBullet() 호출 ← 현재 실행 중

0x208 점수 계산

0x20A 다음 프레임

현재 명령어가 0x206이라면 ShootBullet() 함수가 있는 0x500으로 이동합니다.

하지만 함수 실행이 끝난 후 어디로 돌아가야 하는지 알아야 합니다.

그래서 함수 호출 전에 돌아갈 주소를 스택에 저장합니다.

스택

┌────────┐
│0x208   │
└────────┘

함수가 종료되면 스택에서 0x208을 꺼내 다시 실행을 이어갑니다.

화면

CHIP-8의 화면 크기는 64x32 픽셀입니다.

각 픽셀은 0과 1로 표현되며, 흑백 화면으로 출력됩니다.

키패드

CHIP-8은 16개의 버튼을 가지고 있습니다.

// COSMAC VIP 키패드
1 2 3 C

4 5 6 D

7 8 9 E

A 0 B F

// 최신 PC 키패드
1 2	3	4
Q	W	E	R
A	S	D F
Z	X	C	V

게임에서는 다음과 같이 입력을 확인합니다.

"5번 버튼 눌렸나?"

"A 버튼 눌렸나?"

게임 실행

CHIP-8 인터프리터는 아래 과정을 초당 수백 번 반복합니다.

명령 읽기

↓

무슨 뜻인지 해석

↓

실행

↓

다음 명령

이 과정을 반복하면서 게임이 실행됩니다.

화면에 그림

CHIP-8에서는 그림을 스프라이트(Sprite)라는 작은 데이터 형태로 저장합니다.

예를 들어:

11110000

10010000

10010000

11110000

이라는 데이터가 있다면 화면에는 다음과 같이 출력됩니다.

■■■■

■□□■

■□□■

■■■■

이처럼 작은 픽셀 데이터 조합을 이용해 캐릭터와 게임 요소를 표현합니다.

Trust anchor for certification path not found, 원인은 인증서 순서였습니다

truthgarnet — Sat, 11 Jul 2026 10:59:12 +0900

문제 분석

앱에서 로그인이 실패한다는 문의를 받았습니다.

앱의 로그를 확인해 보니 다음과 같은 오류가 발생하고 있었습니다.

javax.net.ssl.SSLHandshakeException:
java.security.cert.CertPathValidatorException:
Trust anchor for certification path not found.

SSL Handshake 과정에서 인증서 검증에 실패한 것입니다.

조금 더 아래의 로그를 살펴보면 다음과 같은 원인도 함께 확인할 수 있었습니다.

Flattened final assist data: 4868 bytes, containing 1 windows, 16 views
2026-07-08 17:33:46.768 25909-26119 ==========...==========          E  ================HttpConnect=====================
2026-07-08 17:33:50.033 25909-26114 nkiosk.app.tes                   W  Accessing hidden method Ljava/lang/invoke/MethodHandles$Lookup;-><init>(Ljava/lang/Class;I)V (light greylist, reflection)
2026-07-08 17:33:50.125 25909-26114 System.err                       W  **javax.net.ssl.SSLHandshakeException: java.security.cert.CertPathValidatorException: Trust anchor for certification path not found.**

2026-07-08 17:33:50.129 25909-26114 System.err                       W  **Caused by: java.security.cert.CertificateException: java.security.cert.CertPathValidatorException: Trust anchor for certification path not found.**
2026-07-08 17:33:50.129 25909-26114 System.err                       W     at com.android.org.conscrypt.TrustManagerImpl.checkTrustedRecursive(TrustManagerImpl.java:646)
2026-07-08 17:33:50.129 25909-26114 System.err                       W     at com.android.org.conscrypt.TrustManagerImpl.checkTrusted(TrustManagerImpl.java:495)
2026-07-08 17:33:50.129 25909-26114 System.err                       W     at com.android.org.conscrypt.TrustManagerImpl.checkTrusted(TrustManagerImpl.java:418)
2026-07-08 17:33:50.129 25909-26114 System.err                       W     at com.android.org.conscrypt.TrustManagerImpl.getTrustedChainForServer(TrustManagerImpl.java:339)
2026-07-08 17:33:50.129 25909-26114 System.err                       W     at android.security.net.config.NetworkSecurityTrustManager.checkServerTrusted(NetworkSecurityTrustManager.java:94)
2026-07-08 17:33:50.130 25909-26114 System.err                       W     at android.security.net.config.RootTrustManager.checkServerTrusted(RootTrustManager.java:88)
2026-07-08 17:33:50.130 25909-26114 System.err                       W     at com.android.org.conscrypt.Platform.checkServerTrusted(Platform.java:208)
2026-07-08 17:33:50.130 25909-26114 System.err                       W     at com.android.org.conscrypt.ConscryptFileDescriptorSocket.verifyCertificateChain(ConscryptFileDescriptorSocket.java:404)
2026-07-08 17:33:50.130 25909-26114 System.err                       W     at com.android.org.conscrypt.NativeCrypto.SSL_do_handshake(Native Method)
2026-07-08 17:33:50.130 25909-26114 System.err                       W     at com.android.org.conscrypt.NativeSsl.doHandshake(NativeSsl.java:375)
2026-07-08 17:33:50.130 25909-26114 System.err                       W     at com.android.org.conscrypt.ConscryptFileDescriptorSocket.startHandshake(ConscryptFileDescriptorSocket.java:224)
2026-07-08 17:33:50.130 25909-26114 System.err                       W     ... 30 more
2026-07-08 17:33:50.131 25909-26114 System.err                       W  **Caused by: java.security.cert.CertPathValidatorException: Trust anchor for certification path not found.**
2026-07-08 17:33:50.131 25909-26114 System.err                       W     ... 41 more
2026-07-08 17:33:50.194 25909-25909 kr.co.sol....SOL_Logger          E  [[LoginActivity]] 로그인 페이지 - 로그인 실패 , result = null
2026-07-08 17:33:50.202 25909-25909 System.err                       W  java.lang.Exception: 사용자 네트워크 연결이 불안정 하거나
2026-07-08 17:33:50.202 25909-25909 System.err                       W  인터넷 서비스 문제 일 수 있습니다.
2026-07-08 17:33:50.202 25909-25909 System.err                       W  인터넷 연결 확인 후 다시 시도해주세요.
2026-07-08 17:33:50.203 25909-25909 System.err                       W     at $4$1.success(LoginActivity.java:189)
2026-07-08 17:33:50.203 25909-25909 System.err                       W     at $8.completedConnection(ApiRequest.java:425)
2026-07-08 17:33:50.203 25909-25909 System.err                       W     at com.w.base.lib.socket.ConnectionManager$ConnectionProcess.onPostExecute(ConnectionManager.java:284)
2026-07-08 17:33:50.203 25909-25909 System.err                       W     at com.w.base.lib.socket.ConnectionManager$ConnectionProcess.onPostExecute(ConnectionManager.java:91)
2026-07-08 17:33:50.204 25909-25909 System.err                       W     at android.os.AsyncTask.finish(AsyncTask.java:695)
2026-07-08 17:33:50.204 25909-25909 System.err                       W     at android.os.AsyncTask.access$600(AsyncTask.java:180)
2026-07-08 17:33:50.204 25909-25909 System.err                       W     at android.os.AsyncTask$InternalHandler.handleMessage(AsyncTask.java:712)
2026-07-08 17:33:50.204 25909-25909 System.err                       W     at android.os.Handler.dispatchMessage(Handler.java:106)
2026-07-08 17:33:50.204 25909-25909 System.err                       W     at android.os.Looper.loop(Looper.java:193)
2026-07-08 17:33:50.204 25909-25909 System.err                       W     at android.app.ActivityThread.main(ActivityThread.java:6718)
2026-07-08 17:33:50.204 25909-25909 System.err                       W     at java.lang.reflect.Method.invoke(Native Method)
2026-07-08 17:33:50.205 25909-25909 System.err                       W     at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:493)
2026-07-08 17:33:50.205 25909-25909 System.err                       W     at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:858)
2026-07-08 17:33:50.213 25909-25909 kr.co.sol....SOL_Logger          E  [[LoginActivity]] 사용자 네트워크 연결이 불안정 하거나

**Trust anchor for certification path not found.**는 인증서 체인을 따라 최종적으로 신뢰할 수 있는 루트 인증기관(Root CA)까지 도달하지 못했다는 의미입니다.

즉, 클라이언트 입장에서는 이 서버가 정말 신뢰할 수 있는 기관에서 발급받은 인증서인지 끝까지 증명하지 못했다 라고 판단한 것입니다.

문제가 발생하기 전, SSL 인증서를 새롭게 발급하여 서버에 적용했던 것이 떠올랐습니다. 혹시 인증서 교체 과정에서 문제가 발생했던 것은 아닌지 웹 호스팅 업체에 문의를 진행했습니다.

서버에 등록된 SSL 인증서 체인의 순서가 올바르지 않은 것 같다

라고 답변이 와 우선 기존 인증서로 원복을 진행했고, 이후 로그인 다시 정상적으로 동작했습니다.

하지만, 한 가지 의문이 생겼습니다.

인증서 순서가 정말 이렇게까지 중요한 걸까?

제가 인증서를 적용했을 때는 인증서 순서와 상관없이 적용이 되었던 것을 기억했습니다. 그렇다면 무슨 차이가 있길래 또 인증서 순서가 왜 중요한지에 대해 알기 위해 다시 공부해 보기로 했습니다.

SSL 인증서는 어떻게 신뢰를 증명할까?

SSL 인증서의 구조를 이해하기 위해서는 인증기관(CA)이 왜 여러 단계로 나누어져 있는지부터 알아야합니다.

저희가 해외여행을 간다고 생각 해봅시다.

입국 심사관들은 “대한민국은 입국 허가할 정도로 믿을 만한 나라다.”는 사실을 미리 알고 있습니다.

이것이 Root CA 입니다.

하지만, 각 정부에서 직접 국민 한 명씩에게 여권을 발급하기 어렵습니다.

그래서 정부는 “이 관청은 대한민국이라는 이름으로 여권을 발급할 권한이 있다”라는 위임장을 각 구청과 영사관에 줍니다. 이 **위임장이 중간 인증서(Intermediate CA)**입니다.

실제로 국민들이 받는 여권은 이 구청이나 영사관에서 발급합니다.

이 여권이 서버 인증서(Server Certificate) 입니다.

이렇게 계층을 나누는 이유도 있습니다.

만약 어느 구청의 위임장이 도난 당하더라도 그 구청의 위임장만 취소하면 됩니다.

정부 본청의 도장(Root CA)은 안전하게 남습니다.

실제 SSL 인증서도 같은 이유로 Root CA가 Intermediate CA를 발급하고, Intermediate CA가 다시 Server Certificate를 발급하는 계층 구조를 사용합니다.

인증서는 어떻게 검증될까?

여권에는 이런 내용이 적혀 있습니다.

“이 여권은 강남구청에서 발급했습니다.”

하지만 입국 심사관은 강남구청을 모릅니다.

심사관이 신뢰하는 건 오직 대한민국 정부뿐입니다.

그래서 당신은 여권 뿐만 아니라 강남구청이 정부로부터 권한을 위임 받았다는 위임장(중간 인증서)까지 함께 제출해야 합니다.

그러면 심사관은 다음과 같이 확인합니다.

여권 확인
↓
강남구청이 발급했네
↓
강남구청 위임장을 확인
↓
대한민국 정부가 서명했네
↓
대한민국 정부는 내가 이미 가지고 있는 신뢰 목록(Trust Store)에 있어
↓
통과

이 과정은 인증서 체인(Certificate Chain) 검증이라고 합니다.

중간 인증서가 없다면?

만약 여권만 제출하고 위임장을 빠뜨리면 어떤 일이 발생할까요?

심사관은 이렇게 생각할 것입니다.

강남구청? 진짜 권한이 있는 기관인지 내가 어떻게 알아?

연결고리(chain)가 끊어져 입국 거부가 됩니다.

이는 불완전한 인증서 체인(Incomplete Certificate Chain)입니다.

이때 다음과 같은 오류를 자주 볼 수 있습니다.

"Certificate chain incomplete"
"Unable to verify the first certificate"
"Certificate not trusted"
"SSL certificate problem: unable to get local issuer certificate"

즉, 서버 인증서만 전달하고 중간 인증서를 전달하지 않으면 클라이언트는 루트 인증기관까지 연결되는 체인을 만들 수 없기 때문에 인증서를 신뢰하지 못하게 됩니다.

그렇다면 인증서 순서는 왜 중요할까?

심사관은 다음 순서로 확인 합니다.

여권
↓
위임장
↓
정부

그런데,

위임장
↓
여권

순으로 제출하게 되면 어떻게 될까요?

유능한 심사관(관대한 클라이언트)이라면, 서류가 뒤섞여 있어도 알아서 정리해서 읽어줍니다.

실제로 최신 브라우저나 OpenSSL, 일부 Android 환경은 인증서를 재조합하여 올바른 체인을 찾아주는 경우가 있습니다.

하지만, 원칙대로 검증하는 심사관(엄격한 클라이언트)은 순서가 올바르지 않으면 반려할 수도 있습니다.

일부 오래된 Android나 Java환경은 서버가 전달한 인증서 순서를 그대로 검증하기 때문에 체인 순서가 올바르지 않으면 인증서를 신뢰하지 못하는 경우가 있습니다.

그래서 대부분의 서버는 다음 순서대로 인증서를 구성하는 것이 권장됩니다.

Server Certificate
↓
Intermediate Certificate
↓
(Root CA는 일반적으로 포함하지 않음)

오래된 기기에서는 왜 더 자주 발생할까?

가끔 오래된 공항은 최신 정부 목록을 가지고 있지 않습니다.

새롭게 신뢰받기 시작한 정부가 있다면 그 정부를 아직 모를 수도 있죠.

그래서 구청은

새로운 정부의 위임장뿐만 아니라, 오래전부터 모두가 신뢰하던 정부의 보증도 함께 받아 둡니다.

최신 공항은 새로운 정부를 보고 통과시키고,

오래된 공항은 예전 정부를 보고 통과시킵니다.

SSL에서는 이러한 방식을 교차 서명(Cross Signing)이라고 합니다.

덕분에 오래된 운영체제나 브라우저에서도 동일한 인증서를 계속 사용할 수 있습니다.

이번 장애를 통해 배운 점

이번 일을 겪으면서 인증서는 단순히 “발급만 받으면 끝”인 것이 아니라는 사실을 다시 한번 느끼게 되었습니다.

인증서 자체가 정상이라 하더라도 인증서 체인이 올바르게 구성되어 있는지, 중간 인증서가 함께 전달되는지, 체인의 순서가 적절한지에 따라 일부 환경에서는 SSLHandshake가 실패할 수 있습니다.

또, 모든 클라이언트가 동일한 방식으로 인증서를 검증하는 것은 아니었습니다.

앞으로 비슷한 오류를 만나게 된다면 인증서 자체만 확인하는 것이 아니라 인증서 체인과 전달 순서까지 함께 점검해야 한다는 것을 이번 장애를 통해 배울 수 있었습니다.

Windows 환경에서 클로드 작업 알림 설정(Hook연동)

truthgarnet — Tue, 7 Jul 2026 21:49:34 +0900

Claude Code로 긴 작업을 실행해 두고 다른 일을 하다 보면 작업이 끝난 것을 놓치는 경우가 종종 있습니다. 특히 AI가 사용자의 입력을 기다리거나 작업을 완료했는데도 한참 뒤에 확인하게 되는 경우가 생기곤 합니다.

저는 Windows의 Toast Notification을 이용해 Claude Code가 작업을 완료하거나 제 응답을 기다리는 순간 알림을 받을 수 있도록 설정했습니다.

이번 글에서는 BurntToast 모듈을 이용해 Windows 알림을 생성하는 방법과, Claude Code의 Hook 기능과 연동하여 작업 완료 및 사용자 입력 요청 시 알림을 표시하는 방법을 정리해 보겠습니다.

BurnToast 설치

BurntToast는 PowerShell에서 Windows Toast Notification을 쉽게 생성할 수 있도록 만들어진 모듈입니다.

Windows 10과 Windows Server 2019 이상에서 사용할 수 있습니다.

https://github.com/Windos/BurntToast

GitHub - Windos/BurntToast: Module for creating and displaying Toast Notifications on Microsoft Windows 10.

Module for creating and displaying Toast Notifications on Microsoft Windows 10. - Windos/BurntToast

github.com

PowerShell 사용해서 설치

Install-Module -Name BurntToast -Force

Chocolatey 사용해서 설치

choco install burnttoast-psmodule

기본 명령어

BurntToast의 모든 알림은 New-BurntToastNotification 명령으로 생성합니다.

가장 간단한 예시는 다음과 같습니다.

버튼 추가하기

Toast Notification에는 버튼도 추가할 수 있습니다.

예를 들어 블로그로 이동하는 버튼을 만들어 보겠습니다.

$MyBlog = New-BTButton -Content "Go to MyBlog" -Arguments "<https://truthgarnet.tistory.com/>"

New-BurntToastNotification `
    -Text "제 블로그에 환영합니다." `
    -Button $MyBlog

로고 변경하기

기본 아이콘 대신 원하는 이미지를 사용할 수도 있습니다.

-AppLogo 옵션에 이미지 경로를 지정하면 됩니다.

Import-Module BurntToast

New-BurntToastNotification `
    -Text "ClaudeCode", "정신차려 이 각박한 세상 속에서" `
    -Sound Default `
    -AppLogo "C:\Desktop\HybridSamySosaRioLaby.png"

사운드 추가

New-BurntToastNotification -Text 'Cookies are done' -SnoozeAndDismiss -Sound alarm

위의 명령어 말고도 지원하는 다양한 기능은 공식 문서를 참고하면 됩니다.
https://github.com/Windos/BurntToast/blob/main/Help/New-BurntToastNotification.md

BurntToast/Help/New-BurntToastNotification.md at main · Windos/BurntToast

Module for creating and displaying Toast Notifications on Microsoft Windows 10. - Windos/BurntToast

github.com

자주 발생하는 오류

BurntToast를 처음 설치하면 다음과 같은 오류를 만날 수 있습니다.

Import-Module : 이 시스템에서 스크립트를 실행할 수 없으므로 ...

또는

New-BurntToastNotification :
명령을 찾을 수 없습니다.

New-BurntToastNotification : 'New-BurntToastNotification' 명령이 'BurntToast' 모듈에 있지만 모듈을 로드할 수 없습니다.

대부분 PowerShell Execution Policy 때문에 발생하는 문제입니다.

해결 방법

현재 PowerShell 세션에서만 허용

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

현재 사용자만 변경

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

설정을 변경한 뒤 다시 Import-Module BurntToast를 실행하면 정상적으로 동작합니다.

Claude Code Hook에 적용

BurntToast의 기본적인 사용법을 확인했으니, Claude Code의 Hook 기능과 함께 사용해볼 차례입니다.

저는 다음 두 가지 이벤트에 알림을 연결했습니다.

Stop : Claude가 작업을 완료했을 때
PermissionRequest : Claude가 사용자 입력을 기다릴 때

Cluade Code에서 /hooks 을 선택해서 Hooks Stop Hook 메뉴를 열면 다음과 같은 화면이 등장합니다.

그 중에서 Stop Hook을 찾아서 선택하면, 다음과 같은 안내가 표시됩니다.

To modify or remove this hook, edit settings.json directly...

Claude에게 수정하도록 요청할 수도 있지만, 저는 직접 .vscode/settings.json을 수정했습니다.

Command를 아래와 같이 변경하면 됩니다.

"command": "powershell -ExecutionPolicy RemoteSigned -Command \"Import-Module BurntToast; New-BurntToastNotification -Text '{Title}', '{Contnet}' -Sound Default -Sound Default -AppLogo '{이미지절대경로}'\""

이제 아래와 같이 Claude Code의 작업이 끝날 때마다 Windows 알림이 표시됩니다.

PermissionRequest도 Stop과 같은 방식으로 설정할 수 있습니다.

PermissionRequest에서 사용할 수 있는 주요 필드는 다음과 같습니다.

필드	설명
behavior	"allow"는 권한을 부여, "deny"는 거부
updatedInput	"allow"에만 해당: 실행 전에 도구의 입력 매개변수를 수정
updatedPermissions	"allow"에만 해당: 권한 규칙 업데이트를 적용, 사용자가 "항상 허용" 옵션을 선택하는 것과 동일
message	"deny"에만 해당: Claude에게 권한이 거부된 이유를 알려줌
interrupt	"deny"에만 해당: true이면 Claude를 중지

Stop과 설정하준 것과 같이 /hooks를 통해 들어가서 PermissionRequest를 찾아줍니다.

원하는 Command를 .vscode/settings.json에 입력하면 제가 좋아하는 캐릭터가 등장해 "Choose your life"라는 메세지를 띄어주게 됩니다.

마무리

BurntToast는 단순히 Windows 알림을 띄우는 모듈이지만, Claude Code의 Hook 기능과 함께 사용하면 활용도가 훨씬 높아집니다.

특히 AI에게 긴 작업을 맡겨두는 경우라면 작업 완료나 사용자 입력 요청을 즉시 확인할 수 있어 생산성이 크게 좋아집니다.

Windows 환경에서 Claude Code를 사용하고 있다면 한 번쯤 설정해 보는 것을 추천합니다.

서버 오류(Too many connections)

truthgarnet — Thu, 4 Jun 2026 12:55:22 +0900

MYSQL Too many connections 문제 발생

임시 대처로 Sleep을 삭제하는 스케쥴러 적용

해결과정

서버의 트래픽과 로그를 살펴봄
로그를 살펴본 결과 Too many connections 발생

현재 connections의 수가 570 ~590으로 윗돌고 있음
SLEEP되는 connections가 540개 정도 존재many connections의 문제로 그렇다면 DB connection이지 않을 까 생각해서 총 연결할 수 있는 수를 검색, 현재 connections되고 있는 것을 검색

처리

임시로 DB에서 직접 명령어를 통해 SLEEP를 삭제
-- 현재 DB 프로세스 전체 조회 SELECT count(*) FROM information_schema.processlist -- KILL이 붙여진 프로세스 조회 SELECT CONCAT('KILL ', id, ';') FROM information_schema.processlist WHERE command='Sleep';
root 계정이 없는 관계로 cron을 통해서 cron -e 1시간 마다 10분이상이 된 SLEEP들을 삭제하는 방법으로 적용

0 0 * * * mysql -u user -pPW -N -e "SELECT CONCAT('KILL ',id,';') FROM information_schema.processlist WHERE command='Sleep' AND time > 600 AND user='appuser';" | mysql -u user -pPW

MySQL Too Many Connections 문제와 DBCP(Database Connection Pool)

truthgarnet — Thu, 4 Jun 2026 12:51:14 +0900

문제 상황

회사에서 MySQL의 Too many connections 문제가 발생했다.

확인해 보니 MySQL 내부에 Sleep 상태의 connection이 과도하게 쌓여 있었고,

결국 DB가 허용 가능한 최대 connection 수를 초과하면서 장애가 발생한 것으로 보였다.

그렇다면 왜 이런 문제가 발생할까?

이를 이해하려면 먼저 DB Connection이 무엇인지, 그리고 DBCP(Database Connection Pool) 이 왜 필요한지를 이해해야 한다.

DB Connection이란?

애플리케이션과 DB 서버는 네트워크를 통해 통신한다.

예를 들어:

애플리케이션이 SQL 요청 전송
DB 서버가 SQL 실행
결과 응답 반환

이 과정을 반복하게 된다.

이때 MySQL은 TCP 기반으로 동작한다.

즉, 애플리케이션과 DB 서버는 단순히 데이터를 보내는 것이 아니라 TCP Connection 을 맺고 통신한다.

DB Connection 생성 비용

TCP는 연결 지향 프로토콜이다.

따라서 통신 전에 반드시 연결 과정이 필요하다.

연결 생성: 3-Way Handshake

TCP 연결 시:

SYN
SYN + ACK
ACK

과정을 거쳐 연결이 생성된다.

이를 3-Way Handshake라고 한다.

연결 종료: 4-Way Handshake

연결 종료 시에는:

과정을 거친다.

이를 4-Way Handshake라고 한다.

문제점

만약 SQL 요청마다:

TCP 연결 생성
SQL 실행
TCP 연결 종료

를 반복한다면 어떻게 될까?

매 요청마다 Handshake 비용이 발생하게 되고,

트래픽이 많아질수록 성능 저하가 커지게 된다.

즉, DB 작업 자체보다도 connection 생성/종료 비용이 무시할 수 없게 된다.

DBCP(Database Connection Pool)

이 문제를 해결하기 위해 등장한 것이 DBCP(Database Connection Pool)이다.

DBCP는 애플리케이션이 시작될 때 미리 여러 개의 DB Connection을 생성해 두고, 이를 Pool에 보관하여 재사용하는 방식이다.

즉:

요청 발생
→ Pool에서 Connection 가져오기
→ SQL 실행
→ Connection 반환

형태로 동작한다.

핵심은 매번 새로운 TCP 연결을 만드는 것이 아니라, 기존 connection을 재사용한다는 점이다.

Connection close()의 진짜 의미

여기서 중요한 점이 있다.

DBCP 환경에서 connection.close()는 실제 TCP 연결 종료가 아니다.

실제로는:

Pool에 Connection 반환(return)

의 의미를 가진다.

즉:

close() 호출 → Pool로 반환
실제 TCP 연결 유지 → 다음 요청에서 재사용

이 된다.

반환하지 않으면 발생하는 문제

만약 application에서:

connection 반환 누락
예외 발생 후 close() 미호출
비정상 종료

등이 발생하면 어떻게 될까?

Pool의 connection이 계속 점유된 상태로 남게 된다.

그러면:

새로운 요청
→ Pool에 사용 가능한 Connection 없음
→ 새로운 Connection 생성 시도
→ MySQL max_connections 초과
→ Too many connections 발생

문제가 발생할 수 있다.

Sleep 상태가 많으면 무조건 문제일까?

반드시 그렇지는 않다.

MySQL에서 Sleep 상태는 일반적으로:

현재 쿼리를 수행하지 않고 대기 중인 idle connection

을 의미한다.

DBCP는 재사용을 위해 idle connection을 유지하기 때문에,

일정 수준의 Sleep connection은 정상이다.

다만 아래 상황에서는 문제가 된다.

connection 반환 누락
pool 크기 과다 설정
트래픽 급증
장시간 idle connection 유지

이런 상황이 겹치면 Sleep connection이 비정상적으로 증가하게 된다.

MySQL 주요 설정

max_connections

MySQL이 동시에 허용할 수 있는 최대 connection 수이다.

예를 들어:

max_connections = 600

이라면 최대 100개의 client 연결만 허용한다.

실제 운영 상황 예시

A 서버만 있을 때

A 서버
→ Connection 100개 사용

문제 없음.

B 서버 증설

트래픽 증가로 인해 서버를 추가했다고 가정하자.

A 서버 → 100개 사용
B 서버 → 추가 요청 발생

하지만 이미 MySQL의 최대 connection 수가 가득 찬 상태라면:

Too many connections

오류가 발생하게 된다.

즉, 서버를 늘려도 DB의 connection 제한은 그대로이기 때문에 병목이 발생할 수 있다.

wait_timeout

wait_timeout은 일정 시간 동안 아무 요청이 없는 idle connection(Sleep 상태)을 MySQL이 언제 끊을지를 결정하는 값이다.

예를 들어:

wait_timeout=60

이라면 60초 동안 사용되지 않은 connection은 MySQL이 종료한다.

주의할 점

만약 DBCP가 connection을 계속 재사용하려고 하는데,

MySQL이 먼저 connection을 끊어버리면 어떻게 될까?

예를 들어:

59초 동안 idle
→ 갑자기 요청 발생
→ DB는 이미 60초 시점에 connection 종료
→ application 사용 시 exception 발생

문제가 발생할 수 있다.

DBCP 주요 설정

(HikariCP 기준)

minimumIdle

Pool에서 유지할 최소 idle connection 수

즉:

항상 최소 몇 개는 대기 상태로 유지할 것인가

를 의미한다.

maximumPoolSize

Pool이 가질 수 있는 최대 connection 수

여기에는:

idle
active

모두 포함된다.

즉:

idle + active <= maximumPoolSize

이다.

maximumPoolSize를 크게 하면 좋은 걸까?

반드시 그렇지는 않다.

connection 수가 너무 많아지면:

DB Thread 증가
Context Switching 증가
Lock 경합 증가
메모리 사용량 증가

문제가 발생할 수 있다.

즉, 무조건 크게 설정하는 것이 아니라 적절한 값을 찾는 것이 중요하다.

minimumIdle과 maximumPoolSize

일반적으로:

minimumIdle = maximumPoolSize

형태를 많이 권장한다.

트래픽 변화에 따라 connection을 생성/삭제하는 비용을 줄일 수 있기 때문이다.

다만 시스템 특성에 따라 다르게 설정하기도 한다.

maxLifetime

Pool에서 connection을 재사용할 수 있는 최대 시간

중요한 점은:

DB가 connection을 끊기 전에
Pool이 먼저 안전하게 교체

하도록 설정하는 것이다.

따라서 일반적으로:

maxLifetime < wait_timeout

으로 설정한다.

connectionTimeout

Pool에서 connection을 얻기 위해 기다리는 최대 시간

예를 들어:

connectionTimeout = 3000ms

이라면:

3초 동안 connection 획득 대기
실패 시 exception 발생

한다.

적절한 Connection 수 찾기

정답은 없다.

결국 시스템 부하 테스트와 모니터링을 통해 찾는 수밖에 없다.

일반적인 튜닝 방법

1. 모니터링 환경 구축

확인해야 할 것:

DB CPU
DB Memory
서버 Thread 수
DBCP 상태
Active / Idle Connection 수

2. 부하 테스트 진행

예:

nGrinder
JMeter

등을 사용한다.

3. 핵심 지표 확인

대표적으로:

TPS
RPS(Request Per Second)
평균 응답 시간(avg response time)

등을 확인한다.

4. 병목 지점 확인

Connection 수를 늘렸을 때:

DB CPU 급증
응답 시간 증가
lock 증가

등이 발생하는지 확인해야 한다.

참고

3-way handshake

SYN 전송: Client -> Server 연갈하고 싶어요
SYN + ACK 전송: Server -> Client 요청 잘 받았고, 나도 연결 가능해요
ACK 전송: 좋아요, 이제 연결합시다

4-way handshake

FIN 전송: Clinet -> Server 난 이제 보낼 거 없습니다.
ACK 전송: Server -> Client 알겠어요
FIN 전송: SERVER -> CLIEN 나도 이제 끝났습니다.
ACK 전송: Clinet -> Server 확인했습니다 연결 종료

Android AGP 버전 업그레이드

truthgarnet — Wed, 25 Mar 2026 16:08:51 +0900

개요

전임자가 개발해둔 앱을 인수인계받았는데, 처음부터 쉽지 않았다.
라이브러리 버전과 자바 버전이 너무 낮아서 아예 실행조차 되지 않았다.

자바와 Gradle 버전을 하나씩 맞춰가며 겨우 앱을 실행시키는 데 성공했다.
이제 배포만 하면 끝이라고 생각했는데, 구글 콘솔에 업로드하는 순간 또 다른 문제가 발생했다.

바로 ‘16KB 페이지 크기’ 제한 때문이었다.

안드로이드 개발이 처음이었던 나에게는 이 개념 자체가 생소했고, 무엇이 문제인지조차 바로 이해하기 어려워 결국 관련 개념부터 다시 공부하기 시작했고, 이 과정에서 안드로이드 빌드와 배포에 대해 조금 더 깊이 이해하게 되었다.

이 내용은 따로 정리해서 다음 글에서 자세히 다뤄볼 예정이다.

버전 업그레이드 단계 요약

단계	AGP 버전	Gradle 버전	핵심 변경사항
1단계	4.x → 7.x	6.5 → 7.5	jcenter 제거, support → androidx 전환
2단계	7.x → 8.0	7.5 → 8.0	namespace 필수화, buildFeatures 추가, flavorDimensions 문법 변경
3단계	8.0 → 8.5	8.0 → 8.7	16KB 정렬 패키징 설정 (useLegacyPackaging = false)
4단계	라이브러리	CameraX 1.3.4 / ML Kit 16.0.1	16KB 지원, API 23 이상 요구

1. 업그레이드 이유

OCR(인쇄물, 필기체, 이미지 내 텍스트를 디지털 텍스트로 변환하는 기술) 기능을 도입하기 위해 Google ML Kit를 사용하려 했으나, 당시 사용 중이던 AGP(Android Gradle Plugin) 버전에서는 16KB 패키지를 지원하는 ML Kit 최신 버전을 적용할 수 없었다.

결국 OCR 기능을 제대로 사용하기 위해서는 AGP를 전반적으로 업데이트해야 했고, 이에 맞춰 ML Kit 또한 최신 버전으로 함께 업그레이드하는 작업이 필요했다.

2. 최종 목표

ML Kit 최신 버전 도입을 통해 Google 콘솔에 업로드 가능한 상태로 전환했다.

ML Kit 최신 버전 → Android API 23 이상 필요Android API 23 이상 → Java 17 이상 필요Java 17 이상 → AGP 8.x 이상 필요 ∴ AGP 4.x → 8.5 업그레이드가 선행 조건

단계별 업그레이드 경로

• AGP 4.x → 7.x : jcenter 종료, support → androidx 전환

• AGP 7.x → 8.0 : compileSdkVersion 문법 변경, flavorDimensions 문법 변경, namespace 필수화

• AGP 8.0 → 8.5 : packaging.jniLibs.useLegacyPackaging = false 설정 (16KB 정렬 패키징)

3. 현재 환경 (업그레이드 전)

• AGP 버전: 4.x

• Gradle 버전: 6.5

• Java 버전: 8 (VERSION_1_8)

• compileSdkVersion: 30

• minSdkVersion: 22

4. 환경설정 — Android Studio Koala 설치

Android Studio Koala는 구버전으로 공식 사이트 다운로드 페이지에서는 직접 받을 수 없어 아래 방법으로 다운로드 필요하다.

이전 버전 확인

JetBrains IntelliJ Platform Plugin SDK 문서에서 버전 목록 확인: https://plugins.jetbrains.com/docs/intellij/android-studio-releases-list.html

직접 다운로드 (Google CDN)

아래 URL 패턴으로 특정 버전을 직접 다운로드할 수 있다.

https://redirector.gvt1.com/edgedl/android/studio/install/{버전}/android-studio-{버전}-windows.exe
 
// 예시
https://redirector.gvt1.com/edgedl/android/studio/install/2024.1.2.13/android-studio-2024.1.2.13-windows.exe

5. 작업 과정

Step 1. AGP 4.x → AGP 7.x

주요 변경사항

• jcenter() 저장소 제거 → mavenCentral() 사용

• com.android.support.* → androidx.* 라이브러리 전환

• compileSdkVersion 30 → 35 상향

• targetSdkVersion 30 → 35 상향

build.gradle (루트)

buildscript {
    repositories {
        google()
        mavenCentral()
        // jcenter() 제거 완료 (2021년 서비스 종료)
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:7.4.2'
    }
}
 
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
        maven { url 'https://dl.bintray.com/raphaelbussa/maven' }

    }
}

gradle-wrapper.properties

distributionUrl=https\://services.gradle.org/distributions/gradle-7.5-all.zip

lib-build.gradle (라이브러리 모듈)

android {
    compileSdkVersion 35  // 30 → 35 상향
 
    defaultConfig {
        minSdkVersion 23  //  22 → 23 (ML Kit 최신 버전 요구사항)
        targetSdkVersion 35
    }
 
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
        // ※ Java 버전은 Step 2에서 17로 상향
    }
}
 
dependencies {
    //  com.android.support.* → androidx.* 전환 완료
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
    implementation 'androidx.cardview:cardview:1.0.0'
    implementation 'androidx.multidex:multidex:2.0.1'
 
    implementation 'com.squareup.okhttp3:okhttp:3.2.0'
    implementation 'com.google.code.gson:gson:2.8.7'
    implementation 'com.auth0.android:jwtdecode:2.0.0'
    implementation 'com.github.bumptech.glide:glide:4.9.0'
    implementation 'org.apache.commons:commons-lang3:3.12.0'
 
    implementation project(path: ':lib_converter')
    implementation project(path: ':lib_http')
 
    constraints.implementation 'androidx.fragment:fragment:1.3.6'
 
    implementation files('libs\\nfcmodule.jar')
    implementation files('libs\\spots-dialog-1.1.aar')
}

Step 2. AGP 7.x → AGP 8.0

주요 변경사항

• namespace 각 모듈에 명시적 선언 필수

• buildFeatures 블록으로 BuildConfig 등 명시적 활성화 필요

• flavorDimensions 문법 변경: flavorDimensions "default" → flavorDimensions = ["default"]

• Java 17로 버전 상향

build.gradle (루트)

buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:8.0.0"
    }
}

gradle-wrapper.properties

distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-all.zip

각 모듈 build.gradle — namespace 및 buildFeatures 추가

android {
    //  AGP 8.0 필수: namespace 명시적 선언
    namespace "com.example.yourmodule"  // 실제 패키지명으로 교체
 
    compileSdk 35
 
    defaultConfig {
        minSdk 23
        targetSdk 35
    }
 
    //  Java 17로 상향 (API 23 이상 요구사항)
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
 
    //  AGP 8.0 필수: BuildConfig 등 부가 기능 명시적 활성화
    buildFeatures {
        buildConfig true    // BuildConfig 클래스 생성 여부
        // viewBinding true  // ViewBinding 사용 시 추가
        // dataBinding true  // DataBinding 사용 시 추가
    }
 
    //  AGP 8.0 문법 변경: 배열 형식으로 선언
    flavorDimensions = ["default"]
}

namespace 적용 대상 모듈   :app 모듈
→ BuildConfig 생성  :lib_base 모듈
→ BuildConfig 생성  :lib_http 모듈
→ BuildConfig 생성 모든 모듈에 개별 namespace를 반드시 선언해야 합니다.

Step 3. AGP 8.0 → AGP 8.5

주요 변경사항

• 16KB 페이지 정렬 지원을 위한 JNI 라이브러리 패키징 설정

build.gradle (루트)

buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:8.5.1"
    }
}
 
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
        maven { url 'https://dl.bintray.com/raphaelbussa/maven' }

    }
 
    // Kotlin 1.8+에서 stdlib-jdk7/jdk8이 stdlib에 통합됨
    //    → 중복 클래스 충돌 방지를 위해 버전 강제 통일
    configurations.all {
        resolutionStrategy.eachDependency { details ->
            if (details.requested.group == 'org.jetbrains.kotlin') {
                details.useVersion '1.8.22'
            }
        }
    }
}

gradle-wrapper.properties

distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-all.zip

앱 모듈 build.gradle — 16KB 패키징 설정

android {
    namespace "com.example.app"
    compileSdk 35
 
    defaultConfig {
        minSdk 23
        targetSdk 35
    }
 
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
 
    //  AGP 8.5: 16KB 페이지 정렬 패키징 설정
    //    압축하지 않은 상태로 APK에 포함하되, 16KB 정렬을 유지하는 방식
    packaging {
        jniLibs {
            useLegacyPackaging = false
        }
    }
}

Step 4. CameraX + ML Kit 업그레이드

AGP 8.5 환경 준비 완료 후 CameraX와 ML Kit를 16KB 지원 버전으로 교체합니다.

// CameraX dependencies (1.3.4 — stable, 16KB 지원)
implementation 'androidx.camera:camera-core:1.3.4'
implementation 'androidx.camera:camera-camera2:1.3.4'
implementation 'androidx.camera:camera-lifecycle:1.3.4'
implementation 'androidx.camera:camera-view:1.3.4'
implementation 'androidx.camera:camera-extensions:1.3.4'
 
// ML Kit Text Recognition (16.0.1 — 16KB 지원, API 23 이상 요구)
implementation 'com.google.mlkit:text-recognition:16.0.1'

6. 마주한 오류들

오류 1. android.jar 손상 문제

Android resource linking failed
aapt2.exe E  LoadedArsc.cpp:94] RES_TABLE_TYPE_TYPE entry offsets overlap actual entry data.
aapt2.exe E  ApkAssets.cpp:149] Failed to load resources table in APK
  'C:\Users\KONG\AppData\Local\Android\Sdk\platforms\android-35\android.jar'.
error: failed to load include path ...\android-35\android.jar

원인

• android-35의 android.jar가 손상된 상태로 설치됨

• 원인: 사내 Proxy의 최대 파일 크기 제한으로 인해 대용량 파일 다운로드 중 손상 발생

• AGP 버전과 android-35 SDK 간의 호환성 충돌도 복합적으로 작용

해결 방법

• 단기 해결책: compileSdk를 android-35 → android-34로 변경하여 Proxy 크기 제한 회피

• 근본 해결책: 사내 Proxy 외부 환경(모바일 핫스팟 등)에서 SDK를 재다운로드하거나, SDK 관리자에서 android-35 삭제 후 재설치

오류 2. Kotlin stdlib 중복 클래스 충돌

오류 메시지

> Task :app:checkPlusonepayDebugDuplicateClasses FAILED
  Duplicate class kotlin.collections.jdk8.CollectionsJDK8Kt found in modules
    kotlin-stdlib-1.8.22 (org.jetbrains.kotlin:kotlin-stdlib:1.8.22) and
    kotlin-stdlib-jdk8-1.6.0 (org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.6.0)
 
  Duplicate class kotlin.internal.jdk7.JDK7PlatformImplementations found in modules
    kotlin-stdlib-1.8.22 and kotlin-stdlib-jdk7-1.6.0
  ... (이하 동일 패턴 반복)

원인 (라면 비유)

냄비에 A 라면 세트(건더기 스프 대용량 포함)와 B 라면 세트(건더기 스프 소용량 포함)를
동시에 넣으면 어떤 건더기 스프를 써야 할지 모르는 상황과 같습니다.
 
Kotlin 1.8+부터는 stdlib-jdk7 / stdlib-jdk8의 내용이 kotlin-stdlib에 통합되었는데,
다른 의존성 라이브러리가 구버전 stdlib-jdk7:1.6.0 / stdlib-jdk8:1.6.0을 함께 끌어오면서
같은 클래스가 두 jar에 중복으로 존재해 충돌이 발생합니다.

해결 방법 — resolutionStrategy 강제 통일

// build.gradle (루트) — allprojects 블록에 추가
allprojects {
    configurations.all {
        resolutionStrategy.eachDependency { details ->
            if (details.requested.group == 'org.jetbrains.kotlin') {
                details.useVersion '1.8.22'
                // 규칙: kotlin 관련 의존성은 무조건 1.8.22(대용량 통합본)만 사용
            }
        }
    }
}

위 설정의 의미를 풀어쓰면:

• configurations.all = 냄비에 들어오는 모든 재료에 대해

• if (group == 'org.jetbrains.kotlin') = kotlin 계열 재료라면

• useVersion '1.8.22' = 무조건 통합 대용량(1.8.22)만 사용

7. 보안 체크리스트

아래 항목을 빌드 전 반드시 확인하세요.

HTTP → HTTPS 저장소 URL

maven 저장소 URL은 반드시 HTTPS를 사용해야 합니다. HTTP는 중간자 공격(MITM)에 취약하며, 악성 의존성이 빌드에 포함될 수 있습니다.

// 위험 (HTTP)
maven { url 'http://dl.bintray.com/raphaelbussa/maven' }
 
// 안전 (HTTPS)
maven { url 'https://dl.bintray.com/raphaelbussa/maven' }

jcenter() 저장소 제거 확인

jcenter는 2021년 서비스 종료 후 더 이상 유지보수되지 않으며, 보안 패치가 제공되지 않습니다. 모든 모듈의 repositories 블록에서 jcenter()가 완전히 제거되었는지 확인하세요.

repositories {
    google()
    mavenCentral()
    // jcenter() 없음 — 확인 완료
}

minSdk 23 이상 설정

ML Kit 최신 버전은 API 23 미만 디바이스를 지원하지 않습니다. minSdkVersion이 22 이하로 남아있으면 빌드는 성공하더라도 런타임에 크래시가 발생할 수 있습니다.

defaultConfig {
    minSdk 23  //  22 → 23으로 변경 필수
}

8. 참고: AGP 버전별 요구사항 대응표

AGP 버전	Gradle 버전	Java 버전	비고
4.x	6.5	Java 8	레거시. jcenter 사용
7.x	7.5	Java 11+	androidx 전환 완료 권장
8.0	8.0	Java 17+	namespace 필수, buildFeatures 추가
8.5	8.7	Java 17+	16KB 정렬 패키징 지원

[0주차] F-Lab 서포터즈: 온라인 킥오프

truthgarnet — Wed, 19 Mar 2025 00:18:51 +0900

서포터즈의 첫 시작

대학생 때도 안 한 서포터즈를 지금 와서 시작하게 되었습니다.
3년간 회사 생활을 마치고, 회사와 집만 오가는 반복된 생활 속에서 이번 기회에 다양한 경험과 다양한 분을 만나보고 싶다고 생각이 들었습니다.
처음으로 서포터즈 활동을 하게 되어 '잘할 수 있을까? 어색한 분위기는 어떡하지?'라는 생각에 겁도 났습니다. 하지만, 지금 서포터즈를 하지 않으면 후회할 것 같은 느낌을 받아서 바로 당장 시작하기로 마음먹고 신청하게 되었습니다!

오늘의 기분 점수

다행이도 기분점수를 통해 서포터즈 매니저님인 `Soi`님께서 시작 전에 분위기를 풀어주셨습니다.

어색한 분위기를 풀 겸 오늘 서로 각자 기분 점수를 이야기하게 되었고, 퇴근을 못 하신 분들은 2~3점에 머무르셔서 씁쓸한 웃음을 지었고, 저도 전에 야근을 하던 일이 생각이 나 마음속으로 공감하면서 눈물을 흘렸습니다.

마음 속 저의 상태

서포터즈 2기 활동

이번 서포터즈는 다양한 활동을 하는 데요!

오프라인 프로그램 참여 부분에서 무박 2일 해커톤에 참여자나 스테프 참여가 가장 관심이 갔습니다.

아마도 스테프 참여를 하게 되지 않을까 싶습니다.

학습 공간 활동
개인 블로그 & SNS 공유
오프라인 프로그램 참여
- 오프라인 토요 모각코
- 무박 2일 해커톤
온라인 프로그램 참여
- 미니컨퍼런스
온라인 정기 미팅
오프라인 모임

느낀점

아직은 이런 활동이 낯설어 삐걱거리지만, 오랜만에 새로운 도전을 하며 설렘도 느꼈습니다.

앞으로의 활동도 너무 기대가 되고, 서포터즈 활동을 통해 좋은 추억을 만들고 싶습니다!

다음 미팅까지 준비할 내용

서포터즈 2기 네이밍

F-Lab이 연구실이라는 점에서 떠올린 단어가 Flask였습니다. 마침 'F'로 시작하기도 하고, 플라스크는 연구실과도 잘 어울리는 이미지라서 F-Lask라는 이름을 생각해봤습니다. ‘플라스크’로 읽고, F-Lask로 기재하면 어떨까 생각했습니다.

다른 후보도 있었는데, 연구소니까 ‘연구원’을 의미하는 이름을 떠올려 보기도 했습니다. 하지만 Researcher나 ‘리서쳐’ 같은 단어는 뭔가 임팩트가 약하기도 하고 귀에 착 붙는 느낌도 부족했습니다. 그래서 결국 F-Lask가 가장 끌렸습니다.

Flyway 적용 과정

truthgarnet — Tue, 3 Dec 2024 14:26:20 +0900

Flyway에서 MySQL 사용

flyway에서 MySQL를 연결하기까지 고난을 정리하고자 합니다.

flyway란 오픈소스 데이터베이스 마이그레이션 도구입니다.

실서버에서 데이터베이스의 구조가 변경하면, 위험요소가 너무 큽니다.

구조가 바뀜으로 서버에 오류가 발생할 수도 있습니다. 그렇기 때문에, Git처럼 형상관리를 하고자 사용하는 툴입니다.

1. 라이브러리 문제

문제 발생

Caused by: org.flywaydb.core.api.FlywayException: Unsupported Database: MySQL 8.0

발생 이유

Flyway는 특정 버전에서 MySQL의 일부 버전만 지원해서 Flyway와 MySQL의 버전을 맞춰야 합니다.

해결 방법

1. Flyway 버전 변경(❌)

MySQL 8.0을 사용하고 있는 데,

flyway -v // flyway 버전 확인

공식 사이트에 들어가면, flyway가 제공해 주는 버전이 나옵니다.

MySQL은 8.0으로 제한된 테스트 기능을 사용할 수 있다고 나옵니다.

저는 기존에 8.0으로 사용하고 있어서 문제가 8.0에 있는 줄 알고 업그레이드를 진행했습니다.

아래와 같은 MySQL 버전 변경하는 방법을 거쳐서 변경해 줍니다.

MySQL 버전 변경

기존에 돌리고 있는 MySQL 종료
MySQL의 Data와 my.ini 백업 C:\ProgramData\MySQL\MySQL Server 8.0\Data 에 존재
다른 버전 MySQL 설치 https://downloads.mysql.com/archives/community/
설치 후, 환경 변수 설정
기존 데이터 복구
MySQL 실행

기대를 품고 다시 실행한 결과

Caused by: org.flywaydb.core.api.FlywayException: Unsupported Database: MySQL 8.1

이번에는 8.1에서 문제 생긴 것을 알 수 있습니다.

2. flyway-mysql 라이브러리 추가(⭕)

공식 사이트에 검색해 본 결과, flyway-mysql 의존성을 추가해야 한다고 합니다.

친절하게 Flyway 10.7.0부터는 MariaDB 드라이버는 더 이상 기본적으로 MySQL URL을 허용하지 않는다고 합니다. MySQL를 사용하려면 따로 flyway-mysql 라이브러리를 추가 해야 한다고 나옵니다.

Gradle 설정

/* flyway */
implementation 'org.flywaydb:flyway-core'
implementation 'org.flywaydb:flyway-mysql'

2. Flyway 마이그레이션 실패

문제 발생

Caused by: org.flywaydb.core.api.exception.FlywayValidateException: Validate failed: Migrations have failed validation

발생 이유

쿼리문 잘못 작성
flyway_schema_history 실패로 인한 실행 불가
데이터베이스 불일치

해결 방법

저의 경우에는 이미 success = 0 이 발생하여서 발생한 문제였습니다.

SELECT * FROM flyway_schema_history WHERE success = 0;

필드명을 바꾸는 와중에 필드명이 맞지 않았는 데, 수정하고 돌리니 이미 데이터베이스에 flyway가 적용되어서 실행된 flyway를 DELETE 하고 새로운 쿼리를 작성해야 합니다.

드디어 성공한 모습입니다.

Flyway를 적용하는 데 시간이 많이 발생했습니다. 긴 여정이었지만, 해결하고 정상적으로 돌아가는 모습을 보니 너무 뿌듯하다는 생각이 들었습니다.

참고 사이트

Flyway 공식 사이트: https://documentation.red-gate.com/flyway/getting-started-with-flyway/system-requirements/supported-databases-and-versions
MySQL 공식 사이트: https://downloads.mysql.com/archives/community/
stackOverflow: https://stackoverflow.com/questions/72711770/flyway-unsupported-database-mysql-8-0

프로젝트 리팩토링: Swagger 보안

truthgarnet — Mon, 2 Dec 2024 11:59:33 +0900

Swagger IP 접근 제한 처리

문제점

Swagger의 접근을 서버의 IP와 swagger url만 알게 된다면, 모두가 접근할 수 있었습니다.

서버 보안에 대해서 생각을 잘 못하고 있다가 한번 패스워드가 누군가에 의해 변경되는 사고를 겪고 나서 보안에 대해서 더욱 공부를 많이 하고 할 수 있는 보안 처리는 모두 하자라는 생각이 들었습니다. 그래서 스웨거의 접근에 대해서 고민을 하게 되었고, Swagger를 접근할 수 있는 IP를 설정하였습니다.

해결 방안

1. Spring Security를 사용 시, hasIpAddress(’’)으로 허용할 IP를 설정

SpEL은 Spring Expression Language의 약자로, Spring Framework에서 제공하는 표현식 언어

속성 접근, 메서드 호출, 조건문 등 다양한 기능 제공
Spring Security, Spring Data JPA, Spring ELK 등 다양한 Spring 모듈에서 사용 가능

@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
                .authorizeRequests()
                .antMatchers("/swagger-ui/**", "/v3/api-docs/**")
                .access("hasIpAddress('192.0.0.1')") // SpEL (Spring Expression Language)
                .anyRequests().permitAll()
                .and()
                .csrf().disable();
    }
}

2. Filter를 통해서 IP 설정

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        HttpServletRequest httpServletRequest = (HttpServletRequest) request;
        String clientIp = httpServletRequest.getRemoteAddr();

        // Swagger URL에 대한 IP 제한
        String requestUri = httpServletRequest.getRequestURI();
        if ((requestUri.startsWith("/swagger-ui") || requestUri.startsWith("/v3/api-docs")) && !ALLOWED_IP.equals(clientIp)) {
            log.error("허용되지 않는 IP입니다.");
            throw new SecurityException("허용되지 않는 IP입니다.");
        }

        chain.doFilter(request, response);
    }

3. interceptor으로 ip 허용

- 디스패치 서블릿이 컨트롤러를 호출하기 전과 후에 요청과 응답을 참조 또는 가공

```
@Component
public class SwaggerInterceptor implements HandlerInterceptor {

    private static final String ALLOWED_IP = "192.168.1.100"; // 허용할 IP

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        String clientIp = getClientIp(request);

        if (ALLOWED_IP.equals(clientIp)) {
            return true; // 허용된 IP면 요청 진행
        }

        response.setStatus(HttpServletResponse.SC_FORBIDDEN); // 403 Forbidden
        response.getWriter().write("Access Denied");
        return false; // 요청 차단
    }

    private String getClientIp(HttpServletRequest request) {
        String clientIp = request.getHeader("X-Forwarded-For");
        if (clientIp == null || clientIp.isEmpty()) {
            clientIp = request.getRemoteAddr();
        }
        return clientIp;
    }
}
```

4. proxy 서버에서의 설정(ex. nginx)

location /swagger-ui {
    allow 192.168.1.100; # 허용할 IP
    deny all; # 다른 IP는 차단
}

location /v3/api-docs {
    allow 192.168.1.100; # 허용할 IP
    deny all; # 다른 IP는 차단
}

5. Swagger Config 파일에서 설정

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build()
            .enable(isSwaggerEnabled());
    }

    private boolean isSwaggerEnabled() {
        String allowedIp = "192.168.1.100";
        String clientIp = getClientIp();
        return allowedIp.equals(clientIp);
    }

    private String getClientIp() {
        // IP 가져오는 로직 구현 필요
        return "192.168.1.100"; // 예시
    }
}

변경 점

저는 다양한 방법 중에서 2번을 선택하기로 했습니다.

리팩토링하면서 중요하게 본 것이 실제 서버에게 영향을 최대한 주지 않으면서 할 수 있는 방법은 무언인가 생각했습니다.

1번 제외 이유

Spring Expression Language 을 사용하는 것은 너무 생소하기도 하고, 설정이 잘 안 되어서 포기한 부분이었습니다.

3번 제외 이유

Interceptort은 DispatcherServlet 이후에 동작하기 때문에 Spring 내부 로직에 진입한 이후에 실행되어서 IP 접근 제한은 Filter로 작성하는 것이 더 적절하다고 생각이 들었습니다.

4번 제외 이유

실 서버에서 nginx을 사용하여 proxy가 작동되고 있지만, nginx 설정 파일을 건들여야 하고 재시작을 해야 한다는 점이 리스크가 발생할 수 있다고 생각이 들어 4번은 제외 대상이 되었습니다.

5번 제외 이유

Config 파일은 서버가 실행될 때 한 번 실행되기 때문에, 로그를 추적할 수 없습니다. 저는 여기에 접속한 IP가 무엇인지 추적하고 싶었습니다. 그래서 제외 대상이 되었습니다.

추가 설정

fail2ban을 설정 했습니다.
fail2ban이란 로그 파일을 스캔하여, 로그인 시도를 많이 실패하는 IP 주소를 차단하는 프로그램입니다.
/var/log/auth.log을 필터링하여 ssh 접속을 감시합니다.

사진을 보면 무차별적인 접속이 오는 것을 알 수 있습니다.

느낀 점

제가 백엔드 개발자임에 불구하고, 보안 쪽에 너무 모르고 있었지 않나 생각이 듭니다. 개발할 때, 보안 측면에서 생각하는 노력을 키워야겠다는 생각이 듭니다. 물론, 보안 프로그램이 존재한다면 좋겠지만 없는 데로 제가 할 수 있는 것을 해야만 한다고 생각합니다. 다음에는 부족한 부분을 다른 방식으로 어떻게 해결할 수 있는가에 대해서 더욱 고민해 보는 노력을 해야겠습니다.

프로젝트 리팩토링: 아키텍처

truthgarnet — Wed, 27 Nov 2024 18:23:00 +0900

탑 다운 방식

문제점

과거에 뭣도 모르고 개발한 코드가 레거시 하다고 생각하고 리팩토링을 진행했습니다.

폴더 구조를 탑 다운 방식으로 생기는 문제가 발생했습니다.

위의 사진을 봤을 때, ArIcon ArIcon이 cms, user로 구분되어서 중복되어서 사용되고 있습니다.

개발을 진행할 때, 구조를 cms와 user로 api를 구분 지어야 하니까 폴더 구조를 나눠서 생각하자고 진했습니다. 이제 개발의 짬(?) 좀 차고 이 코드를 다시 와서 보니 잘못된 생각을 가지고 있다고 생각이 들었고, 중복된 구간을 해결하고자 프로젝트 구조를 다시 구성하려고 합니다.

변경점

아키텍처 변경 (탑 다운 → 클린 + 레이어드)

리팩토링 한 폴더 구조입니다.

presentation 은 Client와 가까운 코드들로 Controller, Facade가 위치하게 될 것입니다.

application 은 실제 로직에서 사용하는 코드들로 Service, Repository 인터페이스가 위치할 것입니다.

infrastructure 은 외부에서 주입되는 코드들로 데이터베이스 주입(JPA)과 Redis 주입 등이 여기에 들어갈 것입니다.

이렇게 Repository와 JPA Repository로 구분하며 구성한 이유는 그 후에 들어오실 분이 Mybatis 사용에 익숙하시면, Mybatis로 JPA가 익숙하면 JPA로 로직으로 실제 로직(Service)에 영향이 없게 하기 위해서 구성했습니다.

변경전 / 변경후

느낀 점

어렴풋이 개발 설계가 중요하다는 것을 느꼈지만, 이렇게까지 뼈저리게 느끼게 될 줄은 몰랐습니다. 역시나 사람은 경험해 보고 나서야 안다고 한다더니 제 이야기였습니다... 개발하기 전에 공부를 더 많이 했더라면 이런 실수는 범하지 않았을 것이라고 느꼈습니다. 다음에는 더욱 많은 아키텍처를 경험해 보고 상황에 따라 어떤 아키텍처가 적절한지 고민해 보고 개발을 진행하려고 합니다.