꾸준함의 가치

[Trouble Shooting] RefreshTokenService가 필요한 이유

mins0on — Thu, 28 May 2026 23:49:04 +0900

문제 상황

오늘은 JWT 로그인 유지 흐름을 확장하면서 RefreshTokenService를 만들었다.
처음에는 Refresh Token을 생성하는 것까지만 생각했는데, 막상 구현하려고 보니 한 가지가 더 필요했다.

Refresh Token을 발급만 하면 끝나는 것이 아니라, 서버가 이 토큰을 저장하고 조회하고 삭제할 수 있어야 했다.
그래서 RefreshTokenService를 따로 만들었다.

RefreshTokenService

RefreshTokenService는 Refresh Token을 Redis에 저장하고 관리하는 역할을 한다.
로그인에 성공하면 서버는 Refresh Token을 생성하고, 이 값을 Redis에 저장한다.

예를 들어 다음과 같은 형태이다.

key: refresh:{loginId}
value: refreshToken
TTL: 14일

TTL은 Redis에 저장된 데이터의 유효기간이다.
Refresh Token은 만료 시간과 Redis 저장 시간도 맞춰야 하기 때문에, TTL을 함께 설정한다.

이렇게 저장해두면 이후에 Access Token이 만료됐을 때,
재발급 요청에서 Redis에 저장된 Refresh Token과 요청으로 들어온 Refresh Token을 비교할 수 있다.

코드

@RequiredArgsConstructor
@Service
public class RefreshTokenService {

    private static final String REFRESH_TOKEN_PREFIX = "refresh:";

    private final StringRedisTemplate stringRedisTemplate;

    public void save(String loginId, String refreshToken, long refreshTokenValidityMs) {

        String key = createKey(loginId);

        stringRedisTemplate.opsForValue().set(
                key,
                refreshToken,
                Duration.ofMillis(refreshTokenValidityMs)
        );

    }

    public String get(String loginId) {
        String key = createKey(loginId);
        return stringRedisTemplate.opsForValue().get(key);
    }

    public void delete(String loginId) {
        stringRedisTemplate.delete(createKey(loginId));
    }

    private String createKey(String loginId) {
        return REFRESH_TOKEN_PREFIX + loginId;
    }

}

StringRedisTemplate

위 코드의 핵심은 StringRedisTemplate이다.

StringRedisTemplate은 Spring에서 Redis에 문자열 데이터를 저장하고 조회할 때 사용한다.
Redis는 key-value 형태로 데이터를 저장하는데, Refresh Token도 문자열이기 때문에 StringRedisTemplate을 사용한다.

StringRedisTemplate.opsForValue().set()

opsForValue()는 Redis의 String 타입 데이터를 다루겠다는 의미이다.

set()은 Redis에 값을 저장하는 메서드이고,
key에는 refresh:{loginId} 같은 저장 이름이
refreshToken은 실제 저장할 값이,
Duration.ofMillis(refreshTokenValidityMs)는 데이터가 Redis에서 유지될 시간이 저장된다

즉, 이 코드는 Refresh Token을 Redis에 저장하면서 만료 시간까지 함께 설정하는 코드이다.

정리

이번 작업을 통해 RefreshTokenService가 Redis에 Refresh Token을 저장하고 관리하는 역할이라는 것을 이해했다.
특히 StringRedisTemplate과 opsForValue().set()을 통해 key-value 형태로 값을 저장하고 TTL을 설정하는 흐름을 확인했다. Refresh Token 관리는 생성뿐만 아니라 저장, 조회, 삭제까지 함께 봐야 한다는 점을 배웠다.

[Trouble Shooting] Access Token과 Refresh Token은 왜 나눠서 보관할까?

mins0on — Wed, 27 May 2026 22:42:49 +0900

문제 상황

이번 프로젝트에서는, 로그인 유지 방식을 JWT 방식을 이용했다. JWT 방식으로 구현하던 와중 궁금한 점이 생겼다.

Access Token과 Refresh Token을 왜 굳이 나눠서 관리하지?
그냥 토큰 하나만 오래 쓰면 안 되나?

처음에는 토큰을 두 개로 나누는 구조가 오히려 복잡해 보였다.
하지만 각각의 역할을 나눠보니 이유가 조금씩 이해됐다.

Access Token의 역할

Access Token은 실제 API 요청에 사용하는 토큰이다.
예를 들어 로그인한 사용자가 내 정보를 조회할 때는 요청 헤더에 Access Token을 담아 보낸다.

GET /api/user/me
Authorization: Bearer accessToken
백엔드는 이 Access Token을 검증해서 사용자가 인증된 사용자인지 확인한다.

즉 Access Token은 API에 접근할 때 사용하는 출입증 같은 역할을 한다.

하지만 Access Token은 요청마다 자주 사용된다.
프론트에서 꺼내서 Authorization 헤더에 붙여야 하므로, 상대적으로 노출 위험이 있다.

그래서 Access Token은 보통 유효 시간을 짧게 가져간다.

역할

Access Token
- API 요청에 사용
- 자주 사용됨
- 탈취 위험이 있으므로 짧게 유지

Refresh Token의 역할

Refresh Token은 API 요청에 직접 사용하는 토큰이 아니다.
Refresh Token의 역할은 Access Token이 만료됐을 때, 새 Access Token을 발급받는 것이다.

흐름은 다음과 같다.

Access Token 만료
-> /api/auth/reissue 요청
-> Refresh Token 검증
-> 새 Access Token 발급

즉 Refresh Token은 재발급용 토큰이다.

Access Token보다 오래 유지되지만, 그만큼 탈취되면 위험하다.
그래서 Refresh Token은 프론트 JavaScript가 쉽게 접근할 수 있는 곳에 두지 않는 것이 좋다.

왜 하나의 토큰만 오래 쓰면 안 될까?
만약 Access Token 하나만 사용하고, 유효 기간을 14일로 길게 잡는다고 생각해보자.

그러면 구현은 단순해지지만, 토큰이 탈취되면 공격자는 14일 동안 계속 API에 접근할 수 있다.
서버가 별도로 토큰을 관리하지 않는다면 중간에 강제로 무효화하기도 어렵다.

그래서 보통 역할을 나누는 것이 일반적이다.

Token 역할 분리

다음과 같이 역할을 분리하면 Access Token이 노출되더라도 피해 시간을 줄일 수 있고,
사용자는 Refresh Token 덕분에 매번 다시 로그인하지 않아도 된다.

Access Token - 짧게 사용
Refresh Token - 더 안전한 위치에 보관

HttpOnly Cookie

HttpOnly Cookie는 브라우저에 저장되는 쿠키 중에서 JavaScript로 접근할 수 없도록 막은 쿠키다.
일반 쿠키는 JavaScript에서 document.cookie로 읽을 수 있다.

하지만 HttpOnly 옵션이 붙은 쿠키는 위와 같이 읽을 수 없다.
브라우저는 쿠키를 보관하고, 해당 서버로 요청을 보낼 때 자동으로 함께 전송한다.

