AngelPlayer`s Diary

[DBeaver] Cloud Computer에 설치한 DB 원격 접속 방법

AngelPlayer — Mon, 20 Apr 2026 10:07:19 +0900

운영 서버에 데이터베이스(PostgreSQL)를 구축하고 나면, 로컬 PC에서 DB 툴을 이용해 데이터를 직접 조회하거나 관리해야 할 일이 자주 생깁니다.

이때 가장 간편한 방법은 DB 포트(기본 5432)를 외부 인터넷으로 개방하는 것이지만, 이는 보안상 절대 해서는 안 되는 위험한 행동입니다.

오늘은 가장 대중적인 무료 DB 툴인 DBeaver의 'SSH 터널링(SSH Tunneling)' 기능을 활용하여, 포트 개방 없이 안전하고 편리하게 운영 서버의 DB에 접속하는 방법을 알아보겠습니다.

Step 1. SSH 터널 뚫기

DBeaver에서 새 데이터베이스 연결 (Ctrl + Shift + N)을 진행합니다.

저는 클라우드 컴퓨터에 테스트를 위해 PostgreSQL를 설치 했기에 데이터베이스로 PostgreSQL를 선택했습니다.

화면 우측에 SSH, SSL, Proxy 버튼을 클릭 해 SSH를 선택합니다.

Host/IP
Port
User Name
Authentication Method

를 자신의 환경에 맞게 작성해줍니다.

저는 Password 방식이 아니라 Public Key 방식으로 클라우드 컴퓨터에 접속하는데, DBeaver의 경우 확장자 명이 없는 Private Key 뿐만 아니라 PuTTY 등에서 사용하는 .ppk도 지원합니다.

SSH 탭 설정을 마쳤다면, 이제 맨 앞의 Main (일반) 탭으로 돌아옵니다.

Host: localhost (또는 127.0.0.1)를 입력합니다.
Port: 5432 (PostgreSQL 기본 포트)
Database: 접속할 실제 데이터베이스 이름
Username: DB 접속 계정명
Password: DB 계정 비밀번호

를 입력합니다.

여기서 Host가 내 클라우드 컴퓨터 IP가 아니라 localhost인 이유는 이전에 SSH 터널을 뚫어두었기 때문에, DBeaver 입장에서는 이 터널을 통해 원격 서버가 마치 내 컴퓨터(localhost) 안에 있는 것처럼 인식하기 때문입니다.

모든 정보를 입력한 후 창 하단의 [Test Connection (연결 테스트)] 버튼을 눌러 연결 성공 메시지를 먼저 확인한 뒤 [완료]를 누릅니다.

연결이 성공하면 DB 목록에 잘 뜨는 것을 확인하실 수 있습니다.

[Error] CORS 에러 개념 & 해결방법 (feat. SpringBoot)

AngelPlayer — Sun, 21 Dec 2025 16:46:47 +0900

CORS(Cross-Origin Resource Sharing)

CORS는 브라우저가 다른 출처(origin)로 보낸 요청의 응답을 JavaScript에서 접근할 수 있을지 결정하는 보안 정책입니다.

브라우저는 악성 사이트가 사용자의 인증 정보를 이용해 민감한 API 응답을 읽는 것을 방지하기 위해 기본적으로 다른 출처의 응답을 JavaScript에서 차단합니다.

다른 출처(origin)는 크게

- 프로토콜: http / https
- 도메인(호스트): localhost
- 포트 : 3000, 8080

위 3가지로 구분됩니다.

프론트와 백을 기준으로 보면 어떤 사이트(3000)가 다른 사이트(8080)에 사용자의 쿠키를 포함해서 요청을 보내는 것을 예로 들 수 있습니다.

허용 방법

1. CorsConfig

package com.tistory.angelplayer.oauth.global.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.CorsConfigurationSource;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;

import java.util.List;

@Configuration
public class CorsConfig {

    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration config = new CorsConfiguration();

        // ✅ 쿠키 포함 요청 허용 (credentials: 'include' 때문에 필수)
        config.setAllowCredentials(true);

        // ✅ 허용할 프론트 origin을 정확히 명시해야 함 (* 금지)
        config.setAllowedOrigins(List.of("http://localhost:3000"));

        // ✅ 허용 메서드/헤더
        config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
        config.setAllowedHeaders(List.of("*"));

        // (선택) Set-Cookie 등을 브라우저에서 읽어야 할 때
        // config.setExposedHeaders(List.of("Set-Cookie"));

        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", config);
        return source;
    }
}

2. 코드 활성

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
        .cors(Customizer.withDefaults())
        .csrf(csrf -> csrf.disable());

    return http.build();
}

CorsConfig를 활성화하는 코드를 SecurityFilterChain 내부에에 입력면 CORS 에러가 해결됩니다.

정리 : CORS는 브라우저가 다른 출처의 응답을 JavaScript에서 읽을 수 있을지 결정하는 보안 정책이며, Spring Security에서는 별도로 cors()를 활성화해야 적용됩니다.

[Redis] Windows에 Redis 설치하기

AngelPlayer — Sat, 20 Dec 2025 14:50:31 +0900

Windows 환경에서 레디스를 설치 후 사용하는 방법은 크게 2가지가 있습니다.

1. Redis for Windows 설치 파일을 통한 Windows 내 Redis 설치

2. 가상환경에 Redis 설치

https://github.com/microsoftarchive/redis/releases

Releases · microsoftarchive/redis

Redis is an in-memory database that persists on disk. The data model is key-value, but many different kind of values are supported: Strings, Lists, Sets, Sorted Sets, Hashes - microsoftarchive/redis

github.com

1번의 경우 2021년 이후 업데이트가 진행되지 않아 레디스 버전을 6.x 밖에 사용하지 못합니다.

따라서 저희는 WSL2 + Ubuntu 환경에 Redis를 설치하겠습니다.

※ WSL (Windows Subsystem for Linux) : Windows 위에서 Linux를 실행하게 해주는 호환 계층(subsystem)
※ WSL2 : WSL1은 Windows 커널 위에서 Linux 시스템 콜을 번역하여 실행하는 방식인 반면, WSL2는 실제 Linux 커널을 가상 머신에서 실행하는 방식

1. Ubuntu 설치

가상환경을 사용하기 위해서는 몇 가지 환경설정이 필요합니다.

먼저 작업 관리자에서 성능 - CPU로 들어가 가상화가 사용으로 되어있는지 확인해야 합니다.

만약 사용 안 함으로 되어 있다면, BIOS 설정 등에서 가상화 기능을 켜주셔야 합니다.

메인보드 제조사마다 설정 방법이 서로 다르기 때문에 사용하는 보드의 제조사에서 가상화 켜는 방법을 검색해보시기 바랍니다.

Windows 기능 켜기/끄기에서 아래 3가지 기능을 켜주셔야 합니다.

- 가상 머신 플랫폼
- Linux용 Windows 하위 시스템
- Hyper-V (Optional)

현재 테스트 중인 PC의 경우 Windows(11) Home Edition이 설치되어 있는데, Home 버전의 경우 Hyper-V 기능이 따로 없습니다.

다만 Hyper-V 없이도 WSL2를 사용할 수 있기 때문에 Windows Home의 경우 Hyper-V를 제외한 두 가지를 체크 한 뒤 확인을 눌러줍니다.

다음으로 PowerShell을 켜줍니다.

PowerShell 실행 시 관리자 권한으로 실행해야 합니다.

wsl --set-default-version 2

wsl --status       # Default Version: 2 출력을 확인하기

wsl --update

PowerShell에서 위 명령을 입력한 뒤 정상적으로 완료되는지 확인합니다.

이후 재부팅을 진행합니다.

다음으로 Microsoft Store에서 Ubuntu를 설치합니다.

저는 22.04 버전으로 설치를 진행하였습니다.

정상적으로 설치가 완료되었다면 계정 생성 문구가 뜹니다.

※ Ubuntu 설치 후 실행 시 에러 발생 시

만약 설치가 제대로 되지 않는다면 0x80370114 에러가 발생할 수 있습니다.

해당 에러는

- Virtual Machine Platform 비활성화
- BIOS 가상화 OFF
- Windows 기능 반영 실패 (UI 체크만 한 경우)
- VMware / VirtualBox 충돌

등이 원인이 되어 발생할 수 있습니다.

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all


# 다시 작성
wsl --set-default-version 2

wsl --status       # Default Version: 2 출력을 확인하기

wsl --update

그럼 다시 PowerShell을 열어서 dism 명령어를 작성합니다.

이를 통해 정상적으로 동작하지 않던 기능을 활성화 할 수 있습니다.

이후 재부팅 및 Ubuntu 재설치를 진행하면 Redis를 설치할 수 있는 WSL2 환경 구성이 완료됩니다.

2. Redis 설치

curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list

sudo apt-get update

sudo apt-get install redis

다음으로 Redis 설치를 진행합니다.

Ubuntu 터미널에서 위 명령어를 입력합니다.

install redis 명령이 정상적으로 동작하면 설치가 완료된 것입니다.

설치 후 테스트를 위해 redis-cli로 들어가 ping을 입력합니다.

응답으로 PONG이 오면 정상적으로 동작하는 것입니다.

# Redis 설치
sudo apt update
sudo apt install -y redis-server


# redis 서비스 시작
sudo service redis-server start
sudo service redis-server status


# 재부팅 후에도 자동 실행되게 하는 명령어
sudo systemctl enable redis-server


# Redis 비밀번호 설정
sudo nano /etc/redis/redis.conf

requirepass 비밀번호입력

sudo service redis-server restart 


# 테스트
redis-cli ping
redis-cli -a 비밀번호 ping

[OAuth] 02 Session에서 JWT + Token 방식으로 전환

AngelPlayer — Mon, 1 Dec 2025 19:55:31 +0900

앞선 포스트에서 Google OAuth와 SpringBoot, Next.js로 간단히 소셜 로그인과 방명록 기능을 구현해보았습니다.

기존 구현에서는 로그인한 사용자를 인증하기 위해 Session 방식을 사용하였습니다.

하지만 최근에는

이전 포스트의 소스코드 : 세션방식
Google OAuth 로그인 → Spring Security 세션에 OAuth2User 저장
브라우저는 JSESSIONID 쿠키로 로그인 유지
컨트롤러에서 @AuthenticationPrincipal OAuth2User principal 사용

앞으로 개선할 방향 : JWT 방식
OAuth 로그인 성공 시
서버가 Access Token / Refresh Token(JWT) 를 생성
이 둘을 HttpOnly 쿠키(예: ACCESS_TOKEN, REFRESH_TOKEN) 로 내려줌

프론트는 그냥 credentials: 'include' 그대로 사용 → 쿠키 자동 전송
이후 API 호출

JSESSIONID 대신 ACCESS_TOKEN 쿠키를 읽어 검증
토큰이 유효하면 SecurityContext 에 Authentication 넣어줌
컨트롤러는 @AuthenticationPrincipal 로 사용자 정보 사용

세션은 더 이상 인증에 쓰이지 않음

백엔드 수정 사항

com/tistory/angelplayer/oauth
    ├── OauthApplication.java                      # 스프링 부트 메인 클래스
    │
    ├── config
    │    ├── SecurityConfig.java                   # ★ 시큐리티 설정 (OAuth2 + JWT + CORS)
    │    ├── JwtTokenProvider.java                 # ★ JWT 생성/검증 유틸
    │    └── JwtAuthenticationFilter.java          # ★ 요청마다 AccessToken 검증 필터
    │
    ├── auth
    │    ├── controller
    │    │      └── AuthController.java            # ★ /me, /refresh, /logout API
    │    │
    │    ├── handler
    │    │      └── OAuth2LoginSuccessHandler.java # ★ 구글 로그인 성공 → JWT 발급 & 쿠키 저장
    │    │
    │    ├── entity
    │    │      └── RefreshToken.java              # ★ 사용자별 RefreshToken 저장 엔티티
    │    │
    │    ├── repository
    │    │      └── RefreshTokenRepository.java    # ★ RefreshToken JPA 리포지토리
    │    │
    │    └── service
    │           └── AuthService.java               # ★ RefreshToken 저장/검증 & 토큰 재발급 로직
    │
    └── guestbook
         ├── controller
         │      └── GuestbookController.java       # 방명록 API (JWT 인증 필요)
         ├── dto
         │      └── GuestbookRequestDto.java
         ├── entity
         │      └── GuestbookEntry.java
         ├── repository
         │      └── GuestbookEntryRepository.java
         └── service
                └── GuestbookService.java

이번에 변경될 새로운 파일 구조입니다.

1) build.gardle

dependencies {
    // ... 기존 내용

    implementation 'io.jsonwebtoken:jjwt-api:0.11.5'
    runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.11.5'
    runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.11.5'
}

JWT 서명용 키와 유효시간을 설정합니다.

JwtTokenProvider 가 이 값을 읽어서 토큰을 생성/검증합니다.

2) application.yml 에 JWT 설정 값 추가

jwt:
  secret: "ZmFrZV9zZWNyZXRfZmFrZV9zZWNyZXRfZmFrZV9zZWNyZXQ="  # 32바이트 이상 Base64 문자열
  access-token-validity-in-seconds: 3600       # Access Token 1시간
  refresh-token-validity-in-seconds: 604800    # Refresh Token 7일

jwt:는 spring:과 동급입니다.

하위에 넣으시면 안됩니다.

3) JwtTokenProvider.java (JWT 생성/검증 유틸)

package com.tistory.angelplayer.oauth.config;

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.JwtException;
import io.jsonwebtoken.SignatureAlgorithm;
import io.jsonwebtoken.io.Decoders;
import io.jsonwebtoken.security.Keys;
import jakarta.annotation.PostConstruct;
import lombok.RequiredArgsConstructor;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.User;
import org.springframework.stereotype.Component;

import java.security.Key;
import java.util.Collections;
import java.util.Date;

@Component
@RequiredArgsConstructor
public class JwtTokenProvider {

    @Value("${jwt.secret}")
    private String secret;

    @Value("${jwt.access-token-validity-in-seconds}")
    private long accessTokenValidityInSeconds;

    @Value("${jwt.refresh-token-validity-in-seconds}")
    private long refreshTokenValidityInSeconds;

    private Key key;

    @PostConstruct
    public void init() {
        // application.yml의 Base64 secret 문자열을 디코딩해서 HMAC 키 생성
        byte[] keyBytes = Decoders.BASE64.decode(secret);
        this.key = Keys.hmacShaKeyFor(keyBytes);
    }

    // AccessToken 생성 (email, name claim 포함)
    public String createAccessToken(String email, String name) {
        Date now = new Date();
        Date expiry = new Date(now.getTime() + accessTokenValidityInSeconds * 1000);

        return Jwts.builder()
                .setSubject(email)          // 토큰 주체: 이메일
                .claim("name", name)        // 클레임에 이름 저장 (필요 시 사용)
                .setIssuedAt(now)           // 발급 시각
                .setExpiration(expiry)      // 만료 시각
                .signWith(key, SignatureAlgorithm.HS256)
                .compact();
    }

    // RefreshToken 생성
    public String createRefreshToken(String email) {
        Date now = new Date();
        Date expiry = new Date(now.getTime() + refreshTokenValidityInSeconds * 1000);

        return Jwts.builder()
                .setSubject(email)
                .setIssuedAt(now)
                .setExpiration(expiry)
                .signWith(key, SignatureAlgorithm.HS256)
                .compact();
    }

    // 토큰 유효성 검증 (서명 + 만료 체크)
    public boolean validateToken(String token) {
        try {
            Jwts.parserBuilder()
                    .setSigningKey(key)
                    .build()
                    .parseClaimsJws(token);
            return true;
        } catch (JwtException | IllegalArgumentException e) {
            // 서명 오류, 만료, 형식 오류 등 → 전부 false 처리
            return false;
        }
    }

    // 토큰에서 Claims 꺼내기 (이메일, name 등 필요하면 사용)
    public Claims getClaims(String token) {
        return Jwts.parserBuilder()
                .setSigningKey(key)
                .build()
                .parseClaimsJws(token)
                .getBody();
    }

    // 토큰에서 Authentication 객체 생성
    public Authentication getAuthentication(String token) {
        Claims claims = getClaims(token);
        String email = claims.getSubject();

        // 현재는 ROLE_USER 하나만 부여
        SimpleGrantedAuthority authority = new SimpleGrantedAuthority("ROLE_USER");

        User principal = new User(
                email,                               // username
                "",                                  // password (사용 안 함)
                Collections.singletonList(authority) // 권한 리스트
        );

        return new UsernamePasswordAuthenticationToken(
                principal,
                token,                               // credentials 자리에 토큰 자체
                principal.getAuthorities()
        );
    }

    public long getAccessTokenValidityInSeconds() {
        return accessTokenValidityInSeconds;
    }

    public long getRefreshTokenValidityInSeconds() {
        return refreshTokenValidityInSeconds;
    }
}

AccessToken / RefreshToken 생성

토큰의 유효성 검증

토큰에서 Authentication 객체 만들기 (email 기반 UserDetails)

4) JwtAuthenticationFilter.java (요청마다 AccessToken 인증)

// com/tistory/angelplayer/oauth/config/JwtAuthenticationFilter.java

package com.tistory.angelplayer.oauth.config;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;

@RequiredArgsConstructor
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final JwtTokenProvider jwtTokenProvider;

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain)
            throws ServletException, IOException {

        String token = resolveToken(request);

        if (token != null && jwtTokenProvider.validateToken(token)) {
            Authentication authentication = jwtTokenProvider.getAuthentication(token);
            SecurityContextHolder.getContext().setAuthentication(authentication);
        }

        filterChain.doFilter(request, response);
    }

    // 쿠키(ACCESS_TOKEN) 또는 Authorization 헤더에서 토큰 추출
    private String resolveToken(HttpServletRequest request) {
        // 1) 쿠키 우선
        if (request.getCookies() != null) {
            for (Cookie cookie : request.getCookies()) {
                if ("ACCESS_TOKEN".equals(cookie.getName())) {
                    return cookie.getValue();
                }
            }
        }

        // 2) Authorization: Bearer 토큰도 지원 (필요시)
        String bearer = request.getHeader("Authorization");
        if (bearer != null && bearer.startsWith("Bearer ")) {
            return bearer.substring(7);
        }

        return null;
    }
}

매 HTTP 요청마다 쿠키의 ACCESS_TOKEN 또는 Authorization 헤더에서 토큰을 읽고 검증

유효하면 SecurityContext 에 Authentication 세팅

세션 없이 JWT만으로 인증을 처리

5. RefreshToken.java (RefreshToken 엔티티)

// com/tistory/angelplayer/oauth/auth/entity/RefreshToken.java

package com.tistory.angelplayer.oauth.auth.entity;

import jakarta.persistence.*;
import lombok.*;

import java.time.Instant;

@Entity
@Table(name = "refresh_tokens")
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class RefreshToken {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    // 이메일을 사용자 식별자처럼 사용 (별도 User 엔티티 없으므로)
    @Column(nullable = false, unique = true)
    private String email;

    @Column(nullable = false, length = 512)
    private String token;

    @Column(nullable = false)
    private Instant expiry;
}

사용자(email)별 현재 유효한 RefreshToken 을 DB에 저장

재발급 시 저장된 토큰과 비교하여 탈취/중복 사용 방지

6) RefreshTokenRepository.java (리포지토리)

package com.tistory.angelplayer.oauth.auth.repository;

import com.tistory.angelplayer.oauth.auth.entity.RefreshToken;
import org.springframework.data.jpa.repository.JpaRepository;

import java.util.Optional;

public interface RefreshTokenRepository extends JpaRepository<RefreshToken, Long> {

    Optional<RefreshToken> findByEmail(String email);

    Optional<RefreshToken> findByToken(String token);

    void deleteByEmail(String email);
}

이메일 기준으로 RefreshToken을 조회/저장/삭제

7) AuthService.java (RefreshToken 관리 + 재발급 로직)

package com.tistory.angelplayer.oauth.auth.service;

import com.tistory.angelplayer.oauth.auth.entity.RefreshToken;
import com.tistory.angelplayer.oauth.auth.repository.RefreshTokenRepository;
import com.tistory.angelplayer.oauth.config.JwtTokenProvider;
import io.jsonwebtoken.Claims;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.time.Instant;
import java.util.Map;

@Service
@RequiredArgsConstructor
public class AuthService {

    private final JwtTokenProvider jwtTokenProvider;
    private final RefreshTokenRepository refreshTokenRepository;

    // 로그인 성공 시 RefreshToken 저장/업데이트
    @Transactional
    public void saveRefreshToken(String email, String refreshToken) {
        Instant expiry = Instant.now()
                .plusSeconds(jwtTokenProvider.getRefreshTokenValidityInSeconds());

        refreshTokenRepository.findByEmail(email)
                .ifPresentOrElse(
                        entity -> {
                            entity.setToken(refreshToken);
                            entity.setExpiry(expiry);
                        },
                        () -> {
                            RefreshToken newToken = RefreshToken.builder()
                                    .email(email)
                                    .token(refreshToken)
                                    .expiry(expiry)
                                    .build();
                            refreshTokenRepository.save(newToken);
                        }
                );
    }

    // 로그아웃 시 RefreshToken 삭제
    @Transactional
    public void deleteRefreshToken(String email) {
        refreshTokenRepository.deleteByEmail(email);
    }

    // RefreshToken으로 AccessToken + RefreshToken 재발급
    @Transactional
    public Map<String, String> reissueTokens(String refreshToken) {
        // 1) 토큰 형식/만료 검증
        if (!jwtTokenProvider.validateToken(refreshToken)) {
            throw new IllegalArgumentException("유효하지 않거나 만료된 RefreshToken 입니다.");
        }

        Claims claims = jwtTokenProvider.getClaims(refreshToken);
        String email = claims.getSubject();

        // 2) DB에 저장된 RefreshToken과 일치하는지 확인
        RefreshToken saved = refreshTokenRepository.findByEmail(email)
                .orElseThrow(() -> new IllegalArgumentException("저장된 RefreshToken이 없습니다."));

        if (!saved.getToken().equals(refreshToken)) {
            throw new IllegalArgumentException("RefreshToken이 일치하지 않습니다.");
        }

        if (saved.getExpiry().isBefore(Instant.now())) {
            throw new IllegalArgumentException("RefreshToken이 만료되었습니다.");
        }

        // 3) 새 AccessToken + RefreshToken 생성
        String newAccessToken = jwtTokenProvider.createAccessToken(email, (String) claims.get("name"));
        String newRefreshToken = jwtTokenProvider.createRefreshToken(email);

        // 4) DB에 RefreshToken 업데이트
        saveRefreshToken(email, newRefreshToken);

        return Map.of(
                "accessToken", newAccessToken,
                "refreshToken", newRefreshToken
        );
    }
}

로그인 성공 시 RefreshToken 저장/업데이트

전달받은 RefreshToken 검증 후, 새 AccessToken + RefreshToken 발급

로그아웃 시 RefreshToken 삭제

8) OAuth2LoginSuccessHandler.java (구글 로그인 성공 → JWT + 쿠키)

package com.tistory.angelplayer.oauth.auth.handler;

import com.tistory.angelplayer.oauth.auth.service.AuthService;
import com.tistory.angelplayer.oauth.config.JwtTokenProvider;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.security.core.Authentication;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.security.web.authentication.AuthenticationSuccessHandler;
import org.springframework.stereotype.Component;

import java.io.IOException;
import java.util.Map;

@Component
@RequiredArgsConstructor
public class OAuth2LoginSuccessHandler implements AuthenticationSuccessHandler {

    private final JwtTokenProvider jwtTokenProvider;
    private final AuthService authService;

    @Override
    public void onAuthenticationSuccess(HttpServletRequest request,
                                        HttpServletResponse response,
                                        Authentication authentication)
            throws IOException, ServletException {

        OAuth2User oAuth2User = (OAuth2User) authentication.getPrincipal();
        Map<String, Object> attrs = oAuth2User.getAttributes();

        String email = (String) attrs.get("email");
        String name  = (String) attrs.get("name");

        // 1) Access / Refresh Token 생성
        String accessToken  = jwtTokenProvider.createAccessToken(email, name);
        String refreshToken = jwtTokenProvider.createRefreshToken(email);

        // 2) RefreshToken DB 저장
        authService.saveRefreshToken(email, refreshToken);

        // 3) 쿠키에 저장 (HttpOnly)
        addCookie(response, "ACCESS_TOKEN", accessToken,
                (int) jwtTokenProvider.getAccessTokenValidityInSeconds());
        addCookie(response, "REFRESH_TOKEN", refreshToken,
                (int) jwtTokenProvider.getRefreshTokenValidityInSeconds());

        // 4) 프론트엔드 페이지로 리다이렉트
        response.sendRedirect("http://localhost:3000/guestbook");
    }

    private void addCookie(HttpServletResponse response,
                           String name,
                           String value,
                           int maxAge) {

        Cookie cookie = new Cookie(name, value);
        cookie.setHttpOnly(true);  // JS에서 접근 불가 → XSS 방지
        cookie.setPath("/");
        cookie.setMaxAge(maxAge);
        // 개발 환경에서는 http, 운영에서는 https + Secure 설정 권장
        // cookie.setSecure(true);

        response.addCookie(cookie);
    }
}

Google OAuth2 로그인 성공 시 아래 기능을 수행

- 구글 프로필에서 email, name 추출
- AccessToken + RefreshToken 생성
- RefreshToken DB 저장
- 두 토큰을 HttpOnly 쿠키 로 브라우저에 전달
- 프론트 /guestbook 페이지로 리다이렉트

9) SecurityConfig.java (시큐리티 설정 변경)

package com.tistory.angelplayer.oauth.config;

import com.tistory.angelplayer.oauth.auth.handler.OAuth2LoginSuccessHandler;
import lombok.RequiredArgsConstructor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.CorsConfigurationSource;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;

import java.util.List;

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfig {

    private final JwtTokenProvider jwtTokenProvider;
    private final OAuth2LoginSuccessHandler oAuth2LoginSuccessHandler;

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {

        http
                .csrf(csrf -> csrf.disable())
                .cors(Customizer.withDefaults())
                .sessionManagement(session ->
                        session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
                )
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/", "/oauth2/**", "/login/**").permitAll()
                        .requestMatchers("/api/auth/**").permitAll() // /me, /refresh, /logout
                        .anyRequest().authenticated()
                )
                .oauth2Login(oauth -> oauth
                        .successHandler(oAuth2LoginSuccessHandler)
                )
                .logout(logout -> logout
                        .logoutUrl("/logout")
                        .deleteCookies("ACCESS_TOKEN", "REFRESH_TOKEN")
                        .logoutSuccessUrl("http://localhost:3000")
                );

        // JWT 필터를 UsernamePasswordAuthenticationFilter 앞에 추가
        http.addFilterBefore(
                new JwtAuthenticationFilter(jwtTokenProvider),
                UsernamePasswordAuthenticationFilter.class
        );

        return http.build();
    }

    // CORS: 프론트 개발용 설정
    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowedOriginPatterns(List.of("http://localhost:3000"));
        config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
        config.setAllowedHeaders(List.of("*"));
        config.setAllowCredentials(true); // 쿠키 포함 허용

        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", config);
        return source;
    }
}

세션을 사용하지 않고 STATELESS 로 설정

OAuth2 로그인 성공 시 OAuth2LoginSuccessHandler 사용

JwtAuthenticationFilter 를 필터 체인에 추가

CORS 설정 (localhost:3000 허용)

/api/auth/**, /oauth2/** 등 일부 엔드포인트는 인증 없이 허용

10) AuthController.java (me + refresh + logout API)

package com.tistory.angelplayer.oauth.auth.controller;

import com.tistory.angelplayer.oauth.auth.service.AuthService;
import com.tistory.angelplayer.oauth.config.JwtTokenProvider;
import io.jsonwebtoken.Claims;
import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.http.HttpStatus;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

@RestController
@RequestMapping("/api/auth")
@RequiredArgsConstructor
public class AuthController {

    private final JwtTokenProvider jwtTokenProvider;
    private final AuthService authService;

    // 1) 현재 로그인 정보 조회
    @GetMapping("/me")
    public Map<String, Object> me(@AuthenticationPrincipal UserDetails user) {
        if (user == null) {
            return Map.of("authenticated", false);
        }
        return Map.of(
                "authenticated", true,
                "email", user.getUsername()
        );
    }

    // 2) RefreshToken으로 AccessToken + RefreshToken 재발급
    @PostMapping("/refresh")
    public Map<String, Object> refresh(HttpServletRequest request,
                                       HttpServletResponse response) {

        String refreshToken = extractCookie(request, "REFRESH_TOKEN");
        if (refreshToken == null) {
            throw new IllegalArgumentException("RefreshToken 쿠키가 없습니다.");
        }

        Map<String, String> tokens = authService.reissueTokens(refreshToken);

        // 쿠키 재설정
        addCookie(response, "ACCESS_TOKEN", tokens.get("accessToken"),
                (int) jwtTokenProvider.getAccessTokenValidityInSeconds());
        addCookie(response, "REFRESH_TOKEN", tokens.get("refreshToken"),
                (int) jwtTokenProvider.getRefreshTokenValidityInSeconds());

        // 응답 바디에는 간단히 ok 정도만 내려도 되고, 토큰을 넣어도 됩니다.
        return Map.of(
                "status", "ok"
        );
    }

    // 3) 로그아웃 (RefreshToken DB 삭제 + 쿠키 삭제)
    @PostMapping("/logout")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void logout(@AuthenticationPrincipal UserDetails user,
                       HttpServletResponse response) {

        if (user != null) {
            authService.deleteRefreshToken(user.getUsername());
        }

        // 쿠키 삭제
        deleteCookie(response, "ACCESS_TOKEN");
        deleteCookie(response, "REFRESH_TOKEN");
    }

    // ====== 유틸 메서드 ======

    private String extractCookie(HttpServletRequest request, String name) {
        if (request.getCookies() == null) return null;
        for (Cookie cookie : request.getCookies()) {
            if (name.equals(cookie.getName())) {
                return cookie.getValue();
            }
        }
        return null;
    }

    private void addCookie(HttpServletResponse response,
                           String name,
                           String value,
                           int maxAge) {

        Cookie cookie = new Cookie(name, value);
        cookie.setHttpOnly(true);
        cookie.setPath("/");
        cookie.setMaxAge(maxAge);
        response.addCookie(cookie);
    }

    private void deleteCookie(HttpServletResponse response, String name) {
        Cookie cookie = new Cookie(name, "");
        cookie.setPath("/");
        cookie.setMaxAge(0);
        response.addCookie(cookie);
    }
}

/api/auth/me
- 현재 로그인 정보(이메일) 확인

/api/auth/refresh
- RefreshToken 쿠키를 읽어 새 Access/Refresh 토큰 발급
- 쿠키 갱신

/api/auth/logout
- RefreshToken DB 삭제 + 쿠키 삭제

11) GuestbookController.java (JWT 기반으로 사용자 정보 받기)

package com.tistory.angelplayer.oauth.guestbook.controller;

import com.tistory.angelplayer.oauth.guestbook.dto.GuestbookRequestDto;
import com.tistory.angelplayer.oauth.guestbook.entity.GuestbookEntry;
import com.tistory.angelplayer.oauth.guestbook.service.GuestbookService;
import lombok.RequiredArgsConstructor;
import org.springframework.http.HttpStatus;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.server.ResponseStatusException;

import java.util.List;

@RestController
@RequestMapping("/api/guestbook")
@RequiredArgsConstructor
public class GuestbookController {

    private final GuestbookService guestbookService;

    @GetMapping
    public List<GuestbookEntry> list() {
        return guestbookService.getAll();
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public GuestbookEntry create(@AuthenticationPrincipal UserDetails user,
                                 @RequestBody GuestbookRequestDto dto) {
        if (user == null) {
            throw new ResponseStatusException(HttpStatus.UNAUTHORIZED, "로그인이 필요합니다.");
        }

        if (dto.getMessage() == null || dto.getMessage().trim().isEmpty()) {
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "메시지를 입력하세요.");
        }

        String email = user.getUsername();
        String name = "익명"; // JWT claim에서 name을 꺼내고 싶으면 추가 작업 가능

        return guestbookService.createEntry(email, name, dto);
    }
}

@AuthenticationPrincipal UserDetails user 를 사용하여 JWT에서 나온 사용자 이메일을 이용해 글 작성자 정보 설정

12) GuestbookService.java

package com.tistory.angelplayer.oauth.guestbook.service;

import com.tistory.angelplayer.oauth.guestbook.dto.GuestbookRequestDto;
import com.tistory.angelplayer.oauth.guestbook.entity.GuestbookEntry;
import com.tistory.angelplayer.oauth.guestbook.repository.GuestbookEntryRepository;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;

import java.time.Instant;
import java.time.LocalDateTime;
import java.util.List;

@Service
@RequiredArgsConstructor
public class GuestbookService {

    private final GuestbookEntryRepository guestbookEntryRepository;

    /**
     * 방명록 전체 목록 조회
     */
    public List<GuestbookEntry> getAll() {
        // 단순 전체 조회. 필요하면 정렬 조건 추가 가능
        return guestbookEntryRepository.findAll();
    }

    /**
     * 방명록 글 등록
     * @param email 작성자 이메일 (JWT에서 추출)
     * @param name  작성자 이름(또는 닉네임)
     * @param dto   요청 DTO (message 등)
     */
    public GuestbookEntry createEntry(String email, String name, GuestbookRequestDto dto) {
        GuestbookEntry entry = new GuestbookEntry();
        entry.setUserEmail(email);
        entry.setUserName(name);
        entry.setMessage(dto.getMessage());
        entry.setCreatedAt(LocalDateTime.from(Instant.now()));

        return guestbookEntryRepository.save(entry);
    }
}

.getAll() 추가

Front-end의 경우 기존 소스코드를 그대로 유지해도 새롭게 변경된 JWT 기능이 정상적으로 동작합니다.

[OAuth] 01 Google OAuth + SpringBoot + Next로 간편 로그인 구현

AngelPlayer — Mon, 1 Dec 2025 15:59:36 +0900

Google OAuth를 활용하여 간편 로그인 기능 + 방명록을 구현해 보겠습니다.

기능

- Google OAuth

- Session 기반 인증 방식

사용 프레임워크/라이브러리

- Next.js 14

- SpringBoot 3

1. Google Cloud Console 설정

https://cloud.google.com/

클라우드 컴퓨팅 서비스 | Google Cloud

데이터 관리, 하이브리드 및 멀티 클라우드, AI와 머신러닝 등 Google의 클라우드 컴퓨팅 서비스로 비즈니스 당면 과제를 해결하세요.

cloud.google.com

먼저 새 프로젝트를 생성해야 합니다.

Google Cloud Console로 이동하여 로그인 후 [프로젝트 선택 - 새 프로젝트]를 눌러줍니다.

다음으로 프로젝트 이름을 지정하고 [만들기]를 클릭합니다.

프로젝트가 생성되었으면, 면 좌측의 메뉴에서 [API 및 서비스 - OAuth 동의 화면]을 클릭합니다.

OAuth 개요에서 [시작하기] 버튼을 눌러줍니다.

다음으로 프로젝트 구성을 작성합니다.

앱 정보 탭에서는 앱 이름과, 사용자가 지원 요청 시 전달받을 이메일을 지정합니다.

대상 탭에서는 외부를 선택해줍니다.

연락처 정보 탭에서는 연락처 정보 추가 해줍니다.

완료 탭에서는 구글 OAuth 정책에 동의함을 눌러줍니다.

모든 탭의 내용의 작성이 완료되면 만들기를 눌러줍니다.

다음으로 OAuth 클라이언트를 만들어야 합니다.

어플케이션 유형은 웹 어플리케이션을 선택합니다.

승인된 JavaScript 원본의 URI의 경우, 저희는 Spring Boot 백엔드 방식을 사용할 것이므로 사용하지 않습니다.
(Next.js 프론트로 직접 OAuth를 붙일 때만 필요함)

승인된 리디렉션 URI는 백엔드 주소를 입력해주어야 합니다.

Spring Security OAuth2 기본 값은 아래와 같은 형태입니다.
http://<백엔드주소>/login/oauth2/code/{provider}

여기까지 완성하였으면 Google Cloud Console에서 진행할 설정은 모두 완료된 것입니다.

이때 클라이언트 ID와 Password는 Spring boot에서 설정 시 필요하므로 별도로 저장해두시기 바랍니다.

2. Spring 프로젝트 생성 및 설정

다음으로 스프링 프로젝트를 생성하고 적용해 보겠습니다.

https://start.spring.io/

start.spring.io에서 스프링 프로젝트 생성을 진행합니다.

// src/resources/application.yml

spring:
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: [GCC에서_제공받은_ID]
            client-secret: [GCC에서_제공받은 _PW]
            scope:
              - email
              - profile
        provider:
          google:
            issuer-uri: https://accounts.google.com

  datasource:
    url: jdbc:mysql://localhost:3306/내DB명?serverTimezone=Asia/Seoul&characterEncoding=UTF-8
    username: [USERNAME]
    password: [PASSWORD]
    driver-class-name: com.mysql.cj.jdbc.Driver

  jpa:
    hibernate:
      ddl-auto: create   # 개발 중: create / update, 운영: validate 추천
    show-sql: true       # 콘솔에 SQL 출력
    properties:
      hibernate:
        format_sql: true
    database-platform: org.hibernate.dialect.MySQLDialect

다음으로 프로젝트 설정을 진행합니다.

application.yml 파일을 생성하고 spring-security-oauth2에 설정을 작성합니다.

추가적으로 database도 연결을 진행해주시고, 저는 테스트를 위해 간단히 jpa까지 설정하였습니다.

// build.gradle

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-security'
	implementation 'org.springframework.boot:spring-boot-starter-web'
	compileOnly 'org.projectlombok:lombok'
	runtimeOnly 'com.mysql:mysql-connector-j'
	annotationProcessor 'org.projectlombok:lombok'
	testImplementation 'org.springframework.boot:spring-boot-starter-test'
	testImplementation 'org.springframework.security:spring-security-test'
	testRuntimeOnly 'org.junit.platform:junit-platform-launcher'

	implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'
	implementation 'com.fasterxml.jackson.core:jackson-databind'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
}

다음으로 build.gradle에서 의존성을 추가해줍니다.

앞서 웹에서 프로젝트 생성 시 선택하지 않은 기능이 있다면 dependencies안에 추가하여 줍니다.

3. Spring Security & OAuth 로그인 기본 동작 만들기

com/tistory/angelplayer/oauth
    ├── OauthApplication.java                 # 스프링 부트 메인 클래스 (앱 실행 시작점)
    │
    ├── auth
    │    └── controller
    │         └── AuthController.java         # 로그인한 사용자 정보 반환 (/api/auth/me)
    │
    ├── config
    │    └── SecurityConfig.java              # OAuth2 + Spring Security 설정
    │                                          # (구글로그인, 세션 설정, CORS, 권한 관리 등)
    │
    └── guestbook
         ├── controller
         │    └── GuestbookController.java    # 방명록 API 진입점 (등록/조회 REST 컨트롤러)
         │
         ├── dto
         │    └── GuestbookRequestDto.java    # 방명록 등록 요청 DTO
         │
         ├── entity
         │    └── GuestbookEntry.java         # 방명록 엔티티 (DB 테이블 매핑)
         │
         ├── repository
         │    └── GuestbookEntryRepository.java  # 방명록 CRUD용 JPA Repository
         │
         └── service
              └── GuestbookService.java       # 방명록 비즈니스 로직 (저장/조회 처리)

백엔드 프로젝트의 전체 구조는 위와 같습니다.

package com.tistory.angelplayer.oauth.auth.controller;

import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

@RestController
@RequestMapping("/api/auth")
public class AuthController {

    @GetMapping("/me")
    public Map<String, Object> me(@AuthenticationPrincipal OAuth2User principal) {
        if (principal == null) {
            return Map.of("authenticated", false);
        }
        Map<String, Object> attrs = principal.getAttributes();
        return Map.of(
                "authenticated", true,
                "email", attrs.get("email"),
                "name", attrs.get("name"),
                "picture", attrs.get("picture")
        );
    }
}

1) AuthController.java

현재 요청을 보낸 브라우저/클라이언트가 로그인된 상태인지 확인

로그인 상태라면 OAuth2User 의 getAttributes() 를 통해 email, name, picture 등 구글 사용자 정보를 가져와서 반환

로그인 안돼 있으면 { authenticated: false } 응답

프론트엔드(Next.js)가 초기 렌더링 시 “로그인 여부 확인” 용도로 호출하는 API

package com.tistory.angelplayer.oauth.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.CorsConfigurationSource;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;

import java.util.List;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
                .csrf(csrf -> csrf.disable())
                .cors(Customizer.withDefaults())
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/", "/error").permitAll()
                        .requestMatchers("/api/auth/**").permitAll()
                        .requestMatchers("/api/guestbook").permitAll()      // GET 허용
                        .requestMatchers("/api/guestbook/**").authenticated() // POST 등은 로그인 필요
                        .anyRequest().authenticated()
                )
                .oauth2Login(oauth -> oauth
                        .defaultSuccessUrl("http://localhost:3000", true)
                )
                .logout(logout -> logout
                        .logoutUrl("/logout")
                        .logoutSuccessUrl("http://localhost:3000")
                );

        return http.build();
    }

    // CORS 설정 (Next.js 3000 포트 허용)
    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowedOriginPatterns(List.of("http://localhost:3000"));
        config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
        config.setAllowedHeaders(List.of("*"));
        config.setAllowCredentials(true);

        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", config);
        return source;
    }
}

2) SecurityConfig.java (config)
스프링 시큐리티 전체 설정을 담당.

어떤 URL이 인증 없이 접근 가능한지 (permitAll),
어떤 URL이 로그인 필요한지 (authenticated) 정의.

OAuth2 로그인 설정

/oauth2/authorization/google → 구글 로그인 페이지로 연결

로그인 성공 시 defaultSuccessUrl("http://localhost:3000") 로 리다이렉트

CORS 설정 : Next.js(3000 포트)에서 오는 요청을 허용 (credentials 허용 등)

package com.tistory.angelplayer.oauth.guestbook.entity;

import jakarta.persistence.*;
import lombok.*;
import java.time.LocalDateTime;

@Entity
@Table(name = "guestbook_entry")
@Getter @Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class GuestbookEntry {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String userEmail;
    private String userName;

    @Column(length = 1000)
    private String message;

    private LocalDateTime createdAt;
}

3) GuestbookEntry.java (guestbook.entity)

JPA 엔티티(= DB 테이블과 매핑되는 클래스)

package com.tistory.angelplayer.oauth.guestbook.repository;


import com.tistory.angelplayer.oauth.guestbook.entity.GuestbookEntry;
import org.springframework.data.jpa.repository.JpaRepository;

import java.util.List;

public interface GuestbookEntryRepository extends JpaRepository<GuestbookEntry, Long> {

    List<GuestbookEntry> findAllByOrderByCreatedAtDesc();
}

4) GuestbookEntryRepository.java
save(), findById(), findAll() 등 기본 CRUD 메서드를 자동 제공.

커스텀 메서드 findAllByOrderByCreatedAtDesc() 를 통해 방명록 목록을 createdAt 기준 내림차순으로 정렬해서 조회.

실제로 SQL을 직접 작성하지 않아도 GuestbookEntryRepository 를 통해 DB에 접근할 수 있게 해주는 레이어.

package com.tistory.angelplayer.oauth.guestbook.dto;

import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
public class GuestbookRequestDto {
    private String message;
}

5) GuestbookRequestDto.java
클라이언트에서 방명록 글 작성 요청 시 받는 데이터 형태.

Controller 에서 @RequestBody 로 받아서 검증/전달용 객체로 사용.

엔티티(GuestbookEntry)와 분리해서, “요청으로 들어오는 데이터”와 “DB 저장 구조”를 깔끔하게 나누는 역할.

package com.tistory.angelplayer.oauth.guestbook.service;

import com.tistory.angelplayer.oauth.guestbook.entity.GuestbookEntry;
import com.tistory.angelplayer.oauth.guestbook.dto.GuestbookRequestDto;
import com.tistory.angelplayer.oauth.guestbook.repository.GuestbookEntryRepository;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;

import java.time.LocalDateTime;
import java.util.List;

@Service
@RequiredArgsConstructor
public class GuestbookService {

    private final GuestbookEntryRepository repository;

    public List<GuestbookEntry> getAllEntries() {
        return repository.findAllByOrderByCreatedAtDesc();
    }

    public GuestbookEntry createEntry(String userEmail, String userName, GuestbookRequestDto dto) {
        GuestbookEntry entry = GuestbookEntry.builder()
                .userEmail(userEmail)
                .userName(userName)
                .message(dto.getMessage())
                .createdAt(LocalDateTime.now())
                .build();

        return repository.save(entry);
    }
}

6) GuestbookService.java (guestbook.service)
비즈니스 로직 담당.

getAllEntries() : GuestbookEntryRepository를 사용해 방명록 전체 목록 조회.

createEntry(String userEmail, String userName, GuestbookRequestDto dto) : DTO와 사용자 정보를 조합해 GuestbookEntry 생성

Repository로 저장 후 결과 반환

Controller는 “HTTP 요청/응답 처리”에 집중하고, Service는 “로직/규칙/처리 순서”에 집중하게 해주는 구조.

package com.tistory.angelplayer.oauth.guestbook.controller;


import com.tistory.angelplayer.oauth.guestbook.entity.GuestbookEntry;
import com.tistory.angelplayer.oauth.guestbook.dto.GuestbookRequestDto;
import com.tistory.angelplayer.oauth.guestbook.service.GuestbookService;
import lombok.RequiredArgsConstructor;
import org.springframework.http.HttpStatus;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.server.ResponseStatusException;

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

@RestController
@RequestMapping("/api/guestbook")
@RequiredArgsConstructor
public class GuestbookController {

    private final GuestbookService guestbookService;

    // 방명록 목록 조회 (누구나 볼 수 있음)
    @GetMapping
    public List<GuestbookEntry> list() {
        return guestbookService.getAllEntries();
    }

    // 방명록 글 작성 (로그인한 사용자만)
    @PostMapping
    public GuestbookEntry add(
            @RequestBody GuestbookRequestDto dto,
            @AuthenticationPrincipal OAuth2User principal
    ) {
        if (principal == null) {
            throw new ResponseStatusException(HttpStatus.UNAUTHORIZED, "로그인이 필요합니다.");
        }

        if (dto.getMessage() == null || dto.getMessage().trim().isEmpty()) {
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "메시지를 입력하세요.");
        }

        Map<String, Object> attrs = principal.getAttributes();
        String email = (String) attrs.get("email");
        String name = (String) attrs.get("name");

        return guestbookService.createEntry(email, name, dto);
    }
}

7) GuestbookController.java

GET /api/guestbook
누구나 방명록 목록을 조회할 수 있게 함
guestbookService.getAllEntries() 호출 후 결과 반환

POST /api/guestbook
@RequestBody GuestbookRequestDto 로 메시지를 받고
@AuthenticationPrincipal OAuth2User 로 로그인한 사용자 정보 가져온 뒤
정상이라면 guestbookService.createEntry(...) 호출해 새 글 저장 후 반환

즉, HTTP → DTO/Principal 파싱 → Service 호출 → 응답 을 담당하는 레이어.

3. Next js 설정 및 소스코드

1) 프로젝트 생성

$ npx create-next-app@latest fe

$ cd fe

$ npm run dev

next.js 프로젝트 생성을 진행합니다.

생성 이후 npm run dev 명령 실행 시 http://localhost:3000 페이지가 정상적으로 출력되면 프로젝트가 정상적으로 생성 된 것입니다.

2) 백엔드 주소 환경변수 설정

// fe/.env.local
NEXT_PUBLIC_API_BASE_URL=http://localhost:8080

루트 위치에 .env.local 파일을 생성하고 백엔드 주소와 포트를 작성해줍니다.

3) src/app/page.tsx

"use client";

import { useEffect, useState, FormEvent } from "react";

const API_BASE = process.env.NEXT_PUBLIC_API_BASE_URL!;

// 백엔드 /api/auth/me 응답 타입
type MeResponse = {
  authenticated: boolean;
  email?: string;
  name?: string;
  picture?: string;
};

// 백엔드 /api/guestbook 응답 타입
type GuestbookEntry = {
  id: number;
  userEmail: string;
  userName: string;
  message: string;
  createdAt: string;
};

export default function HomePage() {
  const [me, setMe] = useState<MeResponse | null>(null);
  const [entries, setEntries] = useState<GuestbookEntry[]>([]);
  const [message, setMessage] = useState("");
  const [loading, setLoading] = useState(false);

  // 1) 로그인 정보 가져오기
  const fetchMe = async () => {
    try {
      const res = await fetch(`${API_BASE}/api/auth/me`, {
        credentials: "include", // ✅ 세션 쿠키(JSESSIONID) 포함
      });
      const data: MeResponse = await res.json();
      setMe(data);
    } catch (e) {
      console.error(e);
      setMe({ authenticated: false });
    }
  };

  // 2) 방명록 목록 가져오기
  const fetchEntries = async () => {
    try {
      const res = await fetch(`${API_BASE}/api/guestbook`, {
        credentials: "include",
      });
      if (!res.ok) return;
      const data: GuestbookEntry[] = await res.json();
      setEntries(data);
    } catch (e) {
      console.error(e);
    }
  };

  // 첫 로딩 시 로그인 정보 확인
  useEffect(() => {
    fetchMe();
  }, []);

  // 로그인 상태가 되면 방명록 목록 로딩
  useEffect(() => {
    if (me?.authenticated) {
      fetchEntries();
    }
  }, [me]);

  // Google 로그인 버튼 클릭 시
  const handleLogin = () => {
    window.location.href = `${API_BASE}/oauth2/authorization/google`;
  };

  // 로그아웃 (선택사항)
  const handleLogout = () => {
    window.location.href = `${API_BASE}/logout`;
  };

  // 방명록 등록
  const handleSubmit = async (e: FormEvent) => {
    e.preventDefault();
    if (!message.trim()) return;
    setLoading(true);
    try {
      const res = await fetch(`${API_BASE}/api/guestbook`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        credentials: "include",
        body: JSON.stringify({ message }),
      });

      if (!res.ok) {
        alert("등록에 실패했습니다. 로그인 상태를 확인해주세요.");
        return;
      }

      setMessage("");
      await fetchEntries();
    } catch (err) {
      console.error(err);
      alert("에러가 발생했습니다.");
    } finally {
      setLoading(false);
    }
  };

  // 아직 /api/auth/me 응답 전
  if (me === null) {
    return (
      <main style={{ padding: 24 }}>
        <h1>Google OAuth 방명록</h1>
        <p>로그인 상태 확인 중...</p>
      </main>
    );
  }

  // 로그인 안 된 경우
  if (!me.authenticated) {
    return (
      <main style={{ padding: 24 }}>
        <h1>Google OAuth 방명록</h1>
        <p>방명록을 남기려면 Google 계정으로 로그인 해주세요.</p>
        <button onClick={handleLogin}>Google로 로그인</button>
      </main>
    );
  }

  // 로그인 된 경우
  return (
    <main style={{ padding: 24, maxWidth: 600 }}>
      <h1>Google OAuth 방명록</h1>

      <section style={{ marginBottom: 24 }}>
        <p>
          안녕하세요, <b>{me.name}</b> ({me.email})
        </p>
        <button onClick={handleLogout}>로그아웃</button>
      </section>

      <section style={{ marginBottom: 24 }}>
        <form onSubmit={handleSubmit}>
          <textarea
            style={{ width: "100%", minHeight: 80 }}
            value={message}
            onChange={(e) => setMessage(e.target.value)}
            placeholder="방명록을 남겨보세요"
          />
          <div style={{ marginTop: 8 }}>
            <button type="submit" disabled={loading}>
              {loading ? "등록 중..." : "등록"}
            </button>
          </div>
        </form>
      </section>

      <section>
        <h2>방명록 목록</h2>
        {entries.length === 0 ? (
          <p>아직 방명록이 없습니다.</p>
        ) : (
          <ul style={{ listStyle: "none", padding: 0 }}>
            {entries.map((e) => (
              <li
                key={e.id}
                style={{
                  border: "1px solid #ddd",
                  padding: 12,
                  marginBottom: 8,
                  borderRadius: 4,
                }}
              >
                <div>
                  <b>{e.userName}</b> ({e.userEmail})
                </div>
                <div style={{ margin: "4px 0" }}>{e.message}</div>
                <div style={{ fontSize: 12, color: "#666" }}>
                  {new Date(e.createdAt).toLocaleString()}
                </div>
              </li>
            ))}
          </ul>
        )}
      </section>
    </main>
  );
}

핵심 기능은 Goolge OAuth이므로 프론트 단은 간단히 구현하였습니다.

4. 요약 정리

1. 지금까지 구현한 전체 기능 요약
Google OAuth 로그인 구현
- 프론트에서 “Google 로그인” 클릭
- Google OAuth 인증 서버로 이동
- 인증 후 Google이 code를 우리 서버로 전달
- 우리 서버(Spring)가 Google 서버에서 사용자 프로필 정보 가져옴
- 사용자 정보를 세션에 저장
- 로그인 성공 후 프론트로 redirect
- 프론트는 세션 기반으로 로그인 유지

세션(Session) 기반 사용자 인증
- 구글 로그인 성공 → 서버가 세션 생성
- 세션 ID를 브라우저 쿠키(JSESSIONID)에 저장
- 이후 요청 시 쿠키에 담긴 세션 ID를 사용해 로그인 여부 확인

2. 코드의 동작 흐름
① 프론트 → Google 인증 요청
사용자가 Google 로그인 버튼 클릭
⬇
프론트에서 다음 주소로 이동:
GET http://localhost:8080/oauth2/authorization/google

② Google → 서버로 authorization code 전달
구글이 로그인 성공
⬇
Redirect:
GET http://localhost:8080/login/oauth2/code/google?code=xxxx

③ 백엔드에서 Google API 호출 & 사용자 정보 획득
Spring Security가 자동으로:
code → access_token 교환
access_token → 사용자 정보 요청

얻은 정보:
email
name
profile_image
google_id

④ 세션(Session)에 사용자 정보 저장
Spring Security의 기본 동작
→ 서버 세션에 Authentication 저장
⬇
JSESSIONID 쿠키 생성 후 프론트로 전달

⑤ 프론트에서 방명록 작성 요청
프론트가 방명록 API 호출:

POST /api/guestbook
content: "안녕하세요!"

브라우저는 자동으로 쿠키(JSESSIONID)를 함께 보냄
서버는 세션에서 사용자 정보 조회
로그인된 사용자로 판단
방명록 저장

3. JSESSIONID 검증 방법

① 동작 방식
0) JSESSIONID 전달
로그인 성공 시 서버가 JSESSIONID를 내려줌
브라우저는 쿠키에 JSESSIONID를 저장하고 있음

1) 브라우저 Request
이후 브라우저는 요청에 JSESSIONID 쿠키를 함께 실어 서버로 전달

2) 서버 검증
소스코드에서 직접 세션을 검증하는 단계는 없음

@AuthenticationPrincipal를 통해서
톰캣 + 스프링 시큐리티가 필터 레벨에서 자동으로 검증

- 요청이 들어오면, 톰캣이 쿠키에서 JSESSIONID 값을 읽음
- 이 ID로 톰캣 내부 세션 저장소(메모리)에서 HttpSession을 찾음
- 세션이 있고, 만료 시간이 지나지 않았다면 HttpServletRequest에 HttpSession을 붙여서 스프링에게 넘김
- 스프링 시큐리티는 그 세션에 저장된 SecurityContext(로그인 정보)를 꺼냄
- 그 안에 OAuth2User 가 있으면 “로그인 된 사용자”라고 판단

② JSESSIONID 유효기간 / 만료 관리

1) 서버 만료
server.servlet.session.timeout을 통해서
만료시간을 설정할 수 있으며, 없으면 톰캣 기본값(보통 30분 비활성 시 만료) 적용

2) 클라이언트 만료 (브라우저 쿠키 라이프사이클)
Max-Age나 Expires를 사용해 관리
따로 지정하지 않으면 세션 쿠키로 취급 (브라우저를 닫을 떄 쿠키 삭제)

3) 로그아웃 요청
Spring Security가 HttpSession.invalidate() 호출
→ 서버 쪽 세션 삭제
→ JSESSIONID 쿠키도 만료시키는 응답 헤더를 내려줌

[TIL] 20250907 개발일지 (웹 동적 크기 변환, clamp())

AngelPlayer — Sun, 7 Sep 2025 22:09:56 +0900

웹에서 요소들이 동적으로 크기가 바뀌도록 만들기 위한 공부

clamp()
https://developer.mozilla.org/en-US/docs/Web/CSS/clamp

웹 화면의 모든 요소가 동적으로 크기가 바뀌도록 하고 싶었는데 clamp를 사용하면 편리하게 구현 가능할 것 같다.

## 사용법
clamp(최솟값, 선호값, 최댓값)

## 예시
width: clamp(0%, 300px, 100%);

aspect-ratio
종횡비
요소를 비율대로 조정

[AWS] EC2 램 메모리 증설(SWAP)하기 (Feat. 프리티어)

AngelPlayer — Mon, 31 Mar 2025 08:59:53 +0900

작은 용량의 RAM을 사용하면서 여러 기능을 사용하다보면 메모리 용량이 부족한 경우가 종종 발생합니다.

메모리 용량을 늘리기 위해서는 리눅스 커널에서 제공하는 스왑(SWAP)을 사용하면 됩니다.

스왑은 RAM이 부족할 때, 디스크의 일부를 임시 메모리처럼 사용하는 공간입니다.

스왑 공간 만들기

0. 스왑 공간 확인하기

$ free -h

스왑을 위해서는 스왑 공간을 할당해야 합니다.

현재 사용 중인 환경에 스왑 공간이 존재하는지 여부는 free -h 명령을 통해서 확인할 수 있습니다.

1. 스왑 파일 생성

$ sudo dd if=/dev/zero of=/swapfile bs=128M count=16

먼저 dd 명령을 통해 스왑 파일을 생성해야 합니다.

bs는 블록 크기이고, count는 블록 수 입니다.

일반적으로 스왑 공간은 현재 메모리의 2배를 권장하는 편이며, 저는 1GB RAM을 사용 중이기 때문에, 2GB의 스왑 공간을 할당할 것입니다.

스왑 공간은 bs * count로 계산할 수 있으며, 보통 bs를 128MB로 고정하는 편이므로 count는 16이 도출되었습니다. (128 * 16 = 2048)

2. 스왑 파일의 읽기/쓰기 권한 부여

$ sudo chmod 600 /swapfile

$ ls -l

chmod 명령을 통해 스왑파일의 읽기 및 쓰기 권한을 업데이트합니다.

권한이 업데이트 된 것인 ls -l을 통해서 확인하실 수 있습니다.

3. 스왑 영역 설정

$ sudo mkswap /swapfile

$ sudo swapon /swapfile

$ sudo swapon -s

mkswap, swapon을 통해 스왑 영역을 설정합니다.

swapon -s을 통해서 스왑 영역이 적용된 것을 확인할 수 있습니다.

4. 재부팅시 자동으로 스왑 설정 유지하기

$ sudo vi /etc/fstab

# 아래 라인을 작성
/swapfile swap swap defaults 0 0

3번에 swapon /swapfile으로 스왑을 활성화했지만, 서버를 재부팅하면 사라지게 됩니다.

따라서 서버를 재기동하더라도 다시 스왑 공간을 사용하고 싶다면 파일 시스템 정보를 수정해야 합니다.

/etc/fstab에는 다른 설정 라인이 있기 때문에 가장 마지막 줄에 /swapfile 을 작성해주시면 됩니다.

리눅스는 일반적으로 vi를 통해서 파일을 수정하는데, nano 등 다른 에디터를 사용하셔도 무방합니다.

저는 vi를 사용할 것이고, 아래에 간단히 순서대로 작성하는 방법을 작성해 놓겠습니다.

(#의 뒤는 설명이므로 무시하셔도 됩니다.)

0) sudo vi /etc/fstab
1) Shift + G # 마지막 줄로 이동
2) o # 수정 모드로 변경
3) /swapfile swap swap defaults 0 0 # 작성
4) ESC
5) :wq # 저장 후 나가기

5. 확인

free -h로 다시 확인해보시면 Swap 영역이 2GB로 잘 적용된 모습을 확인하실 수 있습니다.

[AWS] EC2 고정 IP(탄력적 IP) 설정하기

AngelPlayer — Tue, 25 Mar 2025 08:19:03 +0900

https://angelplayer.tistory.com/595

지난 시간에는 AWS EC2를 이용하여 클라우드 서버를 구축하였습니다.

지금 서버에 접속하거나 서비스를 구축 후 배포해도 사용하는 데 문제가 없지만, 동적 IP 상태이므로 서버를 재기동하면 IP가 변경될 수 있습니다.

따라서 고정 IP를 사용하도록 만들어야 하는데, AWS에서는 탄력적 IP(Elastic IP)를 통해 고정적인 IP를 사용할 수 있습니다.

EC2 대시보드로 접근하여, '네트워크 및 보안 - 탄력적 IP'로 이동합니다.

화면 우측 상단의 '탄력적 IP 주소 할당'을 클릭합니다.

탄력적 IP 주소의 경우 네트워크 경계 그룹을 EC2 리전과 맞춰주기만 하면 되는데, 기본적으로 계정에 설정된 리전을 따라서 적용됩니다.

우측 하단의 할당을 눌러주세요.

탄력적 IP가 잘 생성된 것을 볼 수 있습니다.

저는 헷갈리지 않도록 우선 Name을 수정했습니다.

Name 란에 마우스를 가져가면 수정 버튼이 생기며 클릭 시 Name 수정이 가능합니다.

다음으로 우측 상단의 '작업 - 탄력적 IP 주소 연결'을 눌러줍니다.

탄력적 IP 주소에서 리소스 유형을 인스턴스로 선택 후 기존에 만들어진 인스턴스를 선택합니다.

인스턴스 선택 후 프라이빗 IP도 설정해야 하는데, 인스턴스를 정상적으로 선택했다면 해당 인스턴스의 IP 정보를 자동으로 받아올 수 있습니다.

인스턴스, 프라이빗 IP를 정상적으로 선택했다면 연결을 눌러주시면 됩니다.

정상적으로 적용되었다면 인스턴스 탭에서 연결한 인스턴스를 선택했을 때 탄력적 IP 주소로 방금 만든 angelplayer-eip가 잘 적용된 것을 볼 수 있습니다.

다시 PuTTY에서 로그인을 진행해 봅시다.

이번에는 Host Name에 탄력적 IP의 주소를 넣어주시면 됩니다.

탄력적 IP 주소는 앞에 인스턴스 탭에서 인스턴스 선택 시 나오는 탄력적 주소란에 적혀 있습니다.

※ 탄력적 IP는 EC2 인스턴스에 연결되어 있을 경우 요금이 부과되지 않지만, 연결되지 않은 상태로 할당만 되어 있을 경우에는 비용이 발생할 수 있습니다.

[AWS] EC2 프리티어 환경 구축하기 (Feat. Ubuntu, PuTTY)

AngelPlayer — Mon, 24 Mar 2025 08:31:25 +0900

AWS에서 제공하는 기능들을 이용하여 클라우드 컴퓨팅 환경을 만들어 보겠습니다.

AWS는 EC2, Lightsail 등을 이용하여 클라우드 컴퓨팅 환경을 구축하며, AWS는 회원가입 후 EC2를 1년간 무료로 사용할 수 있는 프리티어 오퍼를 제공합니다.

AWS (Amazon Web Services)란?
AWS(Amazon Web Services)는 아마존(Amazon)이 제공하는 클라우드 컴퓨팅 플랫폼으로, 인터넷을 통해 서버, 스토리지, 데이터베이스, 네트워크, AI 등의 IT 인프라를 제공하는 서비스입니다.
즉, 물리적인 서버 없이도 AWS를 통해 원하는 만큼 컴퓨팅 리소스를 빌려 사용할 수 있습니다.

EC2 (Elastic Compute Cloud)란?
EC2는 AWS에서 제공하는 가상 서버 서비스입니다.
일반적으로 우리가 알고 있는 물리적 서버를 클라우드 환경에서 가상화된 형태로 제공하는 서비스라고 보면 됩니다.

무료 클라우드 컴퓨팅 서비스 - AWS 프리 티어

이러한 프리 티어 혜택은 AWS 신규 고객에게만 제공되며 AWS 가입일로부터 12개월 동안 유효합니다. 12개월의 무료 사용 기간이 만료되거나 애플리케이션 사용량이 프리 티어 범위를 초과할 경우

aws.amazon.com

우선 AWS에 접속하여 회원가입을 진행해줍니다.

회원가입 후 로그인을 하면 위와 같은 화면이 뜨게 됩니다.

1. EC2 인스턴스 생성하기

1-1. 리전 설정

가장 먼저 AWS의 리전(Region)을 변경해줍니다.

리전이 가까울수록 지연 시간, 안정적인 연결 등에서 유리한 점이 있기 때문에 최대한 가까운 지역을 설정하는 것이 좋습니다.

리전은 AWS 화면에서 우측 상단 설정 옆에서 변경할 수 있습니다.

저는 서울을 선택하였습니다.

1-2. EC2 인스턴스 생성

메인화면 좌측 상단 검색창에 EC2를 작성해줍니다.

검색 결과에서 서비스 - EC2를 선택합니다.

EC2의 대시보드 화면에서 인스턴스 시작을 눌러줍니다.

이름 및 태그에 인스턴스의 이름을 지정해줍니다.

어플리케이션 및 OS 이미지(AMI)를 지정합니다.

저는 우분투 24.04 버전을 선택하였으며, 인스턴스 생성 시점에 LTS(Long Term Support)가 붙어 있는 버전을 사용하시면 됩니다.

인스턴스 유형은 프리티어를 지원하는 t2.micro를 선택합니다.

키 페어(로그인)에서 새 키 페어 생성을 눌러줍니다.

키 페어 이름을 작성해주시고,

키 페어 유형은 RSA,

프라이빗 키 파일 형식은 .pem을 선택하신 후 키 페어 생성을 눌러주세요.

키 페어 생성시 .pem 확장자인 파일이 다운로드 됩니다.

방금 생성한 키는 앞으로 서버에 원격 접속하기 위해서 꼭 필요합니다.

저는 C드라이브 - key 위치에 저장해두었습니다.

네트워크 설정에서는 당장 따로 설정할 내용이 없습니다.

프리티어의 경우 스토리지를 월 최대 30GB까지 사용가능합니다.

만약 여러 인스턴스를 생성한다면 30GB를 적절히 나눠서 사용하면 되지만, 저희는 하나의 인스턴스를 생성할 것이기 때문에 최대 크기인 30GB를 지정했습니다.

스토리지 구성까지 끝났다면 화면 우측의 요약화면에 있는 인스턴스 시작 버튼을 눌러주세요.

잠시 기다리시면 인스턴스 생성에 성공했다는 화면을 볼 수 있습니다.

2. 보안 그룹 설정

2-1. 보안 그룹 생성

다음으로 보안 그룹 규칙을 추가해줍니다.

EC2 대시보드로 돌아가 왼쪽 탭에서 네트워크 및 보안 - 보안 그룹을 선택합니다.

그리고 보안 그룹 생성 버튼을 클릭해줍니다.

먼저 보안 그룹 이름을 설정해줍니다.

보안 그룹의 경우 설명도 필수 항목인데, 보안 그룹 이름과 동일하게 작성하였습니다.

저희는 putty 등으로 접속하기 위한 SSH 포트, 그리고 HTTP, HTTPS 포트를 열어두어야 합니다.

인바운드 규칙에서 규칙 추가 버튼을 눌러서 각각의 유형을 SSH, HTTP, HTTPS를 선택해줍니다.

포트 번호, 프로토콜은 유형에 맞춰서 자동으로 선택됩니다.

언제 어디서든 접근할 수 있도록 소스는 0.0.0.0/0으로 지정해야 합니다.

소스에서 Anywhere-IPv4를 선택하시면 자동으로 완성됩니다.

모든 설정이 완료되면 화면 우측 최하단에 보안 그룹 생성 버튼을 눌러줍니다.

※ SSH(포트 22)는 보안상 내 IP로만 접근을 허용하는 것이 안전합니다.
개발/연습용이라면 0.0.0.0/0으로 설정해도 되지만, 실 서비스 환경에서는 제한을 권장합니다.

보안 그룹 생성이 정상적으로 완료되었습니다.

2-2. 보안 그룹 적용

다시 EC2 대시보드로 돌아가, 인스턴스 - 인스턴스로 이동합니다.

앞서 만들었던 인스턴스를 우클릭한 후, 보안 - 보안 그룹 변경을 눌러줍니다.

연결된 보안 그룹에 방금 생성했던 보안 그룹을 추가해야 합니다.

보안 그룹 추가 후 저장 버튼을 눌러주세요.

3. PuTTY로 서버 접속하기

EC2 - 인스턴스 - 인스턴스로 이동하여 앞서 만들었던 인스턴스트를 선택하고 연결 버튼을 눌러줍니다.

연결 방법은 여러가지가 있는데, 저는 SSH 클라이언트 방식을 사용하겠습니다.

추가적으로 접근을 빠르게 하기 위해서 설정 등을 쉽게 저장할 수 있는 PuTTY를 사용하도록 하겠습니다.

PuTTY를 통해서 EC2를 접속하는 자세한 방법은 모 블로거의 글에 자세히 나와있으니 아래 링크를 참고하시기 바랍니다.

위 화면에서 저희가 필요한 것은 마지막에 위치한 예 : ssh -i ~~~~~~~~ 에서 ubuntu@ec2 ~~ compute.anazonaws.com 입니다.

해당 부분을 복사해두시기 바랍니다.

https://angelplayer.tistory.com/476

[PuTTY] EC2 ssh pk(ppk, pem)으로 접속하기

https://www.putty.org/ Download PuTTY - a free SSH and telnet client for Windows Is Bitvise affiliated with PuTTY? Bitvise is not affiliated with PuTTY. We develop our SSH Server for Windows, which is compatible with PuTTY. Many PuTTY users are therefore o

angelplayer.tistory.com

※ 위 블로그 내용을 요약하면 아래와 같습니다.

PuTTY로 접속하려면 .pem 키를 .ppk로 변환해야 합니다.
1. PuTTYgen 실행 → Load → .pem 파일 선택
2. "Save private key" 클릭 → .ppk 저장
3. PuTTY 실행 후, SSH → Auth → Private Key에 .ppk 경로 지정
4. Session 탭에서 Host Name에 ubuntu@퍼블릭IP 입력
5. Save 후 Open 클릭 → 접속

위 링크를 참조하여, ppk 파일 생성, 경로 설정이 끝났으면 PuTTY 메인 화면으로 돌아갑니다.

이전에 복사해둔 ssh -i ~~~~~~~~ 부분에서 ubuntu@ec2 ~~ compute.anazonaws.com를 Host Name(or IP address)에 붙여 넣어줍니다.

이렇게 지정한 설정은 앞으로 자주 들어갈 확률이 높으므로 Saved Sessions에서 명칭을 지정하고 Save를 해두시는 것을 추천드립니다.

설정이 완료되면 Open을 눌러줍니다.

성공적으로 PuTTY로 AWS EC2에 접속한 것을 확인할 수 있습니다.

다국어 기능 구현하기 (Feat. Next, App Router, TS, next-intl)

AngelPlayer — Sat, 28 Dec 2024 13:40:27 +0900

개발 환경

- Windows
- VSCode

- Next.js 15 (App Router)
- Typescript

- next-intl ^3.26.3

목표

다국어 (영어, 한국어)를 지원하는 웹 페이지 제작

다국어 및 i18n 소개

최근 Next.js에서 다국어 기능을 지원하는 서비스를 개발하고 있습니다.

https://developer.mozilla.org/ko/docs/Glossary/Internationalization

국제화 (internationalization, I18N) - MDN Web Docs 용어 사전: 웹 용어 정의 | MDN

국제화 (i18n ("internationalization" 부터 유래, 20자로 이루어진 단어))는 제품이나 서비스를 모든 대상 문화에 쉽게 적용할 수 있도록 하는 모범 사례입니다.

developer.mozilla.org

다국어를 지원하는 웹사이트는 국제화(Internationalization, i18n) 과정을 통해 여러 국가의 사람들이 쉽게 사용할 수 있도록 개발됩니다.

국제화(이하 i18n)는 단순히 언어를 번역하는 것뿐만 아니라, 지역별 날짜 및 시간 형식, 숫자 및 통화 단위, 측정 단위 등을 사용자의 환경에 맞게 출력하는 것을 목표로 합니다.

이를 통해 사용자는 자신의 지역이나 문화적 맥락에 맞는 경험을 제공받을 수 있습니다.

국제화를 지원하기 위해서는 사용자의 언어 정보를 라우팅에 반영하여야 합니다.

Next 환경에서 i18n을 지원하기 위한 대표적인 라우팅 방법으로는

- Prefix-based routing

- Domain-based routing

두 가지 방식이 있습니다.

Prefix-based routing는 URL 경로에 언어 정보를 접두어(Prefix)로 포함하는 방식입니다.

- 절대 경로 뒤에 /en, /ko와 같이 언어 정보를 엔드 포인트로 전달합니다.

- ex) angelplayer.tistory.com/en

Domain-based routing는 언어별로 서로 다른 서브도메인 또는 도메인을 사용하는 방식입니다.

- ex1) en.angelplayer.tistory.com (서브 도메인 사용 예제)

- ex2) angelplayer.kr (국가별 상위 도메인 사용 예제)

Next.js에서 다국어를 지원하는 라이브러리는 크게 next-i18next와 next-intl가 있습니다.

과거에는 next-i18next를 선호하는 사용자가 압도적으로 많았지만, 최근에는 next-intl을 채택하는 사례가 점점 증가하고 있다는 것을 패키지 다운로드 수 등으로 확인할 수 있습니다.

https://locize.com/blog/next-app-dir-i18n/

i18n with Next.js 13/14 and app directory / App Router (an i18next guide)

Looking for a way to internationalize your Next.js 13/14 project with the new app directory / App Router paradigm? Then this guide is for you!

locize.com

next-i18next의 경우 i18next 라이브러리를 기반으로 국제화를 지원하기 때문에 플러그인 및 부가 기능이 굉장히 많습니다.

한편 초기 구성 파일이나 의존 패키지가 많다는 점이 아쉬웠습니다.

특히 저는 Typescript 환경에서 개발을 원하였으나, 공식 블로그에서는 기본적으로 Javascript 환경의 개발 방법에 대해서 설명하고 있어, 전환이 쉽지 않았습니다.

https://next-intl.dev/

next-intl – Internationalization (i18n) for Next.js

Using next-intl too? Let us know!

next-intl.dev

next-intl의 경우 공식 document를 제공하며, typescript 환경에서의 예제 코드도 제공하고 있기 때문에 매우 편리하였습니다.

또한 설치 및 설정 단계에서 필요한 패키지가 next-intl 하나뿐이라는 점도 매력적으로 다가왔습니다.

따라서 저는 next-intl을 사용하여 i18n을 지원하는 서비스를 만들기로 결정하였습니다.

(앞으로 생성할 프로젝트는 상단에 링크로 제공된 next-intl의 Document에 기반으로 제작하였습니다.)

프로젝트 생성 및 환경 구축

npm install next-intl

먼저 next-intl 패키지를 설치해줍니다.

Root
├── public
│   └── messages
│      ├── en.json (1)
│      └── ko.json
├── next.config.mjs (2)
└── src
    ├── i18n
    │   ├── routing.ts (3)
    │   └── request.ts (5)
    ├── middleware.ts (4)
    └── app
        └── [locale]
            ├── layout.tsx (6)
            └── page.tsx (7)

저희가 구축할 프로젝트의 전체적인 파일 구조는 위와 같습니다.

(1) public/message/[locale].json

{
    "HomePage": {
        "title": "Hello world!",
        "about": "Go to the about page"
    },
    "AboutPage": {
        "name": "AngelPlayer"
    }
}

다국어 번역 데이터를 저장하는 파일입니다.

파일의 최상위 key는 각 페이지의 namespace로 사용합니다.

하위에 중접된 key-value는 각각 텍스트의 식별자와 번역 문자열을 저장하고 있습니다.

(2) next.config.mjs

import createNextIntlPlugin from 'next-intl/plugin';

const withNextIntl = createNextIntlPlugin();

/** @type {import('next').NextConfig} */
const nextConfig = {};

export default withNextIntl(nextConfig);

next-intl 플러그인을 사용하여 Next.js에서 국제화를 설정하기 위한 설정 파일입니다.

(3) src/i18n/routing.ts

import { defineRouting } from 'next-intl/routing';
import { createNavigation } from 'next-intl/navigation';

export const routing = defineRouting({
    // A list of all locales that are supported
    locales: ['en', 'ko'],

    // Used when no locale matches
    defaultLocale: 'en',
});

// Lightweight wrappers around Next.js' navigation APIs
// that will consider the routing configuration
export const { Link, redirect, usePathname, useRouter, getPathname } = createNavigation(routing);

routing.ts는 next-intl 라이브러리에서 제공하는 라우팅 및 네비게이션 기능을 설정하는 파일입니다.

이 파일에서는 지원 언어및 기본 언어를 정의하여 프로젝트에서 다국어를 지원할 수 있도록 설정합니다.

Link, redirect, usePathname, useRouter, getPathname과 같은 네비게이션 유틸리티를 생성하여, 프로젝트 내부에서 언어별 라우팅과 네비게이션을 쉽게 처리할 수 있도록 도와줍니다.

(4) src/middleware.ts

import createMiddleware from 'next-intl/middleware';
import { routing } from './i18n/routing';

export default createMiddleware(routing);

export const config = {
    // Match only internationalized pathnames
    matcher: ['/', '/(ko|en)/:path*'],
};

Next.js의 Middleware 기능을 활용하여 애플리케이션 요청(request)을 가로채고 처리하는 설정 파일입니다.

- createMiddleware
createMiddleware는 요청이 들어올 때 라우팅 및 언어 관련 처리를 수행하는 Middleware를 생성합니다.

routing.ts에서 정의한 라우팅 설정(locales, defaultLocale)을 사용하여 언어 정보를 처리하며, 사용자의 언어 설정에 따라 적절한 경로로 리다이렉트합니다.

- config
Next.js의 Middleware가 작동할 경로를 정의합니다.

matcher를 통해 Middleware가 적용될 URL 패턴을 지정합니다.

(5) src/i18n/request.ts

import { getRequestConfig } from 'next-intl/server';
import { routing } from './routing';
import path from 'path';
import fs from 'fs';

export default getRequestConfig(async ({ requestLocale }) => {
    // This typically corresponds to the `[locale]` segment
    let locale = await requestLocale;

    // Ensure that a valid locale is used
    if (!locale || !routing.locales.includes(locale as any)) {
        locale = routing.defaultLocale;
    }

    const messagesPath = path.join(process.cwd(), 'public', 'messages', `${locale}.json`);
    const messages = JSON.parse(fs.readFileSync(messagesPath, 'utf8'));

    return {
        locale,
        messages,
    };
});

request.ts는 요청에 따라 번역 데이터를 동적으로 로드하고 처리하는 설정 파일입니다.

URL을 통해 언어 정보를 받아오고, 유효성 검증을 수행합니다.

언어 정보를 기반으로 번역 데이터를 로드합니다.

번역 데이터를 페이지에서 사용할 수 있도록 파싱을 진행합니다.

(6) src/app/[locale]/layout.tsx

import type { Metadata } from 'next';
import './../globals.css';
import { NextIntlClientProvider } from 'next-intl';
import { getMessages } from 'next-intl/server';
import { notFound } from 'next/navigation';
import { routing } from '@/i18n/routing';

export const metadata: Metadata = {
    title: 'AngelPlayer`s i18n',
    description: 'Sample code that applies next-intl in Next.js (App Router) and TypeScript environments.',
};

