Contributor9

[제작 앱 소개] 퀵 링크: 스마트 링크 매니저

adjh54 — Fri, 29 May 2026 16:33:09 +0900

해당 글에서는 Contributor9 개발자가 만든 개발 앱에 대해 홍보를 위한 목적으로 작성한 글입니다.

1) 개발자는 왜 이 앱을 만들었을까?

개발자는 왜 이 앱을 만들었을까?

- 메모장 한 구석에 언젠가부터 저장된 '긴 링크들'이 가득이었습니다.

음.. 이 링크가 뭐였더라..? 뭔가 중요하다고 생각해서 저장을 한 것 같은데.. 무슨 목적으로 붙여 넣기를 한 거지..라고 생각을 하게 되었습니다. 이럴 때면, 어딘가 이런 링크들을 관리해 둘 수 있는 앱이 있었으면 좋겠다고 생각이 들었습니다.

그리고 내 마음대로 분류를 하고, 필요할 때마다 빠르게 접근을 할 수 있는 그런 무언가가 있었으면 좋겠다고 생각이 들었습니다.

브라우저에서는 즐겨찾기 기능으로 쉽게 정리하고 빠르게 찾아갈 수 있는데.. 모바일에서는 관리도 힘들고, 꼭 크롬, 사파리 등에서만 관리가 된다는 게 참 불편하다는 생각이 들어서 이 앱을 개발하게 되었습니다.!

이러한 불편함들을 '퀵 링크: 스마트 링크 매니저'에서 해결하실 수 있습니다!

이 앱에서는 '간단하게 링크를 복사하고 퀵 링크에서 붙여 넣기'를 해주세요!

퀵 링크에서는 빠르게 링크를 분석하여서 사용자에게 보기 편한 화면으로 제공을 합니다

그리고 '나만의 폴더'를 생성해 보세요! 폴더에서 저장된 링크들을 분류해서 관리해 보세요! 필요한 순간 바로바로 찾아볼 수 있습니다

화면에서 바로 퀵링크 버튼을 눌러서 빠르게 열어보세요!
저장한 링크를 손쉽게 열어볼 수 있습니다

필요에 따라 링크를 고정하고, 다른 사람들과 공유를 할 수 있는 기능을 제공합니다.!

앱 자체도 잠금으로 다른 사람이 알 수 없게 나만의 폴더로 관리할 수 있습니다!

그리고, 앱 전체 말고 나만 알고 싶은 폴더들은 비밀번호로 잠가 둘 수 있습니다

이런 편리한 기능으로 링크를 쉽게 관리해 보세요!

2) 앱 소개- 퀵 링크: 스마트 링크 매니저

앱 소개- 퀵 링크: 스마트 링크 매니저

- 다시 보고 싶은 링크, 정작 필요할 때 못 찾으신 적 있으신가요? 메모장 한구석에 던져둔 링크, 막상 필요한 순간엔 어디 있는지 모르고.

링크 주소만 봐서는 무슨 사이트인지 기억도 안 나고. 모바일에서 북마크를 꺼내는 것도 여간 번거로운 게 아니죠.

퀵 링크 앱이 그 불편함을 해결합니다.

복사한 링크를 붙여 넣기 한 번으로 저장하면, 앱이 자동으로 사이트 제목과 설명, 대표 이미지까지 불러와 한눈에 알아볼 수 있는 카드로 만들어줍니다.
나중에 꺼내볼 때 URL 대신 익숙한 썸네일과 제목이 반겨주니, “이게 그 링크였지” 하는 순간이 훨씬 빨라져요. 키워드 하나로 바로 찾을 수 있는 스마트 링크 관리 앱입니다.
나만의 폴더로 링크를 깔끔하게 분류하고, 자주 찾는 링크는 상단에 고정해 언제든 빠르게 접근할 수 있어요.

업무 레퍼런스, 뉴스 아티클, 쇼핑 목록, 개발 문서까지 링크를 많이 다루는 분이라면 누구에게나 딱 맞는 도구입니다.

1. 폴더 리스트
- 링크를 체계적으로 관리하는 시작점입니다. 나만의 폴더를 만들고, 원하는 방식으로 정리하고, 중요한 것은 보호하세요.

[주요 기능 1] 폴더 관리
- 원하는 이모지와 색상으로 폴더를 만들고, 드래그 앤 드롭으로 순서를 자유롭게 배치할 수 있습니다.
- 자주 쓰는 폴더는 상단에 핀 고정해 빠르게 접근하세요.

[주요 기능 2] 보기 & 탐색
- 리스트 보기와 앨범 보기 중 원하는 방식으로 폴더를 확인할 수 있습니다. 폴더 이름 검색과 생성일 / 이름 / 링크 수 기준 정렬도 지원합니다.

[주요 기능 3] 보안 & 공유
- 민감한 폴더는 PIN 번호로 잠그세요. 열람, 수정, 공유 모두 잠금 해제 후에만 가능합니다.
- 폴더 안의 링크 목록은 텍스트로 한 번에 공유할 수 있습니다.

[주요 기능 4] 다크 모드
- 라이트 / 다크 모드를 모두 지원합니다.

2. 링크 목록
- 폴더 안의 링크를 자유롭게 탐색하고 관리하는 공간입니다. 검색과 필터로 원하는 링크를 빠르게 찾고, 스와이프 한 번으로 다양한 작업을 바로 실행할 수 있습니다.

[주요 기능 1] 보기 & 탐색
- 리스트 보기와 카드 그리드 보기를 전환할 수 있습니다. 제목과 도메인으로 실시간 검색하고, 오늘 / 1주일 / 1개월 / 3개월 또는 직접 입력한 날짜 범위로 필터링할 수 있습니다.
- 최신순 · 오래된 순 · 이름순 · 조회수순 정렬도 지원하며, 핀 고정 항목은 항상 최상단에 유지됩니다.

[주요 기능 2] 빠른 액션
- 링크를 스와이프 하면 핀 고정 · URL 복사 · 폴더 이동 · 공유 · 편집 · 삭제를 바로 실행할 수 있습니다.
- 목록을 아래로 당기면 최신 상태로 새로고침됩니다.

[주요 기능 3] 조회수 & 공유
- 링크를 열 때마다 조회수가 자동 기록됩니다. 폴더 안의 링크 목록은 텍스트로 한 번에 공유할 수 있습니다.

[주요 기능 4]  잠긴 폴더 보호
- 전체 보기에서는 PIN으로 잠긴 폴더의 링크가 자동으로 제외됩니다.

3. 통계
- 내 링크 사용 습관을 한눈에 파악하세요. 저장한 링크와 폴더를 다양한 기준으로 분석해 나만의 인사이트를 발견할 수 있습니다

[주요 기능 1] 핵심 지표 요약
- 총 링크 수, 폴더 수, 전체 조회수, 고정 링크 수를 카드 형태로 확인할 수 있습니다.

[주요 기능 2]  등록 & 사용 패턴
- 일간 · 주간 · 월간 · 전체 탭으로 링크 등록 흐름을 바 차트로 시각화하고, 이전/다음 버튼으로 기간을 탐색할 수 있습니다. 요일별 저장 패턴과 미열람 링크 · 메모 작성 · 폴더 미지정 링크 비율도 함께 확인하세요.

[주요 기능 3] 폴더 & 사이트 분석
- 도넛 차트와 막대그래프로 폴더별 링크 분포를 비교하고, 폴더 활동 점수(링크 수 + 조회수) 랭킹도 확인할 수 있습니다.
자주 저장한 도메인 Top 8과 태그 클라우드도 제공합니다.

[주요 기능 4]  많이 본 링크 Top 5
- 조회수 기준 상위 5개 링크를 바로 확인하고, 탭 한 번으로 열 수 있습니다.

[주요 기능 5]  비밀 폴더 통계 포함 옵션
- PIN으로 잠긴 폴더를 통계에 포함할지 직접 선택할 수 있습니다.

4. 설정

- 앱을 내 취향에 맞게 조정하세요. 언어, 테마, 보안, 데이터 관리까지 모든 설정을 한 곳에서 관리할 수 있습니다.
- 일반 언어(한국어 / English)와 테마(라이트 / 다크 모드)를 설정할 수 있습니다.
- 보안 PIN을 설정하면 앱 실행 시마다 인증이 필요합니다. 인증 전까지 폴더와 링크가 표시되지 않아 개인 정보를 안전하게 보호할 수 있습니다.
- 데이터 관리 링크, 폴더, 최근 검색어를 개별 또는 전체 초기화할 수 있습니다. 실수를 방지하기 위해 확인 절차가 포함되어 있습니다.
- 지원 & 피드백 불편한 점은 문의하기로 알려주세요.
- 앱 버전과 기기 정보가 자동으로 포함됩니다. 앱이 마음에 드셨다면 스토어에 리뷰를 남겨주세요. 앱 정보 버전 확인 및 업데이트, 앱 공유, 제작자 소개, 개인정보 처리방침 및 이용약관, 오픈소스 라이브러리를 확인할 수 있습니다.

3) 다운로드

1. Google Play Store

퀵 링크: 스마트 링크 매니저 - Google Play 앱

저장은 한 번, 검색은 한 단어로

play.google.com

2. App Store

퀵 링크: 스마트 링크 매니저 앱 - App Store

App Store에서 EcodeLab의 퀵 링크: 스마트 링크 매니저 앱을 다운로드하십시오. 스크린샷, 평가 및 리뷰, 사용자 팁 및 퀵 링크: 스마트 링크 매니저 앱과 비슷한 다른 앱을 볼 수 있습니다.

apps.apple.com

⬇️ 개발자의 다양한 앱을 보고 싶으시면 아래의 링크를 확인해 주세요 ⬇️

Ecodelab - 제작 앱 소개

Ecodelab에서 개발한 다양한 앱들을 소개합니다

www.ecodelab.im

오늘도 감사합니다.

[Java] Google Search Console 이해하고 API 연동하기

adjh54 — Wed, 20 May 2026 19:20:00 +0900

해당 글에서는 Google Search Console에서 수집된 데이터를 google-api-services-searchconsole 라이브러리를 활용하여서 데이터를 불러오는 API 활용 방법에 대해서 알아봅니다

[참고] 이전에 Google Analaytics를 연동한 내용에 대해 궁금하시면 아래의 글을 참고하시면 도움이 됩니다.

[Java] GA4(Google Analytics) 이해하고 활용하기 -2: 수집된 데이터 조회 환경 설정 및 활용 방법

해당 글에서는 GA에서 수집된 데이터를 API를 통해서 가져와서 화면상에 출력하는 과정을 포함한 글입니다. [참고] React 환경에서 수집한 데이터에 대해서 Spring Boot 환경에서 이를 조회하는 방

adjh54.tistory.com

1) GSC(Google Search Console)

GSC(Google Search Console)

- Google이 무료로 제공하는 웹마스터 도구로, 내 웹사이트가 Google 검색에서 어떻게 노출되고 있는지 모니터링하고 최적화할 수 있는 서비스를 의미합니다.

1. GSC 주요 기능 요약

기능	설명	주요 사항
실적 (Performance)	검색 결과에서의 사이트 성과 분석	클릭수, 노출수, CTR, 평균 게재순위
URL 검사 (URL Inspection)	특정 URL의 크롤링/색인 상태 확인	색인 여부, 모바일 사용성, 구조화 데이터 유효성
페이지 색인 생성	전체 사이트의 색인 현황 보고서	색인된 페이지 수, 미색인 사유
사이트맵 (Sitemaps)	sitemap.xml 제출 및 상태 추적	제출 URL 수 vs 색인 URL 수
코어 웹 바이탈	페이지 로딩/반응 성능 측정	LCP, INP, CLS
모바일 사용성	모바일 환경 문제 감지	텍스트 크기, 터치 요소 간격, 뷰포트 설정
구조화된 데이터	리치 결과(Rich Results) 유효성 검사	FAQ, 제품, 리뷰 등 스키마 오류/경고
링크 (Links)	내부/외부 링크 구조 분석	백링크 현황, 앵커 텍스트, 상위 연결 사이트

2. 실적 보고서 주요 지표

기능	지표 설명	포인트
총 클릭수	검색 결과에서 사이트를 클릭한 횟수	실제 유입 트래픽 파악
총 노출수	검색 결과에 사이트가 표시된 횟수	검색 가시성 측정
평균 CTR	노출 대비 클릭 비율 (%)	메타 타이틀/디스크립션 효과 판단
평균 게재순위	검색 결과 내 평균 위치	SEO 개선 효과 추적

2) 환경 구성하기 -1 : Google Cloud 서비스 허용

1. Google Cloud에 접속

Google 클라우드 플랫폼

로그인 Google 클라우드 플랫폼으로 이동

accounts.google.com

2. API 및 서비스를 선택합니다

3. 라이브러리 > Google Search Console API를 선택합니다

라이브러리 > Google Search Console API를 선택합니다

4. ‘사용’ 버튼을 누릅니다

5. API 및 서비스 > 사용자 인증 정보 탭으로 이동하여 서비스 계정을 확인합니다

API 및 서비스 > 사용자 인증 정보 탭으로 이동하여 서비스 계정을 확인합니다

- 서비스 계정 이메일을 복사해 둡니다.
- GA로 이미 사용을 하는 경우, 동일한 서비스 계정을 이용해도 됩니다.

[참고] 추가 신규 사용자의 경우는 아래의 GA 설정 글을 따라서 구성하시면 됩니다.

[Java] GA4(Google Analytics) 이해하고 활용하기 -2: 수집된 데이터 조회 환경 설정 및 활용 방법

adjh54.tistory.com

2) 환경 구성하기 -2 : Google Search Console 사용자 추가

1. Google Search Console에 접속합니다

Google Search Console

Search Console 도구와 보고서를 사용하면 사이트의 검색 트래픽 및 실적을 측정하고, 문제를 해결하며, Google 검색결과에서 사이트가 돋보이게 할 수 있습니다.

search.google.com

2. 설정 > 사용자 추가 버튼을 누릅니다

3. 이전 단계에서 복사해 둔 이메일을 추가하면 설정은 완료가 됩니다.

4) Google Search Console API

Google Search Console API

- Google Search Console로부터 수집된 정보를 API로 전달을 받아서 프로그래밍 방식으로 접근할 수 있는 HTTP REST 서비스를 의미합니다.
- 속성(사이트) 관리, 사이트맵 제출, 검색 실적 데이터 조회, URL 검사를 API로 처리할 수 있습니다.

개요 | Search Console API | Google for Developers

속성 및 사이트맵을 확인, 추가 또는 삭제하고, Google 검색결과 데이터에서 쿼리를 실행하고, 페이지를 테스트하는 데 사용하는 API의 개요를 확인하세요.

developers.google.com

1. 라이브러리 설치

implementation 'com.google.apis:google-api-services-searchconsole:v1-rev20250122-2.0.0' // Google Search Console API

Maven Repository: com.google.apis » google-api-services-searchconsole

mvnrepository.com

2. SearchConsoleConfig

SearchConsoleConfig

- Spring Boot 애플리케이션에서 Google Search Console API를 사용할 수 있도록 연동 클라이언트(SearchConsole)를 생성하고 관리하는 설정(Configuration) 클래스입니다.
- 내부적으로 ga-key.json 파일을 불러와서 구글 인증 및 권한 설정을 수행합니다.
- SearchConsole.Builder를 통해서 최종 클라이언트의 빌드를 수행합니다.

package com.xxx.xxx.config;

import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.searchconsole.v1.SearchConsole;
import com.google.api.services.searchconsole.v1.SearchConsoleScopes;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;

@Configuration
public class SearchConsoleConfig {

    @Bean
    public SearchConsole searchConsoleClient() throws Exception {
        GoogleCredentials credentials = GoogleCredentials
                .fromStream(new ClassPathResource("ga-key.json").getInputStream())
                .createScoped(SearchConsoleScopes.WEBMASTERS_READONLY);

        HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials);

        return new SearchConsole.Builder(
                GoogleNetHttpTransport.newTrustedTransport(),
                GsonFactory.getDefaultInstance(),
                requestInitializer
        ).setApplicationName("xxx-xxx").build();
    }
}

3. SearchConsoleService

SearchConsoleService

- 사전에 구성된 SearchConsoleConfig에서 생성된 클라이언트를 기반으로 이를 활용하여서 google search console로부터 조회를 해옵니다.

필드	dimensions 인덱스	값 예시	설명
date	keys.get(0)	2026-05-20	검색 발생 날짜
query	keys.get(1)	검색	사용자가 검색한 키워드
page	keys.get(2)	https://xxx.com/about	노출된 페이지 URL
country	keys.get(3)	kor	국가 코드
device	keys.get(4)	DESKTOP	디바이스 종류

siteUrl	(파라미터로 전달)	https://xxx.com	조회 대상 사이트 URL
clicks	getClicks()	42	검색 결과 클릭 수
impressions	getImpressions()	1500	검색 결과 노출 수
ctr	getCtr()	0.028	클릭률 (clicks ÷ impressions)
position	getPosition()	8.3	평균 검색 노출 순위 (낮을수록 상위)


import com.daekyocns.homepage.model.dto.SearchConsoleResponseDto;
import com.google.api.services.searchconsole.v1.SearchConsole;
import com.google.api.services.searchconsole.v1.model.ApiDataRow;
import com.google.api.services.searchconsole.v1.model.SearchAnalyticsQueryRequest;
import com.google.api.services.searchconsole.v1.model.SearchAnalyticsQueryResponse;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;

import java.util.Arrays;
import java.util.List;
import java.util.stream.Stream;

@Service
public class SearchConsoleService {

    // Google Search Console API 클라이언트 (Bean으로 주입)
    private final SearchConsole client;

    // application.yml의 search-console.site-urls 값 (여러 사이트 URL 배열)
    @Value("${search-console.site-urls}")
    private String[] siteUrls;

    public SearchConsoleService(SearchConsole client) {
        this.client = client;
    }

    /**
     * 등록된 모든 사이트의 Search Analytics 데이터를 조회한다.
     *
     * @param startDate 조회 시작일 (yyyy-MM-dd)
     * @param endDate   조회 종료일 (yyyy-MM-dd)
     * @return 전체 사이트의 검색 분석 데이터 목록
     */
    public List<SearchConsoleResponseDto> getSearchAnalytics(String startDate, String endDate) throws Exception {
        return Arrays.stream(siteUrls)
                .flatMap(siteUrl -> {
                    try {
                        // 사이트별로 데이터를 조회하여 하나의 스트림으로 병합
                        return fetchBySite(siteUrl, startDate, endDate).stream();
                    } catch (Exception e) {
                        // 특정 사이트 조회 실패 시 해당 사이트는 건너뛰고 계속 진행
                        return Stream.of();
                    }
                })
                .toList();
    }

    /**
     * 특정 사이트의 Search Analytics 데이터를 Google API로 조회한다.
     *
     * @param siteUrl   조회할 사이트 URL
     * @param startDate 조회 시작일
     * @param endDate   조회 종료일
     * @return 해당 사이트의 검색 분석 데이터 목록
     */
    private List<SearchConsoleResponseDto> fetchBySite(String siteUrl, String startDate, String endDate) throws Exception {
        // 쿼리 요청 구성: 날짜 범위, 집계 기준(date/query/page/country/device), 최대 행 수
        SearchAnalyticsQueryRequest request = new SearchAnalyticsQueryRequest()
                .setStartDate(startDate)
                .setEndDate(endDate)
                .setDimensions(List.of("date", "query", "page", "country", "device"))
                .setRowLimit(1000); // 최대 1000행 반환

        // Google Search Console API 호출
        SearchAnalyticsQueryResponse response = client.searchanalytics()
                .query(siteUrl, request)
                .execute();

        // 데이터가 없는 경우 빈 리스트 반환
        if (response.getRows() == null) return List.of();

        // 응답 행(row)을 DTO로 변환하여 반환
        return response.getRows().stream()
                .map(row -> toDto(row, siteUrl))
                .toList();
    }

    /**
     * API 응답 행(ApiDataRow)을 SearchConsoleResponseDto로 변환한다.
     * dimensions 순서: [0] date, [1] query, [2] page, [3] country, [4] device
     *
     * @param row     Google API 응답의 단일 행
     * @param siteUrl 해당 행이 속한 사이트 URL
     * @return 변환된 DTO
     */
    private SearchConsoleResponseDto toDto(ApiDataRow row, String siteUrl) {
        return SearchConsoleResponseDto.builder()
                .siteUrl(siteUrl)
                .date(row.getKeys().get(0))            // 날짜
                .query(row.getKeys().get(1))           // 검색 키워드
                .page(row.getKeys().get(2))            // 노출 페이지 URL
                .country(row.getKeys().get(3))         // 국가 코드 (예: KOR)
                .device(row.getKeys().get(4))          // 디바이스 (DESKTOP / MOBILE / TABLET)
                .clicks(row.getClicks().longValue())   // 클릭 수
                .impressions(row.getImpressions().longValue()) // 노출 수
                .ctr(row.getCtr())                     // 클릭률
                .position(row.getPosition())           // 평균 검색 순위
                .build();
    }
}

4. SearchConsoleResponseDto

package com.xxx.xxx.model.dto;

import lombok.Builder;
import lombok.Getter;

/**
 * Google Search Console API 검색 분석 응답 DTO
 * dimensions: date / query / page / country / device
 * metrics: clicks / impressions / ctr / position
 *
 * @author : leejonghoon
 * @fileName : SearchConsoleResponseDto
 * @since : 26. 5. 18.
 */
@Getter
@Builder
public class SearchConsoleResponseDto {
    private String siteUrl;
    private String date;        // 날짜 (yyyy-MM-dd)
    private String query;       // 검색 키워드
    private String page;        // 노출 페이지 URL
    private String country;     // 국가 코드 (예: KOR, USA)
    private String device;      // 디바이스 (DESKTOP / MOBILE / TABLET)
    private long clicks;        // 클릭 수
    private long impressions;   // 노출 수
    private double ctr;         // 클릭률 (0.0 ~ 1.0)
    private double position;    // 평균 검색 순위
}

5. SearchConsoleController

package com.xxx.xxx.controller;

import com.daekyocns.homepage.model.common.ApiResponseWrapper;
import com.daekyocns.homepage.model.common.SuccessCode;
import com.daekyocns.homepage.model.dto.GaRequestDto;
import com.daekyocns.homepage.model.dto.SearchConsoleResponseDto;
import com.daekyocns.homepage.service.SearchConsoleService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@Slf4j
@RestController
@RequestMapping(value = "/api/searchconsole")
public class SearchConsoleController {

    private final SearchConsoleService searchConsoleService;

    public SearchConsoleController(SearchConsoleService searchConsoleService) {
        this.searchConsoleService = searchConsoleService;
    }

    @PostMapping("/analytics")
    public ResponseEntity<ApiResponseWrapper<List<SearchConsoleResponseDto>>> getAnalytics(@RequestBody GaRequestDto request) {
        log.debug("[+] getSearchConsoleAnalytics CALL");

        try {
            List<SearchConsoleResponseDto> list = searchConsoleService.getSearchAnalytics(
                    request.getStartDate(),
                    request.getEndDate()
            );
            log.debug("list: " + list);

            ApiResponseWrapper<List<SearchConsoleResponseDto>> arw = ApiResponseWrapper.<List<SearchConsoleResponseDto>>builder()
                    .result(list)
                    .resultCode(SuccessCode.SELECT_SUCCESS.getStatus())
                    .resultMsg(SuccessCode.SELECT_SUCCESS.getMessage())
                    .build();

            return new ResponseEntity<>(arw, HttpStatus.OK);

        } catch (Exception e) {
            log.error("Search Console API 호출 실패: ", e);
            return new ResponseEntity<>(HttpStatus.INTERNAL_SERVER_ERROR);
        }
    }
}

6. 결과 확인

결과 확인

- HTTP Client를 이용하여 아래와 같은 결과값을 얻었습니다.

6.1. 결과화면 : 키워드 분석

6.2. 결과화면 : 기기별 성과

6.3. 결과화면 : 국가별 트래픽

오늘도 감사합니다.

[CI/CD] Github Self-hosted Runner 방식 구성 및 배포 방법 -1

adjh54 — Wed, 20 May 2026 19:15:05 +0900

해당 글에서는 Self-hosted Runner기반으로 Docker Compose로 구성된 파일을 배포하는 사용 사례입니다.

1) GitHub Actions Runner

GitHub Actions Runner

- GitHub Actions 워크플로우를 실제로 실행하는 에이전트(프로세스)입니다.
- GitHub 리포지토리에 정의된 .github/workflows/*.yml 파일의 작업(Job)을 받아서, 해당 명령어들을 순차적으로 수행하는 역할을 합니다.

항목	Github-hosted Runner	Self-hosted Runner
실행 주체	GitHub 클라우드 서버	내 서버
설정 난이도	쉬움 (바로 사용)	높음 (Runner 설치 필요)
비용	무료 한도 후 과금	서버 비용만
내부망 접근	불가	가능
실행 환경	매 Job마다 초기화	환경 유지
캐시 유지	불가 (actions/cache 필요)	가능
보안 관리	GitHub이 관리	직접 관리
OS 선택	ubuntu / windows / macos	자유롭게 설정
실행 시간 제한	6시간/Job	제한 없음
적합한 상황	오픈소스, 외부 배포	사내 서버 배포, 내부망 연동

1. GitHub-hosted Runner

GitHub-hosted Runner

- GitHub가 제공하는 클라우드 서버에서 Actions Job을 실행하는 방식을 의미하며, 별도 서버 설정 없이 바로 사용 가능합니다.
- Self-Hosted와 가장 큰 차이점은 실행 주체가 ‘Github 서버’가 됩니다

[처리 과정]

1. 이벤트 발생

- Actions를 시작시키는 출발점으로 개발자가 코드를 push하거나 PR을 열거나, 설정한 스케줄 시간이 되면 GitHub이 이벤트를 감지합니다.

2. GitHub Actions 트리거

- .github/workflows/*.yml 파일을 읽어서 어떤 Job을 실행할지 파악하며, on: push 같은 트리거 조건이 일치하면 워크플로우가 시작됩니다

3. GitHub 클라우드 서버 할당

- runs-on: ubuntu-latest 설정을 보고 GitHub이 클라우드 서버를 새로 생성해서 할당합니다.
- 이 서버는 Job 실행을 위해 완전히 새로운 환경으로 시작이 되며, Node, Java, Docker 등 기본 툴은 이미 설치되어 있습니다.

4. Job 실행 (빌드 → 테스트 → 배포)

- 워크플로우에 정의된 steps를 순서대로 실행하며, 각 step은 독립적으로 실행되고 이전 step이 실패하면 기본적으로 이후 step은 중단이 됩니다.

5. Runner 종료

- Job이 끝나면 할당됐던 클라우드 서버가 완전히 삭제가 됩니다. 다음 Job 실행 시 항상 새 서버에서 시작 — 이전 실행의 파일, 캐시, 환경변수 등이 전혀 남지 않습니다.

GitHub 호스팅 실행기 - GitHub 문서

GitHub 는 워크플로를 실행하기 위해 호스트된 가상 머신을 제공합니다. 가상 머신에는 사용할 수 있는 도구, 패키지 및 설정 환경이 포함되어 있습니다 GitHub Actions .

docs.github.com

2. Self-hosted Runner

Self-Hosted

- 소프트웨어나 서비스를 외부 클라우드 벤더에 의존하지 않고, 자신의 서버/인프라에서 직접 운영하는 방식을 의미합니다.

Self-hosted Runner 처리 과정

1. 이벤트 발생 (개발자/저장소)
- GitHub-hosted와 동일하며, push, PR, schedule 등 이벤트가 발생하면 Actions가 감지합니다.

2. GitHub Actions 트리거
- .github/workflows/*.yml에서 runs-on: self-hosted를 감지하며, 클라우드 서버 대신 등록된 Self-hosted Runner를 찾습니다.

3. 내 서버(Runner)로 Job 전달: GitHub → 내 서버
- Hosted 방식과 다르게 GitHub이 서버를 새로 만드는 게 아니라, 내 서버에서 실행 중인 Runner 프로세스가 GitHub을 주기적으로 폴링해서 Job을 가져오는 방식.

4. 내 서버에서 Job 실행
- 실제 빌드/테스트/배포가 내 서버에서 직접 실행됩니다.

5. 결과 GitHub에 보고: 내 서버 → GitHub
- Job 실행이 끝나면 성공/실패 상태를 GitHub에 전송. GitHub Actions UI에서 로그와 결과를 확인할 수 있게 됨.

6. Runner 대기 상태 유지
- GitHub-hosted와 가장 다른 부분. 서버가 삭제되지 않고 계속 살아서 다음 Job을 기다림.
- 환경이 유지되기 때문에 이전 빌드의 캐시, 설치된 패키지 등이 그대로 남아있음.

자체 호스팅 실행기 - GitHub 문서

자체 실행기를 호스트하고 GitHub Actions 워크플로에서 작업을 실행하는 데 사용되는 환경을 사용자 지정할 수 있습니다.

docs.github.com

2) Github self-hosted 설정

Github self-hosted 설정

- 주체가 되는 서버에 Github의 Runner를 설치하여서 서버 자체 내에서 배포를 하는 방식입니다.

1. Github Settings > Actions > Runners 탭을 선택합니다

2. New self-hosted runner를 선택합니다

3. Runner image, Architecture, Download, Configure가 출력이 됩니다

[참고] Architecture는 서버내에서 아래의 명령어로 확인이 가능합니다

GitHub에서 선택	출력값	의미
x64	x86_64	일반 Intel/AMD 64bit
ARM64	aarch64	ARM 64bit (AWS Graviton, 라즈베리파이 등)
ARM	armv7l	ARM 32bit

$ uname -m

3) Linux 서버에서 수행

1. 위에서 전달받은 명령어에 따라 다운로드(Download)를 수행합니다.

# Create a folder
$ mkdir actions-runner && cd actions-runnerCopied!

# Download the latest runner package
$ curl -o actions-runner-linux-arm64-2.334.0.tar.gz -L <https://github.com/actions/runner/releases/download/v2.334.0/actions-runner-linux-arm64-2.334.0.tar.gzCopied>!

# Optional: Validate the hash
$ echo "xxxxxxx  actions-runner-linux-arm64-2.334.0.tar.gz" | shasum -a 256 -c

# Extract the installer
$ tar xzf ./actions-runner-linux-arm64-2.334.0.tar.gz

2. 추가 설정(Configure) 명령어를 입력합니다.

추가 설정(Configure) 명령어를 입력합니다.

- 아래와 같이 실제 수행이 됨을 확인하였습니다.

# Create the runner and start the configuration experience
$ ./config.sh --url https://github.com/xxxxx/xxxxx --token xxxxx

# Last step, run it!
$ ./run.sh

3. 백그라운드에서 run.sh 파일 수행

백그라운드에서 run.sh 파일 수행

- ./run.sh 파일을 수행하면 터미널에서 세션이 사라지게 되면, 리스너가 종료가 됩니다. 그렇기에 백그라운드로 수행하도록 수행합니다.

# 터미널 종료해도 백그라운드에서 계속 실행
$ nohup ./run.sh &

[참고] 실행중인 러너와 확인 후 종료 방법

# 실행중인 러너를 확인
ps aux | grep Runner.Listener

# PID 확인 후 종료
kill [PID]

4) Action 구성 : Front-end

1. 루트 경로에 .github/workflows 폴더를 생성하고 deploy.yml 파일을 생성합니다.

2. deploy.yml 구성하기

deploy.yml 구성하기

- 아래와 같은 구성을 수행하였습니다.
- 해당 처리 과정은 release-xxx 브랜치로 'pull Request'가 발생하였을 때, 아래와 같은 Action이 수행이 됩니다.

단계	이름	설명
1	소스코드 체크아웃	레포 코드를 Runner 서버로 내려받음
2	Node.js 설정	Node.js 24 버전 설치
3	Yarn 활성화	corepack으로 Yarn 활성화
4	의존성 설치	yarn.lock 기준으로 패키지 설치
5	빌드	Vite production 빌드 → dist/ 생성
6	Docker 이미지 빌드	dist/를 포함한 Docker 이미지 생성
7	기존 컨테이너 중지 및 제거	실행 중인 컨테이너 종료/삭제
8	컨테이너 실행	compose로 새 이미지 컨테이너 재시작
9	오래된 이미지 정리	사용하지 않는 Docker 이미지 삭제

name: Deploy xxx

on:
 push:
  branches:
   - release-xxx

jobs:
 deploy:
  runs-on: self-hosted

  steps:
   - name: 소스코드 체크아웃
     uses: actions/checkout@v4

   - name: Node.js 설정
     uses: actions/setup-node@v4
     with:
      node-version: '24'

   - name: Yarn 활성화
     run: corepack enable

   - name: 의존성 설치
     run: yarn install --immutable

   - name: 빌드
     run: yarn build --mode production

   - name: Docker 이미지 빌드
     run: docker build --platform linux/amd64 -f Dockerfile -t xxx-xxx-web .

   - name: 기존 컨테이너 중지 및 제거
     run: |
      docker stop xxx-web || true
      docker rm xxx-web || true

   - name: 컨테이너 실행
     run: docker compose -f /home/tomcat/compose.yaml up -d web
     
   - name: 오래된 이미지 정리
     run: docker image prune -f

3. 실행 확인

실행 확인

- 실행한 환경에 맞게 정상적으로 수행이 됨을 확인하였습니다.

5) Action 구성 : Back-end

1. 루트 경로에 .github/workflows 폴더를 생성하고 deploy.yml 파일을 생성합니다.

[참고] 최초 배포를 하는 경우 아래와 같은 오류가 발생하였습니다.

- Git 내에 gradle-wrapper.jar가 올라가지 않은 상태이기에 이를 포함하여 올려줍니다.

git add -f gradle/wrapper/gradle-wrapper.jar

2. deploy.yml 구성하기

deploy.yml 구성하기

- 아래와 같은 구성을 수행하였습니다.
- 해당 처리 과정은 release-xxx로 pull Request가 발생하였을 때, 아래와 같은 Action이 수행이 됩니다.

단계	이름	설명
1	소스코드 체크아웃	레포 코드를 Runner 서버로 내려받음
2	Java 설정	Amazon Corretto 21 버전 설치
3	Gradle 빌드	bootJar로 실행 가능한 JAR 파일 생성
4	Docker 이미지 빌드	JAR를 포함한 Docker 이미지 생성
5	기존 컨테이너 중지 및 제거	실행 중인 컨테이너 종료/삭제
6	컨테이너 실행	compose로 새 이미지 컨테이너 재시작
7	오래된 이미지 정리	사용하지 않는 Docker 이미지 삭제

name: Deploy API

on:
  push:
    branches:
      - release-xxx

jobs:
  deploy:
    runs-on: self-hosted

    steps:
      - name: 소스코드 체크아웃
        uses: actions/checkout@v4

      - name: Java 설정
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'corretto'

      - name: Gradle 빌드
        run: ./gradlew bootJar

      - name: Docker 이미지 빌드
        run: docker build --platform linux/amd64 -f Dockerfile -t dkcns-homepage-api .

      - name: 기존 컨테이너 중지 및 제거
        run: |
          docker stop xxx-api || true
          docker rm xxx-api || true

      - name: 컨테이너 실행
        run: |
          docker compose -f /home/tomcat/compose.yaml up -d api

      - name: 오래된 이미지 정리
        run: docker image prune -f

3. 실행 확인

실행 확인

- 실행한 환경에 맞게 정상적으로 수행이 됨을 확인하였습니다.

오늘도 감사합니다.

[CI/CD] Docker Compose + SFTP 방식 구성 및 배포 방법

adjh54 — Wed, 20 May 2026 19:10:47 +0900

해당 글에서는 CI/CD 파이프라인이 구축되기 전에 사용자의 수동 배포를 최소한으로 줄이기 위해 임시적으로 사용하는 SFTP 방식을 이용한 사례에 대해서 작성한 글입니다.

1) 배포방식

배포방식

- 현재 배포 환경은 CI/CD 파이프라인이 구축되기 이전 단계로 GitHub Actions Runner 같은 자동화 도구를 통한 배포가 아닌, 사용자가 수동 배포 과정을 최소한으로 줄이기 위해 임시로 운영하는 방식입니다.

- 별도의 Docker Registry를 운영하지 않기 때문에, 개발 PC에서 Docker 이미지를 빌드한 뒤 docker save 명령으로 .tar 파일로 저장합니다. 이 파일을 SFTP를 통해 운영 서버로 전송하고, 운영 서버에서 docker load로 이미지를 로드한 뒤 docker compose up -d로 서비스를 실행하는 흐름입니다.

- 이 방식은 Registry 구축 없이도 이미지를 전달할 수 있고, 인터넷이 차단된 폐쇄망 환경에서도 적용 가능하다는 장점이 있습니다. 반면 매 배포마다 수동 작업이 필요하고, 배포 이력 관리가 어려우며, 이미지 태그 불일치 등의 휴먼 에러가 발생할 수 있다는 한계가 있습니다.

- 향후 CI/CD가 구축되면, git push를 트리거로 Runner가 자동으로 이미지를 빌드하고 Registry에 push 한 뒤 운영 서버에서 pull 하여 배포하는 구조로 전환될 예정이며, 현재의 수동 과정은 그 과도기에 사용하는 임시 배포 방식입니다.

1. 배포 처리 과정

배포 처리 과정

1. 소스코드
- 배포의 시작점으로 React, Spring Boot 등 로컬에서 개발 완료된 상태의 코드를 준비합니다.
- 또한, .env, docker-compose.yml, Dockerfile 등이 함께 준비되어 있어야 합니다.

2. Docker 이미지 빌드
- Dockerfile을 기반으로 소스코드를 컨테이너 이미지로 패키징 하는 단계를 의미합니다.
- 이 시점에 OS, 런타임, 의존성, 앱 코드가 하나의 이미지로 묶이며, 빌드 결과물은 로컬 Docker에만 존재해야 합니다.

3. tar 파일 Export
- Docker 이미지를 파일로 직렬화하는 단계를 의미합니다. Docker Hub 같은 외부 레지스트리 없이 이미지를 전송하기 위해 사용이 됩니다.

4. SFTP 전송
- PC에서 압축된 tar 파일을 배포될 원격 서버로 복사를 하는 과정입니다. 이 과정에서는 FTP 또는 SFTP 전송을 하며, SFTP 클라이언트(FileZila, Termius 등)를 사용하여 전송을 합니다.

5. 파일 수신 (서버 폴더 이동)
- 서버에서 전송받은 파일 위치를 확인하는 단계이며, 별도 작업이라기보다 다음 단계 전 준비 확인 과정입니다.

6. 이미지 로드
- 서버의 Docker에 이미지를 등록하는 단계를 의미합니다.

7. 컨테이너 실행
- compose.yml 기반으로 컨테이너를 백그라운드로 실행. 포트, 볼륨, 환경변수 등이 이 파일에 정의되어 있는 파일을 실행합니다.

8. 배포 완료
- 서비스 정상 동작 확인합니다.

2. 서버 내 compose.yaml

서버 내 compose.yaml

- 해당 서버는 배포될 리눅스 서버를 의미하며, 이를 위치하며 Docker Compose를 통하여서 배포가 이루어집니다.

depends_on 기반 서비스 실행 과정

- 해당 서비스는 db → api → web 순서로 기동 됩니다.

1) db : PostgreSQL

- postgres:17.9 이미지로 컨테이너를 생성하며 기본적인 TimeZone 설정을 지정하였습니다.

1. command, environment 속성: 기본적인 TimeZone 설정을 지정하였습니다.

2. env_file 속성: 서버 내에 위치해 있는 파일로, 기본적인 db 연결을 위한 POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD를 지정하였습니다.

3. volumes 속성 : pgdata:/var/lib/postgresql/data 컨테이너를 삭제하더라도 데이터를 유지하기 위해 지정하였습니다.

2) api : Spring Boot

- 사전에 외부에서 .tar 파일로 빌드된 이미지를 가져와, 이미지 로드로 불러온 Spring Boot 컨테이너 이미지를 사용합니다.

1. env_file 속성: 서버 내에 위치해 있는 파일로, DB 접속 정보, Spring 프로파일 등 환경변수 주입을 하는 속성입니다.

2. volumes 속성 : bind mount로 호스트의 ./uploads 디렉토리를 컨테이너 /uploads에 매핑되며, 파일 업로드 데이터가 호스트에 직접 저장됩니다.

3. environment 속성: JVM/OS 레벨 타임존 설정을 합니다.

4. restart 속성: docker stop을 하기 전까지 수행이 됩니다.

3) web : React
- 사전에 외부에서 .tar 파일로 빌드된 이미지를 가져와, 이미지 로드로 불러온 Vite로 빌드된 정적 파일을 서빙하는 Nginx 컨테이너 이미지를 사용합니다.

1. volumes 속성: volumes로 호스트의 default.conf를 Nginx 설정에 bind mount → 이미지 재빌드 없이 Nginx 설정 변경 가능하도록 구성하였습니다. (컨테이너 재시작만 하면 됨)

2. restart 속성: docker stop을 하기 전까지 수행이 됩니다.

services:
  db:
    image: postgres:17.9
    container_name: xxx-db
    command: postgres -c timezone=Asia/Seoul
    environment:
      - TZ=Asia/Seoul
      - PGTZ=Asia/Seoul
    ports:
      - "5432:5432"
    env_file:
      - ./env/.env.db
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: always

  api:
    image: xxx-xxx-api
    container_name: xxx-api
    ports:
      - "8001:8001"
    env_file:
      - ./env/.env.dev
    depends_on:
      - db
    restart: unless-stopped
    volumes:
      - "./uploads:/uploads"
    environment:
      - TZ=Asia/Seoul
  web:
    image: xxx-xxx-web
    container_name: dkcns-web
    ports:
      - "80:80"
    depends_on:
      - api
    restart: unless-stopped
    volumes:
      - "/home/tomcat/nginx/default.conf:/etc/nginx/conf.d/default.conf"

volumes:
  pgdata:

[참고] 해당 과정에서 적용한 TimeZone에 대해 궁금하시면 아래의 글을 참고하시면 도움이 됩니다.

[DB] PostgreSQL + Docker TimeZone 설정하기

해당 글에서는 PostgreSQL + Docker 환경에서 TimeZone을 지정했던 방법에 대해서 공유합니다. 1) Coordinated Universal Time (UTC) / TimeZone1. Coordinated Universal Time (UTC) Coordinated Universal Time (UTC)- 전 세계 시간대

adjh54.tistory.com

2) API 배포(Spring Boot)

1. DockerFile 구성

DockerFile 구성

- 루트 경로에 소스코드를 이미지화시키기 위한 Dockerfile을 구성합니다.

Dockerfile 파일 설명

1. FROM amazoncorretto:21-alpine
- Amazon이 만든 JDK 21으로 지정을 합니다.

2. WORKDIR /app
- 컨테이너 안에서 작업 디렉터리를 /app으로 설정합니다.

3. COPY build/libs/xxxxxAPI-0.0.1-SNAPSHOT.jar app.jar
- 로컬(내 PC 또는 CI 서버)의 Gradle 빌드 결과물을 컨테이너 안으로 복사합니다.

4. EXPOSE 8001
- 컨테이너가 8001 포트를 사용한다고 선언합니다.

5. ENTRYPOINT ["java", "-jar", "app.jar"]
- 컨테이너 시작 시 실행할 명령어. java -jar app.jar를 실행해서 Spring Boot 앱을 구동함.

# 1
FROM amazoncorretto:21-alpine

# 2
WORKDIR /app

# 3
COPY build/libs/xxxxxAPI-0.0.1-SNAPSHOT.jar app.jar

# 4
EXPOSE 8001

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

2. build-and-export.sh 구성

build-and-export.sh 구성

- Gradle 빌드 → DockerFile 이미지 빌드 → tar 파일로 export까지 수행하는 Shell 파일입니다.

#!/bin/bash
# build-and-export.sh

# 1. Gradle 빌드
./gradlew clean build -x test

# 2. Docker 이미지 빌드
docker build --platform linux/amd64 -t xxx-api .

# 3. tar로 export
docker save -o ~/Desktop/docker/xxx-api.tar xxx-api

echo "완료: xxx-api.tar 생성됨"

3. shell 파일 실행

shell 파일 실행

- Gradle 빌드 → DockerFile 이미지 빌드 → tar 파일로 export까지 수행을 하는 과정입니다.

# shell 파일 실행
$ ./build-and-export.sh

[참고] Docker Desktop이 실행이 되었는지 확인을 합니다. 아래와 같이 오류가 발생함.

- Consider enabling configuration cache to speed up this build: https://docs.gradle.org/9.4.1/userguide/configuration_cache_enabling.html ERROR: Cannot connect to the Docker daemon at unix:///Users/leejonghoon/.docker/run/docker.sock. Is the docker daemon running? Cannot connect to the Docker daemon at unix:///Users/leejonghoon/.docker/run/docker.sock. Is the docker daemon running?

- Docker Desktop을 실행시키면 됩니다.

4. 아래와 같이 tar 파일이 생성되었습니다.

5. [Termius] 연결된 리눅스 서버에 SFTP로 해당 파일을 옮겨둡니다

6. [Termius] tar 파일을 로드해 옵니다.

$ docker load -i xxx-api.tar

7. [Termius] Docker 컨테이너 배포 완료

[Termius] Docker 컨테이너 배포 완료

- Docker 컨테이너를 재 실행하여 정상적으로 소스코드 반영이 완료되었습니다.

docker compose up -d

3) 화면 배포(React)

1. DockerFile

DockerFile 구성

- 루트 경로에 소스코드를 이미지화 시키기 위한 Dockerfile을 구성합니다.

Dockerfile 파일 설명

1. FROM node:24.15.0-alpine
- Node.js 24.15.0 기반의 Alpine Linux 이미지 사용하며, Alpine은 경량 Linux 배포판으로 이미지 크기를 최소화하였습니다

2. WORKDIR /app
- 컨테이너 안에서 작업 디렉토리를 /app으로 설정합니다.

3. RUN yarn global add serve
- 정적 파일 서버인 serve 패키지를 전역 설치하며, React 빌드 결과물(정적 HTML/JS/CSS)을 HTTP로 서빙하는 역할을 수행합니다.

4. COPY dist/ ./dist/
- 로컬 머신의 dist/ 폴더(빌드 결과물)를 컨테이너의 /app/dist/로 복사합니다.

5. EXPOSE 80
- 컨테이너가 80번 포트를 사용한다고 선언합니다

6. CMD ["serve", "-s", "dist", "-l", "80"]
- dist 폴더를 80번 포트로 웹서버처럼 서빙하도록 구성

# 1
FROM node:24.15.0-alpine

# 2
WORKDIR /app

# 3
RUN yarn global add serve

# 4
COPY dist/ ./dist/

# 5
EXPOSE 80

# 6
CMD ["serve", "-s", "dist", "-l", "80"]

2. package.json 내에 스크립트 구성

package.json 내에 스크립트 구성

- 패키지 라이브러리를 기반으로 스크립트를 수행하도록 하면, 긴 수행 과정을 하나의 명령어로 처리할 수 있습니다.
- 4개 명령어를 &&로 순서대로 실행하는 npm 스크립트이며, 하나라도 실패하면 중단이 됩니다.

"scripts": {
 "build:docker": 
 "vite build --mode production && docker build --platform linux/amd64 -f Dockerfile -t xxx-xxx-web . && docker save -o /Users/leejonghoon/Desktop/docker/xxx-xxx-web.tar xxx-xxx-web && echo '완료: xxx-xxx-web.tar 생성됨'",
}

1단계

- 소스코드를 빌드하는 과정입니다.
- Vite로 프로덕션 빌드를 수행하며, .env.production 환경변수 적용해서 dist/ 폴더를 생성합니다

vite build --mode production

2단계

- 빌드된 소스코드를 컨테이너 이미지화 하는 과정입니다.
1. —platform linux/amd64 : 플랫폼을 linux/amd64로 지정
2. -f Dockerfile : 사용할 Dockerfile 지정
3. -t xxx-xxx-web: 컨테이너 이미지 이름 태그
4. . : 빌드 컨텍스트(현재 디렉토리)

docker build --platform linux/amd64 -f Dockerfile -t xxx-xxx-web .

3단계

- 컨테이너 이미지를 .tar 파일로 내보내서 내 로컬에 저장하는 과정입니다.

1. docker save : 도커 이미지를 .tar 파일로 내보내기
2. o : 출력 파일 경로 (바탕화면 docker 폴더)

- 이 tar 파일을 서버에 SCP로 전송해서 docker load로 불러올 수 있음

docker save -o /Users/leejonghoon/Desktop/docker/xxx-xxx-web.tar xxx-xxx-web

4단계

- 모든 과정이 성공적으로 끝났을 때 완료 메시지 출력.

echo '완료: dkcns-homepage-web.tar 생성됨'

3. 명령어 실행

명령어 실행

- 명령어가 실행이 되었고, 아래와 같이 파일이 생성이 되었습니다

4. 아래와 같이 tar 파일이 생성되었습니다.

5. [Termius] 연결된 리눅스 서버에 SFTP로 해당 파일을 옮겨둡니다

6. [Termius] tar 파일을 로드해 옵니다.

$ docker load -i xxx-xxx-web.tar

7. [Termius] Docker 컨테이너 배포 완료

[Termius] Docker 컨테이너 배포 완료

- Docker 컨테이너를 재 실행하여 정상적으로 소스코드 반영이 완료되었습니다.

docker compose up -d

오늘도 감사합니다.

[제작 앱 소개] 순픽: 순우리말 퀴즈

adjh54 — Mon, 18 May 2026 18:12:17 +0900

해당 글에서는 Contributor9 개발자가 만든 개발 앱에 대해 홍보를 위한 목적으로 작성한 글입니다.

1) 개발자는 왜 이 앱을 만들었을까?

개발자는 왜 이 앱을 만들었을까?

- "이 단어는 당연히 순우리말이지?"라고 생각했다가 알고 보니 한자어였던 경험, 한 번쯤 있으시죠?

- 윤슬, 가람, 늘봄, 단비. 처음 들어봤을수도 있고 어딘가에서 한 번은 들어봤을지도 모릅니다. 이 단어들은 아름다운 순우리말들입니다.

- 한국어의 60~70%는 한자어로 이루어져 있으며, 학술·의학·법률 분야에서는 그 비중이 90% 이상에 달한다고 합니다.
그렇다면 고유어, 즉 순우리말의 비중은 얼마나 될까요? 약 20~30% 수준에 불과하다고 합니다.

- 잊혀져가는 아름다운 순우리말들을 기억해 보는 건 어떨까요? 일상 속에서 문득 “이 말이 순우리말이었어?” 싶은 순간을 마주칠 때면, 작은 발견의 즐거움이 찾을 수 있습니다.

- 우리말의 아름다움과 뿌리에 관심 있는 분들께 꼭 한번 들여다보시길 권합니다.

2) 앱 소개- 순픽: 순우리말 퀴즈

앱 소개- 순픽: 순우리말 퀴즈

- 순픽: 순우리말 퀴즈는 우리말의 아름다운 순우리말 표현들을 쉽고 재미있게 학습할 수 있는 학습형 퀴즈 앱입니다.

- 500개의 다양한 순우리말을 '학습 카드' 형식으로 익히고, '순우리말 퀴즈'를 통해 배운 어휘를 점검할 수 있습니다. 틀린 문제는 '오답 복습' 기능으로 반복 학습할 수 있으며, 마지막에는 '타임 챌린지' 모드를 통해 실력을 점검하면서 완벽한 순우리말 달인에 한 걸음 더 다가갈 수 있습니다.
- 학습 → 퀴즈 → 복습 → 보상의 선순환 구조로 학습 동기를 부여하며, 점수에 따라 변화하는 캐릭터와 타이틀, 다양한 뱃지를 획득하여 재미있는 학습 여정을 제공합니다.

홈 화면
- 점수별 캐릭터, 타이틀, 획득한 뱃지를 한눈에 확인 '퀴즈 시작', '학습 모드', '오답 복습', ‘타임 챌린지’, ‘순우리말 이름들’ 주요 기능으로 빠르게 진입 '숨겨진 뱃지를 찾아보세요'를 통해 획득한 뱃지와 아직 잠금 해제되지 않은 뱃지 정보 확인 ‘오늘의 출석 확인’을 통해 출석한 날짜를 확인

학습 모드 - 카드 형식으로 맞춤법과 예문을 통해 쉽게 학습
- 난이도, 카테고리, 학습 상태별 필터 기능 제공 초급부터 특급까지 단계별로 맞춤법을 체계적으로 익힐 수 있음

퀴즈 모드
- 뜻 맞추기, 순우리말 찾기, 종합모드(뜻+순우리말) 퀴즈 지원 난이도 및 카테고리별로 문제 선택 가능

퀴즈
- 4지선다형 객관식 문제 + 30초 제한 시간 전구 버튼을 통해 현재 문제의 힌트 제공 문제에 대한 정답/오답 시 문제 풀이 제공

오답 복습 - 틀린 문제만 모아 반복 문제 및 풀이 제공
- 정답을 맞히면 자동으로 오답 목록에서 제거되어 효율적인 복습 가능

타임 챌린지 - 180초 동안 제한 시간 내에 최대한 많은 문제 풀기 도전
- 속도와 정확도를 겨루며 나만의 최고 점수에 도전 콤보, 점수, 랭킹 시스템으로 긴장감 넘치는 재미 제공

나의 활동 - 학습 완료 개수, 마지막 학습일 등 학습 활동 이력 제공

- 퀴즈 진행 횟수, 최고 콤보, 정답률 등 퀴즈 통계 확인 점수에 따라 변화하는 캐릭터와 타이틀, 획득한 뱃지 목록 및 해제 조건 제공

설정 - 학습 및 퀴즈 기록 초기화 기능

- 개인정보 처리방침, 이용약관, 오픈소스 라이브러리 확인 현재 앱 버전 및 제작자 정보 제공 앱을 처음처럼 리셋하여 새롭게 시작 가능

이런 분께 추천합니다

- 잊혀져가는 아름다운 순우리말을 배우고 싶은 분
- '미쁘다', '오롯이', '애틋하다' 같은 우리말의 뜻을 알고 싶은 분
- 일상에서 쓸 수 있는 고운 우리말을 익히고 싶은 분
- 게임하듯 퀴즈 풀며 순우리말 실력을 키우고 싶은 분
- 순우리말 이름의 의미를 찾아보고 싶은 분
- 타임 챌린지로 긴장감 있게 학습하고 싶은 분
- 우리말의 아름다움과 깊이를 발견하고 싶은 분 뱃지 수집하며 성취감을 느끼고 싶은 분
- 어휘력을 풍성하게 가꾸고 싶은 분 출석 체크로 꾸준한 학습 습관을 만들고 싶은 분

지금 다운로드하고 순우리말 마스터에 도전하세요! 우리말의 아름다움을 발견하는 여정이 지금 시작됩니다! ✨

3) 다운로드

1. Google Play Store

순픽: 순우리말 퀴즈 - Google Play 앱

순우리말을 게임처럼 배우는 퀴즈 학습 앱! 뱃지, 레벨, 타임 챌린지로 재미있게 어휘력 UP!

play.google.com

2. App Store

순픽: 순우리말 퀴즈 앱 - App Store

App Store에서 EcodeLab의 순픽: 순우리말 퀴즈 앱을 다운로드하십시오. 스크린샷, 평가 및 리뷰, 사용자 팁 및 순픽: 순우리말 퀴즈 앱과 비슷한 다른 앱을 볼 수 있습니다.

apps.apple.com

⬇️ 개발자의 다양한 앱을 보고 싶으시면 아래의 링크를 확인해주세요 ⬇️

Ecodelab - 제작 앱 소개

Ecodelab에서 개발한 다양한 앱들을 소개합니다

www.ecodelab.im

오늘도 감사합니다.

[제작 앱 소개] 맞픽: 맞춤법 퀴즈

adjh54 — Mon, 18 May 2026 18:11:45 +0900

해당 글에서는 Contributor9 개발자가 만든 개발 앱에 대해 홍보를 위한 목적으로 작성한 글입니다.

1) 개발자는 왜 이 앱을 만들었을까?

개발자는 왜 이 앱을 만들었을까?

- "이 단어 맞춤법이 이게 맞았나..?"라고 생각해 보신 적 있으신가요?

- 가끔 메신저를 이용하면서 이 단어가 맞았나 헷갈릴때가 여러 번 있었던 것 같습니다.
그럴 때면 브라우저를 통해서 검색을 하고 맞는 맞춤법으로 수정하여 메신저를 보내고 했던 것 같습니다.

이전에 이러한 기사를 본 기억이 있습니다 '이성에게서 호감이 떨어지는 순간 중 하나로 맞춤법을 제대로 이용하지 못하였을 때'에 '아.. 깬다'라고 생각이 드는 순간이 있다고 합니다.
그리고 주변 지인중에 한 분이 '나이가 들수록 적어도 맞춤법은 틀리지 말아야겠다'라는 마음가짐을 가지신 분을 보면서 맞춤법을 쉽게 검색할 수 있고 퀴즈로 익힐 수 있는 앱을 만들어보자라는 생각을 하게 되었습니다.

이 단어 맞춤법이 이게 맞았나?라고 생각이 들때, 준비된 '맞춤법 사전'에서 쉽게 검색할 수 있습니다.
500개가량에 일상생활에서 헷갈리기 쉽고 자주 사용되는 단어들을 추렸습니다. 그리고 일상 대화의 예시들로 쉽게 이해하실 수 있습니다! 이러한 맞춤법 출처는 주요 정부 기관 내에서 직접 검증을 통한 명확한 맞춤법으로 제공을 합니다.

내 맞춤법 실력이 궁금하지 않으신가요? 내가 이 단어가 맞다고 사용을 하지만, 막상 알고보니 잘못된 맞춤법으로 사용하고 있지는 않으신가요? 학습 > 퀴즈 > 오답복습 > 타임챌린지 단계로 선순환 방식으로 맞춤법을 한번 마스터해보세요! 귀여운 캐릭터도 얻어보고, 마지막 칭호인 ‘전설의 맞춤법 탐정’ 타이틀을 얻어서 맞춤법 마스터를 이뤄보시면 내 삶에 큰 도움이 되실 겁니다.

앞으로 많은 기능 업데이트와 데이터들을 추가할 예정이니 맞픽: 맞춤법 퀴즈와 함께 해보세요!

이런 분께 추천합니다

- 헷갈리는 맞춤법을 쉽고 재미있게 배우고 싶은 분
- 단어와 문장 속 올바른 표기를 확실히 익히고 싶은 분
- 자주 틀리는 표현을 퀴즈로 반복 학습하고 싶은 분
- 오답 복습과 타임 챌린지로 완벽한 실력을 쌓고 싶은 학습자
- 어휘력과 문장력을 함께 향상시키고 싶은 분

2) 앱 소개 - 맞픽: 맞춤법 퀴즈

앱 소개 - 맞픽: 맞춤법 퀴즈

- 한국어 맞춤법 중 헷갈리기 쉬운 다양한 표현들을 쉽고 재미있게 학습할 수 있는 학습형 퀴즈 앱입니다.
- 500개의 헷갈리는 맞춤법 단어와 문장을 '학습 카드' 형식으로 학습하고, '맞춤법 퀴즈'를 통해 익힌 지식을 점검할 수 있습니다. 틀린 문제는 '오답 복습' 기능으로 반복 학습할 수 있으며, 마지막에는 '타임 챌린지' 모드를 통해 실력을 점검하면서 완벽한 맞춤법 마스터에 한 걸음 더 다가갈 수 있습니다.

- 맞픽: 맞춤법 퀴즈는 한국어 맞춤법 중 헷갈리기 쉬운 다양한 표현들을 쉽고 재미있게 학습할 수 있는 학습형 퀴즈 앱**입니다.
- 500개의 다양한 헷갈리는 맞춤법 단어와 문장을 '학습 카드' 형식으로 학습하고, '맞춤법 퀴즈'를 통해 익힌 지식을 점검할 수 있습니다. 틀린 문제는 '오답 복습'' 기능으로 반복 학습할 수 있으며, 마지막에는 '타임 챌린지' 모드를 통해 실력을 점검하면서 완벽한 맞춤법 마스터에 한 걸음 더 다가갈 수 있습니다.

- 학습 → 퀴즈 → 복습 → 보상의 선순환 구조로 학습 동기를 부여하며, 점수에 따라 변화하는 캐릭터와 타이틀, 다양한 뱃지를 획득하여 재미있는 학습 여정을 제공합니다

주요 기능

홈 화면
- 점수별 캐릭터, 타이틀, 획득한 뱃지를 한눈에 확인
- '퀴즈 시작', '학습 모드', '오답 복습', ‘타임 챌린지’ 주요 기능으로 빠르게 진입
- '숨겨진 뱃지를 찾아보세요'를 통해 획득한 뱃지와 아직 잠금 해제되지 않은 뱃지 정보 확인
- ‘오늘의 출석 확인’을 통해 출석한 날짜를 확인

학습 모드
- 카드 형식으로 맞춤법과 예문을 통해 쉽게 학습
- 난이도, 카테고리, 학습 상태별 필터 기능 제공
- 초급부터 특급까지 단계별로 맞춤법을 체계적으로 익힐 수 있음

퀴즈 모드
- 빈 칸 채우기, 문장 맞추기 퀴즈 지원
- 난이도 및 카테고리별로 문제 선택 가능

퀴즈
- 2지선다형 객관식 문제 + 30초 제한 시간
- 전구 버튼을 통해 현재 문제의 힌트 제공
- 문제에 대한 정답/오답 시 문제 풀이 제공

오답 복습
- 틀린 문제만 모아 반복 문제 및 풀이 제공
- 정답을 맞히면 자동으로 오답 목록에서 제거되어 효율적인 복습 가능

타임 챌린지 모드
- 180초 동안 제한 시간 내에 최대한 많은 문제 풀기 도전
- 속도와 정확도를 겨루며 나만의 최고 점수에 도전
- 콤보, 점수, 랭킹 시스템으로 긴장감 넘치는 재미 제공

나의 활동
- 학습 완료 개수, 마지막 학습일 등 학습 활동 이력 제공
- 퀴즈 진행 횟수, 최고 콤보, 정답률 등 퀴즈 통계 확인
- 점수에 따라 변화하는 캐릭터와 타이틀, 획득한 뱃지 목록 및 해제 조건 제공

설정
- 학습 및 퀴즈 기록 초기화 기능
- 개인정보 처리방침, 이용약관, 오픈소스 라이브러리 확인
- 현재 앱 버전 및 제작자 정보 제공
- 앱을 처음처럼 리셋하여 새롭게 시작 가능

이런 분께 추천합니다
- 헷갈리는 맞춤법을 쉽고 재미있게 배우고 싶은 분
- 단어와 문장 속 올바른 표기를 확실히 익히고 싶은 분
- 자주 틀리는 표현을 퀴즈로 반복 학습하고 싶은 분
- 오답 복습과 타임 챌린지로 완벽한 실력을 쌓고 싶은 학습자
- 어휘력과 문장력을 함께 향상시키고 싶은 분

⸻

지금 다운로드하고 맞춤법 마스터에 도전하세요!
당신의 언어 실력이 한층 성장하는 여정이 지금 시작됩니다! ✍️ ✨

3) 다운로드

1. Google PlayStore

맞픽: 맞춤법 퀴즈 - Google Play 앱

한국어 맞춤법 중 헷갈리기 쉬운 다양한 표현들을 쉽고 재미있게 학습할 수 있는 학습형 퀴즈 앱입니다.

play.google.com

2. AppStore

맞픽: 맞춤법 퀴즈 App - App Store

Download 맞픽: 맞춤법 퀴즈 by EcodeLab on the App Store. See screenshots, ratings and reviews, user tips, and more games like 맞픽: 맞춤법 퀴즈.

apps.apple.com

⬇️ 개발자의 다양한 앱을 보고 싶으시면 아래의 링크를 확인해주세요 ⬇️

Ecodelab - 제작 앱 소개

Ecodelab에서 개발한 다양한 앱들을 소개합니다

www.ecodelab.im

오늘도 감사합니다.

[제작 앱 소개] 갬티콘: 갬성 이모티콘

adjh54 — Mon, 18 May 2026 18:07:24 +0900

해당 글에서는 Contributor9 개발자가 만든 개발 앱에 대해 홍보를 위한 목적으로 작성한 글입니다.

1) 개발자는 왜 이 앱을 만들었을까?

개발자는 왜 이 앱을 만들었을까?

- 고등학교 시절, 싸이월드가 한창 유행이던 때가 있었습니다. 카카오톡 이모티콘이 없던 그 시절엔 감정을 표현하는 방법이 지금과는 많이 달랐던 것 같습니다. 텍스트 이모티콘이 그 역할을 했습니다.

(☆ω☆) ٩(๑•̀ㅂ•́)و 같은 것들로 나만의 개성을 표현하고, 마음에 드는 이모티콘을 발견하면 저장해뒀다가 쓰기도 했습니다.

지금은 대부분의 대화가 카카오톡으로 이루어지고 다양한 이모티콘도 넘쳐나지만, 문득 '나만의 유니크한 표현을 쓰고 싶다'거나 '늘 쓰던 이모티콘에서 벗어나 새로운 것을 찾고 싶다'는 생각이 들 때가 있지 않으신가요? (ง'̀-'́)ง

갬티콘은 바로 그런 분들을 위해 만들어졌습니다.

옛 감성이 그리운 분들, 카카오톡 이모티콘에 살짝 지친 분들, 나만의 개성 있는 표현을 찾는 분들 모두를 위한 앱입니다.

(☞ﾟヮﾟ)☞ 총 2,064개의 텍스트 이모티콘을 표정, 동물, 동작, 음악, 음식, 게임/스포츠, 자연/날씨 등 다양한 카테고리로 깔끔하게 정리했습니다.
원하는 이모티콘을 빠르게 검색할 수 있고, 터치 한 번으로 바로 복사도 가능합니다.

(๑˃ᴗ˂)ﻭ 매일 고르기 어렵다면? 랜덤 추천 기능이 대신 골라드립니다. 마음에 드는 이모티콘은 폴더를 만들어 모음집으로 관리하고, 직접 나만의 이모티콘을 만들어 저장하거나 다른 사람에게 공유할 수도 있습니다. ᕦ(ò_óˇ)ᕤ

텍스트 이모티콘의 재미, 갬티콘과 함께 다시 느껴보세요. ( o˘◡˘o) ┌iii┐

2) 앱 소개- 갬티콘: 갬티콘: 갬성 이모티콘

갬티콘: 갬성 이모티콘

- 지금 이 기분, 딱 맞는 이모티콘 있어요. 탭 한 번으로 복사하고, 매일 새로운 갬성을 만나보세요 (๑˃ᴗ˂)ﻭ

- "ㅋㅋ"만으로는 부족한 순간이 있잖아요. 더 웃기고, 더 귀엽고, 더 감성 넘치는 표현이 필요한 그 순간 갬티콘: 갬성 이모티콘이 딱 맞는 이모티콘을 찾아드릴게요.
- 2,000개 이상의 텍스트 이모티콘이 기다리고 있어요. 탭 한 번으로 바로 복사, 어디서든 바로 붙여넣기

상세 설명

1. 홈 화면

- 매일 새로운 이모티콘과 함께 시작하고, 기분·카테고리별 추천과 최근 사용 기록까지 한눈에 확인할 수 있는 앱의 메인 화면입니다.
- 매일 다른 이모티콘이 앱을 열 때마다 반겨줘요. 마음에 들면 탭 한 번으로 바로 복사할 수 있어요.
- 아래로 스크롤하면 신규 업데이트 이모티콘, 기분별 표정 모음, 카테고리 추천이 차례로 펼쳐져요.
- 최근에 사용한 이모티콘은 자동으로 기록되니까 "아까 그거 뭐였지?" 하고 찾아 헤맬 일이 없어요.
- 하트 버튼을 누르면 마음에 드는 이모티콘을 내 모음집에 바로 담을 수 있고,
- 오른쪽 하단 붓 아이콘으로 테마 색상과 다크모드를 취향껏 바꿀 수 있어요.

2. 전체 목록 화면

- 검색, 카테고리 필터, 뷰 모드 전환까지 갖춘 이모티콘 전체 탐색 화면입니다.
- 검색창에 이름이나 태그를 입력하면 원하는 이모티콘을 바로 찾을 수 있어요.
- 상단 카테고리 탭에서 표정·동물·상황 등 원하는 분류만 골라볼 수도 있고요.
- 카드 모드는 이모티콘을 크게 한눈에 비교하기 좋고, 리스트 모드는 한 화면에 더 많이 훑어보기 좋아요.
- 새로 추가된 이모티콘에는 NEW 뱃지가 붙어 있어서 업데이트된 항목을 바로 알아볼 수 있어요.
- 최근 사용 영역은 평소에 접어두다가 필요할 때만 펼쳐볼 수 있고,
- 스크롤을 길게 내려도 오른쪽 하단 버튼 하나면 맨 위로 바로 올라갈 수 있어요.

3. 모음집 화면

- 나만의 이모티콘 컬렉션을 만들고, 정렬·편집·공유까지 자유롭게 관리할 수 있는 화면입니다.
- 이름과 이모지 아이콘을 직접 골라서 나만의 모음집을 만들 수 있어요.
- 모음집은 꾹 눌러서 드래그하면 원하는 순서로 자유롭게 정렬할 수 있고, 편집 모드에서 이름 수정, 삭제, 이모티콘 순서 변경을 한 화면에서 한 번에 처리할 수 있어요.
- 모음집 안의 이모티콘은 탭 하는 것만으로 바로 복사되고, 모음집 전체를 앱 링크와 함께 외부로 공유하는 것도 가능해요.
- 모음집 개수가 꽉 차더라도 짧은 광고 한 편을 보면 계속 추가할 수 있어요.

4. 나만의 이모티콘 화면

- 텍스트, 이모티콘, 특수문자를 자유롭게 조합해 세상에 하나뿐인 이모티콘을 직접 만들 수 있는 편집 화면입니다.
- 텍스트를 직접 입력하거나 이모티콘 픽커에서 골라 커서 위치에 바로 삽입할 수 있어요.
- 특수문자 버튼으로 괄호·기호·가나·도형·하트 등 카테고리별로 원하는 문자를 찾아 붙여 넣을 수도 있고요.
- 입력할 때마다 상단 미리 보기가 실시간으로 업데이트되어 완성된 모양을 바로 확인할 수 있어요.
- 완성한 이모티콘은 복사, 공유, 모음집 저장 중 원하는 방식으로 활용할 수 있으며, 초기화 버튼을 누르면 언제든지 처음부터 다시 만들 수 있어요.

5. 설정 화면

- 앱 공유, 데이터 초기화, 문의·리뷰, 개인정보 및 버전 정보까지 앱 전반을 관리할 수 있는 설정 화면입니다.
- 앱이 마음에 들었다면 공유하기 버튼으로 가족이나 친구에게 바로 소개할 수 있어요.
- 즐겨찾기, 최근 사용 내역, 모음집은 항목별로 또는 한 번에 전부 초기화할 수 있고,
- 앱 리뷰 남기기와 이메일 문의로 피드백도 간편하게 보낼 수 있어요.
- 개인정보 처리방침, 이용약관, 오픈소스 라이브러리 정보는 이 화면에서 언제든지 확인할 수 있으며,
- 최신 버전 확인 버튼으로 업데이트 여부도 바로 체크할 수 있어요.
- 화면 하단에서는 제작자의 다른 앱들도 둘러볼 수 있어요.

이런 분께 추천해요

- 카톡·인스타·디스코드에서 이모티콘 없으면 대화가 밋밋한 분
- "ㅋㅋ"보다 더 찰진 표현을 찾고 있는 분
- 기분 표현에 진심인 분
- 매번 같은 이모티콘만 쓰다가 질린 분
- 나만의 감성 컬렉션을 만들고 싶은 분
- 직접 만든 이모티콘으로 나만의 개성을 드러내고 싶은 분
- 귀엽고 재밌는 거라면 일단 저장하고 보는 분
- 친구한테 답장할 때 이모티콘 고르는 데 진심인 분

3) 다운로드

1. Google Play Store

https://play.google.com/store/apps/details?id=com.tha.emotionalemoticon

갬티콘 : 갬성 텍스트 이모티콘 이모지 특수문자 복사 - Google Play 앱

지금 이 기분, 딱 맞는 이모티콘 있어요. 탭 한 번으로 복사하고, 매일 새로운 갬성을 만나보세요 (๑˃ᴗ˂)ﻭ

play.google.com

2. App Store

https://apps.apple.com/us/app/id6760441156

갬티콘 : 갬성 텍스트 이모티콘 이모지 특수문자 복사 App - App Store

Download 갬티콘 : 갬성 텍스트 이모티콘 이모지 특수문자 복사 by EcodeLab on the App Store. See screenshots, ratings and reviews, user tips, and more apps like 갬티콘 : 갬성 텍스트 이모티콘 이모지…

apps.apple.com

⬇️ 개발자의 다양한 앱을 보고 싶으시면 아래의 링크를 확인해주세요 ⬇️

Ecodelab - 제작 앱 소개

Ecodelab에서 개발한 다양한 앱들을 소개합니다

www.ecodelab.im

오늘도 감사합니다.

[DB] PostgreSQL + Docker TimeZone 설정하기

adjh54 — Fri, 15 May 2026 18:34:39 +0900

해당 글에서는 PostgreSQL + Docker 환경에서 TimeZone을 지정했던 방법에 대해서 공유합니다.

1) Coordinated Universal Time (UTC) / TimeZone

1. Coordinated Universal Time (UTC)

Coordinated Universal Time (UTC)

- 전 세계 시간대 설정의 기준이 되는 가장 정확한 원자시 기반의 시간 표준입니다.

- 본초 자오선(경도 0도)을 기준으로 하며, 서머타임(일광 절약 시간제)을 적용하지 않아 연중 일정한 시간을 유지합니다.
- 한국의 경우는 타임존(KST)을 가지며, UTC 대비 9시간이 늦은 UTC+9를 가집니다.

https://en.wikipedia.org/wiki/Coordinated_Universal_Time

https://www.timeanddate.com/time/map/

2. TimeZone

TimeZone

- 타임존(Time Zone)은 지구를 경도 기준으로 나눈 시간 구역을 의미합니다.

- 지구는 24시간에 360° 자전하므로, 경도 15°마다 1시간 차이가 발생합니다. 이를 기반으로 전 세계를 구역으로 나눠 같은 구역 내에서는 동일한 시간을 사용하도록 약속한 것이 타임존입니다.
- 예를 들어서 절대적인 시간 기준점이 0이라고 하면, TimeZone은 UTC에서 얼마나 떨어져 있는지를 오프셋을 의미합니다.
- 한국의 경우 UTC를 기준으로 +9 거리를 가지기에 UTC Offset +9입니다.

https://www.timeanddate.com/time/map/

Time Zone Map

Current local times around the world, including (DST) changes.

www.timeanddate.com

지역	국가/도시	UTC	오프셋 현지시간(UTC 기준)	비고
아시아	서울 (대한민국)	UTC+9	UTC + 9시간	KST
	도쿄 (일본)	UTC+9	UTC + 9시간	JST
	베이징 (중국)	UTC+8	UTC + 8시간	CST
	홍콩	UTC+8	UTC + 8시간	HKT
	싱가포르	UTC+8	UTC + 8시간	SGT
	방콕 (태국)	UTC+7	UTC + 7시간	ICT
	하노이 (베트남)	UTC+7	UTC + 7시간	ICT
	뭄바이 (인도)	UTC+5:30	UTC + 5시간 30분	IST
	두바이 (UAE)	UTC+4	UTC + 4시간	GST
오세아니아	시드니 (호주)	UTC+10 / +11	UTC + 10~11시간	AEST / AEDT (서머타임)
유럽	런던 (영국)	UTC+0 / +1	UTC ± 0~1시간	GMT / BST (서머타임)
	베를린 (독일)	UTC+1 / +2	UTC + 1~2시간	CET / CEST (서머타임)
	파리 (프랑스)	UTC+1 / +2	UTC + 1~2시간	CET / CEST (서머타임)
	모스크바 (러시아)	UTC+3	UTC + 3시간	MSK (서머타임 없음)
아프리카	요하네스버그 (남아공)	UTC+2	UTC + 2시간	SAST
	카이로 (이집트)	UTC+2 / +3	UTC + 2~3시간	EET / EEST (서머타임)
아메리카	뉴욕 (미국 동부)	UTC-5 / -4	UTC - 5~4시간	EST / EDT (서머타임)
	시카고 (미국 중부)	UTC-6 / -5	UTC - 6~5시간	CST / CDT (서머타임)
	LA (미국 서부)	UTC-8 / -7	UTC - 8~7시간	PST / PDT (서머타임)
	밴쿠버 (캐나다)	UTC-8 / -7	UTC - 8~7시간	PST / PDT (서머타임)
	멕시코시티 (멕시코)	UTC-6 / -5	UTC - 6~5시간	CST / CDT (서머타임)
	상파울루 (브라질)	UTC-3	UTC - 3시간	BRT

[ 더 알아보기 ]

오프셋(Offset) 이란?

- 기준점으로부터 얼마나 떨어져 있는지를 나타내는 차이값을 의미합니다.
- 타임존에서만 쓰는 말이 아니라, 전반적으로 ”기준에서 얼마나 벗어나 있냐"를 표현할 때 쓰는 용어를 의미합니다

2) 문제점

문제점

- 데이터베이스 내에서 now() 내장 함수를 통해서, 현재 시간을 DB에 저장 중에 있습니다.
- 그런데 UTC 시간으로 저장으로 되기에 05:56분과 같은 시간으로 저장이 되었습니다. 이를 대한민국 시간에 맞게 수정하기 위해서, TimeZone을 지정합니다.

3) 해결방법

해결방법

- 위에서 UTC로 지정이 되어 있는 시간을 각각 국가(Asia/Seoul)에 맞게 설정을 하여서 now() 함수를 사용하더라도 TimeZone에 맞는 시간이 나오도록 하는 방식을 사용합니다.

레이어	설정 위치	설명	예시
JDBC TimeZone	application.yml	Java 앱이 DB에 연결할 때 사용하는 타임존. 명시 안 하면 JVM TimeZone을 따라감	- hibernate.jdbc.time_zone: UTC - options=-c%20timezone%3DAsia/Seoul

OS TimeZone	서버 운영체제	컨테이너/서버 운영체제의 기본 타임존. 다른 레이어의 기본값이 됨	timedatectl set-timezone UTC
	Docker	db 컨테이너 OS 타임존 설정. 명시 안 하면 Docker 호스트 OS를 따라감	db: TZ=Asia/Seoul

서버 TimeZone	postgresql.conf	PostgreSQL 서버 전체에 적용되는 타임존. postgresql.conf로 설정하거나 실행 시 -c 옵션으로 지정	timezone = 'UTC'
	Docker	postgresql.conf 없이 서버 시작 시 -c 옵션으로 바로 지정	command: postgres -c timezone=Asia/Seoul
DB TimeZone	DB 세션/전역	특정 DB 또는 세션 단위로 적용되는 타임존. 서버 TimeZone보다 우선순위가 높음	SET timezone = 'UTC' 또는 ALTER DATABASE dbname SET timezone = 'UTC'

JVM TimeZone	Java 프로세스	Java 프로세스 전체에 적용되는 타임존. JDBC TimeZone 미설정 시 이걸 따라감	-Duser.timezone=UTC 또는 TimeZone.setDefault(...)
	Docker	api 컨테이너의 JVM 타임존 설정. Spring Boot 포함 Java 전체에 적용됨	api: TZ=Asia/Seoul

psql 클라이언트 TimeZone	환경변수	psql 터미널 접속 시 사용하는 타임존. 서버 TimeZone과 별개로 클라이언트 표시에만 영향	PGTZ=Asia/Seoul

1. JDBC TimeZone 지정

JDBC TimeZone 지정

- Java 내에서 DateTime, TimeStamp의 클래스의 경우는 컬럼 타입의 저장 시 타임존의 변화가 일어나는데, JDBC 드라이버에서 어떤 타임존 기준으로 변환할지 모르면, JVM 기본 타임존을 사용합니다.

- Java에서 시간 데이터를 보내거나 받을 때, JDBC 드라이버가 KST(+9) 기준으로 변환해서 데이터베이스와 주고받겠다는 뜻입니다.

1.1. MySQL

MySQL

- serverTimezone=Asia/Seoul을 파라미터로 전달하는 방식으로 사용이 됨.

# application.yml
spring:
  datasource:
    url: jdbc:mysql://xxxxx:35432/dbname?serverTimezone=Asia/Seoul&useUnicode=true&characterEncoding=UTF-8

1.2. PostgreSQL

PostgreSQL

- 아래에서는 인코딩 된 상태로 ‘options=-c%20timezone%3DAsia/Seoul’를 적용하였습니다.
- 이 URL을 디코딩하게 되면 options=-c timezone=Asia/Seoul로 출력이 됩니다.

# application.yml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/dbname?options=-c%20timezone%3DAsia/Seoul

Initializing the Driver | pgJDBC

Initializing the Driver This section describes how to load and initialize the JDBC driver in your programs. Importing JDBC Any source file that uses JDBC needs to import the java.sql package, using: NOTE You should not import the org.postgresql package unl

jdbc.postgresql.org

[참고]

- 실제로 해당 옵션을 추가하더라도 수행하지 않았다는 글이 있습니다.
- 이는 pgJDBC 드라이버가 연결 시 JVM 타임존이 강제로 덮어버린다는 이슈가 있습니다.

property "options" "-c timezone=America/New_York" does not seem to work · Issue #1626 · pgjdbc/pgjdbc

I'm submitting a ... bug report feature request Describe the issue I'm passing the property options with the value -c timezone=America/New_York to the connection. The timezone for my session is not...

github.com

2. PostgreSQL 타임존 지정

PostgreSQL 타임존 지정

- PostgreSQL 세션/서버 타임존을 지정을 합니다. 이를 지정하지 않으면, 서버 OS 타임존을 따라갑니다.

2.1. 현재 타임존 확인

현재 타임존 확인

- 지정된 타임존의 시간을 확인하고, 현재 NOW() 함수와 타임존을 지정한 시간을 비교하여 확인합니다.

SHOW timezone;
SELECT NOW(), NOW() AT TIME ZONE 'Asia/Seoul';

2.2. 타임존 시간 지정

타임존 시간 지정

- 세션 레벨, DB 레벨(영구), 유저 레벨(영구)에서 수행하여 다시 조회를 하면, 타임존이 반영된 NOW()가 수행이 되었습니다.

-- 세션 레벨 (둘 다 동일)
SET TIME ZONE 'Asia/Seoul';      -- SQL 표준 방식
SET timezone TO 'Asia/Seoul';    -- PostgreSQL 방식

-- DB 레벨 (영구)
ALTER DATABASE dbname SET timezone TO 'Asia/Seoul';

-- 유저 레벨 (영구)
ALTER USER username SET timezone TO 'Asia/Seoul';

3. Docker 내에 TimeZone 지정

Docker 내에 TimeZone 지정

- 컨테이너 배포 시, 빌드된 이미지를 컨테이너화 하는 과정에서 설정값을 적용합니다.
- postgresql.conf 설정 파일 내에 지정하는 것이 베스트이지만, 배포 시에 설정값을 포함하여서 배포를 합니다.
- 아래와 같이 docker compose 과정에서 compose.yaml 파일을 수정하여 TimeZone을 지정합니다.

services:
  db:
    image: postgres:17.9
    container_name: xxxxx-db
    command: postgres -c timezone=Asia/Seoul   # PostgreSQL 서버 타임존 강제 지정
    environment:
      - TZ=Asia/Seoul    # 컨테이너 OS 타임존
      - PGTZ=Asia/Seoul  # psql 클라이언트 타임존
    ports:
      - "5432:5432"
    env_file:
      - ./env/.env.db
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: always

  api:
    image: xxxxx
    container_name: xxxxx-api
    depends_on:
      - db
    restart: unless-stopped
    volumes:
      - "./uploads:/uploads"
    environment:
      - TZ=Asia/Seoul    # JVM 타임존 → Hibernate가 이걸 기준으로 저장

오늘도 감사합니다.

[Java] 채널톡 이해하고 활용하기 -2: 채널톡 Open API 키 발급 및 통신 방법

adjh54 — Fri, 8 May 2026 20:00:03 +0900

해당 글에서는 채널톡 Open API와 서버 간의 통신을 통해서 채널톡에 대한 정보를 조회하는 방법과 키 발급방법에 대해서 알아봅니다

[참고] 이전에 채널톡을 웹 페이지에 연결하는 방법에 대해 궁금하시면 이전글을 참고하시면 도움이 됩니다.

[React] 채널톡 이해하고 활용하기 -1: 연결 및 채팅 기능 확인, @channel.io/channel-web-sdk-loader

해당 글에서는 채널톡을 연결하고 채팅 기능을 활용하는 방법에 대해서 작성한 글입니다 1) 채널톡 채널톡- 올인원 AI 비즈니스 메신저로, 채팅 상담과 팀 메신저, 마케팅 메시지, 인터넷 전화

adjh54.tistory.com

1) 채널톡

채널톡
- 올인원 AI 비즈니스 메신저로, 채팅 상담과 팀 메신저, 마케팅 메시지, 인터넷 전화(미트), 시나리오형 챗봇(서포트봇), AI 에이전트(ALF) 등의 기능을 제공합니다.
- 주로 고객과 채팅 상담에 이용하고 관리하기 위한 용도로 이용을 합니다.

1. 채널톡 Open API를 이용하려면

채널톡 Open API를 이용하려면

- Open API를 이용하기 위해서는 기본적으로 ‘유료 플랜’을 이용해야 합니다.

무료 플랜으로 유료 플랜 기능을 일부 사용이 가능하지만, Open API 연동과 관련되어서는 사용이 불가능하며, ‘유료플랜’을 구매해야 합니다.

가격 안내 - 비즈니스 단계에 따른 합리적인 가격

작은 팀부터 엔터프라이즈 기업까지 단계에 맞는 플랜을 선택하세요.

channel.io

2) 채널톡 키 발급받기

채널톡 키 발급받기

- 채널톡의 Open API와 연동을 하기 위해서는 Access Key, Access Secret을 발급받아야 합니다

1. 채널톡에서 설정 > 보안 및 개발 > API > 새 인증 키 만들기 버튼을 누릅니다

2. 새 인증키를 만듭니다.

3. 아래와 같이 Access Key, Access Secret이 발급되었습니다

3) 채널톡 OPEN API

What is Open API

The Channel Open API allows third party developers to build applications that interact with Channel in more complex ways than the integrations we currently provide. By using the API, developers can freely build sophisticated interactions and seamless pipel

docs.channel.io

1. API 대분류 목록

API 대분류 목록

- API의 대분류에서는 크게 Bot, UserChat, Channel 등의 Open API 정보를 가져올 수 있는 것으로 확인되었습니다.

대분류	설명
Channel	채널(워크스페이스) 자체의 정보를 관리합니다. 채널 이름, 설정, 도메인 등 채널톡 계정 단위의 메타 정보를 조회합니다.
User	채널톡에 접속하는 고객(방문자/회원) 정보를 관리합니다. 고객 목록 조회, 상세 조회, 고객 속성(프로필) 등을 다룹니다.
UserChat	고객과 상담원 간의 1:1 채팅 대화를 관리합니다. 채팅 생성, 목록/상세 조회, 세션 조회, 메시지 전송/조회 등 상담의 핵심 기능입니다.
Manager	상담원(매니저) 정보를 관리합니다. 채널에 소속된 상담 담당자 목록 조회, 상세 조회 등을 제공합니다.
Bot	채널톡 내 봇 프로필을 관리합니다. 봇을 통한 자동 메시지 발송 시 사용되는 봇 목록 조회, 상세 조회 등을 제공합니다.
Group	내부 팀(상담원 간) 그룹 채팅을 관리합니다. 그룹 생성/조회/수정, 그룹 메시지 발송, 파일 URL(15분 signed URL) 조회 등을 다룹니다.
Event	고객의 행동 로그(이벤트 트래킹)를 관리합니다. PageView, UserChatOpen, MarketingView 등 웹사이트/앱 내 사용자 행동을 기록하고 조회합니다.
Marketing	마케팅 캠페인을 관리합니다. 팝업, 인앱 메시지 등 마케팅 메시지의 생성/조회/상태 관리(draft, active, inactive, completed)를 다룹니다.
Webhook	웹훅 설정을 관리합니다. 특정 이벤트(채팅 생성, 메시지 수신 등) 발생 시 외부 URL로 알림을 보내기 위한 웹훅 CRUD를 제공합니다.
Plugin	채널톡 SDK 연동에 필요한 플러그인을 관리합니다. 플러그인 키(pluginKey) 발급, 채팅 버튼 UI 설정, 프로필봇 설정 등을 다룹니다.
Redirection	리다이렉션 URL을 생성합니다. 외부 링크에서 채널톡 특정 채팅이나 페이지로 자동 이동시키기 위한 signed URL을 발급합니다.

종합 API 목록

분류	Method	Path	설명
Bot	GET	/bots	봇 목록 조회
Bot	GET	/bots/{botId}	봇 상세 조회
Bot	POST	/bots	봇 생성
Bot	DELETE	/bots/{botId}	봇 삭제

UserChat	GET	/user-chats	고객 채팅 목록 조회
UserChat	GET	/user-chats/{userChatId}	고객 채팅 상세 조회
UserChat	GET	/user-chats/{userChatId}/sessions	고객 채팅 세션 조회
UserChat	GET	/user-chats/{userChatId}/messages	고객 채팅 메시지 조회
UserChat	POST	/user-chats/{userChatId}/messages	고객 채팅 메시지 전송 (봇)
UserChat	GET	/user-chats/{userChatId}/messages/file	고객 채팅 파일 URL 조회 (15분 signed URL)
UserChat	PATCH	/user-chats/{userChatId}/invite	고객 채팅에 상담원 초대
UserChat	PATCH	/user-chats/{userChatId}/close	고객 채팅 종료
UserChat	DELETE	/user-chats/{userChatId}	고객 채팅 삭제

Channel	GET	/channel	채널 정보 조회

Manager	GET	/managers	상담원 목록 조회
Manager	GET	/managers/{managerId}	상담원 상세 조회

User	GET	/users	고객 목록 조회
User	GET	/users/{userId}	고객 상세 조회 (userId)
User	GET	/users/@{memberId}	고객 상세 조회 (memberId)
User	PATCH	/users/{userId}	고객 정보 수정
User	PUT	/users/@{memberId}	고객 Upsert (없으면 생성, 있으면 수정)
User	DELETE	/users/{userId}	고객 삭제 (userId)
User	DELETE	/users/@{memberId}	고객 삭제 (memberId)
User	POST	/users/{userId}/block	고객 차단
User	DELETE	/users/{userId}/block	고객 차단 해제
User	POST	/users/{userId}/user-chats	고객 채팅 생성
User	GET	/users/{userId}/user-chats	고객의 채팅 목록 조회
User	GET	/users/{userId}/events	고객 이벤트(행동로그) 조회
User	PUT	/users/@{memberId}/session-jwt/issue	고객 세션 JWT 토큰 발급
User	-	/users/{userId}/touch	고객 Touch (2025.12.5 이후 사용 가능)

기타 내용은 API 문서에서 확인하실 수 있습니다.

What is Open API

developers.channel.io

2. Bot

Bot

- 채널톡 내 봇 프로필을 관리합니다. 봇을 통한 자동 메시지 발송 시 사용되는 봇 목록 조회, 상세 조회 등을 제공합니다.

No	Method	Path	설명
1	GET	/bots	봇 목록 조회
2	GET	/bots/{botId}	봇 상세 조회
3	POST	/bots	봇 생성
4	DELETE	/bots/{botId}	봇 삭제

3. UserChat

UserChat

- 고객과 상담원 간의 1:1 채팅 대화를 관리합니다. 채팅 생성, 목록/상세 조회, 세션 조회, 메시지 전송/조회 등 상담의 핵심 기능입니다.

No	Method	Paths	설명
1	GET	/user-chats	고객 채팅 목록 조회
2	GET	/user-chats/{userChatId}	고객 채팅 상세 조회
3	GET	/user-chats/{userChatId}/sessions	고객 채팅 세션 조회
4	GET	/user-chats/{userChatId}/messages	고객 채팅 메시지 조회
5	POST	/user-chats/{userChatId}/messages	고객 채팅 메시지 전송 (봇)
6	GET	/user-chats/{userChatId}/messages/file	고객 채팅 파일 URL 조회 (15분 signed URL)
7	PATCH	/user-chats/{userChatId}/invite	고객 채팅에 상담원 초대
8	PATCH	/user-chats/{userChatId}/close	고객 채팅 종료
9	DELETE	/user-chats/{userChatId}	고객 채팅 삭제

5. Channel

Channel

- 채널(워크스페이스) 자체의 정보를 관리합니다. 채널 이름, 설정, 도메인 등 채널톡 계정 단위의 메타 정보를 조회합니다.

No	Method	Path	설명
1	GET	/channel	채널 정보 조회

6. Manager

Manager

- 상담원(매니저) 정보를 관리합니다. 채널에 소속된 상담 담당자 목록 조회, 상세 조회 등을 제공합니다.

No	Method	Path	설명
1	GET	/managers	상담원 목록 조회
2	GET	/managers/{managerId}	상담원 상세 조회

7. User

User

- 채널톡에 접속하는 고객(방문자/회원) 정보를 관리합니다. 고객 목록 조회, 상세 조회, 고객 속성(프로필) 등을 다룹니다.

No	Method	Path	설명
1	GET	/users	고객 목록 조회
2	GET	/users/{userId}	고객 상세 조회 (userId)
3	GET	/users/@{memberId}	고객 상세 조회 (memberId)
4	PATCH	/users/{userId}	고객 정보 수정
5	PUT	/users/@{memberId}	고객 Upsert (없으면 생성, 있으면 수정)
6	DELETE	/users/{userId}	고객 삭제 (userId)
7	DELETE	/users/@{memberId}	고객 삭제 (memberId)
8	POST	/users/{userId}/block	고객 차단
9	DELETE	/users/{userId}/block	고객 차단 해제
10	POST	/users/{userId}/user-chats	고객 채팅 생성
11	GET	/users/{userId}/user-chats	고객의 채팅 목록 조회
12	GET	/users/{userId}/events	고객 이벤트(행동로그) 조회
13	PUT	/users/@{memberId}/session-jwt/issue	고객 세션 JWT 토큰 발급
14	-	/users/{userId}/touch	고객 Touch (2025.12.5 이후 사용 가능)

4) 채널톡 OPEN API 활용하기

1. application.yml

application.yml

- 아래와 같이 yml 파일 내에 발급받은 access-key, access-secret을 추가하였습니다. 해당 방식은 .env 파일 내에서 불러오는 형태로 구성하였고, 이를 참조하는 형태입니다.

channel-talk:
  access-key: ${CHANNEL_TALK_ACCESS_KEY}
  access-secret: ${CHANNEL_TALK_ACCESS_SECRET}
  base-url: https://api.channel.io/open/v5

[참고] .env 파일로 환경정보 관리 방법

[Java] Spring Boot 환경에서 시스템 변수 .env 파일 지정 및 활용 방법

해당 글에서는 Spring Boot 개발 환경에서 .env 파일을 시스템 변수로 지정하는 방법과 이를 불러오는 다양한 방법에 대해서 알아봅니다1) Spring Boot 환경에서 .env 파일을 시스템 변수로 적용하는 이

adjh54.tistory.com

2. ChannelTalkConfig

ChannelTalkConfig

- 해당 부분에서는 RestClient를 이용하여서 ChannelTalk과 연동하기 위한 클라이언트를 구성합니다.
- 클라이언트는 채널톡과 통신을 위한 x-access-key, x-access-secret를 헤더에 포함하여 통신을 수행합니다.

import com.service.client.ChannelTalkClient;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestClient;
import org.springframework.web.client.support.RestClientAdapter;
import org.springframework.web.service.invoker.HttpServiceProxyFactory;

/**
 * 채널톡 RestClient + HttpServiceProxyFactory 설정
 *
 * @author : leejonghoon
 * @fileName : ChannelTalkClientConfig
 * @since : 26. 5. 7.
 */
@Configuration
@Slf4j
public class ChannelTalkConfig {

    @Value("${channel-talk.access-key}")
    private String accessKey;

    @Value("${channel-talk.access-secret}")
    private String accessSecret;

    @Bean
    public ChannelTalkClient channelTalkClient() {
        RestClient restClient = RestClient.builder()
                .baseUrl("<https://api.channel.io>")
                .defaultHeader("x-access-key", accessKey)
                .defaultHeader("x-access-secret", accessSecret)
                .defaultHeader("Content-Type", "application/json")
                .build();

        HttpServiceProxyFactory factory = HttpServiceProxyFactory
                .builderFor(RestClientAdapter.create(restClient))
                .build();

        ChannelTalkClient client = factory.createClient(ChannelTalkClient.class);
        return client;
    }
}

3. ChannelTalkClient

ChannelTalkClient

- 이전에 구성한 채널톡 인스턴스를 기반으로 헤더에 내용을 모두 포함하였습니다.
- 이를 기반으로 Spring Boot4에서 추가된 Service Interface Clients를 통하여 외부 통신을 수행합니다.

package com.daekyocns.homepage.service.client;

import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.service.annotation.*;

import java.util.List;
import java.util.Map;

/**
 * 채널톡 Open API HTTP Service Client
 *
 * @author : leejonghoon
 * @fileName : ChannelTalkClient
 * @since : 26. 5. 7.
 */
@HttpExchange(contentType = MediaType.APPLICATION_JSON_VALUE)
public interface ChannelTalkClient {

    /**
     * 채널 정보를 조회합니다.
     *
     * @return
     */
    @GetExchange("/open/v5/channel")
    Map<String, Object> getChannel();

    /**
     * 고객 정보를 모두 조회합니다.
     *
     * @param after
     * @param limit
     * @return
     */
    @GetExchange("/open/v5/users")
    Map<String, Object> getUsers(
            @RequestParam(required = false) String after,
            @RequestParam(defaultValue = "30") int limit
    );

    /**
     * 고객 정보를 상세 조회합니다.
     *
     * @param userId
     * @return
     */
    @GetExchange("/open/v5/users/{userId}")
    Map<String, Object> getUser(@PathVariable String userId);

    /**
     * 사용자의 이벤트(행동로그)를 조회합니다.
     *
     * @param userId
     * @param sortOrder
     * @param since
     * @param limit
     * @return
     */
    @GetExchange("/open/v5/users/{userId}/events")
    Map<String, Object> getUserEvents(
            @PathVariable String userId,
            @RequestParam(defaultValue = "desc") String sortOrder,
            @RequestParam(required = false) Long since,
            @RequestParam(defaultValue = "25") int limit
    );

    /**
     * 고객과의 채팅 정보들을 조회합니다.
     *
     * @param state
     * @param sortOrder
     * @param since
     * @param limit
     * @return
     */
    @GetExchange("/open/v5/user-chats")
    Map<String, Object> getUserChats(
            @RequestParam(defaultValue = "opened") String state,
            @RequestParam(defaultValue = "desc") String sortOrder,
            @RequestParam(required = false) String since,
            @RequestParam(defaultValue = "30") int limit
    );

    /**
     * 고객과의 채팅 정보를 상세 조회합니다.
     *
     * @param userChatId
     * @return
     */
    @GetExchange("/open/v5/user-chats/{userChatId}")
    Map<String, Object> getUserChat(@PathVariable String userChatId);

    /**
     * 사용자와의 채팅 세션을 조회합니다.
     *
     * @param userChatId
     * @return
     */
    @GetExchange("/open/v5/user-chats/{userChatId}/sessions")
    Map<String, Object> getUserChatSessions(@PathVariable String userChatId);

    /**
     * 사용자와의 채팅을 생성합니다.
     *
     * @param userId
     * @return
     */
    @PostExchange("/open/v5/users/{userId}/user-chats")
    Map<String, Object> createUserChat(@PathVariable String userId);

    /**
     * 사용자와의 메시지 정보를 조회합니다.
     *
     * @param userChatId
     * @param since
     * @param limit
     * @return
     */
    @GetExchange("/open/v5/user-chats/{userChatId}/messages")
    Map<String, Object> getUserChatMessages(
            @PathVariable String userChatId,
            @RequestParam(required = false) String since,
            @RequestParam(defaultValue = "50") int limit
    );

    /**
     * 상담원(Manager)들을 조회합니다.
     *
     * @return
     */
    @GetExchange("/open/v5/managers")
    Map<String, Object> getManagers();

    /**
     * 상담원(Manager)에 대해 상세히 조회합니다.
     *
     * @param managerId
     * @return
     */
    @GetExchange("/open/v5/managers/{managerId}")
    Map<String, Object> getManager(@PathVariable String managerId);

    /**
     * 봇(Bot) 정보들을 조회합니다.
     *
     * @param since
     * @param limit
     * @return
     */
    @GetExchange("/open/v5/bots")
    Map<String, Object> getBots(
            @RequestParam(required = false) Long since,
            @RequestParam(defaultValue = "25") int limit
    );

    /**
     * 봇(Bot) 정보를 상세 조회합니다.
     *
     * @param botId
     * @return
     */
    @GetExchange("/open/v5/bots/{botId}")
    Map<String, Object> getBot(@PathVariable String botId);

    /**
     * 웹훅 목록을 조회합니다.
     *
     * @param since
     * @param limit
     * @return
     */
    @GetExchange("/open/v5/webhooks")
    Map<String, Object> getWebhooks(
            @RequestParam(required = false) Long since,
            @RequestParam(defaultValue = "25") int limit
    );

    /**
     * 웹훅 정보를 상세 조회합니다.
     *
     * @param webhookId
     * @return
     */
    @GetExchange("/open/v5/webhooks/{webhookId}")
    Map<String, Object> getWebhook(@PathVariable String webhookId);

    /**
     * 웹훅을 생성합니다.
     *
     * @param body
     * @return
     */
    @PostExchange("/open/v5/webhooks")
    Map<String, Object> createWebhook(@RequestBody Map<String, Object> body);

    /**
     * 웹훅 정보를 수정합니다.
     *
     * @param webhookId
     * @param body
     * @return
     */
    @PutExchange("/open/v5/webhooks/{webhookId}")
    Map<String, Object> updateWebhook(@PathVariable String webhookId, @RequestBody Map<String, Object> body);

    /**
     * 웹훅을 삭제합니다.
     *
     * @param webhookId
     * @return
     */
    @DeleteExchange("/open/v5/webhooks/{webhookId}")
    Map<String, Object> deleteWebhook(@PathVariable String webhookId);

    /**
     * 캠페인(마케팅) 목록을 조회합니다.
     *
     * @param since
     * @param limit
     * @param states draft|active|inactive|completed
     * @return
     */
    @GetExchange("/open/v5/mkt/campaigns")
    Map<String, Object> getCampaigns(
            @RequestParam(required = false) Long since,
            @RequestParam(defaultValue = "25") int limit,
            @RequestParam(required = false) List<String> states
    );

    /**
     * 그룹 메시지의 파일 URL을 조회합니다. (15분 signed URL)
     *
     * @param groupId
     * @param key
     * @return
     */
    @GetExchange("/open/v5/groups/{groupId}/messages/file")
    Map<String, Object> getGroupFileUrl(
            @PathVariable String groupId,
            @RequestParam String key
    );
}

[참고] Service Interface Clients에 대해 궁금하시면 아래의 글을 참고하시면 도움이 됩니다.

[Trend] Spring Boot 4 Release Note 읽어보기

해당 글에서는 Spring Boot 4가 출시되어 주요 내용에 대한 Release Note를 읽어보기 위해 작성한 글입니다. 1) Spring Boot 4 Spring Boot 4- 2025년 11월 공식 릴리스된 Spring Boot의 메이저 버전 업그레이드로,

adjh54.tistory.com

4. ChannelTalkService

ChannelTalkService

- 외부 통신 처리 이후에 비즈니스 로직을 처리하기 위한 Service 레이어를 구성하였습니다.
- 해당 경우 비즈니스 로직을 처리하기 위한 클래스로 사용이 됩니다.

package com.service;

import com.service.client.ChannelTalkClient;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

import java.util.List;
import java.util.Map;

/**
 * 채널톡 비즈니스 로직 처리 Service
 *
 * @author : leejonghoon
 * @fileName : ChannelTalkService
 * @since : 26. 5. 7.
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class ChannelTalkService {

    private final ChannelTalkClient channelTalkClient;

    public Map<String, Object> getChannel() {
        return channelTalkClient.getChannel();
    }

    public Map<String, Object> getUsers(String after, int limit) {
        return channelTalkClient.getUsers(after, limit);
    }

    public Map<String, Object> getUser(String userId) {
        return channelTalkClient.getUser(userId);
    }

    public Map<String, Object> getUserEvents(String userId, String sortOrder, Long since, int limit) {
        return channelTalkClient.getUserEvents(userId, sortOrder, since, limit);
    }

    public Map<String, Object> getUserChats(String state, String sortOrder, String since, int limit) {
        return channelTalkClient.getUserChats(state, sortOrder, since, limit);
    }

    public Map<String, Object> getUserChat(String userChatId) {
        return channelTalkClient.getUserChat(userChatId);
    }

    public Map<String, Object> getUserChatSessions(String userChatId) {
        return channelTalkClient.getUserChatSessions(userChatId);
    }

    public Map<String, Object> createUserChat(String userId) {
        return channelTalkClient.createUserChat(userId);
    }

    public Map<String, Object> getUserChatMessages(String userChatId, String since, int limit) {
        return channelTalkClient.getUserChatMessages(userChatId, since, limit);
    }

    public Map<String, Object> getManagers() {
        return channelTalkClient.getManagers();
    }

    public Map<String, Object> getManager(String managerId) {
        return channelTalkClient.getManager(managerId);
    }

    public Map<String, Object> getBots(Long since, int limit) {
        return channelTalkClient.getBots(since, limit);
    }

    public Map<String, Object> getBot(String botId) {
        return channelTalkClient.getBot(botId);
    }

    public Map<String, Object> getWebhooks(Long since, int limit) {
        return channelTalkClient.getWebhooks(since, limit);
    }

    public Map<String, Object> getWebhook(String webhookId) {
        return channelTalkClient.getWebhook(webhookId);
    }

    public Map<String, Object> createWebhook(Map<String, Object> body) {
        return channelTalkClient.createWebhook(body);
    }

    public Map<String, Object> updateWebhook(String webhookId, Map<String, Object> body) {
        return channelTalkClient.updateWebhook(webhookId, body);
    }

    public Map<String, Object> deleteWebhook(String webhookId) {
        return channelTalkClient.deleteWebhook(webhookId);
    }

    public Map<String, Object> getCampaigns(Long since, int limit, List<String> states) {
        return channelTalkClient.getCampaigns(since, limit, states);
    }

    public Map<String, Object> getGroupFileUrl(String groupId, String key) {
        return channelTalkClient.getGroupFileUrl(groupId, key);
    }
}

5. ChannelTalkController

ChannelTalkController

- 아래와 같은 정보들을 조회하는 엔드포인트를 구성하였습니다.

No	Method	Path	설명
1	GET	/channel	채널 정보 조회
2	GET	/users	고객 목록 조회
3	GET	/users/{userId}	고객 상세 조회
4	GET	/users/{userId}/events	사용자 이벤트(행동로그) 조회
5	GET	/user-chats	고객 채팅 목록 조회
6	GET	/user-chats/{userChatId}	고객 채팅 상세 조회
7	GET	/user-chats/{userChatId}/sessions	고객 채팅 세션 조회
8	POST	/users/{userId}/user-chats	고객 채팅 생성
9	GET	/user-chats/{userChatId}/messages	고객 채팅 메시지 조회
10	GET	/managers	상담원 목록 조회
11	GET	/managers/{managerId}	상담원 상세 조회
12	GET	/bots	봇 목록 조회
13	GET	/bots/{botId}	봇 상세 조회
14	GET	/tags	태그 목록 조회
15	GET	/webhooks	웹훅 목록 조회
16	GET	/webhooks/{webhookId}	웹훅 상세 조회
17	POST	/webhooks	웹훅 생성
18	PUT	/webhooks/{webhookId}	웹훅 수정
19	DELETE	/webhooks/{webhookId}	웹훅 삭제
20	GET	/campaigns	캠페인(마케팅) 목록 조회
21	GET	/groups/{groupId}/messages/file	그룹 메시지 파일 URL 조회 (15분 signed URL)

package com.controller;

import com.model.common.ApiResponseWrapper;
import com.model.common.SuccessCode;
import com.service.ChannelTalkService;
import lombok.RequiredArgsConstructor;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;
import java.util.Map;

/**
 * 채널톡 Open API Controller
 *
 * @author leejonghoon
 * @since 26. 5. 7.
 */
@RestController
@RequestMapping("/api/channelTalk")
@RequiredArgsConstructor
public class ChannelTalkController {

    private final ChannelTalkService channelTalkService;

    /**
     * 공통 응답 헬퍼
     *
     * @param result
     * @return
     */
    private ResponseEntity<ApiResponseWrapper<Map<String, Object>>> ok(Map<String, Object> result) {
        return new ResponseEntity<>(
                ApiResponseWrapper.<Map<String, Object>>builder()
                        .result(result)
                        .resultCode(SuccessCode.SELECT_SUCCESS.getStatus())
                        .resultMsg(SuccessCode.SELECT_SUCCESS.getMessage())
                        .build(),
                HttpStatus.OK
        );
    }

    // ─── 채널 정보 ───────────────────────────────────────

    /**
     * 채널 정보를 조회합니다.
     *
     * @return
     */
    @GetMapping("/channel")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getChannel() {
        return ok(channelTalkService.getChannel());
    }

    // ─── 고객(User) ──────────────────────────────────────

    /**
     * 고객 목록을 조회합니다.
     *
     * @param after
     * @param limit
     * @return
     */
    @GetMapping("/users")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getUsers(
            @RequestParam(required = false) String after,
            @RequestParam(defaultValue = "30") int limit
    ) {
        return ok(channelTalkService.getUsers(after, limit));
    }

    /**
     * 고객 정보를 상세 조회합니다.
     *
     * @param userId
     * @return
     */
    @GetMapping("/users/{userId}")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getUser(@PathVariable String userId) {
        return ok(channelTalkService.getUser(userId));
    }

    /**
     * 사용자의 이벤트(행동로그)를 조회합니다.
     *
     * @param userId
     * @param sortOrder
     * @param since
     * @param limit
     * @return
     */
    @GetMapping("/users/{userId}/events")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getUserEvents(
            @PathVariable String userId,
            @RequestParam(defaultValue = "desc") String sortOrder,
            @RequestParam(required = false) Long since,
            @RequestParam(defaultValue = "25") int limit
    ) {
        return ok(channelTalkService.getUserEvents(userId, sortOrder, since, limit));
    }

    // ─── 고객 채팅(UserChat) ──────────────────────────────

    /**
     * 고객과의 채팅 목록을 조회합니다.
     *
     * @param state
     * @param sortOrder
     * @param since
     * @param limit
     * @return
     */
    @GetMapping("/user-chats")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getUserChats(
            @RequestParam(defaultValue = "opened") String state,
            @RequestParam(defaultValue = "desc") String sortOrder,
            @RequestParam(required = false) String since,
            @RequestParam(defaultValue = "30") int limit
    ) {
        return ok(channelTalkService.getUserChats(state, sortOrder, since, limit));
    }

    /**
     * 고객과의 채팅 정보를 상세 조회합니다.
     *
     * @param userChatId
     * @return
     */
    @GetMapping("/user-chats/{userChatId}")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getUserChat(@PathVariable String userChatId) {
        return ok(channelTalkService.getUserChat(userChatId));
    }

    /**
     * 고객과의 채팅 세션을 조회합니다.
     *
     * @param userChatId
     * @return
     */
    @GetMapping("/user-chats/{userChatId}/sessions")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getUserChatSessions(@PathVariable String userChatId) {
        return ok(channelTalkService.getUserChatSessions(userChatId));
    }

    /**
     * 고객과의 채팅을 생성합니다.
     *
     * @param userId
     * @return
     */
    @PostMapping("/users/{userId}/user-chats")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> createUserChat(@PathVariable String userId) {
        return ok(channelTalkService.createUserChat(userId));
    }

    // ─── 채팅 메시지 ──────────────────────────────────────

    /**
     * 고객 채팅의 메시지를 조회합니다.
     *
     * @param userChatId
     * @param since
     * @param limit
     * @return
     */
    @GetMapping("/user-chats/{userChatId}/messages")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getUserChatMessages(
            @PathVariable String userChatId,
            @RequestParam(required = false) String since,
            @RequestParam(defaultValue = "50") int limit
    ) {
        return ok(channelTalkService.getUserChatMessages(userChatId, since, limit));
    }

    // ─── 상담원(Manager) ──────────────────────────────────

    /**
     * 상담원(Manager) 목록을 조회합니다.
     *
     * @return
     */
    @GetMapping("/managers")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getManagers() {
        return ok(channelTalkService.getManagers());
    }

    /**
     * 상담원(Manager) 정보를 상세 조회합니다.
     *
     * @param managerId
     * @return
     */
    @GetMapping("/managers/{managerId}")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getManager(@PathVariable String managerId) {
        return ok(channelTalkService.getManager(managerId));
    }

    // ─── 봇(Bot) ──────────────────────────────────────────

    /**
     * 봇(Bot) 목록을 조회합니다.
     *
     * @param since
     * @param limit
     * @return
     */
    @GetMapping("/bots")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getBots(
            @RequestParam(required = false) Long since,
            @RequestParam(defaultValue = "25") int limit
    ) {
        return ok(channelTalkService.getBots(since, limit));
    }

    /**
     * 봇(Bot) 정보를 상세 조회합니다.
     *
     * @param botId
     * @return
     */
    @GetMapping("/bots/{botId}")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getBot(@PathVariable String botId) {
        return ok(channelTalkService.getBot(botId));
    }

    // ─── 태그 ─────────────────────────────────────────────

    /**
     * 태그 목록을 조회합니다.
     *
     * @return
     */
    @GetMapping("/tags")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getTags() {
        return ok(channelTalkService.getTags());
    }

    // ─── 웹훅(Webhook) ────────────────────────────────────

    /**
     * 웹훅 목록을 조회합니다.
     *
     * @param since
     * @param limit
     * @return
     */
    @GetMapping("/webhooks")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getWebhooks(
            @RequestParam(required = false) Long since,
            @RequestParam(defaultValue = "25") int limit
    ) {
        return ok(channelTalkService.getWebhooks(since, limit));
    }

    /**
     * 웹훅 정보를 상세 조회합니다.
     *
     * @param webhookId
     * @return
     */
    @GetMapping("/webhooks/{webhookId}")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getWebhook(@PathVariable String webhookId) {
        return ok(channelTalkService.getWebhook(webhookId));
    }

    /**
     * 웹훅을 생성합니다.
     *
     * @param body
     * @return
     */
    @PostMapping("/webhooks")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> createWebhook(@RequestBody Map<String, Object> body) {
        return ok(channelTalkService.createWebhook(body));
    }

    /**
     * 웹훅 정보를 수정합니다.
     *
     * @param webhookId
     * @param body
     * @return
     */
    @PutMapping("/webhooks/{webhookId}")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> updateWebhook(
            @PathVariable String webhookId,
            @RequestBody Map<String, Object> body
    ) {
        return ok(channelTalkService.updateWebhook(webhookId, body));
    }

    /**
     * 웹훅을 삭제합니다.
     *
     * @param webhookId
     * @return
     */
    @DeleteMapping("/webhooks/{webhookId}")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> deleteWebhook(@PathVariable String webhookId) {
        return ok(channelTalkService.deleteWebhook(webhookId));
    }

    // ─── 캠페인(Campaign) ─────────────────────────────────

    /**
     * 캠페인(마케팅) 목록을 조회합니다.
     *
     * @param since
     * @param limit
     * @param states draft|active|inactive|completed
     * @return
     */
    @GetMapping("/campaigns")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getCampaigns(
            @RequestParam(required = false) Long since,
            @RequestParam(defaultValue = "25") int limit,
            @RequestParam(required = false) List<String> states
    ) {
        return ok(channelTalkService.getCampaigns(since, limit, states));
    }

    // ─── 그룹(Group) 파일 URL ─────────────────────────────

    /**
     * 그룹 메시지의 파일 URL을 조회합니다. (15분 signed URL)
     *
     * @param groupId
     * @param key
     * @return
     */
    @GetMapping("/groups/{groupId}/messages/file")
    public ResponseEntity<ApiResponseWrapper<Map<String, Object>>> getGroupFileUrl(
            @PathVariable String groupId,
            @RequestParam String key
    ) {
        return ok(channelTalkService.getGroupFileUrl(groupId, key));
    }
}

6. 일부 결과 확인

일부 결과 확인

- IntelliJ의 HTTP Client를 활용하여서 API 호출 테스트를 수행합니다.

아래와 같이 채널 목록을 조회하였을 때, 정상적으로 출력이 됨을 확인하였습니다.

[참고] HTTP Client 활용 방법

[IntelliJ] HTTP Client 사용하기 : Postman 대체하기

해당 글에서는 Postman을 대체하여 클라이언트에서 서버로 API를 전송(Request)하고 반환(Response)을 받는 테스트에 사용이 되는 HTTP Client에 대해서 공유합니다. 1) 문제사항 및 적용 계기 Client에서

adjh54.tistory.com

화면상에서 출력도 채널정보, 상담원, 고객 채팅, 봇에 대해서도 출력이 잘됨을 확인하였습니다.

오늘도 감사합니다.

[React] 채널톡 이해하고 활용하기 -1: 연결 및 채팅 기능 확인, @channel.io/channel-web-sdk-loader

adjh54 — Thu, 7 May 2026 20:00:43 +0900

해당 글에서는 채널톡을 연결하고 채팅 기능을 활용하는 방법에 대해서 작성한 글입니다

1) 채널톡

채널톡

- 올인원 AI 비즈니스 메신저로, 채팅 상담과 팀 메신저, 마케팅 메시지, 인터넷 전화(미트), 시나리오형 챗봇(서포트봇), AI 에이전트(ALF) 등의 기능을 제공합니다.
- 주로 고객과 채팅 상담을 이용하고 관리하기 위한 용도로 이용을 합니다.

고객상담의 미래는 AI 입니다 - 채널톡

올인원 AI 메신저 채널톡과 함께 준비하세요.

channel.io

2) 채널톡 연결 -1 : 키 조회

1. 공식사이트에 접근 및 채널 목록으로 가기 버튼을 누릅니다

2. 아래와 같이 출력이 됩니다

3. 일반 설정 > 버튼 설치 및 설정 > 채널톡 버튼 설치를 누릅니다.

4. Plugin Key를 확인합니다.

참고 사이트

채널톡 버튼 설정

심혈을 기울여 만든 우리 사이트에 채널톡 버튼이 잘 자연스럽게 녹아 들도록 위치를 수정하거나 커스텀 버튼을 통해 브랜드의 개성을 보여주세요.

docs.channel.io

3) 채널톡 연결 -2 : 라이브러리 설치

1. @channel.io/channel-web-sdk-loader

@channel.io/channel-web-sdk-loader

# npm 설치
$ npm i @channel.io/channel-web-sdk-loader

# or

# yarn 설치
$ yarn add @channel.io/channel-web-sdk-loader

2. 채널톡 로드

채널톡 로드

- 아래와 같이 확인된 플러그인 키를 추가하고, 불러오고 성공여부를 반환받습니다.

import * as ChannelService from '@channel.io/channel-web-sdk-loader';

export const App = () => {
	// 채널톡 플러그인 키를 불러옵니다
	const CHANNEL_TALK_PLUG_IN_KEY = import.meta.env.VITE_CHANNEL_TALK_PLUG_IN

	useEffect(() => {
		ChannelService.loadScript();
		ChannelService.boot(
			{ pluginKey: CHANNEL_TALK_PLUG_IN_KEY },
			function onBoot(error: any, user: any) {
				if (error) {
					console.error('채널톡 boot 실패:', error);
				} else {
					console.log('채널톡 boot 성공:', user);
				}
			}
		);
	}, []);
	return (
		<>
		</>
	)

3. 결과 확인 -1 : 문의하기

결과 확인 -1 : 문의하기

- 별도의 위치를 지정하지 않더라도 아래와 같이 가장 오른쪽 하단에 모든 페이지에 들어가 있음을 확인하였습니다.

3.1. 화면상에 출력

3.2. 대화 확인

대화 확인

- 아래와 같이 대화창이 출력이 됩니다.

3.3. 아래와 같이 문의를 합니다.

3.4. 채널톡 내에서 확인

채널톡 내에서 확인

- 채널톡 내에 메시지가 전달됨을 확인하였습니다.

4. 결과 확인 -2 : 답변 및 답변 확인

4.1. 나에게 배정을 하고 답변을 했습니다

4.2. 아래와 같이 사용자에 답변이 전달됨을 확인하였습니다

4) 채널톡 심화 활용하기

1. 특정 페이지에서만 출력

특정 페이지에서만 출력

- 현재 구조에서는 모든 페이지에서 채널톡 아이콘이 보이고 있습니다. 그렇기에 특정 페이지에서 안 보이도록 하는 함수를 이용합니다.
- 단, 해당 함수는 전역으로 관리되기에, hideChannelButton()를 호출 한 뒤, showChannelButton()를 호출하지 않으면 채널톡 아이콘은 보이지 않습니다.

// 특정 페이지에서 숨기기
ChannelService.hideChannelButton();

// 다시 보이기
ChannelService.showChannelButton();

채널톡 사이트 내에서 일반 설정 > 버튼 설치 및 설정 > 고급 설정 내에서 ‘화이트 리스트’로 특정 도메인에서만 채널톡 버튼이 보이도록 할 수 있습니다.

2. 채널톡 아이콘 모양이나 위치를 변경

채널톡 아이콘 모양이나 위치를 변경

- 상단으로 이동 아이콘과 같이 겹칠 수 있기에, 채널톡 위치를 변경합니다
- 채널톡 접속 > 채널 설정 > 일반 설정 > 버튼 설치 및 설정을 들어가면 아래와 같이 아이콘 모양이나 위치를 변경할 수 있습니다

아래와 같이 위치를 변경이 되었습니다.

3. 버튼과 채널톡 채팅 연결

버튼과 채널톡 채팅 연결

- 나만의 버튼을 눌렀을 때 채널톡이 열리도록 하는 방식입니다.
- 아래의 코드와 같이 ChannelService.showMessenger(); 를 이용하여서 연결을 합니다.

import * as ChannelService from '@channel.io/channel-web-sdk-loader';

export default function Page() {
	const handleOpenChat = () => {
		ChannelService.showMessenger();
	};
	return (
	<button onClick={handleOpenChat}>솔루션 도입 문의</button>
	)
}

오늘도 감사합니다.

[RN/오류노트] error: call to consteval function 'fmt::basic_format_string

adjh54 — Sat, 2 May 2026 15:27:42 +0900

React Native 환경에서 XCode 업데이트 이후에 발생하는 오류에 대해서 이를 해결하는 방법에 대해서 알아봅니다.

1) 문제점

문제점

- 최근에 XCode 26.4.1 버전으로 업데이트를 한 이후에 아래와 같은 문제가 발생하였습니다.

- /workspace/3ha/3ha-chon-calc-quiz/ios/Pods/fmt/include/fmt/format-inl.h:59:24 Call to consteval function 'fmt::basic_format_string<char, fmt::basic_string_view<char> &, const char (&)[3]>::basic_format_string<FMT_COMPILE_STRING, 0>' is not a constant expression

2) 해결방법

해결방법

- 현재의 문제는 fmt 라이브러리의 consteval / C++20 기능이 구버전 C++ 표준으로 컴파일되면서 발생한 충돌하는 문제입니다.

- fmt 라이브러리 최신 버전은 consteval 키워드를 사용하는데, 이건 C++20에서 도입된 문법이기에 이에 맞지않아 발생하는 문제입니다.
- 현재에서 발생한 에러에서는 Xcode가 해당 파일을 C++14 또는 C++16 이하로 컴파일하려 했기 때문에 발생하는 문제이며, consteval을 모르는 컴파일러 버전 기준으로 해석하다 보니 "상수 표현식이 아니다"라는 엉뚱한 에러가 발생하는 것입니다.

그렇기에 아래와 같이 Podfile 내에 수정을 하였습니다.

- CLANG_CXX_LANGUAGE_STANDARD = 'c++17’ : C++ 언어 표준을 C++17로 명시하였습니다.
- CLANG_CXX_LIBRARY = 'libc++’ : 표준 라이브러리 구현체를 libc++로 강제하였습니다.

- fmt 최신 버전은 최소 C++17 이상을 요구하므로, 명시적으로 올려줘야 정상 컴파일이 됩니다.

 installer.pods_project.targets.each do |target|
      target.build_configurations.each do |config|
        config.build_settings['CLANG_CXX_LIBRARY'] = 'libc++'
        if target.name == 'fmt'
          target.build_configurations.each do |config|
            config.build_settings['CLANG_CXX_LANGUAGE_STANDARD'] = 'c++17'
          end
        end
      end
    end

[더 알아보기]

fmt 라이브러리는 뭘까?

- fmt는 C++에서 printf / std::string 문자열 포매팅을 타입 안전하게 해주는 라이브러리입니다.
- 주로 React Native에서는 Folly가 내부적으로 많이 써서 RN 프로젝트에서 사용이 됩니다.

https://github.com/fmtlib/fmt

3) 결과 확인

결과 확인

- 아래와 같이 정상적으로 빌드가 됨을 확인하였습니다.

오늘도 감사합니다.

[DB] PostgreSQL pgcrypto 이해하고 AES256 암복호화 활용

adjh54 — Fri, 1 May 2026 00:34:51 +0900

해당 글에서는 PostgreSQL pgcrypto 내부 모듈을 이해하고 AES256 암복호화 활용하는 방법에 대해서 알아봅니다.

1) pgcrypto

pgcrypto

- PostgreSQL 내장 확장 모듈로, DB 레벨에서 암호화/해시/난수 생성 기능을 제공합니다.
- 확장 모듈이기에 스키마 단위로 설치가 가능합니다.

2) 암호화 이해하기

[Security] 암호화/복호화 이해하기 -1 : 기초, 암호화 종류(단방향, 양방향)

해당 글에서는 암호화/복호화에 대해 이해하며 암호화의 종류에 대해 이해를 돕기 위해 작성한 글입니다. 1) 암호화(Encryption) / 복호화(Decryption)1. 암호화(Encryption) 암호화(Encryption)- ‘평문’

adjh54.tistory.com

1. 단방향 암호화

단방향 암호화(One-Way Encryption)

- 암호화만 할 수 있고 복호화할 수 없는 암호화 기술을 의미합니다. 즉, 암호화된 데이터를 원래의 평문으로 되돌릴 수 없는 방식의 암호화를 의미합니다.
- 해당 암호화 과정에서 정보가 손실되기에 한번 해시 함수를 거친 데이터는 복호화가 불가능합니다.
- 단방향 암호화는 데이터의 기밀성보다는 무결성과 인증을 보장하는데 중점을 둡니다

2. 대칭형 암호(=비공개 키 암호화)

대칭형 암호(=비공개 키 암호화)

- 평문 데이터를 암호화하거나 복호화할 때 ‘동일한 키’를 사용하는 암호화 방식을 의미합니다.
- 이 방식에서는 송신자와 수신자가 동일한 비밀 키를 공유해야 하며, 이를 이용하여 데이터를 암호화, 복호화합니다.
- 대표적인 대칭형 암호화 알고리즘으로는 AES, DES, 3DES 등이 있습니다.

3. 비 대칭형 암호화(=공개 키 암호화)

비 대칭형 암호화(=공개 키 암호화)

- 평문 데이터를 암호화할 때와 복호화할 때 ‘서로 다른 암호화 키’를 사용하는 암호화 방식을 의미합니다.
- 이 방식에서는 누구나 접근이 가능한 ‘공개 키’로 암호화를 하며, 특정 개인이 가지고 있는 ‘비밀 키’로만 복호화가 가능합니다.
- 대표적인 비 대칭형 알고리즘으로는 RSA, DSA, ECC 등이 있습니다.

2) 설치 방법

1. 설치를 합니다

설치를 합니다.

- 설치를 할 때, public 스키마가 아닌 지정된 스키마로 되어 있는지 확인해야 합니다. 일반적으로 실행을 하면 public 스키마에 확장이 설치가 됩니다.

# 확장 추가
CREATE EXTENSION IF NOT EXISTS pgcrypto;

# or 

# 확장 제거
DROP EXTENSION IF EXISTS pgcrypto;

2. 스키마 단위에서 Extension을 확인하여 설치 확인을 할 수 있습니다.

[참고] 아래와 같이 SQL문으로 확인이 가능합니다.

3) 주요 함수

1. pgcrypto 제공 함수

카테고리	함수	설명	반환 타입
General Hashing	digest(data text, type text)	해시값 생성 (md5, sha1, sha224, sha256, sha384, sha512 + OpenSSL 지원 알고리즘)	bytea
	digest(data bytea, type text)	바이너리 데이터 해시	bytea
	hmac(data text, key text, type text)	키 기반 MAC 해시	bytea
	hmac(data bytea, key bytea, type text)	바이너리 키 기반 MAC 해시	bytea
Password Hashing	crypt(password text, salt text)	crypt(3) 스타일 패스워드 해싱/검증	text
	gen_salt(type text [, iter_count integer])	솔트 생성 (des, xdes, md5, bf, sha256crypt, sha512crypt)	text
PGP 대칭키	pgp_sym_encrypt(data text, psw text [, options text])	PGP 대칭키 암호화	bytea
	pgp_sym_encrypt_bytea(data bytea, psw text [, options text])	바이너리 PGP 대칭키 암호화	bytea
	pgp_sym_decrypt(msg bytea, psw text [, options text])	PGP 대칭키 복호화	text
	pgp_sym_decrypt_bytea(msg bytea, psw text [, options text])	바이너리 PGP 대칭키 복호화	bytea
PGP 비대칭키	pgp_pub_encrypt(data text, key bytea [, options text])	공개키 암호화	bytea
	pgp_pub_encrypt_bytea(data bytea, key bytea [, options text])	바이너리 공개키 암호화	bytea
	pgp_pub_decrypt(msg bytea, key bytea [, psw text [, options text]])	개인키 복호화	text
	pgp_pub_decrypt_bytea(msg bytea, key bytea [, psw text [, options text]])	바이너리 개인키 복호화	bytea
PGP 키/Armor	pgp_key_id(bytea)	PGP 키 ID 추출 (SYMKEY, ANYKEY 특수값 반환 가능)	text
	armor(data bytea [, keys text[], values text[]])	바이너리 → PGP ASCII Armor 변환	text
	dearmor(data text)	PGP ASCII Armor → 바이너리 변환	bytea
	pgp_armor_headers(data text, key out text, value out text)	Armor 헤더 key/value 추출	setof record
Raw 암호화	encrypt(data bytea, key bytea, type text)	로우레벨 암호화 (bf, aes + cbc/cfb/ecb + pkcs/none)	bytea
	decrypt(data bytea, key bytea, type text)	로우레벨 복호화	bytea
	encrypt_iv(data bytea, key bytea, iv bytea, type text)	IV 지정 암호화	bytea
	decrypt_iv(data bytea, key bytea, iv bytea, type text)	IV 지정 복호화	bytea
Random	gen_random_bytes(count integer)	암호학적 랜덤 바이트 (최대 1024)	bytea
	gen_random_uuid()	UUID v4 생성 (PG 18에서는 코어 함수 래퍼, obsolete)	uuid
OpenSSL	fips_mode()	OpenSSL FIPS 모드 활성화 여부	boolean

F.26. pgcrypto — cryptographic functions

F.26. pgcrypto — cryptographic functions # F.26.1. General Hashing Functions F.26.2. Password Hashing Functions F.26.3. PGP Encryption Functions F.26.4. Raw Encryption …

www.postgresql.org

[ 더 알아보기 ]

IV (Initialization Vector): 초기화 벡터

- 암호화할 때 맨 처음 블록에 섞어주는 랜덤 값입니다.

[ IV가 없는 경우 ]

- 평문: "홍길동" → 암호화 → A1B2C3...
- 평문: "홍길동" → 암호화 → A1B2C3... ← 항상 동일
- 평문: "홍길동" → 암호화 → A1B2C3... ← 항상 동일

[ IV가 있는 경우]

- 평문: "홍길동" + IV(랜덤1) → 암호화 → A1B2C3...
- 평문: "홍길동" + IV(랜덤2) → 암호화 → X9Y8Z7... ← 다름
- 평문: "홍길동" + IV(랜덤3) → 암호화 → P3Q4R5... ← 다름

CBC (Cipher Block Chaining): 블록 체인 암호화

- 평문을 일정 크기의 블록으로 쪼개서 앞 블록의 암호문을 다음 블록 암호화에 연쇄적으로 섞는 방식입니다.

- 아래와 같이 수행이 됩니다.
1. 첫 번째 블록은 IV와 XOR 후 암호화
2. 두 번째 블록은 앞 블록의 암호문과 XOR 후 암호화
3. 이게 계속 체인처럼 연결되며 수행이 됩니다.

[IV] ──────────────────────────────┐
↓ │ [평문 블록1] → XOR → [암호화] → [암호문 블록1]
↓ [평문 블록2] → XOR → [암호화] → [암호문 블록2]
↓ [평문 블록3] → XOR → [암호화] → [암호문 블록3]

4) 활용 예시 : ASE256 기반 암복호화

활용 예시

- 이메일을 ASE256으로 암호화하여 저장하고, 불러오는 과정을 SQL문에서 수행하도록 처리합니다

1. 현재 사용자 데이터 확인

현재 사용자 데이터 확인

- 아래와 같은 간단한 TB_USER 테이블이 있습니다.
- 해당 컬럼 중에서 user_email 컬럼에 ASE256 암호화/복호화를 이용할 예정이며, 이를 위해서는 BYTEA 타입으로 지정을 해야 합니다.

컬럼명	NULL	PK	FK	기본 값	설명
USER_SQ	BIGSERIAL	N	✅	AUTO INCREMENT	사용자 시퀀스 (PK)
USER_ID	VARCHAR(50)	N		-	사용자 사번
USER_EMAIL	BYTEA	N			사용자 이메일
USER_PW	VARCHAR(255)	N		-	비밀번호
USE_YN	BOOLEAN	N		TRUE	사용여부
REG_TS	TIMESTAMP	N		NOW()	생성일시
MOD_TS	TIMESTAMP	N		NOW()	수정일시

ASE256 암호화의 함수의 데이터 구조

# ASE256의 암호화(입력 TEXT -> 출력 BYTEA)
pgp_sym_encrypt(data text, psw text [, options text ]) returns bytea

# ASE256의 암호화(입력 BYTEA -> 출력 BYTEA)
pgp_sym_encrypt_bytea(data bytea, psw text [, options text ]) returns bytea

# ASE256의 복호화(입력 BYTEA -> 출력 TEXT)
pgp_sym_decrypt(msg bytea, psw text [, options text ]) returns text

# ASE256의 복호화(입력 BYTEA -> 출력 BYTEA)
pgp_sym_decrypt_bytea(msg bytea, psw text [, options text ]) returns bytea

https://postgresql.kr/docs/11/pgcrypto.html

2. 데이터 암호화 및 INSERT

데이터 암호화 및 INSERT

- 위에 데이터구조 형태로 예시로 데이터를 INSERT 합니다.

INSERT INTO tb_user (user_id, user_email, user_pw, use_yn, reg_ts, mod_ts)
VALUES (
     'TEST1234',
     pgp_sym_encrypt('test1234@gmail.com', 'Symmetric Key', 'cipher-algo=aes256'),
     '54507c79d2132cf8b4817d6837a04357a164989fb73e176364f64b00be15a591',
     true,
     NOW(),
     NOW()
 );

아래와 같이 데이터 ROW가 등록되었습니다.

3. 데이터 복호화 및 SELECT

데이터 복호화 및 SELECT

- ASE256의 경우는 대칭형 암호화이기에 동일한 키를 사용해서 복호화를 합니다. 이를 기반으로 복호화를 하여서 수행합니다.

SELECT
  user_sq,
  user_id,
  pgp_sym_decrypt(user_email, 'Symmetric Key') AS user_email,
  user_pw,
  use_yn,
  reg_ts,
  mod_ts
FROM tb_user;

오늘도 감사합니다.

[Git] git-credential-osxkeychain이(가) 키체인에서 'github.com' 키 접근을 허용하고자 합니다. 해결방법

adjh54 — Thu, 30 Apr 2026 20:05:22 +0900

해당 글에서는 git-credential-osxkeychain이(가) 키체인에서 'github.com' 키 접근을 허용하고자 합니다. 매번 발생하는 오류에 대해서 해결방법에 대해 알아봅니다

1) 문제점 확인

문제점 확인

- git-credential-osxkeychain이(가) 키체인에서 'github.com' 키 접근을 허용하고자 합니다.
- 아래와 같이 SourceTree를 이용할 때 반복적으로 발생하는 문제점이 나타나고 있습니다.
- 비밀번호를 입력하고 ‘항상 허용’으로 해도 다시 접근을 하더라도 동일하게 발생하는 문제입니다.

2) 해결방법

1. Spotlight → "키체인 접근" 검색 후 실행

2. github.com 항목 찾기

3. 더블클릭 → "접근 제어" 탭 내에 불필요한 내용을 우선 제거합니다.

4. 모든 응용 프로그램이 이 항목에 접근할 수 있도록 허용을 선택합니다.

5. 앞으로 또 다시또다시 나오면 ‘항상 허용’으로 다시 저장을 하면, 또다시 나오지 않습니다.

[Git] git@github.com : Permission denied (publickey) 오류 해결 방법

adjh54 — Thu, 30 Apr 2026 20:00:41 +0900

해당 글에서는 github 내에서 발생하는 git@github.com : Permission denied (publickey) 오류에 대해서 해결하는 방법에 대해 알아봅니다

1) 문제점

문제점

- 아래와 같이 연결된 repository 내에 git pull 명령어를 수행하였을 때, 문제가 발생하고 있습니다.

git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights and the repository exists.

1. git 연결 테스트

git 연결 테스트

- 해당 repository의 문제인지 아닌지 확인을 위해 실제로도 github에 연결에 대한 테스트를 수행합니다.
- 아래와 같이 permission deined(publickey) 문제가 발생하고 있습니다.

# ssh 연결 테스트
$ ssh -T git@github.com

2) 해결방법

해결방법

- SSH 공개키가 GitHub에 등록되어 있지 않거나, SSH 에이전트에 키가 로드되지 않아서 발생하는 문제입니다.
- 새 맥/PC로 이전 후 GitHub에 새 머신의 공개키를 등록 안 한 경우, 또는 키체인 문제로 에이전트에서 키가 날아간 경우 발생하는 문제라고 합니다.

1. SSH 키 존재 확인

SSH 키 존재 확인

- 루트 경로에 SSH 키가 존재하는지 확인합니다.
- 해당 경로에 id_rsa.pub 또는 id_ed25519.pub 파일이 있어야 정상입니다.

ls -al ~/.ssh

2. SSH 키를 생성합니다.

SSH 키를 생성합니다.

- Enter file in which to save the key → 그냥 Enter(기본 경로 사용)
- Enter passphrase → 그냥 Enter (비밀번호 없음)
- Enter same passphrase again → 그냥 Enter

# 아래의 명령어를 입력하여 SSH 키를 생성합니다.
$ ssh-keygen -t ed25519 -C "your_email@example.com"

3. 생성한 SSH 공개키 등록 확인

생성한 SSH 공개키 등록 확인

- 위에서 생성한 SSH 키에 대해서 생성을 확인합니다.

 cat ~/.ssh/id_ed25519.pub

4. [SSH Key 등록] github 사이트 > 프로필 > Setting을 선택합니다.

5. [SSH Key 등록] SSH and GPG Keys를 선택합니다.

6. [SSH Key 등록] ‘New SSH Key’를 선택합니다

7. [SSH Key 등록] 등록이 완료되었습니다.

8. SSH 에이전트에 키 로드

$ eval "$(ssh-agent -s)"
$ ssh-add ~/.ssh/id_ed25519

9. 정상적으로 git 연결 테스트를 확인하였습니다.

$ ssh -T git@github.com

10. 다시 작업을 수행하여, 정상적으로 수행이 됨을 확인하였습니다.

오늘도 감사합니다.

[Git] git@github.com : Permission denied (publickey)

[제작 앱 소개] 나만의 단위 계산기

adjh54 — Fri, 24 Apr 2026 18:10:03 +0900

해당 글에서는 Contributor9 개발자가 만든 개발 앱에 대해 홍보를 위한 목적으로 작성한 글입니다.

1) 개발자는 왜 이 앱을 만들었을까?

개발자는 왜 이 앱을 만들었을까?

- 많은 계산기 앱들이 있지만, 내가 원하는 계산을 위해서 매번 계산기 위치를 찾고, 여러 번 반복적인 화면을 터치해서 이동하는 것이 참 불편한 거 같다고 느꼈습니다.

- 내가 자주 사용하는 계산기를 내가 원하는 순서대로 배치하여 빠르게 찾을 수 있게하고, 쉽게 검색으로 바로 접근하는 방법이 없을까?라는 아이디어에서 시작된 앱입니다. 이러한 작은 불편함에서 시작되어서 이를 개선하기 위해서 사용자의 편의성을 가장 크게 고려를 하였습니다.

- 앱의 기능에서는 크게는 대분류로 단위, 생활, 프리미엄 계산기로 구성이 되어 있습니다.
대분류 내에서는 자주 이용하는 계산기들은 편집 버튼을 눌러서 쉽게 나만의 위치로 변경할 수 있고 이 위치는 저장이 되어서 계속 유지가 됩니다.

- 그리고 더 빠른검색을 위해서는 계산기 명이나 주요 키워드로 검색할 수 있는 퀵 검색 기능을 제공하며, 주요 해시태그를 선택하여서 원하는 계산기를 빠르게 더욱 빠르게 접근이 가능합니다.

- 이러한 빠른 검색뿐만 아니라 다양한 기능들을 제공합니다. 주요 변환이 필요한 단위 계산뿐만 아니라 생활 속에서 필요한 계산들을 묶어둔 생활 계산기 기능도 제공을 합니다. 일반, 퍼센트, 일자, 근수, 금중량, 체질량 등 평소 일상생활 속에서 계산이 필요한 기능들을 제공합니다.

- 그리고 프리미엄 계산기를 제공합니다. 이미 앱에 출시되고 운영되는 계산 앱들의 주요한 기능을 가져와서 제공이 됩니다. 평수 계산기, 나이 계산기, 촌수 계산기, 나만의 금융 계산기등의 많은 사용자들이 이용한 기능들을 특별하게 나만의 계산기에서 제공을 합니다!

- 이러한 계산들은 기록으로 자동 저장이 되어서, 이전에 내가 계산했던 내용이 무엇인지 빠르게 확인이 되고, 저장, 공유 기능을 제공합니다!

- 앞으로 업데이트 될 내용에서는 좀 더 다양한 계산기들이 추가될 예정입니다! 많은 관심 부탁드립니다

2) 앱 소개- 나만의 단위 계산기

앱 소개- 나만의 단위 계산기

- 단위 계산과 생활 계산 기능을 하나로 모아, 자주 쓰는 계산기를 내 사용 방식에 맞게 구성하고 관리할 수 있는 올인원 계산기 앱으로, 일상은 물론 실무와 학습까지 폭넓게 활용할 수 있는 앱입니다.

✔️ 여러 계산기 앱을 번갈아 쓰는 번거로움 없이, 필요한 계산을 한 화면에서 빠르게 처리할 수 있도록 설계되어서 모든 사용자들이 편하게 사용할 수 있습니다.
✔️ 자주 사용하는 계산기 기능은 사용 패턴에 맞게 정렬할 수 있고, 검색과 태그를 통해 원하는 계산기를 빠르게 찾아 나만의 계산기처럼 효율적으로 사용할 수 있습니다.
✔️ 숫자만 입력하면 길이·무게·시간·면적·데이터 용량 등 필요한 계산 결과를 즉시 확인할 수 있으며, 계산한 값은 복사·공유하거나 히스토리로 저장해 이후 다시 찾아보고 비교해 활용할 수 있습니다.

1. 홈 화면

- 홈 화면은 모든 계산기를 한 곳에서 빠르게 찾고, 내 사용 방식에 맞게 정리할 수 있는 계산기 메인 화면입니다.
- 단순한 계산기 목록이 아니라 검색·분류·커스터마이징을 중심으로 실사용에 최적화된 구조로 설계되었습니다
- 계산기 이름뿐 아니라 설명과 단위명까지 함께 검색할 수 있어 단위·생활·프리미엄 계산기를 구분 없이 한 번에 탐색할 수 있습니다
- 길이, 무게, 시간, 날짜, 건강, 금융 등 자주 쓰는 키워드 태그를 활용해 원하는 계산기에 즉시 접근할 수 있습니다
- 단위 계산기, 생활 계산기, 프리미엄 계산기는 요약 카드 형태로 한눈에 구분되어 각 영역별 계산기 구성과 개수를 직관적으로 확인할 수 있습니다
- 자주 사용하는 계산기는 드래그로 직접 순서를 편집해 저장할 수 있으며, 설정한 배치는 앱을 다시 실행해도 그대로 유지됩니다
- 프리미엄 계산기는 전용 영역으로 시각적으로 구분되어 제공되며, 안내 후 바로 해당 계산기로 이동할 수 있어 핵심 기능을 더욱 명확하게 사용할 수 있습니다

2. 단위 계산기 공통 기능

- 단위 계산기 화면은 하나의 기준 단위 입력만으로 다양한 단위를 즉시 변환할 수 있도록 설계된 실사용 중심의 고급 단위 변환 계산기입니다.
- 단순한 숫자 변환에 그치지 않고 정확성·가독성·복사 및 공유 활용성까지 종합적으로 고려해 구성되었습니다
- 원하는 기준 단위를 선택한 뒤 숫자를 입력하고 변환을 실행하면 즉시 결과가 출력되며, 기준 단위를 변경하면 입력값과 결과가 자동으로 초기화되어 계산 오류를 방지합니다
- 모든 변환 결과에는 한국식 콤마가 자동 적용되고 소수점은 최대 3자리까지 보기 좋게 정리되어 많은 숫자도 한눈에 쉽게 확인할 수 있습니다
- 복사 기능을 통해 기준 단위, 입력값, 전체 변환 결과를 한 번에 텍스트로 복사할 수 있고, 공유 기능으로 메신저·메일·메모 앱 등으로 바로 전달할 수 있습니다
- 변환을 실행할 때마다 계산 내역이 자동으로 저장되며 기준 단위, 입력값, 결과값이 함께 기록되어 언제든 히스토리에서 다시 확인할 수 있습니다
_ 각 단위의 의미와 기준, 사용 예를 카드 형태로 정리한 도움말을 제공해 계산 중 단위가 헷갈릴 때 언제든 쉽게 참고할 수 있습니다
- 숫자 입력 자동 포맷, 키보드 제어, 불필요한 요소 제거 등 실사용을 고려한 UI·UX로 iOS와 Android 모두에서 자연스럽고 일관된 사용 경험을 제공합니다

3. 계산 기록 히스토리

- 계산 기록 히스토리는 내가 사용한 모든 계산 결과를 한곳에서 모아보고 다시 활용할 수 있도록 설계된 기록 관리 페이지입니다.
- 단순 저장을 넘어 검색·필터·복사·공유·삭제까지 실사용에 꼭 필요한 기능을 중심으로 구성되었습니다
- 입력값과 결과값을 기준으로 숫자와 텍스트를 모두 실시간 검색할 수 있어 원하는 계산 기록을 빠르게 찾을 수 있으며, 검색 중에도 리스트가 즉시 반응해 기록이 많아져도 탐색 흐름이 끊기지 않습니다
- 길이, 무게, 시간, 거리, 이동 계산기 등 계산기 종류별로 기록을 필터링할 수 있고, 드롭다운 방식으로 필요한 계산기만 선택할 수 있어 기록 관리가 효율적입니다
_ 모든 기록은 최신 계산 기준으로 자동 정렬되며 계산 시각이 함께 표시되어 최근 사용 결과를 바로 확인하고 반복 계산 시 이전 기록과 쉽게 비교할 수 있습니다
- 입력값과 기준 단위를 명확히 구분하고 변환 결과를 카드 형태로 구조화해 가독성이 뛰어나며, 각 결과는 단위명과 값이 함께 표시되어 한눈에 이해할 수 있습니다
- 계산 결과 전체를 한 번에 복사하거나 메신저·메모 앱 등으로 즉시 공유할 수 있어 그대로 활용하기 좋습니다
- 개별 기록을 선택해 바로 삭제할 수 있고, 삭제 즉시 화면에 반영되어 불필요한 기록도 깔끔하게 관리할 수 있습니다

4. 설정

- 설정 화면은 단위 계산기 앱을 더욱 편리하고 깔끔하게 사용할 수 있도록 구성된 관리 공간으로, 계산 기록 정리부터 앱 정보 확인, 문의와 피드백까지 필요한 기능을 한 곳에 모아 누구나 쉽게 사용할 수 있도록 설계되었습니다
- 불필요하게 쌓인 계산 기록은 한 번의 동작으로 모두 초기화할 수 있어 길이·무게·시간·거리 등 다양한 계산기를 항상 깔끔한 상태로 유지할 수 있으며, 홈 화면에서 사용자가 직접 변경한 계산기 배치를 기본 상태로 되돌려 다시 정리하고 싶을 때 빠르게 초기화할 수 있습니다
- 앱 사용 중 궁금한 점이나 개선 의견이 있을 경우 설정 화면을 통해 간편하게 문의할 수 있고, 스토어 리뷰 페이지로 바로 이동해 의견을 남기거나 문의하기 메뉴를 통해 개발자에게 직접 질문을 전달할 수 있습니다
- 제작자 소개 메뉴에서는 앱을 만든 개발자에 대한 정보를 확인할 수 있으며, ‘제작자 앱 더보기’를 통해 함께 제작된 다른 유용한 앱들을 한눈에 살펴보고 바로 확인하거나 설치할 수 있습니다
- 설정 화면 하단에는 개인정보 처리방침, 이용약관, 오픈소스 라이선스 안내와 함께 현재 앱 버전 정보가 정리되어 있어 앱 사용과 관련된 정책과 업데이트 여부를 언제든지 쉽게 확인할 수 있습니다
- 또한 설정 화면 맨 아래에는 제작자가 만든 다양한 퀴즈 및 유틸리티 앱들이 카드 형태로 소개되어 새로운 앱을 발견하는 즐거움도 함께 제공합니다

이런 분께 추천해요!

- 길이·무게·시간·면적·데이터 용량 등 다양한 단위 변환을 자주 사용하는 분
- 계산기 앱을 여러 개 설치하기보다, 하나로 깔끔하게 정리하고 싶은 분
- 계산 결과를 복사하거나 공유해야 하는 일이 잦은 직장인·학생
- 이전에 계산한 값들을 다시 찾아보거나 비교해서 활용하고 싶은 분
- 자주 쓰는 계산기를 내 방식대로 정렬하고 맞춤 구성하고 싶은 분
- 숫자가 많은 계산도 보기 쉬운 포맷으로 정확하게 확인하고 싶은 분
- 일상 계산부터 실무·학습용 계산까지 한 앱에서 해결하고 싶은 분
- 복잡한 공식 없이, 빠르고 직관적인 계산 흐름을 선호하는 분

지금 이 계산기를 사용해 보세요!

필요한 계산을 찾고 → 입력하고 → 바로 활용하는 가장 실용적인 계산 경험을 만나보세요 ✨
오늘도 계산은 더 빠르게, 정리는 더 깔끔하게 ✔️

3) 다운로드

1. Google PlayStore

https://play.google.com/store/apps/details?id=com.tha.unitcalc

나만의 단위 계산기 - Google Play 앱

검색·태그·정렬로 원하는 계산기를 즉시 찾고, 단위·생활·프리미엄 계산과 히스토리 관리까지 한 번에 해결하는 실사용 중심 올인원 계산기 앱입니다

play.google.com

2. AppStore

https://apps.apple.com/kr/app/id6757512881

나만의 단위 계산기 앱 - App Store

App Store에서 EcodeLab의 나만의 단위 계산기 앱을 다운로드하십시오. 스크린샷, 평가 및 리뷰, 사용자 팁 및 나만의 단위 계산기 앱과 비슷한 다른 앱을 볼 수 있습니다.

apps.apple.com

⬇️ 개발자의 다양한 앱을 보고 싶으시면 아래의 링크를 확인해주세요 ⬇️

Ecodelab - 제작 앱 소개

Ecodelab에서 개발한 다양한 앱들을 소개합니다

www.ecodelab.im

바이브 코딩 : Gemini Enterprise 기반 공통 프롬프트 활용 방법

adjh54 — Wed, 22 Apr 2026 20:00:49 +0900

해당 글에서는 Gemini Enterprise 기반에 공통 프롬프트를 활용하는 방법에 대해서 확인해 봅니다.

1) 바이브 코딩을 이용한 사례

바이브 코딩을 이용한 사례

- 취미 생활로 바이브 코딩을 활용하여 다양한 앱들을 만들고 있습니다.
- 크로스 플랫폼을 활용하여 안드로이드, iOS에 플랫폼에 34개 앱 그리고 1개의 홈페이지를 출시가 되었고 운영 중에 있습니다. 현재에도 신규의 앱을 3개를 출시 준비 중에 있습니다.
- 2025년 04월부터 시작하여, 총 누적 다운로드 약 5,000회를 달성했고 현재 3,822명이 앱을 이용 중에 있습니다.
- 다양한 앱들을 바이브 코딩을 이용하여서 출시하였기에, 다양한 앱을 출시한 경험을 바탕으로 공통으로 프롬프트를 사용할 수 있는 방법에 대해 제안을 합니다.

https://ecodelab.im/main

Ecodelab - 제작 앱 소개

Ecodelab에서 개발한 다양한 앱들을 소개합니다

www.ecodelab.im

2) 프롬프트(Prompt)

프롬프트(Prompt)

- 인공지능(AI) 모델에게 ‘특정 작업을 수행하도록 지시하는 입력 값(명령어)’ 을 의미합니다.
- 어떤 프롬프트를 입력하는가’에 따라 결과물의 품질과 방향성이 크게 달라집니다.

1. 프롬프트 템플릿(Prompt Template)

프롬프트 템플릿(Prompt Template)

- 사용자가 AI에게 지시를 내릴 때, ‘활용할 수 있는 반복 가능한 구조 또는 형식'을 의미합니다.
- '입력 값'이나 '특정 변수'만 변경하면 일관된 형식의 프롬프트를 효율적으로 작성할 수 있고, 이에 따라 다양한 상황에 맞는 구체적인 지시문을 자동으로 생성할 수 있습니다.

'animal_name', 'animal_activity'라는 두 개의 변수를 입력받도록 설정하였습니다.
- 입력 값으로 각각 '독수리'와 '수영'을 입력하면, '독수리는 수영을 할 수 있는가?'라는 동적인 프롬프트가 생성이 되는 구조입니다.

https://docs.cloud.google.com/vertex-ai/generative-ai/docs/learn/prompts/prompt-templates?hl=ko

2. 프롬프트 레시피

프롬프트 레시피(Prompt Recipe)

- 사용자가 AI에게 지시를 내릴 때, 사전에 작성한 '완성된 지시문을 활용하는 것’을 의미합니다.
- 지시문으로 명확한 지침과 구조를 미리 설정해 두면, 원하는 결과를 지속적으로 도출할 수 있으며 반복 작업의 효율성을 극대화하고 출력 품질을 일정하게 유지할 수 있습니다.

[예시]

- 사용자는 ‘이를 기반으로 리스트 화면을 만들어줘’라고 입력 값으로 입력을 하였습니다. 그러면, 사전에 작성한 완성된 지시문(프롬프트 레시피)을 불러와서, 사용자의 입력 값에 추가되어서 일괄된 구조에서 프롬프트로 생성이 됩니다.

[ 더 알아보기 ]

프롬프트 템플릿(Prompt Template)과 프롬프트 레시피(Prompt Recipe)는 무슨 차이가 있을까?

- 프롬프트 템플릿은 청사진으로 표현하고 '구조화된 틀'을 의미합니다. 즉, 하나의 틀 안에 빈칸을 채우듯이 변수만 바꾸어서 여러 작업을 재사용할 수 있는 틀과 같습니다.
- 프롬프트 레시피는 이러한 템플릿에 '구체적인 값'을 모두 채워 넣은 완성본으로, 실제 AI에게 입력할 실행 가능한 '지시문 전체'를 의미합니다.
- 쉽게 말해, 템플릿은 "빵 만드는 방법(레시피 양식)"이고, 레시피는 "실제 재료와 양을 모두 적어서 바로 만들 수 있는 완성된 레시피"입니다.

Prompt Templates vs Prompt Recipes in Prompt Engineering

Discover the power of prompt templates and recipes in AI prompt engineering. Learn how these tools enable scalable, efficient, and effective AI solutions across industries and domains.

promptengineering.org

3. 프롬프트 래핑(Prompt Wrapping)

프롬프트 래핑(Prompt Wrapping)

- 사용자의 입력 값에 사전에 정의된 '프롬프트 형식(템플릿, 레시피)을 자동으로 감싸서’, AI가 더 정확하고 일관된 응답을 생성하도록 유도하는 기술입니다.

[예시]

- Gemini Cli를 기반으로 터미널에서 ./step1.sh create ‘로그인 화면을 만들고 싶어’라는 명령어 터미널에 입력하였습니다.
- 이러면, 사전에 정의한 프롬프트 레시피, 템플릿을 가져와서 이에 맞는 공통적인 프롬프트로 구성되어 일괄된 프롬프트를 입력할 수 있습니다.

4. 프롬프트 래핑: gemini cli 활용 예시

프롬프트 래핑: gemini cli 활용 예시

- 프롬프트 래핑을 이용해서 gemin cli 내에서 활용한 예시입니다.

Gemini CLI와 프롬프트 래핑(Wrapping)으로 자동화 프롬프트 활용하기

해당 글에서는 프롬프트 템플릿 + 레시피 + 래핑 + Gemini CLI를 이용하여서 프롬프트를 좀 더 정형화된 구조로 원하는 결과 값을 얻을 수 있는 방법에 대해 알아보는 방법에 대해 공유합니다.1) 주

adjh54.tistory.com

1. STEP1.sh이라는 쉘 파일 내에 사전 수행 할 프롬프트 레시피(완성된 지시문)를 구성합니다

2. Create라는 변수에 대한 프롬프트 템플릿(상황별 지시문)을 구성합니다.

3. 최종적으로 사용자는 ‘로그인 화면을 만들고 싶어’라는 프롬프트를 입력합니다.

4. 결과로 완성된 지시문 + 상황별 지시문+ 추가 명령어로 수행하여 상황에 따라 변수와 추가 명령어만 바꾸어서 일괄된 처리가 가능해졌습니다.

5. 페르소나(Persona)

페르소나(Persona)

- 'AI가 특정 역할이나 전문가처럼 행동'하도록 지시하는 기법을 의미합니다.
- 예를 들어 '경력 10년 차 UX 디자이너로서', '친절한 초등학교 선생님'과 같이 Ai에게 구체적인 역할을 부여합니다.
- 이를 통해, 답변의 품질, 방향성, 그리고 사용자 맥락에 대한 적합성을 크게 개선할 수 있습니다.

[더 알아보기]

결론적으로 프롬프트 템플릿, 레시피, 래핑, 페르소나는 무슨 차이일까?

구분	프롬프트 템플릿	프롬프트 레시피	프롬프트 래핑	페르소나
정의	변수가 포함된 재사용 가능한 구조화된 틀	변수에 값을 채운 즉시 실행 가능한 완성본	기존 프롬프트를 감싸서 추가 지시사항이나 컨텍스트를 덧붙이는 기법	AI에게 특정 역할, 전문성, 관점을 부여하는 설정
상태	미완성 (변수 존재)	완성 (변수 대입 완료)	완성된 프롬프트 위에 추가 레이어	프롬프트의 앞부분에 위치 (역할 정의)
목적	반복 작업 효율화	즉시 실행	출력 형식 제어, 안전장치, 제약조건 추가	답변의 관점과 품질 개선, 전문성 부여
예시	"다음 {주제}에 대해 {형식}으로 작성해줘"	"다음 AI에 대해 블로그 글로 작성해줘"	"위 내용을 반드시 JSON 형태로만 출력해줘"	"당신은 10년차 시니어 백엔드 개발자입니다"
재사용성	높음 (여러 작업에 적용)	낮음 (특정 작업 전용)	중간 (다양한 프롬프트에 적용 가능)	매우 높음 (모든 대화에 일관되게 적용)
사용 시점	반복되는 패턴 발견 시	구체적인 작업 실행 시	출력 형식 통제나 제약 필요 시	답변 품질/관점 설정이 필요한 모든 시점

3) 공통 프롬프트 활용-1 : 개인 맞춤 설정

공통 프롬프트 활용-1 : 개인 맞춤 설정

- 사용자가 설정한 모든 대화에 자동으로 적용되는 개인 맞춤 설정입니다.
- 선호하는 답변 스타일, 역할, 요구사항 등을 한 번 정의하면 별도로 변경하기 전까지 모든 대화 세션에 지속적으로 반영됩니다.

1. 개인 맞춤 설정을 하지 않은 경우 예시

개인 맞춤 설정을 하지 않은 경우 예시

- 아래와 같이 "일본 오사카 여행지를 추천해 줘." 프롬프트를 지시하였습니다.
- 프롬프트 결과를 받았으나, '내가 원하는 구체적인 결과'를 추출하지 못하였습니다.

2. 개인 맞춤을 적용한 경우

개인 맞춤을 적용한 경우

- 개인 맞춤 설정을 적용한 경우 예시 아래와 같이 맞춤 설정 값을 지정하고 적용하였습니다.
- 이전과 동일한 프롬프트를 입력했을 때, 사전에 입력한 개인 맞춤 설정에 따라 성격, 성향에 맞는 여행지를 추천해 줌을 확인하였습니다.

4) 공통 프롬프트 활용-2 : 프롬프트 칩 활용

공통 프롬프트 활용-2 : 프롬프트 칩 활용

- 웹 앱에서 클릭 한 번으로 사전 정의된 프롬프트를 즉시 실행할 수 있는 버튼형 UI입니다. 사전에 정의된 추천 프롬프트가 제공되며, 클릭 시 텍스트가 자동 입력이 됩니다.
- 팀 단위로 AI의 역할, 규칙, 작업 환경을 사전 정의해 두고, 버튼 클릭만으로 해당 페르소나를 적용할 수 있습니다. 이를 통해, 팀원 모두가 동일한 AI 설정을 공유하며 일관된 결과를 얻을 수 있습니다.

프롬프트 칩 구성 | Gemini Enterprise | Google Cloud Documentation

참고: 이 문서는 Gemini Enterprise의 Standard, Plus, Frontline 버전에 적용됩니다. Business 버전에 관한 자세한 내용은 Gemini Enterprise - Business 버전 고객센터를 참고하세요. 의견 보내기 프롬프트 칩 구성 컬

docs.cloud.google.com

1. 사전에 프롬프트 칩 내의 내용을 사전 정의(역할, 규칙, 작업 환경 등에 대한 정의)

2. 프롬프트 칩이 출력이 되며, 이를 선택하면 프롬프트가 자동 입력

3. 이를 실행하여 페르소나를 지정하고, 추가 프롬프트를 입력하여 공통된 결과 출력

[더 알아보기]

최초 페르소나로 역할을 부여했지만, 하나의 대화창에 프롬프트를 입력하다 보면 ‘컨텍스트 드리프트’가 발생할 수 있습니다.

- 컨텍스트 드리프트의 경우는 대화가 길어지면서 최초 페르소나/설정에서 벗어나는 현상을 의미합니다.

5) 공통 프롬프트 활용-3 : 대화 공유

공통 프롬프트 활용-3 : 대화 공유

- 이전 대화를 다른 사용자와 공유할 수 있습니다. 대화를 다른 사용자와 공유하면 해당 사용자는 프롬프트, 어시스턴트의 응답, 이미지 또는 동영상과 같은 생성된 콘텐츠를 비롯한 대화의 기존 콘텐츠를 모두 볼 수 있습니다.
- 효과적인 프롬프트와 결과물을 팀원과 즉시 공유하여 협업 효율성을 높이고, 성공 사례를 조직 자산으로 축적하여 반복 활용할 수 있습니다.

대화 공유 | Gemini Enterprise | Google Cloud Documentation

참고: 이 문서는 Gemini Enterprise의 Standard, Plus, Frontline 버전에 적용됩니다. Business 버전에 관한 자세한 내용은 Gemini Enterprise - Business 버전 고객센터를 참고하세요. 의견 보내기 대화 공유 컬렉션을

docs.cloud.google.com

1. 구성한 대화창에 공유 버튼을 누릅니다

2. 다른 사용자에게 ‘대화 공유 링크’를 전달합니다

3. 다른 사용자는 링크에 따라 접속을 합니다

4. 이전 사용자가 프롬프트로 이용했던 내용에 대해서 이어서 작성을 할 수 있습니다.

6) 프롬프트 활용- 4: 데이터 스토어

프롬프트 활용- 4: 데이터 스토어

- 사용자의 자체 데이터를 모델과 연결하여, 해당 데이터 기반의 검색, 답변, 작업을 제공하는 기능입니다.
- 사용자 데이터는 Google Cloud(퍼스트 파티), JIRA, Confluence(서드 파티)등을 의미합니다.
- 이 데이터 스토어로 이를 연결하여 연결된 데이터 범위 내에서 응답을 하는 것을 의미합니다.

앱 및 데이터 스토어 정보 | Gemini Enterprise | Google Cloud Documentation

참고: 이 문서는 Gemini Enterprise의 Standard, Plus, Frontline 버전에 적용됩니다. Business 버전에 관한 자세한 내용은 Gemini Enterprise - Business 버전 고객센터를 참고하세요. 의견 보내기 앱 및 데이터 스토어

docs.cloud.google.com

1. 데이터 스토어 활용: Github 설정

1.1.Github 내에 Github apps로 Gemini를 연결

1.2. 각각 접근 가능한 ‘레포지토리 별’로 지정이 가능하며, 접근 권한에 대해서 지정 가능

1.3. Gemini 내에서 github를 연결하면 최종 연결 완료가 됩니다

2. 데이터 스토어: Gemini 활용

2.1. 하단 메뉴에서 커넥터 > ‘github’를 활성화

2.2. 연결된 github 관련하여 프롬프트로 ‘연결된 레포지토리 목록’을 요청했을 때 응답 전달

2.3. 특정 파일(README.md)에 대한 요청 시, 해당 파일 읽어오기

2.4. 특정 ‘레포지토리 내 페이지’에 대한 코드 분석 가능

2.5. 레포지토리 내에 소스코드 분석하여 ‘개발 정책’에 대한 결과물을 반환

2.6. ‘레포지토리 간’의 데이터 통신 구조를 분석 가능

3. 데이터 스토어: Confluence 활용

3.1. 접근 가능한 confluence의 스페이스들을 확인

3.2. 특정 인물에 대해서 조회 및 분석

오늘도 감사합니다.

BaaS 기반 Supabase, 서비스 이해부터 보안 취약점까지

adjh54 — Wed, 22 Apr 2026 13:22:24 +0900

해당 글에서는 BaaS, Backend as a Service 기반에 Supabase의 주요 서비스에 대한 이해를 돕기 위해 작성한 입니다

1) 백엔드 인프라(BaaS, Backend as a Service)에 대한 필요성

백엔드 인프라(BaaS, Backend as a Service)에 대한 필요성

- 현재 개발 중인 앱이 있습니다. 해당 앱은 유튜브 영상을 링크를 복사해서 해당 앱에 붙여 넣기를 하면, 영상을 분석하여서 레시피를 텍스트 형태로 보고, 구간별 영상도 확인할 수 있는 앱입니다.

- 이 앱에서는 사용자별 레시피 관리를 위해 로그인 기능이 필요했고, 이에 따라 백엔드 인프라(API 서버, 인증 서버, OAuth, SMTP, DB 사용자 관리 등) 다양한 인프라 구축과 배포, 그에 따른 관리 포인트가 늘어나는 문제가 있었습니다.

2) Supabase

Supabase

- ‘The Open Source Firebase Alternative’라는 슬로건을 내세운 오픈소스 백엔드 서비스(BaaS, Backend as a Service)입니다.
- 구글의 Firebase와 유사한 기능을 제공하지만, NoSQL인 Firebase는 다르게 관계형 데이터베이스인 PostgreSQL을 기반으로 한다는 점이 가장 큰 차별점입니다.
- Supabase의 주요한 기능으로는 PostgreSQL 데이터베이스, 사용자 인증, 즉시 사용 가능한 API, 엣지 함수, 실시간 구독, 스토리지 및 벡터 임베딩 등의 기능을 제공합니다.

https://supabase.com/

1. 백엔드 서비스(BaaS, Backend as a Service)

백엔드 서비스(BaaS, Backend as a Service)

-개발자가 개발에 필요한 백엔드 인프라(서버, DB, 인증, 스토리지, API 등)를 직접 구축하거나 관리하지 않고, 클라우드 업체가 제공하는 API를 통해서 필요한 기능을 API/SDK 형태로 즉시 사용을 하는 방식을 의미합니다.

https://www.back4app.com/backend-as-a-service-ko

분류	설명	예시
BaaS (Backend as a Service)	인증, DB, 스토리지 등 백엔드 기능을 API로 제공, 프론트엔드 개발에 집중 가능	Firebase, Supabase, AWS Amplify
SaaS (Software as a Service)	완성된 소프트웨어를 구독 형태로 제공	Gmail, Slack, Notion, Figma
IaaS (Infrastructure as a Service)	서버, 스토리지, 네트워크 등 인프라를 제공	AWS EC2, Azure VM, GCP Compute Engine
PaaS (Platform as a Service)	개발 플랫폼(런타임, DB 등)을 제공, 인프라 관리 불필요	Heroku, Google App Engine, AWS Elastic Beanstalk

2. Supabase Price

Supabase Price

- BaaS, Backend as a Service 플랫폼을 사용하는 데의 Price & Fee입니다.
- Free Plan을 사용하더라도, 최대 MAU(Monthly Active Users)를 50,000명까지 수용할 수 있으며, DB 스토리지도 500MB로 사용자가 없는 초기 운영에서 사용해 볼 수 있다는 점이 좋았던 것 같습니다.
- 추후 Pro Plan을 구독한다면 월간 25달러(약 37,000원)의 가격에 MAU(Monthly Active Users) 10만까지 커버가 가능하며 필요에 따라 스케일 업을 할 수 있다는 점이 좋다고 판단되었습니다.

https://supabase.com/pricing

[ 더 알아보기 ]

MAU(Monthly Active Users)은 어떻게 측정이 될까?

- 공식 사이트에서는 로그인하거나 토큰(JWT)을 갱신하는 고유 사용자 수에 따라 요금이 부과된다고 합니다. 각 고유 사용자는 인증 횟수와 관계없이 청구 주기당 한 번만 계산이 됩니다.
- 예를 들어서, 청구 주기는 1월 1일부터 1월 31일까지라고 가정했을 때, 사용자 1(User-1)이 여러 번 로그인했더라도 이번 청구 주기에서는 단일 월간 활성 사용자(MAU)로 계산됩니다.

Manage Monthly Active Users usage | Supabase Docs

The count resets at the start of each billing cycle.

supabase.com

2. Firebase vs Supabase

Firebase vs Supabase

- 대표적인 BaaS (Backend as a Service) 플랫폼인 Firebase와의 차이점을 확인해 봅니다.

- Firebase는 구글에서 제공하는 모바일 및 웹 애플리케이션 개발 플랫폼입니다.
- 개발자가 인프라 관리나 서버 측 로직에 쏟는 시간을 줄이고, 클라이언트 앱의 기능과 사용자 경험(UX)에 집중할 수 있도록 돕는 BaaS(Backend as a Service) 모델의 대표 주자입니다.

https://hanbin-sla.tistory.com/entry/Supabase-vs-Firebase

항목	Supabase	Firebase
소유	Supabase Inc. (오픈소스)	Google (proprietary)
기반	PostgreSQL (SQL)	NoSQL (Firestore)
트랜잭션	완전 지원	제한적
관계형 데이터 / JOIN	O	X
라이센스	오픈소스(Apache 2.0, MIT)	SDK(Apache 2.0), 서버(비공개)
RLS(Row Level Security)	PostgreSQL RLS 네이티브	Security Rules (별도 문법)
실시간 동기화	O	O
인증 (Auth)	O	O
스토리지	Supabase Storage	Firebase Storage
서버리스 함수	Edge Functions (Deno)	Cloud Functions (Node.js)
벡터 DB (AI)	pgvector 내장 지원	별도 연동 필요
자체 호스팅	가능 (Docker)	불가
가격 방식	고정 ($25/월~)	종량제
무료 플랜	O	O

[ 더 알아보기 ]

그래서 무엇을 사용하는 것이 좋을까?
1. Supabase
- SQL/관계형 DB 선호, 자체 호스팅, 오픈소스, AI 기능이 필요한 프로젝트에 적합

2. Firebase
- 빠른 MVP, 실시간 기능, 모바일 앱, Google 생태계와 깊게 연동된 프로젝트에 적합

3) Supabase 서비스 기능

1. 관계형 데이터 베이스: Database(PostgreSQL)

관계형 데이터 베이스: Database(PostgreSQL)

- 완전 관리형으로 단순히 DB 래핑이 아닌 PostgreSQL 그 자체를 제공합니다.
- 벤더 종속 없이 표준 SQL 그대로 사용 가능하며, PostgreSQL의 모든 기능 (트리거, 함수, 뷰, 인덱스 등) 사용이 가능합니다.
- 데이터 간의 관계 설정(Foreign Key)이나 복잡한 쿼리 처리에 매우 강력합니다.

https://supabase.com/database

[ 더 알아보기 ]

완전 관리형 PostgreSQL은 뭘 의미하는 걸까?

- 설치 및 설정, 백업, 업데이트/패치, 확장, 가용성에 대해서 직접 구성하고 관리를 하는 것에 대해서 클라우드사에서 이를 관리하고 처리하게끔 지원을 하는 것을 의미합니다.

구분	직접 관리 (Self-hosted)	완전 관리형 (Managed)
설치 및 설정	OS 설치, 포트 설정, 방화벽 구성	클릭 한 번으로 생성 완료
백업 (Backup)	스케줄러 짜고 저장소 관리 필요	자동 백업 및 시점 복구 지원
업데이트/패치	보안 취약점 체크 및 직접 업데이트	클라우드사가 자동으로 최신 패치
확장 (Scaling)	서버 사양 수동 교체, 데이터 이전	콘솔에서 사양 클릭 시 즉시 확장
가용성 (HA)	서버 죽으면 직접 복구해야 함	다중화 구성을 통해 99.9% 가용성 보장

관리형 데이터베이스 아키텍처 구조입니다.

- KONG API Gateway를 통해서 각각에 맞게 라우팅을 해주며, Supabase가 직접 만든 서비스가 아닌 PostgreSQL + 오픈소스 툴 조합 + 관리 플랫폼을 의미합니다.
https://supabase.com/docs/guides/self-hosting/docker

Supabase 관계형 데이터베이스 둘러보기 -1: Database & Table

- 아래와 같이 일반 데이터베이스와 같이 Supabase 내에 데이터베이스, 테이블을 두고 데이터 관리가 가능합니다.

Supabase 관계형 데이터베이스 둘러보기 -2: Supabase Schema Visualizer

- 아래와 같이 Supabase Schema Visualizer 기능으로 테이블을 E-R Diagram 형태로 가시적으로 확인이 가능합니다.

Supabase 관계형 데이터베이스 둘러보기 -3: IDEA UI

- 테이블 데이터도 IDEA와 같이 조회할 수 있습니다.

Supabase 관계형 데이터베이스 둘러보기 -4: IDEA UI

- 아래와 같이 SQL문을 통해서 테이블 데이터 조회도 가능합니다.

2. 인증 : Authentication

인증 : Authentication

- Supabase의 인증은 JWT 기반 인증 시스템으로, Auth 스키마에 유저 정보를 저장하고 관리합니다. Row Level Security(RLS)와 긴밀하게 연동이 되는 서비스입니다.
- 익명 로그인에서 이메일/비밀번호 기반의 일반 로그인은 물론, Google, GitHub, Apple 등 다양한 소셜 로그인(OAuth)을 지원합니다. 세션 관리와 사용자 보안을 자동으로 처리하는 것을 제공합니다.

https://supabase.com/auth

2.1. 일반 로그인

일반 로그인

- Supabase에서 제공하는 일반 로그인 인증 방식으로는 아래와 같은 방식들을 지원합니다.

방식	설명
익명 로그인	UUID만 발급, 이메일이 없는 로그인 방식
이메일 + 비밀번호	전통적인 이메일/패스워드 로그인 방식
Magic Link	이메일로 링크 전송 → 클릭으로 로그인 방식
이메일 OTP	이메일로 6자리 코드 전송 로그인 방식
SMS/전화 OTP	문자로 6자리 코드 전송
Web3	Ethereum / Solana 지갑 서명

기본적으로 로그인을 수행하는 경우

- 로그인은 JWT를 기반으로 인증되는 시스템으로 Supabase에서는 사용자의 인증을 수행하면 Session이 발급이 됩니다. 이러한 세션은 Access Token, Refresh Token으로 구성이 되어 있으며 이를 통해 사용자의 유효 세션이 관리가 됩니다.
- 각각 사용자의 세션 유효 시간에 대해서도 Supabase 대시보다 내에서도 관리가 가능합니다.

사용자 UID

- 사용자가 회원가입을 하게 되면 auth.users 테이블에 사용자 정보가 저장이 됩니다. 그리고 이 사용자는 각각의 고유한 UID를 가지게 됩니다.
- 이메일/패스워드 회원가입 후 생성, OAuth 로그인 후 생성, Masic Link 링크 선택 시 생성 등에 해당 UID가 발급이 됩니다.

[활용 예시]

- 아래와 같이 이메일/비밀번호를 기반으로 하는 회원가입의 경우, BaaS를 이용하지 않는 경우는 사용자 DB, Security, SMTP 전송 프로세스, 이메일 OTP 프로세스, 이메일 템플릿 구성에 대한 추가적인 개발이 필요하지만, Supabase 내에서는 회원가입을 위한, Email 전송을 위한 메서드 호출만 하면 됩니다.

- 실제적으로 관여한 Back-end 구축 및 환경 구축은 하나도 사용하지 않았습니다.

실제적으로 아래와 같이 회원가입이 완료가 되면 Auth.users 테이블에서 관리가 됩니다.

[ 더 알아보기]

일반 로그인을 할 때, 이메일 회원가입이 있던데? 그럼 이메일 전송을 위한 SMTP까지 제공해 주는 것인가?

- Supabase에서 제공해 주는 noreply@mail.supabase.io 형태나 커스텀으로 내 이메일을 구성하여서 전송이 가능합니다. 또한, AWS SES, SendGrid, Mailgun, Resend과 연동이 가능합니다.

- Custom Email 연결하면 하루 500건이 무료라고 합니다.

아래와 같이 이메일 템플릿도 지정이 가능합니다.

2.2. 소셜 로그인

소셜 로그인

- Supabase에서 제공하는 소셜 로그인입니다.

아래와 같은 다양한 Provider를 통해 인증(Authentication)을 위임하여 간편하게 가입 및 로그인을 수행할 수 있습니다.

https://supabase.com/features/social-login

Spring Boot OAuth 2.0 프로세스를 비교하였을 때, Supabase 프로세스입니다.

- 기존 Spring Boot OAuth 2.0 내에서는 소셜 로그인을 위해서 Spring Security 기반 Auth Code 교환, JWT 발급, 검증, Refresh Token 처리, 클라이언트로 Redirect 과정을 처리해야 했습니다.
- Supabase 환경에서는 인증의 복잡한 부분(OAuth 중개, JWT 발급, 유저 관리)은 Supabase에 위임하여 signInWithOAuth() 함수 호출로 이를 대체할 수 있습니다.

Spring Boot OAuth 2.0 프로세스

Supabase 프로세스

항목	Spring Boot OAuth	Supabase OAuth
token 교환 주체	Client (백엔드)	Supabase Auth 서버
PKCE 처리	직접 구현	자동 처리
사용자 DB 저장	직접 구현	auth.users 자동 저장
Session 발급	JWT 직접 생성	Supabase Session 자동 발급
프론트 호출	-	signInWithOAuth() 한 줄

3. 엣지 함수: Edge Functions

엣지 함수: Edge Functions

- Supabase에서 제공하는 서버리스 함수 실행 환경으로, Deno 런타임 기반으로 동작하며 전 세계 엣지 서버에서 실행됩니다.
- Node.js를 지원하여 100만 개 이상의 NPM 모듈 지원을 통해 함수를 구성할 수 있습니다.
- TypeScript/JavaScript 기본 지원하며, Javascript V8 엔진 기반으로 빠른 콜드 스타트를 제공합니다.

https://supabase.com/edge-functions

아래와 같이 각각 Edge Function를 구성을 합니다.

아래와 같이 TypeScript/JavaScript을 지원하여서 코드 구성이 가능합니다.

아래와 같이 Javascritpt에 연결하여 호출하는 방법도 제공해 줍니다.

또한 추가적으로, 진행 중인 Edge Function에 대해서도 모니터링을 제공합니다.

4. 실시간 데이터 처리 : Realtime

실시간 데이터 처리 : Realtime

- Supabase Realtime은 데이터베이스 변경사항을 WebSocket으로 실시간 전달하는 기능을 의미합니다.
- 데이터베이스의 변경 사항(Insert, Update, Delete)을 클라이언트에 실시간으로 푸시해 줍니다. 채팅이나 실시간 알림 기능을 만들 때 유용합니다.

https://supabase.com/realtime

4.1. 실시간 데이터 처리 프로세스

실시간 데이터 처리 프로세스

- 앱 사용자 A, B, C가 있고 이들이 동일한 채팅방에서 채팅을 한다는 가정하에 있습니다. 사용자 A, B, C는 ‘open-chat’이라는 채널을 구독(subscribe)하고 있습니다.

1. 사용자 A는 채팅을 위해서 “안녕하세요”라는 텍스트를 입력합니다.
2. 이 텍스트 데이터 row는 Supabase DB에 저장이 됩니다.
3. 저장이 되면 이를 감지하여 Supabase Realtime에서는 ‘open-chat’ 채널로 Broadcast를 하여서 구독 중인 수신자인 사용자 B, C에게 전달을 합니다.

- WebSocket에서 Publisher(발행), Subscriber(구독)의 개념이 아닌 DB INSERT로 Publish(발행)가 된다는 점이었습니다.

[Realtime 서비스를 활용한 채팅 구현 사례]

- 아래와 같이 로그인을 수행한 사용자를 기반으로 전체 채팅방을 구현을 하였습니다.
- 채팅방을 구현을 위해서 Publisher(발행자)는 채널에 접근하고, Message라는 테이블 내에 데이터를 INSERT를 하고, Subscriber(구독자)는 채널에 접근하여 구독을 하면, 서로 실시간 채팅방이 구현이 되었습니다.
- 만약 이를 이용하지 않았다면, 별도의 소켓서버, Redis 구축 등 다양한 환경을 구축해야 헀습니다.

사용자 A가 채팅으로 입력을 합니다.

아래와 같이 텍스트가 데이터 베이스에 저장이 되고

이를 구독하고 있던 다른 사용자에게 전달이 됩니다.

5. 저장소: Storage

저장소: Storage
- 이미지, 동영상 등의 대용량 파일을 저장하고 관리할 수 있습니다. CDN이 기본 포함되어 있어 파일 전송 속도가 빠릅니다.
- S3 호환 오브젝트 스토리지로, 이미지/영상/문서 등 파일을 저장·관리하는 서비스입니다. 내부적으로 AWS S3 또는 S3 호환 스토리지(MinIO 등) 위에서 동작을 합니다.

https://supabase.com/storage

Supabase Storage가 내부적으로 AWS S3 호환 방식으로 설계되어 있어서, S3의 용어를 그대로 차용한 Burket을 이용합니다.

분류	설명	예시
Public Burket	URL만 알면 누구나 접근 가능하며 별도의 인증이 필요없는 공간	프로필 이미지, 공개 에셋, 썸네일 등
Private Burket	인증 토큰 또는 Signed URL 필요하며 별도의 인증이 필요한 공간	계약서, 개인정보 파일, 결제 영수증 등

4) BaaS 플랫폼 보안적 취약점

1. 크로스 플랫폼 내에서 Supabase 활용 구조

크로스 플랫폼 내에서 Supabase 활용 구조

1. 모바일 내에서 .env 환경 파일 내에 Supbase URL과 Publishable key를 관리합니다.
2. 이를 기반으로 Supbase와의 통신을 위한 공통 Client를 구성합니다.
3. 클라이언트로 Supabase의 조회 쿼리를 구성하여 Supabase의 Database를 직접 조회를 합니다.

2. Supabase 연결

Supabase 연결

- Supabase를 연결하기 위해서 Front → Supabase로 바로 연결하는 구조를 구성합니다.
- 해당 부분에서는 Publishable key를 이용하여서 ‘anno(손님)’이라는 권한을 받아서 우선 수행을 합니다.

분류	설명
Project URL	- Supabase 프로젝트의 API 엔드포인트 주소를 의미합니다. - REST API, Auth, Storage, Realtime 등 모든 요청이 이 URL로 들어감
Publishable key	- anon(손님) 권한으로 서명된 JWT를 의미합니다. - 클라이언트가 Supabase API에 요청할 때 Authorization 헤더에 자동으로 붙음 - 프론트 상에서 사용되는 키를 의미합니다.
Secret Key	- service_role(관리자) 권한으로 서명된 JWT를 의미합니다. - 클라이언트가 Supabase API에 요청할 때 Authorization 헤더에 자동으로 붙음 - 서버 상에서 사용되는 키를 의미합니다.

3. Supabase Client 생성

Supabase Client 생성

- Supabase의 키를 기반으로 통신을 위한 공통 클라이언트를 생성합니다.

import 'react-native-url-polyfill/auto';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { createClient } from '@supabase/supabase-js';
import { SUPABASE_ANON_KEY, SUPABASE_URL } from '@env';

export const supabaseClient = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
	auth: {
		storage: AsyncStorage,
		autoRefreshToken: true,
		persistSession: true,
		detectSessionInUrl: false,
	},
});

4. Supabase 호출

Supabase 호출

- 연결된 클라이언트를 기반으로 직접 쿼리를 구성하여서 요청을 합니다.

const RecipeService = {
	/**
	 * Supabase 연결 상태 확인
	 */
	checkConnection: async (): Promise<boolean> => {
		const { error } = await supabaseClient.from('recipes').select('id').limit(1);
		if (error) {
			console.error('Supabase 연결 실패:', error.message);
			return false;
		}
		console.log('Supabase 연결 성공');
		return true;
	},

	/**
	 * 전체 레시피 목록 조회
	 */
	selectRecipeList: async (): Promise<MainDataType.Recipe[]> => {
		const { data, error } = await supabaseClient
			.from('recipes')
			.select('*')
			.order('extracted_at', { ascending: false });

		if (error) {
			throw new Error(error.message);
		}
		return (data as TableDataType.RecipeRow[]).map(mapToRecipe);
	},

	/**
	 * 레시피 단건 조회 (id 기준)
	 */
	selectRecipeById: async (id: string): Promise<MainDataType.Recipe> => {
		const { data, error } = await supabaseClient.from('recipes').select('*').eq('video_id', id).single();

		if (error) {
			throw new Error(error.message);
		}
		return mapToRecipe(data as TableDataType.RecipeRow);
	},

	/**
	 * 레시피 단건 조회 (video_id 기준)
	 */
	selectRecipeByVideoId: async (videoId: string): Promise<MainDataType.Recipe> => {
		const { data, error } = await supabaseClient.from('recipes').select('*').eq('video_id', videoId).single();

		if (error) {
			throw new Error(error.message);
		}
		return mapToRecipe(data as TableDataType.RecipeRow);
	},
	
}

5. 보안적 취약점

보안적 취약점

- .env 파일 내에서 직접적으로 Supabase 접속 엔드포인트와 호출 및 접근 가능한 Publishable key를 이용하고 있습니다.
- 해당 키가 ‘anno(손님) 권한’으로 서명된 JWT라고 하더라도, 손님에 대한 정책(Policy)을 지정하지 않는다면, 모든 데이터에 접근이 가능하며 노출 시 보안적인 취약점이 발생할 수 있습니다.

5) MoltBook으로 본 Supabase의 사례

MoltBook

- MoltBook이라는 AI 에이전트를 위한 소셜 네트워크로 AI 에이전트들이 글을 올리고, 토론하고, 추천하는 플랫폼이며 인간은 관찰자로 참여가 가능한 플랫폼이 있습니다.
- 즉, AI 에이전트들이 모여서 노는 SNS 공간에 인간이 관찰자로 참여를 하는 플랫폼입니다.

moltbook - the front page of the agent internet

A social network built exclusively for AI agents. Where AI agents share, discuss, and upvote. Humans welcome to observe.

www.moltbook.com

1. MoltBook 해킹: Supabase 설정 오류로 150만 개의 API 키 노출

MoltBook 해킹: Supabase 설정 오류로 150만 개의 API 키 노출

- .env 파일 내에서 직접적으로 Supabase 접속 엔드포인트와 호출 및 접근 가능한 Publishable key를 이용하고 있습니다.
- 해당 키가 ‘anno(손님) 권한’으로 서명된 JWT라고 하더라도, 손님에 대한 정책(Policy)을 지정하지 않는다면, 모든 데이터에 접근이 가능하며 노출 시 보안적인 취약점이 발생할 수 있습니다.
- 이와 같은 사례로 MoltBook 해킹으로 150만 개의 API 키가 노출된 사례에 대해 알아봅니다.

https://v.daum.net/v/Y1M6G1Kphd

사건 요약

- 2026년 1월 31일, 보안 연구원 Jameson O'Reilly가 Moltbook의 전체 데이터베이스가 공개적으로 노출되어 있다는 사실을 발견했습니다.
-노출된 키를 기반으로 이메일 주소, 인증 토큰, 모든 에이전트의 API 키에 접근 가능한 상태였습니다.

- 재미있는 사항은 창업자 Matt Schlicht은 "Moltbook을 위해 단 한 줄의 코드도 직접 작성하지 않았다. AI가 현실로 만들었다"라고 공개적으로 밝혔습니다. 즉, 바이브 코딩만으로 구성을 하였다고 합니다.

- 즉, 해당 사건의 핵심 원인은 Supabase의 이였습니다. Row Level Security(RLS)를 활성화하지 않았다고 합니다.
- 해당 문제는 즉각적으로 해결이 되었다고 하지만, 150만 개의 키가 노출이 되었다는 큰 이슈였습니다.

Moltbook Data Breach: Supabase RLS Security Lessons | Bastion

Learn how Moltbook's Supabase misconfiguration exposed 1.5 million API keys and what security practices could have prevented this AI agent platform disaster.

bastion.tech

Hacking Moltbook: AI Social Network Reveals 1.5M API Keys | Wiz Blog

Learn how a misconfigured Supabase database at Moltbook exposed 1.5M API keys, private messages, and user emails, enabling full AI agent takeover.

www.wiz.io

후문이지만, 바이브 코딩으로 만든 MoltBook은 2026년 03월 10일에 Meta 내에서 인수를 하였다고 합니다.

[AI의 종목 이야기] 메타, AI 에이전트 소셜 네트워크 '몰트북' 인수

이 기사는 인공지능(AI) 번역으로 생산된 콘텐츠로, 원문은 3월 10일자 로이터 기사(Meta acquires AI agent social network Moltbook)입니다.[서울=뉴스핌] 김현영 기자 = 메타 플랫폼스(종목코드: META)가 인공

www.newspim.com

6) Supabase RLS(Row Level Security)

Supabase RLS(Row Level Security)

- PostgreSQL의 RLS 기능을 Supabase가 활용한 것으로 테이블의 각 행(Row)에 대한 접근을 사용자별로 제어하는 보안 메커니즘을 의미합니다.
- 이를 활성화하지 않으면 API 키만으로 모든 데이터에 접근할 수 있습니다.

- Supabase 내에서는 클라이언트(앱) 내에 Publishable key를 포함하기에, 손님(Anno)에 대한 권한으로 제공을 하지만, 활성화가 되어 있지 않으면 사실상 데이터베이스에 모든 접근이 되기에, 이에 따르는 RLS에 대한 설정된 정책(Policy)을 지정하여 허용된 데이터만 노출되도록 해야 합니다.

Row Level Security | Supabase Docs

Secure your data using Postgres Row Level Security.

supabase.com

Client내에 포함되어 있는 Supabase Publishable key

1. RLS 프로세스

RLS 프로세스

1. 클라이언트는 발급받은 JWT를 Supabase로 전달을 합니다.
2. Supabase Auth Layer에서는 auth.uid() / auth.role() 추출하여 확인합니다.
3. RLS 활성화 여부 확인하여, 비 활성화 되어 있다면, ‘전체 접근 허용’이 되는 것이고, 아니라면 Policy를 확인합니다.
4. Policy를 확인하여서 허용되지 않으면 데이터는 조회되지 않을 것이고, 허용된다면 PostgreSQL을 통해서 쿼리가 실행됩니다.
5. 결과적으로 필터링된 결과를 반환합니다.

- 위에 Moltbook 사례를 보더라도 RLS 활성화 여부를 확인하지 않았다면, 데이터베이스 접근은 모두 ‘전체 접근 허용’이 되었을 것입니다.

2. RLS 적용 방법

2.1. Enable RLS for this table

Enable RLS for this table

- 테이블에 대해서 RLS를 적용합니다.

2.2. ‘Add RLS policy’를 적용합니다

2.3. 직접 Policy를 지정할 수 있고, Template도 제공이 됩니다.

3. RLS Policy Templates

RLS Policy Templates

- 기본적으로 제공하는 RLS Policy Template입니다. 이를 이용하여서 기본적인 설정 구성이 가능합니다.

태그	정책명	설명
SELECT	Enable read access for all users	SELECT로 모든 유저에게 읽기 권한 부여
INSERT	Enable insert for authenticated users only	인증된 유저에게만 INSERT 권한 부여
DELETE	Enable delete for users based on user_id	user_id 컬럼이 본인 ID와 일치하는 행만 삭제 가능
INSERT	Enable insert for users based on user_id	user_id 컬럼이 본인 ID와 일치하는 행만 삽입 가능
UPDATE	Policy with table joins	테이블 JOIN을 활용한 고급 RLS 규칙 (teams, members 테이블 예시)
ALL	Policy with security definer functions	Security Definer 함수로 다대다 관계의 링킹 테이블 접근 제어
SELECT	Policy to implement Time To Live (TTL)	생성 후 24시간 이내 행만 조회 가능 (Instagram 스토리 / Snapchat 방식)
SELECT	Enable users to view their own data only	본인 데이터만 읽기 가능하도록 제한

4. Custom Row Level Security policy

Custom Row Level Security policy

- 위에 템플릿을 이용한 경우 외에 커스텀으로 Policy 지정이 가능합니다.

Supabase 내에서 각각에 맞는 설정이 가능합니다.

3.1. 테이블 단위가 아닌 행(Row) 단위로 접근 제어

테이블 단위가 아닌 행(Row) 단위로 접근 제어

-- RLS 활성화
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

3.2. 정책(Policy) 구조

정책(Policy) 구조
- 정책을 구성하는 SQL입니다.
FOR: 어떤 작업에 적용할지(SELECT | INSERT | UPDATE | DELETE | ALL)
TO: 누구에게 적용할지(authenticated | anon | public | 특정롤)
USING vs WITH CHECKUSING(읽기 조건) — "이 행을 볼 수 있는가?"에 대한 지정
WITH CHECK(쓰기 조건) — "이 값을 쓸 수 있는가?”에 대한 지정

CREATE POLICY "정책명"
ON 테이블명
FOR [SELECT | INSERT | UPDATE | DELETE | ALL]
TO [authenticated | anon | public | 특정롤]
USING (조건)           -- 읽기 조건 (SELECT, UPDATE, DELETE)
WITH CHECK (조건);     -- 쓰기 조건 (INSERT, UPDATE)

예시 -1
- post라는 테이블에 대해서 RLS를 적용합니다
- post는 로그인된 본인의 데이터만 조회, 삽입, 수정, 삭제만 가능하도록 정책을 지정합니다.

ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

CREATE POLICY "본인 데이터 조회"
ON posts FOR SELECT
TO authenticated
USING (auth.uid() = user_id);

CREATE POLICY "본인 데이터 삽입"
ON posts FOR INSERT
TO authenticated
WITH CHECK (auth.uid() = user_id);

CREATE POLICY "본인 데이터 수정"
ON posts FOR UPDATE
TO authenticated
USING (auth.uid() = user_id)
WITH CHECK (auth.uid() = user_id);

CREATE POLICY "본인 데이터 삭제"
ON posts FOR DELETE
TO authenticated
USING (auth.uid() = user_id);

오늘도 감사합니다.

[RN/오류노트] UnhandledPromiseRejection: The promise rejected with the reason "Error: Failed to build ios project. "xcodebuild" exited with error code '65'.

adjh54 — Tue, 21 Apr 2026 20:10:26 +0900

해당 글에서는 React Native 환경에서 발생한 This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). 오류를 해결하는 방법에 대해서 알아봅니다.

1) 문제점

문제점

- React Native 빌드 과정에서 아래와 같은 문제점이 발생하였습니다.

- UnhandledPromiseRejection: This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). The promise rejected with the reason "Error: Failed to build ios project. "xcodebuild" exited with error code '65'.

yarn ios:16pro
info A dev server is already running for this project on port 8082.
info Found Xcode workspace "linkManager.xcworkspace"
info Launching iPhone 16 Pro (iOS 18.5)
info Building (using "xcodebuild -workspace linkManager.xcworkspace -configuration Debug -scheme linkManager -destination id=D6AA575C-2DB6-4E68-B719-CCEE4BD9C5DE")

info   Tip: Make sure that you have set up your development environment correctly, by running npx react-native doctor. To read more about doctor command visit: <https://github.com/react-native-community/cli/blob/main/packages/cli-doctor/README.md#doctor>

node:internal/process/promises:392
new UnhandledPromiseRejection(reason);
^

UnhandledPromiseRejection: This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). The promise rejected with the reason "Error: Failed to build ios project. "xcodebuild" exited with error code '65'. To debug build logs further, consider building your app with Xcode.app, by opening 'linkManager.xcworkspace'.".
at throwUnhandledRejectionsMode (node:internal/process/promises:392:7)
at processPromiseRejections (node:internal/process/promises:475:17)
at process.processTicksAndRejections (node:internal/process/task_queues:106:32) {
code: 'ERR_UNHANDLED_REJECTION'
}

Node.js v22.21.1

2) 해결방법

해결 방법

- ios 폴더 내에 LinkManager.xcodeproj와 linkManager.xcworkspace 로 대문자, 소문자가 섞여서 찾지 못해서 발생하는 문제였습니다.
- 그리고 macOS 파일시스템이 기본적으로 case-insensitive(대소문자 구분 안 함)을 수행하기에 발생을 합니다.
- 해당 과정은 대부분 react-native-rename 라이브러리를 사용하여서 두번 이상 변경을 하는 경우 발생을 하였습니다.

[RN] React Native 환경에서 react-native-rename을 활용하여 프로젝트 명, 패키지 일괄 변경하기

해당 글에서는 React Native 환경에서 react-native-rename을 이용하여서 프로젝트 명, 패키지 명을 일괄적으로 변경하는 방법에 대해 알아봅니다 1) react-native-rename react-native-rename- React Native 프로젝트

adjh54.tistory.com

1. 폴더 명 변경

macOS 파일시스템이 기본적으로 case-insensitive(대소문자 구분 안 함) 문제가 있습니다

- 그렇기에 macOS의 입장에서는 linkManager와 LinkManager를 동일하게 여기기에 중간에 temp를 둬서 변경을 합니다.

# 임시 이름 거쳐서 변경
$ mv linkManager.xcodeproj temp_LinkManager.xcodeproj
$ mv temp_LinkManager.xcodeproj LinkManager.xcodeproj

$ mv linkManager.xcworkspace temp_LinkManager.xcworkspace
$ mv temp_LinkManager.xcworkspace LinkManager.xcworkspace

2. contents.xcworkspacedata

contents.xcworkspacedata

- 참조하고 있는 소문자를 대문자로 변경합니다.

<?xml version="1.0" encoding="UTF-8"?>
<Workspace
   version = "1.0">
   <FileRef
      location = "group:LinkManager.xcodeproj">
   </FileRef>
   <FileRef
      location = "group:Pods/Pods.xcodeproj">
   </FileRef>
   <FileRef
		   // 해당 부분 대문자로 변경
      location = "group:linkManager.xcodeproj">
   </FileRef>
</Workspace>

3. pod 재설치

pod 재설치

- 프로젝트에 대해서 캐시를 모두 정리하고 pod을 재설치를 합니다.

# 1. 프로젝트 ios 폴더 접근
$ cd ios

# 2. CocoaPods 캐시
$ rm -rf Pods Podfile.lock

# 3. CocoaPods 시스템 캐시 정리
$ rm -rf ~/Library/Caches/CocoaPods

# 4. CocoaPods 완전 초기화
$ pod deintegrate

pod install

4. XCode 프로젝트에서 스킴(Scheme) 이름을 변경작업

XCode 프로젝트에서 스킴(Scheme) 이름을 변경작업

- 위에 작업이 실패한 경우 아래와 같이 수행을 합니다.

1. sed -i '' 's/linkManager/LinkManager/g' ...xcscheme
.xcscheme 파일 내부 텍스트에서 linkManager → LinkManager로 치환

2. mv linkManager.xcscheme LinkManager.xcscheme
- 파일명 자체를 소문자 → 대문자로 변경

3. ls ...xcschemes/
- 변경 결과를 확인합니다.

# 파일 내부 텍스트에서 linkManager → LinkManager로 치환 작업
$ sed -i '' 's/linkManager/LinkManager/g' LinkManager.xcodeproj/xcshareddata/xcschemes/linkManager.xcscheme

# 파일명 자체를 소문자에서 대문자로 변경
$ mv LinkManager.xcodeproj/xcshareddata/xcschemes/linkManager.xcscheme LinkManager.xcodeproj/xcshareddata/xcschemes/LinkManager.xcscheme

# 변경 결과 상태를 확인.
$ ls LinkManager.xcodeproj/xcshareddata/xcschemes/

오늘도 감사합니다.

[기타] 로지텍 마우스(MX Master) Logi Options+ : Action Ring으로 빠르게 소프트웨어 실행 방법

adjh54 — Tue, 21 Apr 2026 20:05:28 +0900

해당 글에서는 MX Master 마우스 내에서 Action Ring을 이용하여서 빠르게 소프트웨어를 실행하는 방법에 대해 알아봅니다

1) Logi Options+

Logi Options+

- 로지텍(Logitech)의 공식 마우스/키보드 설정 소프트웨어

Logi Options+ 소프트웨어 | Logitech

Logitech의 마우스 및 키보드용 커스터마이징 소프트웨어인 Logi Options Plus에 대해 알아보세요. 설정을 개인화하고, 단축키를 만들며, 일상의 생산성을 향상하세요. 지금 무료로 다운로드하세요.

www.logitech.com

1. Action Ring

Action Ring

- Logi Options+에서 제공하는 원형 퀵 메뉴 기능

Logi Options+의 Actions Ring | Logitech

Logi Options+에서 지원되는 앱의 도구, 단축키 및 창의적 제어에 빠르게 접근할 수 있는 커스텀 화면 오버레이인 Actions Ring에 대해 알아보세요.

www.logitech.com

2) 설정 방법

1. 공식 사이트에서 소프트웨어를 다운로드 받습니다.

Logi Options+ 소프트웨어 | Logitech

www.logitech.com

2. 앱을 실행 > OPTIONS+ 설치를 선택합니다.

3. 다운로드가 진행이 됩니다.

4. 소프트웨어 로그인을 수행하면 현재 연결된 로지텍 마우스를 확인할 수 있습니다.

5. 로지텍 마우스를 선택합니다

6. 기능 중 ‘제스처’ 기능에 대해서 수정을 합니다

7. 기능 중 Action Ring 표시를 선택하고 'LOGI 플러그인 서비스 활성화' 버튼을 선택합니다.

8. 모든 설정이 완료되고 ‘ACTION RING 구성’ 버튼을 누릅니다.

9. 기본 설정 대신에 앱을 연결하는 기능을 추가합니다 : 열기 > 애플리케이션 열기

10. 액션 링으로 드래그앤 드랍을 해서 위치를 바꾸면 아래와 같이 나옵니다

11. 아래와 같이 검색해서 추가를 하면 완료가 됩니다

12. 아래와 같이 세팅을 마쳤습니다.

13. 지정한 액션링 단축키를 누르면 아래와 같이 필요에 따라 빠르게 앱 실행이 가능합니다.

오늘도 감사합니다.

[RN] react-native-bootsplash 라이브러리를 활용하여 스플래시 화면 만들기

adjh54 — Tue, 21 Apr 2026 20:00:35 +0900

해당 글에서는 React Native 환경에서 react-native-bootsplash 라이브러리를 이용하여 스플래시 화면을 만드는 방법에 대해서 알아봅니다.

1) react-native-bootsplash

react-native-bootsplash

- React Native 앱 실행 시 나타나는 스플래시 스크린(Splash Screen)을 쉽게 구현하기 위한 라이브러리입니다.
- Mathieu Acthernoene(Zoontek)이 만든 라이브러리로, 현재 RN 생태계에서 가장 널리 쓰이는 스플래시 솔루션입니다.

https://www.npmjs.com/package/react-native-bootsplash

사픽: 사자성어 퀴즈 - Google Play 앱

사자성어를 카드로 배우고, 퀴즈와 오답 복습으로 완벽히 암기하는 학습 앱

play.google.com

사픽: 사자성어 퀴즈 앱 - App Store

App Store에서 EcodeLab의 사픽: 사자성어 퀴즈 앱을 다운로드하십시오. 스크린샷, 평가 및 리뷰, 사용자 팁 및 사픽: 사자성어 퀴즈 앱과 비슷한 다른 앱을 볼 수 있습니다.

apps.apple.com

2) 초기 환경 적용 방법

1. 라이브러리 설치

# npm
$ npm i react-native-bootsplash

# yarn
$ yarn add react-native-bootsplash

https://www.npmjs.com/package/react-native-bootsplash

2. [Android] MainActivity.kt

[Android] MainActivity.kt

- JS 번들이 로드되기 전에 잠깐 흰 화면이 뜨는데, RNBootSplash.init()이 그 시점에 스플래시 화면을 즉시 표시해 줌.

import android.os.Bundle
import com.zoontek.rnbootsplash.RNBootSplash // ← 추가

class MainActivity : ReactActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        RNBootSplash.init(this, R.style.BootTheme) // ← 추가
        super.onCreate(savedInstanceState)
    }
}

3. [Android] styles.xml

[Android] styles.xml

- 스플래시의 디자인을 적용합니다. 배경색, 로고, 끝나면 어떤 테마로 돌아갈지에 대해 정의

<style name="BootTheme" parent="Theme.BootSplash">
    <item name="bootSplashBackground">@color/bootsplash_background</item>
    <item name="bootSplashLogo">@drawable/bootsplash_logo</item>
    <item name="postBootSplashTheme">@style/AppTheme</item>
</style>

4. [Android] Color.xml

[Android] Color.xml
- 스플래시 백그라운 색을 정의합니다

<resources>
    <color name="bootsplash_background">#ff8c42</color>
</resources>

5. [iOS] AppDelegate.swift

[iOS] AppDelegate.swift

- iOS 플랫폼에서 React Native 루트 뷰가 만들어지는 시점에 BootSplash.storyboard를 불러와서 스플래시 표시가 됩니다.
- JS 로드 완료 후 JS 쪽에서 RNBootSplash.hide() 호출하면 사라짐

import Firebase
import RNBootSplash // ← 추가
import React
import ReactAppDependencyProvider
import React_RCTAppDelegate
import UIKit

@main
class AppDelegate: RCTAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
  ) -> Bool {
    self.moduleName = "EmotionalEmoticon"
    self.dependencyProvider = RCTAppDependencyProvider()
    self.initialProps = [:]

    FirebaseApp.configure()
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }

  // ✅ 해당 부분 추가
  override func customize(_ rootView: RCTRootView!) {
    super.customize(rootView)
    RNBootSplash.initWithStoryboard("BootSplash", rootView: rootView)
  }

  override func sourceURL(for bridge: RCTBridge) -> URL? {
    self.bundleURL()
  }

  override func bundleURL() -> URL? {
    #if DEBUG
      RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
    #else
      Bundle.main.url(forResource: "main", withExtension: "jsbundle")
    #endif
  }

  override func application(
    _ application: UIApplication, supportedInterfaceOrientationsFor window: UIWindow?
  ) -> UIInterfaceOrientationMask {
    return .portrait
  }
}

6. AppLayout.tsx

AppLayout.tsx

- Navigation이 준비되는 시점에 스플래시를 fade 효과로 숨기는 과정입니다.

import BootSplash from 'react-native-bootsplash'; // 추가

return (
		<NavigationContainer
			ref={navigationRef}
			onReady={() => {
				setCurrentRoute(navigationRef.current?.getCurrentRoute()?.name || '');
				BootSplash.hide({ fade: true }); // 추가
			}}
			onStateChange={() => {
				const routeName = navigationRef.current?.getCurrentRoute()?.name;
				if (routeName) {
					setCurrentRoute(routeName);
				}
			}}>
			<SafeAreaView style={[styles.safeArea, { backgroundColor }]} edges={shouldShowAd ? ['top'] : []}>
				<View style={styles.container}>
					<View style={[styles.adWrapperAbsolute, !shouldShowAd && { height: 0, opacity: 0 }]}>
						<AdmobBannerAd visible={shouldShowAd} paramMarginTop={0} paramMarginBottom={0} />
					</View>
					{shouldShowAd && <View style={{ paddingTop: getAdPaddingTop() }} />}
					<View style={[styles.navigatorWrapper, { paddingTop: getNavigatorPaddingTop(shouldShowAd), backgroundColor }]}>
						<StackNavigator />
					</View>
				</View>
			</SafeAreaView>
		</NavigationContainer>
	);

3) 스플래시 이미지 생성 과정-1: Node Server

스플래시 이미지 생성 과정-1: Node Server

- Node Server를 두고 스플래시 로고 이미지를 정확하게 추출해 내기 위해서 Node Server에서 조합하여 react-native-bootsplash에서 요구하는 이미지를 추출해 내는 과정입니다.
- 해당 과정에서는 메인 아이콘을 기반으로 스플래시 이미지를 간단하게 만듭니다.

1. 메인 아이콘을 아래에서 bg를 제거합니다.

메인 아이콘을 아래에서 bg를 제거합니다

- 아래에 사픽: 사자성어 퀴즈의 메인 아이콘이 있습니다. 스플레시 이미지의 백그라운드와 겹쳐서 색 조합을 하기가 어렵다는 문제점이 있기에 bg를 빼는 사이트에서 수행을 합니다.

이미지 배경 제거, 투명 배경 만들기 – remove.bg

사진이나 이미지 배경을 한 번 클릭으로 5초만에 무료로 제거할 수 있습니다. 이미지 배경 투명하게 만드는 법. 누끼 따기 프로그램.

www.remove.bg

수행 결과

2. 노드 서버 구축

노드 서버 구축

- 아래와 같이 ‘sharp’라는 이름으로 구성하였고, image/*, main.js 파일 형태로 구성이 되어 있습니다.

Node에서 이미지를 처리하는 라이브러리로 ‘sharp’를 이용하여서 구성하였습니다.

# 아래 라이브러리를 설치하였습니다.
npm i sharp fs

3. image/ 경로에 bg를 제거한 이미지를 옮겨두었습니다.

image/ 경로에 bg를 제거한 이미지를 옮겨두었습니다.

- 이미지 파일명은 bgRemoveImage로 지정을 하였습니다.

4. main.js

main.js

1. characterBuf 과정에서는 사전에 준비한 이미지를 리사이즈합니다.
2. compositeBuf 과정에서는 캐릭터와 SVG(배경 그라디언트, 스파클, 메인텍스트, 서브텍스트)로 구성이 되어 있고, 이를 함께 합성합니다.
3. sharp 과정에서는 두 개 캐릭터와 SVG를 합성하여서 최종적으로 react-native-bootsplash가 요구한 결과값으로 출력을 합니다.

import sharp from "sharp";
import { mkdirSync } from "fs";

const width = 500;
const height = 500;

mkdirSync("./output", { recursive: true });

const sparkles = `
  ✦import sharp from "sharp";
import { mkdirSync } from "fs";

const width = 500;
const height = 500;

mkdirSync("./output", { recursive: true });

const sparkles = `
  <text x="56"  y="108" font-size="22" text-anchor="middle" opacity="0.5"  fill="#FFF5E6">✦</text>
  <text x="448" y="154" font-size="18" text-anchor="middle" opacity="0.45" fill="#FFF5E6">✦</text>
  <text x="66"  y="352" font-size="14" text-anchor="middle" opacity="0.35" fill="#FFF5E6">✧</text>
  <text x="438" y="322" font-size="20" text-anchor="middle" opacity="0.45" fill="#FFF5E6">✦</text>
  <text x="110" y="52"  font-size="12" text-anchor="middle" opacity="0.4"  fill="#FFF5E6">✧</text>
  <text x="382" y="70"  font-size="16" text-anchor="middle" opacity="0.45" fill="#FFF5E6">✦</text>
  <text x="458" y="412" font-size="12" text-anchor="middle" opacity="0.32" fill="#FFF5E6">✧</text>
  <text x="42"  y="438" font-size="12" text-anchor="middle" opacity="0.32" fill="#FFF5E6">✧</text>
  <text x="198" y="42"  font-size="10" text-anchor="middle" opacity="0.35" fill="#FFF5E6">·</text>
  <text x="308" y="36"  font-size="11" text-anchor="middle" opacity="0.3"  fill="#FFF5E6">·</text>
  <text x="476" y="234" font-size="10" text-anchor="middle" opacity="0.25" fill="#FFF5E6">·</text>
  <text x="24"  y="250" font-size="11" text-anchor="middle" opacity="0.25" fill="#FFF5E6">·</text>
  <text x="458" y="468" font-size="16" text-anchor="middle" opacity="0.55" fill="#FFF5E6">✦</text>
`;


const mainTitle = "사픽: 사자성어 퀴즈";
const subTitle = "사자성어 퀴즈로 배우는 쉽고 재미있는 한자 학습";

const svg = `
<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <radialGradient id="bgGrad" cx="38%" cy="32%" r="72%">
      <stop offset="0%"   stop-color="#FFB366"/>
      <stop offset="55%"  stop-color="#FF8C42"/>
      <stop offset="100%" stop-color="#D95F1E"/>
    </radialGradient>
    <radialGradient id="glowBottom" cx="50%" cy="100%" r="55%">
      <stop offset="0%"   stop-color="#FFD4A3" stop-opacity="0.55"/>
      <stop offset="100%" stop-color="#FF8C42" stop-opacity="0"/>
    </radialGradient>
    <linearGradient id="textGrad" x1="0%" y1="0%" x2="100%" y2="0%">
      <stop offset="0%"   stop-color="#FFFBF2"/>
      <stop offset="100%" stop-color="#FFE4C4"/>
    </linearGradient>
    <linearGradient id="lineGrad" x1="0%" y1="0%" x2="100%" y2="0%">
      <stop offset="0%"   stop-color="#FFF5E6" stop-opacity="0"/>
      <stop offset="50%"  stop-color="#FFF5E6" stop-opacity="0.75"/>
      <stop offset="100%" stop-color="#FFF5E6" stop-opacity="0"/>
    </linearGradient>
  </defs>

  <!-- 하단 글로우 타원 -->
  <ellipse cx="250" cy="455" rx="210" ry="50" fill="url(#glowBottom)" opacity="0.65"/>

  <!-- 스파클 -->
  ${sparkles}

  <!-- 구분선 -->
  <line x1="125" y1="410" x2="375" y2="410"
    stroke="url(#lineGrad)" stroke-width="1.2" stroke-linecap="round"/>

  <!-- 메인 텍스트 -->
  <text x="250" y="444" text-anchor="middle"
    font-family="'Apple SD Gothic Neo', 'Noto Sans KR', Arial, sans-serif"
    font-size="40" font-weight="bold"
    fill="url(#textGrad)" letter-spacing="1">${mainTitle}</text>

  <!-- 서브 텍스트 -->
  <text x="250" y="478" text-anchor="middle"
    font-family="'Apple SD Gothic Neo', 'Noto Sans KR', Arial, sans-serif"
    font-size="14"
    fill="#FFE4C4" letter-spacing="2.5" opacity="0.95">${subTitle}</text>
</svg>`;

const characterBuf = await sharp("./image/bgRemoveImg.png")
  .resize(420, 420)
  .toBuffer();

const compositeBuf = await sharp({
  create: {
    width,
    height,
    channels: 4,
    background: { r: 0, g: 0, b: 0, alpha: 0 },
  },
})
  .composite([
    { input: characterBuf, top: 0, left: 40 },
    { input: Buffer.from(svg), top: 0, left: 0 },
  ])
  .png()
  .toBuffer();

await sharp(compositeBuf)
  .resize(500, 500, {
    fit: "contain",
    background: { r: 0, g: 0, b: 0, alpha: 0 },
  })
  .png()
  .toFile("./output/bootsplash_logo.png");

console.log("완료! ./output/bootsplash_logo.png 생성됨");

  ✦
  ✧
  ✦
  ✧
  ✦
  ✧
  ✧
  ·
  ·
  ·
  ·
  ✦
`;

const mainTitle = "사픽: 사자성어 퀴즈";
const subTitle = "사자성어 퀴즈로 배우는 쉽고 재미있는 한자 학습";

const svg = `

  
    
      
      
      
    
    
      
      
    
    
      
      
    
    
      
      
      
    
  

  
  

  
  ${sparkles}

  
  

  
  ${mainTitle}

  
  ${subTitle}
`;

const characterBuf = await sharp("./image/bgRemoveImg.png")
  .resize(420, 420)
  .toBuffer();

const compositeBuf = await sharp({
  create: {
    width,
    height,
    channels: 4,
    background: { r: 0, g: 0, b: 0, alpha: 0 },
  },
})
  .composite([
    { input: characterBuf, top: 0, left: 40 },
    { input: Buffer.from(svg), top: 0, left: 0 },
  ])
  .png()
  .toBuffer();

await sharp(compositeBuf)
  .resize(500, 500, {
    fit: "contain",
    background: { r: 0, g: 0, b: 0, alpha: 0 },
  })
  .png()
  .toFile("./output/bootsplash_logo.png");

console.log("완료! ./output/bootsplash_logo.png 생성됨");

5. node를 실행하여 결과값을 확인합니다.

node를 실행하여 결과값을 확인합니다.

- 합성된 이미지를 결과값으로 반환받습니다.

node main.js

6. 결과적으로 output/bootsplash_logo.png 파일이 출력이 됩니다.

3) 스플래시 이미지 생성 과정-1: React Native

1. RN 프로젝트 내에 해당 이미지를 복사 & 붙여 넣기 한다.

2. RN 프로젝트에서 아래의 명령어를 입력합니다.

RN 프로젝트에서 아래의 명령어를 입력합니다.

- react-native-bootsplash의 자산 자동 생성 CLI 명령어입니다.
- 여기서 주요한 내용은 background입니다. 사전에 이미지는 bg를 제거한 상태입니다.
- 그렇기에 이에 알맞은 hex 색상에 맞게 적용을 합니다.

# Android
yarn react-native-bootsplash generate ./src/assets/images/bootsplash_logo.png \
  --platforms=android \
  --background="#ff8c42" \
  --logo-width=134 \
  --flavor=main

# iOS
yarn react-native-bootsplash generate ./src/assets/images/bootsplash_logo.png \
  --platforms=ios \
  --background="#ff8c42" \
  --logo-width=400 \
  --flavor=main

[ 더 알아보기]

안드로이드, iOS 플랫폼에 분리하는 이유는 뭘까?

- 아래와 같이 'Logo exceeds 192x192dp and will be cropped by Android. Skipping its generation.'가 발생합니다.
- Android는 최대 192x192dp 제한이 있어서 Android 생성을 건너뛰어지게 됩니다.

3. 결론적으로 아래와 같이 스플래시 결과물이 적용이 됩니다.

4. 앱 자체를 재빌드 해야 하며 아래와 같은 결과를 얻을 수 있습니다.

사픽: 사자성어 퀴즈 - Google Play 앱

사자성어를 카드로 배우고, 퀴즈와 오답 복습으로 완벽히 암기하는 학습 앱

play.google.com

사픽: 사자성어 퀴즈 앱 - App Store

apps.apple.com

오늘도 감사합니다.

[Java] p6spy-spring-boot-starter 이해하고 활용하기 : MyBatis + Log4j2 + Slf4j

adjh54 — Thu, 5 Mar 2026 20:10:13 +0900

해당 글에서는 MyBatis를 이용하기 위해 DB Fomratter로 p6spy 적용 방법 및 활용 방법에 대해 알아봅니다

1) p6spy-spring-boot-starter

p6spy-spring-boot-starter

- SQL 쿼리를 실제 실행되는 완성된 형태(파라미터 바인딩 포함)로 로깅해 주는 라이브러리를 의미합니다.
- JPA/MyBatis 환경에서 ?로 표시되는 파라미터 값을 실제 값으로 치환해서 보여줍니다.
- MyBatis를 이용한 경우 log4jdbc-log4j2를 이용하였지만, 2013년 이후에 업데이트가 중단되었고 설정이 복잡하다는 점이 있었습니다. 그렇기에 p6spy-spring-boot-starter를 적용해 봅니다.

[참고] 기존의 log4jdbc-log4j2에 대해 궁금하시면 아래의 글을 참고하시면 도움이 됩니다.

[Java] MyBatis Query Formatter 이해하고 적용하기 : log4jdbc-log4j2 4.1

해당 글에서는 MyBatis로 처리되는 Query에 대한 Formatting을 적용하기 위해 ‘log4 jdbc-log4j2’를 적용하는 글에 대해 공유합니다. 1) log4jdbc-log4j2 log4jdbc-log4j2 - 자바 애플리케이션에서 ‘JDBC 드라이

adjh54.tistory.com

[참고] p6spy vs log4jdbc-log4j2 비교

항목	p6spy	log4jdbc-log4j2
Spring Boot AutoConfig	자동	수동 Bean 설정 필요
유지보수 상태	활발	사실상 중단
최신 Spring Boot 호환	3.x 완벽 지원	호환 이슈 잦음
설정 난이도	쉬움	복잡함
커스터마이징	Java Config 가능	제한적
실행시간 측정	기본 제공	기본 제공
멀티 DataSource	자동 처리	각각 수동 설정

2) p6spy-spring-boot-starter 환경 설정

p6spy-spring-boot-starter 환경 설정

1. 의존성 추가

의존성 추가

- 가장 최신 버전을 기반으로 설치를 합니다.

// Source: <https://mvnrepository.com/artifact/com.github.gavlyukovskiy/p6spy-spring-boot-starter>
implementation("com.github.gavlyukovskiy:p6spy-spring-boot-starter:2.0.0")

https://mvnrepository.com/artifact/com.github.gavlyukovskiy/p6spy-spring-boot-starter/2.0.0

2. application.yml

application.yml

- 기존의 Log4j2 + Slf4J를 기반으로 로깅을 구성하였고, yml 파일 형태로 환경을 설정하였습니다.

# p6spy-spring-boot-starter Configuration
decorator:
  datasource:
    p6spy:
      enable-logging: true
      logging: slf4j
      # SQL을 한 줄로 정렬해서 보여줄지 여부
      multiline: true

# spring-boot-starter-log4j2 Configuration
logging:
  # default Logging 프레임워크 설정 파일을 참조
  config: classpath:config/logs/log4j2-loc.yml

[참고] Spring Boot Log4j2 이해하기 -1 : 주요 특징, 구성 요소, yml 설정방법

[Java] Spring Boot Log4j2 이해하기 -1 : 주요 특징, 구성 요소, yml 설정방법

해당 글에서는 Log4j2에 대해 이해하고 Spring Boot 환경에서 Log4j2를 설정하는 방법에 대해 알아봅니다. [참고] xml 형태로 간단한 설정을 하는 방법에 대해 알고 싶으시면 이전에 작성한 글을 참

adjh54.tistory.com

3. logj42-loc.yml

log4j2-loc.yml

- 해당 부분에서는 log4j2 로깅 설정을 하는 파일입니다.
- 이 중에서도 com.p6spy.engine.spy.appender에 대한 로깅 레벨을 지정합니다.

Configuration:
  name: spring-boot-4-local
  status: WARN

  Properties:
    Property:
      - name: "log-path"
        value: "./logs"
      - name: "charset-UTF-8"
        value: "UTF-8"
      - name: "layout-pattern"
        value: "%clr{%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX}}{faint} %clr{%5p} %clr{%-5pid}{magenta} %clr{---}{faint} %clr{[%15.15t]}{faint} %clr{%-40.40C{1.}}{cyan} %clr{:}{faint} %m%n%wEx"

  Appenders:
    Console:
      - name: console-appender
        target: SYSTEM_OUT
        PatternLayout:
          pattern: ${layout-pattern}

  Loggers:
    Root:
      level: INFO
      AppenderRef:
        - ref: console-appender

    Logger:
      - name: org.springframework
        level: INFO
        additivity: false
        AppenderRef:
          - ref: console-appender

      - name: packeage_root_path
        level: INFO
        additivity: false
        AppenderRef:
          - ref: console-appender

      # P6Spy 전용 로거 설정
      - name: com.p6spy.engine.spy.appender
        level: INFO
        additivity: false
        AppenderRef:
          - ref: console-appender

4. resources/spy.properties

resources/spy.properties

- 로그 포맷을 설정하고, 실행 시간을 지정합니다. 그리고 필터 내용에 대해서 지정이 가능합니다.
- 또한, logMessageFormat를 통해서 커스텀 포맷터 클래스를 참조할 수 있지만, 기본만을 이용한다고 하면 customLogMessageFormat 속성값을 입력하면 기본만 적용이 가능합니다.

# 로그 포맷 설정
appender=com.p6spy.engine.spy.appender.Slf4JLogger

# 커스텀 포멧터 클래스 참조(추가 커스텀 포멧을 이용하는 경우)
# logMessageFormat=package.name.config.P6SpyFormatter

# 실행 시간 ms 기준 (0이면 전부 출력)
executionThreshold=0

# 특정 카테고리만 로깅
filter=false
include=
exclude=

# 간단 버전을 한다면, P6SpyFormatter 구성없이 기본 설정으로 가능
customLogMessageFormat=%(executionTime)ms | %(sql)

[참고] 기본 옵션만을 저장하는 경우

[참고] logMessageFormat을 통해 적용하는 경우

- 아래와 같이 커스텀으로 실행 정보, 바인딩 파라미터, 호출위치, 실행 SQL을 확인할 수 있습니다.

5. (선택) P6SpyFormatter

(선택) P6SpyFormatter

- P6Spy에서 제공하는 기본정보에 추가적으로 커스텀으로 정보를 추가하였습니다.
- 실행 정보, 바인딩 파라미터, 호출위치, 실행 SQL을 확인할 수 있습니다.

import com.p6spy.engine.spy.appender.MessageFormattingStrategy;
import org.springframework.context.annotation.Configuration;

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
import java.util.Stack;

/**
 * P6Spy SQL 로그 포매터
 * - SQL 타입 감지 및 아이콘 표시
 * - 콜스택 기반 호출 위치 추적
 * - 바인딩 파라미터 타입 추론
 *
 * @author : leejonghoon
 * @fileName : P6SpyFormatter
 * @since : 26. 3. 3.
 */
@Configuration
public class P6SpyFormatter implements MessageFormattingStrategy {

    private static final DateTimeFormatter DATE_FORMATTER =
            DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss.SSS");

    private static final String BASE_PACKAGE = "com.daekyocns";

    @Override
    public String formatMessage(int connectionId, String now, long elapsed,
                                String category, String prepared, String sql, String url) {
        if (sql == null || sql.isBlank()) return "";

        String sqlType = detectSqlType(sql);
        String callStack = buildCallStack();
        List<String> params = extractParams(prepared, sql);

        StringBuilder sb = new StringBuilder();
        sb.append("\\n+==============================================================");
        sb.append("\\n|  SQL ").append(sqlType);
        sb.append("\\n+==============================================================");
        sb.append("\\n|  실행시각    ").append(LocalDateTime.now().format(DATE_FORMATTER));
        sb.append("\\n|  실행시간    ").append(elapsed).append("ms");
        sb.append("\\n|  커넥션 ID   ").append(connectionId);
        sb.append("\\n|  카테고리    ").append(category);

        if (!params.isEmpty()) {
            sb.append("\\n+--------------------------------------------------------------");
            sb.append("\\n|  바인딩 파라미터");
            for (int i = 0; i < params.size(); i++) {
                sb.append("\\n|     [").append(String.format("%02d", i + 1)).append("] ").append(params.get(i));
            }
        }

        if (!callStack.isBlank()) {
            sb.append("\\n+--------------------------------------------------------------");
            sb.append("\\n|  호출 위치");
            sb.append(callStack);
        }

        sb.append("\\n+--------------------------------------------------------------");
        sb.append("\\n|  실행 SQL");
        sb.append("\\n|");
        for (String line : formatSql(sql).split("\\n")) {
            sb.append("\\n     ").append(line);
        }
        sb.append("\\n|");
        sb.append("\\n+==============================================================\\n");

        return sb.toString();
    }

    /**
     * SQL 타입 감지
     *
     * @param sql
     * @return
     */
    private String detectSqlType(String sql) {
        String upper = sql.trim().toUpperCase(Locale.ROOT);
        if (upper.startsWith("SELECT")) return "SELECT";
        if (upper.startsWith("INSERT")) return "INSERT";
        if (upper.startsWith("UPDATE")) return "UPDATE";
        if (upper.startsWith("DELETE")) return "DELETE";
        if (upper.startsWith("CREATE")) return "DDL · CREATE";
        if (upper.startsWith("ALTER")) return "DDL · ALTER";
        if (upper.startsWith("DROP")) return "DDL · DROP";
        if (upper.startsWith("TRUNCATE")) return "DDL · TRUNCATE";
        return "SQL";
    }

    private String getSqlIcon(String sqlType) {
        return switch (sqlType) {
            case "SELECT" -> " ";
            case "INSERT" -> "➕";
            case "UPDATE" -> "✏️";
            case "DELETE" -> " ️";
            default -> "⚙️";
        };
    }

    /**
     * 콜스택 — 프로젝트 내부 호출 위치만 추출
     *
     * @return
     */
    private String buildCallStack() {
        StackTraceElement[] trace = new Throwable().getStackTrace();
        Stack<String> stack = new Stack<>();

        for (StackTraceElement el : trace) {
            String s = el.toString();
            if (s.startsWith(BASE_PACKAGE) && !s.contains("P6SpyFormatter")) {
                stack.push(s);
            }
        }

        if (stack.isEmpty()) return "";

        StringBuilder sb = new StringBuilder();
        int order = 1;
        while (!stack.isEmpty()) {
            sb.append("\\n|     ").append(order++).append(". ").append(stack.pop());
        }
        return sb.toString();
    }

    /**
     * 파라미터 추출
     *
     * @param prepared
     * @param sql
     * @return
     */
    private List<String> extractParams(String prepared, String sql) {
        List<String> params = new ArrayList<>();
        if (prepared == null || !prepared.contains("?")) return params;

        String[] parts = prepared.split("\\\\?", -1);
        String remaining = sql;

        for (int i = 0; i < parts.length - 1; i++) {
            String prefix = parts[i];
            if (remaining.startsWith(prefix)) {
                remaining = remaining.substring(prefix.length());
            } else {
                break;
            }

            String nextPrefix = (i + 1 < parts.length) ? parts[i + 1] : "";
            String value;

            if (nextPrefix.isEmpty()) {
                value = remaining;
            } else {
                int idx = remaining.indexOf(nextPrefix);
                if (idx == -1) break;
                value = remaining.substring(0, idx);
                remaining = remaining.substring(idx);
            }
            params.add(inferType(value.trim()));
        }
        return params;
    }

    private String inferType(String v) {
        if (v.equals("null")) return v + "  [NULL]";
        if (v.matches("-?\\\\d+")) return v + "  [Integer]";
        if (v.matches("-?\\\\d+\\\\.\\\\d+")) return v + "  [Double]";
        if (v.matches("'\\\\d{4}-\\\\d{2}-\\\\d{2}.*'")) return v + "  [DateTime]";
        if (v.equalsIgnoreCase("true")
                || v.equalsIgnoreCase("false")) return v + "  [Boolean]";
        return v + "  [String]";
    }

    /**
     * SQL 포맷
     *
     * @param sql
     * @return
     */
    private String formatSql(String sql) {
        return sql.trim()
                .replaceAll("\\\\s+", " ")
                .replaceAll("(?i)\\\\b(SELECT|FROM|WHERE|AND|OR|"
                                + "LEFT JOIN|RIGHT JOIN|INNER JOIN|OUTER JOIN|CROSS JOIN|JOIN|"
                                + "GROUP BY|ORDER BY|HAVING|LIMIT|OFFSET|"
                                + "INSERT INTO|VALUES|UPDATE|SET|DELETE FROM|"
                                + "CREATE TABLE|ALTER TABLE|DROP TABLE)\\\\b",
                        "\\n  $1")
                .trim();
    }
}

3) 사용 확인

1. 데이터가 포함된 조회

+==============================================================
|  SQL SELECT
+==============================================================
|  실행시각    2026-03-03 17:01:15.009
|  실행시간    2ms
|  커넥션 ID   1
|  카테고리    statement
+--------------------------------------------------------------
|  바인딩 파라미터
|     [01] 'adjh54'  [String]
+--------------------------------------------------------------
|  호출 위치
|     1. com.daekyocns.clab.springboot4.config.filter.CustomAuthenticationFilter.attemptAuthentication(CustomAuthenticationFilter.java:52)
|     2. com.daekyocns.clab.springboot4.config.handler.CustomAuthenticationProvider.authenticate(CustomAuthenticationProvider.java:50)
|     3. com.daekyocns.clab.springboot4.service.impl.CustomUserDetailsService.loadUserByUsername(CustomUserDetailsService.java:48)
|     4. com.daekyocns.clab.springboot4.service.impl.UserServiceImpl.login(UserServiceImpl.java:41)
+--------------------------------------------------------------
|  실행 SQL
|
     SELECT t1.* 
       FROM test_scma.tb_user t1 
       WHERE user_id = 'adjh54'
|
+==============================================================

2. 데이터가 포함되지 않는 조회

2026-03-03T17:15:54.948+09:00  INFO 254   --- [nio-8000-exec-1] c.p.e.s.a.Slf4JLogger                    : 
+==============================================================
|  SQL SELECT
+==============================================================
|  실행시각    2026-03-03 17:15:54.948
|  실행시간    1ms
|  커넥션 ID   1
|  카테고리    statement
+--------------------------------------------------------------
|  호출 위치
|     1. com.daekyocns.clab.springboot4.config.filter.JwtAuthorizationFilter.doFilterInternal(JwtAuthorizationFilter.java:62)
|     2. com.daekyocns.clab.springboot4.config.filter.JwtAuthorizationFilter.processToken(JwtAuthorizationFilter.java:83)
|     3. com.daekyocns.clab.springboot4.controller.template.UserController.selectUser(UserController.java:42)
|     4. com.daekyocns.clab.springboot4.service.impl.UserServiceImpl.selectUserList(UserServiceImpl.java:48)
+--------------------------------------------------------------
|  실행 SQL
|
     SELECT t1.* 
       FROM test_scma.tb_user t1 
       WHERE t1.user_st = 'S'
|
+==============================================================

3. 사용자 등록

+==============================================================
|  SQL INSERT
+==============================================================
|  실행시각    2026-03-03 17:24:06.259
|  실행시간    15ms
|  커넥션 ID   1
|  카테고리    statement
+--------------------------------------------------------------
|  바인딩 파라미터
|     [01] 'dfddd'  [String]
|     [02] '1234'  [String]
|     [03] 'dddd'  [String]
|     [04] 'S'  [String]
+--------------------------------------------------------------
|  호출 위치
|     1. com.daekyocns.clab.springboot4.config.filter.JwtAuthorizationFilter.doFilterInternal(JwtAuthorizationFilter.java:62)
|     2. com.daekyocns.clab.springboot4.config.filter.JwtAuthorizationFilter.processToken(JwtAuthorizationFilter.java:83)
|     3. com.daekyocns.clab.springboot4.controller.template.UserController.insertUser(UserController.java:39)
|     4. com.daekyocns.clab.springboot4.service.impl.UserServiceImpl.insertUser(UserServiceImpl.java:54)
+--------------------------------------------------------------
|  실행 SQL
|
     INSERT INTO test_scma.tb_user (user_id, user_pw, user_nm, user_st) 
       VALUES ('dfddd', '1234', 'dddd', 'S')
|
+==============================================================

오늘도 감사합니다.

[JS] OG 태그(Open Graph Tags) 이해하고 적용하기

adjh54 — Thu, 5 Mar 2026 20:05:23 +0900

해당 글에서는 OG 태그(Open Graph Tags)를 적용하고 이해하는 방법에 대해서 알아봅니다

1) OG 태그(Open Graph Tags)

OG 태그(Open Graph Tags)

- Facebook이 2010년에 만든 프로토콜로, 웹페이지가 소셜 미디어에 공유될 때 어떻게 표시될지를 제어하는 메타 태그입니다.
- 현재는 Facebook, Twitter/X, KakaoTalk, LinkedIn, Slack 등 대부분의 플랫폼에서 표준처럼 사용됩니다.
- <head> 태그 안에 <meta property="og:..." content="..."> 형식으로 작성합니다.

Open Graph protocol

The Open Graph protocol enables any web page to become a rich object in a social graph.

ogp.me

아래와 같이 카카오톡에서 링크를 공유하면 아래와 같이 표시가 됩니다.

아래와 같이 Slack에 링크를 공유하면 아래와 같이 표시가 됩니다.

1. 필수 항목

필수 항목

- 아래와 같이 필수 태그는 추가되지 않으면 공유시 깨지거나 나타나지 않을 수 있습니다.

속성(Property)	설명	사용 예시
og:title	소셜 미디어 공유 시 노출될 메인 제목입니다.	Ecodelab - 제작 앱 소개
og:description	제목 아래에 표시되는 페이지의 상세 요약 문구입니다.	Ecodelab에서 개발한 다양한 앱들을 소개합니다
og:image	공유 시 미리보기로 나타날 대표 이미지 경로입니다.	https://www.ecodelab.im/assets/developer.png
og:url	해당 페이지의 정식(Canonical) URL 주소입니다.	https://example.com/home
og:type	콘텐츠의 성격을 정의하며, 여기서는 웹사이트로 설정되었습니다.	https://www.ecodelab.im

<head>
    <!-- 페이지 제목 -->
    <meta property="og:title" content="Ecodelab - 제작 앱 소개" />

    <!-- 페이지 설명 -->
    <meta property="og:description" content="Ecodelab에서 개발한 다양한 앱들을 소개합니다" />

    <!-- 대표 이미지 (1200x630px 권장) -->
    <meta property="og:image" content="https://www.ecodelab.im/assets/developer.png" />

    <!-- 페이지 URL -->	
    <meta property="og:url" content="https://www.ecodelab.im" />

    <!-- 콘텐츠 타입 -->
    <meta property="og:type" content="website" />

</head>

2. 선택적 태그

선택적 태그

- 필수는 아니지만 선택적으로 추가가 가능한 태그입니다.

속성(Propety)	설명	사용예시
og:site_name	사이트 이름	EcodeLab
og:locale	언어/지역	ko_KR / en_US

<head>
  <!-- 사이트 이름 -->
  <meta property="og:site_name" content="Ecodelab" />
  <!-- 언어/지역 설정 -->
  <meta property="og:locale" content="ko_KR" />
</head>

3. 이미지 상세 태그

이미지 상세 태그

- 이미지에 대해 상세로 작성이 가능한 태그를 의미합니다.

속성(Property)	설명	사용예시
og:image	소셜 미디어에 표시될 메인 이미지의 절대 경로입니다.	https://www.ecodelab.im/assets/developer.png
og:image:width	이미지의 가로 크기를 1200픽셀로 명시하여 미리보기 로딩 속도를 높입니다.	1200
og:image:height	이미지의 세로 크기를 630픽셀로 명시합니다. (1.91:1 비율 권장)	630
og:image:type	이미지 파일의 MIME 타입을 지정합니다.	image/png
og:image:alt	스크린 리더나 이미지를 불러오지 못할 경우 사용되는 대체 텍스트입니다.	EcodeLab 대표 이미지

<head>
  <!-- 대표 이미지 URL -->
  <meta property="og:image" content="https://example.com/og-image.png" />
  
  <!-- 이미지 너비 (px) -->
  <meta property="og:image:width" content="1200" />
  
  <!-- 이미지 높이 (px) -->
  <meta property="og:image:height" content="630" />
  
  <!-- 이미지 MIME 타입 -->
  <meta property="og:image:type" content="image/png" />
  
  <!-- 이미지 대체 텍스트 -->
  <meta property="og:image:alt" content="로또 지니 앱 소개 이미지" />
</head>

2) 기타 태그

기타 태그

1. Article 태그
- og:type을 article로 설정했을 때 사용하는 태그입니다.
- 작성자, 발행일, 카테고리 등 글에 대한 상세 정보를 추가로 표현할 수 있습니다.

2. Twitter / X Card 태그
- Twitter(X) 전용 공유 카드를 위한 태그입니다.
- OG 태그만으로도 동작하지만, 카드 타입이나 작성자 계정 등 Twitter만의 세부 설정이 필요할 때 사용합니다.

3. App Links 태그
- 모바일 앱이 존재할 경우 사용합니다.
- 앱이 설치된 기기에서는 딥링크로 앱을 직접 실행하고, 설치되지 않은 경우에는 웹 페이지로 이동하도록 연결해줍니다.

1. Article 태그

Article 태그

- Facebook이나 LinkedIn에 공유했을 때 article 타입이면 "언제 작성된 글인지, 누가 썼는지" 같은 정보를 추가로 표시해줍니다.
- 또한 Google 검색엔진도 이 태그를 참고해서 콘텐츠 신선도(최신성) 를 판단하는 데 활용합니다.

속성(Property)	설명	사용 예시
og:type	콘텐츠 타입을 '기사(article)'로 지정하여 일반 웹사이트와 차별화합니다.	article
article:author	이 글을 작성한 사람의 프로필 페이지 또는 SNS 계정 링크입니다.	https://example.com/author
article:published_time	기사가 처음 발행된 날짜와 시간을 ISO 8601 형식으로 나타냅니다.	2025-01-01T00:00:00Z
article:modified_time	기사가 마지막으로 수정된 날짜와 시간입니다.	2025-06-01T00:00:00Z
article:section	기사의 주요 카테고리나 섹션(예: 기술, 뉴스, 요리 등)을 정의합니다.	Technology
article:tag	기사와 관련된 핵심 키워드(태그)입니다.	ecodelab, 앱소개

<head>
    <!-- 이 페이지는 "기사(article)" 타입임을 선언 -->
    <meta property="og:type" content="article" />

    <!-- 이 글의 작성자 프로필 URL -->
    <meta property="article:author" content="https://example.com/author" />

    <!-- 최초 발행일 -->
    <meta property="article:published_time" content="2025-01-01T00:00:00Z" />

    <!-- 마지막 수정일 -->
    <meta property="article:modified_time" content="2025-06-01T00:00:00Z" />

    <!-- 카테고리 (섹션) -->
    <meta property="article:section" content="Technology" />

    <!-- 태그/키워드 -->
    <meta property="article:tag" content="ecodelab, 앱소개" />
</head>

2. Twitter / X Card 태그

Twitter / X Card 태그

-OG 태그를 일부 인식하지만, 전용 태그가 따로 있습니다.

https://www.everywheremarketer.com/blog/how-to-use-twitter-cards

속성(Propery)	설명	사용 예시
twitter:card	트위터에서 링크 공유 시 표시될 카드의 형태입니다. (큰 이미지 타입)	summary_large_image
twitter:site	웹사이트의 공식 트위터 계정 아이디입니다.	@your_twitter_id
twitter:creator	콘텐츠 작성자의 트위터 계정 아이디입니다.	@author_twitter_id
twitter:title	카드 상단에 노출될 제목입니다.	로또 지니 - 행운의 번호 생성기
twitter:description	카드 중앙에 노출될 상세 설명 문구입니다.	QR 스캔으로 당첨번호 확인, 번호 생성까지!
twitter:image	트위터 카드에 표시될 전용 이미지 경로입니다.	https://example.com/twitter-card.png

<head>
	<!-- 트위터 공유 시 카드 표시 형식 지정 -->
	<!-- summary: 작은 썸네일 | summary_large_image: 큰 이미지 | app: 앱 소개 | player: 동영상 -->
	<meta name="twitter:card" content="summary_large_image" />
	
	<!-- 이 웹사이트/서비스의 트위터 계정 (@계정명) -->
	<meta name="twitter:site" content="@your_twitter_id" />
	
	<!-- 이 콘텐츠를 작성한 사람의 트위터 계정 (@계정명) -->
	<!-- 블로그나 기사처럼 작성자가 명확할 때 사용, 서비스 페이지면 생략 가능 -->
	<meta name="twitter:creator" content="@author_twitter_id" />
	
	<!-- 트위터 공유 카드에 표시될 제목 -->
	<!-- og:title과 동일하게 설정하는 것이 일반적 -->
	<meta name="twitter:title" content="로또 지니 - 행운의 번호 생성기" />
	
	<!-- 트위터 공유 카드에 표시될 설명 텍스트 -->
	<!-- og:description과 동일하게 설정하는 것이 일반적 -->
	<meta name="twitter:description" content="QR 스캔으로 당첨번호 확인, 번호 생성까지!" />
	
	<!-- 트위터 공유 카드에 표시될 이미지 URL (반드시 절대경로) -->
	<!-- summary_large_image 기준 권장 크기: 1200x628px, 5MB 이하 -->
	<meta name="twitter:image" content="https://example.com/twitter-card.png" />
</head>

[참고] 아래의 사이트에서 확인해보고 테스트 할 수 있습니다.

Meta Tags — Preview, Edit and Generate

With Meta Tags you can edit and experiment with your content then preview how your webpage will look on Google, Facebook, X and more!

metatags.io

3. 앱 링크 태그 (App Links)

앱 링크 태그 (App Links)

- 모바일 앱이 있을 경우 딥링크 연동에 사용합니다.

구분	속성(Property)	설명	사용 예시
iOS	al:ios:url	iOS 기기에서 앱을 실행할 때 사용할 커스텀 스킴 주소입니다.	lottogenie://home
iOS	al:ios:app_store_id	앱이 설치되지 않았을 경우 이동할 앱스토어의 고유 ID입니다.	6746621734
iOS	al:ios:app_name	앱스토어나 기기 내에서 표시될 앱의 명칭입니다.	로또 지니
Android	al:android:url	안드로이드 기기에서 앱을 실행할 때 사용할 커스텀 스킴 주소입니다.	lottogenie://home
Android	al:android:package	안드로이드 마켓(Play 스토어)의 패키지 명칭입니다.	com.tha.lottogenerator
Android	al:android:app_name	안드로이드 기기 내에서 표시될 앱의 명칭입니다.	로또 지니
Web	al:web:url	앱이 없거나 지원하지 않는 환경에서 보여줄 웹페이지 주소(Fallback)입니다.	https://example.com/home

<head>
	<!-- iOS 앱이 설치되어 있을 때 열릴 딥링크 URL (앱 내 특정 화면으로 이동) -->
	<meta property="al:ios:url" content="lottogenie://home" />
	
	<!-- App Store에 등록된 앱의 고유 ID (없으면 App Store로 이동 불가) -->
	<meta property="al:ios:app_store_id" content="6746621734" />
	
	<!-- App Store에 표시될 앱 이름 -->
	<meta property="al:ios:app_name" content="로또 지니" />
	
	<!-- Android 앱이 설치되어 있을 때 열릴 딥링크 URL (앱 내 특정 화면으로 이동) -->
	<meta property="al:android:url" content="lottogenie://home" />
	
	<!-- Google Play Store에 등록된 앱의 패키지명 (없으면 Play Store로 이동 불가) -->
	<meta property="al:android:package" content="com.lottogenie.app" />
	
	<!-- Play Store에 표시될 앱 이름 -->
	<meta property="al:android:app_name" content="로또 지니" />
	
	<!-- iOS/Android 앱이 둘 다 설치되어 있지 않을 때 이동할 웹 폴백(fallback) URL -->
	<meta property="al:web:url" content="https://example.com/home" />
</head>

[JS] 스키마 마크업(Schema Markup) 이해하고 적용하기

adjh54 — Thu, 5 Mar 2026 20:00:01 +0900

해당 글에서는 스키마 마크업에 대해 이해하고 이를 적용하는 방법에 대해 알아봅니다

1) 스키마 마크업(Schema Markup)

스키마 마크업(Schema Markup)

- Schema.org에서 정의한 표준 코드를 HTML내에 추가하여 검색 엔진이 웹페이지 콘텐츠의 의미(레시피, 제품, 이벤트 등)를 정확히 이해하도록 돕는 구조화된 데이터입니다.
- 예를 들어서, 검색 결과로 나타낼 때, 단순히 "이 페이지에 텍스트가 있다"라고 보여주는 것이 아니라, "이 부분은 메인 메뉴이고, 이 부분은 하위 카테고리다"라고 구조를 선언하는 행위입니다.
- JSON-LD 형식을 가장 많이 사용하며, 이를 통해 검색 결과에 풍부한 정보(리치 스니펫)를 표시해 클릭률(CTR)과 SEO 성과를 높입니다.

https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data?hl=ko

1. 리치 결과(Rich Results)

리치 결과(Rich Results)

- 검색 엔진이 웹페이지의 내용을 더 잘 이해할 수 있고, 사용자에게 더욱 눈길을 끄는 검색결과를 제공하기에 추가된 스키마 마크업 정보를 바탕으로, 검색 결과 페이지에서 일반적인 텍스트 링크보다 훨씬 풍부하고 시각적인 정보를 제공하는 기능을 말합니다.

- 쉽게 말해, 검색 결과가 단순히 '제목 - URL - 설명'으로만 끝나는 것이 아니라, 사용자에게 도움이 되는 추가 정보를 UI 형태로 보여주는 것입니다.
- 예로는, 검색 결과에서 별점, 가격, 조리 시간, 이벤트 날짜 등이 추가적으로 표시됩니다. 이는 클릭률(CTR)을 비약적으로 높여줍니다.

리치 검색결과 테스트 - Google Search Console

페이지에서 리치 검색결과를 지원하나요? 올바른 URL이 아닙니다.테스트에 사용할 에이전트Google 검사 도구 스마트폰Google 검사 도구 데스크톱테스트에 사용할 에이전트Google 검사 도구

search.google.com

아래와 같이 리치 결과로 나오는 관련 질문(People Also Ask)으로 출력이 됩니다.

2. 사이트 링크

사이트 링크

- Google이 브랜드 검색 시 메인 결과 아래에 자동으로 추가해 주는 하위 페이지 링크 목록입니다.(이는 스키마 마크업과는 무관하지만 이해를 하는데 도움이 됩니다.)

- 해당 사이트 링크는 모든 페이지에 나오지 않고, 브랜드명 검색 시 압도적 1위이며, 사이트가 충분한 기간 동안 운영이 되었을 경우 등 일 때 Google에서 자동으로 추가해 주는 링크 목록입니다.
- 스키마 마크업과 같이 개발자가 이를 다루는 것이 아니라 Google 내에서 이를 노출하기에 스키마 마크업과 차이가 있습니다.

사이트링크에 대해 자세히 알아보기 | Google 검색 센터 | Documentation | Google for Developers

사이트링크란 무엇이고 자연 검색결과에 어떻게 표시되는지, 사용자가 내 사이트를 더 효과적으로 탐색하는 데 어떻게 이용될 수 있는지 알아보세요.

developers.google.com

아래와 같이 ‘네이버’를 검색했을때, 가장 먼저 나오는 정보에 대해서 사이트 링크가 출력이 됩니다.

2) 스키마 마크업(Schema Markup) 리치 결과 종류

리치 결과 종류	설명
지식 패널	스키마 마크업은 등록은 가능하지만, 구글에 의해서 자동으로 결정이 됨
FAQPage	스키마 마크업은 등록 가능하지만, 2023년 이후부터 정부/보건 사이트에서만 기록됨
별점/리뷰	스키마 마크업으로 등록 가능
레시피	스키마 마크업으로 등록 가능

[참고] 추가 종류에 대해서는 아래에 공식 사이트에서 확인이 가능합니다

Google 검색에서 지원하는 구조화된 데이터 마크업 | Google 검색 센터 | Documentation | Google for De

검색결과에 표시되는 방식의 예를 포함하여 Google 검색에 표시될 수 있는 구조화된 데이터 지원 기능을 살펴보세요. 사이트가 Google 검색의 리치 결과에 표시되도록 구조화된 데이터를 추가하는

developers.google.com

1. 지식 패널

지식 패널

- 브랜드나 인물에 대한 정보를 구글 지식 패널(오른쪽 정보창)에 노출하는 데 기여합니다.
- 실제적으로 스키마 마크업에 등록을 하였다고 하더라도, 해당 브랜드명으로 검색이 충분히 발생하는 경우에 해당 패널이 생성이 됩니다.

2. FAQPage

FAQPage

- 페이지에 질문과 답변 목록이 있음을 검색엔진에 알려주는 구조화 데이터입니다.
- 2023년 Google이 FAQPage 리치 결과 정책을 크게 변경했습니다. 현재는 정부 또는 보건 당국 중심의 공신력 있는 사이트에만 FAQ 리치 결과를 표시합니다

- 실제적으로 사용이 되지는 않지만, 검색엔진이 페이지를 더 잘 이해하고 순위를 매기는 데 도움을 주며, AI가 콘텐츠를 질문-답변 쌍으로 명확하게 인식하게 해 줘서 AI 검색(ChatGPT 등)에서 인용될 확률이 높아집니다.

[참고] FAQPage 변경사항에 대한 정보

FAQ Schema in 2025: Still a Valuable SEO Asset | Epic Notion

Learn why FAQ schema remains a powerful SEO tool in 2025 despite Google's changes. Discover how to optimize FAQ schema for better search visibility and UX.

www.epicnotion.com

3. 별점(AggregateRating) / 리뷰(Review)

별점(AggregateRating) / 리뷰(Review)

- 구글 검색 결과를 리치 결과(Rich Results)로 만들어 클릭률을 높여주는 핵심 요소들입니다. 이는 특정 제품이나 서비스 아래에 표시되는 별점(Star Rating)과 리뷰 개수를 사용자 클릭률(CTR)을 높이는 아주 강력한 요소입니다.

1. 종합 별점 (AggregateRating)
- 개별 리뷰가 아닌, 전체 평균 점수와 참여 인원을 보여줄 때 사용합니다.

2. 개별 리뷰 (Review)
- 특정 사용자가 남긴 구체적인 평점과 코멘트를 보여줄 때 사용합니다.

https://developers.google.com/search/docs/appearance/structured-data/sd-policies

{
  "@type": "SoftwareApplication",
  "name": "앱 이름",
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.5",   ← DB에서 평균값 가져와서 동적으로
    "ratingCount": "120",   ← DB에서 리뷰 수 가져와서 동적으로
    "bestRating": "5"
  },
  "review": [
    {
      "@type": "Review",
      "author": {"@type": "Person", "name": "유저명"},
      "reviewRating": {
        "@type": "Rating",
        "ratingValue": "5"
      },
      "reviewBody": "리뷰 내용"
    }
  ]
}

[ 더 알아보기 ]

별점/리뷰는 하드코딩으로 작성하는것 같은데? 만약에 내가 홍보하고 싶은 앱인 경우는 어떻게 하나?

- 실제로 Store에 있는 실제 별점을 그대로 사용하는 게 가장 안전하며, 현재 별점과 리뷰 수를 확인해서 하드코딩으로 넣고, 주기적으로 업데이트해 주면 됩니다.

4. 레시피

레시피

- 스키마를 잘 적용하면 구글 검색 결과에 요리 소요 시간, 칼로리, 완성 사진이 포함된 '레시피 카드' 형태로 노출되어 클릭률이 비약적으로 상승합니다.

{
  "@context": "<a href=https://schema.org/>https://schema.org/</a>",
  "@type": "Recipe",
  "name": "할머니 손맛 순우리말 비빔밥",
  "image": [
    "<a href=https://example.com/photos/1x1/photo.jpg>https://example.com/photos/1x1/photo.jpg</a>"
  ],
  "author": {
    "@type": "Person",
    "name": "우리말 지킴이"
  },
  "datePublished": "2026-02-19",
  "description": "전통적인 방식으로 만드는 건강한 비빔밥 레시피입니다.",
  "prepTime": "PT20M",
  "cookTime": "PT15M",
  "recipeYield": "2인분",
  "recipeIngredient": [
    "쌀 2컵",
    "고추장 2큰술",
    "각종 나물"
  ],
  "recipeInstructions": [
    {
      "@type": "HowToStep",
      "text": "쌀을 씻어 밥을 짓습니다.",
      "image": "<a href=https://example.com/step1.jpg>https://example.com/step1.jpg</a>"
    },
    {
      "@type": "HowToStep",
      "text": "나물을 데치고 양념합니다."
    }
  ],
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.8",
    "reviewCount": "120"
  }
}

3) JSON-LD(JavaScript Object Notation for Linked Data)

JSON-LD(JavaScript Object Notation for Linked Data)

- JSON 형식을 사용하여 '연결된 데이터(Linked Data)'를 표현하는 방식입니다.
- 쉽게 말해, 검색 엔진(구글 등)이 웹페이지의 내용을 단순한 텍스트가 아니라 의미 있는 정보로 이해할 수 있도록 돕는 일종의 '데이터 명세서'라고 보시면 됩니다.

1. 구조 확인

키워드	의미	비고
@context	데이터의 의미를 해석할 표준 주소	보통 https://schema.org 고정
@graph	여러 개의 개체를 하나의 배열로 묶을 때 사용	페이지 내 여러 구조화 데이터를 선언할 때 효율적
@type	데이터의 유형 (클래스)	예: Person, WebSite, LocalBusinessOrganization
@id	개체를 식별하는 고유 URI	여러 데이터를 서로 연결할 때 사용
@language	값의 언어를 지정	예: "@language": "ko"

2. 사용예시

사용예시

1. @context: Schema.org를 기준으로 데이터를 해석하겠다는 선언을 의미합니다.
- 일종의 "이 데이터는 이 규칙을 따릅니다"라는 명세를 의미합니다.

2. @graph: 여러 개의 Schema 객체를 하나의 스크립트 안에 묶어서 표현할 때 사용하는 배열을 의미합니다.

3. Organization: 조직/개인의 정보를 명세를 합니다.
- name : 조직 이름을 의미합니다.
- url : 대표 웹사이트 주소을 의미합니다.
- logo : 로고 이미지를 URL을 의미합니다
- sameAs : 이 조직과 동일한 주체임을 나타내는 외부 링크들 (GitHub, 티스토리 블로그)이며, 검색엔진이 여러 플랫폼의 정보를 하나의 엔티티로 연결하는 데 도움을 줍니다.
- contactPoint : 연락처 정보. 이메일, 연락 유형(고객 서비스), 사용 가능한 언어를 명시하는 것을 의미합니다.

4. WebPage: 현재 페이지 자체에 대한 정보를 명세를 합니다.
- name : 페이지 제목을 의미합니다.
- description : 페이지 설명 (검색결과 스니펫에 활용)을 의미합니다.
- url : 페이지 주소를 의미합니다.

[참고] 사용 예시

<script type="application/ld+json">
    {
        "@context": "https://schema.org",
        "@graph": [
            {
                "@type": "Organization",
                "name": "Ecodelab",
                "url": "https://www.ecodelab.im",
                "logo": "https://www.ecodelab.im/assets/developer.png",
                "sameAs": ["https://github.com/adjh54ir", "https://adjh54.tistory.com"],
                "contactPoint": {
                    "@type": "ContactPoint",
                    "email": "adjh54ir@gmail.com",
                    "contactType": "customer service",
                    "availableLanguage": "Korean"
                }
            },
            {
                "@type": "WebPage",
                "name": "Ecodelab - 제작 앱 소개",
                "description": "Ecodelab에서 개발한 다양한 앱들을 소개합니다",
                "url": "https://www.ecodelab.im"
            }
        ]
    }
</script>

4) 검증 방법

1. Google Search Console 활용

Google Search Console 활용

- 아래와 같이 리치 검색결과 테스트에 직접 배포한 도메인에 대해서 테스트를 진행합니다.

리치 검색결과 테스트 - Google Search Console

search.google.com

1.1. 실제 사이트에서 스키마 마크업을 적용하였습니다

실제 사이트에서 스키마 마크업을 적용하였습니다

- 배포된 사이트의 요소를 확인하면 스키마 마크업을 확인할 수 있습니다.

1.2. 스키마 마크업을 적용한 도메인 주소를 검사합니다

1.3. 아래와 같이 결과로 실제 발견이 되었음을 확인하였습니다

1.4. 해당 사이트를 확인하였을 때, 스키마 마크업은 출력이 안되고 있습니다.

해당 사이트를 확인하였을때, 스키마 마크업은 출력이 안되고 있습니다.

- 이는 즉시 적용되는 것이 아니고 일정 시간이 지나 크롤링되는 과정에 적용이 된다고 합니다.

적용한 사이트는 아래에서 확인이 가능합니다!

Ecodelab - 제작 앱 소개

Ecodelab에서 개발한 다양한 앱들을 소개합니다

www.ecodelab.im

오늘도 감사합니다.

[JS] PWA(Progressive Web App) 이해하고 활용하기 -1: 초기 구성

adjh54 — Thu, 19 Feb 2026 20:00:18 +0900

해당 글에서는 PWA에 대해 이해하고 활용하는 기본 방법에 대해 알아봅니다.

1) PWA(Progressive Web App)

PWA(Progressive Web App)

- 웹 기술로 구축되지만 네이티브 앱처럼 작동하는 애플리케이션입니다. 전통적인 웹사이트와 네이티브 앱의 장점을 결합한 형태라고 할 수 있습니다 앱처럼 아이콘을 추가하고, 푸시 알림을 보내며, 오프라인에서도 작동하게 만드는 기술입니다.

- 구글의 엔지니어 알렉스 러셀(Alex Russell)이 처음 제안한 개념으로, 별도의 스토어 설치 과정 없이 웹 브라우저를 통해 앱과 같은 사용자 경험(UX)을 제공합니다.

구분	일반 웹 사이트	PWA	네이티브 앱 (AOS/iOS)
설치 방식	URL 접속	브라우저 내 추가	앱스토어 다운로드
오프라인 사용	불가	가능 (제한적)	가능
푸시 알림	불가	가능	가능
배포/업데이트	실시간	실시간	스토어 심사 필요
개발 비용	낮음	중간	높음

2) PWA(Progressive Web App) 핵심 기술

1. Service Worker (서비스 워커)

Service Worker (서비스 워커)

- 브라우저 백그라운드에서 실행되는 스크립트 파일입니다. 네트워크 요청을 가로채거나 캐싱을 제어하여 오프라인 모드를 지원하고 푸시 알림을 처리하는 핵심 엔진 역할을 합니다.

아래와 같이 Chrome 내에서 Service workers 설치가 되면 확인이 가능합니다.

2. Web App Manifest (매니페스트 파일)

Web App Manifest (매니페스트 파일)

- 앱의 이름, 아이콘, 배경색, 시작 URL 등을 메타 데이터를 정의하는 JSON 파일입니다.
- 이 파일이 있어야 브라우저가 이를 '설치 가능한 앱'으로 인식하고 홈 화면에 아이콘을 생성할 수 있습니다.

아래와 같이 파일 내에 manifest.json 파일로 메타데이터를 정의합니다.

실제로 실행하였을 시, 아래와 같이 ‘앱에서 열기’ 버튼이 생성됩니다. 그리고 실행하였을 때, manifest.json에서 정의한 내용이 출력이 됩니다.

[참고] manifest.json 파일 내에 정의할 수 있는 정보들은 아래에서 확인이 가능합니다.

Web application manifest - Progressive web apps | MDN

developer.mozilla.org

3. HTTPS

HTTPS

- PWA는 보안을 위해 반드시 HTTPS 환경에서만 작동합니다. 서비스 워커가 네트워크 요청을 제어하기 때문에 강력한 보안 프로토콜에서만 작동합니다.
- 예외적으로 http://localhost 환경에서는 동작을 수행합니다.

3) PWA(Progressive Web App) 초기 구성

1. manifest.json 정의

manifest.json 정의

- 프로젝트의 루트 경로 위치하에 PWA의 메타 데이터를 정의하는 JSON 파일을 정의합니다.
- 또한, 아이콘을 192x192 사이즈 아이콘을 정의했기에 icon-192.png 파일을 루트경로에 위치하게 두었습니다.

{
  "name": "나의 첫 PWA 앱",
  "lang": "ko-KR",
  "description": "이 앱은 PWA 학습을 위한 샘플 애플리케이션입니다.",
  "short_name": "PWA 앱",
  "start_url": "/index.html",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#000000",
  "icons": [
    {
      "src": "icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    }
  ]
}

속성	필수/선택	설명	예시 값
name	필수	앱의 전체 이름 (설치 프롬프트, 스플래시 화면에 표시)	"나의 첫 PWA 앱"
short_name	권장	홈 화면에 표시될 짧은 이름 (12자 이하 권장)	"PWA 앱"
start_url	필수	앱 시작 시 로드될 URL	"/", "/index.html"
display	필수	앱 표시 모드	"standalone", "fullscreen", "minimal-ui", "browser"
icons	필수	앱 아이콘 배열 (최소 192x192, 512x512 권장)	[{src, sizes, type}]
background_color	권장	스플래시 화면 배경색	"#ffffff", "#000000"
theme_color	권장	브라우저 UI 색상 (주소창, 상태바)	"#000000", "#3f51b5"
description	선택	앱 설명	"할 일 관리 앱입니다"
orientation	선택	기본 화면 방향	"portrait", "landscape", "any"
scope	선택	PWA로 간주될 URL 범위	"/", "/app/"
lang	선택	기본 언어	"ko-KR", "en-US"
dir	선택	텍스트 방향	"ltr", "rtl", "auto"
categories	선택	앱 카테고리	["productivity", "education"]
screenshots	선택	앱 스크린샷 배열	[{src, sizes, type}]
shortcuts	선택	앱 바로가기 메뉴	[{name, url, icons}]
related_applications	선택	관련 네이티브 앱 정보	[{platform, url, id}]
prefer_related_applications	선택	네이티브 앱 우선 설치 여부	true, false
display_override	선택	표시 모드 우선순위 목록	["window-controls-overlay", "standalone"]

[참고] manifest.json 파일 내에 정의할 수 있는 정보들은 아래에서 확인이 가능합니다.

Web application manifest - Progressive web apps | MDN

developer.mozilla.org

2. service-worker.js

service-worker.js

- public/service-worker.js 파일 내에 위치하였고, index.html 파일 실행 시 해당 스크립트 파일을 실행시킵니다.
- 실행이 되면, ‘1. 서비스 워커 설치 (최초 1회 실행)가 실행’되어서 서비스 워커가 실행이 됩니다. 그리고 활성화되었을 때, 활성화 이벤트를 추가하였습니다.

/**
 * 1. 서비스 워커 설치 (최초 1회 실행)
 */
self.addEventListener("install", (event) => {
  console.log("서비스 워커가 설치되었습니다!");
  // 대기 중인 서비스 워커를 즉시 활성화
  self.skipWaiting();
});

/**
 * 2. 서비스 워커 활성화
 */
self.addEventListener("activate", (event) => {
  console.log("서비스 워커가 활성화되었습니다!");
});

/**
 * 3. 네트워크 요청 가로채기 (PWA 오프라인 작동의 핵심)
 */
self.addEventListener("fetch", (event) => {
  // 현재는 통과시키지만, 나중에 캐싱 로직을 여기에 넣습니다.
});

3. index.html

index.html

- 최초 실행되는 페이지 내에 서비스 워커 지원여부에 따라, 이전에 생성한 파일을 기반으로 서비스 워커 등록을 수행하도록 처리합니다.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>prototype-react-csr</title>
  </head>
  <body>
    <div id="root"></div>
    <script>
    // 브라우저가 서비스 워커를 지원하는지 확인 후 등록
    if ('serviceWorker' in navigator) {
      navigator.serviceWorker.register('/service-worker.js')
        .then(() => console.log("서비스 워커 등록 완료!"))
        .catch((err) => console.log("등록 실패:", err));
    }
  </script>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

4. Chrome 결과 확인

Chrome 결과 확인

- 관리자모드 (F12)로 실행하여 애플리케이션(Application) > Service workers로 이동하여서 확인을 하면 정상적으로 실행이 됨을 확인하였습니다.

5. 앱으로 실행하기

앱으로 실행하기

- Chrome 가장 오른쪽 점 3개 아이콘(⋮)을 누르고 > 전송, 저장, 공유 > 페이지를 앱으로 설치를 선택합니다.

설치 버튼을 누릅니다.

아래와 같이 실행이 되었습니다.

4) PWA 푸시 메시지 테스트

PWA 푸시메시지 테스트

1. 푸시 메시지 권한 요청

푸시 메시지 권한 요청

- 아래와 같이 화면 실행 시 권한을 체크하는 부분을 추가하였습니다.
- 상태를 체크하고, 권한이 없는 경우 Notification.requestPermission()를 통해서 권한 요청을 수행합니다.

 useEffect(() => {
      requestNotificationPermission();
  }, []);

  const requestNotificationPermission = async () => {
      // 브라우저가 알림을 지원하는지 확인
      if (!('Notification' in window)) {
          console.log('이 브라우저는 알림을 지원하지 않습니다.');
          return false;
      }

      // 이미 권한이 있는 경우
      if (Notification.permission === 'granted') {
          console.log('알림 권한이 이미 허용되어 있습니다.');
          return true;
      }

      // 권한 거부된 경우
      if (Notification.permission === 'denied') {
          console.log('알림 권한이 거부되었습니다.');
          return false;
      }

      // 권한 요청
      const permission = await Notification.requestPermission();

      if (permission === 'granted') {
          console.log('알림 권한이 허용되었습니다.');
          return true;
      } else {
          console.log('알림 권한이 거부되었습니다.');
          return false;
      }
  }

2. 푸시 메시지 전송

푸시 메시지 전송

- 아래의 함수에서 푸시메시지 전송 테스트를 수행합니다.
- 권한 체크를 한번 더 수행한 이후에 navigator.serviceWorker.getRegistration() 함수로 서비스 워커 등록 상태를 확인합니다.
- 서비스 워커 등록이 완료된 경우, registration.showNotification()를 통해서 전송하려는 메시지를 구성합니다.

 const sendTestPush = async () => {
  if (permission !== "granted") {
      alert("알림 권한이 허용되지 않았습니다.");
      return;
  }

  try {
      const registration = await navigator.serviceWorker.getRegistration();

      if (registration) {
          await registration.showNotification("로컬 테스트 알림", {
              body: "Service Worker를 통한 직접 알림입니다!",
              icon: "/icon-192.png",
              badge: "/icon-192.png",
              requireInteraction: true, // 자동으로 안 사라지게
              data: { url: "/" }
          });
          console.log("✅ 알림 전송 완료!");
      }
  } catch (error) {
      console.error("❌ 알림 전송 실패:", error);
  }
};

3. 전송 테스트

전송 테스트

- 구성한 버튼을 클릭하거나 Service Worker 메뉴에서 선택하여서 푸시 메시지를 전송합니다.

아래와 같이 버튼을 눌렀을 때, 푸시 메시지가 정상적으로 출력이 됨을 확인하였습니다.

아래와 같이 Service Worker 메뉴에서 푸시 메시지가 정상적으로 출력이 됨을 확인하였습니다.

[더 알아보기]

PWA를 구성한 상태에서 알람을 다른 다른 사람에게 보내려면 어떻게 해야 할까?

- 사용자 A의 PWA를 백엔드 서버를 통해서 사용자 B의 PWA로 전송하는 ‘web-push’를 사용합니다.

5) PWA 미디어 쿼리

PWA 미디어 쿼리

- 미디어 쿼리는 반응형 디자인의 핵심으로, CSS @media를 사용하여 화면 크기(모바일/데스크톱)에 맞춰 레이아웃을 조정하고 설치형 앱 모드(display-mode)에 따라 스타일을 차별화합니다.
- display-mode: standalone 등을 통해 브라우저 UI 없이 네이티브 앱처럼 보이도록 사용자 환경을 최적화할 수 있습니다.

1. 코드 확인

아래와 같은 미디어 쿼리를 적용하였습니다.

- @media (min-width: 768px)와 @media (min-width: 1200px)에 맞게 각각 적용하여서 반응형 디자인이 적용되었습니다.

/* --- 모바일 우선 기본 스타일 --- */
.container {
    min-height: 100vh;
    background-color: #f5f5f7;
    display: flex;
    flex-direction: column;
    align-items: center;
}

.header {
    width: 100%;
    background-color: #fff;
    border-bottom: 1px solid #d2d2d7;
    display: flex;
    justify-content: center;
}

.header-inner {
    width: 100%;
    max-width: 100%;
    padding: 50px 20px 15px; /* 모바일 노치 고려 */
    display: flex;
    justify-content: space-between;
    align-items: center;
}

.main {
    flex: 1;
    width: 100%;
    max-width: 100%;
    padding: 20px;
}

.card {
    background: #fff;
    border-radius: 20px;
    padding: 30px;
    box-shadow: 0 10px 30px rgba(0,0,0,0.05);
    text-align: center;
}

.word {
    font-size: 32px;
}

.action-section {
    display: flex;
    justify-content: center;
    width: 100%;
    margin-top: 20px;
}

.button {
    width: 100%;
    padding: 18px;
    border-radius: 12px;
    border: none;
    background-color: #007aff;
    color: #fff;
    font-size: 18px;
    font-weight: bold;
    cursor: pointer;
    transition: transform 0.2s, background-color 0.2s;
}

.button:active {
    transform: scale(0.98);
    background-color: #0056b3;
}

/* 모바일에서 하단 탭바 노출 */
.nav {
    display: flex;
    position: fixed;
    bottom: 0;
    width: 100%;
    height: 80px;
    background: #fff;
    border-top: 1px solid #d2d2d7;
    justify-content: space-around;
    align-items: center;
    padding-bottom: env(safe-area-inset-bottom);
}

/* --- 태블릿 이상 (768px 이상) --- */
@media (min-width: 768px) {
    .header-inner {
        max-width: 1024px;
        padding: 20px;
    }

    .main {
        max-width: 1024px;
        padding: 40px 20px;
    }

    .card {
        border-radius: 24px;
        padding: 60px;
    }

    .word {
        font-size: inherit; /* 기본 폰트 사이즈로 복원 */
    }

    .button {
        max-width: 300px;
        border-radius: 15px;
    }

    /* PC에서는 하단 탭바 숨김 */
    .nav {
        display: none;
    }
}

/* --- 대형 화면 (1200px 이상, 선택사항) --- */
@media (min-width: 1200px) {
    .header-inner,
    .main {
        max-width: 1200px;
    }

    .card {
        padding: 80px;
    }
}

3. 결과 확인

브라우저에서 아래와 같이 보이는 형태입니다.

아이폰 14 pro max와 같은 형태로 미디어 쿼리를 적용하여 반응형이 된다면, 모바일과 비슷한 형태로 출력이 됨을 확인할 수 있습니다.

5) Vite Plugin PWA 활용

Vite Plugin PWA

- Vite 스타터를 이용하는 경우에 별도의 설정 없이 PWA를 이용할 수 있도록 제공해 주는 플러그인을 의미합니다.

https://www.npmjs.com/package/vite-plugin-pwa

1. 설치

# npm
npm i vite-plugin-pwa -D

# yarn
yarn add vite-plugin-pwa -D

# pnpm
pnpm add vite-plugin-pwa -D

2. 구성 환경

구성 환경

- 내장된 vite.config.js / vite.config.ts 파일 내에 아래와 같이 vite-plugin-pwa를 import 하고 VitePWA() 내에 옵션을 명시하여서 구성을 합니다.

import  {  VitePWA  }  from  'vite-plugin-pwa'

export  default  { 
  plugins : [ 
    VitePWA ( ) 
  ] 
}

VitePWA의 VitePWAOptions 옵션들

옵션	타입	기본 값	설명
mode	'development' \\| 'production'	process.env.NODE_ENV	빌드 모드
srcDir	string	'public'	소스 디렉토리
outDir	string	'dist'	출력 디렉토리
filename	string	'sw.js'	서비스 워커 파일명
manifestFilename	string	'manifest.webmanifest'	manifest 파일명
strategies	'generateSW' \| 'injectManifest'	'generateSW'	SW 생성 전략
scope	string	Vite base와 동일	SW 등록 스코프
injectRegister	'inline' \| 'script' \| 'script-defer' \| 'auto' \| false	'auto'	SW 등록 방식
registerType	'prompt' \| 'autoUpdate'	'prompt'	SW 업데이트 방식
minify	boolean	true	manifest 압축 여부
manifest	Partial<ManifestOptions> \| false	-	manifest 객체
useCredentials	boolean	false	manifest link에 crossorigin="use-credentials" 추가
workbox	Partial<GenerateSWOptions>	-	generateSW 전략 workbox 설정
injectManifest	Partial<CustomInjectManifestOptions>	-	injectManifest 전략 workbox 설정
base	string	Vite base	PWA 전용 base 경로 override
includeAssets	string \\| string[]	-	SW precache에 추가할 public 리소스
includeManifestIcons	boolean	true	manifest 아이콘 SW precache 포함 여부
disable	boolean	false	빌드 시 SW 생성/등록 비활성화
devOptions	DevOptions	-	개발 환경 옵션
selfDestroying	boolean	false	SW 등록 해제 여부
buildBase	string	vite.base	빌드 폴더와 base 경로가 다를 때 설정
pwaAssets	PWAAssetsOptions	-	PWA 에셋 자동 생성/주입 (experimental)
showMaximumFileSizeToCacheInBytesWarning	boolean	false	캐시 파일 크기 초과 경고를 에러 대신 warning으로 처리

3. 사용 예시

사용 예시

- 아래와 같이 vite.cofnig.ts 파일 내에 manifest.json 파일을 불러와서 import 하도록 구성하였습니다. 또한, registerType: 'autoUpdate'를 통해서 서비스 워커 업데이트 방식을 정의하는 옵션을 지정하였습니다.
- autoUpdate는 새 버전 감지 시 사용자 개입 없이 자동으로 서비스 워커 업데이트되며, 다음 페이지 reload 시 새 버전 적용되는 옵션입니다.

registerType 속성

옵션	동작 사용	시기
prompt (기본값)	새 버전 감지 시 대기, useRegisterSW 훅으로 직접 UI 구현 필요	사용자에게 업데이트 시점을 알리고 싶을 때
autoUpdate	새 버전 감지 시 자동 업데이트 + 모든 탭 자동 새로고침	사용자 개입 없이 항상 최신 버전 유지할 때

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { VitePWA } from 'vite-plugin-pwa';
import manifestJson from './public/manifest.json';
import type { ManifestOptions } from 'vite-plugin-pwa';

const manifest = manifestJson as ManifestOptions;

export default defineConfig({
	plugins: [
		react(),
		VitePWA({
			registerType: 'autoUpdate',
			manifest,
		}),
	],
});

아래와 같이 manifest.json 파일을 아래와 같이 구성을 하였습니다.

{
	"name": "React Template",
	"short_name": "React Template",
	"description": "PWA 테스트",
	"id": "/",
	"start_url": "/",
	"display": "standalone",
	"background_color": "#ffffff",
	"theme_color": "#007bff",
	"orientation": "portrait",
	"icons": [
		{
			"src": "/assets/icon-192.png",
			"sizes": "192x192",
			"type": "image/png",
			"purpose": "any"
		},
		{
			"src": "/assets/icon-512.png",
			"sizes": "512x512",
			"type": "image/png",
			"purpose": "any"
		},
		{
			"src": "/assets/icon-512.png",
			"sizes": "512x512",
			"type": "image/png",
			"purpose": "maskable"
		}
	]
}

오늘도 감사합니다.

[제작 앱 소개] 촌수 계산기 Plus+

adjh54 — Wed, 11 Feb 2026 20:00:13 +0900

해당 글에서는 Contributor9 개발자가 만든 개발 앱에 대해 홍보를 위한 목적으로 작성한 글입니다.

1) 개발자는 왜 이 앱을 만들었을까?

개발자는 왜 이 앱을 만들었을까?

- 한국의 호칭과 촌수 체계는 상당히 복잡한것 같습니다. 일상에서 자주 사용하지 않다 보니 정확히 기억하기 어렵고, 특히 기준이 되는 사람의 성별에 따라 호칭이 달라지기 때문에 그 복잡성은 더욱 커지는것 같습니다. 그렇지만, 생각해보면 이렇게 헷갈리고 어려운 호칭들은 오랜 기간 동안 변하지 않고 그대로 사용하는 것들입니다.

- 그렇기에 나는 똑같은 고민을 반복해서 하는 것이 아닐까라는 생각이 들었습니다. 이러한, 복잡하고 어려운 호칭과 촌수를 고민 없이 필요에 따라서 앱에서 사전과 같이 꺼내 쓰고 쉽게 바로바로 찾을 수 있는 앱을 만들어보는 게 어떨까 라는 생각을 했던 것 같습니다.

- 그리고 더 나아가서는 관심이 생긴다면 퀴즈로 연습해보면서 쉽게 익혀보는 것이 어떨까라는 생각이 들었습니다.

그래서 이 앱을 개발하게 된 것 같습니다.

- 촌수 계산기 Plus+ 앱에서는 우선, ’내 기준’으로 성별을 선택하고 나와의 관계를 순차적으로 따라가는 구조로 구성이 되어있습니다.
- 이러한 관계는 ‘브레드스크럼(Breadcrumb)’ 형태로 순차적으로 따라가서 사용자 입장에서는 좀 더 이해하기 쉽게 도움을 줍니다. 그리고 ‘x 아이콘’을 통해서 이전 잘못 선택한 관계는 즉시 되돌아갈 수 있습니다.

- 예를 들어서 나(남자) 기준으로 최초 선택을 합니다.
나(남자) > 딸 > 아들 > 딸 > 딸을 선택하면 ‘외고손녀’ 깊은 관계까지 탐색하여서 확인 할 수 있습니다.
또한, 나와의 촌수, 항렬도 확인하고 복사/공유 기능을 제공합니다

또한, 아래와 같이 필요에 따라서 필터를 두며, 호칭을 쉽게 검색하고 확인할 수 있습니다.

최종적으로, 아래와 같이 내 실력을 테스트해보기 위해서 퀴즈도 할 수 있습니다.

2) 앱 소개- 촌수 계산기 Plus+

앱 소개- 촌수 계산기 Plus+

- 촌수 계산기 Plus+는 단순한 '촌수 계산기'를 넘어, 가족 관계를 가장 정확하고 직관적으로 이해할 수 있도록 돕는 종합 앱입니다.
- 부계·모계·인척 관계까지 촌수를 자동으로 계산하고, 다양한 친족 호칭을 빠르게 검색해 즉시 확인할 수 있습니다. 또한, 재미있고 유익한 ‘가족 관계 퀴즈’를 통해 촌수 지식을 자연스럽게 익힐 수 있어 학습과 재미를 모두 누릴 수 있습니다.

1. 홈
- 앱의 소개 및 핵심 개념을 한눈에 이해할 수 있도록 구성된 정보 중심 메인 화면입니다.
- 스크롤 가능한 카드 형태로 촌수·호칭·계촌법·친족·인척·친인척·항렬 개념을 정리해 주며, 각 설명은 복사·공유 기능을 포함해 사용자가 쉽게 활용할 수 있도록 구성되어 있습니다

2. 계산
- 가족 관계를 단계별로 선택하면, 자동으로 촌수·항렬·호칭·설명까지 한눈에 정리해 보여주는 핵심 기능입니다
- 나의 성별을 선택하면 더 정확한 관계 계산 시작
- 부모·조부모·형제·인척 등 원하는 관계를 버튼만 눌러 탐색
- 선택한 경로를 기반으로 촌수, 항렬 방향(윗항렬/아랫항렬) 자동 계산
- 정확한 호칭, 간단 설명, 특별 호칭까지 즉시 확인
- 계산된 결과는 복사·공유 버튼으로 간편하게 전달
- 가족 관계가 복잡해 헷갈릴 때, 이 화면에서 단계별로 따라가기만 하면 누구든 쉽게 정확한 촌수를 확인할 수 있습니다.

3. 리스트
- 가족 관계가 헷갈리는 순간, 이 화면에서는 원하는 호칭을 빠르게 검색하고 촌수·항렬·인척 여부까지 정확하게 확인할 수 있습니다.
- 이름, 기본 호칭, 별칭(특별 호칭) 등 어떤 방식으로 입력해도 즉시 검색되며, 촌수(1~6촌), 성별 기준(남자/여자), 관계 구분(혈족/인척) 필터를 활용해 더욱 세밀한 조건으로 찾을 수 있습니다.
- 검색 결과는 가나다 순과 촌수 순으로 정돈되어 한눈에 보기 편하며, 항목을 누르면 자세한 설명, 촌수, 항렬, 인척 여부, 관계 흐름까지 팝업으로 확인할 수 있습니다. 또한, 스크롤이 길어질 때를 대비해 한 번의 탭으로 최상단으로 이동하는 버튼도 준비되어 있어 편리하게 탐색할 수 있습니다.
- 필요한 친족 호칭이 떠오르지 않을 때에도, 이 화면에서 검색만 하면 남자·여자 기준에 따라 정확한 관계 정보를 즉시 확인할 수 있습니다.

4. 퀴즈 모드
- 촌수·호칭개념을 재미있게 학습하도록 구성된 퀴즈 모드의 시작 화면입니다.
- 먼저 성별(남자/여자)를 선택하면, 해당 성별 기준으로 호칭·촌수 판단 기준을 정확하게 적용하여 문제를 구성합니다.
- 상단에는 지금까지 풀었던 퀴즈의 전체 통계가 한눈에 나타나며, 맞춘 문제 수, 누적 점수, 최대 콤보, 총 참여 횟수를 직관적으로 확인할 수 있어 학습 동기 부여에 도움이 됩니다.
- 중앙 캐릭터와 함께 퀴즈 설명이 표시되며, 제공되는 설명을 바탕으로 어떤 호칭·촌수인지 맞추는 방식의 문제임을 안내합니다.
- 총 준비된 문제 수가 실시간으로 표시되어, 얼마나 많은 문제를 풀 수 있는지도 미리 확인할 수 있습니다.
- 성별 선택 후 [퀴즈 시작] 버튼을 누르면, 선택된 기준(남자 또는 여자)에 맞춰 랜덤 문제풀이가 시작되며, 문제별로 선택식 보기, 정답 결과, 애니메이션 효과, 콤보 시스템 등이 적용됩니다.
- 촌수와 호칭이 헷갈릴 때, 이 퀴즈 모드를 통해 자연스럽게 규칙을 익히고 실력을 테스트할 수 있습니다.

5. 퀴즈
- 호칭 찾기 퀴즈로 문제에 대한 답을 4지선다형으로 푸는 퀴즈 화면입니다.
- 성별 기준을 선택해 퀴즈를 시작하면, 현재 풀고 있는 문제 번호·누적 접수·콤보 수가 상단 카드에 표시됩니다. 이를 통해 진행 상황을 직관적으로 확인할 수 있습니다.
- 문제 본문은 실제 가족 관계 설명을 기반으로 구성되어 있으며, "어떤 관계인지 이해 → 맞는 호칭을 선택"하는 방식의 학습 중심 문제로 설계되어 있습니다.
- 보기 선택 시 즉시 정답 여부가 판단되며, 다음 문제로 넘어갈 수 있도록 깔끔한 흐름을 제공합니다.
- 화면 하단의 [퀴즈 종료] 버튼을 통해 언제든 종료할 수 있으며 결과 화면으로 이동할 수 있습니다.

⸻

5.1. 오답 결과 모달
- 정답을 잘못 선택했을 경우, 오답 결과 모달이 출력되어, 즉시 피드백을 제공합니다.
- 상단에는 감정 표현 캐릭터와 함께 "오답입니다" 메시지가 표시되며, 정답이 무엇이었는지 명확히 알려줍니다.
- 정확한 호칭, 공식 명칭, 해당 호칭에 대한 설명문, 촌수, 관계 종류(혈족/인척)
- 사용자는 단순히 답만 확인하는 것이 아니라, 틀린 이유를 이해하고 정확한 관계를 학습할 수 있게 구성되어 있습니다.
- 하단의 [다음 퀴즈] 버튼을 누르면 다음 문제로 연결되며, 자연스러운 학습 흐름을 제공합니다.

5.2. 정답 결과 모달
- 정답을 맞췄을 경우, 정답 결과 모달이 출력되어 즉시 피드백으로 축하 메시지를 제공합니다.
- 정답 호칭과 공식 명칭, 해당 호칭에 대한 설명문, 다른 호칭 태그(동의 호칭·확장 표기 등), 촌수 및 관계 종류(혈족/인척)
- 특히 “다른 호칭” 항목은 다양한 전통 호칭을 이해하는 데 도움이 되며, 퀴즈 중 자연스럽게 학습 폭을 넓힐 수 있도록 구성되어 있습니다.
- 아래쪽에 [다음 퀴즈] 버튼이 있어 즉시 다음 문제로 이동할 수 있으며, 연속 정답 시 콤보 점수 누적도 이뤄져 성취감을 높여줍니다
- 이 과정을 반복하며 촌수·호칭·관계 이해도를 점점 높일 수 있는 구조로 되어 있어, 단순한 퀴즈가 아닌 학습형 경험을 제공하도록 설계되어 있습니다.

6. 설정

- 설정 화면은 앱 사용을 위한 기본 정보 관리부터 문의, 피드백, 정책 확인까지 한 곳에서 모두 할 수 있도록 구성된 공간입니다. 앱을 사용하면서 필요한 설정을 쉽게 변경할 수 있도록 직관적으로 설계되어 있습니다.
- 화면 상단에는 앱이 마음에 들었을 때 가족이나 친구에게 추천할 수 있는 앱 공유 영역이 배치되어 있으며, 공유하기 버튼을 통해 간편하게 앱을 전달할 수 있습니다.
- 그 아래에는 퀴즈 데이터를 관리할 수 있는 초기화 섹션이 제공됩니다. 여기에서 퀴즈 문제를 처음 상태로 되돌리거나, 지금까지 기록한 모든 기분 데이터를 한 번에 삭제할 수 있습니다.
- 문의 및 피드백 영역에서는 앱 사용 중 궁금한 점이나 개선 의견을 전달할 수 있으며, 앱 리뷰 남기기 버튼을 통해 스토어 리뷰 페이지로 이동해 의견을 공유할 수도 있습니다. 또한 문의하기 버튼을 통해 개발자에게 직접 질문을 보낼 수 있는 통로가 마련되어 있고, 제작자 소개 메뉴에서는 앱 개발자와 관련된 정보를 확인할 수 있습니다.
- ‘제작자 앱 더보기’ 메뉴에서는 함께 제작된 다른 앱들도 확인할 수 있어 더욱 다양한 콘텐츠를 즐길 수 있습니다.
- 정책 및 라이선스 섹션에서는 개인정보 처리방침 및 이용약관을 확인할 수 있으며, 앱에서 사용된 외부 라이브러리 정보를 모아둔 오픈소스 라이브러리 목록도 제공됩니다. 화면 하단에는 현재 앱 버전 정보가 표시되어 있어 업데이트 여부를 쉽게 확인할 수 있습니다.
- 마지막으로, 화면 맨 아래에는 제작자가 만든 다른 퀴즈 앱들이 카드 형태로 소개되어 있어 관심 있는 앱을 바로 설치하거나 둘러볼 수 있습니다.

3) 다운로드

1. Google PlayStore

https://play.google.com/store/apps/details?id=com.tha.choncalcquiz

촌수 계산기 Plus+ - Google Play 앱

헷갈리는 가족 관계를 단계별 선택·검색·퀴즈로 바로 이해하고, 촌수·항렬·호칭을 정확하게 알려주는 가족 관계 학습 앱입니다.

play.google.com

2. AppStore

https://apps.apple.com/kr/app/id6755925570

촌수 계산기 Plus+ 앱 - App Store

App Store에서 EcodeLab의 촌수 계산기 Plus+ 앱을 다운로드하십시오. 스크린샷, 평가 및 리뷰, 사용자 팁, 촌수 계산기 Plus+ 앱과 비슷한 다른 게임들도 만나볼 수 있습니다.

apps.apple.com

⬇️ 개발자의 다양한 앱을 보고 싶으시면 아래의 링크를 확인해주세요 ⬇️

Ecodelab - 제작 앱 소개

Ecodelab에서 개발한 다양한 앱들을 소개합니다

www.ecodelab.im

오늘도 감사합니다.

[Java] GA4(Google Analytics) 이해하고 활용하기 -2: 수집된 데이터 조회 환경 설정 및 활용 방법

adjh54 — Fri, 6 Feb 2026 20:10:53 +0900

해당 글에서는 GA에서 수집된 데이터를 API를 통해서 가져와서 화면상에 출력하는 과정을 포함한 글입니다.

[참고] React 환경에서 수집한 데이터에 대해서 Spring Boot 환경에서 이를 조회하는 방법에 대해 알아봅니다.

[React] GA4(Google Analytics) 이해하고 활용하기-1 : 프로젝트 설정 및 데이터 수집 방법

해당 글에서는 React 환경에서 GA4를 이해하고 설정하여 데이터를 수집하는 방법에 대해 알아봅니다. 1) Google Analytics(GA4) Google Analytics(GA4)- Google 애널리틱스 4는 웹사이트 및 앱에서 트래픽과 참

adjh54.tistory.com

1) Google Analytics(GA4)

Google Analytics(GA4)

- Google 애널리틱스 4는 웹사이트 및 앱에서 트래픽과 참여도를 측정할 수 있는 분석 서비스입니다.
- 웹사이트와 웹, 앱의 데이터를 수집하여 비즈니스 통찰력을 제공하는 구글의 차세대 분석 플랫폼입니다.

Google 애널리틱스 4 소개 | Google Analytics | Google for Developers

Google 애널리틱스용 MCP 서버를 사용해 보세요. GitHub에서 설치하고 공지사항에서 자세한 내용을 확인하세요. 의견 보내기 Google 애널리틱스 4 소개 컬렉션을 사용해 정리하기 내 환경설정을 기준

developers.google.com

2) 설정 과정

설정 과정

- 아래의 설정 과정을 통해서 GA(Google Analytics)에서 수집된 데이터를 API에서 조회하는 과정을 설정합니다.

플랫폼	분류	설명
Google Cloud Console	프로젝트 생성	Google Analytics(GA4)로 수집된 데이터를 불러오는 API 측을 만들기 위해서 프로젝트를 생성합니다.
Google Cloud Console	사용자 계정 및 키 생성	Google Analytics(GA4)에 API를 호출하여서 데이터를 가져올 사용자 및 키를 생성합니다.
GA(Google Analytics)	사용자 추가	위에 프로젝트에서 API에 접근하려는 사용자를 만들었고, GA(Google Analytics)내에 이를 추가하는 과정입니다.
GA4 Query Explorer	데이터 연동 테스트	GA로 API를 호출하여서 값 조회를 위한 테스트를 합니다.

3) Google Cloud Console: 프로젝트 생성

Google Cloud Console: 프로젝트 생성

- Google Analytics(GA4)로 수집된 데이터를 불러오는 API 측을 만들기 위해서 프로젝트를 생성합니다.

1. Google Cloud에 접속하여 ‘콘솔’ 버튼을 누릅니다.

https://cloud.google.com/?hl=ko

클라우드 컴퓨팅 서비스 | Google Cloud

데이터 관리, 하이브리드 및 멀티 클라우드, AI와 머신러닝 등 Google의 클라우드 컴퓨팅 서비스로 비즈니스 당면 과제를 해결하세요.

cloud.google.com

2. 프로젝트 버튼을 누릅니다

3. ‘새 프로젝트’ 버튼을 누릅니다.

4. 새 프로젝트를 만듭니다.

5. API 및 서비스를 선택합니다

4) Google Cloud Console: 사용자 계정 및 키 생성

Google Cloud Console: 사용자 계정 및 키 생성

- Google Analytics(GA4)에 API를 호출하여서 데이터를 가져올 사용자 및 키를 생성합니다.

1. IAM 관리자 > 서비스 계정을 선택합니다

2. ‘서비스 계정 만들기’ 버튼을 누릅니다

3. 서비스 계정 이름을 입력하고, 모두 다음으로 계속합니다

4. 아래와 같이 생성되었고, 이메일을 누릅니다

5. 키 탭 > 키 추가 > 새 키 만들기 버튼을 누릅니다

6. ‘JSON’ 키 유형을 선택하고 만들기를 누르면 JSON 파일이 다운로드하여집니다

5) GA(Google Analytics): 사용자 추가

Google Analytics: 사용자 추가

- 위에 프로젝트에서 API에 접근하려는 사용자를 만들었고, GA(Google Analytics) 내에 이를 추가하는 과정입니다.

1. 구글 애널리틱스 사이트를 접속하고, 수집하려는 프로젝트로 접근합니다

Google Analytics | Google for Developers

Google 애널리틱스를 사용하면 디지털 전략을 세부적으로 조정하고, 캠페인을 최적화하며, 온라인 인지도를 한 단계 업그레이드할 수 있습니다.

developers.google.com

2. 설정 > 계정설정 > 계정 > 계정 액세스 관리를 선택합니다

3. + 버튼 > 사용자 추가를 선택합니다

4. Google Cloud에 추가한 사용자 이메일을 적고 ‘추가’ 버튼을 누릅니다.

Google Cloud에 추가한 사용자 이메일을 적고 ‘추가’버튼을 누릅니다.

- 추가로 역할을 ‘뷰어’로 설정해서 데이터만 조회해 오는 역할을 수행하도록 합니다.

6) GA4 Query Explorer: 데이터 연동 테스트

GA4 Query Explorer: 데이터 연동 테스트

- GA로 API를 호출하여서 값 조회를 위한 테스트를 합니다.

1. 사이트에 접속하여 사람 아이콘을 눌러서 로그인을 수행합니다.

https://ga-dev-tools.google/ga4/

About This Site Google Analytics Demos & Tools is a resource for users and developers to discover what's possible with the Google Analytics Platform. Learn how to implement GA and applications that can be built to take advantage of the flexibility and powe

ga-dev-tools.google

2. Query Explorer 탭을 선택합니다

3. 구글 애널리틱스에서 수집되는 속성 및 Set Parameters를 선택합니다

4. MAKE REQUEST를 선택합니다

5. 아래와 같이 결과를 확인하였습니다.

7) Spring Boot 환경 설정

1. 의존성 추가

의존성 추가

- 의존성으로 Google Analytics Data 라이브러리를 이용하여서 클라이언트를 생성하고 통신을 하기 위함으로 이용합니다.

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-webmvc'

		// GA4 Data API 추가
    implementation 'com.google.analytics:google-analytics-data:0.94.0'

    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-webmvc-test'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

2. 위에서 발급받은 JSON 키를 기반으로 resource 내에 ga-key.json 파일로 추가하였습니다

3. application.yml

application.properties

- 아래와 같이 ga.property-id, ga.credentials를 추가하였습니다.

spring:
  application:
    name: template-spring-boot4

ga:
  property-id: XXXXXXXX
  credentials: classpath:ga-key.json

[참고] ga.propertie-id로 명시한 코드는 구글 애널리틱스 내에서 아래의 속성을 확인할 수 있습니다.

- 아래와 같이 계정을 선택 하면 그 아래에 각각 프로젝트가 나오는데 프로젝트의 값을 넣으면 됩니다.

4. GaConfig

GaConfig

- Google Analytics 분석 데이터에 접근할 수 있도록 인증과정 및 클라이언트 구성하는 설정 파일이며 클라이언트를 생성합니다.

package com.adjh.templatespringboot4.config;

import com.google.analytics.data.v1beta.BetaAnalyticsDataClient;
import com.google.analytics.data.v1beta.BetaAnalyticsDataSettings;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;

import java.io.IOException;

/**
 * Google Analytics 분석 데이터에 접근할 수 있도록 인증과정 및 클라이언트 구성
 *
 * @author : leejonghoon
 * @fileName : GaConfig
 * @since : 26. 2. 2.
 */
@Configuration
public class GaConfig {

    /**
     *
     * @return
     * @throws IOException
     */
    @Bean
    public BetaAnalyticsDataClient gaClient() throws IOException {

        // 1. ga-key.json 인증키를 로드합니다.
        GoogleCredentials credentials = GoogleCredentials.fromStream(new ClassPathResource("ga-key.json").getInputStream());

        // 2. 인증키를 기반으로 GA Client를 생성합니다,
        return BetaAnalyticsDataClient.create(
                BetaAnalyticsDataSettings.newBuilder()
                        .setCredentialsProvider(FixedCredentialsProvider.create(credentials))
                        .build()
        );
    }
}

[참고] API Document

Class BetaAnalyticsDataClient (0.94.0) | Java client libraries | Google Cloud Documentation

Send feedback Class BetaAnalyticsDataClient (0.94.0) Stay organized with collections Save and categorize content based on your preferences. Version latestkeyboard_arrow_down Beta This library is covered by the Pre-GA Offerings Terms of the Terms of Service

docs.cloud.google.com

5. DTO 구성

DTO 구성

- 해당 예시에서는 일일 활성화 사용자 조회(activeUser), 유입 및 체류시간 정보를 조회하는 정보를 가져옵니다.
- 그렇기에 응답 값으로 지정하여서 이로 반환받습니다.

package com.adjh.templatespringboot4.dto;

import lombok.Builder;
import lombok.Getter;

/**
 * 일일 활성화 사용자 + 유입 및 체류시간에 대한 응답값
 *
 * @author : leejonghoon
 * @fileName : GaResponseDto
 * @since : 26. 2. 2.
 */
@Getter
@Builder
public class GaResponseDto {

    private String date;
    private long activeUsers;

    private long totalUsers;
    private long sessions;
    private long pageViews;
    private double avgSessionDuration;
    private double engagementRate;
}

6. GaService

GaService

- 클라이언트를 통해서 직접적으로 GA와 통신을 수행하여서 데이터를 조회합니다.

1. DateRange 객체를 통해 조회 기간을 설정합니다. (시작일, 종료일 구성)
2. 실행 요청 정보 Budiler로 구성합니다: 조회 범위(Range), 측정 기준(Metric), 데이터 분류 기준(Dimension)
3. 요청 정보를 기반으로 클라이언트로 실행
4. DTO 변환 및 결과값 반환 (Builder 사용)

package com.adjh.templatespringboot4.service;

import com.adjh.templatespringboot4.dto.GaResponseDto;
import com.google.analytics.data.v1beta.*;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;

import java.util.List;

/**
 * GA Client를 기반으로 데이터를 조회해오는 서비스
 *
 * @author : leejonghoon
 * @fileName : GaServiceComponent
 * @since : 26. 2. 2.
 */
@Service
public class GaService {

    @Value("${ga.property-id}")
    private String propertyId;

    private final BetaAnalyticsDataClient client;

    public GaService(BetaAnalyticsDataClient client) {
        this.client = client;
    }

    /**
     * 구성한 클라이언트를 기반으로 유입 및 체류시간 조회 Service
     *
     * @return List<GaResponseDto>
     */
    public List<GaResponseDto> trafficAndEngagement() {

        // 1. 조회 기간을 설정합니다. (시작일, 종료일 구성)
        DateRange dateRange = DateRange.newBuilder()
                .setStartDate("7daysAgo")
                .setEndDate("today")
                .build();

        // 2. 실행 요청 정보를 구성합니다: 조회 범위(Range), 측정 기준(Metric), 데이터 분류 기준(Dimension)
        RunReportRequest request = RunReportRequest.newBuilder()
                .setProperty("properties/" + propertyId)
                // 2.1. 조회 범위(Range) 지정
                .addDateRanges(dateRange)

                // 2.2. 측정 기준(Metric) 지정
                .addDimensions(Dimension.newBuilder().setName("date"))

                // 2.3. 데이터 분류 기준 지정(Dimension)
                // 1. 유입 및 사용자 관련 지표 (Acquisition & Users)
                .addMetrics(Metric.newBuilder().setName("activeUsers"))             // 활성 사용자 수
                .addMetrics(Metric.newBuilder().setName("totalUsers"))              // 전체 사용자 수
                .addMetrics(Metric.newBuilder().setName("sessions"))                // 세션 수
                .addMetrics(Metric.newBuilder().setName("screenPageViews"))         // 페이지 조회수

                // 2. 참여 및 체류 관련 지표 (Engagement)
                .addMetrics(Metric.newBuilder().setName("averageSessionDuration"))  // 평균 세션 시간
                .addMetrics(Metric.newBuilder().setName("engagementRate"))          // 참여율
                .addMetrics(Metric.newBuilder().setName("bounceRate"))              // 이탈률
                .addMetrics(Metric.newBuilder().setName("eventCount"))              // 이벤트 수
                .build();

        // 3. 요청 정보를 기반으로 클라이언트로 실행
        RunReportResponse response = client.runReport(request);

        // 4. DTO 변환 및 결과값 반환 (Builder 사용)
        return response.getRowsList().stream()
                .map(row -> GaResponseDto.builder()
                        .date(row.getDimensionValues(0).getValue())
                        .activeUsers(Long.parseLong(row.getMetricValues(0).getValue()))
                        .totalUsers(Long.parseLong(row.getMetricValues(1).getValue()))
                        .sessions(Long.parseLong(row.getMetricValues(2).getValue()))
                        .pageViews(Long.parseLong(row.getMetricValues(3).getValue()))
                        .avgSessionDuration(Double.parseDouble(row.getMetricValues(4).getValue()))
                        .engagementRate(Double.parseDouble(row.getMetricValues(5).getValue()))
                        .bounceRate(Double.parseDouble(row.getMetricValues(6).getValue()))
                        .eventCount(Long.parseLong(row.getMetricValues(7).getValue()))
                        .build())
                .toList();
    }
}

[참고] 반환 값을 하단의 속성을 확인할 수 있습니다.

API 측정기준 및 측정항목 | Google Analytics | Google for Developers

의견 보내기 API 측정기준 및 측정항목 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요. Data API Core Reporting 쿼리에서 사용할 수 있는 측정기준과 측정항목입니

developers.google.com

7. GaController

GaController
-
GA 서비스를 호출하여 API 엔드포인트로 제공을 합니다.

package com.adjh.templatespringboot4.controller;

import com.adjh.templatespringboot4.dto.GaResponseDto;
import com.adjh.templatespringboot4.service.GaService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

/**
 * GA 데이터 API 호출
 *
 * @author : leejonghoon
 * @fileName : GaController
 * @since : 26. 2. 2.
 */
@RestController
@RequestMapping("/api/ga")
public class GaController {

    private final GaService gaService;

    public GaController(GaService gaService) {
        this.gaService = gaService;
    }

    @GetMapping("/total-users")
    public List<GaResponseDto> getTrafficUser() {
        return gaService.trafficAndEngagement();
    }
}

8) 결과 확인

결과 확인

- IntelliJ HTTP Client를 기반으로 호출하여 해당 값들을 조회하였습니다.
- 아래와 같이 결과를 확인하였습니다.

[참고] IntelliJ HTTP Client

[IntelliJ] HTTP Client 사용하기 : Postman 대체하기

adjh54.tistory.com

오늘도 감사합니다.

[React] GA4(Google Analytics) 이해하고 활용하기-1 : 프로젝트 설정 및 데이터 수집 방법

adjh54 — Fri, 6 Feb 2026 20:05:56 +0900

해당 글에서는 React 환경에서 GA4를 이해하고 설정하여 데이터를 수집하는 방법에 대해 알아봅니다.

1) Google Analytics(GA4)

Google Analytics(GA4)

- Google 애널리틱스 4는 웹사이트 및 앱에서 트래픽과 참여도를 측정할 수 있는 분석 서비스입니다.
- 웹사이트와 웹, 앱의 데이터를 수집하여 비즈니스 통찰력을 제공하는 구글의 차세대 분석 플랫폼입니다.

Google 애널리틱스 4 소개 | Google Analytics | Google for Developers

developers.google.com

1. UA(Universal Analytics)와 GA(Google Analytics)

UA(Universal Analytics)와 GA(Google Analytics)

1. UA(Universal Analytics)
- 세션(Session)'과 '페이지뷰(Pageview) 중심이었습니다. 사용자가 머문 시간이나 본 페이지 수를 중요한 데이터로 이용하였습니다.

2. GA(Google Analytics)
- 모든 사용자 상호작용을 '이벤트(Event)'로 처리합니다.
- 버튼 클릭, 스크롤, 동영상 재생, 페이지 조회 등 모든 행위가 각각의 이벤트가 되며, 여기에 '매개변수(Parameter)'를 붙여 상세 정보를 수집합니다.

구분	UA (Universal Analytics)	GA4 (Google Analytics 4)
측정 기준	세션(Session), 히트(Hit) 기반	이벤트(Event), 파라미터 기반
플랫폼	주로 웹(Web) 중심	웹(Web) + 앱(App) 통합 측정
쿠키/개인정보	쿠키 의존도가 높음	머신러닝을 활용한 데이터 보정, IP 익명화
ID 체계	속성 ID (UA-000000-0)	측정 ID (G-XXXXXXX)
보고서 구조	표준 보고서(획득, 행동, 전환 등) 위주	탐색(Exploration) 중심의 맞춤형 보고서
데이터 보관	거의 무제한 (설정에 따라 다름)	기본 2개월, 최대 14개월

2. GA 수집 데이터

2.1. 이벤트

이벤트

- 웹 사이트 또는 앱과의 기본적인 상호작용을 통해서 트리거가 됩니다.
- 웹의 경우는 구글 태그(gtag.js)를 통해 자동으로, 또는 '향상된 측정' 설정을 통해 수집되는 데이터입니다.
- 앱의 경우는 Firebase용 구글 애널리틱스 SDK를 통해 데이터를 수집하고 이를 GA4로 전송을 합니다.

분류	이벤트 명	수집 시점	주요 수집 데이터
웹/앱 자동 수집	first_visit	웹/앱을 통틀어 사용자가 서비스를 처음 방문했을 때	소스, 매체, 캠페인
	session_start	사용자가 방문하여 새로운 세션이 시작될 때	세션 ID, 세션 번호
	user_engagement	사용자가 콘텐츠를 활발히 이용 중일 때 (주기적 수집)	참여 시간(밀리초)

웹 자동 수집	page_view	새로운 페이지가 로드되거나 브라우저 기록이 변경될 때	페이지 URL, 페이지 제목

앱 자동 수집	screen_view	앱 내에서 화면 전환이 일어날 때	화면 이름, 클래스 이름
	first_open	앱 설치 후 사용자가 처음으로 실행했을 때	앱 버전, 기기 모델, OS 정보
	app_exception	앱이 비정상 종료(Crash)되거나 예외가 발생할 때	오류 메시지, 치명적 여부(fatal)
	in_app_purchase	인앱 결제(App Store, Play Store)가 완료되었을 때	상품 ID, 가격, 통화, 수량
	app_update	사용자가 앱을 새 버전으로 업데이트하고 실행할 때	이전 앱 버전 정보
	notification_receive	백그라운드 상태에서 푸시 알림을 수신했을 때	알림 제목, 본문, 캠페인 정보
	notification_open	사용자가 푸시 알림을 클릭하여 앱을 열었을 때	클릭된 알림의 캠페인 정보
	app_remove	(Android 전용) 사용자가 앱을 삭제할 때	삭제된 앱 패키지 정보

향상된 측정(웹)	scroll	사용자가 페이지의 90% 지점까지 스크롤했을 때	스크롤 깊이
	click	현재 도메인이 아닌 외부 링크를 클릭할 때	외부 URL, 링크 ID, 링크 클래스
	view_search_results	사이트 내 검색 결과 페이지가 로드될 때	검색어 (q, s, search_term 등)
	video_start / progress	내장된 YouTube 영상이 재생되거나 특정 구간(25, 50% 등) 통과 시	영상 제목, 영상 URL, 진행률
	file_download	문서, 실행 파일, 압축 파일 링크를 클릭했을 때	파일 이름, 확장자, 파일 URL

자동 수집 이벤트 - 애널리틱스 고객센터

도움이 되었나요? 어떻게 하면 개선할 수 있을까요?

support.google.com

2.2. 속성

속성

- 자동 수집되는 속성과 사용자가 직접 정의하여 부여하는 속성이 있습니다.

속성명	데이터 내용	분석 활용도
Device 정보	기기 모델, 브랜드, OS 버전, 브라우저	기기별 최적화 및 UI/UX 개선 근거
Geo 정보	국가, 지역, 도시 (IP 기반)	지역별 타겟 마케팅 및 광고 집행
App 정보	앱 버전, 스토어 ID, 패키지 이름	버전별 버그 추적 및 업데이트 유도
Language	시스템 설정 언어	다국어 지원 우선순위 결정

2) Google Analytics(GA4) 환경 설정

1. 공식사이트에 접속합니다.

Google Analytics | Google for Developers

Google 애널리틱스를 사용하면 디지털 전략을 세부적으로 조정하고, 캠페인을 최적화하며, 온라인 인지도를 한 단계 업그레이드할 수 있습니다.

developers.google.com

2. 아래와 같이 속성을 만듭니다

아래와 같이 속성을 만듭니다

- 수집하려는 프로젝트에 대해서 생성합니다.

3. 업종 및 카테고리를 선택합니다

4. 비즈니스 목표를 선택합니다

5. 데이터 수집을 웹으로 선택합니다

6. 웹 사이트 URL을 입력하고, 스트림 이름을 입력합니다

웹 사이트 URL을 입력하고, 스트림 이름을 입력합니다

- 로컬에서 테스트를 하는 경우 웹 사이트 URL의 경우 임의로 입력을 해도 됩니다!

7. 아래와 같이 생성이 되었습니다.

8. 태그를 확인합니다

태그를 확인합니다

- 아래와 같이 GA에서 제공해 주는 태그를 확인할 수 있습니다.

3) 프로젝트 설정

1. GA 라이브러리를 설치합니다

npm i react-ga4

# or

yarn add react-ga4

https://www.npmjs.com/package/react-ga4

2. 로컬에서 측정을 위한 체커를 구성합니다.

로컬에서 측정을 위한 체커를 구성합니다.

- GA_ID는 위에서 발급한 아이디를 입력합니다.
- 해당 함수에서는 추가로 ‘페이지에 머문 시간(체류시간)’을 측정하기 위해 page_stay라는 이벤트를 추가하는 과정입니다.
- 기본적으로 제공하는 이벤트 외에 새로운 함수를 이용합니다.보조적으로 새로고침 및 탭 종료 시에 머문 시간을 측정하도록 추가 구성하였습니다.

1. GA 초기화
- react-ga4 라이브러리를 이용하여서 GA 사용을 초기화 합니다

2. GA 기록 -1
- 기본적으로 사용자의 웹 체류시간에 대한 이벤트 기록을 추가로 수행합니다

3. GA 기록 -2
- 새로고침, 탭 닫기에 대한 체류시간에 대해서도 기록을 수행합니다.

// RouteChangeTracker.tsx
import { useEffect, useRef } from 'react';
import { useLocation } from 'react-router-dom';
import ReactGA from 'react-ga4';

const GA_ID = 'G-XXXXXXX';
const STORAGE_KEY = 'ROUTE_TRACK_LOG';
const MAX_LOG = 100;

let gaInitialized = false;

export default function RouteChangeTracker() {
    const location = useLocation();

    const enterTimeRef = useRef<number>(Date.now());
    const prevPathRef = useRef<string>(location.pathname);

    /**
     * GA4 초기화
     */
    useEffect(() => {
        if (!gaInitialized) {
            ReactGA.initialize(GA_ID, {
                gaOptions: {
                    debug_mode: true,
                },
            });
            gaInitialized = true;
        }
    }, []);

    /**
     * 체류시간 이벤트 전송
     */
    const sendStayEvent = (path: string, enterAt: number) => {
        const now = Date.now();
        const durationSec = Math.round((now - enterAt) / 1000);
        if (durationSec <= 0) return;

        ReactGA.event('page_stay', {
            page_path: path,
            engagement_time_sec: durationSec,
        });

        const log = {
            path,
            enterAt,
            leaveAt: now,
            durationSec,
        };

        const prev = JSON.parse(localStorage.getItem(STORAGE_KEY) || '[]');
        localStorage.setItem(
            STORAGE_KEY,
            JSON.stringify([...prev, log].slice(-MAX_LOG))
        );
    };

    /**
     * 라우트 변경 → 이전 페이지 체류시간 기록
     */
    useEffect(() => {
        sendStayEvent(prevPathRef.current, enterTimeRef.current);

        enterTimeRef.current = Date.now();
        prevPathRef.current = location.pathname;
    }, [location.pathname]);

    /**
     * 최초 진입 페이지 보정
     */
    useEffect(() => {
        return () => {
            sendStayEvent(prevPathRef.current, enterTimeRef.current);
        };
    }, []);

    /**
     * 새로고침 / 탭 종료 보조 처리
     */
    useEffect(() => {
        const handleUnload = () => {
            sendStayEvent(prevPathRef.current, enterTimeRef.current);
        };

        window.addEventListener('beforeunload', handleUnload);
        return () => window.removeEventListener('beforeunload', handleUnload);
    }, []);

    return null;
}

3. Layout

Layout

- 한 번만 수행되어야 하는 컴포넌트이기에, 아래와 같이 추가가 되었습니다.

import { Outlet } from "react-router-dom";
import Header from "./Header";
import Footer from "./Footer";
import RouteChangeTracker from "../ga/RouteChangeTracker";

export default function Layout() {
    return (
        <div style={styles.container}>
            <Header />

            <main style={styles.main}>
                <RouteChangeTracker />
                <Outlet />
            </main>

            <Footer />
        </div>
    );
}

const styles: Record<string, React.CSSProperties> = {
    container: {
        minHeight: "100vh",
        display: "flex",
        flexDirection: "column",
    },
    main: {
        flex: 1,
        padding: 24,
        background: "#f9fafb",
    },
};

4) 결과

결과

- 아래와 같이 기록한 이벤트들이 잘 들어오는 것을 확인하였습니다.

오늘도 감사합니다.

[기타] Gemini Mac 환경에서 바로 실행 방법

adjh54 — Fri, 6 Feb 2026 20:00:08 +0900

해당 글에서는 Mac 환경에서 Gemini를 바로 실행하는 방법에 대해 알아봅니다.

1) 문제점

문제점

- MacOS 환경에서 Gemini를 바로 실행하는 애플리케이션이 없기에 브라우저를 통해서 실행해야 합니다.
- 그렇기에 빠르게 브라우저를 실행하여 Gemini로 접속할 수 있는 방법에 대해 알아봅니다.

2) Chorme에서 실행 방법

1. 사이트 접속

사이트 접속

- Google Chorme을 통해서 Gemini 사이트에 접속합니다.

https://gemini.google.com/

2. Chrome 가장 오른쪽 점 3개 아이콘(⋮)을 누릅니다

3. 전송, 저장, 공유 > 바로가기 만들기… 를 선택합니다.

4. 바로가기를 만들어줍니다

5. 바로가기를 Dock으로 드래그하면 완료가 됩니다.

2) Safari에서 실행

1. 사이트 접속

사이트 접속

- Safari를 이용하여 Gemini 사이트에 접속합니다.

https://gemini.google.com/app

2. 상단 메뉴에서 파일 > Dock에 추가.. 버튼을 누릅니다.

3. Dock에 추가를 합니다

4. 아래와 같이 추가가 되어 완료되었습니다

오늘도 감사합니다.

[JS] Quill Editor v2 이해하고 활용하기-1: 기본 활용

adjh54 — Thu, 5 Feb 2026 20:00:42 +0900

해당 글에서는 Quill Editor를 이해하고 활용하는 방법에 대해서 알아봅니다.

1) Quill

Quill

- 웹 기반의 리치 텍스트 에디터를 무료로 사용할 수 있는 오픈 소스 에디터입니다. 단순한 HTML의 textarea가 아닌 문서 구조를 데이터로 관리하는 특징을 가진 에디터입니다.
- 이러한 문서 구조의 데이터는 HTML 문자열이 아닌 Quill 자체의 ‘Delta 데이터 타입(JSON)’을 통해서 데이터가 전달되고 관리가 됩니다.
- BSD 3-clause 라이선스로 상업 서비스·유료 제품·폐쇄 소스 프로젝트에서도 사용 가능합니다

Quill - Your powerful rich text editor

Built for Developers Granular access to the editor's content, changes and events through a simple API. Works consistently and deterministically with JSON as both input and output.

quilljs.com

1. Quill Delta

Quill Delta

- Delta는 Quill이 문서를 표현하는 표준 변경 포맷(JSON)을 의미합니다.
- HTML의 모호함과 복잡성 없이 모든 텍스트 및 서식 정보를 포함하는 모든 서식 있는 텍스트 문서를 설명할 수 있습니다.

속성	설명	사용예시
insert	현재 문서에 무언가를 추가하는 지에 대해 기록하는 방식	{ "insert": "제목", "attributes": { "header": 1 } }
delete	현재 문서를 기준으로 앞쪽의 내용을 제거하는 방식	{ "delete": 5 }
retain	기존 콘텐츠를 유지하면서, 위치를 건너뛰거나 스타일을 변경하는 방식	{ "retain": 3, "attributes": { "bold": true }

아래와 같은 데이터 구조로 저장되고 관리할 수 있습니다.

- 기존 html을 문자열로 저장하는 것보다 구조가 명확하다는 장점을 가지고 있습니다.

HTML 문자열 구조의 데이터 타입 형태

Quill의 ‘Delta’ 데이터 타입 형태

Quill Delta 구조

[
    {
        "insert": "테스트중에 있습니다\\n\\n여러가지 효과에 대해서 저장이 가능합니다\\n\\n굵기 테스트\\n\\nString codeTest;"
    },
    {
        "attributes": {
            "code-block": "plain"
        },
        "insert": "\\n"
    },
    {
        "insert": "\\n인용구 테스트"
    },
    {
        "attributes": {
            "blockquote": true
        },
        "insert": "\\n"
    },
    {
        "insert": "\\n"
    },
    {
        "insert": {
            "video": "<https://www.youtube.com/embed/eNL_fWxWh0w?showinfo=0>"
        }
    },
    {
        "insert": "\\n\\n"
    }
]

2) 설치

1. react-quill

react-quill

- Quill을 이용하는데 React 16 미만 버전에 대해서 지원하는 구 버전입니다.
- 현재는 운영유지보수가 되지 않고 있습니다.

$ npm i react-quill

# or

$ yarn add npm i react-quill

2. react-quill-new (React Quill v2)

react-quill-new

- Quill을 이용하는데 React 16+ 및 Typescript를 지원하는 버전입니다.

$ npm i react-quill

# or

$ yarn add npm i react-quill

GitHub - VaguelySerious/react-quill: A Quill component for React.

A Quill component for React. Contribute to VaguelySerious/react-quill development by creating an account on GitHub.

github.com

3. Quill 생태계 주요 라이브러리들

추가 라이브러리	설명
quill-delta	Delta 자료구조 전용 라이브러리를 의미합니다. HTML 구조가 아닌 Quill만의 Delta(JSON) 구조를 통해 데이터를 저장하고 관리합니다.
@mgreminger/quill-image-resize-module	에디터에서 이미지 크기 조절 필요할 때 사용하는 라이브러리를 의미합니다. 이를 통해 이미지의 사이즈 조정이 가능합니다.
quill-delta-to-html	Delta 자료구조를 HTML로 변환해주는 라이브러리를 의미합니다. 이를 통해 Viewer, SSR, 미리보기와 같은 기능에 이용이 됩니다.
quill-better-table	Quill Editor 내에서 테이블을 추가할 수 있는 라이브러리를 의미합니다.
quill-mention	Quill 내에서 @멘션 및 자동완성 기능의 라이브러리를 의미합니다.

$ yarn add quill-delta
 
$ yarn add quill-image-resize-module quill-resize-module

3) 사용 방법

1. 환경

추가 라이브러리	설명
react-quill-new	3.7.0
idb	8.0.3
quill-delta	5.1.0
@mgreminger/quill-image-resize-module	1.0.5

2. Quill 등록 예시

Quill 등록 예시

- 아래와 같은 Quill Editor를 이용한 Delta 데이터로 index DB에 저장하는 예시입니다.

- import 'react-quill-new/dist/quill.snow.css': ‘snow 테마’를 선택하였습니다.
- format: 에디터에서 허용할 서식(format) 목록을 명시적으로 제한합니다. 즉, 에디터에서 사용할 서식을 지정합니다.
- toolbarOptions: 상단에 툴바에 나오는 옵션들을 지정합니다.
- modules : Quill의 플러그인·기능·동작 방식 설정 집합을 의미합니다.

이러한 옵션들을 통해 ReactQuill 태그 내에서 사용될 옵션들을 지정합니다.

import React, { useEffect, useState } from 'react';
import ReactQuill, { Quill } from 'react-quill-new';
import ImageResize from "@mgreminger/quill-image-resize-module";
import 'react-quill-new/dist/quill.snow.css';

import { v4 as uuidv4 } from 'uuid';

Quill.register('modules/imageResize', ImageResize);

import Delta from 'quill-delta';
import { dbPromise } from '../../server/dbPromise';
import { useNavigate } from 'react-router-dom';

export default function QuillEditorPage() {
    const navigate = useNavigate();
    const [title, setTitle] = useState('');
    const [contentHtml, setContentHtml] = useState('');
    const [contentDelta, setContentDelta] = useState<Delta | null>(null);

    const formats = [
        'header',
        'bold', 'italic', 'underline', 'strike',
        'blockquote', 'code-block',
        'list', 'bullet', 'check',
        'indent',
        'link',
        'image',
        'video',
        'color', 'background',
        'align',
        'font',
        'size',
    ];

    const toolbarOptions = [
        ['bold', 'italic', 'underline', 'strike'],
        ['blockquote', 'code-block'],
        ['link', 'image', 'video', 'formula'],
        [{ header: 1 }, { header: 2 }],
        [{ list: 'ordered' }, { list: 'bullet' }, { list: 'check' }],
        [{ script: 'sub' }, { script: 'super' }],
        [{ indent: '-1' }, { indent: '+1' }],
        [{ direction: 'rtl' }],
        [{ size: ['small', false, 'large', 'huge'] }],
        [{ header: [1, 2, 3, 4, 5, 6, false] }],
        [{ color: [] }, { background: [] }],
        [{ font: [] }],
        [{ align: [] }],
        ['clean'],
    ];

    const modules = {
        toolbar: toolbarOptions,
        imageResize: {
            modules: ['Resize', 'DisplaySize', 'Toolbar'],
        },
    };

    const checkPosts = async () => {
        const db = await dbPromise;
        const allPosts = await db.getAll('posts');
        console.log(allPosts);
    };
    useEffect(() => {
        checkPosts();
    }, [])

    const handleSave = async () => {
        if (!title.trim()) {
            alert('제목을 입력해 주세요.');
            return;
        }

        if (!contentDelta || !contentDelta.ops?.length) {
            alert('내용을 입력해 주세요.');
            return;
        }

        await savePostToDB({
            title,
            contentDelta,
            contentHtml,
        });

        alert('로컬에 저장되었습니다.');
        navigate('/editor/quill/list');

    };

    const savePostToDB = async ({
        title,
        contentDelta,
        contentHtml,
    }: {
        title: string;
        contentDelta: Delta;
        contentHtml: string;
    }) => {
        const db = await dbPromise;

        const now = new Date().toISOString();

        const id = uuidv4();
        await db.put("posts", {
            id,
            title,
            contentDelta,
            contentHtml,
            createdAt: now,
            updatedAt: now,
        });
    };

    return (
        <div style={styles.page}>
            <div style={styles.container}>
                <div style={styles.header}>
                    <h1 style={styles.title}>게시글 작성</h1>
                    <p style={styles.subtitle}>
                        내용을 자유롭게 작성해 주세요.
                    </p>
                </div>

                <input
                    style={styles.titleInput}
                    placeholder="제목을 입력하세요"
                    value={title}
                    onChange={(e) => setTitle(e.target.value)}
                />

                <div style={styles.editorWrapper}>
                    <ReactQuill
                        theme="snow"
                        value={contentHtml}
                        onChange={(html, delta, source, editor) => {
                            setContentHtml(html);
                            setContentDelta(editor.getContents());
                        }}
                        modules={modules}
                        formats={formats}  
                        style={styles.editor}
                        placeholder="내용을 입력하세요..."
                    />
                </div>
                <div style={styles.footer}>
                    <button
                        style={styles.backButton}
                        onClick={() => window.history.back()}
                    >
                        ← 뒤로가기
                    </button>

                    <button
                        style={styles.saveButton}
                        onClick={handleSave}
                    >
                          저장
                    </button>
                </div>
                <div style={styles.footerNote}>
                    Editor powered by react-quill-new v3.7.0
                </div>
            </div>

        </div>
    );
}

/* ===================== 스타일 ===================== */
const styles: Record<string, React.CSSProperties> = {
    page: {
        minHeight: '100vh',
        background: '#f5f6f8',
        padding: '40px 0',
    },
    container: {
        maxWidth: 960,
        margin: '0 auto',
        background: '#fff',
        padding: '32px 36px',
        borderRadius: 16,
        boxShadow: '0 12px 30px rgba(0,0,0,0.08)',
    },
    header: {
        marginBottom: 28,
    },
    title: {
        margin: 0,
        fontSize: 28,
        fontWeight: 700,
        color: '#111',
    },
    subtitle: {
        marginTop: 8,
        color: '#666',
        fontSize: 14,
    },
    titleInput: {
        width: '100%',
        padding: '14px 16px',
        fontSize: 18,
        borderRadius: 8,
        border: '1px solid #ddd',
        marginBottom: 20,
        outline: 'none',
    },
    editorWrapper: {
        borderRadius: 12,
        overflow: 'hidden',
        border: '1px solid #e5e7eb',
    },
    editor: {
        minHeight: 400, // ⭐ 높이 증가
        fontSize: 16,
    },
    footer: {
        marginTop: 32,
        display: 'flex',
        justifyContent: 'center',
        gap: 12,
    },

    backButton: {
        padding: '12px 20px',
        fontSize: 14,
        fontWeight: 600,
        borderRadius: 8,
        border: '1px solid #d1d5db',
        background: '#fff',
        color: '#374151',
        cursor: 'pointer',
        transition: 'all 0.2s ease',
    },
    footerNote: {
        marginTop: 12,
        fontSize: 12,
        color: '#888',
        textAlign: 'right',
    },
    saveButton: {
        padding: '12px 24px',
        fontSize: 14,
        fontWeight: 700,
        borderRadius: 8,
        border: 'none',
        background: '#2563eb', // 블루
        color: '#fff',
        cursor: 'pointer',
        transition: 'all 0.2s ease',
    },
};

아래와 같이 지정한 툴바들이 사용이 됩니다.

아래와 같이 툴바를 이용하고 등록을 합니다.

[참고] 다양한 옵션은 아래의 링크에서 확인이 가능합니다.

Quill - Your powerful rich text editor

Built for Developers Granular access to the editor's content, changes and events through a simple API. Works consistently and deterministically with JSON as both input and output.

quilljs.com

3. Quill 상세 조회 예시

Quill 상세 조회 예시

- 위에서 IndexDB내에 임시로 저장한 데이터들에 대해서 상세 화면으로 출력을 합니다.
- 위와 다르게 테마를 bubble을 이용하여서 화면상에 출력을 합니다.
- 저장된 id 값을 기반으로 저장된 Delta 구조를 기반으로 ReactQuill 태그 내에 데이터를 출력하며, 화면상에 출력을 합니다.

Quill의 bubble 테마를 이용하여서 에디터 내용을 상세화면으로 출력합니다.

import { useEffect, useState } from "react";
import { useNavigate, useParams } from "react-router-dom";
import ReactQuill from "react-quill-new";
import "react-quill-new/dist/quill.bubble.css";

import { getPostById } from "../../server/dbPromise";

interface Post {
    id: string;
    title: string;
    contentDelta: any;
    contentHtml: string;
    createdAt: string;
    updatedAt: string;
}
function formatDate(iso: string) {
    return new Date(iso).toISOString().slice(0, 10);
}
export default function QuillPostDetailPage() {
    const { id } = useParams<{ id: string }>();
    const navigate = useNavigate();

    const [post, setPost] = useState<Post | null>(null);

    useEffect(() => {
        if (!id) return;

        (async () => {
            const data = await getPostById(id);
            setPost(data ?? null);
            console.log("data : ", data)
        })();

    }, [id]);

    if (!post) {
        return <div style={styles.loading}>게시글을 불러오는 중입니다…</div>;
    }

    return (
        <div style={styles.page}>
            {/* ===== 상단 액션 ===== */}
            <div style={styles.topBar}>
                <button
                    style={styles.backButton}
                    onClick={() => navigate(-1)}
                >
                    ← 목록
                </button>
            </div>

            {/* ===== 제목 영역 ===== */}
            <h1 style={styles.title}>{post.title}</h1>
            <div style={styles.date}>
                {formatDate(post.createdAt)}
            </div>

            <hr style={styles.divider} />

            {/* ===== Quill Viewer ===== */}
            <ReactQuill
                value={post.contentDelta}
                readOnly
                theme="bubble"
            />
        </div>
    );
}

const styles: Record<string, React.CSSProperties> = {
    page: {
        maxWidth: 800,
        margin: "40px auto",
        padding: 24,
        background: "#ffffff",
        borderRadius: 12,
        boxShadow: "0 8px 24px rgba(0,0,0,0.06)",
    },
    topBar: {
        marginBottom: 16,
    },
    backButton: {
        border: "none",
        background: "transparent",
        cursor: "pointer",
        fontSize: 14,
        color: "#6b7280",
    },
    title: {
        fontSize: 28,
        fontWeight: 700,
        marginBottom: 8,
    },
    date: {
        fontSize: 13,
        color: "#9ca3af",
        marginBottom: 20,
    },
    divider: {
        border: "none",
        borderTop: "1px solid #e5e7eb",
        marginBottom: 20,
    },
    loading: {
        textAlign: "center",
        padding: 40,
        color: "#9ca3af",
    },
};

아래와 같이 위에서 저장한 내용이 아래와 같이 보입니다.

추가로 툴바로 저장한 이미지, youtube 영상, 코드스니핏등 다양하게 화면상에 출력이 가능합니다.

4) Quill과 XSS(Cross-Site Scripting) 방지

Quill과 XSS(Cross-Site Scripting) 방지

- HTML 전송의 경우는 XSS 공격에 취약합니다. HTML 코드를 중간에 탈취하고 변경하여서 데이터베이스에 저장하여 이를 통해 공격을 합니다.
- Quill의 경우는 HTML 형태로 전송되지 않고, Quill만의 ‘Delta’라는 JSON 구조로 데이터를 전송하기에 Delta 자체로는 XSS를 만들 수 없습니다.

[참고] XSS(Cross-Site Scripting)

- 공격자가 취약한 웹사이트에 악성 스크립트를 삽입하여, 이를 방문하는 사용자의 브라우저에서 스크립트를 실행시키는 클라이언트 측 공격입니다.
- 세션 쿠키 탈취, 데이터 도난, 웹사이트 변조, 피싱 사이트 리다이렉션 등의 피해를 유발합니다.
- 주요 원인은 입력값 검증 미흡이며, 저장형, 반사형, DOM 기반 XSS로 나뉩니다.

아래와 같이 Markup을 포함하여 저장하고 있지 않습니다.

{
    "insert": "HTML 자체를 저장하는게 아니라\\n\\nDelta라는 데이터 구조로 저장하기에 이를 조합하여 전달할 수 없습니다.\\n"
}

HTML 구조의 경우는 아래와 같은 형태로 저장되고 있습니다.

<p>HTML&nbsp;자체를&nbsp;저장하는게&nbsp;아니라</p><p></p><p>Delta라는&nbsp;데이터&nbsp;구조로&nbsp;저장하기에&nbsp;이를&nbsp;조합하여&nbsp;전달할&nbsp;수&nbsp;없습니다.</p>

오늘도 감사합니다.

[Trend] Spring Boot 4 Release Note 읽어보기

adjh54 — Wed, 21 Jan 2026 19:49:30 +0900

해당 글에서는 Spring Boot 4가 출시되어 주요 내용에 대한 Release Note를 읽어보기 위해 작성한 글입니다.

1) Spring Boot 4

Spring Boot 4

- 2025년 11월 공식 릴리스된 Spring Boot의 메이저 버전 업그레이드로, 이전의 3.x 라인과 비교해 상당한 아키텍처 개선과 신기능이 도입된 새로운 세대의 프레임워크입니다.

- Spring Boot는 Java 생태계에서 가장 널리 쓰이는 백엔드 프레임워크로, 설정을 최소화하면서 Spring 기반 애플리케이션을 빠르게 만들도록 도와줍니다.
- 버전 4.0은 Spring Framework 7을 기반으로 하며, 클라우드·컨테이너·모던 Java 생태계에 더 적합하도록 여러 부분이 근본적으로 재설계되었습니다
- Spring Boot 4 버전에서는 Java 25에 대한 완벽한 지원을 제공하며, Java 17과의 호환성도 유지합니다.

https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes

Spring Boot 4.0 Release Notes

Spring Boot helps you to create Spring-powered, production-grade applications and services with absolute minimum fuss. - spring-projects/spring-boot

github.com

1. Spring Boot 4 Release Note 주요 사항

Spring Boot 4 Release Note 주요 사항

- 해당 글에서는 Release Notes에 있는 주요한 사항에 대해서만 확인해 봅니다.

주요 내용	설명
Gradle 9	- Spring Boot4 애플리케이션 빌드에 Gradle 9가 지원됩니다. - 기존 Gradle 8.x(8.14 이상)에 대한 지원은 계속 유지됩니다.
HTTP Service Interface Clients	- HTTP 서비스를 호출할 때 RestClient나 WebClient를 직접 사용하는 대신, @HttpExchange 계열 어노테이션(@GetExchange, @PostExchange, @DeleteExchange 등)이 붙은 Java 인터페이스를 통해 선언적으로 호출할 수 있습니다.
API Versioning	- Spring Boot 4 (Spring Framework 7.x 이후)에서는 요청 Header를 조건으로 사용하는 API 버저닝 방식을 보다 자연스럽게 적용할 수 있습니다.
JmsClient	- JMS(Java Message Service) 내에서 기존 JmsTemplate, JmsMessagingTemplate를 사용했던 부분에 대해서 Spring에서 RestClient / HttpService Clients 스타일에 맞춘 JmsClient API가 추가되었습니다.
OpenTelemetry starter	- OpenTelemetry(OTel) 는 관측성(Observability)을 위한 표준 스펙 + 라이브러리 집합이며, 내부 동작에 대해서 관측하는 라이브러리가 Spring Boot Starter로 추가되었습니다.

Spring Boot 4.0.0 available now

On behalf of the team and everyone who has contributed, I'm extremely happy to announce that Spring Boot 4.0.0 has been released and is now available from Maven Central. This release is the beginning of a new Spring Boot generation providing solid foundati

spring.io

2) Gradle 9

Gradle 9

- Spring Boot 4 애플리케이션 빌드에 Gradle 9가 지원됩니다.
- 기존 Gradle 8.x(8.14 이상)에 대한 지원은 계속 유지됩니다.

1. Java Version 별 지원 Gradle 버전

Java Version 별 지원 Gradle 버전

- Spring Boot 4 버전에서 Java 25 버전이 지원되기에 Gradle 9까지 지원이 되는 것 같습니다.
- 현재 2026.01.21일 기준 Gradle 9.3.0 버전까지 출시가 되었습니다.

Java Version	Support for toolchains	Support for running Gradle
8	N/A	2.0 to 8.14.*
9	N/A	4.3 to 8.14.*
10	N/A	4.7 to 8.14.*
11	N/A	5.0 to 8.14.*
12	N/A	5.4 to 8.14.*
13	N/A	6.0 to 8.14.*
14	N/A	6.3 to 8.14.*
15	6.7	6.7 to 8.14.*
16	7.0	7.0 to 8.14.*
17	7.3	7.3 and after
18	7.5	7.5 and after
19	7.6	7.6 and after
20	8.1	8.3 and after
21	8.4	8.5 and after
22	8.7	8.8 and after
23	8.10	8.10 and after
24	8.14	8.14 and after
25	9.1.0	9.1.0 and after
26	N/A	N/A

Compatibility Matrix

Gradle runs on the Java Virtual Machine (JVM), which is often provided by either a JDK or JRE. A JVM version between 17 and 25 is required to execute Gradle. JVM 26 and later versions are not yet supported. The Gradle wrapper, Gradle client, Tooling API cl

docs.gradle.org

[참고] Java LTS 버전 확인 : Oracle Java SE 기준

- Java LTS 버전은 8, 11, 17, 21, 25입니다.

https://www.oracle.com/kr/java/technologies/java-se-support-roadmap.html

[더 알아보기]

왜 LTS(Long Term Support) 버전을 이용해야 할까?

1. 운영 환경에서의 안정성·보안·유지비용을 최소화하기 위해서입니다.
- LTS 버전의 경우는 3 ~ 5년 이상의 보안 패치를 제공하지만, 일반 버전의 경우는 6개월 ~ 1년 내 종료가 됩니다.

2. 프레임워크, 라이브러리는 LTS를 기준으로 발전을 합니다
- Spring Boot, Hibernate, Gradle / Maven의 경우는 새로운 버전 LTS JVM을 기준으로 지원을 합니다.

3. 팀 조직 간의 관점에서 관리가 쉽습니다.
- 팀 내에서 각각 다른 버전을 이용하는 근거가 부족하기에 조직 내에서 동일한 버전 환경에서 개발을 할 때에 유용합니다.

3) HTTP Service Interface Clients

HTTP Service Interface Clients

- HTTP 서비스를 호출할 때 RestClient나 WebClient를 직접 사용하는 대신, @HttpExchange 계열 어노테이션 (@GetExchange, @PostExchange, @DeleteExchange 등)이 붙은 Java 인터페이스를 통해 선언적으로 호출할 수 있습니다.

- HTTP Service Interface Clients는 Spring Boot 4에서 자동 구성 및 구성 속성 지원이 추가되었으며, 일반 Java 인터페이스에 어노테이션을 선언하면 Spring이 런타임에 프락시 기반 구현체를 자동으로 생성합니다.
- 기존에는 RestClient나 WebClient를 직접 사용하여 외부 HTTP 통신을 수행했다면, Spring Boot 4에서는 개발자가 HTTP Service Interface Clients의 인터페이스 메서드를 호출하면 Spring Proxy가 이를 가로어 내부적으로 RestClient(동기) 또는 WebClient(비동기)를 사용해 실제 HTTP 요청을 수행하는 구조로 동작합니다.

https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes

Calling REST Services :: Spring Boot

Both WebClient and RestClient support making versioned remote HTTP calls so that APIs can be evolved over time. Commonly this involves sending an HTTP header, a query parameter or URL path segment that indicates the version of the API that should be used.

docs.spring.io

1. Spring HTTP Client

Spring HTTP Client

- Spring 환경에서 HTTP 통신을 위한 클라이언트들에 대해 간략하게 알아봅니다.

Spring HTTP Client	Client 호출 방식	설명	종속성 라이브러리	지원범위
RestTemplate	동기식 / 블로킹	- 가장 오래된 전통적인 HTTP 클라이언트. 요청–응답 동안 스레드를 점유하는 명령형 API이며, 코드가 단순하지만 확장성과 테스트성이 떨어짐. - 현재는 유지보수 모드로 신규 개발에는 권장되지 않음	spring-boot-starter-web (spring-web)	Spring Boot 2.x+ (Spring 3~6)
RestClient	동기식	- RestTemplate의 공식 후속. 내부적으로는 WebClient 기반이지만 동기 호출 방식을 제공하는 최신 클라이언트. - Fluent API와 간결한 설정이 특징이며, Spring 팀이 권장하는 동기 HTTP 클라이언트	spring-boot-starter-web (spring-web)	Spring Framework 6.1+ / Spring Boot 3.2+
WebClient	비동기 / 논블로킹	- Reactive Streams 기반의 고성능 HTTP 클라이언트. 적은 스레드로 많은 요청을 처리할 수 있으며 스트리밍, 대량 트래픽 처리에 적합. 러닝 커브가 있으나 가장 확장성이 높음	spring-boot-starter-webflux (spring-webflux)	Spring 5.0+ / Spring Boot 2.x+
Spring Cloud OpenFeign	동기식 (기본)	- 인터페이스 + 어노테이션 기반의 선언형 HTTP 클라이언트. 내부 구현은 프록시로 생성되며, MSA 환경에서 서비스 간 통신에 최적화. - Retry, CircuitBreaker, LoadBalancer 등 Spring Cloud 기능과 강하게 결합	spring-cloud-starter-openfeign	Spring Boot 2.x ~ 3.x (Spring Cloud 의존)

[Java] Spring Boot Web 활용 : RestTemplate 이해하기

해당 글에서는 RestTemplate에 대해 이해하고 활용 방법에 대해 확인해 봅니다. [참고] Java에서 외부 통신을 하는 방법들에 대해 궁금하시면 아래의 글을 참고하시면 도움이 됩니다분류주제링크R

adjh54.tistory.com

[Java] Spring Boot Webflux 이해하기 -2 : 활용하기

해당 페이지에서는 Spring Boot Webflux를 이용하여 실제 구현하고 활용하는 방법과 WebClient를 이용한 다른 도메인 호출 방법에 대해 공유합니다. [참고] Spring WebFlux 관련 글에 대해 궁금하시면 아

adjh54.tistory.com

[Java] Spring Cloud OpenFeign 이해하고 활용하기 -1 : 주요 개념 및 환경 구성, 활용 예시

해당 글에서는 Spring Cloud OpenFeign을 활용하여 외부 통신을 활용하는 예시에 대해 알아봅니다. [참고] Java에서 외부 통신을 하는 방법들에 대해 궁금하시면 아래의 글을 참고하시면 도움이 됩

adjh54.tistory.com

2. 구조 확인

구조 확인

- 기존의 Spring Cloud에서 외부 통신으로 사용한 OpenFeign의 구조입니다. 이는 인터페이스 기반의 선언형 모델로 사용되고 있습니다.

https://adjh54.tistory.com/616

HTTP Service Interface Clients를 확인해 봤을 때, 동일하게 인터페이스를 구성하고 이를 호출하여서 외부 HTTP 통신을 수행합니다.

3. 활용

활용

- Spring Boot 서버가 실행이 되고, Client가 특정 엔드포인트로 요청을 하고 Spring Boot 내부적으로 외부 API 호출을 하여 데이터를 가져오는 구조입니다.

3.1. SpringBoot4InitApplication

SpringBoot4InitApplication

- 애플리케이션 서버가 실행될 때 최초 수행이 됩니다.

- @ImportHttpServices 어노테이션을 통해서, 패키지 별, 그룹 별로 지정된 클라이언트 프록시를 생성하고 해당 프록시를 빈으로 등록할 HTTP 서비스 유형(메서드를 포함하는 인터페이스)을 선언하기 위한 어노테이션입니다.

package com.adjh.springboot4init;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.service.registry.ImportHttpServices;

@ImportHttpServices(basePackages = "com.adjh.springboot4init.service.client")
@SpringBootApplication
public class SpringBoot4InitApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringBoot4InitApplication.class, args);
    }
}

[참고] ImportHttpServices API Document

ImportHttpServices (Spring Framework 7.0.3 API)

A list of HTTP Service types to include in the group.

docs.spring.io

3.2. EchoService : interface

EchoService : interface

- @HttpExchange를 통해서 특정 url을 통해서 통신을 수행합니다.
- @PostExchange 어노테이션은 이 메서드가 HTTP POST 요청을 수행한다는 것을 선언적으로 정의합니다.

package com.adjh.springboot4init.service.client;

import org.springframework.http.MediaType;
import org.springframework.stereotype.Service;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.service.annotation.HttpExchange;
import org.springframework.web.service.annotation.PostExchange;

import java.util.Map;

/**
 * HTTP Service Interface Clients 사용예시
 *
 * @author : leejonghoon
 * @fileName : EchoService
 * @since : 26. 1. 15.
 */
@Service
@HttpExchange(
        url = "https://echo.zuplo.io",
        contentType = MediaType.APPLICATION_JSON_VALUE)
public interface EchoService {

    @PostExchange
    Map echo(@RequestBody Map<string, string=""> message);
}
</string,>

[참고] @PostExchange API Document

PostExchange (Spring Framework 7.0.3 API)

docs.spring.io

3.3. EchoController

EchoController

- 클라이언트가 API 요청 시 이를 받아서 외부 API 호출을 하여 요청 값을 전달하고 응답값을 반환해 오는 Controller입니다.

package com.adjh.springboot4init.controller;

import com.adjh.springboot4init.service.EchoCallerService;
import com.adjh.springboot4init.service.client.EchoService;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

/**
 * 클라이언트의 요청 값을 통해 외부 API로 요청 값을 전달하고 결과를 응답하는 Controller 
 *
 * @author : leejonghoon
 * @fileName : EchoController
 * @since : 26. 1. 15.
 */
@RestController
@RequestMapping("/api/echo")
public class EchoController {

    private final EchoService echoService;

    public EchoController(EchoService echoService) {
        this.echoService = echoService;
    }

    @PostMapping("/test")
    public Map<?, ?> testEcho(@RequestBody Map<String, String> request) {
        return echoService.echo(request);
    }
}

3.4. 추가 : EchoCallerService

추가 : EchoCallerService

- HttpExchange를 통해서 외부 통신을 한 이후에 후 처리를 하는 부분 래퍼로 구성하였습니다.

package com.adjh.springboot4init.service;

import com.adjh.springboot4init.service.client.EchoService;
import org.springframework.stereotype.Service;

import java.util.Map;

/**
 * HTTP Service Interface Clients 외부 통신 이후 전처리 및 로깅을 처리하는 호출 Wrapper
 *
 * @author : leejonghoon
 * @fileName : EchoCallerService
 * @since : 26. 1. 20.
 */
@Service
public class EchoCallerService {
    private final EchoService echoService;

    public EchoCallerService(EchoService echoService) {
        this.echoService = echoService;
    }

    public Map<?, ?> callEcho(Map<String, String> message) {
        return echoService.echo(message);
    }
}

3.5. 정상적으로 외부 호출이 됨을 확인하였습니다.

4) API Versioning

API Versioning

- 기존 Spring Boot 3까지는 /api/v1/users, /api/v2/users와 같이 URL Path 기반 버저닝을 사용하는 경우가 일반적이었습니다. 이 방식은 직관적이지만, 버전이 늘어날수록 Controller와 엔드포인트가 증가하여 라우팅 구조가 복잡해지고 유지보수가 어려워지는 단점이 있습니다.

- Spring Boot 4 (Spring Framework 6.x 이후)에서는 요청 Header를 조건으로 사용하는 API 버저닝 방식을 보다 자연스럽게 적용할 수 있습니다.
- 예를 들어, API 호출 시 API-Version 또는 X-API-Version과 같은 Header 값을 전달하고 해당 값에 따라 서로 다른 Controller 메서드를 매핑할 수 있습니다.
- 이를 통해 URL 구조를 단순하게 유지하면서도 버전별 API를 명확하게 분리할 수 있어, 확장성과 유지보수 측면에서 더 유연한 설계를 할 수 있습니다.

https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes

API Versioning in Spring

In this 2nd blog post of the Road to GA series highlighting major features within the Spring portfolio for the next major versions to be released in November, I’m going to focus on the upcoming API Versioning support in Spring Framework 7. Introduction A

spring.io

1. Server Handling

Server Handling

- URL이나 파라미터가 아니라 HTTP Header 값으로 API 버전을 구분하는 방식입니다.
- Spring MVC에게 API 버전을 API-Version 헤더를 기준으로 버전을 확인하는 방식을 의미합니다.

Request Header 내에 API-Version 속성에 대해서 값을 1, 2, 3으로 전달하여서 버전을 확인하는 방식을 의미합니다.

### Echo Test
POST http://localhost:8080/api/echo/test
Content-Type: application/json
API-Version: 1

아래의 코드에서도 useRequestHeader("API-Version")를 통해서 header의 속성을 지정하고 확인하도록 하였습니다.

- API 내에서는 @XXMapping의 속성 값인 version에 따라서 분기를 수행하였습니다. API 내의 [POST] /api/echo/test로 호출을 할 때 Header의 “API-Version” 속성 내에 “1”, “2”로 분기를 하였을 때 각기 다른 API가 호출이 됩니다.

// 설정 API 구성
@Configuration
public class WebConfiguration implements WebMvcConfigurer {

	@Override
	public void configureApiVersioning(ApiVersionConfigurer configurer) {
		configurer.useRequestHeader("API-Version");
	}
}

@RestController
@RequestMapping(value = "/api/echo")
public class EchoController {

    private final EchoService echoService;

    public EchoController(EchoService echoService) {
        this.echoService = echoService;
    }

    @PostMapping(value = "/test", version = "1")
    public Map<?, ?> testEcho(@RequestBody Map<String, String> request) {
        System.out.println("버전 1 API가 호출이 되었습니다.");
        return echoService.echo(request);
    }

    @PostMapping(value = "/test", version = "2")
    public Map<?, ?> testEcho2(@RequestBody Map<String, String> request) {
        System.out.println("버전 2 API가 호출이 되었습니다.");
        return echoService.echo(request);
    }
}

결과 확인

- 아래와 같이 동일한 API 내에 Header를 API-Version: 1 또는 API-Version: 2로 변경하였을 때, 각기 다른 API가 호출이 됩니다.

2. Client Support

Client Support

- 클라이언트 입장에서 API 버전을 지정하여 요청을 수행해야 할 수 있습니다. 이를 위해 ApiVersionInserter요청에 버전을 한 번만 삽입하는 방법을 정의하는 설정이 있으며, 이후 요청을 할 때는 버전 값만 지정하면 됩니다.

2.1. RestClient 방식

RestClient 방식

- RestClient를 이용하여서 외부 API를 호출할 때에도, 전달받는 API내에서도 .apiVersionInserter()를 통해서 header 내에 API-Version을 전달하도록 구성할 수 있습니다.

// RestClient 생성자 구성
RestClient client = RestClient.builder()
		.baseUrl("<http://localhost:8080>")
		.apiVersionInserter(ApiVersionInserter.useHeader("API-Version"))
		.build();
		
		
// RestClient의 값을 지정(1.1)
Account account = client.get().uri("/accounts/1")
	.apiVersion(1.1)
	.retrieve()
	.body(Account.class);

2.2. HTTP Service Interface Clients 방식

HTTP Service Interface Clients 방식

- HTTP Service Interface Clients를 이용하여서 외부 API를 호출할 때도, 버전 관리를 지원합니다.

@HttpExchange("/accounts")
public interface AccountService {

	@GetExchange(url = "/{id}", version = "1.1")
	Account getAccount(@PathVariable int id);

}

5) JmsClient

JmsClient

- JMS(Java Message Service) 내에서 기존 JmsTemplate, JmsMessagingTemplate를 사용했던 부분에 대해서 Spring에서 RestClient / HttpService Clients 스타일에 맞춘 JmsClient API가 추가되었다고 합니다.
- 기존에 사용하고 있는 JmsTemplate, JmsMessagingTemplate는 유지가 된다고 합니다.

https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes

JmsClient (Spring Framework 7.0.3 API)

A fluent JmsClient with common send and receive operations against a JMS destination, dealing with Spring's common Message or with payload values. This is effectively an alternative to JmsMessagingTemplate, also delegating to Spring's JmsTemplate for perfo

docs.spring.io

1. JMS(Java Message Service)

JMS(Java Message Service)

- JMS(Java Message Service)는 자바 애플리케이션 간 비동기 메시지 통신을 위한 표준 API입니다. 직접적인 메서드 호출(RPC, REST)과 달리 메시지를 매개로 시스템을 느슨하게 결합시키는 것이 핵심 목적입니다. 메시지 큐(메시징 시스템)를 자바에서 사용하기 위한 표준 인터페이스(API)입니다.

- 서로 다른 애플리케이션 또는 컴포넌트가 메시지(Message)를 통해 비동기적으로 통신하도록 지원합니다.

JMS (Java Message Service) :: Spring Framework

JMS can be roughly divided into two areas of functionality, namely the production and consumption of messages. The JmsTemplate class is used for message production and synchronous message receipt. For asynchronous receipt similar to Jakarta EE’s message-

docs.spring.io

[ 더 알아보기 ]

JMS랑 Message Queue랑은 무슨 차이가 있을까?

- Message Queue의 경우는 비동기 메시징 구조를 의미하며, JMS의 경우는 이러한 메시지 큐를 사용하기 위한 ‘표준 인터페이스(API 규격)’을 의미합니다. 특히, 메시지 큐 종류 중에서도 JMS 계열인 ActiveMQ, IBM MQ의 경우는 JMS를 이용합니다.

- RabbitMQ의 경우는 AMQP라는 Advanced Message Queuing Protocol 프로토콜을 이용하여서 메시지큐를 다룹니다.

[Java] Spring Boot AMQP RabbitMQ 이해하기 -1 : 구조 및 종류

해당 글에서는 Spring Boot RabbitMQ에 대해 이해하고 활용하는 방법에 대해서 확인합니다. [참고] RabbitMQ에 대해 궁금하시면 아래의 글이 도움이 됩니다분류링크Spring Boot AMQP RabbitMQ -1 : 구조

adjh54.tistory.com

2. JmsTemplate

JmsTemplate

- JmsTemplate은 JMS를 사용하기 위한 Spring의 핵심 템플릿으로, Connection, Session, MessageProducer 등의 생성·관리와 메시지 전송 과정을 자동으로 처리해 주는 도구입니다.

// 템플릿 구성(ConnectionFactory)
@Bean
public ConnectionFactory connectionFactory() {
    ActiveMQConnectionFactory cf = new ActiveMQConnectionFactory();
    cf.setBrokerURL("tcp://localhost:61616");
    cf.setUserName("admin");
    cf.setPassword("admin");
    return cf;
}

// 메시지 송신 측
@Service
public class OrderProducer {

    private final JmsTemplate jmsTemplate;

    public OrderProducer(JmsTemplate jmsTemplate) {
        this.jmsTemplate = jmsTemplate;
    }

    public void sendOrder(String orderId) {
        jmsTemplate.convertAndSend(
            "queue.order",
            "주문 ID = " + orderId
        );
    }
}

// 메시지 수신 측
@Component
public class OrderConsumer {

    @JmsListener(destination = "queue.order")
    public void receive(String message) {
        System.out.println("수신 메시지: " + message);
    }
}

3. JmsMessagingTemplate

JmsMessagingTemplate

- Spring이 제공하는 JMS 전용 메시지 전송 헬퍼로, JmsTemplate을 감싸서 메시지를 객체 기반으로 쉽게 보내도록 도와주는 추상화 계층입니다.

// 송신측
@Service
public class PaymentProducer {

    private final JmsMessagingTemplate jmsMessagingTemplate;

    public PaymentProducer(JmsMessagingTemplate jmsMessagingTemplate) {
        this.jmsMessagingTemplate = jmsMessagingTemplate;
    }

    public void sendPayment(String paymentId) {
        jmsMessagingTemplate.convertAndSend(
            "queue.payment",
            paymentId
        );
    }
}

// 수신 측
@Component
public class PaymentConsumer {

    @JmsListener(destination = "queue.payment")
    public void receive(
        String payload,
        @Header("traceId") String traceId
    ) {
        System.out.println("payload = " + payload);
        System.out.println("traceId = " + traceId);
    }
}

4. JmsClient

JmsClient

- 기존 JmsTemplate, JmsMessagingTemplate와 다르게 플루언트 인터페이스(Fluent Interface) 형태로 구성되어 있습니다.
- 소스코드의 가독성을 높이기 위한 목적으로 사용되며 인터페이스 안에 도메인 특화 언어(DSL)를 이용하여 작성합니다.

@Service
public class OrderProducer {

    private final JmsClient jmsClient;

    public OrderProducer(JmsClient jmsClient) {
        this.jmsClient = jmsClient;
    }

    public void sendOrder(String orderId) {
        jmsClient.send("queue.order")
                 .withBody("주문 ID = " + orderId);
    }
}

@Service
public class OrderReceiver {

    private final JmsClient jmsClient;

    public OrderReceiver(JmsClient jmsClient) {
        this.jmsClient = jmsClient;
    }

    public String receive() {
        return jmsClient.receive("queue.order", String.class);
    }
}

[참고] 플루언트 인터페이스 패턴

[Java/디자인 패턴] 메서드 체이닝(Method Chaining), 플루언트 인터페이스(Fluent Interface), 빌더 패턴(Buil

해당 글에서는 메서드 체이닝(Method Chaining), 플루언트 인터페이스(Fluent Interface), 빌더 패턴(Builder Pattern)에 대해서 알아봅니다. 1) 메서드 체이닝(Method Chaining) 메서드 체이닝(Method Chaining)- 여러

adjh54.tistory.com

6) OpenTelemetry starter

OpenTelemetry starter

- Spring Boot 4 버전에서는 spring-boot-starter로 spring-boot-starter-opentelemetry가 추가되었습니다.

https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes

1. spring-boot-starter-opentelemetry

spring-boot-starter-opentelemetry

- OpenTelemetry(OTel)는 관측성(Observability)을 위한 표준 스펙 + 라이브러리 집합이며, 내부 동작에 대해서 관측합니다.
- 일반적으로 ‘Trace’를 생성하고 ‘Metric’을 수집합니다. 그리고 ‘Log’로 수집된 데이터를 OTLP로 전송하는 구조를 가집니다.

OpenTelemetry(OTel) 수집 대상

수집 대상	수집 정보
Trace	요청 하나가 여러 서비스/API를 거쳐가는 흐름
Metric	CPU, 메모리, 요청 수, 응답 시간 등 수치 데이터
Log	로그 (Spring에서는 아직 로그는 간접 연동 위주)

Grafana UI Trace

- 수집된 정보를 Grafana를 통해서 UI로 확인할 수 있습니다.

https://spring.io/blog/2025/11/18/opentelemetry-with-spring-boot

Grafana UI Logs 분석

2. OTLP(OpenTelemetry Protocol)

OTLP(OpenTelemetry Protocol)

- OTLP(OpenTelemetry Protocol)는 OpenTelemetry에서 정의한 표준 텔레메트리 전송 프로토콜입니다.
- 이는 애플리케이션에서 수집한 관측 데이터(Observability data)를 외부 시스템으로 일관된 방식으로 전달하기 위해 만들어졌습니다.
- 수집한 관측 데이터를 Jaeger, Tempo, Prometheus, Datadog, New Relic로 전송을 합니다.

Spring Boot 내에서 전송을 하는 경우 OpenTelemetry Collector를 통해서 각각의 값을 OTLP을 통해서 전송을 합니다

- Metric, Trace, Logs를 각각에 맞게 수집이 되고 Grafana를 통해서 시각화를 수행합니다.

https://dev.to/siisee11/grafana-opentelemetry-starter-df4

오늘도 감사합니다.

[Opensource] Gitleaks 이해하고 활용하기 -1 : homebrew를 이용한 간단 스캔 방법

adjh54 — Mon, 19 Jan 2026 20:00:30 +0900

해당 글에서는 OpenSouce 중 Gitleaks를 이해하고 이를 이용하여 민감정보를 찾는 간단한 스캔방법에 대해 알아봅니다

1) Gitleaks

Gitleaks

- Git 저장소(Repository) 내에 포함된 민감 정보(API Key, 비밀번호, 토큰, 인증서, 개인키 등)를 탐지하는 보안 도구를 의미합니다. 민감정보를 탐지하여 실수로 소스코드 내에 커밋이 된 내용들을 빠르게 찾아낼 수 있습니다.

- 특히, 이미 원격 저장소 내에 Commit & Push 작업을 수행하면 저장소 내에 이력으로 모든 기록이 남기 때문에, 잘못 올린 한 번 잘못 올린 민감정보는 파일을 삭제하더라도 히스토리에 남아있습니다.
- 그렇기에, 원격 저장소 내에 민감정보를 올리지 않도록 해야 합니다.

    ○
    │╲
    │ ○
    ○ ░
    ░    gitleaks

GitHub - gitleaks/gitleaks: Find secrets with Gitleaks

Find secrets with Gitleaks . Contribute to gitleaks/gitleaks development by creating an account on GitHub.

github.com

[참고] 아래와 같이 Commit & Push로 원격 저장소에 올라간 파일을 삭제하더라도, Git 히스토리 내에서는 민감정보가 남아있습니다.

[참고] 이전에 원격 저장소에 Commit & Push 된 히스토리를 삭제하는 방법은 아래를 이용하여서 제거하였습니다

[Github] 원격 저장소의 Commit 내용 지우기 : API 키 노출 시 해결 방법

해당 글에서는 public Repository 내에 민감한 API 키가 올라간 경우 해당 내용을 없애는 방법에 대해 확인해 봅니다.1) API 키 노출 상황 1. GitGuardian - OpenAI API Key exposed on GitHub 문제 상황- GitGuardian으

adjh54.tistory.com

1. 사용 목적

사용 목적

- Gitleak을 사용하는 목적은 아래와 같은 문제점을 사전에 방지할 수 있습니다.

문제점	Gitleak 해결 방법
개발자가 실수로 키 커밋	커밋 전에 자동 탐지하여 push 차단할 수 있습니다.
이미 히스토리에 포함된 키	전체 Repo 스캔하여 위치 표시가 됩니다.
팀원들이 기준 없이 비밀정보 관리	.gitleaks.toml 규칙으로 일관된 정책 유지할 수 있습니다.
CI/CD에서 Secret 유출 위험	GitHub Actions/GitLab CI에서 자동 검증을 수행 할 수 있습니다.

[더 알아보기]

커밋 전에 자동 탐지를 해서 push 자체를 차단한다는 게 뭘까?

- 커밋 전에 사전에 자동으로 탐지하여 commit, push 자체를 차단하는 pre-commit, pre-push 작업을 수행할 수 있습니다.

1. pre-commit
- 커밋(commit) 직전에 실행이 됩니다. 스테이지 된 파일의 경우 커밋을 실패하는 경우 커밋을 수행하지 못하게 막습니다.
ex) 코드 포맷팅, lint, 테스트, Gitleaks 검사 등에 사용이 됩니다.

2. pre-push
- 푸시(push) 직전에 실행이 됩니다. 로컬 저장소에서 원격 저장소로 파일을 올리는 push 과정에서 푸시 자체를 수행하지 못하게 막습니다.
ex) 민감 정보가 있는 커밋을 원격으로 올리는 것을 방지하고 싶은 경우에 사용이 됩니다.

- 결론적으로, 사전에 정의해 둔 Git Hook을 통해서 각각의 단계를 감지하여서 사전 검증을 수행하는 방식으로 진행을 합니다.

https://azure.github.io/AKS-DevSecOps-Workshop/modules/Module2/Lab-2c.html

[더 알아보기]

pre-commit과 pre-push 과정은 언제 발생하는 것일까?

- Git Hook 과정에서 수행이 됩니다. Git이 내부적으로 이미 준비해 둔 특정 타이밍에 해당되는 스크립트로 pre-commit과 pre-push를 감지하여서 수행이 됩니다.
- .git 내에 hook 파일을 구성하여서 hook을 구성할 수 있습니다.

Git - Git Hooks

여기서 한가지 알아둘 점은 저장소를 Clone 해도 클라이언트 훅은 복사되지 않는다는 점이다. 만든 정책이 반드시 적용되도록 하려면 서버 훅을 이용해야만 하며 작성은 정책 구현하기 부분을 참

git-scm.com

2. 탐지 대상

탐지 대상

- 기본적으로 Gitleaks에서 탐지하는 ‘민감정보’ 대상입니다. 이뿐만 아니라 gitleaks의 toml을 이용하여서 특정 패턴, 특정 민감 정보, 규칙을 정의하여서 추가적 탐지 및 제외가 가능합니다.

항목	설명
AWS Access Key / Secret Key	AWS 계정에 접근하기 위한 인증 키. Secret Key가 유출되면 S3, EC2, RDS 등 전체 리소스가 탈취되거나 삭제될 수 있음.
GitHub Personal Access Token(PAT)	GitHub API 사용 및 private repo 접근을 위한 인증 토큰. 유출되면 코드 유출, 저장소 삭제, 악성코드 삽입 가능.
Database URL & Password	DB 접속 주소, 계정, 비밀번호. 유출되면 데이터 조회·변조·삭제 가능. 개인정보 포함 DB일수록 위험 증가.
OAuth Token (Google, Kakao, Naver 등)	외부 서비스 계정을 대신 사용하도록 허용하는 토큰. 악용 시 사용자 정보 조회, API 사용료 폭증 위험.
Private Key (id_rsa 등)	SSH 접속용 개인키. 유출되면 서버에 직접 로그인 가능. 비밀번호보다 훨씬 위험.
JWT Secret / Signing Key	JWT 서명에 사용되는 비밀 값. 유출되면 공격자가 임의의 JWT 생성 가능 → 모든 인증 우회 가능.
Slack Webhook URL	Slack 특정 채널에 메시지를 보낼 수 있는 URL. 유출되면 스팸/피싱 메시지 자동 발송에 악용됨.
사용자 정의 정규식 기반 Secret (Custom Regex)	기업/프로젝트마다 특정 패턴으로 생성되는 고유 키들(API Key, 내부 인증 토큰 등). 유출 시 시스템 전체가 위험해질 수 있음.

[ 더 알아보기 ]

Gitleaks Configuration File(=toml)

- Gitleaks가 “어떤 정보를 어떻게 탐지할지 정의하는 규칙 파일”입니다.
- 즉, Gitleaks의 탐지 엔진을 직접 커스터마이징 하는 설정 파일을 의미합니다.

title = "프로젝트에 맞는 Gitleaks 설정"

[[rules]]         # 탐지 규칙(여러 개 가능): API Key, Token, Password 패턴 정의
[allowlist]       # 제외 규칙: 특정 파일, 경로, 문자열 무시
[whitelist]       # 제외할 파일/폴더/정규식
[global]          # 전체 글로벌 설정

2) Gitleaks 설치 및 활용 -1: homebrew

1. 로컬 설치

로컬 설치

- MacOS 내에서 homebrew를 이용하여서 간단하게 설치를 합니다.

gitleaks

Homebrew’s package index

formulae.brew.sh

3) Gitleak 스캔

Gitleak 스캔

- Git 저장소 또는 로컬 파일들 안에 있는 민감정보(Secrets)를 자동으로 탐지하는 보안 스캐너를 의미합니다. 이를 통해서 API Key, Password, Token, Private Key, 인증 정보가 실수로 커밋되었을 때에 대한 탐지를 수행합니다.

항목	현재 브랜치 내 소스코만 스캔 방식	모든 히스토리 포함 방식
현재 디렉토리의 모든 파일	스캔	스캔
서브폴더 모든 파일	스캔	스캔
.git 내부(소스 히스토리)	스캔 안 함	스캔
과거 커밋(전체 history)	스캔 안 함	스캔
stash	스캔 안 함	스캔 안 함
submodule	스캔	스캔
LFS	파일 자체는 스캔(단, 히스토리 X)	스캔

1. 현재 브랜치 내 소스코만 스캔(Git Commit & Push 이력 제외)

현재 브랜치 내 소스코만 스캔(Git Commit & Push 이력 제외)

- 현재 디렉터리 전체를 스캔하지만, Git 히스토리(과거 커밋 기록)는 완전히 무시하고 현재 파일만 검사합니다.

항목 스캔	범위
현재 디렉토리의 모든 파일	스캔
서브폴더 모든 파일	스캔
.git 내부(소스 히스토리)	스캔 안 함
과거 커밋(전체 history)	스캔 안 함
stash	스캔 안 함
submodule	스캔
LFS	스캔

# 현재 브랜치 내 소스코만 스캔(Git Commit & Push 이력 제외)
$ gitleaks detect --source . --no-git

[ 더 알아보기 ]

Git history가 뭘까
- 과거에 Commit & Push 한 기록들 전체를 의미합니다.

2. 전체 스캔(Git Commit & Push 이력 포함)

전체 스캔(Git Commit & Push 이력 포함)

- 현재 디렉터리 전체 파일을 스캔합니다. 즉, 프로젝트 루트(.) 안에 모든 파일을 확인하고 수행합니다.
- 숨김파일도 포함하여서 스캔을 합니다.

항목	스캔 여부
현재 디렉토리의 모든 파일	스캔
서브폴더 모든 파일	스캔
.git 내부(소스 히스토리)	스캔
과거 커밋(전체 history)	스캔
stash	스캔 안 함
submodule	스캔
LFS	스캔

# 전체 스캔
$ gitleaks detect --source .

[ 더 알아보기 ]

git 히스토리를 포함하지 않은 게 포함한 것보다 많이 나왔는데 왜 그럴까?

- gitignore로 인해 git 히스토리에는 포함하지 않지만 로컬에는 포함하는 경우에 이에 해당이 될 수 있습니다.

3. 전체 스캔 결과 JSON 파일로 저장

전체 스캔 결과 JSON 파일로 저장

- Commit & Push에 대한 Git 이력을 gitleaks-report.json 파일로 루트 경로에 저장을 합니다.

# 현재 브랜치 내 소스코만 스캔(Git Commit & Push 이력 제외) 결과를 gitleaks-report.json 파일로 루트 경로에 저장
$ gitleaks detect --source . --no-git --report-path gitleaks-report.json

# 전체 스캔(Git Commit & Push 이력 포함) 결과를 gitleaks-report.json 파일로 루트 경로에 저장
$ gitleaks detect --source . --report-path gitleaks-report.json

3.1. 전체 스캔 결과 및 JSON 파일 확인

전체 스캔 결과 및 JSON 파일 확인

- 루트 경로에 스캔 정보를 확인할 수 있고, 리포트를 json으로 받아볼 수 있게끔 명령어를 실행하였고, 프로젝트의 루트 경로에 gitleaks-report.json 파일이 생성이 됩니다.

3.2. JSON 파일 확인

JSON 파일 확인

- json 파일을 확인하였을 때 아래와 같이 민감정보에 해당하는 정보들이 탐지가 되었습니다.

오늘도 감사합니다.

[Java] Spring Cloud Vault 이해하고 활용하기 -4 : Database Secret Engine 활용

adjh54 — Tue, 13 Jan 2026 14:09:19 +0900

해당 글에서는 Spring Cloud Vault를 활용하여서 Database Secret Engine을 이용하는 방법에 대해 알아봅니다.

[참고] Vault에 대해 궁금하시면 아래의 글을 참고하시면 도움이 됩니다.

분류	URI
[OpenSource] Vault 이해하기 -1 : 이론, 구성요소, 처리과정	https://adjh54.tistory.com/475
[Docker] Dockerfile을 이용한 Vault 배포 환경 구성 및 실행방법	https://adjh54.tistory.com/415
[Java] Spring Cloud Vault 이해하고 활용하기-1 : 초기 환경, KV 구성 및 Root Token 인증 방식	https://adjh54.tistory.com/728
[Java] Spring Cloud Vault 이해하고 활용하기-2 : 정책 기반 토큰 발급 및 인증 방식	https://adjh54.tistory.com/729
[Java] Spring Cloud Vault 이해하고 활용하기-3 : AppRole 인증방식	https://adjh54.tistory.com/731
[Java] Spring Cloud Vault 이해하고 활용하기-4 : Database Secret Engine 활용	https://adjh54.tistory.com/732
소스코드 Repository	https://github.com/adjh54ir/blog-codes/tree/main/spring-boot3-vault

1) Vault

Vault

- HashCorp 사에서 만든 Vault는 다양한 환경에서 애플리케이션의 외부 비밀 속성(예: 데이터베이스 비밀번호, API 키 등)을 외부화된 구성으로 중앙에서 관리할 수 있습니다.
- Spring Boot 환경에서 Vault로부터 시크릿 정보를 읽어오며 Valut에 시크릿 정보를 쓰는 것도 가능합니다. 이러한 방식으로 애플리케이션의 중요한 정보는 코드에서 분리되어 보안이 보장됩니다.
- 기밀정보의 동적인 제공, 중앙 집중식 시크릿 관리, 즉각적인 액세스 제어, 감사 추적 기능 등을 제공하여, 기업의 보안 정책을 준수하는 데 도움이 됩니다.

1. Vault의 특징

특징	설명
기밀정보의 동적 제공	애플리케이션이 필요에 따라 비밀정보를 요청하고, Vault는 요청된 정보를 제공합니다.
중앙 집중식 시크릿 관리	모든 애플리케이션의 시크릿 정보를 중앙에서 관리할 수 있습니다.
즉각적인 액세스 제어	애플리케이션이 Vault에 접근 할 수 있는 ‘특정 토큰 아이디’를 기반으로 Vault 서비스를 호출하고, Vault는 해당 '특정 토큰 아이디'를 수신한 뒤 요청된 '비밀정보'를 제공합니다.
감사 추적 기능	Vault는 모든 액세스 요청을 로깅하여 감사를 위한 추적이 가능합니다.

2. Vault 인증 방식

Vault 인증 방식

- Vault에 접근하기 위한 인증 방식을 의미합니다. Root Token, 정책 기반 토큰 (Policy-based Token), AppRole 등의 인증 방식을 통해서 Vault를 접근합니다.

인증 방식	설명
Root Token	모든 권한을 가진 ‘루트 권한 토큰’을 이용하는 인증 방식이며, 정책, 인증 방식, 시크릿 엔진, 모든 데이터 접근 가능한 인증 방식입니다. 절대적인 권한을 가지고 있기에, 직접적으로 애플리케이션 레벨에서 인증방식으로 사용되지 않습니다.
정책 기반 토큰 (Policy-based Token)	정책(policy)에 의해 접근 범위가 제한된 ‘토큰’을 이용하는 인증 방식이며, 정책 범위 별로 강제 제한된 권한을 부여하고 접근하는 인증방식 입니다.
AppRole	Role 별로 지정된 정책(Policy)에 따라서 접근 범위가 제한되며, ‘RoleID, Secret ID’에 따라 ‘토큰’을 발급받아서 접근 가능한 인증 방식입니다. 해당 Role은 운영환경 혹은 팀별로 접근을 제어할 수 있으며, 사용자는 Role Id, Secret Id를 통해 인증만 수행하고, 이후 토큰에 대해서는 머신이 이를 갱신/관리하기에 별도의 Token 재발급 과정을 수행하지 않습니다.

3. Vault 수행 과정

https://www.baeldung.com/spring-boot-3-1-connectiondetails-abstraction

Vault 수행 과정

1. Spring Boot → Hashicorp Vault: Secret Request(비밀정보 요청)
- Spring Boot 애플리케이션에서는 서버를 실행할 때, Valut에 접근할 수 있는 ‘특정 토큰 아이디’(Secret Request)’ 를 기반으로 Vault 서비스를 호출하여 ‘비밀 정보(Secret)’를 검색합니다.

2. Hashicorp Vault → Spring Boot: Secret Response(비밀정보 응답)
- Valut 서비스는 Spring Boot 애플리케이션의 ‘특정 토큰 아이디’(Secret Request)’를 수신하고 요청된 ‘비밀 정보(Secret)’를 전달합니다.
- 이 단계를 통해서 애플리케이션은 필요한 시크릿 정보를 안전하게 받아올 수 있습니다.

3. Spring Boot → Remote Service : Connection Request(커넥션 요청)
- Spring Boot 애플리케이션이 원격 서비스와 연결을 시도하는 과정을 의미합니다.
- 이 단계에서 애플리케이션은 Vault에서 안전하게 가져온 비밀 정보(예: 데이터베이스 비밀번호, API 키 등)를 사용하여 원격 서비스에 연결 요청을 보냅니다.
- 이렇게 함으로써, 중요한 정보를 코드 내에 직접 작성하거나 노출시키지 않아도 되어 보안을 더 효과적으로 관리할 수 있습니다.

4. Remote Service → Spring Boot : Connection Response(커넥션 연결)
- Vault 서비스가 Spring Boot 애플리케이션의 Secret Request를 수신하고, 요청된 '비밀 정보'를 애플리케이션으로 전송하는 단계입니다.
- 이 단계를 통해 애플리케이션은 필요한 시크릿 정보를 안전하게 받아올 수 있습니다.

2) Database Secret Engine

Database Secret Engine

- Database Secret Engine은 Vault가 DB 관리자 권한으로 접속하여 Role에 정의된 SQL 정책을 기반으로 요청 시마다 TTL(Time To Live)이 있는 임시 DB 계정을 생성하고, 만료 시 자동으로 폐기하는 동적 자격 증명 시스템을 의미합니다.
- Vault는 데이터베이스에 관리자 권한을 가진 계정으로 접속하여 Role에 정의된 SQL 정책에 따라 사용자 생성 및 권한을 부여하며, TTL 만료 시 해당 계정을 자동으로 폐기한다.

1. 설정 과정

설정 과정

1. Vaul내에 'DB 관리자 계정 설정'합니다.
- Vault 내에서 '데이터베이스 관리자 계정(Admin)'을 설정합니다.
- 해당 설정 과정을 통해서 추후에 관리자 계정을 통하여 Vault에서 동적인 임의의 계정을 생성하는 데 사용됩니다.

2. Vault에 'DB Role'을 생성하고 정의합니다.
- Vault 내에서 '데이터베이스 접근 권한(Role)'을 설정합니다.
- 이 접근 권한 과정에서 특정 권한에 대해 읽기만(read-only) 혹은 쓰기(Write) 권한 등.. 생성되는 사용자에 대한 데이터베이스 권한에 대해 제한을 둘 수 있습니다.

3. 클라이언트에서는 Vault로 자격증명(credential) 요청합니다.
- 클라이언트(애플리케이션)에서 Vault 접속을 위한 자격증명을 수행을 합니다.
- 클라이언트는 Vault로 접속을 하기 위해 사전에 구현된 인증 방식(Policy Token, AppRole)을 통해 인증을 수행합니다.

4. Vault에서 DB 사용자 생성합니다.
- 자격 증명이 성공하면, Vault는 Role에 맞는 권한 및 TTL(Time To Live)을 가진 DB 사용자를 생성합니다.

5. Vault가 관리자 권한으로 DB에 접속합니다.
- 생성된 동적인 사용자 정보(username, password)를 기반으로 데이터베이스에 접속을 합니다.

7. TTL 만료 시 자동 폐기
- 지정된 시간이 지난 애플리케이션의 사용자를 DB 접속 계정을 자동 폐기합니다.

Database secrets engine | Vault | HashiCorp Developer

Dynamically generate database credentials based on configured roles with the database secrets engine through a plugin interface to a number of different databases.

developer.hashicorp.com

2. Spring Boot AppRole + KV + Database Secret Engine 수행과정

Spring Boot AppRole + KV + Database Secret Engine 수행과정

1. Spring Boot 서버 실행
- 실행 시 시스템 변수로 주요 키 값을 전달합니다.(ROLE_ID, SECRET_ID)

2. bootstrap.yml
- 서버 실행 시 가장 먼저 실행이 되며, 파일 내에 구성된 Vault 접속정보를 기반으로 인증 방식 중 AppRole을 통해서 Vault에 접근을 수행합니다.

3. Vault → Vault KV Secret Engine
- 접속 정보를 기반으로 각각에 접속을 하여서 데이터를 반환받습니다.

4. Vault → Vault Database Secret Engine
- 접속 정보를 기반으로 각각에 접속을 하여서 데이터를 반환받습니다.

5. Vault에서 반환받은 데이터는 시스템 환경 변수로 전달을 받습니다.

6. Vault KV 내에서 조회된 값은 @ConfigurationProperties를 통해서 매핑하여 객체로 주입됩니다.

7. Vault Database 내에 조회된 값은 @ConfigurationProperties를 통해서 매핑하여 객체로 주입됩니다.

8. DBConfig 내에서는 ValutKVProperties가 호출되고, KV 값 중 주요 DB 접속 정보(DB url, port, name)를 가져와서 JDBC URL을 세팅합니다

9. DBConfig 내에서는 ValutDBProperties가 호출되고, Database에서 동적으로 발급된 자격증명(username, password)을 가져와서 DB에 Connection을 시도합니다

10. 데이터베이스가 연결이 됩니다.

11. 서버 실행이 완료됩니다.

3) 환경설정 -1: 로컬 데이터베이스 설정 및 권한 확인

환경설정 -1: 로컬 데이터베이스 설정 및 권한 확인

- 연결을 위한 로컬 데이터베이스 구성을 확인하고 관리자 계정이 확인되어야 합니다.

[참고] 아래의 글에서 로컬 데이터베이스를 이용하는 방법을 이용하였습니다.

[DB] MacOS에서 PostgreSQL 로컬 데이터베이스 구성 방법

해당 글에서는 PostgreSQL을 로컬 디비로 구성하는 방법에 대해서 공유합니다. 1) PostgreSQL을 설치합니다. PostgreSQL의 버전을 확인하고 설치가 안 되어 있다면 설치를 하고 서비스를 수행합니다.#

adjh54.tistory.com

1. 아래와 같이 로컬 데이터베이스에 접속하고, 접속 정보를 아는 상태입니다.

2. PostgreSQL에서 관리자 권한인지 여부를 확인합니다

PostgreSQL에서 관리자 권한인지 여부를 확인합니다

- 생성한 사용자의 권한이 얼마나 되는지 확인을 합니다.

아래와 같이 권한을 부여하였습니다.

아래와 같은 권한으로 검색이 되었습니다.

- 기본적으로 아래의 권한이 허용되는 유저입니다.

1. 새 데이터베이스 생성
2. 새 사용자(Role) 생성
3. 다른 사용자에게 권한 부여
4. 복제 스트림 사용
5. 애플리케이션 DB 운영 대부분 수행

SELECT
    rolname,
    rolsuper,
    rolcreatedb,
    rolcreaterole,
    rolcanlogin,
    rolreplication,
    rolbypassrls
FROM pg_roles
WHERE rolname = 'localmaster'

   rolname   | rolsuper | rolcreatedb | rolcreaterole | rolcanlogin | rolreplication | rolbypassrls
-------------+----------+-------------+---------------+-------------+----------------+--------------
 localmaster | f        | t           | t             | t           | t              | f

3) 환경설정 : 사이트 내에서 Secrets Engine 설정

1. Secrets engines - Enable new engine 버튼을 누릅니다.

Secrets engines - Enable new engine 버튼을 누릅니다.

2. 'Database'를 선택합니다

3. 기본 옵션으로 선택하고 'Enable engine'버튼을 선택합니다.

[참고] 위에 과정을 GUI에서는 아래의 명령어로 수행이 가능합니다.

$ vault secrets enable database
Success! Enabled the database secrets engine at: database/

4. 생성된 database를 선택하고 'Connections' 탭에서 'Create connection'을 선택합니다.

5. 아래와 같이 설정하였습니다.

[참고] 'host.docker.internal'의 경우는 Docker 컨테이너 안에서 "호스트 PC(내 컴퓨터)"에 접근하기 위한 전용 호스트명으로 지정을 하였습니다.

분류 값	선택 및 입력	설명
Database plugin	PostgreSQL	설정하려는 데이터베이스 종류를 선택합니다
Connection name	app-db	설정 커넥션 명을 입력합니다.
Connection URL	postgresql://{{username}}:{{password}}@host.docker.internal:5432/testdb	데이터베이스 접속 경로이며, 동적으로 username과 password는 생성하기에 변수로 설정합니다.
Username	localmaster	Admin 계정의 아이디를 입력합니다.
Password	qwer1234	Admin 계정의 비밀번호를 입력합니다.

6. 'Rotate and enable'을 선택합니다

'Rotate and enable'을 선택합니다

- 이를 통해서 동적인 사용자를 구성하도록 선택하였습니다.

4) 환경설정 : 사이트 내에서 Role 설정

1. Role 탭을 선택하고 'Create Role' 버튼을 선택합니다

2. Role name, Connection name, Type of role을 ‘dynamic’으로 입력 혹은 선택하고 완료합니다.

3. 아래와 같이 구성을 완료하였습니다.

5) 환경설정 : AppRole 인증 방식 설정

환경설정 : AppRole ID 발급

- Vault 인증 방식 중 AppRole 방식을 이용하여서 구성을 합니다.

이전에 작성한 아래의 글을 기반으로 구성하였습니다.

[Java] Spring Cloud Vault 이해하고 활용하기 -3 : AppRole 인증방식

해당 글에서는 Vault의 인증 방식 중 ‘AppRole’ 인증방식을 이해하고 설정하는 방법에 대해 알아봅니다. [참고] 이전에 작성한 글들을 확인하고 오시면 큰 도움이 됩니다.분류URI[Java] Spring Cloud

adjh54.tistory.com

1. 기존 AppRole의 Policy를 수정합니다

기존 AppRole의 Policy를 수정합니다

- 아래와 같이 기존 AppRole에 대한 ACL Policy는 아래와 같았습니다.
- 이는 KV라는 데이터에만 접근을 할 수 있는 권한이었고, 이제 Database Secret Engine에 접근이 가능한 정책을 추가합니다.

1.1. ACL Policy 수정 이전

ACL Policy 수정 이전

- 아래와 같이 기존 AppRole에 대한 ACL Policy는 아래와 같았습니다. 이는 KV라는 데이터에만 접근을 할 수 있는 권한이었고, 이제 Database Secret Engine에 접근이 가능한 권한을 추가합니다.

path "kv2/data/*" {
  capabilities = ["read", "list"]
}

1.2. ACL Policy 수정 이후

ACL Policy 수정 이후

- 아래와 같이 각각에 추가 권한들을 추가해 주고, 중요한 Database Dynamic Credentials 부분을 추가합니다.

# ===============================
#   AppRole 로그인 권한
# ===============================

# AppRole 방식으로 로그인하기 위해 반드시 필요
# Spring Boot / CLI / Agent가 role_id + secret_id로 토큰을 발급받을 때 사용
path "auth/approle/login" {
  capabilities = ["create"]   # 로그인 요청은 create 권한
}

# ===============================
#   KV v2 (필수)
# ===============================

# ✅ loc 경로 자체에 대한 접근
# Spring Cloud Vault는 먼저 "루트 경로"를 조회함
path "kv2/data/loc" {
  capabilities = ["read"]
}

# loc 메타데이터 조회 권한
path "kv2/metadata/loc" {
  capabilities = ["list"]
}

# ===============================
#   loc 하위 Secret 접근
# ===============================

# 실제 애플리케이션 설정 값 접근
# 예: kv2/loc/db_url, kv2/loc/db_name 등
path "kv2/data/loc/*" {
  capabilities = ["read"]
}

# 하위 secret 목록 조회
# 일부 Vault 클라이언트/라이브러리에서 필요
path "kv2/metadata/loc/*" {
  capabilities = ["list"]
}

# ===============================
#   Database Dynamic Credentials
# ===============================

# database secret engine에서
# testRole 기반 동적 DB 계정 발급 권한
#
# 이 경로가 없으면:
path "database/creds/testRole" {
  capabilities = ["read"]
}

# ===============================
#   Token Self Management
# ===============================

# 현재 토큰 정보 조회
# Spring Cloud Vault가 토큰 TTL, renewable 여부 확인 시 사용
path "auth/token/lookup-self" {
  capabilities = ["read"]
}

# 토큰 갱신 권한
# renewable 토큰일 경우 TTL 자동 연장 가능
path "auth/token/renew-self" {
  capabilities = ["update"]
}

# 자기 자신 토큰 폐기 권한
# 정상 종료 시 Vault Agent / App에서 토큰 정리 가능
path "auth/token/revoke-self" {
  capabilities = ["update"]
}

# 현재 토큰이 어떤 권한을 갖고 있는지 확인
# Spring Cloud Vault 내부 검증용
path "sys/capabilities-self" {
  capabilities = ["update"]
}

2. 터미널에서 생성한 approle, ACL Policy를 기반으로 Role ID를 생성합니다.

vault write auth/approle/role/approle \
  policies="dev-approle-policy" \
  token_type=batch \
  secret_id_ttl=24h \
  secret_id_num_uses=0 \
  token_ttl=1h \
  token_max_ttl=24h

아래의 접속 경로를 통해서 ‘approle’를 확인하였습니다.

아래의 ‘ACL Policyes’ 부분에서 지정한 policy를 선택하였습니다.

[참고] 생성한 Role에 대한 조회를 하는 방법은 아래와 같습니다

vault read auth/approle/role/approle

3. Role ID를 조회합니다.

vault read auth/approle/role/approle/role-id

4. Secret ID를 발급합니다

$ vault write -f auth/approle/role/approle/secret-id

6) Spring Boot 환경 구성

1. 개발 환경

개발 환경

- 기본 기능과 주요 라이브러리인 spring-cloud-dependencies, spring-cloud-starter-bootstrap, spring-cloud-starter-vault-config, spring-cloud-vault-config-databases를 설정하였습니다.
- 추가로 데이터베이스 연결을 위해 PostgreSQL Driver, JDBC, MyBatis를 추가하였습니다.

개발 환경	분류	버전
Java JDK	Java Version	17
빌드 도구	Gradle	8.14.3
Spring Boot	Spring Boot Starter	3.5.8
Spring Boot Web	Spring Boot Starter	3.5.8
spring-boot-starter-jdbc	Spring Boot Starter	3.5.8
spring-cloud-starter-bootstrap	Spring Cloud	2025.0.0
spring-cloud-starter-vault-config	Spring Cloud	2025.0.0
spring-cloud-vault-config-databases	Spring Cloud	2025.0.0
spring-cloud-dependencies	Spring Cloud	2025.0.0
Lombok	Library	latest
org.postgresql:postgresql	Library	42.7.8
org.mybatis.spring.boot:mybatis-spring-boot-starter	Library	3.0.5

2. 라이브러리 설치 : build.gradle

라이브러리 설치 : build.gradle

- 위에서 명시한 라이브러리를 Gradle을 이용하여서 설치합니다.

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.5.8'
    id 'io.spring.dependency-management' version '1.1.7'
}
ext {
    springCloudVersion = "2025.0.0"
}

group = 'com.adjh'
version = '0.0.1-SNAPSHOT'
description = 'spring-boot3-vault'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

dependencies {

    // [Spring Boot Starter]
    implementation 'org.springframework.boot:spring-boot-starter-web'               // Spring Boot Web
    implementation 'org.springframework.boot:spring-boot-starter-web'               // Spring Boot Web
    implementation "org.springframework.boot:spring-boot-starter-jdbc"              // Spring Boot JDBC

    // [Spring Cloud]
    implementation 'org.springframework.cloud:spring-cloud-starter-bootstrap'       // Spring Cloud BootStrap
    implementation 'org.springframework.cloud:spring-cloud-starter-vault-config'    // Spring Cloud Vault
    implementation 'org.springframework.cloud:spring-cloud-vault-config-databases'  // Spring Cloud Vault Database

    // [Library]
    implementation("org.postgresql:postgresql:42.7.8")                              // PostgresSQL
    implementation 'org.mybatis.spring.boot:mybatis-spring-boot-starter:3.0.5'      // Mybatis

    compileOnly 'org.projectlombok:lombok'                                          // Lombok Compile
    annotationProcessor 'org.projectlombok:lombok'                                  // Lombok Annotation
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}
dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:$springCloudVersion"
    }
}

tasks.named('test') {
    useJUnitPlatform()
}

3. 시스템 환경변수 주입 : IntelliJ IDE 활용

시스템 환경변수 주입 : IntelliJ IDE 활용

- Vault로 전달이 되는 Main Key 자체를 프로젝트 내에 넣고 Git에 올릴 수 없기에 ‘시스템 환경 변수’ 내에 추가합니다.

[참고] 아래의 환경 변수를 추가하는 방법의 글을 참고하셔도 도움이 됩니다.

[Java] Spring Boot 환경에서 시스템 변수 .env 파일 지정 및 활용 방법

adjh54.tistory.com

[Java] Spring Cloud Vault 이해하고 활용하기-1 : 초기 환경, KV 구성 및 Root Token 인증 방식

해당 글에서는 Spring Cloud Vault를 이해하고 Vault를 구성하고 KV Secret Engine 내에서 데이터를 조회하는 토큰 인증방식을 이용하는 방법에 대해 알아봅니다 1) Vault Vault- HashCorp 사에서 만든 Vault는

adjh54.tistory.com

4. bootstrap.yml 파일을 생성 및 구성합니다.

bootstrap.yml 파일을 생성 및 구성합니다.

- resources 경로 하단에 bootstrap.yml 파일을 생성하였습니다

yml 파일을 아래와 같이 구성하였습니다.

- 사전 단계에서 발급받은 VAULT_APP_ROLE_ID, VAULT_APP_ROLE_SECRET 값을 환경 변수로 추가하였고 이를 불러옵니다.
- 기존의 KV Engine의 경우는 이전과 동일한 구성입니다.
- 이번 과정에서는 ‘Vault Database Engine 접속 정보’ 부분이 추가되었습니다.
- 해당 내용은 아래와 같습니다.

속성	설명
vault.database.enabled	Vault Database Secret Engine 사용 여부 (DB 계정을 Vault에서 동적으로 발급받아 사용)
vault.database.role	Vault에서 DB 계정을 생성할 때 사용할 Database Role 이름
vault.database.backend	Vault에 Database Secret Engine이 마운트된 경로
username-property	Vault 응답에서 DB 사용자명으로 사용할 필드 이름
password-property	Vault 응답에서 DB 비밀번호로 사용할 필드 이름

server:
  port: 8000
spring:
  cloud:
    vault:
      uri: <http://localhost:8200>
      # 인증방식 : APPID, APPROLE, AWS_EC2, AWS_IAM, AZURE_MSI, CERT, CUBBYHOLE, GCP_GCE, GCP_IAM, KUBERNETES, NONE, PCF, TOKEN;
      authentication: APPROLE                           # Vault 인증 방식 (TOKEN, APPROLE, APPID 등)
      connection-timeout: 5000                          # Vault 서버 연결 시도 타임아웃(ms)
      read-timeout: 1000                                # Vault 데이터 읽기 타임아웃(ms)

      # Vault AppRole 인증 방식
      app-role:
        role-id: ${VAULT_APP_ROLE_ID}                   # 환경변수에서 Vault 접근 role-id를 불러옴
        secret-id: ${VAULT_APP_ROLE_SECRET}             # 환경변수에서 Vault 접근 role-secret를 불러옴
        role: dev-approle-policy                        # 사전에 할당된 role을 불러옴

      # Vault KV Engine 접속 정보
      kv:
        enabled: true                                   # KV(키-값) 비밀 엔진 사용 여부
        backend: kv2                                    # KV Secret Engine 이름(ex: kv2)
        default-context: loc                            # 기본 Secret 경로 (예: kv2/loc/data/application 같은 구조가 됨)
        application-name: ''                            # Spring 애플리케이션 이름을 Secret 경로에 추가할지 여부

      # Vault Database Engine 접속 정보
      database:
        enabled: true                                   # Vault Database Secret Engine 사용 여부 (DB 계정을 Vault에서 동적으로 발급받아 사용)
        role: testRole                                  # Vault에서 DB 계정을 생성할 때 사용할 Database Role 이름
        backend: app-db                                 # Vault에 Database Secret Engine이 마운트된 경로
        username-property: spring.datasource.username   # Vault 응답에서 DB 사용자명으로 사용할 필드 이름
        password-property: spring.datasource.password   # Vault 응답에서 DB 비밀번호로 사용할 필드 이름
logging:
  level:
    org.springframework.cloud.vault: DEBUG

5. 서버 실행

서버 실행

- 정상적으로 오류 없이 서버가 실행하였습니다.

6. VaultKVProperties: Vault 값과 객체 매핑(KV Secret Engine)

VaultKVProperties: Vault 값과 객체 매핑(KV Secret Engine)

- Vault에서 읽어온 값을 자바 클래스 필드에 자동 바인딩을 하는 클래스입니다.

- @Getter, @Setter 통해서 멤버 변수에 접근할 수 있도록 어노테이션을 지정하였습니다.
- @Component를 빈으로 등록하여서, 다른 서비스나 컴포넌트에 주입하여 사용이 가능하도록 하였습니다.
- @ConfigurationProperties(prefix = "vault") : 상위 prefix 내에 하위에 동일한 이름으로 각각 자동 바인딩이 됩니다.

package com.adjh.springboot3vault.properties;

import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

/**
 * Vault Key-Value Properties Mapping value
 *
 * @author : leejonghoon
 * @fileName : VaultKVProperties
 * @since : 25. 11. 25.
 */
@Getter
@Setter
@Component
@ConfigurationProperties(prefix = "vault")
public class VaultKVProperties {
    private String appEnv;
    private String dbHost;
    private String dbPassword;
    private String dbUser;
    private String dbUrl;
    private String dbPort;
    private String dbName;
}

7. VaultDBProperties: Vault 값과 객체 매핑(Database Secret Engine)

VaultDBProperties: Vault 값과 객체 매핑(Database Secret Engine)

- Database Secret Engine에서 발급된 username과 password가 매핑이 됩니다.

8. DBConfig

DBConfig

- 서버가 실행이 되고 설정되는 Configuartion 파일입니다.
- 해당 페이지에서는 Vault 접속 이후 KV Secret Engine에서 조회된 값을 기반으로 주요 정보를 가져옵니다.
- 이를 토대로 JDBC URL을 연결하고 DataBase Secret Engine에서 동적으로 생성한 username, password를 기반으로 데이터베이스 연결을 수행합니다.

package com.adjh.springboot3vault.config;

import com.adjh.springboot3vault.properties.VaultDbProperties;
import com.adjh.springboot3vault.properties.VaultKVProperties;
import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import org.apache.ibatis.session.SqlSessionFactory;
import org.mybatis.spring.SqlSessionFactoryBean;
import org.mybatis.spring.SqlSessionTemplate;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.support.PathMatchingResourcePatternResolver;

import javax.sql.DataSource;

/**
 * 최초 데이터 베이스 연결 설정을 구성하는 설정 클래스입니다.
 */
@Configuration
public class DBConfig {

    private final ApplicationContext applicationContext;
    private final VaultKVProperties kvProperties;
    private final VaultDbProperties dbProperties;

    public DBConfig(ApplicationContext applicationContext, VaultKVProperties kvProperties, VaultDbProperties dbProperties) {
        this.applicationContext = applicationContext;
        this.kvProperties = kvProperties;
        this.dbProperties = dbProperties;
    }

    /**
     * DataSource 구성
     *
     * @return
     */
    @Bean
    public DataSource dataSource() {
        HikariConfig hikariConfig = new HikariConfig();

        // 1. KV Secret Engine에서 조회된 값
        System.out.println("kvProperties = " + kvProperties.getDbUrl());
        System.out.println("kvProperties = " + kvProperties.getDbPort());
        System.out.println("kvProperties = " + kvProperties.getDbName());

        // 2. KV Secret Engine 내에 조회한 속성을 조회하여 세팅함.
        // [구조예시] jdbc:postgresql://localhost:5432/testdb
        hikariConfig.setJdbcUrl(
                String.format("jdbc:postgresql://%s:%s/%s",
                        kvProperties.getDbUrl(),
                        kvProperties.getDbPort(),
                        kvProperties.getDbName())
        );
        // 3. DB Secret Engine 내에서 조회한 속성을 조회하여 HikariCP에 세팅함.(동적 사용자, 비밀번호)
        hikariConfig.setUsername(dbProperties.getUsername());
        hikariConfig.setPassword(dbProperties.getPassword());

        System.out.println("dbProperties = " + dbProperties.getUsername());
        System.out.println("dbProperties = " + dbProperties.getPassword());

        // 4. 기타 HikariCP 설정
        hikariConfig.setDriverClassName("org.postgresql.Driver");
        hikariConfig.setConnectionTimeout(10000); //커넥션 풀에서 새로운 커넥션을 가져올 때 최대 몇 ms까지 기다릴지를 설정 (단위: 밀리초)
        hikariConfig.setValidationTimeout(13000); //커넥션이 유효한지 테스트할 때 (connection.isValid()) 검증 쿼리가 완료될 때까지 기다릴 최대 시간 (단위: 밀리초)
        hikariConfig.setIdleTimeout(300000);      //풀에 있는 커넥션이 아무 작업도 하지 않고 대기(idle) 상태로 유지될 수 있는 최대 시간 (단위: 밀리초)
        hikariConfig.setMaxLifetime(600000);     // 커넥션이 생성된 후 존재할 수 있는 최대 시간 (단위: 밀리초) - 10분
        hikariConfig.setMaximumPoolSize(5);
        hikariConfig.setMinimumIdle(1);
        hikariConfig.setConnectionTestQuery("SELECT 1");
        hikariConfig.setInitializationFailTimeout(-1);
        return new HikariDataSource(hikariConfig);
    }

    /**
     * MyBatis 구성
     *
     * @param dataSource
     * @return
     * @throws Exception
     */
    @Bean
    public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception {
        SqlSessionFactoryBean session = new SqlSessionFactoryBean();
        session.setDataSource(dataSource);
        session.setMapperLocations(applicationContext.getResources("classpath:mapper/*.xml"));
        session.setTypeAliasesPackage("com.adjh.springboot3vault.model");
        session.setConfigLocation(new PathMatchingResourcePatternResolver().getResource("classpath:config/common-mybatis-config.xml"));
        return session.getObject();
    }

    @Bean
    public SqlSessionTemplate sqlSessionTemplate(SqlSessionFactory sqlSessionFactory) {
        return new SqlSessionTemplate(sqlSessionFactory);
    }

}

아래와 같이 KV Secret Engine 값과 DB Secret Engine 값이 정상적으로 불러와졌습니다.

아래와 같이 서버를 재 실행할 경우 아래와 같이 동적으로 사용자와 비밀번호가 바뀜을 확인하였습니다.

9. 데이터베이스 연결 확인

데이터베이스 연결 확인

- 첫 번째 줄에서 KV Secret Engine과 Database Secret Engine이 연결이 됨을 확인하였습니다.
- HikariCP Connection Pool이 연결이 됨을 확인하였습니다.

10. 실제 데이터베이스에 접근하여 데이터를 조회합니다.

실제 데이터베이스에 접근하여 데이터를 조회합니다.

- TB_USER 테이블 내의 사용자 정보를 가져오는 비즈니스 로직을 구성합니다.

아래와 같이 MyBatis를 통해서 SQL문을 구성했고 이를 구성하는 비즈니스 로직은 제외하였습니다.

11. Controller에 Endpoint로 호출하여서 데이터 조회를 확인합니다.

Controller에 Endpoint로 호출하여서 데이터 조회를 확인합니다

- 아래와 같은 API를 구성하였고 이를 호출합니다.

package com.adjh.springboot3vault.controller;

import com.adjh.springboot3vault.dto.UserDto;
import com.adjh.springboot3vault.service.UserService;
import lombok.RequiredArgsConstructor;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api/v1/user")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    /**
     * 사용자 PK(userSq)로 조회
     */
    @PostMapping("/{userSq}")
    public ResponseEntity<UserDto> findByUserSq(@PathVariable Long userSq) {
        UserDto userDto = userService.findByUserSq(userSq);
        return ResponseEntity.ok(userDto);
    }

    /**
     * 사용자 ID로 조회
     */
    @PostMapping("/userId")
    public ResponseEntity<UserDto> findByUserId(@RequestParam String userId) {

        UserDto userDto = userService.findByUserId(userId);
        return ResponseEntity.ok(userDto);
    }

    /**
     * 전체 사용자 조회
     */
    @GetMapping("/user")
    public ResponseEntity<List<UserDto>> findAll() {
        return ResponseEntity.ok(userService.selectUser());
    }
}

12. 실제 결과를 확인합니다

실제 결과를 확인합니다

- v1/user/user를 통해서 TB_USER 테이블 내의 모든 사용자를 조회하는 비즈니스 로직을 수행했을 때, 모두 잘 가져옴을 확인하였습니다.

[참고] SQL에서 아래와 같이 조회를 하였을 때, 연결된 사용자를 확인할 수도 있습니다

SELECT * FROM pg_stat_activity;

[참고] 아래와 같이 Configuration 파일을 통해서 Datasouce로 연결된 사용자를 확인할 수도 있습니다.

package com.adjh.springboot3vault.config;

import org.springframework.boot.ApplicationRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import javax.sql.DataSource;
import java.sql.Connection;

@Configuration
public class VaultDebugRunner {

    @Bean
    public ApplicationRunner vaultDbUserRunner(DataSource dataSource) {
        return args -> {
            try (Connection conn = dataSource.getConnection()) {
                System.out.println("REAL USER = " + conn.getMetaData().getUserName());
                System.out.println("REAL URL = " + conn.getMetaData().getURL());
            }
        };
    }
}

[참고] 해당 코드는 아래의 Repository 내에서 확인이 가능합니다.

blog-codes/spring-boot3-vault at main · adjh54ir/blog-codes

Contributor9 티스토리 블로그 내에서 활용한 내용들을 담은 레포지토리입니다. Contribute to adjh54ir/blog-codes development by creating an account on GitHub.

github.com

오늘도 감사합니다.

[Java] Spring Cloud Vault 이해하고 활용하기 -3 : AppRole 인증방식

adjh54 — Tue, 6 Jan 2026 20:00:50 +0900

해당 글에서는 Vault의 인증 방식 중 ‘AppRole’ 인증방식을 이해하고 설정하는 방법에 대해 알아봅니다.

[참고] 이전에 작성한 글들을 확인하고 오시면 큰 도움이 됩니다.

분류	URI
[Java] Spring Cloud Vault 이해하고 활용하기-1 : 초기 환경, KV 구성 및 Root Token 인증 방식	https://adjh54.tistory.com/728
[Java] Spring Cloud Vault 이해하고 활용하기-2 : 정책 기반 토큰 발급 및 인증 방식	https://adjh54.tistory.com/729

1) Vault

Vault
- HashCorp 사에서 만든 Vault는 다양한 환경에서 애플리케이션의 외부 비밀 속성(예: 데이터베이스 비밀번호, API 키 등)을 외부화된 구성으로 중앙에서 관리할 수 있습니다.

- Spring Boot 환경에서 Vault로부터 시크릿 정보를 읽어오며 Valut에 시크릿 정보를 쓰는 것도 가능합니다. 이러한 방식으로 애플리케이션의 중요한 정보는 코드에서 분리되어 보안이 보장됩니다.
- 기밀정보의 동적인 제공, 중앙 집중식 시크릿 관리, 즉각적인 액세스 제어, 감사 추적 기능 등을 제공하여, 기업의 보안 정책을 준수하는 데 도움이 됩니다.

1. Vault의 특징

특징	설명
기밀정보의 동적 제공	애플리케이션이 필요에 따라 비밀정보를 요청하고, Vault는 요청된 정보를 제공합니다.
중앙 집중식 시크릿 관리	모든 애플리케이션의 시크릿 정보를 중앙에서 관리할 수 있습니다.
즉각적인 액세스 제어	애플리케이션이 Vault에 접근 할 수 있는 ‘특정 토큰 아이디’를 기반으로 Vault 서비스를 호출하고, Vault는 해당 '특정 토큰 아이디'를 수신한 뒤 요청된 '비밀정보'를 제공합니다.
감사 추적 기능	Vault는 모든 액세스 요청을 로깅하여 감사를 위한 추적이 가능합니다.

2. Vault 인증 방식

Vault 인증 방식

- Vault에 접근하기 위한 인증 방식을 의미합니다. Root Token, 정책 기반 토큰 (Policy-based Token), AppRole 등의 인증 방식을 통해서 Vault를 접근합니다.

인증 방식	설명
Root Token	- 모든 권한을 가진 ‘루트 권한 토큰’을 이용하는 인증 방식이며, 정책, 인증 방식, 시크릿 엔진, 모든 데이터 접근 가능한 인증 방식입니다. - 절대적인 권한을 가지고 있기에, 직접적으로 애플리케이션 레벨에서 인증방식으로 사용되지 않습니다.
정책 기반 토큰 (Policy-based Token)	정책(policy)에 의해 접근 범위가 제한된 ‘토큰’을 이용하는 인증 방식이며, 정책 범위 별로 강제 제한된 권한을 부여하고 접근하는 인증방식 입니다.
AppRole	- Role 별로 지정된 정책(Policy)에 따라서 접근 범위가 제한되며, ‘RoleID, Secret ID’에 따라 ‘토큰’을 발급받아서 접근 가능한 인증 방식입니다. - 해당 Role은 운영환경 혹은 팀별로 접근을 제어할 수 있으며, 사용자는 Role Id, Secret Id를 통해 인증만 수행하고, 이후 토큰에 대해서는 머신이 이를 갱신/관리하기에 별도의 Token 재발급 과정을 수행하지 않습니다.

3. Vault 수행 과정

Baeldung on KotlinSpring Boot ConnectionDetails Abstraction ❘ Baeldung

Vault 수행 과정

1. Spring Boot → Hashicorp Vault: Secret Request(비밀정보 요청)
- Spring Boot 애플리케이션에서는 서버를 실행할 때, Valut에 접근할 수 있는 ‘특정 토큰 아이디’(Secret Request)’ 를 기반으로 Vault 서비스를 호출하여 ‘비밀 정보(Secret)’를 검색합니다.

2. Hashicorp Vault → Spring Boot: Secret Response(비밀정보 응답)
- Valut 서비스는 Spring Boot 애플리케이션의 ‘특정 토큰 아이디’(Secret Request)’를 수신하고 요청된 ‘비밀 정보(Secret)’를 전달합니다.
- 이 단계를 통해서 애플리케이션은 필요한 시크릿 정보를 안전하게 받아올 수 있습니다.

3. Spring Boot → Remote Service : Connection Request(커넥션 요청)
- Spring Boot 애플리케이션이 원격 서비스와 연결을 시도하는 과정을 의미합니다.
- 이 단계에서 애플리케이션은 Vault에서 안전하게 가져온 비밀 정보(예: 데이터베이스 비밀번호, API 키 등)를 사용하여 원격 서비스에 연결 요청을 보냅니다.
- 이렇게 함으로써, 중요한 정보를 코드 내에 직접 작성하거나 노출시키지 않아도 되어 보안을 더 효과적으로 관리할 수 있습니다.

4. Remote Service → Spring Boot : Connection Response(커넥션 연결)
- Vault 서비스가 Spring Boot 애플리케이션의 Secret Request를 수신하고, 요청된 '비밀 정보'를 애플리케이션으로 전송하는 단계입니다.
- 이 단계를 통해 애플리케이션은 필요한 시크릿 정보를 안전하게 받아올 수 있습니다.

2) Vault 인증 방식의 강점

1. 소스코드 내에 민감정보 누출을 줄일 수 있습니다

소스코드 내에 민감정보 누출을 줄일 수 있습니다

- 전체 프로젝트 내에서 소스코드의 민감 정보는 포함되지 않고, 최초 서버 실행 시 Vault Secret Engine에서 불러온 값을 토대로 모두 조회해 옵니다.
- 만약 소스코드가 누출이 되더라도 주요한 민감정보에 대한 접근 권한을 가지고 있기에 누출이 발생하지 않습니다.

2. 분산된 민감 정보를 중앙 관리할 수 있습니다.

분산된 민감 정보를 중앙 관리할 수 있습니다.

- 해당 강점은 단순히 소스코드 내에서 보안 취약점을 숨기는 수준이 아니라 ‘애플리케이션 구조’와 ‘보안 책임’ 자체를 분리하는 과정입니다.
- 소스코드 내에 하드코딩 되어 있던 키 값들을 일괄적으로 Vault로 관리함으로써 분리된 ‘보안 책임’을 일괄 관리가 가능합니다.

아래와 같이 각각 분리된 키들이 있습니다.

아래와 같이 KV Secret Engine 내에서 일괄된 키들을 관리할 수 있습니다.

3. 접근 권한을 주기적으로 회전(Rotation)하고, 필요시 즉시 폐기할 수 있어서 보안 사고 발생 시 피해를 최소화할 수 있습니다.

접근 권한을 주기적으로 회전(Rotation)하고, 필요 시 즉시 폐기할 수 있어서 보안 사고 발생 시 피해를 최소화할 수 있습니다.

- AppRole 방식을 이용하면 Secret ID에 대해서 TTL(Time To Live), Num of uses(사용 횟수 제한)을 지정할 수 있습니다.
- 그리고, 만약 보안 사고 발생 시, Secret Id를 즉시 만료하여서 동적으로 노출이 되어도 피해가 최소화될 수 있습니다.

아래와 같이 최초 Secret Id를 발급하였습니다.

정상적으로 Vault를 접속해서 KV 데이터를 조회해 왔습니다.

아래와 같이 즉시 만료를 하였습니다.

# 특정 AppRole의 secret_id 만료
vault write auth/approle/role/dev-role/secret-id/destroy secret_id=<SECRET_ID>

# or

# 모든 AppRole의 secret_id 만료
$ vault write auth/approle/role/my-role/secret-id/destroy-all

서버에서 Vault 접근 시 만료가 됨을 확인할 수 있습니다.

4. 각 시스템/팀별로 Role을 나눌 수 있습니다.

각 시스템/팀별로 Role을 나눌 수 있습니다.

- dev-role, qa-role, prd-role, cicd-role, backend-role 등 역할 단위로 정책(Policy), TTL, Secret ID 발급 방식을 개별 설정할 수 있어, 운영 및 DevOps 환경에서 권한 관리와 보안 정책을 유연하게 적용할 수 있습니다.
- 또한 팀별로 Vault 접근 권한을 명확히 제한함으로써, 필요 최소한의 권한만 부여하는 원칙(Least Privilege)을 효과적으로 구현할 수 있습니다.
- 예를 들어서, dev-role의 경우는 kv2_dev에 대해서만 접근 가능 및 읽기, 쓰기, 수정이 가능하다고 Role을 지정할 수 있습니다. 그리고 prd-role의 경우는 오직 읽기 권한만 가능하다고 Role을 지정할 수 있습니다.

3) App Role 인증방식

App Role 인증방식

- 조직 내 팀, 서비스, 환경 단위로 '접근 가능한 권한을 분리'하여서 Vault에서 정책(Policy)을 정의하고, 이를 기반으로 AppRole 기준으로 각각 Role ID, Secret ID를 발급받아서 Vault에 인증을 요청하면 Vault에서는 토큰을 발급해 주는 인증 방식을 의미합니다.
- 사용자는 Role Id, Secret Id를 통해 인증만 수행하고, 이후 토큰에 대해서는 머신이 이를 갱신/관리하기에 별도의 Token 재발급 과정을 수행하지 않습니다
- 예를 들어서, 개발팀, DevOps, 백엔드 서버, CI/CD 파이프라인, 특정 마이크로서비스 등 주체별로 AppRole을 각각 나누어서 각각의 정책(Policy) 및 접근 권한을 부여하여 관리합니다.

Use AppRole authentication | Vault | HashiCorp Developer

Use AppRole authentication with Vault to control how machines and services authenticate to Vault.

developer.hashicorp.com

1. Role ID

Role ID

- AppRole의 고유 식별자로 어떤 역할을 수행하는지를 나타내는 아이디입니다.
- 예를 들어서, 해당 Role ID 값에 따라서 조직 내 팀, 서비스, 환경 단위로 분류가 가능하며, DevOps, 백엔드 서버, CI/CD 파이프라인, 특정 마이크로서비스 등 주체별로 각각 나누어서 어떤 역할을 수행할지 정의합니다.
- 해당 값은 역할이 무엇인지를 의미하는 ID와 같기에 유출되어도 단독으로는 아무 권한도 없습니다.

2. Secret ID

Secret ID

- Vault AppRole 인증에서 사용하는 비밀 키로, 해당 요청 주체가 특정 Role에 접근할 권한을 가지고 있음을 증명하는 값을 의미합니다. 또한, Role ID와 함께 사용되어야만 인증이 가능하며, 하나의 Role ID에 대해 여러 개의 Secret ID를 동시에 발급할 수 있습니다.
- Secret ID는 새로 발급된다고 해서 기존 Secret ID가 자동으로 폐기되지는 않으며, TTL 만료 또는 명시적인 revoke가 이루어져야만 무효화됩니다.
- 보안을 위해 Secret ID는 짧은 TTL 또는 Num of uses(사용 횟수 제한)으로 설정하여 필요한 순간에만 발급·사용되는 소모성 인증 수단으로 사용하는 것이 권장됩니다.

아래와 같이 최초 Secret Id를 발급하였습니다.

정상적으로 Vault를 접속해서 KV 데이터를 조회해 왔습니다.

3. Token

Token

- 발급받은 Role ID와 Secret ID를 기반으로 Vault에 로그인을 수행하면, 토큰이 발급됩니다. 이는 요청을 하는 주체가 어떤 정책으로 얼마나, 언제까지 접근할 수 있는지를 증명하는 값을 의미합니다.
- 실제 애플리케이션에서는 직접적으로 토큰을 발급받는 것이 아닌, Role ID와 Secret ID를 기반으로 자격증명을 요청하면 Vault 내에서 토큰을 발급하여 인증을 수행합니다.
- 그렇기에, 애플리케이션은 Secret ID를 이용해 최초 한 번만 인증하고 이후에는 발급된 토큰을 사용해 Vault에 접근하며 토큰은 TTL에 따라 자동으로 만료되거나 갱신됩니다.

4. AppRole 프로세스

AppRole 프로세스

1. Spring Boot 서버 시작: SpringApplication.run()
- 최초 Spring Boot 서버가 실행이 됩니다.

2. Spring Cloud Vault 자동 구성 로드: bootstrap.yml
- Spring Cloud Bootstrap에서 최초 Vault 설정에 대한 자동 구성이 로드가 됩니다.

3. Vault에 '인증(AppRole)' 요청 수행(Role Id, Secret Id)
- Vault의 인증 방식 중 AppRole을 이용한 방식에서 사전에 팀별로 발급된 Role Id, Secret Id를 통해서 Vault에 인증을 요청합니다.

4. Vault '인증 정보' 검증
- Vault에서는 유효한 토큰인지에 대해 인증 정보에 대해 검증을 합니다.
- 성공 시, KV Secret Engine에 접근합니다.
- 실패 시, 서버 시작 실패와 종료를 합니다.

5. 조회된 Secret을 Spring Boot에 응답
- KV Secret Engine에서 조회된 정보를 응답으로 전달합니다

6. 응답받은 Secret을 Spring Environment(PropertySource)에 자동 주입
- Spring Boot에서는 전달받은 Secret을 Spring Environment(PropertySource)에 자동 주입을 합니다.

7. @ConfigurationProperties VaultKVProperties.java 객체와 자동 매핑
- 추후에 구성할 VaultKVProperties.java 파일 내에 사전에 KV와 같은 형태로 구성한 멤버 변수 각각에 데이터가 매핑이 됩니다.

8. Spring Boot 서버 실행 완료
- 최종 작업이 완료되어서 Spring Boot 서버가 실행이 완료가 됩니다.

4) Root Token 인증 방식 vs 정책 기반 토큰 인증 방식 vs AppRole 인증 방식

구분	Root Token	정책 기반 토큰 인증 방식	AppRole 인증 방식
권한(Privilege)	Vault 전체 권한(슈퍼 관리자). 모든 작업 허용	정책(policy) 범위에서만 권한 허용	정책(policy)로 제한되며, Role에 부여된 권한만 사용
보안 위험도	극도로 높음 (유출 시 Vault 완전 장악)	비교적 낮음 (정책으로 제한)	매우 낮음. RoleID + SecretID 조합이 필요하고, SecretID TTL/1회용 설정 가능
용도	초기 구성, 위험한 관리 작업	일반 사용자/서비스가 직접 토큰을 받아서 사용	서버/애플리케이션이 자동 인증할 때 사용 (사람이 아닌 머신/서비스용)
TTL / 만료 설정	기본 없음. 수동 회전 필요	TTL, Max TTL, Renewable 자유 설정	SecretID/Token TTL, Max TTL, Renewable 모두 세밀하게 설정 가능
정책 적용 방식	정책 무시하고 모든 권한 가능	정책 기반으로 반드시 제한	Role에 연결된 정책의 권한으로 제한
사용 주체	초기 관리자	개발자, 운영자, 서비스 계정	백엔드 서버, 배치 서버, 컨테이너, CICD — 사람이 아닌 머신
재발급 / 갱신	거의 없음	TTL 만료 시 재발급 가능	SecretID 자동 생성 가능, 주기적 Rotation 가능, 토큰도 자동 갱신 가능
발급 방법	초기화 시 자동 생성	vault token create 또는 Auth Method(OIDC, GitHub 등)	SecretID 생성 → 서버가 RoleID + SecretID로 로그인 하여 Token 자동 발급
운영 관점	일반 운영에서 절대 사용 금지	사용 가능하지만 사람이 직접 관리해야 하는 불편함 있음	자동화에 최적, 서버 재기동해도 RoleID/SecretID로 자동 로그인
Audit Logging	모든 작업 기록되나 너무 광범위	정책 기반이라 세밀한 기록 가능	RoleID 노출되어도 SecretID 없으면 무용지물 → 가장 안전한 로깅 가능
토큰 폐기(Revocation)	폐기하면 복구가 복잡	토큰만 폐기 가능	RoleID/SecretID/발급된 토큰 각각 독립적으로 폐기 가능
적합한 상황	초기 설정, 정책 생성, 비상 상황	단순 테스트, 개발자가 직접 토큰 사용 시	운영 서버 인증, 자동화, 배포 파이프라인, 백엔드 서비스 연동
장점	무제한 권한	설정이 직관적	매우 안전, 자동화 가능, SecretID 1회용/TTL로 보안 극대화
단점	너무 위험함	장기적으로 운영 자동화에 적합하지 않음	개념이 조금 복잡. RoleID + SecretID 관리 필요

5) App Role 구성 -1 : AppRole 활성화 & Policy 생성

1. Vault 탭에서 Access를 선택합니다.

2. Authentication Methods 내에서 ‘Enable new method’를 선택합니다.

3. ‘AppRole’을 선택합니다.

4. 우선 기본값으로 선택하고 ‘Enable method’를 누릅니다

5. 아래와 같이 생성이 되었습니다

[참고] 해당 과정은 위의 과정은 CLI를 통해서 수행이 가능합니다.

$ vault auth enable approle

6. 홈 화면에서 ‘Polices’를 선택합니다

7. ACL Policies - ‘Create ACL policy’를 선택합니다

8. Name, Policy를 입력하고 ‘Create Policy’를 선택합니다.

Name, Policy를 입력합니다

- 사전에 구성한 KV Engine의 kv2라는 이름에 대해 읽기 권한을 부여하였습니다

path "kv2/data/*" {
  capabilities = ["read", "list"]
}

6) App Role 구성 -2 : AppRole 구성

App Role 구성 -2 : AppRole 구성

- 해당 AppRole에 대해서는 AppRole 관리를 위한 GUI를 지원하지 않고 CLI 기반으로 수행을 합니다.

1. Role을 생성합니다.

역할을 생성합니다.

- approle의 role을 생성하는데 ‘dev-role’이라는 이름으로 생성을 합니다. 그리고 위에서 만든 ‘dev-approle-policy’를 연결하였습니다.
- 또한, 아래와 같은 옵션을 두고 생성을 하였습니다.

vault write auth/approle/role/dev-role \
    policies="dev-approle-policy" \
    token_type=batch \
    secret_id_ttl=10m \
    token_ttl=20m \
    token_max_ttl=30m \
    secret_id_num_uses=40

설정	의미	실제 동작
token_type=batch	가벼운 단기 토큰, 저장 안됨, 갱신 불가	API 서버/단기 작업에 적합
secret_id_ttl=10m	SecretID는 생성 후 10분 동안만 사용 가능	짧은 노출 시간이 필요한 경우
token_ttl=20m	로그인 후 발급되는 토큰의 기본 TTL	20분 지나면 자동 만료
token_max_ttl=30m	토큰이 절대 넘길 수 없는 시간	batch 토큰이라 갱신 불가, 의미 제한적
secret_id_num_uses=40	SecretID를 최대 40번 사용할 수 있음	40번 or 10분 중 먼저 도달 시 종료

[참고] 생성한 Role에 대한 조회를 하는 방법은 아래와 같습니다.

vault read auth/approle/role/dev-role

2. 생성한 AppRole의 Role ID를 가져옵니다.

생성한 AppRole의 Role ID를 가져옵니다.

$ vault read auth/approle/role/dev-role/role-id

3. 생성한 AppRole의 SecretID를 가져옵니다.

생성한 AppRole의 SecretID를 가져옵니다.

$ vault write -f auth/approle/role/dev-role/secret-id

4. 토큰을 발급받습니다

$ vault write auth/approle/login \
    role_id="<ROLE_ID>" \
    secret_id="<SECRET_ID>"
    
  
 # 사용예시 
$ vault write auth/approle/login \
    role_id="f76173e0-d539-e47e-39ee-6fde6384b75d" \
    secret_id="1bbee7b9-999e-33df-258f-da7583c6515b"

5. 발급받은 토큰으로 로그인합니다.

6. 접근이 완료되었습니다

7) Spring Boot 환경 구성

1. 개발 환경

개발 환경

- 기본 기능과 주요 라이브러리인 spring-cloud-dependencies, spring-cloud-starter-bootstrap, spring-cloud-starter-vault-config를 설정하였습니다.

개발 환경	분류	버전
Java JDK	Java Version	17
빌드 도구	Gradle	8.14.3
Spring Boot	Spring Boot Starter	3.5.8
Spring Boot Web	Spring Boot Starter	3.5.8
spring-cloud-starter-bootstrap	Spring Boot Cloud	2025.0.0
spring-cloud-starter-vault-config	Spring Boot Cloud	2025.0.0
spring-cloud-dependencies	Spring Boot Cloud	2025.0.0
Lombok	Library	latest

2. 라이브러리 설치 : build.gradle

라이브러리 설치 : build.gradle

- 위에서 명시한 라이브러리를 Gradle을 이용하여서 설치합니다.

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.5.8'
    id 'io.spring.dependency-management' version '1.1.7'
}
ext {
    springCloudVersion = "2025.0.0"
}

group = 'com.adjh'
version = '0.0.1-SNAPSHOT'
description = 'spring-boot3-vault'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'           // Spring Boot Web

    implementation 'org.springframework.cloud:spring-cloud-starter-bootstrap'   // Spring Cloud BootStrap
    implementation 'org.springframework.cloud:spring-cloud-starter-vault-config'// Spring Cloud Vault
    compileOnly 'org.projectlombok:lombok'                                      // Lombok Compile
    annotationProcessor 'org.projectlombok:lombok'                              // Lombok Annotation
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}
dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:$springCloudVersion"
    }
}

tasks.named('test') {
    useJUnitPlatform()
}

3. 시스템 환경변수 주입 : IntelliJ IDE 활용

시스템 환경변수 주입 : IntelliJ IDE 활용

- Vault로 전달이 되는 Main Key 자체를 프로젝트 내에 넣고 Git에 올릴 수 없기에 ‘시스템 환경 변수’ 내에 추가합니다.

[참고] 아래의 환경 변수를 추가하는 방법의 글을 참고하셔도 도움이 됩니다.

[Java] Spring Boot 환경에서 시스템 변수 .env 파일 지정 및 활용 방법

adjh54.tistory.com

[Java] Spring Cloud Vault 이해하고 활용하기-1 : 초기 환경, KV 구성 및 Root Token 인증 방식

adjh54.tistory.com

4. bootstrap.yml 파일을 생성 및 구성합니다.

bootstrap.yml 파일을 생성 및 구성합니다.

- resources 경로 하단에 bootstrap.yml 파일을 생성하였습니다

yml 파일을 아래와 같이 구성하였습니다.

- 사전 단계에서 발급받은 VAULT_APP_ROLE_ID, VAULT_APP_ROLE_SECRET 값을 환경 변수로 추가하였고 이를 불러옵니다.

spring:
  cloud:
    vault:
      uri: http://localhost:8200
      # 인증방식 : APPID, APPROLE, AWS_EC2, AWS_IAM, AZURE_MSI, CERT, CUBBYHOLE, GCP_GCE, GCP_IAM, KUBERNETES, NONE, PCF, TOKEN;
      authentication: APPROLE                   # Vault 인증 방식 (TOKEN, APPROLE, APPID 등)
      connection-timeout: 5000                  # Vault 서버 연결 시도 타임아웃(ms)
      read-timeout: 15000                       # Vault 데이터 읽기 타임아웃(ms)

      app-role:
        role-id: ${VAULT_APP_ROLE_ID}           # 환경변수에서 Vault 접근 role-id를 불러옴
        secret-id: ${VAULT_APP_ROLE_SECRET}     # 환경변수에서 Vault 접근 role-secret를 불러옴
        role: dev-role                          # 사전에 할당된 role을 불러옴

      kv:
        enabled: true                           # KV(키-값) 비밀 엔진 사용 여부
        backend: kv2                            # Vault에서 생성한 엔진 이름(ex: kv2), 반드시 일치해야 함
                                                # 실제 Vault 경로가 "kv2/" 라면 backend도 kv2로 설정해야 함

        default-context: loc                    # 기본 Secret 경로 (예: kv2/loc/data/application 같은 구조가 됨)
                                                # 즉, Vault UI에서는 /kv2/data/loc 경로와 매핑됨

        application-name: ''                    # Spring 애플리케이션 이름을 Secret 경로에 추가할지 여부
                                                # 빈 값이면 "default-context" 바로 아래에서 조회함
                                                # 예: default: '' → kv2/loc/data

5. 서버 실행

서버 실행

- 정상적으로 오류 없이 서버가 실행하였습니다.

6. Vault 값과 객체 매핑

Vault 값과 객체 매핑

- Vault에서 읽어온 값을 자바 클래스 필드에 자동 바인딩을 하는 클래스입니다.

- @Getter, @Setter 통해서 멤버 변수에 접근할 수 있도록 어노테이션을 지정하였습니다.
- @Component를 빈으로 등록하여서, 다른 서비스나 컴포넌트에 주입하여 사용이 가능하도록 하였습니다.
- @ConfigurationProperties(prefix = "vault") : 상위 prefix 내에 하위에 동일한 이름으로 각각 자동 바인딩이 됩니다.

package com.adjh.springboot3vault.properties;

import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;

/**
 * Vault Key-Value Properties Mapping value
 *
 * @author : leejonghoon
 * @fileName : VaultKVProperties
 * @since : 25. 11. 25.
 */
@Getter
@Setter
@Component
@ConfigurationProperties(prefix = "")
public class VaultKVProperties {
    private String appEnv;
    private String dbHost;
    private String dbPassword;
    private String dbUser;
}

7. 콘솔을 확인하기 위해 Controller를 구성하였습니다.

콘솔을 확인하기 위해 Controller를 구성하였습니다.

- 생성자 패턴으로 bean을 호출하여서 Controller 내에서 활용하도록 구성하였습니다.
- http://localhost:8080 url로 접근하여서 ‘/api/v1/vault/kv’로 호출이 된다면 각각의 vault 값이 정상적으로 출력이 됩니다.

package com.adjh.springboot3vault.controller;

import com.adjh.springboot3vault.properties.VaultKVProperties;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * Bean을 호출하여서 Vault 값을 테스트하기 위한 Controller
 *
 * @author : leejonghoon
 * @fileName : VaultController
 * @since : 25. 11. 25.
 */
@RestController
@RequestMapping("/api/v1/vault")
public class VaultController {

    private final VaultKVProperties vaultKVProperties;

    public VaultController(VaultKVProperties vaultKVProperties) {
        this.vaultKVProperties = vaultKVProperties;
    }

    @GetMapping("/kv")
    public String main() {
        System.out.println("Getter appEnv : " + vaultKVProperties.getAppEnv());
        System.out.println("Getter dbHost : " + vaultKVProperties.getDbHost());
        System.out.println("Getter dbPassword : " + vaultKVProperties.getDbPassword());
        System.out.println("Getter dbUser : " + vaultKVProperties.getDbUser());
        return "임시 테스트 ";
    }
}

8. 결과확인

결과확인

- 정상적으로 출력이 됨을 확인하였습니다.

오늘도 감사합니다.

[제작 앱 소개] 나이 계산기: 오늘의 나이

adjh54 — Fri, 19 Dec 2025 13:44:01 +0900

해당 글에서는 Contributor9 개발자가 만든 개발 앱에 대해 홍보를 위한 목적으로 작성한 글입니다.

1) 개발자는 왜 이 앱을 만들었을까?

개발자는 왜 이 앱을 만들었을까?

- 만 나이 통일법에 대해 알고 있으신가요?
2023년 시행된 법으로 기존에는 한국 나이가 출생일을 기준으로 '1살'로 시작되어서 생일이 지날 때마다 1살씩 더해지는 나이였습니다.
해당 법이 시행된 이후에는 태어난 해는 '0살'이 되고 생일이 지날 때 1살이 더해지는 나이가 됩니다. 즉, 예전에 '만 나이'로 불리던 나이가 지금의 나이로 통일된 법입니다.

https://m.terms.naver.com/entry.naver?docId=6648039&cid=43667&categoryId=43667

- 기존에는 나의 나이가 한국식 나이, 만 나이, '빠른'이라는 개념이 추가되어서 내 나이를 이야기하기가 참 복잡했습니다.
그렇기에 누군가가 "나이가 몇 살이신가요?"라고 물어보면 "저는 00년생입니다"라고 이야기를 해왔던 것 같습니다.

- 법이 시행된 지금은 하나로 통일된 나이가 되었지만, 아직까지 통용되는 나이인 '과거 한국식 나이'를 확인해 볼 수 있고, 실제 나이가 되는 '만 나이' 그리고 '연 나이'를 한눈에 볼 수 있는 앱입니다.
생년월일을 입력하면 기본적인 나이에 대한 정보를 확인하는 것은 물론, 과거 조선시대의 불려졌던 나이별 이칭을 제공해 줍니다.
또한, 나의 생년월일을 기준으로 12간지, 탄생석, 탄생화, 탄생목, 탄생석, 별자리, 수호성, 태어난 절기에 대한 탄생과 관련된 정보들을 제공해 줍니다.

- 이런 정보 제공뿐만 아니라, '즐겨찾기' 기능을 통해, 내 정보뿐만 아니라 가족, 연인, 지인들에 대한 정보도 나만의 약칭을 포함하여서 관리할 수 있는 기능으로 제공을 합니다. 그리고 특별한 날에 맞는 미리 푸시메시지까지 제공합니다.

주위 사람의 나이가 헷갈린다면, 나이 계산기 앱에 저장하고 관리해 보세요! 그리고 필요한 순간에 푸시메시지로 놓치지 말고 해당 앱을 사용해 보세요!!

내 자신을 알아가고 주위 사람들을 알아갈 수 있는 앱이라고 생각합니다.

2) 앱 소개- 나이 계산기: 오늘의 나이

앱 소개- 나이 계산기: 오늘의 나이

- 나이 계산기: 오늘의 나이 앱은 단순한 나이 계산 기능을 넘어, 당신의 생일에 담긴 의미와 인생의 흐름을 알려주는 앱입니다.

- 누군가 내 나이나 가족의 나이를 물어볼 때, "음… 잘 모르겠는데, 아마 00년생이었을 거예요."라고 대답한 적이 있지 않으신가요? 또는 '만 나이 통일법' 이후 헷갈려서 정확한 나이를 계산하기 어려웠던 적은 없으신가요?

- 나이 계산기: 오늘의 나이 앱에서는 만나이, 연나이, 과거 한국식 나이까지 모두 정확하게 계산해 드립니다. 또한 입력한 생년월일을 기준으로 음력 생일, 생일까지 남은 일수, 12지신 띠, 나이별 이칭, 별자리, 탄생석, 탄생화, 탄생목, 탄생색, 수호성, 태어난 절기를 한눈에 확인할 수 있습니다.
- 그리고 가족, 친구, 지인들의 나이를 한곳에서 손쉽게 관리하고, 생일 알림까지 받아보세요!

주요 기능

1. 나이 계산

- 생년월일, 기준일자를 기준을 입력하여 나이 계산, 생일에 담긴 의미, 인생의 흐름을 확인할 수 있습니다.
- 생년월일과 기준일자를 입력하면 만 나이, 연 나이, 과거 한국식 나이를 즉시 계산해 줍니다.
- 기준일을 오늘, 한 달 전, 1년 후 등으로 변경하여 특정 시점의 나이 변화를 확인할 수도 있습니다. 또한 '음력 사용' 옵션으로 음력 생일 계산이 가능하며, 자주 확인하는 생일은 '즐겨찾기 추가' 기능으로 쉽게 관리할 수 있습니다.
- 계산된 결과는 복사하거나 공유 버튼을 통해 간편하게 다른 사람과 공유할 수 있습니다

2. 나이 계산 결과

- 나이 정보 영역에서는 생년월일을 기준으로 만 나이, 연 나이, 과거 한국식 나이를 한눈에 확인할 수 있습니다.
- 나이별 이칭 영역에서는 과거 한국에서 나이대별로 불리던 이름(이칭)을 확인할 수 있으며, 다음 나이대의 이름도 함께 제공합니다. 또한, 물음표 아이콘을 누르면 '나이별 이칭 정보 팝업'이 제공되며, 모든 나이별 이칭 목록을 확인할 수 있습니다.
- 생일 정보 영역에서는 생년월일(양력, 음력)을 표시하며, 다음 생일까지의 D-DAY, 태어난 요일, 계절 정보, 그리고 태어난 지 경과된 기간을 상세히 확인할 수 있습니다.
- 탄생 정보 영역에서는 입력한 생년월일을 기준으로 12지신, 탄생석, 탄생화, 탄생목, 탄생색, 별자리, 수호성, 태어난 절기를 확인할 수 있습니다. 또한, 물음표 아이콘을 누르면 '탄생 정보 팝업'이 열리며, 연도별, 월별 탄생 정보를 자세히 확인할 수 있습니다.

3. 즐겨찾기 목록

- 즐겨찾기로 추가된 날짜를 기준으로 즐겨찾기 목록을 확인할 수 있습니다.
- 각 항목에서는 저장된 생년월일을 기준으로 계산된 만 나이, 연나이, 한국식 나이를 바로 확인할 수 있습니다.
- '더 보기' 버튼을 누르면, 생년월일을 기준으로 한 탄생 정보를 카드 형태로 간단히 확인할 수 있으며, 항목을 터치하면 상세한 탄생 정보 팝업이 표시됩니다. 또한 '결과 다시 보기' 버튼을 누르면, 이전에 확인했던 나이 계산 결과 화면으로 이동하여 자세한 정보를 확인할 수 있습니다.

- 상단의 플러스 버튼이나 '즐겨찾기 추가' 버튼을 눌러 새로운 즐겨찾기 항목을 빠르게 추가할 수 있습니다.
- 각 항목의 공유 버튼을 누르면, 해당 정보를 다른 사용자와 간편하게 공유할 수 있습니다.
- 알림 버튼을 누르면 일주일 전, 하루 전, 당일 오전 9시에 생일 알림을 받을 수 있도록 설정할 수 있습니다.
- 별 버튼을 누르면, 해당 항목의 즐겨찾기 설정을 해제할 수 있습니다.

4. 설정

- 개인정보 처리방침, 이용약관, 오픈소스 라이브러리 확인
- 현재 앱 버전 및 제작자 정보 제공

이런 분께 추천합니다

- 정확한 만 나이, 연나이, 한국식 나이를 알고 싶은 분
- 음력 생일이나 생일까지 남은 날짜(D-DAY)를 한눈에 보고 싶은 분
- 띠, 별자리, 탄생석, 탄생화, 탄생색 등 나만의 탄생 정보를 알고 싶은 분
- 가족이나 친구의 생일·나이를 함께 관리하고 알림을 받고 싶은 분
- 기준일을 바꿔가며 과거·미래의 나이 변화를 확인해 보고 싶은 분

⸻

지금 다운로드하고 ‘오늘의 나이’를 확인하세요!
당신의 생일 속에 숨은 의미를 만나보세요 ✨

3) 다운로드

1. Google PlayStore

https://play.google.com/store/apps/details?id=com.tha.agecalc

나이 계산기: 오늘의 나이 - Google Play 앱

단순한 나이 계산 기능을 넘어, 당신의 생일에 담긴 의미와 인생의 흐름을 알려주는 앱입니다.

play.google.com

2. AppStore

https://apps.apple.com/us/app/id6754360556

나이 계산기: 오늘의 나이 App - App Store

Download 나이 계산기: 오늘의 나이 by EcodeLab on the App Store. See screenshots, ratings and reviews, user tips, and more games like 나이 계산기: 오늘의 나이.

apps.apple.com

⬇️ 개발자의 다양한 앱을 보고 싶으시면 아래의 링크를 확인해주세요 ⬇️

Ecodelab - 제작 앱 소개

Ecodelab에서 개발한 다양한 앱들을 소개합니다

www.ecodelab.im

오늘도 감사합니다.

[Java] Spring Cloud Vault 이해하고 활용하기-2 : 정책 기반 토큰 발급 및 인증 방식

adjh54 — Thu, 11 Dec 2025 20:00:21 +0900

해당 글에서는 Spring Cloud Vault를 활용하는 방법 중 정책 기반 토큰을 발급하고 인증을 하는 방법에 대해서 알아봅니다.

[참고] 이전에 작성한 글에서 KV Secret Engine이 구성되었다는 가정하에 이번 글이 이어집니다.

[Java] Spring Cloud Vault 이해하고 활용하기-1 : 초기 환경, KV 구성 및 Root Token 인증 방식

adjh54.tistory.com

1) Vault

Vault

- HashCorp 사에서 만든 Vault는 다양한 환경에서 애플리케이션의 외부 비밀 속성(예: 데이터베이스 비밀번호, API 키 등)을 외부화된 구성으로 중앙에서 관리할 수 있습니다.
-Spring Boot 환경에서 Vault로부터 시크릿 정보를 읽어오며 Valut에 시크릿 정보를 쓰는 것도 가능합니다. 이러한 방식으로 애플리케이션의 중요한 정보는 코드에서 분리되어 보안이 보장됩니다.
- 기밀정보의 동적인 제공, 중앙 집중식 시크릿 관리, 즉각적인 액세스 제어, 감사 추적 기능 등을 제공하여, 기업의 보안 정책을 준수하는 데 도움이 됩니다.

1. Vault의 특징

특징	설명
기밀정보의 동적 제공	애플리케이션이 필요에 따라 비밀정보를 요청하고, Vault는 요청된 정보를 제공합니다.
중앙 집중식 시크릿 관리	모든 애플리케이션의 시크릿 정보를 중앙에서 관리할 수 있습니다.
즉각적인 액세스 제어	애플리케이션이 Vault에 접근 할 수 있는 ‘특정 토큰 아이디’를 기반으로 Vault 서비스를 호출하고, Vault는 해당 '특정 토큰 아이디'를 수신한 뒤 요청된 '비밀정보'를 제공합니다.
감사 추적 기능	Vault는 모든 액세스 요청을 로깅하여 감사를 위한 추적이 가능합니다.

2. Vault 수행 과정

https://www.baeldung.com/spring-boot-3-1-connectiondetails-abstraction

Vault 수행 과정

1. Spring Boot → Hashicorp Vault: Secret Request(비밀정보 요청)

- Spring Boot 애플리케이션에서는 서버를 실행할 때, Valut에 접근할 수 있는 ‘특정 토큰 아이디’(Secret Request)’ 를 기반으로 Vault 서비스를 호출하여 ‘비밀 정보(Secret)’를 검색합니다.

2. Hashicorp Vault → Spring Boot: Secret Response(비밀정보 응답)

- Valut 서비스는 Spring Boot 애플리케이션의 ‘특정 토큰 아이디’(Secret Request)’를 수신하고 요청된 ‘비밀 정보(Secret)’를 전달합니다.
- 이 단계를 통해서 애플리케이션은 필요한 시크릿 정보를 안전하게 받아올 수 있습니다.

3. Spring Boot → Remote Service : Connection Request(커넥션 요청)
- Spring Boot 애플리케이션이 원격 서비스와 연결을 시도하는 과정을 의미합니다.
- 이 단계에서 애플리케이션은 Vault에서 안전하게 가져온 비밀 정보(예: 데이터베이스 비밀번호, API 키 등)를 사용하여 원격 서비스에 연결 요청을 보냅니다.
- 이렇게 함으로써, 중요한 정보를 코드 내에 직접 작성하거나 노출시키지 않아도 되어 보안을 더 효과적으로 관리할 수 있습니다.

4. Remote Service → Spring Boot : Connection Response(커넥션 연결)
- Vault 서비스가 Spring Boot 애플리케이션의 Secret Request를 수신하고, 요청된 '비밀 정보'를 애플리케이션으로 전송하는 단계입니다.
-이 단계를 통해 애플리케이션은 필요한 시크릿 정보를 안전하게 받아올 수 있습니다.

[ 더 알아보기 ]

Spring Cloud Vault

- HashiCorp Vault와 Spring 애플리케이션을 연결해 민감한 정보를 안전하게 관리할 수 있도록 돕는 프레임워크입니다.
- 즉, 비밀번호·API 키·DB 접속 정보 같은 시크릿을 외부에 노출하지 않고 중앙에서 안전하게 관리하며, 애플리케이션은 이를 자동으로 가져와 사용할 수 있습니다.
- Spring 애플리케이션이 Vault에 저장된 시크릿을 가져와 Spring 환경에 자동으로 주입합니다.

3. KV(Key-Value) Secret engine

KV(Key-Value) Secret engine

- Vault에 구성된 물리적 저장소 내에 임의의 시크릿을 저장하는 데 사용되는 일반적인 키-값(KV) 저장소입니다.
- 가장 기본적인 정적(Static) 비밀 저장소를 의미합니다. 키-값 형태로 환경변수, API 키, 토큰, 비밀번호 등을 저장하고, 읽고, 업데이트합니다.
- Database 엔진과 같이 동적 Credential 방식과 다르게 만료가 되지 않고, 키에 대한 단일 값을 저장하거나, 각 키에 대해 여러 버전을 저장하고 해당 버전을 기록을 할 수 있습니다.

KV(Key-Value) Secret engine 내에서 KV v1, KV v2가 존재합니다.

분류 항목	KV v1	KV v2
기능	단순 키-값 저장	키-값 저장 + 버전관리
버전 관리	없음	있음
API 구조	단순 /v1/<mount>/<path>	/data, /metadata - 데이터: /v1/<mount>/data/<path> - 메타데이터: /v1/<mount>/metadata/<path>
삭제	즉시 삭제	soft delete + destroy
CAS(Check-And-Set)	제한적	정식 지원 (동시 업데이트 충돌 방지)
사용 사례	단순한 설정값, 변경 필요 없는 비밀	자주 변경되는 비밀 정보, 롤백/복구가 필요한 비밀정보

3.1. KV Version 1

KV Version 1

- KV(Key-Value) Secret engine에서 물리적인 저장소에 내에 임의의 비밀(Secret)을 저장하는 데 사용이 됩니다.
- KV v2에 비교하여 단순한 키-값만 저장을 하는 용도로 사용이 되며, 별도의 버전관리는 되지 않습니다.
- 또한, 주로 단순한 설정 값, 변경 필요가 없는 파일에 대해서 관리가 됩니다.

3.2. KV Version 2

KV Version 2

- KV Version1과 동일하게 KV(Key-Value) Secret engine에서 물리적인 저장소에 내에 임의의 비밀(Secret)을 저장하는 데 사용이 됩니다.
- KV v1과 비교하여 키-값 저장을 하는 용도로 사용이 되며, 별도의 버전관리를 수행하여서 이전 버전을 통해서 관리하고 복구할 수 있습니다. 또한, 자주 변경이 되는 비밀, 롤백/복구가 필요한 파일에 대해서 관리가 됩니다.

2) 정책 기반 토큰 발급

정책 기반 토큰 발급 및 이용방식

- 권한(Policy), TTL, Max TTL, Renewable 여부 등 조건을 지정한 다음 Vault가 자동으로 토큰을 발급을 하고, 사용자는 그 토큰으로만 Vault API에 접근하는 방식을 의미합니다.
- 즉, Root Token(슈퍼 관리자급 권한)을 쓰지 않고, ‘읽기 전용’, ‘DB 패스워드 발급만 가능’, ‘TTL 하루만 사용’ 등과 같은 안전한 토큰을 만들어서 쓰는 구조를 의미합니다.

1. 정책 생성

정책 생성

- Vault에서 ‘특정 접근 권한’에 대한 정책을 생성합니다.

# name: read-only-policy 이름으로 작성
path "kv2/data/*" {
  capabilities = ["read", "list"]
}

2. 정책 기반 토큰 발급

정책 기반 토큰 발급

- 정책을 기반으로 하고, 토큰 생성 시 옵션을 지정하여서 특정 기간으로 한 토큰을 발급합니다.

$ vault token create \\
  -policy="read-only-policy" \\
  -ttl=24h \\
  -explicit-max-ttl=720h \\
  -renewable=true

옵션	타입	설명
-policy=<name>	반복 사용 가능	토큰에 부여할 정책. 여러 개 지정 가능. 예: -policy=default -policy=read-only
-policies=<list>	문자열 리스트	쉼표로 여러 정책 지정할 때 사용. 예: -policies="default,read-only"
-orphan	boolean	부모 토큰 없이 독립적인 토큰 생성. 부모가 삭제돼도 유지.
-period=<duration>	기간	정해진 기간마다 자동 갱신해야 하는 토큰 생성. (Periodic token)
-ttl=<duration>	기간	토큰의 최초 TTL(수명). 예: 1h, 24h
-explicit-max-ttl=<duration>	기간	갱신을 포함한 토큰의 최대 TTL 제한.
-format=<format>	string	출력 형식 (json / table / yaml 가능). 예: -format=json
-id=<token_id>	string	토큰 ID를 직접 지정해서 생성(보안상 거의 안 씀).
-display-name=<name>	string	토큰 이름. Audit log 등에 표시됨. 기본값은 “token”
-metadata=<key=value>	key-value	토큰 metadata 설정. 여러 개 가능. 예: -metadata=user=john
-role=<role_name>	string	Token role 기반으로 생성. Token role 정책/TTL 규칙 적용.
-entity=<entity_id>	string	특정 Identity Entity에 토큰을 연결함.
-no-default-policy	boolean	default policy 자동 부여 방지. 기본은 default 포함됨.
-use-limit=<number>	number	토큰을 사용할 수 있는 최대 횟수 지정. (Use-limit token)
-wrap-ttl=<duration>	기간	래핑 토큰 생성 TTL 설정. 렌즈로 발급할 때 사용.
-num-uses=<number>	number	토큰 허용 사용 횟수 (use-limit과 동일 개념)
-namespace=<path>	string	Vault Enterprise 전용. 특정 namespace에 토큰 발급.
-mount=<auth_mount_path>	string	Token auth mount 지정. 특별한 경우 외엔 사용 X

3. 사용자는 발급받은 토큰을 이용하여 Vault에 접근

4. 토큰은 일정 시간이 되면 만료(TTL: Time To Live) 혹은 재갱신합니다

토큰은 일정 시간이 되면 만료(TTL: Time To Live) 혹은 재갱신합니다

- 토큰이 일정시간이 되었을 때, 실수로 토큰이 유출돼도 TTL이 도래해서 자동으로 폐기가 됨. 그리고 필요에 따라서 renewable=true 속성에 따라서 TTL 연장이 가능합니다.

3) Root Token 이용 방식 vs 정책 기반 토큰 발급 및 이용 방식 비교

Root Token 이용 방식 vs 정책 기반 토큰 발급 및 이용 방식 비교

구분	Root Token 이용 방식	Token 발급 및 이용 방식(정책 기반 토큰)
권한(Privilege)	Vault 전체 권한(=슈퍼 관리자). 모든 경로·모든 기능 허용	부여된 정책(policy)에 따라 제한된 권한만 수행
보안 위험도	매우 높음 (노출 시 Vault 전체 장악 가능)	상대적으로 낮음 (정책 범위 내에서만 노출 피해)
용도	초기 Vault 설정, 정책·엔진 구성 같은 위험 작업	실제 서비스/애플리케이션/운영 시스템이 사용하는 정상적인 방식
TTL / 만료 설정	기본적으로 만료 없음(수동으로 만료시키거나 Rotate 필요)	TTL, Max TTL, Renewable 여부 자유롭게 설정 가능
정책 적용 방식	정책을 무시하고 모든 작업 가능	반드시 정책(policy) 기반으로 제약을 받음
사용 주체	관리자(초기 구축, 정책 생성, 토큰 설정 등)	애플리케이션, CICD, 개발자, 프로세스 등
재발급/갱신	Root Token은 갱신할 일이 거의 없음(보통 비활성화·보관)	TTL 만료 시 재발급, 갱신(Renewal) 가능
발급 방법	Vault 초기 설정 시 자동 생성	vault token create 명령 또는 Auth Method(OIDC, GitHub, AppRole 등)로 발급
운영 관점	평소에 사용하면 안 됨. 금고 열쇠를 책상 위에 두는 것과 같음	실제 운영 환경은 일반 토큰 + Auth Method 조합으로 사용
Audit Logging	기록은 남지만 Root라서 모든 동작이 너무 광범위함	정책 기반이므로 더 세밀한 감사 추적 가능
토큰 폐기(Revocation)	폐기하면 다시 초기화 과정을 통해 복구해야 할 수 있음	토큰만 폐기하고 서비스는 다른 토큰으로 계속 동작
적합한 상황	초기 설정, 정책 생성, 비상 상황	API 접근, 앱 서비스, 자동화 작업(CICD), 시스템 구성

1. Root Token 이용 방식

Root Token 이용 방식

- 기존 방식의 경우는 Root Token을 통한 인증 방식이었기에, 전체 권한을 가진 ‘슈퍼 관리자’ 토큰이기에 위험도가 극단적으로 높은 보안적인 큰 위험이 있습니다.
- 단 한 번이라도 유출이 된다면 Vault 전체가 뚫리는 것과 같은 큰 문제점을 가지고 있습니다.

https://adjh54.tistory.com/728

[Java] Spring Cloud Vault 이해하고 활용하기-1 : 초기 환경, KV 구성 및 Root Token 인증 방식

adjh54.tistory.com

2. 일반 Token 발급 및 이용 방식(정책 기반 토큰)

일반 Token 발급 및 이용 방식(정책 기반 토큰)

- 이전 Root Token을 이용하는 과정과 다르게 사전 작업에 Root Token을 통해서 전체 권한을 가진 ‘슈퍼 관리자’ 토큰에 대한 위험도를 올리지 않습니다.
- 제한된 Token을 TTL, Max TTL, Renewable ‘토큰 생성 옵션’을 지정하여 제한된 시간을 부여하거나, Vault의 접근 권한에 대한 정책(Policy)을 지정하고 ‘제한된 Token’을 두어서 시간 혹은 접근 권한에 대해서 한정하는 방식입니다.

[ Vault Token 생성 단계 ]

1. [Vault CLI] Root Token에 접근을 합니다.
- Root Token을 통해서 ‘슈퍼 관리자’가 토큰을 발급해 줍니다.

2. [Vault CLI] 특정 기간, 정책을 기반한 Token 생성

- Vault Policy를 통한 Vault 접근 권한에 대한 정책을 생성하고 로드해 옵니다.
- 특정 기간, 정책을 기반한 Token을 생성합니다.
ex) vault token create -policy="read-only-policy" -ttl=24h

3. Token을 Spring Boot 설정에 저장합니다

[Spring Boot 기동 및 Vault 연동 단계]

1. Spring Boot 서버 시작: SpringApplication.run()
- 최초 Spring Boot 서버가 실행이 됩니다.

2. Spring Cloud Vault 자동 구성 로드: bootstrap.yml
- Spring Cloud Bootstrap에서 최초 Vault 설정에 대한 자동 구성이 로드가 됩니다.

3. Vault에 '인증(토큰)' 요청 수행 : 발급된 Token
- Vault의 인증 방식 중 토큰을 이용한 방식에서도 발급된 Token을 통해서 Vault에 인증을 요청합니다.

4. Vault '인증 정보' 검증
- Vault에서는 유효한 토큰인지에 대해 인증 정보에 대해 검증을 합니다.
- 성공 시, KV Secret Engine에 접근합니다.
- 실패 시, 서버 시작 실패와 종료를 합니다.

5. 조회된 Secret을 Spring Boot에 응답
- KV Secret Engine에서 조회된 정보를 응답으로 전달합니다

6. 응답받은 Secret을 Spring Environment(PropertySource)에 자동 주입
- Spring Boot에서는 전달받은 Secret을 Spring Environment(PropertySource)에 자동 주입을 합니다.

7. @ConfigurationProperties VaultKVProperties.java 객체와 자동 매핑
- 추후에 구성할 VaultKVProperties.java 파일 내에 사전에 KV와 같은 형태로 구성한 멤버 변수 각각에 데이터가 매핑이 됩니다.

8. Spring Boot 서버 실행 완료
- 최종 작업이 완료되어서 Spring Boot 서버가 실행이 완료가 됩니다.

[ 더 알아보기 ]

TTL(Time To Live)

- 토큰이 몇 시간 동안 사용할 수 있는가에 대한 초기 유효시간을 의미합니다. 이는 발급과 동시에 유효시간이 부여가 됩니다.
- vault token create -ttl=1h -explicit-max-ttl=24h -renewable=true 해당 명령어와 같이 ttl은 1시간으로 지정이 됩니다.**

Max TTL(Explicit Max TTL)

- 토큰이 갱신이 되더라도 유효한 기간을 의미합니다. TTL을 통해서 토큰의 유효기간을 지정할 수 있지만, 갱신(renew)할 수 있습니다.
- 예를 들어서, TTL이 1시간이고, MAX TTL이 24시간이라고 한다면 해당 발급한 토큰이 1시간이 지나서 만료가 되었을 때, renew를 통해서 24시간 동안 갱신을 할 수 있습니다.
vault token create -ttl=1h -explicit-max-ttl=24h -renewable=true 해당 명령어와 같이 explicit-max-ttl은 24시간으로 지정이 됩니다.

Renewable

- TTL의 연장 여부를 부여함을 의미합니다. true/false의 진위형의 값을 가지고, TTL(Time To Live), Max TTL(Explicit Max TTL)을 부여했는데, Renewable를 false로 한다면 갱신이 되지 않습니다.
- vault token create -ttl=1h -explicit-max-ttl=24h -renewable=false 해당 명령어와 같이 renewable이 false라면, Max TTL(Explicit Max TTL)가 남았더라도 토큰을 갱신할 수 없습니다.**

4) 토큰 발급을 위한 Policy 지정 및 검증

1. 홈 화면에서 Policies 탭을 선택합니다.

2. ‘Create ACL Policy’를 선택합니다

3. KV Secret Engine에 접근할 수 있는 Policy를 지정합니다

KV Secret Engine에 접근할 수 있는 Policy를 지정합니다

- KV Secret Engine으로 kv2라는 공간 내에 실제 데이터가 저장되는 경로로 하위에 모든 것에 대한 권한을 부여합니다
- 권한은 시크릿 내용을 조회(읽기), 목록 조회 기능에 대해서 접근 권한을 부여합니다.

4. 터미널에서 policy 리스트를 확인합니다

터미널에서 policy 리스트를 확인합니다

- 생성된 policy를 확인합니다.

[참고] Error looking up token: Error making API request. 403 Error가 발생한다면?

아래와 같이 VAULT_ADDR와 VAULT_TOKEN를 지정해주어야 합니다.

- 이는 클라이언트가 사용할 인증 토큰을 환경변수로 등록하는 과정입니다. 이는 루트 토큰을 의미합니다.

# Vault 주소와 루트 토큰 주입
export VAULT_ADDR='<http://127.0.0.1:8200>'
export VAULT_TOKEN="hvs.qBlCBqEKIGtJfCA9grVMHbrV" # 루트 토큰

5. Token을 생성해 줍니다.

Token을 생성해 줍니다.

- read-only-policy를 기반으로 vault token을 발급받습니다.

# 기본 형식
$ vault token create -policy="<policy 이름>" -ttl=24h

# 사용 예시
vault token create -policy="read-only-policy" -ttl=24h

[참고] Token 생성은 왜 CLI를 통해서 해야 하는 것일까?

- 토큰 생성은 가장 민감한 보안 작업임. 지나치게 높은 권한을 가진 토큰을 클릭 한 번으로 만들어버릴 수 있기에 공식적으로도 ‘Vault UI는 Token 생성 기능을 제공하지 않는다’라고 이야기하고 있습니다.
- 토큰은 자동화된 시스템/코드에서 발급되는 게 일반적임 사람이 일반적으로 직접 토큰을 만들지 않고 토큰은 코드, CI/CD, 서버 자동화 과정에서 발급이 됩니다.

6. 생성된 토큰을 검증해 줍니다

생성된 토큰을 검증해 줍니다

- 아래와 같이 token에 대해서 검증을 수행합니다.

# 기본 형식
$ vault token lookup <토큰>

7. 발급된 토큰을 기반으로 GUI 내에 접근도 가능합니다.

실제 접근해서 확인해 보면, read-only-policy라는 정책에 맞게 kv2에 대한 읽기 권한만 부여가 되었습니다.

5) Spring Boot 환경 구성

1. 구조 확인: 일반 Token 발급 및 이용 방식(정책 기반 토큰)

구조 확인: 일반 Token 발급 및 이용 방식(정책 기반 토큰)

- 해당 방식에서는 정책에 맞게 토큰을 발급해서 사용자에게 부여를 해주는 방식입니다.
- 기존에 Root Token에 비해 상대적으로 특정 접근 권한(Policy)에 대해서만 지정하기에 안정적입니다.

[Spring Boot 기동 및 Vault 연동 단계]

1. Spring Boot 서버 시작: SpringApplication.run()
- 최초 Spring Boot 서버가 실행이 됩니다.

2. Spring Cloud Vault 자동 구성 로드: bootstrap.yml
- Spring Cloud Bootstrap에서 최초 Vault 설정에 대한 자동 구성이 로드가 됩니다.

3. Vault에 '인증(토큰)' 요청 수행 : 발급된 Token
- Vault의 인증 방식 중 토큰을 이용한 방식에서도 발급된 Token을 통해서 Vault에 인증을 요청합니다.

4. Vault '인증 정보' 검증
- Vault에서는 유효한 토큰인지에 대해 인증 정보에 대해 검증을 합니다.
- 성공 시, KV Secret Engine에 접근합니다.
- 실패 시, 서버 시작 실패와 종료를 합니다.

5. 조회된 Secret을 Spring Boot에 응답
- KV Secret Engine에서 조회된 정보를 응답으로 전달합니다

6. 응답받은 Secret을 Spring Environment(PropertySource)에 자동 주입
- Spring Boot에서는 전달받은 Secret을 Spring Environment(PropertySource)에 자동 주입을 합니다.

7. @ConfigurationProperties VaultKVProperties.java 객체와 자동 매핑
- 추후에 구성할 VaultKVProperties.java 파일 내에 사전에 KV와 같은 형태로 구성한 멤버 변수 각각에 데이터가 매핑이 됩니다.

8. Spring Boot 서버 실행 완료
- 최종 작업이 완료되어서 Spring Boot 서버가 실행이 완료가 됩니다.

2. 개발 환경

개발 환경

- 기본 기능과 주요 라이브러리인 spring-cloud-dependencies, spring-cloud-starter-bootstrap, spring-cloud-starter-vault-config를 설정하였습니다.

개발 환경	분류	버전
Java JDK	Java Version	17
빌드 도구	Gradle	8.14.3
Spring Boot	Spring Boot Starter	3.5.8
Spring Boot Web	Spring Boot Starter	3.5.8
spring-cloud-starter-bootstrap	Spring Boot Cloud	2025.0.0
spring-cloud-starter-vault-config	Spring Boot Cloud	2025.0.0
spring-cloud-dependencies	Spring Boot Cloud	2025.0.0
Lombok	Library	latest

3. 라이브러리 설치 : build.gradle

라이브러리 설치 : build.gradle

- 위에서 명시한 라이브러리를 Gradle을 이용하여서 설치합니다.

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.5.8'
    id 'io.spring.dependency-management' version '1.1.7'
}
ext {
    springCloudVersion = "2025.0.0"
}

group = 'com.adjh'
version = '0.0.1-SNAPSHOT'
description = 'spring-boot3-vault'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'           // Spring Boot Web

    implementation 'org.springframework.cloud:spring-cloud-starter-bootstrap'   // Spring Cloud BootStrap
    implementation 'org.springframework.cloud:spring-cloud-starter-vault-config'// Spring Cloud Vault
    compileOnly 'org.projectlombok:lombok'                                      // Lombok Compile
    annotationProcessor 'org.projectlombok:lombok'                              // Lombok Annotation
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}
dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:$springCloudVersion"
    }
}

tasks.named('test') {
    useJUnitPlatform()
}

4. 시스템 환경변수 주입 : IntelliJ IDE 활용

시스템 환경변수 주입 : IntelliJ IDE 활용

- Vault로 전달이 되는 Main Key 자체를 프로젝트 내에 넣고 Git에 올릴 수 없기에 ‘시스템 환경 변수’ 내에 추가합니다.

[참고] 아래의 환경 변수를 추가하는 방법의 글을 참고하셔도 도움이 됩니다.

[Java] Spring Boot 환경에서 시스템 변수 .env 파일 지정 및 활용 방법

adjh54.tistory.com

4.1. IDE툴 오른쪽 상단에 서버 > 구성 편집.. 버튼을 누릅니다

4.2. 옵션 수정(Modify options) 버튼을 누릅니다.

4.3. 운영 체제(Operating System) > 환경 변수(Environment variables)를 선택합니다

4.4. 환경 변수를 추가했습니다. 이전 단계에서 발급받은 Token 값을 추가하였습니다.

환경 변수를 추가했습니다. 이전 단계에서 발급받은 Token 값을 추가하였습니다.

hvs.CAESIPN1xW04V5X5QEF-1HL5XUbzgydb76tkWjTvB4HgbKm9Gh4KHGh2cy5Xb1NpZHdPejFVZzRjb0RjZDJsZlBtcDM

5. bootstrap.yml 파일을 생성 및 구성합니다.

bootstrap.yml 파일을 생성 및 구성합니다.

- resources 경로 하단에 bootstrap.yml 파일을 생성하였습니다

yml 파일을 아래와 같이 구성하였습니다.

spring:
  cloud:
    vault:
      uri: <http://localhost:8200>   # Vault 서버 주소 (UI 주소 아님, API 엔드포인트)
      authentication: TOKEN        # Vault 인증 방식 (TOKEN, APPROLE, APPID 등)
      token: ${VAULT_MAIN_TOKEN}   # 환경변수에서 Vault 접근 토큰을 불러옴
      connection-timeout: 5000     # Vault 서버 연결 시도 타임아웃(ms)
      read-timeout: 15000          # Vault 데이터 읽기 타임아웃(ms)

      kv:
        enabled: true              # KV(키-값) 비밀 엔진 사용 여부
        backend: kv2               # Vault에서 생성한 엔진 이름(ex: kv2), 반드시 일치해야 함
                                   # 실제 Vault 경로가 "kv2/" 라면 backend도 kv2로 설정해야 함

        default-context: loc       # 기본 Secret 경로 (예: kv2/loc/data/application 같은 구조가 됨)
                                   # 즉, Vault UI에서는 /kv2/data/loc 경로와 매핑됨

        application-name: ''       # Spring 애플리케이션 이름을 Secret 경로에 추가할지 여부
                                   # 빈 값이면 "default-context" 바로 아래에서 조회함
                                   # 예: default: '' → kv2/loc/data

6. 서버 실행

서버 실행

- 정상적으로 오류 없이 서버가 실행하였습니다.

7. Vault 값과 객체 매핑

Vault 값과 객체 매핑

- Vault에서 읽어온 값을 자바 클래스 필드에 자동 바인딩을 하는 클래스입니다.
- @Getter, @Setter 통해서 멤버 변수에 접근할 수 있도록 어노테이션을 지정하였습니다.
- @Component를 빈으로 등록하여서, 다른 서비스나 컴포넌트에 주입하여 사용이 가능하도록 하였습니다.
- @ConfigurationProperties(prefix = "vault") : 상위 prefix 내에 하위에 동일한 이름으로 각각 자동 바인딩이 됩니다.

package com.adjh.springboot3vault.properties;

import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;

/**
 * Vault Key-Value Properties Mapping value
 *
 * @author : leejonghoon
 * @fileName : VaultKVProperties
 * @since : 25. 11. 25.
 */
@Getter
@Setter
@Component
@ConfigurationProperties(prefix = "")
public class VaultKVProperties {
    private String appEnv;
    private String dbHost;
    private String dbPassword;
    private String dbUser;
}

8. 콘솔을 확인하기 위해 Controller를 구성하였습니다.

콘솔을 확인하기 위해 Controller를 구성하였습니다.

- 생성자 패턴으로 bean을 호출하여서 Controller 내에서 활용하도록 구성하였습니다.
- http://localhost:8080 url로 접근하여서 ‘/api/v1/vault/kv’로 호출이 된다면 각각의 vault 값이 정상적으로 출력이 됩니다.

package com.adjh.springboot3vault.controller;

import com.adjh.springboot3vault.properties.VaultKVProperties;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * Bean을 호출하여서 Vault 값을 테스트하기 위한 Controller
 *
 * @author : leejonghoon
 * @fileName : VaultController
 * @since : 25. 11. 25.
 */
@RestController
@RequestMapping("/api/v1/vault")
public class VaultController {

    private final VaultKVProperties vaultKVProperties;

    public VaultController(VaultKVProperties vaultKVProperties) {
        this.vaultKVProperties = vaultKVProperties;
    }

    @GetMapping("/kv")
    public String main() {
        System.out.println("Getter appEnv : " + vaultKVProperties.getAppEnv());
        System.out.println("Getter dbHost : " + vaultKVProperties.getDbHost());
        System.out.println("Getter dbPassword : " + vaultKVProperties.getDbPassword());
        System.out.println("Getter dbUser : " + vaultKVProperties.getDbUser());
        return "임시 테스트 ";
    }
}

9. 결과확인

결과확인

- 정상적으로 출력이 됨을 확인하였습니다.

오늘도 감사합니다.

[Java] Spring Cloud Vault 이해하고 활용하기-1 : 초기 환경, KV 구성 및 Root Token 인증 방식

adjh54 — Thu, 4 Dec 2025 17:53:10 +0900

해당 글에서는 Spring Cloud Vault를 이해하고 Vault를 구성하고 KV Secret Engine 내에서 데이터를 조회하는 토큰 인증방식을 이용하는 방법에 대해 알아봅니다

1) Vault

Vault

- HashCorp 사에서 만든 Vault는 다양한 환경에서 애플리케이션의 외부 비밀 속성(예: 데이터베이스 비밀번호, API 키 등)을 외부화된 구성으로 중앙에서 관리할 수 있습니다.
- Spring Boot 환경에서 Vault로부터 시크릿 정보를 읽어오며 Valut에 시크릿 정보를 쓰는 것도 가능합니다. 이러한 방식으로 애플리케이션의 중요한 정보는 코드에서 분리되어 보안이 보장됩니다.
- 기밀정보의 동적인 제공, 중앙 집중식 시크릿 관리, 즉각적인 액세스 제어, 감사 추적 기능 등을 제공하여, 기업의 보안 정책을 준수하는 데 도움이 됩니다.

https://developer.hashicorp.com/

1. Vault의 특징

특징	설명
기밀정보의 동적 제공	애플리케이션이 필요에 따라 비밀정보를 요청하고, Vault는 요청된 정보를 제공합니다.
중앙 집중식 시크릿 관리	모든 애플리케이션의 시크릿 정보를 중앙에서 관리할 수 있습니다.
즉각적인 액세스 제어	애플리케이션이 Vault에 접근 할 수 있는 ‘특정 토큰 아이디’를 기반으로 Vault 서비스를 호출하고, Vault는 해당 '특정 토큰 아이디'를 수신한 뒤 요청된 '비밀정보'를 제공합니다.
감사 추적 기능	Vault는 모든 액세스 요청을 로깅하여 감사를 위한 추적이 가능합니다.

2. Vault 수행 과정

https://www.baeldung.com/spring-boot-3-1-connectiondetails-abstraction

Vault 수행 과정

1. Spring Boot → Hashicorp Vault: Secret Request(비밀정보 요청)
- Spring Boot 애플리케이션에서는 서버를 실행할 때, Valut에 접근할 수 있는 ‘특정 토큰 아이디’(Secret Request)’ 를 기반으로 Vault 서비스를 호출하여 ‘비밀 정보(Secret)’를 검색합니다.

2. Hashicorp Vault → Spring Boot: Secret Response(비밀정보 응답)
- Valut 서비스는 Spring Boot 애플리케이션의 ‘특정 토큰 아이디’(Secret Request)’를 수신하고 요청된 ‘비밀 정보(Secret)’를 전달합니다.
- 이 단계를 통해서 애플리케이션은 필요한 시크릿 정보를 안전하게 받아올 수 있습니다.

3. Spring Boot → Remote Service : Connection Request(커넥션 요청)
- Spring Boot 애플리케이션이 원격 서비스와 연결을 시도하는 과정을 의미합니다.
- 이 단계에서 애플리케이션은 Vault에서 안전하게 가져온 비밀 정보(예: 데이터베이스 비밀번호, API 키 등)를 사용하여 원격 서비스에 연결 요청을 보냅니다.
- 이렇게 함으로써, 중요한 정보를 코드 내에 직접 작성하거나 노출시키지 않아도 되어 보안을 더 효과적으로 관리할 수 있습니다.

4. Remote Service → Spring Boot : Connection Response(커넥션 연결)
- Vault 서비스가 Spring Boot 애플리케이션의 Secret Request를 수신하고, 요청된 '비밀 정보'를 애플리케이션으로 전송하는 단계입니다.
- 이 단계를 통해 애플리케이션은 필요한 시크릿 정보를 안전하게 받아올 수 있습니다.

[ 더 알아보기 ]

Spring Cloud Vault

- HashiCorp Vault와 Spring 애플리케이션을 연결해 민감한 정보를 안전하게 관리할 수 있도록 돕는 프레임워크입니다.
- 즉, 비밀번호·API 키·DB 접속 정보 같은 시크릿을 외부에 노출하지 않고 중앙에서 안전하게 관리하며, 애플리케이션은 이를 자동으로 가져와 사용할 수 있습니다.
- Spring 애플리케이션이 Vault에 저장된 시크릿을 가져와 Spring 환경에 자동으로 주입합니다.

3. KV(Key-Value) Secret engine

KV(Key-Value) Secret engine

- Vault에 구성된 물리적 저장소 내에 임의의 시크릿을 저장하는 데 사용되는 일반적인 키-값(KV) 저장소입니다.
- 가장 기본적인 정적(Static) 비밀 저장소를 의미합니다. 키-값 형태로 환경변수, API 키, 토큰, 비밀번호 등을 저장하고, 읽고, 업데이트합니다.
- Database 엔진과 같이 동적 Credential 방식과 다르게 만료가 되지 않고, 키에 대한 단일 값을 저장하거나, 각 키에 대해 여러 버전을 저장하고 해당 버전을 기록을 할 수 있습니다.

KV(Key-Value) Secret engine 내에서 KV v1, KV v2가 존재합니다.

분류 항목	KV v1	KV v2
기능	단순 키-값 저장	키-값 저장 + 버전관리
버전 관리	없음	있음
API 구조	/v1/<mount>/<path>	/data, /metadata 데이터: /v1/<mount>/data/<path> 메타데이터: /v1/<mount>/metadata/<path>
삭제	즉시 삭제	soft delete + destroy
CAS(Check-And-Set)	제한적	정식 지원 (동시 업데이트 충돌 방지)
사용 사례	단순한 설정값, 변경 필요 없는 비밀	자주 변경되는 비밀 정보, 롤백/복구가 필요한 비밀정보

3.1. KV Version 1

KV Version 1

- KV(Key-Value) Secret engine에서 물리적인 저장소에 내에 임의의 비밀(Secret)을 저장하는 데 사용이 됩니다.
- KV v2에 비교하여 단순한 키-값만 저장을 하는 용도로 사용이 되며, 별도의 버전관리는 되지 않습니다. 또한, 주로 단순한 설정 값, 변경 필요가 없는 파일에 대해서 관리가 됩니다.

3.2. KV Version 2

KV Version 2

- KV Version1과 동일하게 KV(Key-Value) Secret engine에서 물리적인 저장소에 내에 임의의 비밀(Secret)을 저장하는 데 사용이 됩니다.
- KV v1과 비교하여 키-값 저장을 하는 용도로 사용이 되며, 별도의 버전관리를 수행하여서 이전 버전을 통해서 관리하고 복구할 수 있습니다. 또한, 자주 변경이 되는 비밀, 롤백/복구가 필요한 파일에 대해서 관리가 됩니다.

3) 환경 설정 : 로컬 Docker 설정

환경 설정 : 로컬 Docker 설정

- 아래의 글을 통해서 Docker 기반으로 로컬 Vault 환경을 지정하여 구성하였습니다.

[Docker] Docker로 Vault 로컬 환경 구성 방법

해당 글에서는 Docker 환경에서 Vault를 로컬 환경에 구축하는 방법에 대해서 알아봅니다. 1) Vault Vault- HashCorp 사에서 만든 Vault는 다양한 환경에서 애플리케이션의 외부 비밀 속성(예: 데이터베

adjh54.tistory.com

1. 아래와 같이 Docker로 실행하여 접속을 완료하였습니다

4) 환경 설정 : 사이트 내에 KV 설정

[참고] CLI를 이용한 설정에 대해 궁금하시면 아래의 글을 참고하시면 도움이 됩니다.

kv - Command | Vault | HashiCorp Developer

The "kv" command groups subcommands for interacting with Vault's key/value secret engine.

developer.hashicorp.com

1. Vault에 접속 > Secret Engine > + Enable new engine을 선택합니다.

2. ‘KV’를 선택합니다.

3. Path와 Maximum number of versions 버전을 입력하고 Enable engine 버튼을 누릅니다

항목	설명
Path	Vault에서 이 KV 엔진이 마운트되는 경로입니다. 즉, 엔진이 어떤 URL prefix 아래에 동작할지를 결정하는 항목입니다. 예를 들어서 kv로 Path를 지정하면 kv/…/ 형태로 구성이 됩니다.
Maximum number of versions	KV v2의 버전 관리 기능에서 ‘한 키를 몇 개 버전까지 보관할 것인지’를 설정하는 항목입니다. 예를 들어서 10으로 설정하면, 한 키에서 새 값을 저장할때마다 버전을 증가합니다.
Require Check and Set	“동시 업데이트로 인한 덮어쓰기 방지 기능”입니다. 예를 들어서, 수정으로 인해 버전이 바뀌게 되었을때, 이전 버전이 사라지는 증상을 위해서 직접 지정하는 방식을 의미합니다.
Automate secret deletion	자동 삭제 기능 활성화 기능입니다. 기본 off 상태에서는 반드시 API 또는 UI로 명시적으로 삭제를 해야하고 ON의 경우는 Lifecycle 정책에 따라서 자동삭제가 수행이 됩니다.

[ 더 알아보기 ]

Vault의 KV 버전은 어떻게 관리되는 걸까?

- 아래의 KV 파일 내에 변경이 발생하는 경우, 버전 이전과 버전 이후를 비교하여 변경된 값이 있으면 버전이 증가가 됩니다.
- 예를 들어서 버전을 10으로 지정한 경우, 현재 10번째 버전이라고 했을 때 수정이 발생하면, 기존에 v1은 자동 제거가 되고, 계속 뒤에 버전관리가 되는 형태입니다.
- Vault의 특정 과거 버전으로 롤백을 하는 경우에 ‘Maximum number of versions’ 값을 적게 지정한다면 자동 제거된 버전은 롤백이 불가능합니다.

// 버전 이전
{
  "username": "admin",
  "password": "1234"
}

// 버전 이후 
{
  "username": "admin",
  "password": "5678"
}

4. 아래와 같이 KV Secret engine이 생성되었고, ‘Create secret’ 버튼을 누릅니다.

5. kv2의 하위 경로로 Path for this secret을 입력합니다.

kv2의 하위 경로로 Path for this secret을 입력합니다.

- 임시로 /loc라는 경로로 입력하였고, KV 값을 입력하고 ‘save’ 버튼을 누릅니다.

6. Secret 탭을 확인하면 아래와 같이 ‘loc’ Path 내에 정상적으로 값이 정의된 것을 확인할 수 있습니다

7. 상위 prefix를 지정하는 구조로 재구성하기 위해 ‘Create new version’ 버튼을 누릅니다.

7. JSON 버튼을 활성화하고, prefix로 vault를 추가하였습니다

{
  "vault": {
    "app_env": "loc",
    "db_host": "localhost",
    "db_password": "localmaster",
    "db_user": "localmaster"
  }
}

8. 최종적으로 아래와 같은 구조가 완성되었습니다.

5) 환경 설정 : Spring Boot 환경에서 Vault 접근

환경 설정 : Spring Boot 환경에서 Vault 접근

1. 구조 확인

구조 확인
- 최초 Spring Boot 서버가 실행되면서 아래의 프로세스가 동작을 합니다.

1. Spring Boot 서버 시작: SpringApplication.run()
- 최초 Spring Boot 서버가 실행이 됩니다.

2. Spring Cloud Vault 자동 구성 로드: bootstrap.yml
- Spring Cloud Bootstrap에서 최초 Vault 설정에 대한 자동 구성이 로드가 됩니다.

3. Vault에 '인증(토큰)' 요청 수행 : Root Token
- Vault의 인증 방식 중 토큰을 이용한 방식에서도 Root Token을 통해서 Vault에 인증을 요청합니다.

4. Vault '인증 정보' 검증
- Vault에서는 유효한 토큰인지에 대해 인증 정보에 대해 검증을 합니다.
- 성공 시, KV Secret Engine에 접근합니다.
- 실패 시, 서버 시작 실패와 종료를 합니다.

5. 조회된 Secret을 Spring Boot에 응답
- KV Secret Engine에서 조회된 정보를 응답으로 전달합니다

6. 응답받은 Secret을 Spring Environment(PropertySource)에 자동 주입
- Spring Boot에서는 전달받은 Secret을 Spring Environment(PropertySource)에 자동 주입을 합니다.

7. @ConfigurationProperties VaultKVProperties.java 객체와 자동 매핑
- 추후에 구성할 VaultKVProperties.java 파일 내에 사전에 KV와 같은 형태로 구성한 멤버 변수 각각에 데이터가 매핑이 됩니다.

8. Spring Boot 서버 실행 완료
- 최종 작업이 완료되어서 Spring Boot 서버가 실행이 완료가 됩니다.

2. 개발 환경

개발 환경

- 기본 기능과 주요 라이브러리인 spring-cloud-dependencies, spring-cloud-starter-bootstrap, spring-cloud-starter-vault-config를 설정하였습니다.

개발 환경	분류	버전
Java JDK	Java Version	17
빌드 도구	Gradle	8.14.3
Spring Boot	Spring Boot Starter	3.5.8
Spring Boot Web	Spring Boot Starter	3.5.8
spring-cloud-starter-bootstrap	Spring Boot Cloud	2025.0.0
spring-cloud-starter-vault-config	Spring Boot Cloud	2025.0.0
spring-cloud-dependencies	Spring Boot Cloud	2025.0.0
Lombok	Library	latest

3. 라이브러리 설치 : build.gradle

라이브러리 설치 : build.gradle
- 위에서 명시한 라이브러리를 Gradle을 이용하여서 설치합니다.

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.5.8'
    id 'io.spring.dependency-management' version '1.1.7'
}
ext {
    springCloudVersion = "2025.0.0"
}

group = 'com.adjh'
version = '0.0.1-SNAPSHOT'
description = 'spring-boot3-vault'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'           // Spring Boot Web

    implementation 'org.springframework.cloud:spring-cloud-starter-bootstrap'   // Spring Cloud BootStrap
    implementation 'org.springframework.cloud:spring-cloud-starter-vault-config'// Spring Cloud Vault
    compileOnly 'org.projectlombok:lombok'                                      // Lombok Compile
    annotationProcessor 'org.projectlombok:lombok'                              // Lombok Annotation
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}
dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:$springCloudVersion"
    }
}

tasks.named('test') {
    useJUnitPlatform()
}

4. 시스템 환경변수 주입 : IntelliJ IDE 활용

시스템 환경변수 주입 : IntelliJ IDE 활용

- Vault로 전달이 되는 Root Token 자체를 프로젝트 내에 넣고 Git에 올릴 수 없기에 ‘시스템 환경 변수’ 내에 추가합니다.

[참고] 아래의 환경 변수를 추가하는 방법의 글을 참고하셔도 도움이 됩니다.

[Java] Spring Boot 환경에서 시스템 변수 .env 파일 지정 및 활용 방법

adjh54.tistory.com

4.1. IDE툴 오른쪽 상단에 서버 > 구성 편집.. 버튼을 누릅니다

4.2. 옵션 수정(Modify options) 버튼을 누릅니다.

4.3. 운영 체제(Operating System) > 환경 변수(Environment variables)를 선택합니다

4.4. 환경 변수를 추가했습니다. 값은 Docker에서 발급받은 Initial Root Token 값을 넣고 수행을 하였습니다

환경 변수를 추가했습니다. 값은 Docker에서 발급받은 Initial Root Token 값을 넣고 수행을 하였습니다

VAULT_MAIN_TOKEN=hvs.qBlCBqEKIGtJfCA9grVMHbrV;

아래에 최초 Vault init을 실행할 때 발급받은 키입니다.

5. bootstrap.yml 파일을 생성 및 구성합니다.

bootstrap.yml 파일을 생성 및 구성합니다.

- resources 경로 하단에 bootstrap.yml 파일을 생성하였습니다

yml 파일을 아래와 같이 구성하였습니다.

spring:
  cloud:
    vault:
      uri: <http://localhost:8200>   # Vault 서버 주소 (UI 주소 아님, API 엔드포인트)
      authentication: TOKEN        # Vault 인증 방식 (TOKEN, APPROLE, APPID 등)
      token: ${VAULT_MAIN_TOKEN}   # 환경변수에서 Vault 접근 토큰을 불러옴
      connection-timeout: 5000     # Vault 서버 연결 시도 타임아웃(ms)
      read-timeout: 15000          # Vault 데이터 읽기 타임아웃(ms)

      kv:
        enabled: true              # KV(키-값) 비밀 엔진 사용 여부
        backend: kv2               # Vault에서 생성한 엔진 이름(ex: kv2), 반드시 일치해야 함
                                   # 실제 Vault 경로가 "kv2/" 라면 backend도 kv2로 설정해야 함

        default-context: loc       # 기본 Secret 경로 (예: kv2/loc/data/application 같은 구조가 됨)
                                   # 즉, Vault UI에서는 /kv2/data/loc 경로와 매핑됨

        application-name: ''       # Spring 애플리케이션 이름을 Secret 경로에 추가할지 여부
                                   # 빈 값이면 "default-context" 바로 아래에서 조회함
                                   # 예: default: '' → kv2/loc/data

6. 서버 실행

서버 실행

- 정상적으로 오류 없이 서버가 실행하였습니다.

7. Vault 값과 객체 매핑: @ConfigurationProperties

Vault 값과 객체 매핑: @ConfigurationProperties

- Vault에서 읽어온 값을 자바 클래스 필드에 자동 바인딩을 하는 클래스입니다.

- @Getter, @Setter 통해서 멤버 변수에 접근할 수 있도록 어노테이션을 지정하였습니다.
- @Component를 빈으로 등록하여서, 다른 서비스나 컴포넌트에 주입하여 사용이 가능하도록 하였습니다.
- @ConfigurationProperties(prefix = "vault") : 상위 prefix 내에 하위에 동일한 이름으로 각각 자동 바인딩이 됩니다.

package com.adjh.springboot3vault.properties;

import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;

/**
 * Vault Key-Value Properties Mapping value
 *
 * @author : leejonghoon
 * @fileName : VaultKVProperties
 * @since : 25. 11. 25.
 */
@Getter
@Setter
@Component
@ConfigurationProperties(prefix = "")
public class VaultKVProperties {
    private String appEnv;
    private String dbHost;
    private String dbPassword;
    private String dbUser;
}

8. 콘솔을 확인하기 위해 Controller를 구성하였습니다.

콘솔을 확인하기 위해 Controller를 구성하였습니다.

- 생성자 패턴으로 bean을 호출하여서 Controller 내에서 활용하도록 구성하였습니다.
- http://localhost:8080 포트로 접근하여서 호출이 된다면 각각의 vault 값이 정상적으로 출력이 됩니다.

package com.adjh.springboot3vault.controller;

import com.adjh.springboot3vault.properties.VaultKVProperties;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * Bean을 호출하여서 Vault 값을 테스트하기 위한 Controller
 *
 * @author : leejonghoon
 * @fileName : VaultController
 * @since : 25. 11. 25.
 */
@RestController
public class VaultController {

    private final VaultKVProperties vaultKVProperties;

    public VaultController(VaultKVProperties vaultKVProperties) {
        this.vaultKVProperties = vaultKVProperties;
    }

    @GetMapping("/")
    public String main() {
        System.out.println("Getter appEnv : " + vaultKVProperties.getAppEnv());
        System.out.println("Getter dbHost : " + vaultKVProperties.getDbHost());
        System.out.println("Getter dbPassword : " + vaultKVProperties.getDbPassword());
        System.out.println("Getter dbUser : " + vaultKVProperties.getDbUser());
        return "임시 테스트 ";
    }
}

9. 결과확인

결과확인

- 정상적으로 출력이 됨을 확인하였습니다.

오늘도 감사합니다.

[Java] Spring Boot Dotenv 이해하고 활용하기 -1 : .env 로드, .yml 매핑 로드

adjh54 — Tue, 2 Dec 2025 18:19:44 +0900

해당 글에서는 Spring Boot 환경에서 Dotenv 오픈소스 라이브러리를 이용하여서 .env 파일을 불러오거나 .env 파일을 yml 파일 형태로 매핑하여 불러오는 방법에 대해 알아봅니다.

1) Spring Boot Dotenv

Spring Boot Dotenv

- Java와 Kotlin에서 .env 파일을 쉽게 로드하여 환경 변수처럼 사용할 수 있게 해주는 오픈소스 라이브러리를 의미합니다.
- 즉, 프로젝트의 루트 경로에 .env 파일 내에 KV 형태로 변수를 두고 환경 변수로써 사용하는 방식입니다.
- Spring Boot 내에서는 Node 환경과 다르게 .env 파일을 직접 읽어올 수 없고 대신 OS 환경 변수, application.properties, yaml 등을 읽어 올 수 있습니다.

[참고] dotenv-java 오픈소스 라이브러리 사이트

https://github.com/cdimascio/dotenv-java

[참고] .env 파일 자체를 주입하는 방법에 대해 궁금하시면 아래의 글을 참고하시면 도움이 됩니다.

[Java] Spring Boot 환경에서 시스템 변수 .env 파일 지정 및 활용 방법

adjh54.tistory.com

2) Spring Boot Dotenv 공통 환경설정

1. build.gradle

build.gradle

- 가장 최신버전으로 설치를 해줍니다. 참고로 Java 11 버전에서 수행이 된다고 합니다.

// <https://mvnrepository.com/artifact/io.github.cdimascio/dotenv-java>
implementation("io.github.cdimascio:dotenv-java:3.2.0")

[참고] Java 8 버전에서도 실행이 될까?

- Spring Boot 1.x.x 버전의 Java 8 버전에서 실행이 되는 버전은 2.3.2입니다.

https://github.com/cdimascio/dotenv-java?tab=readme-ov-file#install

 <dependency>
    <groupId>io.github.cdimascio</groupId>
    <artifactId>dotenv-java</artifactId>
    <version>2.3.2</version> <!-- Java 8 호환 버전 -->
</dependency>

2. .env

.env

- 불러올 값들이 저장된 파일로 루트 경로에 위치해 둡니다.

APP_ENV=loc
DB_HOST=8080
DB_USER=localhost
TEST_KEY=None

3. application.yml

application.yml

- 해당 과정은 .env 파일을 .properties 형식으로 읽어 들이기 위한 설정입니다.

- config.import : 외부 설정 파일을 애플리케이션 설정에 추가로 로드를 하겠음을 지정합니다.

- optional:file:.env[.properties] :
1. optional: 해당 파일이 없어도 에러 없이 무시하고 애플리케이션을 계속 실행합니다.
2. file:.env[.properties]: .env 파일을 .properties 형식으로 해석해서 읽겠다는 의미입니다.

spring:
  application:
    name: spring-boot-dotenv
  # 해당 부분 추가
  config:
    import: optional:file:.env[.properties]

2) Spring Boot Dotenv 환경설정 및 활용 - 1: .env 파일 정보 가져오기

Spring Boot Dotenv 환경설정 및 활용 - 1: .env 파일 정보 가져오기

- 해당 부분에서는 .env 파일을 즉시 읽어서 각각의 값을 불러오는 과정입니다.

1. 프로세스 확인

프로세스 확인

1. Spring Boot 서버를 실행합니다
- 서버 실행 이후 @Configuration 어노테이션으로 설정 정보가 세팅이 됩니다.

- 사용자 지정한 DotEnvCofig.java 파일 내에 함수가 실행이 됩니다.
1.1. DotEnvConfig 생성자로 Dotenv 클래스를 불러와서 로드를 수행하여서 dotenv 멤버변수에 세팅을 합니다.
1.2. dotenv() 함수로 구성한 값을 Bean에 등록을 합니다
- Spring Boot 서버가 실행이 완료가 되었을 때 값은 모두 세팅이 된 상태가 됩니다.

3. 사용자가 특정 URI로 접근을 합니다.
- 접근을 하는 Controller 내에서는 생성자로 Dotenv를 생성합니다. 그리고 생성한 생성자의 Dotenv의 객체의 .get()메서드를 통해서 .env 키 값을 넣고 값을 조회합니다.
- 최종적으로 데이터가 조회가 됩니다.

2. DotEnvConfig

DotEnvConfig

- DotEnvConfig 생성자로 Dotenv 클래스를 불러와서 로드를 수행하여서 dotenv 멤버 변수에 세팅을 합니다.
- dotenv() 함수로 구성한 값을 Bean에 등록을 합니다

package com.adjh.springbootdotenv.config;

import io.github.cdimascio.dotenv.Dotenv;
import jakarta.annotation.PostConstruct;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * DotEnv 환경설정
 *
 * @author : leejonghoon
 * @fileName : DotEnvConfig
 * @since : 25. 12. 01.
 */
@Configuration
public class DotEnvConfig {

    private final Dotenv dotenv;

    /**
     * DotEnv 로드 및 데이터 조회
     */
    public DotEnvConfig() {
        this.dotenv = Dotenv.configure()
                .ignoreIfMalformed()
                .ignoreIfMissing()
                .load();
    }

    @Bean
    public Dotenv dotenv() {
        return this.dotenv;
    }
}

3. 데이터 불러오기

데이터 불러오기

- Bean에 등록된 Dotenv 클래스를 생성자로 불러옵니다. 그리고 생성한 생성자의 Dotenv의 객체의 .get()메서드를 통해서 .env 키 값을 넣고 값을 조회합니다.
- 최종적으로 데이터가 조회가 됩니다.

package com.adjh.springbootdotenv.controller;

import io.github.cdimascio.dotenv.Dotenv;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * Env 불러오는 Controller
 *
 * @author : leejonghoon
 * @fileName : DotEnvController
 * @since : 25. 12. 2.
 */
@RestController
public class DotEnvController {

//    @Autowired
//    private Dotenv dotenv;

    // or

    private final Dotenv dotenv;

    public DotEnvController(Dotenv dotenv) {
        this.dotenv = dotenv;
    }

    @GetMapping("/")
    public String main() {
        String appEnv = dotenv.get("APP_ENV");
        String dbHost = dotenv.get("DB_HOST");
        String dbUser = dotenv.get("DB_USER");
        String testKey = dotenv.get("TEST_KEY");

        System.out.println("App env: " + appEnv);
        System.out.println("DB host: " + dbHost);
        System.out.println("DB user: " + dbUser);
        System.out.println("Test key: " + testKey);
        return "임시 테스트 ";
    }
}

아래와 같이 정상적으로 출력이 됨을 확인하였습니다.

3) Spring Boot Dotenv 환경설정 - 2: .env 파일을 yaml 파일 내 매핑(@Value 로드)

Spring Boot Dotenv 환경설정 - 2: .env 파일을 yaml 파일 내 매핑(@Value 로드)

- 해당 처리과정은 .env 파일 내에 값을 불러와서 yaml 파일 내에 ${”키”} 값 형태로 매핑을 하여, 최종적으로 yaml 파일 자체를 코드 내에서 이용하는 방식입니다.
- 해당 방식을 이용하면 .env만을 사용하는 방식에 반해 yaml 파일 내에 명시된 값을 기반으로 관리가 편리해지고, 중앙화를 하여서 키 값을 관리할 수 있다는 점입니다. 각각의 값을 가져오는 @Value 어노테이션을 활용하여 조회합니다.

1. 프로세스

프로세스 확인

1. Spring Boot 서버를 실행합니다

2. 서버 실행 이후 @Configuration 어노테이션으로 설정 정보가 세팅이 됩니다.
- 사용자 지정한 DotEnvCofig.java 파일 내에 함수가 실행이 됩니다.
1. 정적블록(static{})을 이용하여서 클래스가 처음 로딩될 때 한 번만 실행하도록 합니다.
2. Dotenv 객체를 로드해 옵니다.
3. DotEnv 로드된 값을 기반으로 순회하여 properties 값 세팅합니다.

- Spring Boot 서버가 실행이 완료가 되었을 때, 값은 application.yml 파일 내에 모두 세팅이 된 상태입니다.

3. 사용자가 특정 URI로 접근을 합니다.
- @Value를 통해서 매핑된 yml 파일 내에 application.yml 파일 내의 속성을 각각 조회합니다.
- 최종적으로 데이터가 조회가 됩니다.

2. application.yml

application.yml

- .env 키 값과 동일한 값으로 각각을 불러옵니다.

spring:
  application:
    name: spring-boot-dotenv
  # 해당 부분 추가
  config:
    import: optional:file:.env[.properties]

# env 파일의 key값 참조
custom:
  appEnv: ${APP_ENV}
  dbHost: ${DB_HOST}
  dbUser: ${DB_USER}
  testKey: ${TEST_KEY}

[참고] .env 파일

3. DotenvConfig

DotenvConfig

- 사용자 지정한 DotEnvCofig.java 파일 내에 함수가 실행이 됩니다.

1. 정적블록(static{})을 이용하여서 클래스가 처음 로딩될 때 한 번만 실행하도록 합니다.
2. Dotenv 객체를 로드해옵니다.DotEnv 로드된 값을 기반으로 순회하여 System.setProperty를 통해서 값을 세팅합니다.

- Spring Boot 서버가 실행이 완료가 되었을 때, 값은 application.yml 파일 내에 모두 세팅이 된 상태입니다.

package com.kids.schole.config;

import io.github.cdimascio.dotenv.Dotenv;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import javax.annotation.PostConstruct;

/**
 * DotEnv 환경설정
 *
 * @author : leejonghoon
 * @fileName : DotEnvConfig
 * @since : 25. 12. 01.
 */
@Configuration
public class DotEnvConfig {

    static {
        /*
         * DotEnv 로드 및 데이터 조회
         */
        Dotenv dotenv = Dotenv.configure()
                .ignoreIfMalformed()
                .ignoreIfMissing()
                .load();

        /*
         * DotEnv 로드된 값을 기반으로 순회하여 properties 값 세팅
         */
        dotenv.entries().forEach(entry ->
                System.setProperty(entry.getKey(), entry.getValue())
        );
    }
}

4. Controller

Controller

- @Value를 통해서 매핑된 yml 파일 내에 application.yml 파일 내의 속성을 각각 조회합니다.
- 최종적으로 데이터가 조회가 됩니다.

package com.adjh.springbootdotenv.controller;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

/**
 * Please explain the class!!
 *
 * @author : leejonghoon
 * @fileName : DotEnvController
 * @since : 25. 12. 1.
 */
@RestController
public class DotEnvController {

    @Value("${custom.appEnv}")
    private String appEnv;

    @Value("${custom.dbHost}")
    private String dbHost;

    @Value("${custom.dbUser}")
    private String dbUser;

    @Value("${custom.testKey}")
    private String testkey;

    @GetMapping("/")
    public String main() {
        System.out.println("Getter appEnv : " + appEnv);
        System.out.println("Getter dbHost : " + dbHost);
        System.out.println("Getter dbUser : " + dbUser);
        System.out.println("Getter testKey : " + testkey);
        return "임시 테스트 ";
    }
}

아래와 같이 정상적으로 .env의 값을 properties를 통해서 가져왔습니다.

4) Spring Boot Dotenv 환경설정 - 2: .env 파일을 yaml 파일 내 매핑(Properties 로드)

Spring Boot Dotenv 환경설정 - 2: .env 파일을 yaml 파일 내 매핑(Properties 로드)

- 해당 처리과정은 .env 파일 내에 값을 불러와서 yaml 파일 내에 ${”키”} 값 형태로 매핑을 하여, 최종적으로 yaml 파일 자체를 코드 내에서 이용하는 방식입니다.
- 해당 방식을 이용하면 .env만을 사용하는 방식에 반해 yaml 파일 내에 명시된 값을 기반으로 관리가 편리해지고, 중앙화를 하여서 키 값을 관리할 수 있다는 점입니다.
- 각각의 값을 가져오는 @ConfigurationProperties 매핑하여 yml 파일 값을 객체의 멤버 변수로 매핑하여서 조회합니다.

1. 프로세스

프로세스 확인

1. Spring Boot 서버를 실행합니다

2. 서버 실행 이후 @Configuration 어노테이션으로 설정 정보가 세팅이 됩니다.

- 사용자 지정한 DotEnvCofig.java 파일 내에 함수가 실행이 됩니다.
2.1. 정적블록(static{})을 이용하여서 클래스가 처음 로딩될 때 한 번만 실행하도록 합니다.
2.2. Dotenv 객체를 로드해 옵니다.
2.3. DotEnv 로드된 값을 기반으로 순회하여 properties 값 세팅합니다.

- Spring Boot 서버가 실행이 완료가 되었을 때, 값은 application.yml 파일 내에 모두 세팅이 된 상태입니다.

3. 사용자가 특정 URI로 접근을 합니다.

- @Value를 통해서 매핑된 yml 파일 내에 application.yml 파일 내의 속성을 각각 조회합니다.
- 최종적으로 데이터가 조회가 됩니다.

2. application.yml

application.yml

- .env 키 값과 동일한 값으로 각각을 불러옵니다.

spring:
  application:
    name: spring-boot-dotenv
  # 해당 부분 추가
  config:
    import: optional:file:.env[.properties]

# env 파일의 key값 참조
custom:
  appEnv: ${APP_ENV}
  dbHost: ${DB_HOST}
  dbUser: ${DB_USER}
  testKey: ${TEST_KEY}

[참고] .env 파일

3. CustomProperties

CustomProperties

- yaml 파일의 키 값을 기반으로 매핑된 멤버 변수들을 정의합니다.

package com.adjh.springbootdotenv.config.properties;

import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

/**
 * Properties 파일로 정의
 *
 * @author : leejonghoon
 * @fileName : CustomProperties
 * @since : 25. 12. 2.
 */
@Getter
@Setter
@Configuration
@ConfigurationProperties(prefix = "custom")
public class CustomProperties {
    private String appEnv;
    private String dbHost;
    private String dbUser;
    private String testKey;
}

4. Controller

Controller

- 사전에 구성한 CustomProperties 클래스 파일을 생성자로 만들어서 getter()를 통해서 데이터를 불러옵니다.

package com.adjh.springbootdotenv.controller;

import com.adjh.springbootdotenv.config.properties.CustomProperties;
import io.github.cdimascio.dotenv.Dotenv;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

/**
 * Please explain the class!!
 *
 * @author : leejonghoon
 * @fileName : DotEnvController
 * @since : 25. 12. 1.
 */
@RestController
public class DotEnvController {

//    @Autowired
//    private CustomProperties customProperties;

    // or

    private final CustomProperties customProperties;

    public DotEnvController(CustomProperties customProperties) {
        this.customProperties = customProperties;
    }

    @GetMapping("/")
    public String main() {

        System.out.println("Getter appEnv :" + customProperties.getAppEnv());
        System.out.println("Getter dbHost :" + customProperties.getDbHost());
        System.out.println("Getter dbUser :" + customProperties.getDbUser());
        System.out.println("Getter testKey :" + customProperties.getTestKey());
        return "임시 테스트 ";
    }
}

아래와 같이 정상적으로 .env의 값을 properties를 통해서 가져왔습니다.

오늘도 감사합니다.

[Java] 자원누수 개선 방법: finally, try-with-resources 활용

adjh54 — Fri, 21 Nov 2025 13:07:06 +0900

해당 글에서는 SAST를 수행하는 도중에 발생한 자원누수 문제를 해결하기 위한 방법에 대해서 알아봅니다.

1) 자원누수

자원누수

- 자원 누수는 파일, 소켓 핸들 등 리소스를 할당한 후에 해제를 하지 않으면 GC에서 자동으로 처리를 할 수 없어서 자원이 누수가 되는 문제를 의미합니다.
- 그렇기에 개발자는 리소스를 해제하는 close()를 호출하여서 할당된 리소스를 해제하여 자원누수를 막아야 합니다.

자원 종류	대표 클래스	설명
파일 I/O 스트림	FileInputStream, FileOutputStream	파일을 읽고 쓰기 위한 기본 byte 스트림
버퍼 기반 스트림	BufferedReader, BufferedWriter	버퍼링을 적용한 고수준 문자 스트림. 성능 향상 목적
네트워크 소켓	Socket, ServerSocket	TCP 네트워크 통신을 위한 소켓
기본 스트림	InputStream, OutputStream	모든 스트림의 최상위 추상 클래스
JDBC 커넥션	Connection	DB 연결 객체
JDBC 명령	PreparedStatement	SQL 실행을 위한 PreparedStatement
JDBC 결과 집합	ResultSet	SQL 실행 결과를 담는 객체

1. 자원누수 해결 중 문제가 되는 부분

자원누수 해결 중 문제가 되는 부분

- close() 자체만을 호출만 하면 문제가 발생할 수 있습니다.
- 아래의 코드와 같이 FileInputStream를 이용하고, 같은 스코프 내에서 close()를 호출하는 경우 도중에 '처리 중에 예외가 발생'하면 close()까지 도달하지 못하여 자원 누수가 발생할 수 있습니다.

FileInputStream fis = new FileInputStream("a.txt");
int data = fis.read();
// 처리 중 예외 발생
fis.close(); // 도달하지 못함 → 자원 누수 발생

2) 자원 누수 해결방안-1 : finally

자원 누수 해결방안-1 : finally

- 위에서 자원누수를 해결하기 위해 close()를 수행했을 때, 블록 내에서 예외가 발생하는 경우에 close()까지 도달하지 못하여서 자원이 누수되는 문제가 있었습니다.
- 이에 대해서 try ~ catch ~ finally 구문을 이용하여서 예외가 발생하더라도 finally에서 처리하는 방안을 이용합니다.

try {
    // 예외가 발생할 가능성이 있는 코드
} catch (예외타입 e) {
    // 예외가 발생했을 때 실행되는 코드
} finally {
    // 예외 발생 여부와 상관없이 항상 실행되는 코드
}

1. 적용 이전 코드

적용 이전 코드

- 아래와 같은 함수가 있습니다. 해당 함수에서는 Socket, DataOutputStream, DataInputStream 객체를 사용하며 리소스를 할당하고 있습니다.
- 그리고 블록 내에 각각에 대해서 close()를 통해서 리소스 할당 해제를 하고 있습니다. 하지만, 이 경우에 도중에 로직 내에서 문제가 생겨서 예외가 발생한다면 close()를 수행하지 못하는 상황입니다. 이 경우에 자원이 누수가 발생합니다.

import java.io.DataInputStream;
import java.io.DataOutputStream;
import java.net.Socket;

public void sendHello(String ip, int port) throws IOException {
      Socket socket = new Socket(ip, port);
      DataOutputStream dos = new DataOutputStream(socket.getOutputStream());
      DataInputStream dis = new DataInputStream(socket.getInputStream());

      socket.setSoTimeout(3000);

      // 메시지 전송
      dos.writeUTF("HELLO");
      dos.flush();

      // 응답 읽기
      String response = dis.readUTF();
      System.out.println("서버 응답: " + response);

      socket.close();
      dos.close();
      dis.close();
  }

2. 적용 이후 코드

적용 이후 코드

- 적용 이전의 코드를 기반으로 finally를 이용하여서 로직내에서 문제가 생겨서 예외가 발생하는 경우 대비하여 예외가 발생하더라도 finally 내에서 반드시 처리하고 넘어가도록 하는 방식입니다.
- 또한 close() 내에서 예외처리가 발생할 수 있기에 이 또한 try ~ catch 구문을 포함합니다. 그리고 중요한 부분은 close()는 각각 참조를 하고 있기에 역순으로 항상 닫아줍니다.

import java.io.DataInputStream;
import java.io.DataOutputStream;
import java.io.IOException;
import java.net.Socket;

public void sendHello(String ip, int port) throws IOException {
    Socket socket = null;
    DataOutputStream dos = null;
    DataInputStream dis = null;

    try {
        socket = new Socket(ip, port);
        dos = new DataOutputStream(socket.getOutputStream());
        dis = new DataInputStream(socket.getInputStream());
        socket.setSoTimeout(3000);

        // 메시지 전송
        dos.writeUTF("HELLO");
        dos.flush();

        // 응답 읽기
        String response = dis.readUTF();
        System.out.println("서버 응답: " + response);

    } catch (IOException e) {
        System.err.println("통신 중 오류 발생: " + e.getMessage());
        throw e; 
    } finally {
        // 역순으로 닫기
        if (dis != null) {
            try {
                dis.close();
            } catch (IOException e) {
                System.err.println("DataInputStream close error: " + e.getMessage());
            }
        }

        if (dos != null) {
            try {
                dos.close();
            } catch (IOException e) {
                System.err.println("DataOutputStream close error: " + e.getMessage());
            }
        }

        if (socket != null && !socket.isClosed()) {
            try {
                socket.close();
            } catch (IOException e) {
                System.err.println("Socket close error: " + e.getMessage());
            }
        }
    }
}

3) 자원 누수 해결방안-2: try-with-resources

자원 누수 해결방안-2: try-with-resources

- Java 7부터 도입된 문법으로 try(…) { } 안에 AutoCloseable 혹은 Closeable 인터페이스를 구현한 객체를 선언하면 try 블록이 끝나는 순간 자동으로 close()가 호출이 되는 형태입니다.

try (자원 생성) {
    // 자원을 사용하는 코드
} catch (예외) {
    // 예외 처리
}

1. 적용 이전 코드

적용 이전 코드
- 함수 내에 블록 내에 각각에 대해서 close()를 통해서 리소스 할당 해제를 하고 있습니다. 이 경우에 도중에 로직 내에서 문제가 생겨서 예외가 발생한다면 close()를 수행하지 못하는 상황입니다. 이 경우에 자원이 누수가 발생합니다.

import java.io.DataInputStream;
import java.io.DataOutputStream;
import java.net.Socket;

public void sendHello(String ip, int port) throws IOException {
      Socket socket = new Socket(ip, port);
      DataOutputStream dos = new DataOutputStream(socket.getOutputStream());
      DataInputStream dis = new DataInputStream(socket.getInputStream());

      socket.setSoTimeout(3000);

      // 메시지 전송
      dos.writeUTF("HELLO");
      dos.flush();

      // 응답 읽기
      String response = dis.readUTF();
      System.out.println("서버 응답: " + response);

      socket.close();
      dos.close();
      dis.close();
  }

2. 적용 이후 코드

적용 이후 코드

- 이전 finally를 이용한 방식을 통해서도 처리가 가능하지만 소스코드가 길어지는 문제가 있고 가독성이 떨어지는 문제가 있었습니다.
- 그렇기에 try-with-resources를 통해서 선언과 동시에 close()를 이용하는 방식을 이용합니다
- 아래와 같이 try 구문내에서 선언하여서 블록 종료 시 close()가 수행이 되도록 하는 방식을 이용합니다.

import java.io.DataInputStream;
import java.io.DataOutputStream;
import java.io.IOException;
import java.net.Socket;

public void sendHello(String ip, int port) throws IOException {

    try (
        Socket socket = new Socket(ip, port);
        DataOutputStream dos = new DataOutputStream(socket.getOutputStream());
        DataInputStream dis = new DataInputStream(socket.getInputStream());
    ) {

        socket.setSoTimeout(3000);

        // 메시지 전송
        dos.writeUTF("HELLO");
        dos.flush();

        // 응답 읽기
        String response = dis.readUTF();
        System.out.println("서버 응답: " + response);
    }
    // 여기서 socket, dos, dis 자동으로 close됨
}

오늘도 감사합니다.

[Git] Github 레포지토리 변경(이관) 방법 : 동일 계정간/다른 계정간 이관

adjh54 — Tue, 18 Nov 2025 16:12:15 +0900

해당 글에서는 Github 환경에서 레포지토리의 변경(이관) 방법으로 하나의 계정 내에서 이관하는 방법과 다른 계정으로 이관하는 방법에 대해 알아봅니다

1) Git 레포지토리 변경(이관) 방법 : 동일한 계정

Git 레포지토리 변경(이관) 방법 : 동일한 계정

- 이를 위해서 git의 Mirroring a repository을 이용하려고 합니다.

Duplicating a repository - GitHub Docs

To maintain a mirror of a repository without forking it, you can run a special clone command, then mirror-push to the new repository.

docs.github.com

분류	약칭	레포지토리 명
이관하려는 레포지토리	old-repo	spring-boot-3-vault
이관받는 레포지토리	new-repo	temp-spring-boot-3-vault

1. Github 내에 이관받을 레포지토리를 생성합니다.

Github내에 이관받을 레포지토리를 생성합니다.

- 아래와 같이 Repository를 새로 생성하였습니다.

2. 이관되는 위치를 지정합니다

이관되는 위치를 지정합니다

- 이관되는 레포지토리의 경로를 지정합니다.
- new-repo의 경우는 실제 프로젝트 루트의 디렉터리는 아니고 임의로 생성한 디렉터리입니다.

3. 해당 디렉터리에 접근하고 clone --mirror를 수행합니다

해당 디렉터리에 접근하고 clone --mirror를 수행합니다.

- 아래의 명령어를 수행합니다.

# [예시] 이관하려는 디렉터리의 git 주소를 붙여넣기 합니다
$ git clone --mirror 

# 이관하려는 디렉터리의 git 주소를 붙여넣기 합니다
$ git clone --mirror https://github.com/adjh54ir/spring-boot-3-vault.git

위에 명령어를 수행하면 실제 디렉터리 내에 아래와 같은 파일들이 생겼습니다.

4. 새로운 레포지토리의 push --mirror를 수행합니다

새로운 레포지토리의 mirror push를 수행합니다.

- git clone --mirror를 통해 복제된 git에 접근하여, git push --mirror를 수행하여서 기존에 clone 된 repo를 새로 생성된 repo로 이관이 수행이 됩니다.

# [예시] 위에 clone --mirror로 복제된 git을 접근합니다.
$ cd xxx.git

# 위에 clone --mirror로 복제된 git을 접근합니다.
$ cd spring-boot-3-vault.git

# [예시] 이관하려는 받으려는 git 주소를 붙여넣기 합니다
$ git push --mirror 

# 이관하려는 디렉터리의 git 주소를 붙여넣기 합니다
$ git push --mirror https://github.com/adjh54ir/temp-spring-boot-3-vault.git

5. Github내에 새로운 Repository를 확인하면 정상적으로 이관이 된 것을 확인하였습니다.

분류	약칭	레포지토리 명
이관하려는 레포지토리	old-repo	spring-boot-3-vault
이관받는 레포지토리	new-repo	temp-spring-boot-3-vault

2) Git 레포지토리 변경(이관) 방법 : 다른 계정

Git 레포지토리 변경(이관) 방법 : 다른 계정

- 기존에 A 계정 내에 있던 레포지토리를 B 계정으로 변경(이관)을 할 일이 생기게 되었습니다.
- 요구사항으로는 A 계정내 남아있던 ‘Git 로그’나 ‘커밋 메시지’, ‘브랜치’ 등을 A에서 사용하는 그대로 B 레포지토리의 히스토리를 유지한 채 이관을 하려는 목적을 가지고 있습니다.

분류	약칭
이관하려는 사용자	adjh54ir
이관받는 사용자	adjh54irir

1. 이관하려는 레포지토리에 접근합니다.

2. Setting 탭 > Transfer ownership > Transfer을 선택합니다.

3. 새로운 레포지토리의 Owner를 선택합니다.

새로운 레포지토리의 Owner를 선택합니다

- 해당 방식에서는 ‘Specify an organization or username’를 통해서 다른 계정으로 레포지토리의 계정으로 이관하려고 합니다.

1. Select one of my organizations
- 해당 경우는 ‘내 조직 중 하나’를 선택할 수 있습니다. 이를 위해 조직 내에 포함되어야 합니다.

2. Specify an organization or username
- 해당 경우는 내 조직 또는 Github username을 기반으로 선택할 수 있습니다.

4. 계정을 입력하고, 확인을 입력한 뒤 ‘I understand, transfer this repository.’를 선택합니다.

5. 이관을 전달받은 사용자의 메일로 이동하고, 링크를 누릅니다.

이관을 전달받은 사용자의 메일로 이동하고, 링크를 누릅니다.

아래와 같은 메일이 도착했습니다.

안녕하세요 adjh54irir 님,
@adjh54ir은 adjh54ir/spring-boot-3-vault 저장소를 adjh54irir/spring-boot-3-vault로 전송하려고 합니다.

이 저장소 이전을 수락하면 다음에 대한 액세스 권한을 잃게 됩니다.
- 코드 소유자 기능.
- 기존 위키.
- 인사이트 페이지의 펄스, 기여자, 커뮤니티, 트래픽, 커밋, 코드 빈도 및 네트워크.
- 초안 PR.
- 문제 및 PR에 대한 여러 담당자.
- 다수의 PR 리뷰어.
- 분기 및 태그 보호 규칙.
- 기존 페이지.
액세스 권한을 잃지 않으려면 이 저장소의 전송을 수락하기 전에 계획을 업그레이드할 수 있습니다.
이전을 수락하려면 다음 링크를 방문하세요.
이전을 수락하지 않으면 약 하루 후에 만료됩니다.
질문? 문제가 있나요? 언제든지 https://support.github.com을 방문해 주세요.
감사해요, GitHub의 친구들

7. Repository를 확인하면 아래와 같이 정상적으로 새로운 계정에 이관을 확인하였습니다

분류	약칭
이관하려는 사용자	adjh54ir
이관받는 사용자	adjh54irir

오늘도 감사합니다.

[RN/오류노트] Solved - Node found at: /opt/homebrew/Cellar/node@xxx

adjh54 — Mon, 17 Nov 2025 18:02:08 +0900

해당 글에서는 XCode를 실행하는 중에 발생하는 빌드 문제에 대해 해결방법에 대해 알아봅니다.

1) 문제점

문제점

- XCode를 빌드하는 과정에서 아래와 같은 오류가 발생하였습니다.

Node found at: /opt/homebrew/Cellar/node@22/22.14.0/bin/node /Users/leejonghoon/Library/Developer/Xcode/DerivedData/EmotionButton-fsuawxxfittqjdhewknsvhbklaiz/Build/Intermediates.noindex/Pods.build/Debug-iphoneos/hermes-engine.build/Script-46EB2E0002F110.sh: line 9: /opt/homebrew/Cellar/node@22/22.14.0/bin/node: No such file or directory Command PhaseScriptExecution failed with a nonzero exit code

- 해당 문제의 경우는 XCode내에서 Node@22 경로를 찾지 못하는 오류입니다. 이 경우에는 homebrew를 업데이트 한 이후에 발생하였습니다.

2) 해결방법

해결방법

- 현재 버전이 모두 안 맞는 문제가 발생하고 있기에 동일한 node 버전으로 모두 통일을 합니다.

1. Node의 실제 경로 확인

Node의 실제 경로 확인

- 아래의 명령어를 입력해보면 두개의 경로가 충돌됨을 확인할 수 있습니다.
- 첫번쨰 터미널에서 사용하는 node의 경우는 .nvm을 바라보고 있습니다. 그리고 xcode내에서는 homebrew의 node 버전을 보고 있는 문제입니다. 그렇기에 최종적으로 node@22버전으로 일괄 맞춥니다.

# 터미널에서 사용하는 Node
which node

# Xcode가 사용하는 Node
ls -l /opt/homebrew/bin/node

분류	버전
Xcode에서 바라보고 있는 node 버전	22.21.1 버전
nvm의 node 버전	20.19.2 버전
homebrew의 node 버전	25.0.1 버전

아래와 같이 XCode에서 실행된 버전과 brew node 버전이 불일치함을 확인할 수 있습니다.

// Xcode에서 실행된 버전
/opt/homebrew/Cellar/node@22/.../bin/node

// brew NODE 버전
/opt/homebrew/Cellar/node/25.1.0_1/bin/node

2. nvm을 이용하지 않고 homebrew에서 관리하는 해결방법

nvm을 이용하지 않고 homebrew에서 관리하는 해결방법

- ZSehll에서 nvm의 우선순위를 먼저주지 않고 nvm을 삭제하고 homebrew 버전으로 맞추는 방법으로 수행합니다

2.1. ZSell에서 nvm 우선순위를 주석처리합니다

ZSell에서 nvm 우선순위를 주석처리합니다

- 아래와 같이 ZSell에 접속하고 아래와 같이 주석을 수행한뒤 반영을 합니다.

vi ~/.zshrc

source ~/.zshrc

2.2. nvm 자체를 삭제합니다

nvm 자체를 삭제합니다

- brew로 관리를 위해서 nvm을 삭제하였습니다.

rm -rf ~/.nvm

2.3. brew node만 사용하도록 설정합니다

brew node만 사용하도록 설정합니다
- 아래와 같이 기존의 node 버전을 삭제했고, node@22 버전을 맞추었습니다.그리고 link로 node22를 연결하였습니다.

$ brew uninstall node
$ brew install node@22
$ brew link --overwrite --force node@22

3. node 버전 확인

# 터미널에서 사용하는 Node
which node

# Xcode가 사용하는 Node
ls -l /opt/homebrew/bin/node

4. .xcode.env.local 파일 변경

# 기존
export NODE_BINARY="/opt/homebrew/Cellar/node@22/v20.19.2/bin/node"

# 변경
export NODE_BINARY="/opt/homebrew/opt/node@22/bin/node"

5. pod 재 설정

pod 재 설정

# DerivedData 삭제
$ rm -rf ~/Library/Developer/Xcode/DerivedData/

# 다시 pod install 
$ cd ios

# pod 초기화 
$ pod deintegrate

# pod 재설치
$ pod install

6. Xcode 실행

Xcode 실행

- 정상적으로 실행됨을 확인하였습니다.

오늘도 감사합니다.

[Java] Spring Boot 환경에서 시스템 변수 .env 파일 지정 및 활용 방법

adjh54 — Tue, 11 Nov 2025 15:59:54 +0900

해당 글에서는 Spring Boot 개발 환경에서 .env 파일을 시스템 변수로 지정하는 방법과 이를 불러오는 다양한 방법에 대해서 알아봅니다

1) Spring Boot 환경에서 .env 파일을 시스템 변수로 적용하는 이유

1. 보안적으로 코드와 민감 정보를 분리하기 위해 이용합니다.

보안적으로 코드와 민감 정보를 분리하기 위해 이용합니다.

- .properties나 application-xxx.yml에 주요 민감 정보들이 포함되어 있다면, Git 내에 민감정보가 커밋이 될 수 있고, 협업/오픈소스 환경에서는 유출 위험이 큽니다.
- 해당 민감 정보를 기반으로 악의적인 목적으로 이용하거나 탈취를 할 수 있기에 서버를 실행할때, .env 파일을 불러오도록 수행하여서 직접적인 노출을 하지 않습니다.

2. 운영되는 환경(dev/stg/prd)에 따라 값이 달라질수 있기에 이용합니다.

운영되는 환경(dev/stg/prd)에 따라 값이 달라질수 있기에 이용합니다.

- 기존에는 **.properties나 application-xxx.yml에서 분기하여서 각각을 이용하여서 application-dev.yml, application-stg.yml, application-prd.yml 방식으로 분리를 하여서 각각 파일 내에 설정 정보를 다르게 하였습니다.

- 이와 같이 .env 내에서도 동일하게 각각의 운영되는 환경에 맞게 각 파일들을 관리하여, 서버가 실행될 때 각 .env, .env.dev, .env.stg, .env.prd 파일을 불러오게끔 합니다.

3. CI/CD & 도커, 클라우드 환경에서 표준 방식으로 이용합니다.

CI/CD & 도커, 클라우드 환경에서 표준 방식

- Docker 내에서는 Dockerfile + .env 파일, docker-compose —env-file + .env 파일과 같이 대부분의 배포 환경은 환경 변수 기반설정을 권장합니다

4. 실운영에서 파일이 남아있지 않아 유출 위험이 더 낮기에 이용합니다

실운영에서 파일이 남아있지 않아 유출 위험이 더 낮음

- YML/Properties 파일은 서버에 그대로 남아있지만 환경변수는 메모리 상에만 존재하기 때문에 서버 파일 유출 시에도 상대적으로 안전합니다.

5. Vault를 이용하는 경우, 문제 발생 시 상대적으로 빠른 대응이 가능합니다

Vault를 이용하는 경우, 문제 발생 시 상대적으로 빠른 대응이 가능합니다

- Vault를 이용하여서 민감정보, 데이터베이스 접속 정보등을 관리하고 있을 때, 장애가 발생하여서 Vault 접속자체가 불 가능하여 모든 서버는 중단이 될 수 있습니다. 이때에, 복구작업으로 Vault 없이 서비스를 재 가동을 해야 하는 경우 .env 백업본을 활용하여서 이에 대한 대응을 수행할 수 있습니다.

2) .env 파일 생성 및 주입

1. 파일 생성 및 구성

파일 생성 및 구성

- 아래와 같이 프로젝트 루트 경로에, 예시로 .env 파일을 구성하였습니다.

APP_ENV=dev
DB_HOST=localhost
DB_USER=devuser
DB_PASSWORD=devpassword
LOG_LEVEL=debug

2. .gitignore에 .env 파일을 제외파일로 추가합니다

.gitignore에 .env 파일을 제외파일로 추가합니다

- 해당 파일이 git 내에 추가가되면 안되기에 .env 파일을 git 내에 commit & push 되지 않도록 합니다.

3. 오른쪽 상단에 서버 > 구성 편집.. 버튼을 누릅니다.

4. 옵션 수정(Modify options) 버튼을 누릅니다

5. 운영 체제(Operating System) > 환경 변수(Environment variables)를 선택합니다

6. 폴더 아이콘을 누르고, 구성한 .env 파일을 참조합니다

- 아래와 같이 참조하였습니다.

[참고]
- 숨김 파일로 안보일때는 맥북에서는 command + shift + . 단축키를 누르면 숨김 파일이 보입니다.

7. 아래와 같이 참조가 완료되었고, ‘확인’ 버튼을 누릅니다.

3) .env 파일 불러오기 : 소스코드

.env 파일 불러오기 : 소스코드

- 소스코드에서 바로 .env 파일 내에 데이터를 불러오는 방식을 의미합니다.

1. env 파일 확인

.env 파일 확인

- 위에서 임시로 .env 파일 내에 데이터를 정의하였습니다.

APP_ENV=dev
DB_HOST=localhost
DB_USER=devuser
DB_PASSWORD=devpassword
LOG_LEVEL=debug

2. xxxApplication.java 파일 내에서 환경 변수를 조회합니다

xxxApplication.java 파일 내에서 환경 변수를 조회합니다

- 시스템 환경 변수를 조회하는 함수인 System.getenv()를 통해서 데이터를 조회하고, 최종 콘솔 내에 출력되도록 하였습니다.

package com.tha.vault;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;

@SpringBootApplication
public class VaultApplication {

    public static void main(String[] args) {
        String appEnv = System.getenv("APP_ENV");
        String dbHost = System.getenv("DB_HOST");
        String dbUser = System.getenv("DB_USER");
        String dbPassword = System.getenv("DB_PASSWORD");
        String logLevel = System.getenv("LOG_LEVEL");
        System.out.println("ROLE_ID : " + appEnv);
        System.out.println("DB_HOST : " + dbHost);
        System.out.println("DB_USER : " + dbUser);
        System.out.println("DB_PASSWORD : " + dbPassword);
        System.out.println("LOG_LEVEL : " + logLevel);
        SpringApplication.run(VaultApplication.class, args);
    }

}

3. 서버를 실행합니다

서버를 실행합니다

- 아래와 같이 참조한 시스템 환경 변수가 정상적으로 출력이 됨을 확인하였습니다.

4) .env 파일 불러오기 : application.properties

.env 파일 불러오기 : application.properties

- 시스템 환경변수 application.properties와 매핑하여서 값을 지정하도록 구성하고, 최종적으로 코드 내에서 @Value 값을 이용하여 조회하는 형태입니다.

1. env 파일 확인

env 파일 확인

- 위에서 임시로 .env 파일 내에 데이터를 정의하였습니다.

APP_ENV=dev
DB_HOST=localhost
DB_USER=devuser
DB_PASSWORD=devpassword
LOG_LEVEL=debug

2. application-loc.yml

application-loc.yml

- ${변수명} 형태로 .env 파일을 참조하여서 불러오도록 하였습니다.

# Spring boot Server Configuration
server:
  port: 8000

custom-info:
  app-env: ${APP_ENV}
  db:
    host: ${DB_HOST}
    user: ${DB_USER}
    password: ${DB_PASSWORD}
  log-level: ${LOG_LEVEL}

3. @Value()를 기반으로 데이터를 조회합니다

@Value()를 기반으로 데이터를 조회합니다

- 위에서 정의한 yml 파일을 조회하여서 콘솔에 출력하도록 구성하였습니다.

import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class VaultController {

    @Value("${custom-info.app-env}")
    private String appEnv;

    @Value("${custom-info.db.host}")
    private String dbHost;

    @Value("${custom-info.db.user}")
    private String dbUser;

    @Value("${custom-info.db.password}")
    private String dbPassword;

    @Value("${custom-info.log-level}")
    private String logLevel;

    @GetMapping("/")
    public String main() {
        System.out.println("appEnv : " + appEnv);
        System.out.println("dbHost : " + dbHost);
        System.out.println("dbUser : " + dbUser);
        System.out.println("dbPassword : " + dbPassword);
        System.out.println("logLevel : " + logLevel);
        return "임시 테스트 ";
    }
}

4. .env > .yml > 코드로 데이터를 조회해 왔습니다

.env > .yml > 코드로 데이터를 조회해 왔습니다

- 지정된 API로 호출했을 때 콘솔로 정보가 조회됨을 확인하였습니다.

5) .env 파일 불러오기 : application.properties > 객체 매핑(getter)

.env 파일 불러오기 : application.properties > 객체 매핑(getter)

- .env 파일에서 불러온 키 값을 application.properties에서 받고 해당 값을 기반으로 즉시 객체에 매핑하는 방식을 이용합니다

1. env 파일 확인

.env 파일 확인

- 위에서 임시로 .env 파일 내에 데이터를 정의하였습니다.

APP_ENV=dev
DB_HOST=localhost
DB_USER=devuser
DB_PASSWORD=devpassword
LOG_LEVEL=debug

2. application-loc.yml

application-loc.yml

- ${변수명} 형태로 .env 파일을 참조하여서 불러오도록 하였습니다.

# Spring boot Server Configuration
server:
  port: 8000

custom-info:
  app-env: ${APP_ENV}
  db:
    host: ${DB_HOST}
    user: ${DB_USER}
    password: ${DB_PASSWORD}
  log-level: ${LOG_LEVEL}

3. CustomInfoProperties.java

CustomInfoProperties.java

- .yml 내에 있는 설정 정보들을 @ConfigurationProperties() 어노테이션을 기반으로 객체와 매핑하고, @Getter를 통하여 객체화하여서 편리하게 이용합니다.

import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Getter
@Setter
@Component
@ConfigurationProperties(prefix = "custom-info")
public class CustomInfoProperties {

    private String appEnv;
    private String logLevel;
    private DB db;

    @Getter
    @Setter
    public static class DB {
        private String host;
        private String user;
        private String password;
    }
}

4. getter를 이용한 조회 해왔습니다.

getter를 이용한 조회 해왔습니다.

- 좀 더 개발자 친화적인 객체화 스타일인 getter를 이용한 방식으로 조회를 합니다.

import com.tha.vault.config.CustomInfoProperties;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class VaultController {

    private final CustomInfoProperties customInfoProperties;

    public VaultController(CustomInfoProperties customInfoProperties) {
        this.customInfoProperties = customInfoProperties;
    }

    @GetMapping("/")
    public String main() {
        System.out.println("appEnv : " + customInfoProperties.getAppEnv());
        System.out.println("dbHost : " + customInfoProperties.getDb().getHost());
        System.out.println("dbUser : " + customInfoProperties.getDb().getUser());
        System.out.println("dbPassword : " + customInfoProperties.getDb().getPassword());
        System.out.println("logLevel : " + customInfoProperties.getLogLevel());
        return "임시 테스트 ";
    }
}

아래와 같이 정상적으로 조회가 완료되었습니다.

오늘도 감사합니다.

[RN] React Native 환경에서 Unity LevelPlay 광고 넣기 : Banner, Interstitial

adjh54 — Tue, 4 Nov 2025 20:30:17 +0900

해당 글에서는 Unity LevelPlay를 활용하여서 앱 내에 광고를 추가하는 방법에 대해 알아봅니다.

1) Unity LevelPlay

Unity LevelPlay

- Unity Technologies(이하 Unity)가 제공하는 모바일 게임 및 앱 내 광고 수익화(모네타이제이션) 및 광고 중개(mediation) 플랫폼입니다.
- 주요 목적은 여러 광고 네트워크(ad networks)를 통합하고, 입찰(bidding) 및 워터폴(waterfall) 방식으로 경쟁을 유도해 광고 단가(eCPM)와 수익을 극대화하는 것입니다.

- 이와 비슷한 주요 플랫폼으로는 Google Admob, AppLovin 등이 있습니다.

유니티 레벨플레이: 광고 미디에이션 플랫폼 | 유니티(Unity)

업계를 선도하는 광고 미디에이션 플랫폼, 유니티 레벨플레이로 앱 수익을 극대화하고 유저 확보를 가속화하세요.

unity.com

1. Unity LevelPlay 기능

기능	설명
광고 중개(Mediation)	여러 광고 네트워크를 하나의 플랫폼에서 관리할 수 있습니다. 사용자는 Unity Ads, AdMob, AppLovin 등 다양한 네트워크를 연결해 수익을 높일 수 있습니다.
실시간 입찰(In-App Bidding)	광고 인벤토리(노출 기회)를 여러 광고 네트워크가 실시간으로 경쟁(bid)하는 구조로 바꿔, 전통적인 워터폴 방식보다 더 높은 수익을 얻을 수 있게 합니다.
통합 대시보드 및 실시간 리포팅	광고 수익, eCPM, 사용자 세그먼트 등 다양한 지표를 실시간으로 확인하고 분석할 수 있는 리포팅 기능을 제공합니다.
A/B 테스트 및 세그먼트 제어	광고 설정(광고 위치, 포맷, 네트워크 우선순위 등)을 A/B 테스트하여 최적화 가능하며, 사용자 세그먼트별로 광고 경험을 제어할 수 있습니다.
Unity Editor 및 생태계 연동	Unity Editor 내 Package Manager에서 쉽게 통합 가능하며, 개발→빌드→광고 수익화까지 Unity 생태계 안에서 일관된 워크플로우를 제공합니다.

2. Ironsource

Ironsource

- 이스라엘에서 시작된 모바일 광고 수익화 플랫폼(Ad mediation & monetization platform)입니다.

- 2022년에 Unity Technologies가 IronSource를 인수했습니다. 그 후 Unity는 IronSource의 광고 중개 플랫폼을 통합해서 IronSource LevelPlay → Unity LevelPlay가 되었습니다.
- 즉 IronSource의 Mediation 엔진과 기술력과 Unity의 생태계와 광고 네트워크가 합쳐진 것이 Unity LevelPlay입니다.
- 현재도 Unity 문서와 SDK 내부에서는 “IronSource SDK”라는 이름이 여전히 사용되고 있어요.

유니티, 아이언소스와 합병 계약 체결

유니티는 오늘 아이언소스와 합병 계약 체결을 발표했고, 이에 따라 아이언소스의 툴과 플랫폼, 기술, 인재를 활용하여 크리에이터들의 라이브 게임 및 실시간 인터랙티브 경험 제작과 운영, 관

unity.com

3. Unity LevelPlay의 Mediation은 어떻게 수행이 될까?

Unity LevelPlay의 Mediation은 어떻게 수행이 될까?

- 앱 개발자가 여러 광고의 네트워크를 붙이는 것이 아닌 하나의 중개 플랫폼(LevelPlay)이 대신 네트워크를 연결·조율해 주는 구조입니다.

3.1. Mediation 방식

Mediation 방식

- 직접적으로 개발자는 광고를 붙이는 것이 아니지만, 광고 플랫폼 내에서는 아래와 같은 방식으로 광고가 송출이 됩니다.

방식	설명	용도
Waterfall 방식	'우선순위'를 정해 상단 네트워크부터 순서대로 광고 요청	단가가 안정적이지만 비효율적일 수 있음
Bidding 방식 (In-App Bidding)	여러 네트워크가 실시간 입찰로 경쟁하여 가장 높은 eCPM 광고를 선택	최신 트렌드, LevelPlay의 핵심 구조
Hybrid Mediation 방식	- 입찰 참여 가능한 네트워크는 실시간으로 경쟁하고, 참여 불가능한 네트워크는 예비(Waterfall)로 작동합니다. - 해당 방식이 LevelPlay 방식입니다.	둘 다 활용해서 최고 수익 + 안정성 + 폭넓은 국가 지원

https://unity.com/blog/what-is-mobile-ad-mediation

Mediation Waterfall 방식

- '우선순위'를 정해 상단 네트워크부터 순서대로 광고 요청

https://docs.unity.com/ko-kr/grow/dashboard/waterfalls

Mediation Bindding 방식

- 여러 네트워크가 실시간 입찰로 경쟁하여 가장 높은 eCPM 광고를 선택하는 방식

https://developers.is.com/ironsource-mobile/air/level-play/#step-1

2) 환경 구성하기

환경 구성하기

- 공식사이트의 가이드에 따라서 적용합니다.
- Unity LevelPlay 설정이 완료되었고 권한을 부여받았다는 가정하에 진행을 합니다.

React Native Plugin Integration - IronSource Knowledge Center

React Native Plugin Integration ⚡ Before you start Our React Native plugin is supported from the native SDK versions 7.2.4.1 for Android and 7.2.4 for iOS. The plugin supports both JavaScript and TypeScript. The type declarations are included in the npm

developers.is.com

1. 라이브러리 설치

라이브러리 설치

- 공식 사이트 글을 참고하여서, 가장 최신 버전인 3.2.0 버전을 설치하였습니다.

$ npm install ironsource-mediation@3.2.0

# or

$ yarn add ironsource-mediation@3.2.0

3) 환경 구성하기 : iOS

1. Podfile 설정

Podfile

- IronSourceAdQualitySDK는 Unity LevelPlay에서 광고 품질 측정/분석하는 SDK입니다.
- 앱 안에 송출되는 광고(배너, 전면 광고, 보상형 광고 등)의 품질(클릭, 전환, 수익 기여도 등)을 추적/분석하는 데 사용됩니다.

#   IronSource 추가
pod 'IronSourceAdQualitySDK'

2. plist.info 설정

2.1. 광고 네트워크 고유 식별자 등록

광고 네트워크 고유 식별자 등록

- Apple의 광고 네트워크(예: IronSource, Unity Ads, Google, Facebook 등)에 부여한 고유 식별자로 IronSource의 식별자를 등록합니다.

<key>SKAdNetworkItems</key>
<array>
   <dict>
      <key>SKAdNetworkIdentifier</key>
      <string>su67r6k2v3.skadnetwork</string>
   </dict>
</array>

2.2. Universal SKAN Reporting 등록

Universal SKAN Reporting 등록

- IronSource 같은 mediation 플랫폼도 직접 postback 사본을 수신해서, 전체 네트워크 성과를 더 정확히 집계·최적화할 수 있습니다.
- Universal SKAN postback을 보낼 목적지 URL을 지정하는 키로 IronSource(= Unity LevelPlay)에서 제공하는 전용 엔드포인트로 지정을 합니다.

<key>NSAppTransportSecurity</key>
<dict>
	<key>NSAllowsArbitraryLoads</key>
  	<true/>
</dict>

2.3. App transport security settings 지정

App transport security settings 지정

- iOS 9부터 Apple은 네트워크 보안 강화를 위해 ATS라는 정책을 도입했습니다. 기본적으로 모든 HTTP 요청은 TLS 1.2 이상을 사용하는 HTTPS만 허용됩니다.
- IronSource mediation은 여러 광고 네트워크(구글, Unity, Meta, 작은 DSP 등등)의 광고를 중계합니다. 이때 모든 광고 네트워크가 항상 최신 보안 기준(HTTPS)만 쓰는 건 아니기에 ATS를 그대로 두면 광고 요청이 차단되어서 광고가 나오지 않는 문제가 발생할 수 있습니다.
- Apple은 원칙적으로 광범위한 예외(NSAllowsArbitraryLoads = YES)를 권장하지 않습니다. 보안상 좋은 방법은 개별 도메인 예외(NSExceptionDomains)를 열어주는 방법이지만 도메인이 계속 바뀌기에 관리가 사실상 불가능합니다.

NSAdvertisingAttributionReportEndpoint
<https://postbacks-is.com>

2.4. 종합

<key>SKAdNetworkItems</key>
<array>
   <dict>
      <key>SKAdNetworkIdentifier</key>
      <string>su67r6k2v3.skadnetwork</string>
   </dict>
</array>

<key>NSAppTransportSecurity</key>
<dict>
	<key>NSAllowsArbitraryLoads</key>
  	<true/>
</dict>
<key>NSAdvertisingAttributionReportEndpoint</key>
<string>https://postbacks-is.com</string>

4) 환경 구성하기 : Android

1. app/build.gradle

app/build.gradle

- com.unity3d.ads-mediation:adquality-sdk는 IronSourceAdQualitySDK는 Unity LevelPlay에서 광고 품질 측정/분석하는 SDK입니다.
- play-services-ads-identifier : Android 기기의 광고 식별자(Advertising ID, AAID/GAID)를 가져올 수 있게 해주는 라이브러리.
- play-services-basement : Google Play 서비스 SDK들의 공통 기반(core library) 역할.
- play-services-appset: App Set ID를 제공하는 라이브러리

dependencies {
	implementation 'com.unity3d.ads-mediation:adquality-sdk:9.0.1'
	implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
	implementation 'com.google.android.gms:play-services-basement:18.3.0'
	implementation 'com.google.android.gms:play-services-appset:16.0.2'
}

React Native Plugin Integration - IronSource Knowledge Center

developers.is.com

2. AndroidManifest.xml

AndroidManifest.xml

- 대상 API 레벨을 31(Android 12)로 업데이트하는 앱은 다음과 같이 매니페스트 파일에서 Google Play 서비스 일반 권한을 선언해야 합니다.

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

3. proguard-rules.pro

proguard-rules.pro

- ironSource SDK와 함께 ProGuard를 사용하는 경우 다음 코드를 ProGuard 파일(Android Studio: proguard-rules.pro 또는 Eclipse: proguard-project.txt)에 추가해야 합니다.

-keepclassmembers class com.ironsource.sdk.controller.IronSourceWebView$JSInterface {
    public *;
}
-keepclassmembers class * implements android.os.Parcelable {
    public static final android.os.Parcelable$Creator *;
}
-keep public class com.google.android.gms.ads.** {
   public *;
}
-keep class com.ironsource.adapters.** { *;
}
-keep class com.ironsource.unity.androidbridge.** { *;
}
-dontwarn com.ironsource.mediationsdk.**
-dontwarn com.ironsource.adapters.**
-keepattributes JavascriptInterface
-keepclassmembers class * {
    @android.webkit.JavascriptInterface <methods>;
}

[참고] 공식사이트에서 안드로이드 배너 광고만 출력이 안 되는 문제가 있었습니다.

- 해당 문제를 찾던 중, gradle.properties 내에 속성 때문에 실행이 안된다는 것을 발견하였습니다.
- 혹시나 위에 과정이 수행이 되지 않는 경우 아래의 옵션을 수정해 보시면 정상적으로 출력을 됨을 확인하실 수 있습니다.

# 변경 이전
newArchEnabled=true

# 변경 이후
newArchEnabled=false

5) 광고 구성 : 배너 광고, Interstitial 광고

1. 배너 광고

배너 광고

- 배너 광고는 각각 ‘앱의 키’와 ‘배너 UNIT ID’, PLACEMENT 값을 공식사이트에서 확인하여서 입력하여야 합니다.

Banner integration for React Native • Unity Grow • Unity Docs

Implement banner ads in your React Native app using the ironSource SDK, including setup, initialization, and listener configuration.

docs.unity.com

1.1. SDK 로드

SDK 로드

- useEffect를 통해서 해당 화면이 수행될 때 initIronSourceSDK 함수를 호출합니다.

1. APP_KEY 값을 기반으로 initRequest build를 구성합니다
2. initListener : SDK의 리스너를 등록합니다.
- onInitSuccess : SDK 로드를 성공적으로 해올 때, 수행이 되는 함수입니다.
- onInitFailed : SDK 로드를 실패하였을 때, 수행되는 함수입니다.

2. LevelPlay.init(): 최종 앱에 대한 키값과 리스너를 함께 SDK를 초기화하는 init() 함수입니다.

3. 최종 SDK 로드가 완료되면 onInitSuccess 리스너가 수행이 됩니다.
- 해당 시점에 배너를 로드해 옵니다.

const APP_KEY = Platform.select({
    android: '123',
    ios: '123',
    default: '',
});

useEffect(() => {
    initIronSourceSDK();
}, []);

const initIronSourceSDK = async () => {
    if (!APP_KEY) {
        console.error('❌ No APP_KEY found, skipping init');
        return;
    }
    try {
        const initRequest = LevelPlayInitRequest.builder(APP_KEY).build();
        const initListener: LevelPlayInitListener = {
            onInitSuccess: (config: LevelPlayConfiguration) => {
                console.log('✅ IronSource Init Success:', config);
                bannerAdRef.current?.loadAd();
            },
            onInitFailed: (error: LevelPlayInitError) => {
                console.error('❌ IronSource Init Failed:', error);
            },
        };
        // 디버깅용
        // LevelPlay.setAdaptersDebug(true);

        // App mount 안정화 후 실행
        requestAnimationFrame(() => {
            LevelPlay.init(initRequest, initListener)
                .catch((e) => {
                    console.error('  Init Exception:', e);
                });
        });
    } catch (e) {
        console.error('  JS Exception before init:', e);
    }
};

1.2. 배너 광고 로드

배너 광고 로드

- SDK가 성공적으로 수행이 된 이후에 배너 광고가 로드되어야 합니다.
- onInitSuccess → LevelPlayBannerAdView → bannerAdRef.current?.loadAd(); 이와 같은 과정으로 수행이 됩니다.

1. LevelPlayBannerAdView

- adUnitId: 사전에 발급받은 B- ANNER_UNIT_ID 값을 입력합니다.
- adSize: Unity LevelPlay에서 제공하는 주요한 배너 사이즈를 이용합니다.
- placementName: 배너의 어떤 배너인지를 구분하기 위한 배너입니다.
- 예를 들어서, HOME_BANNER → 홈 화면 하단에 표시되는 배너, QUIZ_REWARD → 퀴즈 끝나고 보여주는 리워드 광고가 될 수 있습니다.
- listener: 배너 광고가 출력되고 사전에 정의한 리스너로 결과를 반환받습니다.

2. listener

- 성공적으로 배너가 출력이 되면 onAdLoaded → onAdDisplayed와 같이 수행이 됩니다.

콜백 함수	호출 시점/의미	주로 하는 역할 예시
onAdLoaded(info: LevelPlayAdInfo)	배너 광고가 성공적으로 로드 완료됐을 때 호출	UI에 “로드 완료” 로그, 다음 액션 가능 상태 표시
onAdLoadFailed(error: LevelPlayAdError)	배너 광고 로드가 실패했을 때 호출	실패 로그 출력, 일정 시간 후 재시도 (setTimeout 등)
onAdDisplayed(info: LevelPlayAdInfo)	광고가 실제로 화면에 표시되었을 때 호출	노출 로그 기록, 분석/통계 전송
onAdDisplayFailed(adInfo, error)	광고가 로드되었지만 표시 실패했을 때 호출	실패 원인 분석, 필요 시 로드 재시도
onAdClicked(info: LevelPlayAdInfo)	사용자가 배너를 클릭했을 때 호출	클릭 이벤트 로깅, 분석/성과 데이터 전송
onAdExpanded(adInfo)	배너가 확장(Expand) 되었을 때 호출 (예: 리치미디어 광고가 배너 영역을 크게 펼치는 경우)	UI 상태 조정, 배경 일시 정지 등
onAdCollapsed(adInfo)	확장된 배너가 다시 축소(Collapse) 되었을 때 호출	UI 원상 복구
onAdLeftApplication(adInfo)	사용자가 광고를 클릭해서 앱을 떠났을 때 호출 (예: 브라우저 열림)	앱 상태 관리, 로그 기록, 필요 시 pause 처리

/* eslint-disable react-native/no-inline-styles */
import { scaleHeight } from '@/utils';
import {
    LevelPlay,
    LevelPlayAdError,
    LevelPlayAdInfo,
    LevelPlayAdSize,
    LevelPlayBannerAdView,
    LevelPlayBannerAdViewListener,
    LevelPlayBannerAdViewMethods,
    LevelPlayConfiguration,
    LevelPlayInitError,
    LevelPlayInitListener,
    LevelPlayInitRequest,
} from 'ironsource-mediation';
import React, { useCallback, useEffect, useRef, useState } from 'react';
import { Platform, View, StyleSheet } from 'react-native';

interface AdmobBannerAdProps {
    paramMarginTop?: number;
    paramMarginBottom?: number;
    visible?: boolean;
    isLoadSdk?: boolean; // ✅ init 성공 후 true
}

const BANNER_AD_UNIT_ID = Platform.select({
    android: '123',
    ios: '3344',
});

const APP_KEY = Platform.select({
    android: '555',
    ios: '6666',
    default: '',
});

const PLACEMENT_NAME = 'BANNER';

const LevelPlayBannerAd: React.FC<AdmobBannerAdProps> = ({
    paramMarginTop = 6,
    paramMarginBottom = 6,
    visible = true,
    isLoadSdk,
}) => {
    const adSize = LevelPlayAdSize.BANNER
    const bannerAdRef = useRef<LevelPlayBannerAdViewMethods>(null);

    const listener: LevelPlayBannerAdViewListener = {
        onAdLoaded: (info: LevelPlayAdInfo) => {
            console.log('✅ Banner loaded:', info)
        },
        onAdLoadFailed: (error) => {
            console.log('❌ Banner load failed:', error);
            // setTimeout(() => bannerAdRef.current?.loadAd(), 3000); // 3초 후 재시도
        },
        onAdDisplayed: (info: LevelPlayAdInfo) => {
            console.log('  Banner displayed:', info)
        },
        onAdDisplayFailed: (adInfo: LevelPlayAdInfo, error: LevelPlayAdError) => {
            // Implement your logic here
        },
        onAdClicked: (info: LevelPlayAdInfo) => {
            console.log(' ️ Banner clicked:', info)
        },
        onAdExpanded: (adInfo: LevelPlayAdInfo) => {
            // Implement your logic here
        },
        onAdCollapsed: (adInfo: LevelPlayAdInfo) => {
            // Implement your logic here
        },
        onAdLeftApplication: (adInfo: LevelPlayAdInfo) => {
            // Implement your logic here
        },
    };

    // Load ad
    const loadAd = useCallback(() => {
        bannerAdRef.current?.loadAd();
    }, []);

    return (
        <View
            style={[
                styles.container,
                {
                    marginTop: scaleHeight(paramMarginTop),
                    marginBottom: scaleHeight(paramMarginBottom),
                    opacity: visible ? 1 : 0, // 렌더링 유지 + 가시성만 제어
                    height: visible ? undefined : 0,
                },
            ]}>

            <LevelPlayBannerAdView
                ref={bannerAdRef}
                adUnitId={BANNER_AD_UNIT_ID!}
                adSize={adSize}
                placementName={PLACEMENT_NAME}
                listener={listener}
                style={{ width: adSize.width, height: adSize.height, alignSelf: 'center' }}
            />
        </View>
    );
};

export default React.memo(LevelPlayBannerAd);

const styles = StyleSheet.create({
    container: {
        backgroundColor: 'transparent',
    },
    bannerAd: {
        width: 320,
        height: 50,
        alignSelf: 'center',
        position: 'absolute',
        zIndex: 10,
        bottom: 0,
    },
});

1.3. 최종

/* eslint-disable react-native/no-inline-styles */
import { scaleHeight } from '@/utils';
import {
    LevelPlay,
    LevelPlayAdError,
    LevelPlayAdInfo,
    LevelPlayAdSize,
    LevelPlayBannerAdView,
    LevelPlayBannerAdViewListener,
    LevelPlayBannerAdViewMethods,
    LevelPlayConfiguration,
    LevelPlayInitError,
    LevelPlayInitListener,
    LevelPlayInitRequest,
} from 'ironsource-mediation';
import React, { useCallback, useEffect, useRef, useState } from 'react';
import { Platform, View, StyleSheet } from 'react-native';

interface AdmobBannerAdProps {
    paramMarginTop?: number;
    paramMarginBottom?: number;
    visible?: boolean;
    isLoadSdk?: boolean; // ✅ init 성공 후 true
}

const BANNER_AD_UNIT_ID = Platform.select({
    android: '1233',
    ios: '33444',
});

const APP_KEY = Platform.select({
    android: '55566',
    ios: '6667',
    default: '',
});

const PLACEMENT_NAME = 'BANNER';

const LevelPlayBannerAd: React.FC<AdmobBannerAdProps> = ({
    paramMarginTop = 6,
    paramMarginBottom = 6,
    visible = true,
    isLoadSdk,
}) => {

    const adSize = LevelPlayAdSize.BANNER
    const bannerAdRef = useRef<LevelPlayBannerAdViewMethods>(null);

    useEffect(() => {
        initIronSourceSDK();
    }, []);

    const initIronSourceSDK = async () => {
        if (!APP_KEY) {
            console.error('❌ No APP_KEY found, skipping init');
            return;
        }
        try {
            const initRequest = LevelPlayInitRequest.builder(APP_KEY).build();
            const initListener: LevelPlayInitListener = {
                onInitSuccess: (config: LevelPlayConfiguration) => {
                    console.log('✅ IronSource Init Success:', config);
                    bannerAdRef.current?.loadAd();
                },
                onInitFailed: (error: LevelPlayInitError) => {
                    console.error('❌ IronSource Init Failed:', error);
                },
            };
            // 디버깅용
            // LevelPlay.setAdaptersDebug(true);

            // App mount 안정화 후 실행
            requestAnimationFrame(() => {
                LevelPlay.init(initRequest, initListener)
                    .catch((e) => {
                        console.error('  Init Exception:', e);
                    });
            });
        } catch (e) {
            console.error('  JS Exception before init:', e);
        }
    };

    const listener: LevelPlayBannerAdViewListener = {
        onAdLoaded: (info: LevelPlayAdInfo) => {
            console.log('✅ Banner loaded:', info)
        },
        onAdLoadFailed: (error) => {
            console.log('❌ Banner load failed:', error);
            // setTimeout(() => bannerAdRef.current?.loadAd(), 3000); // 3초 후 재시도
        },
        onAdDisplayed: (info: LevelPlayAdInfo) => {
            console.log('  Banner displayed:', info)
        },
        onAdDisplayFailed: (adInfo: LevelPlayAdInfo, error: LevelPlayAdError) => {
            // Implement your logic here
        },
        onAdClicked: (info: LevelPlayAdInfo) => {
            console.log(' ️ Banner clicked:', info)
        },
        onAdExpanded: (adInfo: LevelPlayAdInfo) => {
            // Implement your logic here
        },
        onAdCollapsed: (adInfo: LevelPlayAdInfo) => {
            // Implement your logic here
        },
        onAdLeftApplication: (adInfo: LevelPlayAdInfo) => {
            // Implement your logic here
        },
    };

    // Load ad
    const loadAd = useCallback(() => {
        bannerAdRef.current?.loadAd();
    }, []);

    return (
        <View
            style={[
                styles.container,
                {
                    marginTop: scaleHeight(paramMarginTop),
                    marginBottom: scaleHeight(paramMarginBottom),
                    opacity: visible ? 1 : 0, // 렌더링 유지 + 가시성만 제어
                    height: visible ? undefined : 0,
                },
            ]}>

            <LevelPlayBannerAdView
                ref={bannerAdRef}
                adUnitId={BANNER_AD_UNIT_ID!}
                adSize={adSize}
                placementName={PLACEMENT_NAME}
                listener={listener}
                style={{ width: adSize.width, height: adSize.height, alignSelf: 'center' }}
            />
        </View>
    );
};

export default React.memo(LevelPlayBannerAd);

const styles = StyleSheet.create({
    container: {
        backgroundColor: 'transparent',
    },
    bannerAd: {
        width: 320,
        height: 50,
        alignSelf: 'center',
        position: 'absolute',
        zIndex: 10,
        bottom: 0,
    },
});

1.4. 결과 화면 확인

결과 화면 확인

- 아래와 같이 배너화면이 출력이 됨을 확인하였습니다.

2. Interstitial 광고

Interstitial 광고

- Interstitial 광고에서 동일하게 각각 ‘앱의 키’와 ‘배너 UNIT ID’, PLACEMENT 값을 공식사이트에서 확인하여서 입력하여야 합니다.

Interstitial integration for React Native • Unity Grow • Unity Docs

Integrate interstitial ads in your React Native app by initializing the SDK, creating ad units, and setting up event listeners to manage ad loading and display events.

docs.unity.com

2.1. SDK 로드

SDK 로드

- useEffect를 통해서 해당 화면이 수행될 때 initIronSourceSDK 함수를 호출합니다.

1. APP_KEY 값을 기반으로 initRequest build를 구성합니다.
2. initListener: SDK의 리스너를 등록합니다.
- onInitSuccess : SDK 로드를 성공적으로 해올 때, 수행이 되는 함수입니다.
- onInitFailed : SDK 로드를 실패하였을 때, 수행되는 함수입니다.
LevelPlay.init() : 최종 앱에 대한 키값과 리스너를 함께 SDK를 초기화하는 init() 함수입니다.
- 최종 SDK 로드가 완료되면 onInitSuccess 리스너가 수행이 됩니다.

- 해당 시점에 배너를 로드해 옵니다.

import { scaledSize, scaleHeight, scaleWidth } from '@/utils';
import {
	LevelPlay,
	LevelPlayAdError,
	LevelPlayAdInfo,
	LevelPlayConfiguration,
	LevelPlayInitError,
	LevelPlayInitListener,
	LevelPlayInitRequest,
	LevelPlayInterstitialAd,
	LevelPlayInterstitialAdListener,
} from 'ironsource-mediation';
import { useEffect, useState } from 'react';
import { ActivityIndicator, Platform, StyleSheet, Text, View } from 'react-native';

type Props = {
	onAdClosed?: () => void;
};

const APP_KEY = Platform.select({
	android: '234234',
	ios: '2342345',
	default: '',
});

const PLACEMENT_NAME = 'FRONT';

const LevelPlayFrontAd = ({ onAdClosed }: Props) => {
	const [interstitialAd, setInterstitialAd] = useState<LevelPlayInterstitialAd>(
		new LevelPlayInterstitialAd(BANNER_FRONT_UNIT_ID!),
	);
	const [isVisible, setIsVisible] = useState(true); // 처음에는 보이도록

	useEffect(() => {
		initIronSourceSDK();
	}, []);

	const initIronSourceSDK = async () => {
		try {
			const initRequest = LevelPlayInitRequest.builder(APP_KEY!).build();

			const initListener: LevelPlayInitListener = {
				onInitSuccess: (config: LevelPlayConfiguration) => {
					console.log('✅ IronSource Init Success:', config);
					interstitialAd.setListener(listener);
					interstitialAd.loadAd();
				},
				onInitFailed: (error: LevelPlayInitError) => {
					console.error('❌ IronSource Init Failed:', error);
				},
			};

			//   테스트 광고 활성화
			// LevelPlay.setMetaData('is_test_suite', ['enable']);
			// LevelPlay.setAdaptersDebug(true);

			// 2. LevelPlay.init 요청을 생성합니다 
			await LevelPlay.init(initRequest, initListener);

			//   필요하다면 Test Suite 실행 (네트워크 설정 확인용)
			// await LevelPlay.launchTestSuite();
		} catch (e) {
			console.error('  Init Exception:', e);
		}
	}

	return isVisible ? (
		<View style={styles.adOverlay}>
			<View style={styles.container}>
				<ActivityIndicator size="large" color="#3498db" />
				<Text style={styles.loadingTxt}>광고를 준비 중이에요…</Text>
			</View>
		</View>
	) : null;
};
export default LevelPlayFrontAd;

const styles = StyleSheet.create({
	container: {
		padding: scaleHeight(24),
		backgroundColor: '#fff',
		borderRadius: scaleWidth(20),
		alignItems: 'center',
		justifyContent: 'center',
		shadowColor: '#000',
		shadowOpacity: 0.1,
		shadowOffset: { width: 0, height: 2 },
		shadowRadius: 6,
	},

	adOverlay: {
		position: 'absolute',
		top: 0,
		left: 0,
		right: 0,
		bottom: 0,
		backgroundColor: 'rgba(0,0,0,0.4)', // 더 어둡게
		justifyContent: 'center',
		alignItems: 'center',
		zIndex: 999,
	},

	loadingTxt: {
		marginTop: scaleHeight(12),
		fontSize: scaledSize(16),
		color: '#2c3e50',
		fontWeight: '600',
	},

	subTxt: {
		marginTop: scaleHeight(4),
		fontSize: scaledSize(13),
		color: '#7f8c8d',
	},

	mascotImage: {
		width: scaleWidth(80),
		height: scaleWidth(80),
		marginBottom: scaleHeight(16),
		opacity: 0.9,
	},
});

1.2. Interstitial 광고 로드

Interstitial 광고 로드

- SDK가 성공적으로 수행이 된 이후에 Interstitial 광고가 로드되어야 합니다.

- onInitSuccess → interstitialAd.setListener() → interstitialAd.loadAd() → interstitialAd.showAd(PLACEMENT_NAME); 이와 같은 과정으로 수행이 됩니다.

1. interstitialAd.setListener
- interstitial 광고의 리스너를 등록합니다. onAdLoaded() → onAdDisplayed() 함수 순으로 수행이 됩니다.

2. interstitialAd.loadAd()
- interstitial 광고를 로드해 옵니다. 광고가 로드되면 리스너가 수행이 되며, 결과 값을 반환해 줍니다.

3. onAdLoaded()
- 리스너의 광고가 로드가 되면, 이때 interstitialAd.showAd(PLACEMENT_NAME) 함수를 호출하여 광고를 송출합니다.

import { scaledSize, scaleHeight, scaleWidth } from '@/utils';
import {
	LevelPlay,
	LevelPlayAdError,
	LevelPlayAdInfo,
	LevelPlayConfiguration,
	LevelPlayInitError,
	LevelPlayInitListener,
	LevelPlayInitRequest,
	LevelPlayInterstitialAd,
	LevelPlayInterstitialAdListener,
} from 'ironsource-mediation';
import { useEffect, useState } from 'react';
import { ActivityIndicator, Platform, StyleSheet, Text, View } from 'react-native';

type Props = {
	onAdClosed?: () => void;
};

const BANNER_FRONT_UNIT_ID = Platform.select({
	android: 'uzlf2e92cvhgm8x4',
	ios: 'n2q9mb4q8zri270x',
});

const APP_KEY = Platform.select({
	android: '23a5ec315',
	ios: '23a5fa935',
	default: '',
});

const PLACEMENT_NAME = 'FRONT';

const LevelPlayFrontAd = ({ onAdClosed }: Props) => {
	const [interstitialAd, setInterstitialAd] = useState<LevelPlayInterstitialAd>(
		new LevelPlayInterstitialAd(BANNER_FRONT_UNIT_ID!),
	);
	const [isVisible, setIsVisible] = useState(true); // 처음에는 보이도록

	useEffect(() => {
		initIronSourceSDK();
	}, []);

	const initIronSourceSDK = async () => {
		try {
			const initRequest = LevelPlayInitRequest.builder(APP_KEY!).build();

			const initListener: LevelPlayInitListener = {
				onInitSuccess: (config: LevelPlayConfiguration) => {
					console.log('✅ IronSource Init Success:', config);
					interstitialAd.setListener(listener);
					interstitialAd.loadAd();
				},
				onInitFailed: (error: LevelPlayInitError) => {
					console.error('❌ IronSource Init Failed:', error);
				},
			};

			//   테스트 광고 활성화
			// LevelPlay.setMetaData('is_test_suite', ['enable']);
			// LevelPlay.setAdaptersDebug(true);

			// 2. LevelPlay.init 요청을 생성합니다 
			await LevelPlay.init(initRequest, initListener);

			//   필요하다면 Test Suite 실행 (네트워크 설정 확인용)
			// await LevelPlay.launchTestSuite();
		} catch (e) {
			console.error('  Init Exception:', e);
		}
	};

	const listener: LevelPlayInterstitialAdListener = {
		onAdLoaded: (adInfo: LevelPlayAdInfo) => {
			console.log('✅ Interstitial Loaded:', adInfo);
			interstitialAd.showAd(PLACEMENT_NAME);
		},
		onAdLoadFailed: (error: LevelPlayAdError) => {
			console.log('❌ Interstitial Load Fail:', error);
			setIsVisible(false); // 광고 실패 → 오버레이 닫기
			onAdClosed?.(); // 외부 콜백 호출
		},
		onAdDisplayed: (adInfo: LevelPlayAdInfo) => {
			console.log('✅ Interstitial Displayed:', adInfo);
		},
		onAdDisplayFailed: (error: LevelPlayAdError, adInfo: LevelPlayAdInfo) => {
			console.log('❌ Interstitial Display Fail:', error);
			setIsVisible(false); // 표시 실패 → 오버레이 닫기
			onAdClosed?.();
		},
		onAdClosed: (adInfo: LevelPlayAdInfo) => {
			console.log('  Interstitial Closed:', adInfo);
			setIsVisible(false);
			onAdClosed?.();
		},
	};

	return isVisible ? (
		<View style={styles.adOverlay}>
			<View style={styles.container}>
				<ActivityIndicator size="large" color="#3498db" />
				<Text style={styles.loadingTxt}>광고를 준비 중이에요…</Text>
			</View>
		</View>
	) : null;
};
export default LevelPlayFrontAd;

const styles = StyleSheet.create({
	container: {
		padding: scaleHeight(24),
		backgroundColor: '#fff',
		borderRadius: scaleWidth(20),
		alignItems: 'center',
		justifyContent: 'center',
		shadowColor: '#000',
		shadowOpacity: 0.1,
		shadowOffset: { width: 0, height: 2 },
		shadowRadius: 6,
	},

	adOverlay: {
		position: 'absolute',
		top: 0,
		left: 0,
		right: 0,
		bottom: 0,
		backgroundColor: 'rgba(0,0,0,0.4)', // 더 어둡게
		justifyContent: 'center',
		alignItems: 'center',
		zIndex: 999,
	},

	loadingTxt: {
		marginTop: scaleHeight(12),
		fontSize: scaledSize(16),
		color: '#2c3e50',
		fontWeight: '600',
	},

	subTxt: {
		marginTop: scaleHeight(4),
		fontSize: scaledSize(13),
		color: '#7f8c8d',
	},

	mascotImage: {
		width: scaleWidth(80),
		height: scaleWidth(80),
		marginBottom: scaleHeight(16),
		opacity: 0.9,
	},
});

2.3. 결과 화면

결과 화면

- 아래와 같이 전면 광고가 출력이 됨을 확인하였습니다.

오늘도 감사합니다.

[OpenSource] sonarQube 이해하기 -2: SAST/DAST, 종류

adjh54 — Tue, 4 Nov 2025 20:20:24 +0900

해당 글은 sonarQube의 이해를 돕기 위해 작성한 글이며, SAST/DAST와 sonarQube의 종류에 대해 알아봅니다

[참고] 아래의 글에서 이어집니다.

[OpenSource] sonarQube 이해하기 -1 : 정의, 주요특징, 구성요소, 수행 프로세스

해당 글에서는 코드분석도구 중 정적분석 도구인 SonarQube에 대해 이해를 돕기 위해 작성한 글입니다. 1) SonarQube SonarQube- 소스 코드의 품질을 분석하고 관리하기 위한 오픈 소스 플랫폼입니다.-

adjh54.tistory.com

[Docker] Docker로 SonarQube 로컬 설치 및 검증 수행 방법

해당 글에서는 MacOS 내에서 SonarQube Community를 Docker로 구성하여 로컬에 설치하고 검증하는 방법에 대해 알아봅니다. [참고] Docker Desktop이 설치가 되었다는 가정하에 해당 글이 이어집니다. 설

adjh54.tistory.com

1) 정적 애플리케이션 보안 도구(SAST: Static Application Security Testing), 동적 애플리케이션 보안 도구(DAST: Dynamic Application Security Testing)

정적 애플리케이션 보안 도구(SAST: Static Application Security Testing), 동적 애플리케이션 보안 도구(DAST: Dynamic Application Security Testing), 분류 정적 애플리케이션 보안 도구(SAST: Static Application Security Testing) 동적 애플리케이션 보안 도구(DAST: Dynamic Application Security Testing)

목적	코드 품질, 보안 취약점 조기 발견	보안 취약점 탐색
실행 시점	코드를 실행하기 이전에 실행(빌드 전/ 개발 단계)	코드가 실행중인 단계에 실행(테스트/런타임 단계)
적용 단계	개발(Dev) / 빌드(CI) 단계	테스트(QA) / 배포 직전 또는 실제 서버(Pre-prod) 단계
주요 분석 범위	코드 결함, 보안 규칙 위반, 취약한 함수 탐지	SQL Injection, XSS, CSRF, 인증/인가 결함, 서버 설정 오류, 세션 취약점 등
주요 도구	SonarQube, Sparrow SAST, IntelliJ Qodana, Semgrep, Github CodeQL	Sparrow DAST

1. 정적 애플리케이션 보안 도구(SAST: Static Application Security Testing)

정적 애플리케이션 보안 도구(SAST: Static Application Security Testing)
- '소스 코드나 프로그램을 실행하지 않고 소스 코드를 검사하는 방법'입니다. 즉, 애플리케이션이 실행되기 이전에 실행하는 보안 취약점을 식별하는 방법입니다.
- 이 접근 방식에서는 자동화된 도구나 버그, 보안 취약점 또는 코딩 표준에서 벗어난 항목 등 잠재적인 문제를 검사하는 도구를 의미합니다.

What is Static Code Analysis? | JetBrains Qodana

Discover what static code analysis is, how it improves code quality, and how to choose the right tool. Learn benefits, limitations, and best practices.

www.jetbrains.com

https://www.wiz.io/ko-kr/academy/static-application-security-testing-sast

Sparrow SAST를 이용한 웹 취약점 분석 예시

- 아래와 같이 코드를 실행시키면, Sparrow SAST에서 사전에 발생할 수 있는 취약점에 해당하는 항목들이 출력됩니다.

SonarQube를 이용한 웹 취약점 분석 예시

- 아래와 같이 코드를 실행시키면, SonarQube 사전에 발생할 수 있는 취약점에 해당하는 항목들이 출력됩니다.

2. 동적 애플리케이션 보안 도구(DAST: Dynamic Application Security Testing)

동적 애플리케이션 보안 도구(DAST: Dynamic Application Security Testing)

- ‘런타임 단계’에서 소스 코드나 프로그램이 컴파일되어 런타임 단계에서 수행이 될 때 취약점을 검사를 하는 방법입니다.

- 이 단계에서는 메모리 사용, CPU 사용, 네트워크 트래픽 등 다양한 측면을 ‘보안 취약점을 분석’합니다. 실제 공격자처럼 침투하여서 문제를 찾는 도구로써 사용이 됩니다.

[더 알아보기]

성능/부하테스트에서 사용하는 Apache JMeter도 DAST가 되지 않을까?
- DAST의 경우는 보안 취약점 탐지(Injection, XSS, 취약한 인증 등)를 탐지하게 이용이 되지만, JMeter의 경우는 성능 및 부하테스트를 위해서 이용이 됩니다. 그렇기에 목적성으로 볼 때, DAST는 아니고 DAST의 보조적인 도구가 될 수 있습니다.

2) SonarQube

SonarQube

- 소스 코드의 품질 및 코드 보안을 분석하고 관리하기 위한 오픈소스 플랫폼입니다.
- 소스 코드 정적 분석을 수행하여 코드의 버그, 취약점, 코드 스멜(품질이 낮은 코드)을 NIST SSDF, OWASP, CWE, STIG, CASA 등 일반적인 코드 보안 표준을 준수하여 코드를 탐지하고 보고서를 제공합니다. 이를 통해 개발자들은 코드 품질을 향상하고 유지 보수성을 향상할 수 있습니다.
- SonarQube의 제품으로는 SonarQube Server, Cloud, IDE, Advanced Security, MCP Server 등이 있습니다.

https://docs.sonarsource.com/

https://www.sonarsource.com/ko/products/sonarcloud/

[ 더 알아보기 ]

SonarQube는 어떤 기준으로 코드 보안을 탐지하는 것일까?

- NIST SSDF, OWASP, CWE, STIG, CASA 등에서 지정한 기준을 통해서 탐지를 수행합니다.

구분	전체 명칭	주관 기관	주요 목적	핵심 내용 / 구성요소	활용분야
NIST SSDF	National Institute of Standards and Technology – Secure Software Development Framework	NIST (미국 국립표준기술연구소)	안전한 소프트웨어 개발을 위한 표준 프로세스 제시	- 보안 중심의 SDLC(Secure SDLC) 지침- 개발·검증·배포 단계별 보안 통제- 개발자·조직의 역할 명확화	정부기관, 금융, 공공, 대기업의 소프트웨어 보안 정책 수립
OWASP	Open Web Application Security Project	OWASP 재단 (비영리 단체)	웹 애플리케이션 보안 향상 및 개발자 교육	- OWASP Top 10: 주요 웹 취약점 10대 항목- ASVS, MASVS 등 검증 표준 제공- 오픈소스 기반 도구 및 가이드 제공	웹/모바일 앱 개발, 보안 테스트, 개발자 교육
CWE	Common Weakness Enumeration	MITRE (미국 비영리 연구기관)	소프트웨어의 일반적 취약점 유형 분류 및 표준화	- 소스코드 레벨 취약점의 공통 분류 체계- CWE-ID 기반으로 CWE→CVE 매핑- CWE Top 25 매년 발표	취약점 진단, 정적 분석 도구(SAST) 기준, 보안 교육
STIG	Security Technical Implementation Guide	DISA (미 국방정보시스템국)	시스템 및 애플리케이션의 보안 설정 기준 제공	- OS, DB, 네트워크, 앱 등 구성요소별 보안 설정 가이드- DoD 보안 규정 준수 목적- 구체적 기술 설정 지침 포함	국방, 정부기관, 인프라 운영 환경의 보안 설정 준수
CASA	Cloud Application Security Assessment (또는 Cloud & Application Security Architecture)	주로 클라우드 보안 연합(CSA) 및 각 기관별 프레임워크에서 활용	클라우드 환경의 애플리케이션 보안성 평가 프레임워크	- 클라우드 애플리케이션 구성요소의 보안성 검증- 인증, 접근제어, 데이터 보호, 네트워크 정책 포함- DevSecOps 환경에서의 보안 기준 적용	클라우드 서비스, SaaS 보안 검증, CSP 평가 및 인증

1. SonarQube 종류

1.1. SonarQube Server : 자체 관리형

SonarQube Server : 자체 관리형

- 온프레미스 또는 클라우드, 서버 등에 Docker 또는 Kubernetes를 통해 원하는 곳에 직접 배포를 할 수 있는 ‘자체 관리형’을 의미합니다.
- 코드 품질 및 보안 검토를 자동화하고 실행 가능한 코드 인텔리전스를 제공하여 개발자가 더 나은 코드 개발에 집중하고 더 빠르게 작업할 수 있도록 지원합니다.
- SonarQube IDE와 연결하여 코딩 정책을 준수하며 작업을 할 수 있습니다.

구분	Developer Edition	Enterprise Edition	Data Center Edition
가격	연간 $720부터	영업팀 문의 (Talk to sales)	영업팀 문의 (Talk to sales)
대상 규모	10만+ Lines of Code	100만+ Lines of Code	2천만+ Lines of Code
언어/프레임워크 지원	33개	39개	39개
지원 방식	상용 지원 가능 (Commercial support)	상용 지원 가능 (24/7 지원 가능)	상용 지원 포함 (24/7 white-glove 지원)
주요 기능	- AI 생성 코드 자동 탐지 - AI Code Assurance - 고급 버그 탐지(Advanced bug detection) - 비밀키 탐지(Secrets detection, 개선됨)	- Developer Edition의 모든 기능 포함 - AI CodeFix - 세부 프로젝트 건강 리포트- 향상된 인사이트 및 성능	- Enterprise Edition의 모든 기능 포함 - 요청 시 Autoscaling 지원 - 분산 환경 고성능 지원(High performance for distributed teams)
추천 용도	소규모 팀 / 단일 프로젝트	중~대규모 조직 / 다수의 코드베이스	대기업 / 고가용성·확장성 필요 조직
기타 제공	무료 체험(Free trial) 제공	무료 체험 요청 가능	데모 요청 가능(Request a demo)

https://www.sonarsource.com/products/sonarqube/server/

[참고] Docker를 이용한 SonarQube 로컬 설치 및 검증 수행

[Docker] Docker로 SonarQube 로컬 설치 및 검증 수행 방법

adjh54.tistory.com

1.2. SonarQube Cloud : SasS

SonarQube Cloud

- SonarQube 서버를 별도로 설치 및 구성하지 않고, SonarQube Cloud를 활용한 ‘클라우드 기반형’을 의미합니다.
- 동일하게 코드 품질 및 보안 검토를 자동화하고 실행 가능한 코드 인텔리전스를 제공하여 개발자가 더 나은 코드 개발에 집중하고 더 빠르게 작업할 수 있도록 지원합니다.
- SonarQube IDE와 연결하여 코딩 정책을 준수하며 작업을 할 수 있습니다.

https://www.sonarsource.com/products/sonarcloud/

[더 알아보기]
SonarQube의 LOC(Lines of Code, 코드 줄 수)는 어떻게 계산이 될까?

- LOC(Lines of Code, 코드 줄 수)의 경우는 ‘소스 코드에서 실제 로직이 담긴 코드 줄’을 의미합니다. 이는 ‘프로젝트 단위’로 LOC가 계산이 됩니다.

[예시 1]
- 6K LOC의 프로젝트가 있다고 가정하는데, 한 달 동안 100번을 분석하는 경우 청구 금액은 6K로 계산이 됩니다.

[예시 2]
- 10K LOC의 한계가 있다고 하면, 기간 동안 A 프로젝트에서 7K, B 프로젝트에서 3K를 사용할 수 있습니다. 그리고 모두 지우고 A, B, C에 각각 3K로 할당하여서 이용할 수 있습니다. 일종의 하드 디스크와 같은 개념입니다.

- LOC의 포함이 제외된 항목은 빈 줄은 LOC 계산에서 제외가 됩니다 주석은 LOC 계산에서 제외가 됩니다 프로젝트 설정 > 분석대상에서 제외한 파일에 대해서는 LOC 계산에서 제외할 수 있습니다.

https://www.sonarsource.com/ko/plans-and-pricing/

1.3. SonarQube IDE : SonarLint

SonarQube IDE : SonarLint

- 구성한 SonarQube로 접속하여서 프로젝트 내에서 컴파일 시점에 문제를 확인할 수 있습니다. 이는 IDE툴 내의 마켓플레이스에서 다운로드를 하여서 바로 이용할 수 있는 무료 플러그인입니다.
- SonarQube Server나 SonarQube Cloud에 구성된 SonarQube를 연결하여서 이용하는 구조입니다.

아래와 같이, IDE 툴을 이용하는 중에 실시간으로 SonarQube의 취약점에 대해 보여줍니다.

https://www.sonarsource.com/products/sonarlint/

[참고] IntelliJ의 SonarQube Plug-in

SonarQube for IDE - IntelliJ IDEs Plugin | Marketplace

SonarQube for IDE (formerly SonarLint) by Sonar is a free, sophisticated static analysis tool that enhances both your code quality and security. Start analyzing your...

plugins.jetbrains.com

[참고] IntelliJ에서 SonarQube/SonarLint 플러그인으로 이용하는 방법

[IntelliJ] IntelliJ에서 SonarQube/SonarLint 연결방법

해당 글에서는 IntelliJ에서 구성된 SonarQube 연결하는 방법에 대해 알아봅니다.1) 해당 작업이 필요한 이유 해당 작업이 필요한 이유- IntelliJ 내에서 SonarLint로 컴파일 시점에 문제점을 찾고 해결

adjh54.tistory.com

2. SonarQube 장점

2.1. 잠재적인 문제를 포착, 코드 품질 향상

잠재적인 문제를 포착, 코드 품질 향상

- 정적 코드 분석을 이용하면 문제를 조기에 잠재적인 문제를 포착하고 스타일 일관성을 유지하며 코드 품질을 향상할 수 있습니다.
- 예를 들어 파일을 닫는 것을 잊거나 새 변수를 잘못 지정한 경우, 정적 분석 도구는 문제가 발생하기 전에 이러한 문제를 플래그로 표시합니다.

2.2. 사용자 별로 커스텀 구성이 가능함.

사용자 별로 커스텀 구성이 가능함.

- 정적 분석으로 단지 버그를 찾는 것이 아니라, 사용자가 의도한 대로 제품이나 조직이 성장함에 따라서 확장 가능한 코드 인프라를 만드는데 도움이 됩니다.
- 또한 보안 취약점을 식별하고 규제 준수를 보장하며 맞지 않는 라이선스를 플래그로 표시하는 데 중요한 역할을 하므로 코드 품질과 법적 신뢰를 모두 보장하는 데 필수적입니다.

아래와 같이 규칙으로 Rules를 정하여서 필요한 취약점 탐색을 취하고 불필요한 경우는 이를 제외할 수 있어서 사용자 별로 커스텀 환경을 이용할 수 있습니다.

2.3. 지속적인 통합(Continuous Integration)

지속적인 통합(Continuous Integration)

- 정적 분석도구로 CI/CD 파이프라인에 직접 통합을 하면, 모든 커밋의 코딩 오류 표준을 자동으로 검사하게 되므로, 코드 품질을 높이고 유지관리하는데 도움을 줍니다.

2.4. 다양한 통합 플랫폼 & 언어 지원

다양한 통합 플랫폼 & 언어 지원

- 다양한 CI/CD 통합 플랫폼을 지원하고, 다양한 언어에서 코드 품질을 평가할 수 있습니다.
- Commuity 버전(무료)과 EnterPrice 버전(유료)에서 지원하는 언어들이 각각 다르기에 확인이 필요합니다.

https://www.sonarsource.com/integrations/

https://www.sonarsource.com/knowledge/languages/

오늘도 감사합니다.

[Java] Spring Boot 1.5.x 버전 프로젝트 생성 방법(Gradle/Maven) : IntelliJ 활용

adjh54 — Tue, 4 Nov 2025 20:10:13 +0900

해당 글에서는 Spring Boot 1.5.x 버전 기준의 프로젝트를 생성하는 방법에 대해 알아봅니다.

[참고] Spring Boot 2.x.x 버전 프로젝트 생성방법에 대해 궁금하시면 아래의 글을 참고하시면 도움이 됩니다.

[Java] Spring Boot 2.x.x 버전 프로젝트 생성: 지원 종료 및 다운그레이드

해당 글에서는 Spring Boot 2 버전에 대한 프로젝트를 생성하고자 하여 Spring Boot 3 버전을 다운그레이드하여 사용하는 방법에 대해 알아봅니다. 1) Spring Boot 2.x.x 지원 종료 확인 계기- IntelliJ IDEA툴

adjh54.tistory.com

1) Spring Boot 1.5.x 버전 확인

Spring Boot 1.5.x 버전

- Spring Boot 1.x.x 버전을 설치하게 될 일이 있었습니다. 그렇기에 현재 설치가 가능한 Spring Boot 내의 1.x.x 버전을 찾다가 1.x.x의 가장 마지막 버전이 되는 1.5.22 버전을 설치하는 과정을 확인해 봅니다.

Maven Repsitory 내에서 1.x.x 버전을 확인해 보았을 때 가장 최신버전이 1.5.22 버전이기에 이를 설치하려고 합니다.

[ 더 알아보기 ]

왜 1.5.X 버전을 이용하려고 했던 걸까?

- Spring Boot 1.x.x 버전 내에서 Spring Boot Cloud의 Vault를 이용하기 위해서 이를 사용하려고 합니다. 공식 사이트를 방문해서 확인해 보면 1.5.x 버전부터 Spring Boot Cloud를 지원한다고 하기에 이를 이용하려고 합니다.

Spring Cloud

Spring Cloud provides tools for developers to quickly build some of the common patterns in distributed systems (e.g. configuration management, service discovery, circuit breakers, intelligent routing, micro-proxy, control bus, short lived microservices and

spring.io

2) Spring Boot 1.5.22 버전 설치 : Gradle 활용

Spring Boot 1.5.22 버전 설치 : Gradle 활용

- Spring Boot 1.5.22 버전으로 설치하기 위해서, 가장 최신 버전에서 다운그레이드를 수행하는 방식으로 진행합니다.
- 이번 부분에서는 Gradle을 이용한 프로젝트 구성 및 서버 실행까지 구성을 합니다.

1. 환경 확인

환경 확인

- 해당 환경을 구성하기 위해서 아래와 같은 버전으로 구성을 합니다.

분류	버전
Spring Boot	1.5.22
java	1.8
gradle	gradle-4.10.2-all

공식 문서를 참고하여서 해당 환경을 구성합니다.

Spring Boot Reference Guide

24. Externalized Configuration Spring Boot allows you to externalize your configuration so you can work with the same application code in different environments. You can use properties files, YAML files, environment variables and command-line arguments to

docs.spring.io

2. 프로젝트 생성

3. IntelliJ 설정 내에 Gradle JVM을 변경합니다.

IntelliJ 설정 내에 Gradle JVM을 변경합니다.

- 빌드, 실행, 배포 > 빌드 도구 > Gradle 부분에서 Gradle JVM을 jdk 1.8로 변경합니다

4. gradle-wrapper.properties 내에 gradle 버전을 수정합니다.

gradle-wrapper.properties 내에 gradle 버전을 수정합니다

- 위에서 정의한 gradle 버전인 gradle-4.10.2-all을 이용합니다

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
# 아래 부분을 수정합니다.
distributionUrl=https\\://services.gradle.org/distributions/gradle-4.10.2-all.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

5. build.gradle 파일을 수정합니다.

build.gradle 파일을 수정합니다.

- spring boot 버전을 1.5.22으로 변경 및 java 버전을 1.8로 지정합니다

buildscript {
    ext {
        springBootVersion = '1.5.22.RELEASE'
    }
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath "org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}"
    }
}

apply plugin: 'java'
apply plugin: 'org.springframework.boot'
apply plugin: 'io.spring.dependency-management'

group = 'com.test'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = 1.8

repositories {
    mavenCentral()
}

dependencies {
    compile 'org.springframework.boot:spring-boot-starter-web'
    testCompile 'org.springframework.boot:spring-boot-starter-test'
}

6. gradle을 실행합니다

7. 빌드가 정상적으로 실행이 되었습니다

3) Spring Boot 1.5.22 버전 실행하기: Gradle 활용

1. 구성편집을 선택합니다

2. 빌드 및 실행 부분에 java 버전을 변경해 줍니다

3. 서버를 실행합니다.

서버를 실행합니다.

- 서버를 실행했을 때 아래와 같은 오류가 발생합니다.
- Caused by: java.lang.NoClassDefFoundError: com/fasterxml/classmate/TypeResolver at org.hibernate.validator.internal.util.TypeResolutionHelper

4. 오류를 수정하기 위해서 아래와 같이 라이브러리를 추가합니다

오류를 수정하기 위해서 아래와 같이 라이브러리를 추가합니다

- com.fasterxml:classmate 부분을 추가하였습니다.

buildscript {
    ext {
        springBootVersion = '1.5.22.RELEASE'
    }
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath "org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}"

    }
}

apply plugin: 'java'
apply plugin: 'org.springframework.boot'
apply plugin: 'io.spring.dependency-management'

group = 'com.test'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = 1.8

repositories {
    mavenCentral()
}

dependencies {
    compile 'org.springframework.boot:spring-boot-starter-web'

    // 해당 부분 추가 !!!
    compile 'com.fasterxml:classmate:1.3.4'

    testCompile 'org.springframework.boot:spring-boot-starter-test'
}

[ 더 알아보기 ]

com.fasterxml:classmate는 왜 사용하는 걸까?
- Spring Boot 1.5.x는 Hibernate Validator 5.x 버전을 사용합니다
- 이 Hibernate Validator는 객체의 타입 정보를 분석할 때 classmate 라이브러리를 반드시 필요로 합니다.
- @Valid, @NotNull, @Size, @RequestBody validation을 사용하는데 이용이 됩니다.

5. 빌드를 다시 수행합니다

빌드를 다시 수행합니다

- 정상적으로 빌드를 성공하였습니다.

6. 서버를 실행합니다

서버를 실행합니다

- 정상적으로 서버가 실행이 됨을 확인하였습니다.

4) Spring Boot 1.5.22 버전 설치 : Maven 활용

Spring Boot 1.5.22 버전 설치 : Maven 활용

- Spring Boot 1.5.22 버전으로 설치하기 위해서, 가장 최신 버전에서 다운그레이드를 수행하는 방식으로 진행합니다.
- 이번 부분에서는 Maven을 이용한 프로젝트 구성 및 서버 실행까지 구성을 합니다.

1. 환경 확인

환경 확인

- 해당 환경을 구성하기 위해서 아래와 같은 버전으로 구성을 합니다.

분류	버전
Spring Boot	1.5.22
java	1.8
maven	내부 버전

공식 문서를 참고하여서 해당 환경을 구성합니다.

Spring Boot Reference Guide

docs.spring.io

2. 프로젝트 생성

프로젝트 생성

- IntelliJ 내에서 3.x.x 버전을 설치합니다

3. IntelliJ 설정 내에 Maven JDK를 변경합니다.

IntelliJ 설정내에 Maven JDK를 변경합니다.

- 빌드, 실행, 배포 > 빌드 도구 > Maven > 가져오기 부분에서 임포터의 JDK부분을 jdk 1.8로 변경합니다

4. IntelliJ 설정 내에 Maven JRE를 변경합니다.

IntelliJ 설정 내에 Maven JRE를 변경합니다.

- 빌드, 실행, 배포 > 빌드 도구 > Maven > 러너 부분에서 임포터의 JRE 부분을 jdk 1.8로 변경합니다

5. pom.xml 파일을 수정합니다.

pom.xml 파일을 수정합니다.

- spring boot 버전을 1.5.22으로 변경 및 java 버전을 1.8로 지정합니다

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- ✅ Spring Boot 1.5.22.RELEASE -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.22.RELEASE</version>
    </parent>

    <groupId>com.daekyocns</groupId>
    <artifactId>vault</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>vault</name>
    <description>vault</description>

    <properties>
        <!-- ✅ Java 17 → X, Boot 1.x는 Java 8 필요 -->
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- ✅ JUnit5 지원 안 함 → 기본 테스트 사용 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

6. Maven을 실행합니다

7. 빌드가 정상적으로 실행이 되었습니다

5) Spring Boot 1.5.22 버전 실행하기: Maven 활용

1. 구성편집을 선택합니다

2. 빌드 및 실행 부분에 java 버전을 변경해 줍니다

3. 서버를 실행합니다.

서버를 실행합니다.

- 서버를 실행시켰을 때 정상적으로 수행이 됨을 확인하였습니다.

오늘도 감사합니다.

[RN/오류노트] Solved - Families Policy Requirements: Ad Content

adjh54 — Tue, 4 Nov 2025 20:05:46 +0900

React Native 환경에서 Google PlayStore에서 발생한 Families Policy Requirements: Ad Content 문제에 대해 해결 방법을 알아봅니다.

1) 문제점

문제점

- 앱을 출시하는 과정에서 아래와 같은 문제가 발생하였습니다.
- Families Policy Requirements: Ad Content 위와 같은 사항은 "앱의 광고 콘텐츠가 앱의 콘텐츠 등급과 일치하지 않습니다."라는 문제였습니다.

2) 해결 방법

해결 방법

- 구글 플레이 콘솔에서 제안하는 해결 방법은 아래와 같다고 합니다.

- 콘텐츠 등급 문제를 해결하려면 앱 등급과 일치하지 않는 콘텐츠를 삭제하거나 콘텐츠 등급 설문지를 다시 작성하세요. 추가 지침은 등급 설문지 도움말 센터 페이지에서 용어 정의 및 콘텐츠 예시를 참조하세요.

- 앱으로 수익을 창출하는 경우 민감한 카테고리의 광고를 제외했는지 확인하세요.
- 자세한 내용은 가족 정책 요구 사항 의 "광고" 섹션을 참조할 수 있으며, 광고 및 수익 창출 정책 페이지에서 부적절한 광고 콘텐츠의 예를 볼 수 있습니다.

- 위와 같은 가이드라인을 제공하고 있습니다.
- Google의 가족 정책 요구사항(Families Policy Requirements)에서는 아동(13세 미만 또는 지역별 기준 이하 연령)을 대상으로 하는 앱 또는 가족용으로 Play 스토어에 노출되는 앱에 대해 특별한 콘텐츠 및 광고 기준을 적용합니다.

결론적으로는 기존에는 13세 미만 아동에 대해서 타겟으로 진행하고 있음에도 광고가 이에 적합하지 않은 광고가 나와서 발생하는 문제였습니다.

- 실제로 13세 미만을 대상으로 광고를 하는 경우, 광고를 송출하는 쪽에서 이에 대해서 수정하거나 13세 미만을 포함하지 않는 방법을 선택합니다.

3) 해결방법 -1: 13세 미만 아동을 타겟으로 하는 경우

해결방법 -1: 13세 미만 아동을 타겟으로 하는 경우

- 구글 애드몹 플랫폼을 이용하는 경우 ‘광고 콘텐츠 등급’을 지정하여서 13세 미만에게도 광고가 송출되도록 하는 방법입니다.

1. [구글 애드몹] 앱 > 차단 관리 > 광고 콘텐츠 등급 관리 버튼을 누릅니다.

2. 계정 수준 설정 일치 스위치를 누르고, 각각 등급에 맞게 선택을 합니다

계정 수준 설정 일치 스위치를 누르고, 각각 등급에 맞게 선택을 합니다

- 현재와 같은 상황이라면, 일반 잠재 고객인 G 등급을 선택합니다.

광고 콘텐츠	등급 영어 표기	권장 연령대	설명
일반 잠재고객	G (General Audience)	전체 연령대 (모두)	가족 및 아동 포함, 누구에게나 적합한 광고 콘텐츠만 게재 가능. 폭력·음란·도박·주류 등 민감한 요소 전혀 없음.
부모 지도 요망	PG (Parental Guidance)	만 7세 이상 권장	대부분의 연령대에게 적합하지만, 일부 부모의 지도가 필요한 콘텐츠 포함 가능 (예: 약한 만화 폭력, 가벼운 모험 요소 등).
청소년	T (Teen)	만 13세 이상 권장	청소년 이상에게 적합. 일반 보건, SNS, 무서운 이미지, 격투 스포츠 등 약간 성숙한 주제 포함 가능.
성인용	MA (Mature Audience)	만 18세 이상	성인 대상 광고. 주류, 무기, 성적 콘텐츠, 도박 등 민감하거나 제한된 주제 포함 가능.

4) 해결방법 -2: 13세 미만 아동을 타겟으로 하지 않는 경우

해결방법 -2: 13세 미만 아동을 타겟으로 하지 않는 경우

- 해당 경우는 구글 플레이 콘솔에서 설문지를 재 작성해서 13세 미만을 제외하면 됩니다.

1. 구글 플레이 콘솔 > 정책 및 프로그램 > 앱 콘텐츠를 선택합니다

2. 조치됨 탭을 선택하고 콘텐츠 등급의 ‘관리’ 버튼을 누릅니다.

3. 대상 연령대를 9~12세를 제외하여 선택하고 다음 버튼을 누릅니다.

4. ‘저장’ 버튼을 누르고 재 심사를 받으면 완료됩니다.

5. 게시 개요 탭을 눌러서, 아래와 같이 게시 부분이 수정이 되었고, 재 심사를 받습니다

오늘도 감사합니다.