HttpOnly Cookie에 저장하는 이유

JWT 구조에서 Refresh Token을 HttpOnly Cookie에 저장하는 이유는 오래 살아있는 토큰이기 때문에 더 안전하게 보관해야 하기 때문이다.

그래서 프론트 JavaScript가 직접 읽을 수 있는 브라우저 저장소인 localStorage나 sessionStorage보다 HttpOnly Cookie를 사용하는 방식이 많이 쓰인다.

한 마디로, HttpOnly Cookie는 JavaScript로 읽을 수 없고, 브라우저가 요청 시 자동으로 서버에 보내는 쿠키이다.

Redis

HttpOnly Cookie는 브라우저에 안전하게 보관하는 방법이라면, Redis는 서버가 Refresh Token을 관리하는 방법이다.
HttpOnly Cookie는 클라이언트 쪽 저장 위치이고, Redis는 서버 쪽 저장 위치이다.

즉 Refresh Token을 한 군데에 두는 게 아니라, 양쪽에서 다룬다고 생각하면 된다.

예시

로그인 성공

1. 백엔드가 Refresh Token 생성
2. 브라우저에는 HttpOnly Cookie로 저장
3. 서버는 같은 Refresh Token을 Redis에도 저장

재발급 요청

1. 브라우저가 Cookie에 담긴 Refresh Token을 자동 전송
2. 백엔드가 그 Refresh Token을 꺼냄
3. Redis에 저장된 Refresh Token과 비교
4. 같으면 새 Access Token 발급

정리

이처럼 Redis가 필요한 이유는 서버가 Refresh Token을 기억해야 하기 때문이다.

JWT 자체는 서명만 맞으면 유효하다고 판단할 수 있다.
하지만 로그아웃, 강제 만료, 재발급 관리 등을 하려면 서버가 현재 허용중인 REfresh Token을 알고 있어야 하며, 이를 저장하는 곳으로 Redis를 사용하는 것이다.

정리

Access Token과 Refresh Token을 나누는 이유는 보안과 사용자의 편의성을 함께 가져가기 위해서이다.

Access Token은 API 요청마다 자주 사용되기 때문에 짧게 유지한다.
하지만 Refresh Token은 Access Token을 재발급하기 위해 오래 유지되지만 그만큼 더 안전하게 보관해야 한다.

그래서 Refresh Token은 브라우저에서는 HttpOnly Cookie로 보관하고, 서버에서는 Redis에 저장해 유효성을 관리한다.

이번 정리를 통해 JWT 로그인 유지 방식은 단순히 토큰을 발급하는 것이 아니라,
토큰의 역할과 저장 위치를 분리해 보안과 사용자 편의성을 함께 고려하는 구조라는 것을 알 수 있었다.

[Trouble Shooting] JWT 필터에서 토큰이 없는데 바로 401을 던지지 않는 이유

mins0on — Tue, 26 May 2026 23:30:36 +0900

문제 상황

JWT 인증 필터를 만들면서 이런 코드를 작성했고, 이 부분이 이상하게 느껴졌다.

토큰이 없다는 건 인증되지 않은 요청이라는 뜻인데, 왜 바로 예외를 던지거나 401 Unauthorize 응답을 던지지 않고 다음 필터로 넘기는 걸까?

JWT가 없으면 잘못된 요청이 아닐까, 바로 막아야 하는 게 아닐까?라는 생각을 했지만 Spring Security의 인증 흐름을 조금 더 보니 잘못된 생각이었음을 깨달았다.

String authorization = request.getHeader("Authorization");

if (authorization == null || !authorization.startsWith("Bearer ")) {
    filterChain.doFilter(request, response);
    return;
}

JWT 필터는 모든 요청을 지난다

JWT 필터는 보통 Spring Security 필터 체인에 등록된다.

.addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class)

이렇게 등록하면 JWT 필터는 로그인 요청, 회원가입 요청 등 여러 요청을 지나가게 된다.
즉, JWT 필터 입장에서는 지금 들어온 요청이 반드시 인증이 필요한 요청인지 알기 어렵다.

예를 들어 다음 요청들은 토큰이 없어도 정상이어야 한다.

POST /api/auth/login
POST /api/auth/signup
GET /api/regions/sidos

로그인하려는 사용자, 회원가입 하려는 사용자 등은 토큰이 없는 것이 정상적인 흐름이다.
그런데 JWT 필터에서 토큰이 없다는 이유로 바로 401을 던지면 로그인이나 회원가입 요청까지 전부 막혀버릴 수 있다.

JWT 필터의 역할

JWT 필터의 역할은 모든 요청을 무조건 막는 것이 아닌,
Authorization 헤더에 Bearer 토큰이 있으면 검증하고, 유효하면 인증 정보를 SecurityContext에 저장하는 역할이다.

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

    String authorization = request.getHeader(AUTHORIZATION_HEADER);

    if (!hasAuthorization(authorization)) {
        filterChain.doFilter(request, response);
        return;
    }

    String token = authorization.substring(BEARER_PREFIX.length());

    if (!jwtProvider.validateToken(token)) {
        filterChain.doFilter(request, response);
        return;
    }

    String loginId = jwtProvider.getLoginId(token);

    UserDetails userDetails = customUserDetailService.loadUserByUsername(loginId);

    UsernamePasswordAuthenticationToken authentication =
            new UsernamePasswordAuthenticationToken(
                    userDetails,
                    null,
                    userDetails.getAuthorities()
            );

    SecurityContextHolder.getContext().setAuthentication(authentication);

    filterChain.doFilter(request, response);
}

private boolean hasAuthorization(String authorization) {
    return authorization != null && authorization.startsWith(BEARER_PREFIX);
}

위의 코드와 같이 토큰이 있으면 인증을 시도하고, 토큰이 없으면 인증 정보를 만들 수 없기 때문에 다음 필터로 넘긴다.
여기서 중요한 점은, 다음 필터로 넘긴다고 해서 무조건 요청이 성공하는 것은 아니라는 점이다.

filterChain.doFilter(request, response);

최종 판단은 SecurityConfig

토큰이 없는 요청을 허용할지 막을지는 JWT 필터가 아니라, SecurityConfig의 권한 설정이 판단한다.
예를 들어 다음과 같은 설정이 있다고 가정하겠다.

.authorizeHttpRequests(auth -> auth
        .requestMatchers("/api/auth/**", "/api/regions/**").permitAll()
        .anyRequest().authenticated()
)