export default async function LocaleLayout({
    children,
    params,
}: {
    children: React.ReactNode;
    params: { locale: string };
}) {
    // `params`에서 `locale`을 비동기로 가져옵니다.
    const { locale } = await params;

    // `locale`이 유효하지 않으면 404를 반환합니다.
    if (!routing.locales.includes(locale as any)) {
        notFound();
    }

    // 메시지를 비동기로 가져옵니다.
    const messages = await getMessages(locale as any);

    return (
        <html lang={locale}>
            <body>
                <NextIntlClientProvider messages={messages}>{children}</NextIntlClientProvider>
            </body>
        </html>
    );
}

next-intl 라이브러리를 활용하여 i18n를 처리할 수 있는 환경을 구축합니다.

getMessages()를 통해 요청된 언어에 맞는 번역 데이터를 비동기적으로 로드합니다.

NextIntlClientProvider 컨텍스트를 통해서 번역 데이터를 제공함으로써 하위 컴포넌트에서 번역 데이터를 읽고 출력할 수 있습니다.

(7) src/app/[locale]/page.tsx

import { useTranslations } from 'next-intl';
import { Link } from '@/i18n/routing';

export default function HomePage() {
    const t = useTranslations('HomePage');
    return (
        <div>
            <h1>{t('title')}</h1>
            <Link href='/about'>{t('about')}</Link>
        </div>
    );
}

(7-1) src/app/[locale]/about/page.tsx

import { useTranslations } from 'next-intl';
import React from 'react';

export default function AboutPage() {
    const t = useTranslations('AboutPage');
    return (
        <div>
            <h1>{t('name')}</h1>
        </div>
    );
}

page.tsx에서는 useTranslations()를 통해서 번역 데이터를 받아와 사용할 수 있습니다.

useTranslations('namespace')에서 namespace를 입력하면, 해당 네임스페이스의 번역 데이터를 가져옵니다.
가져온 번역 데이터는 t 변수에 저장합니다.

t('key')를 호출하면, 지정된 키에 해당하는 번역 문자열을 텍스트로 출력할 수 있습니다.

결과적으로 기대했던 다국어 기능을 구현할 수 있었습니다.