위의 설정은 /api/auth/**, /api/regions/**의 요청 외에는 인증이 필요하다는 요청이다.
만약 토큰 없이 /api/user/me 같은 보호 API로 요청하면, JWT 필터는 그냥 넘기지만 Security 설정에서 authenticated() 조건을 만족하지 못한다.

그 결과 Spring Security가 인증되지 않은 요청으로 판단하고, 401 또는 403 응답을 내린다.

정리

처음에는 토큰이 없으면 JWT 필터에서 바로 막아야 한다고 생각했다.

하지만 JWT 필터는 모든 요청을 지나가기 때문에, 토큰이 없다는 이유만으로 바로 막으면 로그인, 회원가입, 공개 API까지 막힐 수 있다.

그래서 JWT 필터는 직접 최종 판단을 하기보다, 토큰이 있으면 인증 정보를 만들고 없으면 다음 필터로 넘긴다.
그리고 최종적으로 해당 요청이 인증이 필요한지는 SecurityConfig의 설정이 판단한다.

흐름

요청 들어옴
-> JWT 필터 실행
-> Bearer 토큰이 있으면 검증
-> 유효하면 SecurityContext에 Authentication 저장
-> 다음 필터로 이동
-> SecurityConfig의 권한 설정으로 최종 허용/거부 판단

이번 문제를 통해 JWT 필터의 역할을 더 명확히 이해할 수 있었다.
JWT 필터는 모든 요청을 막는 것이 아닌, 요청 토큰이 있을 때 Spring Security가 이해할 수 있는 인증 정보로 바꿔주는 역할에 가깝다.

[TownTalk] - 기술 스택 고민과 선택

mins0on — Tue, 26 May 2026 09:15:31 +0900

프로젝트 기술 스택 선정

이번 프로젝트는 지역 기반 커뮤니티 서비스이며, 초기에는 REST API 기반 백엔드 서버를 구축하고 이후 모바일 앱 연동까지 고려하고 있다. 그래서 단순히 익숙한 기술을 고르기보다는, 확장성, 유지보수성, 앱 연동 가능성, 배포 편의성을 기준으로 기술 스택을 선택했다.

Java 21

이전 프로젝트에서는 Java 17을 사용했지만, 이번 프로젝트에서는 Java 21을 선택했다. Java 21도 Java 17과 마찬가지로 LTS 버전이기 때문에 장기적으로 안정적인 유지보수가 가능하다.

vs Java 17

Java 17과 비교했을 때 Java 21의 가장 큰 장점은 최신 기능들이 더 안정적으로 반영되었다는 점이다. 대표적으로 Virtual Thread가 정식 기능으로 포함되어, 많은 요청을 처리하는 서버 애플리케이션에서 더 가볍고 효율적인 동시성 처리가 가능해졌다. 또한 switch 문 개선, Record Pattern, Sequenced Collection 같은 기능들이 추가되어 코드를 더 간결하고 읽기 쉽게 작성할 수 있다.

즉, Java 17이 안정적인 선택지였다면 Java 21은 그 안정성을 유지하면서도 성능과 개발 편의성을 더 높인 버전이라고 볼 수 있다.

LTS 버전

LTS는 Long Term Support이라는 뜻으로, 장기간 지원되는 버전이라는 뜻이다.
Java는 계속 새 버전이 나오지만 ,모든 버전을 오래 지원하지 않기에, 보통 오래 안정적으로 사용할 수 있는 LTS 버전을 많이 사용한다.

Virtual Thread

Virtaul Thread는 Java 21에서 정식으로 들엉노 기능이다.
기존에는 요청 하나를 처리할 때 운영체제의 무거운 스레드를 사용하는 경우가 많았는데, Virtaul Thread는 더 가벼운 스레드를 사용해서 많은 요청을 효율적으로 처리할 수 있다.

Record Pattern

Java 21에서는 record 관련 기능도 계속 개선됐다. 프로젝트에서는 요청/응답 DTO를 작성할 때 record를 활용해 불필요한 코드를 줄이고, 데이터 전달 객체를 더 간결하게 표현할 수 있다.

Sequenced Collection

Sequenced Collection은 Java 21에서 추가된 컬렉션 관련 기능이다. 쉽게 말해 순서가 있는 컬렉션을 더 일관되게 다룰 수 있게 해주는 기능이다.

예를 들어 List, LinkedHashSet처럼 순서가 있는 자료구조에서 첫 번째 값, 마지막 값의 동작을 더 통일된 방식으로 사용이 가능하다.

list.getFirst();
list.getLast();
list.reversed();

Spring Boot 4.0.6

이전에는 Spring Boot 3.5 버전을 사용했지만, 이번 프로젝트에서는 Spring Boot 4.0.6을 선택했다. Spring Boot 3.5도 충분히 안정적인 버전이지만, Spring Boot 4는 더 최신 Spring 생태계를 기반으로 한다는 장점이 있다.

Spring Boot 4는 Spring Framework 7 기반으로 동작하며, 최신 Java 환경과 더 잘 맞도록 개선되었다. 또한 기존에 사용하던 인증, 검증, 데이터베이스 연동, REST API 개발 방식은 그대로 유지하면서도 내부 구조와 의존성들이 최신 버전으로 정리되어 있다.

즉, Spring Boot 3.5가 안정적인 실무형 버전이라면, Spring Boot 4.0.6은 앞으로의 확장성과 최신 기술 호환성을 고려한 선택이라고 볼 수 있다. 모바일 앱 연동, JWT 인증, API 확장 등을 계속 추가할 예정이기 때문에 처음부터 최신 버전으로 개발 환경을 구성했다.

Gradle - Groovy

빌드 도구는 Gradle을 선택했다. Gradle은 Maven보다 설정이 유연하고 빌드 속도 측면에서도 장점이 있다. Spring Boot 프로젝트에서 기본적으로 많이 사용되며, 의존성 관리와 테스트, 빌드 자동화에 적합하다.

Supabase PostgreSQL

데이터베이스는 MySQL, MongoDB 등 다른 선택지도 있었지만, Supabase PostgreSQL을 사용했다. 이번 프로젝트에는 실무에서 많이 쓰는 PostgreSQL에 더 익숙해지고 싶었다.

PostgreSQL은 관계형 데이터베이스이기 때문에 사용자, 게시글, 댓글, 좋아요, 지역 정보처럼 서로 관계가 명확한 데이터를 다루기에 좋다. 또한 데이터 정합성이 중요하고, 복잡한 조회가 필요한 커뮤니티 서비스와 잘 맞는다.

vs MySQL

PostgreSQL, MySQL 모두 관계형 데이터베이스이다. 사용자, 게시글, 댓글 등 서로 관계가 있는 데이터를 저장 할 때 사용한다. 특히 MySQL은 사용하기 쉽고, 자료가 많아 일반적인 웹 서비스에 많이 사용되어 입문하기 편하다는 장점이 있다.

PostgreSQL은 데이터 정합성, 복잡한 조회, 확장 기능에 강한 데이터베이스이다.
커뮤니티 서비스에는 1:N의 관계가 많다. 예를 들어 사용자 1명이 게시글 여러개를 작성 할 수 있고, 게시글 1개에 댓글이 여러개 작성될 수 있다.

이러한 관계가 많아질수록 데이터가 정확하게 저장되고 조회되는 것이 중요한데, PostgreSQL은 이런 관계형 데이터와 복잡한 조회에 강점이 있다.

PostgreSQL 장점

복잡한 조회에 강함

PostgreSQL은 SQL 표준 기능과 고급 쿼리 기능을 폭 넓게 지원한다. 예를 들면 여러 테이블을 JOIN해서 조회 한다던지, 게시글 수 같은 집계, 조건별 정렬과 페이징 등이 있다. 커뮤니티 서비스에서는 단순히 게시글만 가져오는게 아니라 이러한 조회가 필요할 것이다.

JSON 데이터에 유연

MySQL도 JSON을 다룰 수 있지만, PostgreSQL이 JSON을 더 강력하고 유연하게 다루는 편이다.

PostgreSQL은 jsonb 타입을 제공하고 내부적으로 인덱스를 사용해 JOSN 내부 값 검색을 효율적으로 할 수 있다. 공식 문서에서도 jsonb 데이터의 키나 값을 효율적으로 검색하기 위해 GIN 인덱스를 사용할 수 있다고 설명한다.

MySQL도 JSON 타입은 있지만, JOSN 컬럼 자체를 바로 일반 컬럼처럼 인덱싱 하기보다는 특정 값을 직접 활용하는 방식을 많이 사용한다. 그래서 JSON을 많이 활용하는 구조에서는 PostgreSQL이 더 자연스럽다.

Supabase

Supabase를 선택한 이유는 PostgreSQL을 클라우드 환경에서 쉽게 사용할 수 있기 때문이다. 직접 DB 서버를 설치하고 관리하지 않아도 되고, 초기 개발 단계에서 빠르게 데이터베이스를 구성할 수 있다. 나중에 모바일 앱이나 웹 클라이언트와 연동할 때도 관리 화면, 인증 기능, API 연계 가능성 등에서 장점이 있다.

정리

실제 데이터베이스 = PostgreSQL
PostgreSQL을 관리해주는 클라우드 서비스 = Supabase
Java 객체와 DB를 연결해주는 ORM = JPA

Spring Data JPA

ORM으로는 Spring Data JPA를 사용했다. SQL을 직접 작성하는 방식도 가능하지만, JPA를 사용하면 객체 중심으로 데이터를 다룰 수 있어 도메인 구조를 설계하기 좋다.

예를 들어 User, Post, Comment 같은 엔티티를 만들고 이들 간의 관계를 코드로 표현할 수 있다. 반복적인 CRUD 코드도 줄일 수 있어 개발 생산성이 높아진다. 다만 복잡한 쿼리가 필요한 경우에는 JPQL이나 QueryDSL 같은 방식을 함께 고려할 수 있다.

Spring Security, JWT

보안은 Spring Security를 기반으로 구성할 예정이다. 커뮤니티 서비스에서는 로그인, 회원별 권한, 게시글 작성 권한, 토큰 검증 같은 기능이 필수적이다.

특히 모바일 앱까지 고려하면 세션 기반 인증보다는 JWT 방식이 더 적합하다. JWT는 서버가 로그인 상태를 직접 저장하지 않고 토큰을 통해 사용자를 인증할 수 있기 때문에, 웹과 모바일 앱 모두에서 사용하기 좋다.

Spring Validation

사용자 입력값 검증을 위해 Spring Validation을 사용했다. 회원가입, 로그인, 게시글 작성, 댓글 작성 같은 API에서는 잘못된 값이 들어오는 경우를 반드시 처리해야 한다.

예를 들어 이메일 형식, 비밀번호 길이, 게시글 제목의 빈 값 여부 등을 DTO 단계에서 검증하면 컨트롤러와 서비스 코드가 더 깔끔해진다. 또한 API 응답의 일관성을 유지하기에도 좋다.

보일러 플레이트 코드란 기능 자체는 단순한데, Java 문법상 계속 반복해서 작성해야하는 코드를 의미한다.

Lombok, Spring Boot DevTools

Lombok은 반복적인 getter, setter, constructor 코드를 줄이기 위해 사용했다. 엔티티나 DTO가 많아질수록 보일러플레이트 코드가 늘어나는데, Lombok을 사용하면 코드가 훨씬 간결해진다.

Spring Boot DevTools는 개발 중 서버 재시작과 변경 사항 반영을 편하게 하기 위해 사용했다. 개발 생산성을 높이는 보조 도구이다.

REST API

REST API는 웹 프론트엔드, 모바일 앱, 외부 서비스와 연동하기 쉽기에, API 스타일은 REST API로 설계했다.

현재는 백엔드 서버 중심으로 개발하더라도, 나중에 React 웹, Android/iOS 앱, 또는 Flutter/React Native 앱이 같은 API를 사용할 수 있다. 즉, 클라이언트가 바뀌어도 백엔드 API는 재사용할 수 있다는 장점이 있다.

Vite

Vite는 가볍고 빠르게 React 프론트엔드를 만들기 좋은 도구이다. Next.js는 라우팅, SEO, 백엔드 기능까지 포함한 React 프레임워크로 많은 기능을 갖고 있다.

하지만 이번 프로젝트는 Spring Boot 백엔드 서버가 따로 있고, 프론트엔드는 그 API를 호출하는 역할이 중심이다.
그래서 처음부터 Next.js처럼 많은 기능을 가진 프레임워크보다, React 화면 개발에 집중할 수 있고 설정이 비교적 단순한 Vite가 더 적합하다고 판단했다.

정리

이번 기술 스택은 빠른 개발과 장기적인 확장을 모두 고려해서 선택했다. Java와 Spring Boot는 안정적인 백엔드 서버를 만들기 좋고, PostgreSQL은 관계형 데이터가 많은 커뮤니티 서비스에 적합하다. Supabase는 초기 데이터베이스 운영 부담을 줄여주며, REST API 구조는 이후 웹과 모바일 앱 연동을 쉽게 만든다.

결국 핵심은 백엔드를 특정 화면이나 클라이언트에 종속되지 않게 만드는 것이다. 지금은 서버와 API를 중심으로 개발하고, 이후에는 Vite 기반 웹 프론트엔드나 모바일 앱을 같은 API에 연결하는 방식으로 확장할 수 있다.

[Trouble Shooting] Spring Security formLogin이 React JSON API와 맞지 않았던 이유

mins0on — Mon, 25 May 2026 22:05:56 +0900

로그인에서 formLogin 대신 AuthenticationManager를 사용한 이유

TownTalk 프로젝트에서 로그인 기능을 구현하고 있던 와중 처음에는 Spring Security의 formLogin 설정을 사용하려고 했다. formLogin을 사용하면 Spring Security가 로그인 요청을 직접 처리해주기 때문이다.

예를 들어 loginProcessignUrl을 지정하면 URL에 대한 컨트롤러를 따로 만들지 않아도 Security Filter가 요청을 가로채서 인증을 수행한다.

처음에는 이 구조가 편해 보여서 formLogin을 사용하려고 했다.
하지만 실제로 적용해보니 현재 프로젝트 구조와는 잘 맞지 않았다. 이 프로젝트는 React에서 JSON 형식으로 로그인 요청을 보내고, 백엔드는 그 요청에 대해 JSON 응답을 내려주는 방식으로 구성되어 있기 때문이다.

반면 Spring Security의 기본 formLogin은 HTML form 기반 로그인 흐름에 더 적합하다.그래서 React + JSON API 구조에서는 요청 처리 방식과 응답 방식이 맞지 않아 오히려 흐름이 헷갈렸다.

이번 글에서는 왜 formLogin 대신 AuthenticationManager를 직접 호출하는 방식으로 로그인 흐름을 정리했는지 적어보려고 한다.

헷갈렸던 부분

Spring Security를 제대로 적용해보는 건 이번이 처음이였다. 그래서 처음 formLogin을 설정하면서 loginPage와 loginProcessignUrl이 헷갈렸었다.

.formLogin(form -> form
        .loginPage("/login")
        .loginProcessingUrl("/api/auth/loginProc")
        .usernameParameter("loginId")
        .passwordParameter("password")
)

처음에는 loginPage("/login")을 설정하면 React의 /login 화면과 자연스럽게 연결되는 줄 알았지만, 이는 React 화면을 찾아주는 설정이 아니다.

인증이 필요한 요청이 들어왔을 때 Spring Security가 이동시킬 로그인 페이지 URL을 지정하는 설정이다.

또 loginProcessingUrl("/api/auth/loginProc")은 컨트롤러에 직접 매핑하는 URL이 아니다. 이 URL은 Spring Security Filter가 가로채서 로그인 인증을 처리하는 URL이다.

즉, 기본 formLogin 흐름은 서버가 HTML form 로그인을 처리하는 구조에 더 가깝다.

문제 발생 이유

현재 프로젝트는 React 프론트와 Spring Boot 백엔드가 분리되어 있다.
React는 fetch로 JSON 요청을 보내고, 백엔드는 /api/.. 형태로 JSON 응답을 내려주고 있다.

하지만 Spring Security의 기본 formLogin은 HTML form 요청을 기준으로 동작같으며, 형태는 다음과 비슷하다.

POST /login
Content-Type: application/x-www-form-urlencoded

username=testuser&password=password123!

프로젝트 - 로그인 요청

POST /api/auth/login
Content-Type: application/json

{
  "loginId": "testuser",
  "password": "password123!"
}

요청 방식 자체가 다르기에, formLogin을 그대로 사용하면 흐름이 계속 헷갈렸다.
특히 로그인 실패 시에도 React 입장에서는 HTML redirect보다 JSON 에러 응답이 필요했다.

해결 방향

현재 구조에서는 로그인 API를 직접 만들고, 그 안에서 Spring Security의 인증 기능을 사용하는 방식이 더 자연스러웠다.
그래서 login 요청을 처리하는 코드를 작성하고, 내부에서 AuthenticationManager를 호출했다.

authenticationManager.authenticate(
        new UsernamePasswordAuthenticationToken(
                request.loginId(),
                request.password()
        )
);

이 코드는 직접 비밀번호를 비교하는 코드가 아니라, AuthenticationManager에게 인증 요청을 하는 코드이다.
실제 사용자 조회는 UserDetailsService가 하고, 비밀번호 검증은 PasswordEncoder가 담당한다.

변경 후 흐름

React LoginPage
-> POST /api/auth/login
-> AuthController
-> AuthenticationManager
-> UserDetailsService
-> PasswordEncoder
-> 인증 성공 또는 실패

React는 JOSN으로 로그인 요청을 보내고, 백엔드는 API 컨트롤러에서 요청을 받아 Spring Security 인증 로직에 위임한다.

React는 화면과 요청을 담당하고, Spring Security는 인증 검증을 담당하게 되어 역할이 더 명확해졌다.

정리

서버 렌더링 기반의 HTML form 로그인이라면 Spring Security의 formLogin이 자연스럽다.
하지만 현재 프로젝트처럼 React와 Spring Boot API 서버가 분리된 구조에서는 formLign보다 JSON 로그인 API를 직접 만들고, AuthenticationManager에 인증을 위임하는 방식이 적합했다.

이러한 문제를 통해, Spring Security의 formLogin은 단순히 로그인 기능을 켜는 설정이 아니라,
HTML form 기반 인증 흐름을 전제로 한 구조라는 점을 이해하게 됐다.

그리고 이번 점을 계기로 Spring Security Filter Chain를 더 깊이있게 공부해야 한다고 느꼈고, 바로 내부 구조와 흐름에 대해서 공부할 생각이다.

[Migration] Spring Boot 마이그레이션 1단계 - 테스트 코드 작성

mins0on — Mon, 25 May 2026 09:15:15 +0900

들어가며

Spring MVC 프로젝트를 Spring Boot로 마이그레이션하면서 가장 먼저 고민한 것은 "마이그레이션 후 기존 기능이 정상적으로 동작하는지 어떻게 검증할 것인가"였다.

기존 방식대로라면 마이그레이션 후 브라우저를 열고 하나하나 클릭하며 확인해야 했다. 로그인, 회원가입, 관리자 페이지, 마이페이지 등 모든 기능을 수동으로 검증하는 것은 시간이 오래 걸리고, 놓치는 부분이 생길 수밖에 없었다.

특히 이번 마이그레이션은 단순히 프로젝트를 Spring Boot에서 실행되게 만드는 작업이 아니었다. 이후 Spring Security 도입, JPA 전환, Redis 세션 적용처럼 내부 구조를 계속 바꿔야 하는 작업 이었다.

겉으로 보이는 화면과 기능은 그대로 유지되어야 하지만, 내부 구현은 계속 달라질 예정이었다. 그래서 본격적인 마이그레이션 전에 테스트 코드를 먼저 작성하기로 했다.

테스트 코드가 있으면 마이그레이션 후 테스트를 실행하는 것만으로 기존 기능의 정합성을 1차 검증할 수 있다. 나에게 테스트 코드는 새 기능을 검증하기 위한 도구라기보다, 기존 기능을 지키기 위한 안전장치에 가까웠다.

마이그레이션 실행 흐름

1. 테스트 코드 작성
2. Spring Security 도입
3. JPA 전환
4. Redis 세션 적용
5. GitHub Actions CI/CD 구성

테스트 코드 작성 방식 선택 - BDD(Behavior Driven Development)

처음에는 테스트코드를 JUnit5 기본 방식으로 작성했다. 그런데 테스트 코드를 작성하다 보니 준비 단계에서 when()을 쓰고, 실행 단계에서도 when을 사용하니 작성하면서도 헷갈리는 부분이 있었다.

그래서 given/when/then 패턴과 맞지 않는다는 것을 느꼈고, 다른 방식을 찾아보았다.

테스트 코드를 작성하면서 단순히 테스트 개수를 늘리는 것보다, 나중에 다시 봤을 때 의도를 이해할 수 있는 테스트를 작성하는 것이 더 중요하다고 생각했다.

✔️ Mockito 기본 방식
when(userDao.selectUser("testUser")).thenReturn(mockUser);

✔️ BDD 방식
given(userDao.selectUser("testUser")).willReturn(mockUser);  ✔️ 준비
SessionUser result = userService.login("testUser", "password");  ✔️ 실행
assertThat(result).isNotNull();  ✔️ 검증

BDD 방식은 given/when/then 패턴과 자연스럽게 매핑되어, 테스트 코드의 의도가 명확하게 드러났다.
또한 then().should()로 메서드 호출 여부를 검증하는 것도 가독성이 좋아서 BDD 방식을 선택했다.

테스트 범위 정하기

프로젝트 전체 기능을 한 번에 테스트하기는 어려웠다. 이 프로젝트는 팀 프로젝트였고, 수강 신청, 강의, 게시판, 댓글 등 여러 기능이 있었다. 그중 내가 주로 담당한 영역은 회원과 관리자 기능이었다.

그래서 테스트 범위도 먼저 내 담당 영역으로 좁혀, 회원 영역에서는 다음 흐름을 중심으로 테스트했다.

처음부터 모든 테스트를 완벽하게 작성하려고 했지만 오히려 진도가 나가지 않았기에, "내가 구조를 바꿀 때 가장 자주 깨질 수 있는 부분"부터 테스트했다.

Controller 테스트

Controller 테스트는 사용자의 요청과 응답 흐름을 확인하기 위해 작성했으며, 사용한 방식은 @WebMvcTest와 MockMvc다. 처음에는 Security까지 같이 테스트하는 것이 더 좋은 것 아닌가 생각했다. 하지만 이 단계의 목적은 컨트롤러 요청/응답 흐름을 확인하는 것이었다.

Security는 별도의 테스트에서 검증하는 것이 더 명확하다고 판단했다. Controller 테스트에 Security까지 섞이면, 테스트가 실패했을 때 컨트롤러 문제인지 권한 설정 문제인지 구분하기 어렵기 때문이다.

Service 테스트

Service 테스트는 실제 비즈니스 로직을 확인하기 위해 작성했으며, 사용한 방식은 MockitoExtension이다.
Service 테스트에서는 DB, 메일, Supabase Storage 같은 외부 의존성을 mock으로 대체했다.

예를 들어 비밀번호 찾기 기능은 사용자 정보가 일치하면 임시 비밀번호를 발급하고 메일을 보내야 한다. 하지만 테스트에서 실제 메일을 보낼 필요는 없다. 중요한 것은 "메일 발송 로직이 호출되었는지"와 "예외 상황에서 올바르게 실패하는지"다.

이렇게 외부 의존성을 mock 처리하니 테스트가 빨라졌고, 서비스 로직의 조건 분기에 집중할 수 있었다.

테스트를 작성하면서 발견한 점

테스트를 작성하면서 단순히 "기능이 맞는지"만 확인한 것은 아니었다. 기존 코드의 책임이 어디에 있는지도 더 잘 보이기 시작했다. 가장 대표적인 부분이 로그인이다.

기존 프로젝트에서는 컨트롤러가 로그인 요청을 받고, 사용자 정보를 조회하고, 세션에 저장하는 흐름을 가지고 있었다. 그리고 인터셉터가 로그인 여부와 관리자 권한을 확인했다.

하지만 Spring Security를 도입하면 로그인 요청은 Security 필터가 처리한다. 컨트롤러가 직접 로그인 로직을 가질 필요가 줄어든다. 이 차이를 테스트를 보면서 더 명확하게 알 수 있었다.

기존 Controller 테스트에는 로그인 성공/실패 흐름이 들어있었지만, Security 전환 이후에는 이 테스트의 책임이 바뀌어야 한다. 로그인 컨트롤러 테스트가 아니라 Security 필터 체인, UserDetailsService, 로그인 성공/실패 핸들러 테스트로 분리하는 것이 더 맞다.

즉, 테스트 코드를 작성하면서 오히려 앞으로 리팩토링해야 할 방향이 보였다.

Spring Security 도입 전에 도움이 된 부분

테스트 코드 덕분에 Spring Security를 도입할 때 기준을 잡을 수 있었다. Security 적용 후에는 다음 흐름을 우선 확인했다.

1. 비로그인 사용자가 보호 URL에 접근하면 로그인 화면으로 이동하는가
2. 일반 사용자가 /admin/**에 접근하면 권한 없음 처리가 되는가
3. PENDING 계정으로 로그인하면 상태에 맞는 에러 메시지가 출력되는가
4. 로그인 성공 후 SessionUser가 세션에 저장되는가
5. 로그아웃 후 인증 정보와 세션이 정리되는

이 과정에서 기존 인터셉터가 담당하던 로그인 여부 확인과 관리자 권한 확인은 Spring Security로 옮기는 것이 맞다고 판단했다.

반대로 게시판 접근 권한이나 수강 신청 기간 체크처럼 다른 도메인의 비즈니스 규칙은 무리하게 제거하지 않았다. 이 부분은 내가 담당한 범위를 벗어나기도 하고, 단순 인증/인가와는 성격이 다르기 때문이다.

부족한 점

현재 작성한 테스트는 마이그레이션을 위한 첫 번째 안전망으로, 아직 부족한 부분도 많다. Security 필터를 포함한 인증/인가 테스트, CustomUserDetailsService 계정 상태별 로그인 실패 테스트 등..

특히 지금은 Controller 테스트에서 Security 필터를 제외하고 있기 때문에, 실제 권한 정책은 별도의 Security 테스트로 반드시 보강해야 한다.

마무리

이번 단계에서 테스트 코드는 단순히 정답을 확인하는 도구가 아니었다. 마이그레이션 과정에서 기존 기능을 지키기 위한 기준점이었고, 동시에 코드의 책임을 다시 생각하게 만드는 도구였다.

Spring Boot 마이그레이션은 앞으로 Security, JPA, Redis, CI/CD까지 계속 이어질 예정이다. 내부 구조는 계속 바뀌겠지만, 사용자가 경험하는 기능은 유지되어야 한다.

그래서 앞으로의 작업도 테스트를 기준으로 하나씩 확인하면서 진행하려고 한다.

한 줄 회고

테스트 코드를 먼저 작성해두니 마이그레이션이 단순한 코드 이동이 아니라, 기존 기능을 유지하면서 구조를 개선하는 작업이라는 점이 더 분명해졌다.

[회고] 첫 팀 프로젝트를 마치며

mins0on — Sun, 24 May 2026 12:16:23 +0900

첫 팀 프로젝트를 마치며

첫 팀 프로젝트를 시작하기 전에는 내가 맡은 역할에 맞춰 충분히 공부했다고 생각했고, 어느 정도 자신감도 있었다. 실무에 가까운 구조와 간결한 코드를 목표로 삼고 프로젝트를 시작했다.

하지만 실제로 프로젝트를 진행해보니 생각처럼 쉽지 않았다. 처음 진행하는 팀 프로젝트였고, 기능 구현 자체가 막히는 순간도 많았다. 그럴 때마다 조급함이 앞섰고, 설계나 구조를 충분히 고민하기보다 일단 기능을 완성하는 데 집중하게 되었다.

그 결과 많은 로직이 컨트롤러에 몰리는 비효율적인 구조가 만들어졌다. 프로젝트를 완성한 뒤 다시 코드를 돌아보니, 내가 직접 작성한 코드임에도 흐름을 한눈에 파악하기 어려웠고 수정하기도 부담스러웠다.

팀 프로젝트였기 때문에 팀원의 코드를 이해하고 활용해야 하는 상황도 많았다. 하지만 코드의 의도가 명확하게 드러나지 않거나, 충분한 커뮤니케이션 없이 작성된 코드는 파악하는 데 시간이 오래 걸렸다. 이 경험을 통해 코드 가독성과 협업에서의 커뮤니케이션이 얼마나 중요한지 체감했다.

이후 일부 코드를 리팩토링하면서 서비스 레이어를 분리하고, 공통 응답 처리에는 제네릭 와일드카드를 적용해보았다. 로직의 책임이 분리되자 코드의 의도가 더 명확해졌고, 흐름도 훨씬 쉽게 읽혔다. 이 과정에서 코드의 간결함은 단순히 짧게 작성하는 것이 아니라, 가독성과 유지보수성을 높이는 방향이어야 한다는 것을 배웠다.

프로젝트를 시작하기 전에는 팀 프로젝트가 끝나면 바로 새로운 개인 프로젝트를 준비할 생각이었다. 하지만 프로젝트를 마친 뒤 생각이 바뀌었다. 무작정 여러 프로젝트를 만드는 것보다, 하나의 프로젝트를 깊이 있게 돌아보고 부족했던 부분을 개선하는 과정이 더 중요하다고 느꼈다.

그래서 이 프로젝트를 다시 살펴보며 Spring Boot 기반으로 마이그레이션하고, 기존에 아쉬웠던 구조를 하나씩 개선해보기로 했다. 테스트 코드를 작성해 기존 기능을 검증하고, Spring Security로 인증/인가 구조를 정리하며, 이후 JPA와 Redis 세션, CI/CD까지 단계적으로 적용해볼 계획이다.

이번 경험을 통해 기능을 완성하는 것만큼 중요한 것은 유지보수 가능한 구조를 만드는 것이라는 점을 배웠다. 다음 프로젝트에서는 처음부터 관심사의 분리와 코드 가독성을 더 의식하며 개발하고 싶다.

[개념 정리] 포트

mins0on — Sat, 23 May 2026 09:15:20 +0900

포트(Port)

컴퓨터 한 대에서는 지금도 브라우저, 카카오톡, Spring Boot 서버 등 수 많은 프로그램이 동시에 실행되고 있다.
그러면 외부에서 데이터가 들어올 때 운영체제는 이걸 어느 프로그램한테 전달해야 하는지 어떻게 알까?

포트는 컴퓨터 안에서 실행 중인 각 프로그램에게 붙여주는 고유한 번호이다. 0 ~ 65535까지 존재하며, 외부에서 데이터가 들어오면 운영체제가 포트 번호를 보고 '8080으로 왔으니 Spring Boot에게 전달'이라고 판단을 한다.

ex) IP 주소는 '서울시 강남구 xx아파트' 같은 건물 주소이고, 포트는 '110동 201호' 같은 호실 번호이다.
✔️ 즉, 주소(IP)만 있으면 건물까지는 찾아가지만, 호실(포트)이 없으면 어디로 가야하는지 모른다.

IP주소와 포트의 관계

네트워크에서 특정 컴퓨터의 특정 프로그램에 접근 하려면 IP 주소와 포트 번호를 함께 작성해야 한다.
표기법은 IP 주소:포트번호 이다.

같은 컴퓨터에서도 프로그램마다 다른 포트를 사용하고 있기 때문에, 서로 충돌 없이 동시에 실행될 수 있다.

localhost

localhost는 "내 컴퓨터 자신"을 가리키는 이름이다. IP 주소와 완전히 동일하며, 개발할 때 서버를 로컬에서 띄우고 브라우저로 접속할때 사용하는 주소이다.

로컬에서 개발할 때 localhost는 개발자 본인만 접근할 수 있다. 외부에서 접근하려면 내 컴퓨터의 실제 IP나 배포된 서버 주소가 필요하다.

[개념 정리] 리버스 프록시

mins0on — Fri, 22 May 2026 14:10:14 +0900

리버스 프록시(Reverse Proxy)

리버스 프록시란 클라이언트의 요청을 대신 받아서 내부 서버로 전달하고, 응답을 다시 클라이언트에게 돌려주는 서버이다. 클라이언트는 실제 서버가 어디 있는지 알 수 없다.

장점

✔️ 보안 : 실제 서버 포트(8080 등)를 외부에 숨겨, 직접 공격을 차단 한다.
✔️ SSL 처리 : HTTPS 인증서를 여기서 한 번만 처리하여, 내부 서버는 그냥 HTTP로 통신한다.
✔️ 로드밸런싱 : 서버가 여러 대일 때 요청을 골고루 분산하여, 트래픽이 폭발해도 죽지 않는다.

요청 흐름

클라이언트 입장에선 프록시 주소 하나만 알면 되고, 뒤에서 어떤 서버가 몇 대 돌아가는지는 몰라도 된다.

정리

즉, 리버스 프록시 서버는 다음과 같은 상황에서 쓴다

✔️ 서버를 외부에 직접 노출하기 싫을 때
✔️ 도메인 하나로 여러 서비스를 운영할 때
✔️ HTTPS 인증서 관리를 한 곳에서 처리하고 싶을 때
✔️ 트래픽이 많아져서 서버를 여러 대로 늘릴 때

nginx, Apache 같은 리버스 프록시 소프트웨어는 Linux, macOS, Windows 모두 동작하며, OS 종속 개념이 아닌 아키텍처 패턴이다. 다만, 실 서버는 거의 Linux 위에서 운영되기 때문에 Linux 환경에서 주로 접하게 된다.

[운영체제] Linux의 기초 개념 이해 - 파일 시스템, 입출력, 권한 모델

mins0on — Fri, 22 May 2026 09:15:26 +0900

디렉토리 및 파일 관리

리눅스에서는 설정, 로그, 네트워크 소켓, 하드웨어 장치까지 모든 것이 파일로 추상화된다. 파일 시스템 구조를 이해하지 못하면 도커 볼륨을 마운트할 때, nginx 설정을 변경할 때, 로그를 추적할 때 매번 길을 잃게 된다.

Eveything is a File

Everything is a File은 리눅스의 핵심 철학으로 일반 파일, 디렉터리, 심볼릭 링크, 장치 파일, 소켓, 파이프 모두 파일 인터페이스로 다룹니다.

윈도우에서는 마우스, 키보드 모니터 같은 하드웨어나 네트워크 연결을 '장치 관리자'나 '제어판' 같은 특수한 프로그램으로 관리한다. 하지만, 리눅스는 무식할 정도로 단순하게 모든 걸 최상위 폴더인 '루트(/)' 아래의 파일과 디렉토리 구조로 만든다.

즉, 리눅스에서 무언가를 제어하거나 데이터를 조회하고 싶다면 전용 프로그램 필요 없이 그냥 그 파일이 있는 위치로 찾아가 조회 및 수정을 하면 끝난다는 철학입니다.

도커 볼륨 마운트

도커 컨테이너는 원래 일회성이다. 컨테이너를 삭제하면 그 안에서 생성된 로그나 사용자가 업로드한 파일, DB 데이터가 전부 날아간다.

이 문제를 해결하기 위해 내 실제 컴퓨터(호스트)의 특정 폴더와 도커 컨테이너 내부의 특정 폴더를 실시간으로 연동해 두는 것을 마운트라고 한다.

볼륨은 내 컴퓨터의 구체적인 경로를 신경 쓰지 않고, 도커한테 저장 공간을 하나 만들어달라고 요청하는 방식이다. 그러면 도커가 리눅스 도커 관리 영역에 비밀 폴더를 하나 만들고 컨테이너와 연결해준다.

즉, 도커가 데이터 유실을 막기 위해 내 컴퓨터 안에 안전하게 마련한 비밀 데이터 저장소이다.

Nginx 설정

Nginx는 가볍고 빠른 웹 서버이자, 요청을 뒤로 넘겨주는 리버스 프록시(Reverse Proxxy)역할을 하는 프로그램이다.
실무에서는 주로 Nginx 설정 파일을 포트 포워딩 및 라우팅 할 때, HTTPS 보안 적용 등을 할때 사용한다.

FHS(Filesystem Hierarchy Standard) - 표준 디렉터리 구조

리눅스는 FHS에 따라 디렉터리의 역할이 정해져있다. 외울 필요는 없지만, 자주 쓰는 경로는 익혀 두는 것이 좋다.

✔ # 루트 — 모든 것의 시작점
├── bin/ # 기본 실행 파일 (ls, cp, mv…)
├── etc/ # 시스템 전역 설정 파일
├── home/ # 사용자 홈 디렉터리
├── var/ # 로그, 캐시 등 가변 데이터
├── tmp/ # 임시 파일 (재부팅 시 삭제)
├── proc/ # 커널·프로세스 정보 (가상 FS)
├── dev/ # 장치 파일 (sda, tty…)
└── usr/ # 사용자 설치 프로그램

필수 명령어

# 탐색 / 이동
$ pwd # 현재 위치 출력
$ ls -alh /etc # 숨김파일 포함 상세 목록
$ cd ~ # 홈 디렉터리로 이동
$ cd - # 이전 디렉터리로 돌아가기 # 생성 / 복사 / 이동 / 삭제
$ mkdir -p project/src/utils # 중간 디렉터리까지 한번에 생성
$ cp -r src/ backup/ # 디렉터리 재귀 복사
$ mv old.txt new.txt # 이름 변경 or 이동
$ rm -rf temp/ # ⚠ 강제 재귀 삭제 (복구 불가) # 파일 내용 확인
$ cat config.txt # 전체 출력 $ less large.log # 페이지 단위로 탐색 (q로 종료)
$ tail -f /var/log/syslog # 로그 실시간 추적 # 검색
$ find . -name "*.log" -mtime -1 # 1일 이내 수정된 .log 파일
$ grep -rn "ERROR" ./logs/ # 재귀적으로 ERROR 문자열 검색

표준 입출력 및 리다이렉션

리눅스 명령어들은 각자 독립적이지만, 표준 입출력이라는 공통 언어로 연결된다. 이 구조 덕분에 간단한 명령어들을 조합해서 복잡한 데이터 처리가 가능하다. 파이프(|)와 리다이렉션(>)을 모르면 셀 스크립트 작성이나 로그 분석이 힘들어진다.

stdin / stdout / stderr

리눅스에서 모든 프로세스는 커널이 부여하는 3가지 표준 스트림(기본 입출력 통로)를 가지며, 각각 디스크립터(정수) 번호로(fd) 매핑되어 관리됩니다.

fd 0 (stdin / 표준 입력) : 프로세스로 데이터가 들어오는 통로(기본 값 : 키보드)
fd 1 (stdout / 표준 출력) : 프로세스의 정상 처리 결과가 나가는 통로(기본 값 : 터미널 화면)
fd 2 (stderr / 표준 에러) : 프로세스의 에러 메시지가 나가는 통로(기본 값 : 터미널 화면

stdout과 stderr를 구분하는 이유는 정상 출력만 파이프로 다음 명령어에 넘기고, 에러는 별도 로그 파일에 기록하기 위해서다.

또한 파이프(|)를 통해 명령어 A 결과물을 명령어 B 입력으로 넘길 때, A에서 에러가 발생하더라도 정상 출력 통로(fd 1)만 넘어가므로 B프로세스가 에러 메시지를 정상 데이터로 오인해 처리하는 연쇄 오류를 방지한다.

사용자 권한 모델과 보안

리눅스는 다중 사용자 운영체제이다. 권한 모델을 이해하지 못하면, Permission denied 에러 앞에서 막히거나, 반대로 모든 명령어를 sudo로 실행하는 위험한 습관이 생긴다. 서버 보안의 기초는 권한 권리에서 시작한다.

사용자·그룹 모델

모든 파일과 프로세스는 소유자(user)와 그룹(group)을 가지며, 권한 검사는 항상 세 단계로 이루어진다.

도커 컨테이너 내부는 기본적으로 root로 실행된다. 도커 컨테이너는 호스트 컴퓨터(실제 서버)의 OS 커널을 공유한다.
만약 컨테이너가 해킹 당했는데 내부 프로그램이 root 권한으로 돌고 있다면, 해커가 실제 서버까지 해킹할 수 있다.

그래서 Dockerfile을 만들 때 USER 지시어를 사용해 최고 권한자가 아닌 일반 사용자를 생성하고, 그 사용자로 프로그램을 실행하도록 명시하는 것이 좋다.

Dockerfile은 도커 이미지(설계도)를 빌드하기 위한 명령어들을 순서대로 기록한 텍스트 파일이다. 수동으로 서버 환경을 구축하는 과정을 하나의 스크립트로 자동화한 명세서이다.

보안 원칙

권장 패턴

✔ 필요한 권한만 부여
✔ sudo로 특정 명령어만 허용
✔ SSH키 권한 600 유지
✔ 서비스 계정 분리

지양 패턴

✔ 모든 것에 777권한 부여
✔ root로 서비스 실행
✔ 비밀번호 없는 sudo 설정