Aleph Kim의 IT 블로그

Laravel - 큐

Aleph Kim — Fri, 26 Jun 2026 18:49:31 +0900

1. 문제는 "느린 코드"가 아니라 "워커 점유 시간"이다

PHP 웹 애플리케이션에서 요청은 보통 nginx를 거쳐 PHP-FPM worker로 전달된다. FPM worker 하나는 한 번에 요청 하나를 처리한다. 응답을 돌려주기 전까지 그 worker는 다른 요청을 받을 수 없다.

동시 처리 가능한 요청 수
= 사용 가능한 FPM worker 수

문제는 평균 응답 시간이 아니다. 문제는 일부 요청이 갑자기 오래 걸리는 경우다.

예를 들어 평소 50ms로 끝나던 엔드포인트가 특정 입력에서 2분 동안 실행된다고 해보자. 대량 메일 발송, 외부 API 폴링, 엑셀 리포트 생성, 대규모 데이터 집계 같은 작업이 여기에 해당한다.

이런 요청이 몇 개만 겹쳐도 FPM worker가 오래 묶인다. 그러면 원래 빠르게 끝날 수 있었던 로그인, 목록 조회, 결제 확인 같은 요청까지 뒤에서 기다리게 된다.

빠른 요청들
   ↓
[FPM worker pool]
   ↑
느린 요청 몇 개가 worker를 오래 점유

nginx와 FPM 사이에는 fastcgi_read_timeout 같은 제한도 있다. nginx의 기본 fastcgi_read_timeout은 60초이며, 이 시간 동안 FastCGI 서버가 응답 데이터를 보내지 않으면 연결이 닫힌다. 사용자는 504 Gateway Timeout을 보게 될 수 있다.

그래서 핵심은 "이 작업을 더 빠르게 만들자"가 아니다.

핵심은 이 질문이다.

이 작업이 사용자의 HTTP 응답 안에서 반드시 끝나야 하는가?

답이 아니면 요청 경로 밖으로 빼야 한다.

2. 큐는 작업을 나중에 실행하는 장치가 아니라, 요청 수명을 끊어내는 장치다

Laravel 큐의 가장 중요한 역할은 무거운 작업을 HTTP 요청의 수명에서 분리하는 것이다.

HTTP 요청
→ Job dispatch
→ 큐 백엔드에 저장
→ 즉시 응답

별도 worker
→ 큐에서 Job pop
→ 실제 작업 처리

컨트롤러 안에서 메일을 직접 보내면 HTTP 요청이 메일 발송 시간만큼 길어진다. 반대로 Job을 dispatch하면 요청에서는 "작업을 큐에 넣는 일"만 하고 끝난다.

SendWelcomeMail::dispatch($user->id);

return response()->json([
    'message' => 'queued',
]);

이때 실제 메일 발송은 FPM worker가 아니라 별도의 queue:work 프로세스가 처리한다.

[HTTP 요청] ─ dispatch ─▶ [queue backend] ◀─ pop ─ [queue worker]
   빠르게 응답              jobs table / Redis       무거운 작업 수행

즉 큐를 도입한다는 것은 "코드를 비동기로 바꾼다"보다 더 정확히 말해 "사용자 응답을 위한 worker와 백그라운드 작업을 위한 worker를 분리한다"는 뜻이다.

3. connection과 queue는 다르다

Laravel 큐에서 자주 헷갈리는 용어가 있다.

connection = 큐 백엔드
queue      = 그 백엔드 안의 논리적 채널

예를 들어 redis는 connection이고, high, default, emails는 queue 이름이다.

SendMail::dispatch($user->id)
    ->onConnection('redis')
    ->onQueue('emails');

worker는 특정 connection에서 특정 queue들을 소비한다.

php artisan queue:work redis --queue=high,default

여기서 high,default의 순서가 중요하다. Laravel worker는 앞에 있는 queue를 우선 처리한다. 그래서 인증 메일, 결제 후처리처럼 지연이 민감한 Job은 high에 넣고, 대량 통계 집계나 마케팅 발송은 default 또는 bulk로 분리할 수 있다.

high queue     → 즉시성 중요
default queue  → 일반 작업
bulk queue     → 느려도 되는 대량 작업

이 분리가 없으면 대량 작업이 쌓였을 때 중요한 작업까지 같이 밀린다. 큐를 쓴다고 자동으로 우선순위가 생기는 것이 아니다. queue 이름을 어떻게 나누고 worker를 어떻게 띄우느냐가 운영 품질을 결정한다.

4. database 드라이버는 단순하지만, DB를 큐로 쓰는 선택이다

Laravel은 database, Redis, SQS 같은 여러 큐 백엔드를 같은 API 뒤로 숨긴다. 그중 database 드라이버는 별도 인프라 없이 RDB 테이블을 큐로 쓰는 방식이다.

기본적으로 jobs 테이블에 Job payload가 저장된다.

컬럼	의미
`queue`	논리적 queue 이름
`payload`	직렬화된 Job 정보
`attempts`	시도 횟수
`reserved_at`	worker가 점유한 시각
`available_at`	이 시각 이후 실행 가능
`created_at`	생성 시각

Job을 dispatch하면 Laravel은 Job 객체를 직렬화해서 payload로 저장한다.

Job 객체
→ serialize
→ payload JSON
→ jobs table 저장

여기서 중요한 점은 생성자에 넘긴 값이 큐 payload에 들어간다는 것이다. 큰 바이너리, 거대한 배열, 필요 이상으로 많은 관계가 로드된 Eloquent 모델을 넣으면 payload가 커진다.

대부분은 데이터 자체보다 식별자만 넘기는 편이 낫다.

// 권장하기 쉬운 형태
ProcessReport::dispatch($report->id);

// 위험해질 수 있는 형태
ProcessReport::dispatch($largeCollection);

큐 payload는 "작업에 필요한 최소 정보"만 담아야 한다. 실제 데이터는 worker가 처리 시점에 다시 조회하는 편이 안전하다.

5. database 큐에서 worker들은 같은 Job을 어떻게 피하나

database 큐에서 가장 중요한 문제는 여러 worker가 같은 Job을 동시에 집지 않게 하는 것이다.

Laravel의 DatabaseQueue는 트랜잭션 안에서 다음 실행 가능한 Job을 찾고, 그 행을 잠근 뒤, reserved_at과 attempts를 갱신한다.

개념적으로는 이런 흐름이다.

SELECT *
FROM jobs
WHERE queue = ?
  AND (
    (reserved_at IS NULL AND available_at <= ?)
    OR reserved_at <= ?
  )
ORDER BY id ASC
LIMIT 1
FOR UPDATE SKIP LOCKED;

의미는 단순하다.

아직 점유되지 않았고 실행 가능한 Job
또는
점유된 지 retry_after가 지나 죽은 worker의 Job

FOR UPDATE는 선택한 행을 잠근다. SKIP LOCKED는 다른 worker가 이미 잠근 행을 기다리지 않고 건너뛴다.

Laravel 10.x 기준 source를 보면 MySQL 8.0.1 이상, MariaDB 10.6 이상, PostgreSQL 9.5 이상, Vitess 19 이상에서는 FOR UPDATE SKIP LOCKED를 사용한다. SQL Server에서는 별도 lock 힌트를 쓰고, 그 외에는 일반적인 lock으로 폴백한다.

여기서 중요한 구분이 있다.

SKIP LOCKED 있음
→ 잠긴 행을 건너뛰므로 worker들이 병렬로 다른 Job을 잡기 쉬움

SKIP LOCKED 없음
→ 같은 앞쪽 행의 lock을 기다릴 수 있어 처리량이 떨어짐

즉 구버전 DB에서 약해지는 것은 보통 정확성보다 처리량이다. 중복 실행을 무조건 허용한다는 뜻이 아니라, worker들이 더 자주 기다리게 된다는 뜻에 가깝다.

6. retry_after와 timeout을 헷갈리면 중복 실행이 나온다

큐 운영에서 가장 자주 터지는 설정 실수는 retry_after와 timeout을 같은 것으로 보는 것이다.

둘은 완전히 다른 축이다.

설정	의미
`retry_after`	worker가 죽었다고 보고 점유 Job을 다시 풀어주는 시간
`$timeout` / `--timeout`	한 Job 실행을 worker가 강제로 종료하는 시간

예를 들어 어떤 Job이 정상적으로 100초 걸리는데 retry_after가 90초라면 어떻게 될까.

0초    worker A가 Job 점유
90초   Laravel이 "A가 죽었나?"라고 보고 Job을 다시 사용 가능하게 봄
100초  worker A가 아직 처리 중
동시에 worker B가 같은 Job을 다시 처리할 수 있음

결과는 중복 실행이다. 메일이 두 번 가거나, 외부 API가 두 번 호출되거나, 결제가 두 번 시도되는 식의 문제가 생길 수 있다.

그래서 원칙은 간단하다.

Job timeout < retry_after

Laravel 공식 문서도 worker timeout 값을 retry_after보다 몇 초 짧게 잡으라고 설명한다. 그래야 오래 걸리는 worker가 먼저 종료되고, 그 뒤 retry_after가 지난 Job이 다시 시도된다.

Laravel 10.x 문서에서는 Job별 timeout을 Job 클래스의 $timeout property로 설명한다. 이 값은 queue:work --timeout으로 지정한 값보다 우선한다.

큐는 기본적으로 at-least-once 전달 모델에 가깝다. 즉 "최소 한 번은 실행"을 목표로 하며, 장애 상황에서는 중복 실행이 가능하다. 그래서 메일, 결제, 쿠폰 지급, 포인트 적립처럼 부수효과가 있는 Job은 멱등성을 직접 설계해야 한다.

같은 요청이 두 번 와도 결과는 한 번만 반영되게 만들 것

이것이 큐 운영의 핵심이다.

7. queue:work는 웹 요청과 다른 생명주기를 가진다

php artisan queue:work는 PHP-FPM 요청이 아니다. CLI에서 실행되는 별도 PHP 프로세스다.

그리고 중요한 점은 queue:work가 상주 프로세스라는 것이다.

프레임워크 boot
→ Job 처리
→ 다음 Job 처리
→ 다음 Job 처리
→ 계속 반복

이 구조는 빠르다. 매 Job마다 Laravel을 새로 부팅하지 않아도 되기 때문이다.

하지만 위험도 있다.

FPM 요청
→ 요청 끝나면 상태 정리

queue:work
→ 프로세스가 살아 있는 동안 상태가 남을 수 있음

싱글톤 객체, static property, 전역 상태, 누적 배열, 닫히지 않은 리소스가 Job 사이에 남을 수 있다. 전통적인 PHP 요청 모델에 익숙하면 이 차이를 놓치기 쉽다.

그래서 worker는 주기적으로 재시작되도록 운영하는 편이 안전하다.

php artisan queue:work redis \
  --queue=high,default \
  --tries=3 \
  --timeout=60 \
  --max-time=3600 \
  --max-jobs=1000

--max-time과 --max-jobs는 worker가 영원히 늙어가지 않도록 하는 안전장치다. 메모리 누수나 상태 오염이 누적되기 전에 프로세스를 새로 띄우는 방식이다.

배포할 때도 주의해야 한다. 상주 worker는 이미 로드한 코드를 메모리에 들고 있다. 새 코드를 배포했다고 worker가 자동으로 새 코드를 읽는 것은 아니다.

php artisan queue:restart

이 명령은 worker에게 현재 Job을 끝낸 뒤 재시작하라고 알려준다. Supervisor나 systemd 같은 프로세스 관리자는 종료된 worker를 다시 띄운다.

참고로 fastcgi_finish_request()로 응답을 먼저 flush한 뒤 뒤처리를 계속하는 방법도 있다. 하지만 이 코드는 여전히 같은 PHP 요청 흐름 안에서 실행된다. 큐처럼 별도 worker, 재시도, 실패 추적, 처리량 제어가 생기는 것은 아니다. 그래서 짧은 후처리에는 쓸 수 있어도, 무거운 작업을 분리하는 기본 해법으로 보기는 어렵다.

8. Supervisor 상주 worker와 cron 기동 worker는 목적이 다르다

큐 worker를 운영하는 대표적인 방식은 두 가지다.

1. Supervisor/systemd로 항상 띄워둔다
2. cron 또는 scheduler가 주기적으로 worker를 띄운다

처리량과 지연 시간이 중요하면 상주 worker가 정석이다.

[program:app-worker]
command=php /path/artisan queue:work redis --queue=high,default --sleep=3 --tries=3 --timeout=60 --max-time=3600 --max-jobs=1000
autostart=true
autorestart=true
numprocs=4
stopwaitsecs=3600
stopsignal=TERM

이 방식에서는 worker가 항상 떠 있다. Job이 들어오면 바로 처리할 수 있고, numprocs로 병렬성을 늘릴 수 있다.

반대로 작은 서비스나 인프라 제약이 있는 환경에서는 scheduler로 worker를 짧게 띄우는 절충도 가능하다.

Schedule::command('queue:work --stop-when-empty --max-time=50')
    ->everyMinute()
    ->withoutOverlapping(10)
    ->runInBackground();

이 구성은 이런 의미다.

옵션	의미
`--stop-when-empty`	큐가 비면 worker 종료
`--max-time=50`	1분 주기보다 짧게 실행해 겹침을 줄임
`withoutOverlapping(10)`	이전 실행이 남아 있으면 다음 실행 건너뜀
`runInBackground()`	scheduler의 다른 작업을 막지 않음

이 방식은 상주 worker보다 처리량이 낮다. 하지만 유휴 상태에서 worker가 계속 메모리를 점유하지 않는다.

정리하면 선택 기준은 이렇다.

지연 시간이 중요하고 Job이 자주 들어온다
→ Supervisor/systemd + Redis/Horizon

작은 규모이고 작업이 가끔 들어온다
→ scheduler로 짧게 queue:work 기동

9. ShouldQueue는 실행 경로를 바꾸는 마커다

Laravel에서는 Job을 직접 dispatch할 수도 있지만, Mailable, Notification, Listener에 ShouldQueue를 붙여 비동기화할 수도 있다.

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;

class WelcomeMail extends Mailable implements ShouldQueue
{
    use Queueable, SerializesModels;
}

호출부는 크게 달라지지 않는다.

Mail::to($user)->send(new WelcomeMail($user));

하지만 WelcomeMail이 ShouldQueue를 구현하고 있으면 Laravel은 즉시 발송 대신 queue로 보낸다.

ShouldQueue 자체는 메서드가 없는 마커 인터페이스다. 프레임워크가 "이 객체는 큐로 보내야 한다"는 신호로 읽는 것이다.

Notification과 Event Listener도 같은 방식으로 동작한다. 그래서 호출부를 크게 바꾸지 않고도 느린 부수효과를 요청 경로 밖으로 밀어낼 수 있다.

Job 자체의 시도 횟수와 timeout은 Laravel 10.x 기준으로 Job 클래스의 property를 이용해 표현할 수 있다. 재시도 대기 시간은 단순 값이면 $backoff property로, 점증 backoff처럼 여러 값을 쓰려면 backoff() 메서드로 표현한다.

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class SendWelcomeMail implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public $tries = 3;

    public $timeout = 30;

    public function backoff(): array
    {
        return [10, 60, 300];
    }
}

10. SerializesModels는 모델을 통째로 저장하지 않게 돕는다

Job에 Eloquent 모델을 넘길 때 Laravel은 Queueable / SerializesModels 계열의 직렬화 규칙을 통해 모델 전체를 그대로 payload에 넣지 않는다.

핵심은 모델을 식별자로 바꿔 저장하는 것이다.

User 모델 객체
→ User 클래스명 + primary key + connection
→ worker에서 다시 조회

이 방식의 장점은 payload가 작아지고, worker가 처리 시점의 최신 DB 상태를 다시 읽는다는 점이다.

하지만 단점도 있다.

dispatch 시점에는 존재하던 모델이 worker 처리 시점에는 삭제되어 있을 수 있다.

dispatch
→ User id=10 저장
→ 그 사이 User 삭제
→ worker가 id=10 조회 실패

이때 Job을 실패시키지 않고 조용히 버리고 싶다면 Laravel 버전에 맞는 missing model 처리 방식을 써야 한다. Laravel 10.x 문서 기준으로는 $deleteWhenMissingModels = true property를 사용할 수 있다.

class SendWelcomeMail implements ShouldQueue
{
    public $deleteWhenMissingModels = true;
}

11. 트랜잭션 안에서 dispatch하면 afterCommit을 확인해야 한다

큐와 DB 트랜잭션을 함께 쓸 때 흔한 레이스가 있다.

DB::transaction(function () {
    $order = Order::create([...]);

    ProcessOrder::dispatch($order);
});

이 코드는 보기에는 자연스럽다. 하지만 worker가 빠르면 트랜잭션이 commit되기 전에 Job을 집을 수 있다.

그러면 worker 입장에서는 아직 DB에 보이지 않는 데이터를 읽으려고 하는 셈이다.

요청 프로세스
→ 트랜잭션 시작
→ 주문 생성
→ Job dispatch
→ 아직 commit 전

worker
→ Job pop
→ 주문 조회
→ 조회 실패 또는 불완전한 상태

해결책은 after_commit 설정 또는 afterCommit()이다.

ProcessOrder::dispatch($order)->afterCommit();

이렇게 하면 열린 DB 트랜잭션이 모두 commit된 뒤 Job이 실제로 dispatch된다. 트랜잭션이 rollback되면 그 안에서 예약된 Job도 버려진다.

트랜잭션과 큐를 함께 쓴다
→ afterCommit 여부를 반드시 확인한다

이 규칙 하나만 지켜도 프로덕션에서 애매하게 재현되는 큐 버그를 꽤 줄일 수 있다.

12. Queue, Command, Scheduler, Event, Observer는 책임이 다르다

Laravel에는 "요청 밖에서 무언가를 실행하는 도구"가 여러 개 있다. 이름만 보면 비슷하지만 책임이 다르다.

도구	트리거	책임
Queue Job	코드에서 dispatch	무거운 작업을 비동기로 처리
Artisan Command	수동 실행 또는 scheduler	배치, 운영 작업, 데이터 보정
Scheduler	시간	정해진 시점에 Command나 Job을 실행
Event + Listener	사건 발생	하나의 사건에 여러 부수효과 연결
Observer	모델 생명주기	모델 저장/삭제에 항상 붙는 처리

예를 들어 매일 새벽 리포트를 생성해야 한다면 Scheduler가 시간을 담당하고, Command가 실행 단위를 담당하고, 내부에서 Queue Job을 dispatch해 병렬 처리할 수 있다.

Scheduler
→ Artisan Command
→ Queue Job 여러 개 dispatch
→ worker가 실제 처리

회원 가입 후 메일, 슬랙 알림, CRM 동기화를 붙이고 싶다면 Event와 Listener가 잘 맞는다.

UserRegistered event
→ SendWelcomeMail listener
→ NotifySlack listener
→ SyncCrm listener

각 Listener에 ShouldQueue를 붙이면 느린 부수효과만 비동기로 분리할 수 있다.

Observer는 모델 저장/삭제에 항상 따라야 하는 규칙에 적합하다. 다만 Observer 자체는 동기 실행되므로, 무거운 작업은 Observer 안에서 직접 처리하지 말고 Job으로 넘기는 편이 좋다.

13. 운영 체크리스트

큐는 코드를 깔끔하게 만드는 도구이기도 하지만, 실제로는 운영 시스템이다. 그래서 다음 항목을 계속 확인해야 한다.

Job이 쌓이기만 한다
→ worker가 떠 있는지 확인
→ scheduler/cron이 도는지 확인
→ withoutOverlapping lock이 남아 있는지 확인

Job이 중복 실행된다
→ timeout < retry_after 확인
→ 멱등성 키 확인
→ afterCommit 누락 확인

배포 후 코드가 안 바뀐다
→ 상주 worker가 구버전 코드를 들고 있는지 확인
→ php artisan queue:restart 실행

worker가 조용히 죽는다
→ 메모리 제한, OOM, 로그 확인
→ --max-jobs / --max-time / --memory 설정 확인

DB 부하가 커진다
→ database 큐 polling 비용 확인
→ Redis 전환 또는 Horizon 도입 검토

Redis 큐를 쓰는 경우 Laravel Horizon도 좋은 선택이다. Horizon은 Redis 기반 queue의 처리량, 실행 시간, 실패 Job 같은 지표를 볼 수 있는 대시보드와 worker 설정 체계를 제공한다.

14. 정리

Laravel 큐의 핵심은 비동기 문법이 아니다.

핵심은 HTTP 요청의 책임과 백그라운드 작업의 책임을 분리하는 것이다.

HTTP 요청
→ 사용자에게 필요한 응답을 빠르게 반환

Queue worker
→ 오래 걸리고 실패할 수 있는 작업을 따로 처리

FPM worker는 사용자 응답을 위해 아껴야 한다. 메일 발송, 외부 API 호출, 대량 집계, 파일 변환 같은 작업이 FPM worker를 오래 붙잡고 있으면 전체 애플리케이션 응답성이 무너진다.

큐를 쓰면 이 문제를 구조적으로 끊어낼 수 있다.

다만 큐를 도입하면 새로운 책임도 생긴다.

worker 운영
재시도 정책
실패 Job 관측
중복 실행 방어
트랜잭션 경계
배포 시 worker 재시작

그래서 큐는 "나중에 실행"이 아니라 "다른 실행 주체에게 책임을 넘기는 것"으로 이해하는 편이 좋다.

정리하면 이렇게 말할 수 있다.

요청에 꼭 필요한 일은 HTTP 경로에서 처리하고, 실패해도 재시도할 수 있는 무거운 일은 큐로 넘긴다. Laravel 큐 설계의 품질은 이 경계를 얼마나 정확히 긋느냐에서 결정된다.

참고 자료

Laravel Queues 10.x: https://laravel.com/docs/10.x/queues
Laravel Mail 10.x: https://laravel.com/docs/10.x/mail
Laravel Task Scheduling 10.x: https://laravel.com/docs/10.x/scheduling
Laravel Horizon 10.x: https://laravel.com/docs/10.x/horizon
Laravel Framework DatabaseQueue source: https://github.com/laravel/framework/blob/10.x/src/Illuminate/Queue/DatabaseQueue.php
nginx fastcgi_read_timeout: https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_read_timeout
PHP fastcgi_finish_request: https://www.php.net/manual/en/function.fastcgi-finish-request.php

PHP - 인터프리터 언어와 컴파일 언어, 그리고 PHP가 Java처럼 동작하지 않는 이유

Aleph Kim — Fri, 26 Jun 2026 18:12:46 +0900

인터프리터와 컴파일러, 그리고 PHP가 Java처럼 동작하지 않는 이유

프로그래밍 언어는 결국 컴퓨터가 실행할 수 있는 형태로 바뀌어야 한다. 사람이 작성한 소스 코드를 CPU가 바로 이해하는 것은 아니기 때문이다.

그래서 모든 언어는 어떤 방식으로든 변환 과정을 거친다.

소스 코드
→ 번역 또는 해석
→ 실행

전통적으로 이 변환을 실행 전에 미리 하면 컴파일 방식, 실행하면서 처리하면 인터프리터 방식이라고 부른다. 하지만 현대 언어에서는 이 구분이 아주 깔끔하게 나뉘지 않는다.

1. 컴파일 언어와 인터프리터 언어는 절대 분류가 아니다

C, C++, Rust, Go 같은 언어는 보통 실행 전에 기계어 실행 파일로 컴파일한다.

C/Rust/Go source
→ compiler
→ machine code binary
→ 실행

반대로 Python, Ruby, PHP, JavaScript 같은 언어는 사용자가 별도의 빌드 산출물을 직접 만들지 않고 바로 실행하는 경험을 제공한다.

source
→ runtime/interpreter
→ 실행

그래서 관습적으로 “컴파일 언어”, “인터프리터 언어”라고 부르지만, 더 정확히는 언어 자체보다 실행 구현 방식의 차이다.

Java는 소스를 .class bytecode로 컴파일한 뒤 JVM에서 실행하고, JavaScript V8은 bytecode interpreter와 JIT compiler를 함께 사용한다. Python도 CPython 기준으로 소스를 bytecode로 컴파일한 뒤 VM에서 실행한다.

즉 현대적인 관점에서는 이렇게 보는 게 맞다.

컴파일 vs 인터프리터
= 실행 전에 얼마나 번역하느냐
= 실행 중에 얼마나 최적화하느냐
= 실행 상태를 얼마나 오래 유지하느냐

2. Python은 순수 인터프리터인가?

아니다. 적어도 표준 구현체인 CPython은 순수 인터프리터라고 보기 어렵다.

CPython은 .py 파일을 바로 한 줄씩 읽어 실행하는 것이 아니라, 먼저 bytecode로 컴파일한다. 그 bytecode는 Python VM이 실행한다. 또한 bytecode는 .pyc 파일로 __pycache__에 저장될 수 있어 다음 실행에서 재컴파일 비용을 줄인다.

Python source
→ CPython bytecode
→ Python VM
→ 실행

다만 사용자가 javac처럼 명시적인 빌드 단계를 거치지 않기 때문에, 개발 경험상 “인터프리터 언어”라고 부르는 것이다.

그리고 CPython도 3.13부터 실험적 JIT를 포함할 수 있다. 다만 기본 실행 모델을 설명할 때는 여전히 “bytecode를 VM이 해석한다”는 표현이 더 안전하다.

3. PHP도 순수 인터프리터가 아니다

PHP도 Python과 비슷하게 동작한다.

PHP source
→ Zend opcode
→ Zend VM
→ 실행

PHP는 소스를 Zend Engine이 opcode로 컴파일하고, Zend VM이 그 opcode를 실행한다. 여기에 OPcache를 켜면 컴파일된 opcode를 공유 메모리에 저장해 매 요청마다 소스를 다시 파싱하고 컴파일하는 비용을 줄인다.

첫 요청
PHP source → opcode compile → OPcache 저장 → 실행

다음 요청
OPcache의 opcode 재사용 → 실행

그래서 “PHP는 매 요청마다 무조건 처음부터 인터프리팅한다”는 표현은 부정확하다. OPcache가 활성화된 운영 환경에서는 컴파일 결과를 재사용한다.

PHP 8부터는 JIT도 추가됐다. 다만 JIT가 있다고 해서 일반적인 PHP 웹 애플리케이션이 Java HotSpot처럼 항상 강한 JIT 효과를 얻는다고 보면 안 된다. PHP JIT는 설정에 따라 활성화되고, 웹 요청 중심 애플리케이션에서는 병목이 DB, 네트워크, I/O인 경우가 많기 때문이다.

4. 그럼 PHP는 왜 Java처럼 계속 떠 있는 VM으로 쓰지 않을까?

질문의 핵심은 “PHP도 bytecode와 VM이 있는데 왜 Java처럼 애플리케이션을 메모리에 올려두고 계속 재사용하지 않느냐”다.

여기서 중요한 차이는 컴파일 여부가 아니라 요청 상태를 유지하느냐다.

Java 웹 애플리케이션은 보통 JVM 프로세스가 오래 살아 있다.

JVM 시작
→ 애플리케이션 로드
→ 객체/상태/캐시 유지
→ 여러 요청 처리
→ JIT 최적화 누적

반면 전통적인 PHP-FPM 모델은 worker 프로세스는 살아 있지만, 각 요청의 애플리케이션 상태는 요청이 끝나면 정리되는 방식이다.

php-fpm worker 유지
→ 요청 수신
→ Laravel/PHP 요청 처리
→ 응답
→ 요청 중 만든 상태 정리
→ 다음 요청 처리

즉 PHP가 매 요청마다 프로세스를 새로 띄우는 것은 아니다. FPM worker는 살아 있다. OPcache도 살아 있다. 하지만 요청 중 생성한 객체, 전역 상태, 서비스 컨테이너 상태는 기본적으로 다음 요청에 그대로 이어지지 않는다.

이것이 전통적인 PHP의 중요한 특징이다.

5. PHP가 이 모델을 택한 이유

PHP의 기본 모델은 흔히 shared-nothing에 가깝다고 설명한다. 요청 하나가 끝나면 그 요청에서 만든 대부분의 상태가 사라진다.

이 방식은 성능 면에서 Java식 상주 애플리케이션보다 불리한 부분이 있다. 매 요청마다 프레임워크 부트스트랩 비용이 들 수 있기 때문이다.

하지만 장점도 크다.

요청마다 깨끗한 상태
→ 상태 오염 위험 감소
→ 메모리 누수 누적 감소
→ 동시성 모델 단순화
→ 배포와 운영이 단순해짐

Java나 Node.js처럼 애플리케이션이 오래 살아 있으면 전역 변수, 싱글톤, static 상태, 메모리 누수가 계속 누적될 수 있다. 반면 전통적인 PHP는 요청이 끝나면 대부분 정리되므로 이런 문제가 구조적으로 덜하다.

대신 PHP는 OPcache로 컴파일 비용을 줄인다.

컴파일 결과는 유지한다
애플리케이션 요청 상태는 버린다

이게 PHP의 절충점이다.

6. PHP도 Java처럼 상주 모델로 쓸 수 있다

PHP가 반드시 전통적인 FPM 모델로만 동작해야 하는 것은 아니다.

Laravel Octane, Swoole, RoadRunner, FrankenPHP worker mode 같은 도구를 쓰면 애플리케이션을 한 번 부트스트랩한 뒤 메모리에 유지하고 여러 요청을 처리할 수 있다.

PHP application boot
→ 메모리에 유지
→ 여러 요청 처리
→ worker 재시작 전까지 상태 유지

이 방식은 빠르다. Laravel 부트스트랩 비용을 줄일 수 있고, 처리량도 좋아질 수 있다.

하지만 대가가 있다. 요청 사이에 상태가 남을 수 있으므로 전통적인 PHP에서 신경 쓰지 않아도 되던 문제를 직접 관리해야 한다.

static 배열에 데이터를 계속 쌓으면 메모리 누수가 된다.
request 객체를 싱글톤에 보관하면 다음 요청에서 오래된 request를 볼 수 있다.
배포 후 worker reload를 하지 않으면 새 코드가 바로 반영되지 않을 수 있다.

즉 PHP도 Java식 모델을 사용할 수 있지만, 그 순간부터 Java식 장기 실행 프로세스의 책임도 함께 따라온다.

7. 정리

컴파일 언어와 인터프리터 언어의 차이는 단순히 빠르다, 느리다의 문제가 아니다.

컴파일 방식
→ 실행 전에 더 많이 준비
→ 성능과 검증에 유리

인터프리터 방식
→ 실행 시점에 더 많이 처리
→ 개발 편의성과 유연성에 유리

하지만 현대 언어는 대부분 섞여 있다.

Python  → bytecode + VM
Java    → bytecode + JVM + JIT
PHP     → opcode + Zend VM + OPcache + 선택적 JIT
JS V8   → bytecode interpreter + JIT

PHP와 Java의 진짜 차이는 “VM이 있느냐 없느냐”가 아니다.

Java는 애플리케이션 상태를 오래 유지하는 쪽에 가깝고, 전통적인 PHP는 컴파일 결과는 캐시하되 요청 상태는 버리는 쪽에 가깝다.

그래서 PHP는 단순한 운영, 요청 격리, 상태 초기화의 안전성을 얻었다. 대신 장기 실행 애플리케이션이 얻는 강한 warm-up 효과와 상태 재사용은 기본값으로 포기했다. 필요하다면 Octane, Swoole, RoadRunner, FrankenPHP 같은 상주 런타임으로 그 반대 선택을 할 수 있다.

8. 참고 자료

컴파일의 기본 개념
- MDN: Compile
  컴파일은 한 언어/형식의 프로그램을 다른 형식의 명령어로 변환하는 과정이며, AOT와 JIT 컴파일을 함께 설명한다.
- GCC 공식 문서: Options Controlling the Kind of Output
  GCC 컴파일 과정이 preprocessing, compilation, assembly, linking 단계로 이어지고 최종적으로 실행 파일을 만들 수 있음을 설명한다.
- GCC 공식 문서: Optimize Options
  최적화 옵션이 실행 성능이나 코드 크기 개선을 목표로 하며, 그 대신 컴파일 시간/메모리 비용이 늘 수 있음을 설명한다.
컴파일 언어 예시
- Rust 공식 문서: What is rustc?
  rustc가 Rust 컴파일러이며, 소스 코드를 라이브러리나 실행 가능한 binary code로 만든다고 설명한다.
- Oracle 공식 문서: The javac Command
  javac가 Java 소스 파일을 JVM에서 실행되는 .class 파일로 컴파일한다고 설명한다.
인터프리터 방식 / Python
- Python 공식 튜토리얼: Whetting Your Appetite
  Python을 interpreted language로 설명하며, 별도 compile/link 과정 없이 개발 중 빠르게 실험할 수 있다는 장점을 언급한다.
- Python 공식 문서: Glossary - bytecode
  Python 소스 코드가 CPython 인터프리터 내부 표현인 bytecode로 컴파일되고, virtual machine에서 실행된다고 설명한다.
- Python 공식 문서: py_compile
  Python 소스 파일을 bytecode cache 파일로 컴파일하는 기능을 설명한다.
현대 언어가 섞여 있다는 근거
- MDN: Just-In-Time Compilation
  JIT는 실행 중에 중간 표현이나 고수준 언어 코드를 machine code로 컴파일하는 방식이며, interpreter와 AOT의 장점을 섞는 접근이라고 설명한다.
- V8 공식 블로그: Firing up the Ignition interpreter
  V8이 JavaScript 함수를 bytecode로 컴파일하고 Ignition interpreter가 이를 실행한다고 설명한다.
- PyPy 공식 문서: Bytecode Interpreter
  PyPy도 Python 소스에서 파싱/컴파일된 code object와 bytecode interpreter 구조를 가진다고 설명한다.

PHP - SAPI

Aleph Kim — Fri, 26 Jun 2026 17:52:33 +0900

개요

PHP 애플리케이션은 같은 코드베이스라도 항상 같은 방식으로 실행되지 않는다. 웹 요청은 보통 PHP-FPM worker가 처리하고, php artisan 같은 명령은 CLI 프로세스가 처리한다. 로컬 개발에서 사용하는 php artisan serve는 또 다른 실행 방식인 PHP built-in server를 사용한다.

이 차이를 이해하려면 먼저 SAPI를 분리해서 봐야 한다. SAPI는 PHP 엔진이 외부 세계와 만나는 실행 인터페이스다. 즉 PHP 코드 자체가 달라지는 것이 아니라, PHP 엔진에 요청을 어떻게 전달하고 결과를 어디로 내보낼지가 달라진다.

1. SAPI란?

SAPI는 PHP 문맥에서 Server API, 또는 Server Application Programming Interface로 설명된다. 이름에 server가 들어가지만 웹 서버 전용이라는 뜻은 아니다. CLI, FPM, CGI, built-in server, phpdbg 모두 PHP의 SAPI다.

PHP 실행은 대략 이렇게 나뉜다.

입력 환경
→ SAPI
→ PHP 엔진 / Zend Engine
→ PHP 코드 실행
→ SAPI를 통해 결과 반환

SAPI는 다음을 결정한다.

입력을 어디서 받을지: HTTP 요청, 터미널 인자, FastCGI payload 등
출력을 어디로 보낼지: HTTP response, stdout, debugger 등
$_SERVER, php://input, header 처리 방식을 어떻게 구성할지
프로세스 수명이 요청 단위인지, 명령 단위인지, 장기 상주인지

그래서 Laravel 코드가 같아도 실행 컨텍스트는 달라진다.

웹 요청             → FPM/FastCGI SAPI
php artisan 명령     → CLI SAPI
php artisan serve    → built-in web server / cli-server SAPI
테스트 커버리지      → phpdbg SAPI

2. CGI

CGI(Common Gateway Interface)는 웹 서버가 외부 프로그램을 실행해 동적 응답을 만드는 오래된 인터페이스다.

Browser
→ Web Server
→ 요청마다 php-cgi 프로세스 실행
→ PHP script 실행
→ 응답 반환
→ 프로세스 종료

CGI의 핵심 특징은 요청마다 외부 프로그램 프로세스를 새로 만든다는 점이다. 웹 서버는 요청 정보를 환경변수와 표준 입력으로 넘기고, 외부 프로그램은 표준 출력으로 HTTP 헤더와 본문을 돌려준다.

구조는 단순하지만 비용이 크다.

요청마다 프로세스 생성 비용이 든다.
Laravel 같은 프레임워크는 매 요청마다 부트스트랩 비용이 크다.
트래픽이 늘면 프로세스 생성/종료 자체가 병목이 된다.

그래서 현대 PHP 운영 환경에서 CGI를 직접 쓰는 경우는 드물다.

3. FastCGI

FastCGI는 CGI의 가장 큰 문제였던 요청마다 프로세스를 새로 만드는 비용을 줄이기 위해 나온 별도 인터페이스/프로토콜이다.

Browser
→ Nginx / Apache
→ FastCGI protocol
→ 이미 떠 있는 PHP 프로세스
→ PHP script 실행
→ 응답 반환

CGI와 달리 PHP 프로세스를 미리 띄워두고 재사용한다. 웹 서버는 매 요청마다 새 프로세스를 실행하지 않고, 이미 살아 있는 FastCGI 프로세스에 요청을 전달한다.

다만 FastCGI 자체는 “요청 전달 방식”에 가깝다. 운영에서는 프로세스 수 조절, 죽은 프로세스 재시작, graceful reload, slow log, max requests 같은 관리 기능이 필요하다. PHP에서 이 역할을 맡는 대표 구현이 PHP-FPM이다.

4. FPM

FPM(FastCGI Process Manager)은 PHP용 FastCGI 프로세스 매니저다. 웹 서버가 직접 PHP 코드를 실행하는 것이 아니라, FPM worker에게 FastCGI 요청을 넘긴다.

Browser
→ Nginx
→ FastCGI
→ php-fpm master
→ php-fpm worker
→ Laravel public/index.php
→ 응답 반환

FPM의 역할은 PHP worker pool을 운영하는 것이다.

worker 프로세스를 미리 띄워둔다.
요청이 들어오면 놀고 있는 worker에게 배정한다.
worker 수를 pm.max_children 등으로 제한한다.
느린 요청, timeout, 재시작, 로그 등을 관리한다.
요청이 끝나면 worker는 다음 요청을 받을 수 있다.

중요한 점은 FPM worker 하나가 한 번에 요청 하나를 처리한다는 것이다. 응답이 끝나기 전까지 그 worker는 다른 요청을 받을 수 없다. 그래서 오래 걸리는 작업을 웹 요청 안에서 처리하면 worker가 묶이고, worker pool이 고갈될 수 있다.

큐를 쓰는 이유도 여기에 있다. 요청에 꼭 필요한 작업만 FPM worker가 처리하고, 메일 발송·파일 변환·외부 API 처리 같은 무거운 작업은 CLI worker로 넘긴다.

5. CLI

CLI(Command Line Interface)는 터미널, cron, Supervisor, systemd 등에서 php 실행 파일을 직접 실행하는 방식이다.

php artisan queue:work
php artisan migrate
php script.php

구조는 FPM과 다르다.

Shell / cron / Supervisor
→ php CLI 바이너리
→ artisan 또는 PHP script 실행
→ 종료

또는 queue:work처럼 장기 실행될 수도 있다.

Supervisor
→ php artisan queue:work
→ Laravel 부트스트랩
→ Job 처리 루프
→ 여러 Job 처리 후 재시작

CLI 프로세스는 FPM worker를 사용하지 않는다. php artisan queue:work, php artisan schedule:run, php artisan migrate는 모두 FPM pool과 별개의 PHP 프로세스다.

따라서 FPM의 웹 timeout에는 묶이지 않지만, 대신 장기 프로세스 특유의 문제가 생긴다.

메모리 누수가 누적될 수 있다.
싱글톤, static 상태가 Job 사이에 남을 수 있다.
코드 배포 후 재시작이 필요하다.
--max-time, --max-jobs, --memory 같은 제한으로 주기적 재활용이 필요하다.

6. CLI server

CLI server는 PHP가 제공하는 개발용 built-in web server다. Laravel의 php artisan serve는 내부적으로 이 서버를 실행한다.

php artisan serve

실제로는 대략 이런 형태다.

php -S 127.0.0.1:8000 server.php

구조는 CGI도 FPM도 아니다.

Browser
→ php -S 프로세스
→ PHP built-in web server
→ Laravel public/index.php
→ 응답 반환

CGI처럼 요청마다 php-cgi 프로세스를 새로 띄우지 않는다. FPM처럼 Nginx가 FastCGI로 worker pool에 요청을 넘기는 구조도 아니다. PHP 프로세스 자체가 간단한 HTTP 서버 역할을 한다.

운영용으로 적합하지 않은 이유는 운영 서버로써 필요한 기능이 부족하기 때문이다.

기본적으로 개발 편의성에 초점을 둔 서버다.
정교한 worker/process 관리가 없다.
Nginx/Apache 수준의 정적 파일 처리, buffering, reverse proxy, TLS 운영 기능이 없다.
장애 복구, 튜닝, 관측성이 제한적이다.
일반적인 운영 트래픽을 전제로 설계되지 않았다.

OPcache 같은 opcode cache는 설정에 따라 CLI server에서도 사용할 수 있다. 다만 개발 서버에서는 코드 변경이 즉시 반영되는 편이 중요하고, 운영 수준의 캐시·프로세스 관리까지 붙일 바에는 Nginx + FPM 구조를 쓰는 것이 맞다.

그래서 php artisan serve는 로컬 개발용으로 보는 것이 정확하다.

7. 정리

같은 Laravel 애플리케이션도 실행 주체에 따라 성격이 완전히 달라진다.

실행 방식	대표 명령/구조	용도	특징
CGI	Web Server → `php-cgi`	과거 방식	요청마다 프로세스 생성
FastCGI	Web Server → FastCGI process	요청 전달 방식	프로세스 재사용
FPM	Nginx → PHP-FPM worker	운영 웹 요청	PHP FastCGI worker pool 관리
CLI	`php artisan ...`	명령어, 큐, 스케줄	FPM과 독립된 PHP 프로세스
CLI server	`php -S`, `php artisan serve`	로컬 개발 서버	CGI/FPM이 아닌 PHP 내장 HTTP 서버

운영 Laravel 기준으로 가장 중요한 구분은 이것이다.

사용자 웹 요청       → PHP-FPM worker
큐/스케줄/명령어     → PHP CLI process
로컬 개발 서버       → PHP built-in server

php artisan serve는 CGI가 아니라 built-in server를 사용한다.
php artisan queue:work 같은 CLI 명령은 FPM worker를 사용하지 않는다.
FPM은 웹 요청을 처리하기 위한 PHP FastCGI worker pool이고, CLI는 터미널이나 프로세스 매니저가 PHP 바이너리를 직접 실행하는 별도 실행 경로다.

8. 참고자료

SAPI / PHP_SAPI
- PHP 공식 문서: php_sapi_name()
  현재 PHP가 사용하는 Server API, 즉 SAPI 이름을 반환한다. 예시 값으로 cli, cli-server, fpm-fcgi, cgi-fcgi, apache2handler, phpdbg, embed 등이 제시되어 있다.
- PHP 공식 문서: PHP_SAPI 상수
  현재 PHP 빌드의 Server API를 나타내는 상수.
CLI
- PHP 공식 문서: Using PHP from the command line
  CLI SAPI의 목적은 PHP로 shell application을 개발/실행하는 것이며, CLI와 CGI는 서로 다른 SAPI라고 설명한다.
- PHP 공식 문서: Command line options
  php -f, php -r, php -S 등 CLI 옵션 설명. -S <addr>:<port>가 built-in web server 실행 옵션이다.
CGI
- RFC 3875: The Common Gateway Interface CGI Version 1.1
  CGI를 HTTP 서버 아래에서 외부 프로그램을 실행하기 위한 인터페이스로 정의한다.
- PHP 공식 문서: CGI and command line setups
  PHP가 기본적으로 CLI와 CGI 프로그램으로 빌드될 수 있고, CGI processing에 사용될 수 있음을 설명한다.
- PHP 공식 문서: Installed as CGI binary
  CGI 방식으로 PHP를 설치했을 때의 보안 고려사항.
FastCGI
- FastCGI 원문 스펙: FastCGI Specification
  FastCGI를 CGI의 open extension으로 설명하고, CGI와 달리 long-lived application process를 지원한다고 설명한다.
- Nginx 공식 문서: ngx_http_fastcgi_module
  Nginx가 FastCGI server로 요청을 전달하는 fastcgi_pass, fastcgi_param, fastcgi_read_timeout 등을 설명한다.
PHP-FPM
- PHP 공식 문서: FastCGI Process Manager FPM
  FPM은 PHP의 주요 FastCGI 구현이며, heavy-loaded sites에 유용한 advanced process management, worker pool, slowlog, dynamic/ondemand/static child spawning 등을 제공한다고 설명한다.
- PHP 공식 문서: fastcgi_finish_request()
  응답을 flush한 뒤에도 시간이 오래 걸리는 작업을 계속할 수 있는 FPM 관련 함수. 단, 워커 점유 관점에서는 주의가 필요하다.
Apache module / mod_php
- PHP 공식 문서: Apache 2.x on Unix systems
  --with-apxs2, LoadModule php_module modules/libphp.so, SetHandler application/x-httpd-php 등을 통해 PHP를 Apache SAPI module로 붙이는 방식을 설명한다.
- PHP 공식 문서: Installed as an Apache module
  PHP가 Apache 모듈로 실행될 때 Apache 사용자 권한을 상속한다는 점을 설명한다.
Built-in web server / CLI server
- PHP 공식 문서: Built-in web server
  CLI SAPI가 built-in web server를 제공하며, php -S localhost:8000으로 실행한다. 개발/테스트용이며 public network에서 쓰지 말라고 명시한다. 기본적으로 single-threaded process라는 설명도 있다.
- Laravel 공식 소스: ServeCommand.php
  serve 명령의 설명은 “Serve the application on the PHP development server”이고, 실제 serverCommand()가 php_binary(), -S, host:port, router script를 반환한다. 즉 php artisan serve는 PHP built-in server 래퍼다.
- PHP 공식 문서: OPcache runtime configuration
  opcache.enable_cli가 CLI 버전의 PHP에서 opcode cache를 켤 수 있는 설정임을 설명한다. 따라서 “CLI server는 캐시가 절대 없다”보다는 “기본/일반 개발 설정에서는 운영용 캐시·프로세스 관리 구조가 아니다”가 정확하다.
phpdbg
- PHP 공식 문서: Interactive PHP Debugger
  phpdbg는 SAPI module로 구현된 PHP 디버깅 플랫폼이며 step debugging, breakpoint, opcode 출력 등을 제공한다.

기타 - 아키텍처의 종류

Aleph Kim — Thu, 23 Apr 2026 14:11:22 +0900

1. 엔터프라이즈 아키텍처 (Enterprise Architecture, EA)

범위: 조직 전체 (기업 수준)
목적: 비즈니스 목표와 IT 전략의 일치
설명: 회사의 비즈니스 프로세스, 데이터, 애플리케이션, 기술 인프라가 전체적으로 어떻게 맞물려 돌아가는지 정의하는 가장 거시적인 설계
참고 자료: https://www.gartner.com/reviews/market/enterprise-architecture-tools

2. 솔루션 아키텍처 (Solution Architecture, SA)

범위: 특정 프로젝트 또는 서비스
목적: 비즈니스 요구사항을 기술적 해결책으로 변환
설명: 특정 문제를 해결하기 위해 필요한 소프트웨어, 인프라, 보안, 데이터 관리 등을 어떻게 통합하여 하나의 완성된 시스템(솔루션)을 만들지 설계
참고 자료: https://learn.microsoft.com/en-us/dynamics365/guidance/implementation-guide/solution-architecture-design-pillars

3. 소프트웨어 아키텍처 (Software Architecture)

범위: 애플리케이션 내부 (코드 및 모듈)
목적: 코드의 유지보수성, 확장성, 재사용성 확보
설명: 소프트웨어 구성 요소 간의 관계와 규칙을 정의합니다.
주요 패턴: 레이어드(Layered), 마이크로서비스(MSA), 클린 아키텍처, 이벤트 기반 아키텍처 등
참고 자료: https://martinfowler.com/architecture/

4. 인프라 아키텍처 (Infrastructure Architecture)

범위: 물리적/논리적 하드웨어 환경
목적: 시스템의 안정성, 성능, 가용성 보장
설명: 서버, 네트워크(VPC, Subnet), 스토리지, 로드밸런서, CDN(CloudFront) 등 코드가 구동되는 환경의 물리적/가상적 배치를 설계
참고 자료: https://aws.amazon.com/what-is/iac/ - 코드형 인프라는 어떻게 작동하나요? 섹션

5. 데이터 아키텍처 (Data Architecture, DA)

범위: 데이터 자산 전반
목적: 데이터의 무결성, 보안, 효율적 활용
설명: 데이터베이스(MariaDB 등)의 스키마 설계부터 데이터의 생성, 저장, 처리, 통합, 분배에 이르는 생애주기 규칙을 수립
참고 자료: https://www.ibm.com/kr-ko/think/topics/data-architecture

6. 보안 아키텍처 (Security Architecture)

범위: 시스템 전체의 보호 계층
목적: 자산 보호 및 위험 관리
설명: 인증, 인가, 데이터 암호화, 네트워크 방화벽 등 시스템 전반에 걸쳐 위협으로부터 보호하기 위한 보안 통제 구조를 설계
참고 자료: https://www.ibm.com/docs/en/apptio-gov/tbm-studio/saas?topic=model-security-architecture-overview

요약 비교

종류	핵심 질문	대상
엔터프라이즈 아키텍처	회사가 어떻게 IT를 활용하는가?	비즈니스 + IT 전체
솔루션 아키텍처	이 프로젝트를 어떻게 완성하는가?	서비스 전체 기술 스택
소프트웨어 아키텍처	코드를 어떻게 구조화하는가?	애플리케이션 로직
인프라 아키텍처	서버와 네트워크를 어떻게 배치하는가?	컴퓨팅 자원 환경
데이터 아키텍처	데이터를 어떻게 관리하는가?	DB 및 데이터 흐름
보안 아키텍처	어떻게 시스템을 방어하는가?	전 영역 보안 계층

Laravel - Unable to connect with STARTTLS: stream_socket_enable_crypto(): SSL operation failed with code 1. OpenSSL Error messages: error:0A000086:SSL routines::certificate verify failed 에러 해결

Aleph Kim — Thu, 5 Feb 2026 13:56:10 +0900

문제 상황

Laravel에서 SMTP로 메일 발송 시 다음 오류가 발생했다.

Unable to connect with STARTTLS: stream_socket_enable_crypto(): SSL operation failed with code 1. 
OpenSSL Error messages: error:0A000086:SSL routines::certificate verify failed

원인 분석

먼저 메일 서버 인증서 상태를 확인했다.

openssl s_client -starttls smtp -connect office.example.co.kr:25 -servername office.example.co.kr 2>&1 | grep -E "(Verify return code|verify error)"

결과:

verify error:num=66:EE certificate key too weak
Verify return code: 66 (EE certificate key too weak)

원인: 메일 서버 SSL 인증서가 1024-bit 이하 RSA 키로 발급되어 있었다.

OpenSSL 3.0부터 보안 정책이 강화되어 2048-bit 미만 키를 가진 인증서는 기본적으로 거부한다. PHP 8.1+가 OpenSSL 3.0을 사용하면서 이 정책이 적용된 것이다.

해결

config/mail.php에서 인증서 검증 비활성화:

'smtp' => [
    'transport' => 'smtp',
    'url' => env('MAIL_URL'),
    'host' => env('MAIL_HOST', 'smtp.mailgun.org'),
    'port' => env('MAIL_PORT', 587),
    'encryption' => env('MAIL_ENCRYPTION', 'tls'),
    'username' => env('MAIL_USERNAME'),
    'password' => env('MAIL_PASSWORD'),
    'verify_peer' => false # 추가
],

php artisan config:clear

verify_peer 옵션이란?

SSL/TLS 연결 시 상대방 인증서의 유효성을 검증할지 여부다.

true (기본값): 인증서 체인, 만료일, 키 강도 등 검증
false: 검증 없이 암호화 연결만 수립

false로 설정해도 통신 암호화는 유지된다. 단지 상대방 서버가 진짜인지 확인을 안 할 뿐이다.

보안 고려사항

verify_peer => false의 위험은 MITM(중간자 공격)인데, 이 공격이 성립하려면:

공격자가 DNS를 조작하거나
네트워크 경로를 장악해야 한다

DNS 권한이 본인에게 있고, 서버 인프라를 신뢰할 수 있는 환경이라면 실질적 위험은 낮다.

근본적 해결책

메일 서버 관리자에게 2048-bit 이상 RSA 키로 인증서 재발급을 요청하는 것이 올바른 해결책이다.

Linux - nmap 포트 스캔

Aleph Kim — Thu, 22 Jan 2026 12:00:01 +0900

기본 명령어

# 특정 호스트의 주요 포트 스캔 (1000개 포트)
nmap 192.168.1.1

# 특정 포트만 스캔
nmap -p 80,443,3306 192.168.1.1

# 포트 범위 스캔
nmap -p 1-65535 192.168.1.1

# 서비스 버전 확인
nmap -sV -p 80,443 192.168.1.1

옵션 설명

# === 포트 지정 ===
-p 80              
# 80번 포트만 검사 (nginx/apache 확인할 때)

-p 80,443,3306     
# 여러 포트 동시 검사 (웹+DB 서버 확인)

-p 1-1000          
# 1번부터 1000번까지 순서대로 검사

-p-                
# 1~65535번 전부 검사 (시간 오래 걸림)

-p U:53,T:80       
# UDP 53번(DNS), TCP 80번(HTTP) 검사


# === 스캔 속도 ===
-F                 
# 자주 쓰는 100개 포트만 검사 (30초 안에 끝남)

--top-ports 20     
# 가장 많이 쓰는 상위 20개 포트만 검사


# === 스캔 방식 ===
-sS                
# SYN 스캔 - 연결 안하고 포트만 확인 (빠르고 로그 안남음, sudo 필요)

-sT                
# TCP 연결 스캔 - 실제로 연결해서 확인 (권한 없을 때, 느림)

-sU                
# UDP 포트 검사 (DNS 53번 같은거, 매우 느림)

-sV                
# 포트가 열려있으면 어떤 프로그램인지까지 확인
# 예: 80번 포트 → nginx 1.18.0


# === 호스트 확인 ===
-Pn                
# "서버 살아있나?" 체크 건너뛰기
# 방화벽이 ping 막아놨을 때 필수

-n                 
# IP를 도메인으로 바꾸는 작업 안함 (2~3배 빠름)


# === 결과 보기 ===
-v                 
# 검사하면서 중간 결과 계속 보여줌

-oN result.txt     
# 결과를 텍스트 파일로 저장


# === 속도 조절 ===
-T0               # 매우 느림 (탐지 회피용)
-T3               # 보통 속도 (기본값)
-T4               # 빠름 (실무에서 가장 많이 씀)
-T5               # 매우 빠름 (결과 부정확할 수 있음)

Database - mariadb, mysql dump(로컬, 원격, docker)

Aleph Kim — Sat, 17 Jan 2026 09:18:27 +0900

개요

서버 작업을 하다 보면 DB 덤프를 떠야 하는 상황이 자주 생긴다.
로컬 서버, 원격 서버, 도커 컨테이너 등 환경에 따라 명령어가 달라서 헷갈릴 때가 많아 환경별 덤프 명령어를 정리해보았다.

1. 로컬 MariaDB 서버에서 DB 덤프

기본 명령어

mariadb-dump -u root -p database_name > backup.sql

사용 예시

# 특정 데이터베이스 덤프
mariadb-dump -u root -p my_laravel_db > ~/Desktop/laravel_backup_20250117.sql

# 모든 데이터베이스 덤프
mariadb-dump -u root -p --all-databases > ~/Desktop/all_databases.sql

# 특정 테이블만 덤프
mariadb-dump -u root -p my_laravel_db users posts > ~/Desktop/users_posts.sql

주요 옵션

mariadb-dump -u root -p \
  --single-transaction \     # InnoDB 일관성 보장
  --routines \               # 저장 프로시저 포함
  --triggers \               # 트리거 포함
  --events \                 # 이벤트 포함
  database_name > backup.sql

2. 원격 MariaDB 서버에서 로컬로 DB 덤프

기본 명령어

ssh user@remote_host "mariadb-dump -u username -p database_name" > local_backup.sql

사용 예시

# IP 주소로 접속
ssh ubuntu@192.168.1.100 "mariadb-dump -u root -p my_laravel_db" > ~/Desktop/remote_backup.sql

주의사항

사용 시 ssh 명령어 부분은 각자 원격 서버 환경에 따라 수정을 해야한다(-p, -i 옵션 추가 등)

3. 원격 MariaDB 도커 컨테이너에서 로컬로 DB 덤프

기본 명령어

ssh user@server "docker exec -i container_name mariadb-dump -u root -p database_name" > local_dump.sql

사용 예시

# 비밀번호 입력 방식
ssh ubuntu@123.45.67.89 "docker exec -i mariadb mariadb-dump -u root -p production_db" > ~/Desktop/prod_dump.sql
# 실행 시 비밀번호 입력 프롬프트가 나타남

4. mariadb-dump vs mysqldump

MariaDB 10.5부터 변경됨

MariaDB 10.5 이상에서는 mariadb-dump가 공식 명령어다. mysqldump는 심볼릭 링크로 남아있지만 쥐도 새도 모르게 제거될 수 있다.

# 기존 방식 (비권장)
mysqldump -u root -p database_name > backup.sql

# 권장 방식 (MariaDB 10.5+)
mariadb-dump -u root -p database_name > backup.sql

명령어 확인

# MariaDB 버전 확인
mariadb --version
# mariadb from 11.8.2-MariaDB

# mariadb-dump 존재 확인
which mariadb-dump
# /usr/bin/mariadb-dump

핵심 포인트

반드시 체크할 사항

도커 컨테이너: docker exec -i 사용 (-it 아님)
파일 크기: 대용량 DB는 gzip으로 압축 권장

압축과 함께 사용

# 덤프와 동시에 압축
mariadb-dump -u root -p database_name | gzip > backup.sql.gz

# 원격 도커에서 압축
ssh ubuntu@server "docker exec -i mariadb mariadb-dump -u root -p db_name | gzip" > dump.sql.gz

MySQL 사용 시

MySQL을 사용하는 경우 mysqldump 명령어를 사용한다. 사용법은 동일하다.

# 로컬 MySQL 덤프
mysqldump -u root -p database_name > backup.sql

# 원격 MySQL 서버에서 덤프
ssh user@server "mysqldump -u root -p database_name" > local_dump.sql

# 원격 MySQL 도커 컨테이너에서 덤프
ssh ubuntu@server "docker exec -i mysql_container mysqldump -u root -p database_name" > local_dump.sql

Docker - Ubuntu 서버에 docker, docker compose 설치하기

Aleph Kim — Thu, 15 Jan 2026 11:39:17 +0900

Docker 설치

# 필수 패키지 설치
sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates curl software-properties-common

# Docker GPG key 추가
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Docker 저장소 추가
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Docker 설치
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

# Docker 서비스 시작 및 자동 시작 설정
sudo systemctl start docker
sudo systemctl enable docker

# 설치 확인
docker -v

Docker Compose 설치

# Docker Compose 다운로드 및 설치
sudo curl -L "https://github.com/docker/compose/releases/download/$(curl -s https://api.github.com/repos/docker/compose/releases/latest | grep -Po '"tag_name": "\K.*?(?=")')/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# 실행 권한 추가
sudo chmod +x /usr/local/bin/docker-compose

# 설치 확인
docker-compose --version

unable to get image '이미지': permission denied while trying to ~~ 에러 발생 시

# 1. 현재 사용자를 docker 그룹에 추가
sudo usermod -aG docker $USER

# 2. 재로그인
exit

# 3. SSH 다시 접속

# 4. 확인
docker ps

Js - 국내 전화번호 정규식

Aleph Kim — Tue, 6 Jan 2026 10:52:45 +0900

2021. 12. 07 기준 전기통신번호관리세칙 기반 국내 전화번호 형식 종류

구분	번호	형식	세칙 근거	설명
시내전화	02	02-XXX(X)-XXXX	제7조③, 별표1	서울
	031	031-XXX(X)-XXXX	제7조③, 별표1	경기
	032	032-XXX(X)-XXXX	제7조③, 별표1	인천
	033	033-XXX(X)-XXXX	제7조③, 별표1	강원
	041	041-XXX(X)-XXXX	제7조③, 별표1	충남
	042	042-XXX(X)-XXXX	제7조③, 별표1	대전
	043	043-XXX(X)-XXXX	제7조③, 별표1	충북
	044	044-XXX(X)-XXXX	제7조③, 별표1	세종
	051	051-XXX(X)-XXXX	제7조③, 별표1	부산
	052	052-XXX(X)-XXXX	제7조③, 별표1	울산
	053	053-XXX(X)-XXXX	제7조③, 별표1	대구
	054	054-XXX(X)-XXXX	제7조③, 별표1	경북
	055	055-XXX(X)-XXXX	제7조③, 별표1	경남
	061	061-XXX(X)-XXXX	제7조③, 별표1	전남
	062	062-XXX(X)-XXXX	제7조③, 별표1	광주
	063	063-XXX(X)-XXXX	제7조③, 별표1	전북
	064	064-XXX(X)-XXXX	제7조③, 별표1	제주
이동전화	010	010-XXXX-XXXX	제8조③ 3호 나,다	2007.9.1 이후 통합번호 (셀룰러/PCS/IMT)
	011	011-XXX(X)-XXXX	제8조③ 3가호	2007.9.1 이전 셀룰러/PCS
	016	016-XXX(X)-XXXX	제8조③ 3가호	2007.9.1 이전 셀룰러/PCS
	017	017-XXX(X)-XXXX	제8조③ 3가호	2007.9.1 이전 셀룰러/PCS
	018	018-XXX(X)-XXXX	제8조③ 3가호	2007.9.1 이전 셀룰러/PCS
	019	019-XXX(X)-XXXX	제8조③ 3가호	2007.9.1 이전 셀룰러/PCS
인터넷전화	070	070-XXXX-XXXX	제8조③ 8호	인터넷전화서비스 (VoIP)
특수목적	012	012-XXXX-XXXX	제8조③ 9호	사물지능통신(IoT)
	013X	013X-XXX-XXXX	제8조③ 6가호	선박무선/주파수공용/무선데이터/5G특화망
	0135	0135-XXX-XXXX	제8조③ 6나호	통합공공망 (재난안전/철도/해상무선)
	014XY	014XY-XXX-XXXX	제8조③ 7호	부가통신역무 제공사업자
	015	015-XXX-XXXX	제8조③ 5호	무선호출(페이저)
	0100	0100-XXX-XXXX	제8조③ 4호	위성휴대통신
공통서비스	030	030-XXX(X)-XXXX	제8조④ 1호	통합메시징 (음성/팩스/이메일 통합)
(0N0계열)	050	050-XXX(X)-XXXX	제8조④ 2호	개인번호서비스
	060	060-XXX-XXXX	제8조④ 3호	전화정보서비스 (유료정보)
	080	080-XXX-XXXX	제8조④ 4호	착신과금서비스 (수신자부담 프리콜)
특수번호	10Y	100~109	제11조①	전화번호안내 등 사업자 공통서비스
(1YY계열)	11Y	110~119	제11조①	공공기관 긴급신고 (112경찰, 119소방 등)
	12Y	120~129	제11조①	공공기관 민원상담 (120다산콜 등)
	13YY	1300~1399	제11조①	공공기관 재난안전/행정서비스
	14YY	14YY-XXXX-XXXX	제11조①, 제20조⑥	대표번호 (수신자부담)
	15YY	15YY-XXXX-XXXX	제11조①, 제20조⑥	대표번호 자동응답/결제호처리
	16YY	16YY-XXXX-XXXX	제11조①, 제20조⑥	대표번호
	18YY	18YY-XXXX-XXXX	제11조①, 제20조⑥	대표번호
	17YY	1700~1799	제11조①	예비
	19YY	1900~1999	제11조①	예비
사업자식별	00X	00X-국제번호	제8조③ 1가호	국제전화 (회선설비보유, X≠3,7,9)
(국제/시외)	003YY	003YY-국제번호	제8조③ 1나호	국제전화 (설비보유재판매)
	007YY	007YY-국제번호	제8조③ 1나호	국제전화 (설비보유재판매)
	08X	08X-지역번호-번호	제8조③ 2가호	시외전화 (회선설비보유, X≠5,9)
	085YY	085YY-지역번호-번호	제8조③ 2나호	시외전화 (설비보유재판매)
데이터망	4500~4509	4XXX-XXX-XXXX	제13조 1호	데이터망 (기간통신사업자)
	4800~4819	48XX-XXX-XXXX	제13조 2호	데이터망 (부가통신사업자)

전화번호 검증 정규식

// 정규식: /^(02\d{7,8}|0(31|32|33|41|42|43|44|51|52|53|54|55|61|62|63|64)\d{7,8}|01[0-1|6-9]\d{7,8}|070\d{8}|012\d{8}|0100\d{7}|013[0-46-9]\d{7}|0135\d{7}|014\d{9}|015\d{7}|030\d{7}(?!\d)|050\d{7}(?!\d)|0(60|80)\d{7}|1[0-2]\d(?!\d)|1[3-9]\d{2}(?!\d)|1[4-68]\d{6}(?!\d)|1[4-68]\d{10}|(450[0-9]|48[01]\d)\d{7})$/

// 국내 전화번호 검증
const isPhoneNumber = (phone) => /^(02\d{7,8}|0(31|32|33|41|42|43|44|51|52|53|54|55|61|62|63|64)\d{7,8}|01[0-1|6-9]\d{7,8}|070\d{8}|012\d{8}|0100\d{7}|013[0-46-9]\d{7}|0135\d{7}|014\d{9}|015\d{7}|030\d{7}(?!\d)|050\d{7}(?!\d)|0(60|80)\d{7}|1[0-2]\d(?!\d)|1[3-9]\d{2}(?!\d)|1[4-68]\d{6}(?!\d)|1[4-68]\d{10}|(450[0-9]|48[01]\d)\d{7})$/.test(String(phone).replace(/[\s\-().]/g, ''));

// 사용 예시
console.log(isPhoneNumber('01012345678'));  // true
console.log(isPhoneNumber('02-123-4567'));    // true
console.log(isPhoneNumber('070-1234-5678'));  // true
console.log(isPhoneNumber('112'));            // true
console.log(isPhoneNumber('099-1234-5678'));  // false
console.log(isPhoneNumber('1234'));           // false

전기통신번호관리세칙 출처

국가법령정보센터 - https://www.law.go.kr/LSW/admRulLsInfoP.do?admRulId=35486&efYd=0

DB - ACID

Aleph Kim — Wed, 10 Dec 2025 09:54:11 +0900

ACID란?

ACID는 데이터베이스 트랜잭션이 안전하게 처리되기 위해 반드시 지켜야 하는 4가지 속성이다.

Atomicity (원자성)

트랜잭션 내 모든 작업이 완전히 성공하거나 완전히 실패해야 한다.

예시: 계좌이체 시 A계좌 출금과 B계좌 입금이 모두 성공하거나 모두 취소된다. 출금만 되고 입금 실패는 불가능하다.

Consistency (일관성)

트랜잭션 전후로 데이터베이스가 일관된 상태를 유지해야 한다.

예시: 쇼핑몰에서 주문 시 "재고수량 ≥ 주문수량" 규칙이 있다면, 재고 10개인 상품을 15개 주문하려고 하면 트랜잭션 자체가 거부된다. 트랜잭션이 완료되면 반드시 재고가 충분히 남아있는 상태가 보장된다.

Isolation (격리성)

동시 실행되는 트랜잭션들이 서로 영향 없이 독립적으로 실행되어야 한다.

예시: 콘서트 티켓 마지막 1장이 남았을 때 A와 B가 정확히 동시에 예매 버튼을 클릭했다. 격리성이 없으면 둘 다 "1장 남음"을 보고 둘 다 구매에 성공하는 문제가 발생한다. 격리성이 있으면 A의 트랜잭션이 끝날 때까지 B는 대기하고, A 구매 후 B는 "품절"을 확인한다.

Durability (지속성)

커밋된 트랜잭션은 시스템 장애 시에도 영구 보존되어야 한다.

설명: 데이터베이스는 트랜잭션 커밋 시 디스크에 즉시 기록한다(메모리가 아닌). WAL(Write-Ahead Logging)을 사용해 변경사항을 먼저 로그 파일에 저장하고, 서버가 다운되어도 로그 파일이 디스크에 남아있어서 재시작 시 복구할 수 있다. Mysql은 InnoDB 엔진이 이 기능을 기본 제공한다.

Mysql - 비관적 락(Pessimistic Lock)

Aleph Kim — Wed, 10 Dec 2025 09:47:44 +0900

개요

락(Lock)에 대해 찾아보다 Mysql이 "자동으로 비관적 락을 건다"는 말을 발견했는데 '그럼 내가 따로 코드를 짤 필요가 없는 건가?' 싶은 마음에 헷갈려서 정리해보았다.

Mysql 자동 락의 역할

Mysql(InnoDB)은 UPDATE나 DELETE 실행 시 자동으로 해당 행에 락을 건다.

예시: 동시 수정 방지

재고를 10으로 변경하는 A 요청과 20으로 변경하는 B 요청이 동시에 실행되는 상황이다.

// A 요청
UPDATE products SET stock = 10 WHERE id = 1;

// B 요청 (거의 동시)
UPDATE products SET stock = 20 WHERE id = 1;

자동 락 덕분에:

A의 UPDATE 실행 중 → B는 대기
A 완료 → B 실행
결과: stock = 20

자동 락이 없었다면 두 UPDATE가 동시에 섞여서 데이터가 깨질 수 있다.

그럼 어떤 상황에서 코드상으로 비관적 락을 걸어야 하는가?

자동 락은 쿼리 실행 순간만 보호한다. 실제 애플리케이션에서는 조회 -> 수정 순서로 진행되는데, 이 사이에 동시성 문제가 발생한다.

재고 차감 시나리오

재고 10개 있을 때, 두 명이 동시에 1개씩 주문한다.

// A 요청
$product = Product::find(1); // stock = 10 조회 (락 없음)

// B 요청 (동시에)
$product = Product::find(1); // stock = 10 조회 (락 없음)

// A 요청
$product->update(['stock' => $product->stock - 1]); // 10 - 1 = 9

// B 요청
$product->update(['stock' => $product->stock - 1]); // 10 - 1 = 9

결과: 2번 차감했지만 stock = 9, 재고 1개가 증발했다.

조회할 때는 락이 없어서 둘 다 10을 읽고, 각자 9로 업데이트해버린 것이다.

코드상으로 비관적 락 추가

조회할 때부터 락을 걸어서 다른 트랜잭션이 접근하지 못하게 막는 방법이다.

DB::transaction(function () {
    // SELECT ... FOR UPDATE로 락 걸기
    $product = Product::lockForUpdate()->find(1);

    $product->update(['stock' => $product->stock - 1]);
}); // 트랜잭션 종료 시 락 해제

동작 과정:

// A 요청
DB::transaction(function () {
    $product = Product::lockForUpdate()->find(1); // stock = 10, 락 걸림
    $product->update(['stock' => 9]);
}); // 락 해제

// B 요청 (A가 끝날 때까지 대기)
DB::transaction(function () {
    $product = Product::lockForUpdate()->find(1); // stock = 9 조회
    $product->update(['stock' => 8]);
});

결과: stock = 8

비관적 락 종류

// 배타적 락 (Exclusive Lock) - 읽기/쓰기 모두 차단
Product::lockForUpdate()->find(1);

// 공유 락 (Shared Lock) - 읽기 허용, 쓰기만 차단
Product::sharedLock()->find(1);

주의사항

데드락 위험: 여러 테이블 락 시 순서 주의
성능 저하: 대기 시간 발생

후기

일상적으로 접하는 DB에 알면 알수록 다양한 기능이 포함되어있다는 사실이 놀라웠고, 코드로 작성하는 비관적 락과의 차이점도 분명하게 정리된 것 같아 유익한 시간이 된 것 같다.

DB - 파티셔닝과 샤딩

Aleph Kim — Mon, 8 Dec 2025 17:52:57 +0900

개요

개발을 하다보면 파티셔닝과 샤딩이라는 용어를 종종 듣게 된다. 찾아보니 둘 다 데이터를 분할한다는 공통점이 있지만, 작동 방식과 목적이 완전히 다르다는 것을 알게 되었다. 이에 대한 내용과 더불어 샤딩을 구현할 때 Laravel ORM에서 어떻게 특정 샤드를 찾아가는지에 대한 내용까지 정리해보았다.

파티셔닝 (Partitioning)

하나의 데이터베이스 서버 내에서 대용량 테이블을 물리적으로 여러 조각으로 분할하는 기술

주요 특징:

단일 서버, 단일 DB 인스턴스에서 동작
쿼리 성능 향상 (필요한 파티션만 스캔)
유지보수 용이 (파티션 단위 삭제/아카이빙)

MariaDB는 RANGE, LIST, HASH, KEY 네 가지 파티셔닝을 지원한다.

-- RANGE 파티셔닝 예시
CREATE TABLE orders (
    id BIGINT,
    created_at DATETIME,
    ...
) PARTITION BY RANGE (YEAR(created_at)) (
    PARTITION p2023 VALUES LESS THAN (2024),
    PARTITION p2024 VALUES LESS THAN (2025),
    PARTITION p2025 VALUES LESS THAN (2026)
);

샤딩 (Sharding)

여러 데이터베이스 서버로 데이터를 수평 분할하는 기술

주요 특징:

다중 서버에 데이터 분산
수평 확장 가능 (Scale-out)
애플리케이션 레벨에서 라우팅 로직 필요

Laravel에서는 다중 DB 연결 설정으로 구현한다.

// config/database.php
'connections' => [
    'shard_0' => [
        'driver' => 'mysql',
        'host' => '10.0.1.1',
        'database' => 'app_shard_0',
        ...
    ],
    'shard_1' => [
        'driver' => 'mysql',
        'host' => '10.0.1.2',
        'database' => 'app_shard_1',
        ...
    ],
],

핵심 차이: 파티셔닝은 단일 서버 내 최적화, 샤딩은 다중 서버로 확장성 확보다.

ORM에서 샤딩 처리 방법

Laravel Eloquent의 on() 메서드

Laravel은 on() 메서드로 동적 연결 선택을 지원한다.

// config/database.php 설정만 되어 있으면
'connections' => [
    'shard_0' => ['driver' => 'mysql', 'host' => '10.0.1.1', ...],
    'shard_1' => ['driver' => 'mysql', 'host' => '10.0.1.2', ...],
],

// 바로 사용 가능
User::on('shard_0')->find(1);
User::on('shard_1')->where('status', 'active')->get();

핵심: ORM은 단일 연결만 처리하므로, 개발자가 연결 선택(on())을 명시해야 한다.

후기

파티셔닝과 샤딩을 막연하게만 알고 있었는데, 이번에 정리해보며 훨씬 명확히 기억할 수 있게 되었다. 특히 ORM에서 User::on('shard_0')처럼 간단하게 연결을 지정할 수 있다는 점이 놀라웠다.

Laravel - encrypt, bcrypt의 차이와 안전성

Aleph Kim — Tue, 25 Nov 2025 18:04:17 +0900

개요

Laravel에서 데이터 암호화에 사용되는 encrypt와 비밀번호 해싱에 사용되는 bcrypt의 차이점과, 각각의 salt 방식, 그리고 bcrypt가 APP_KEY 없이도 충분히 안전한 이유를 정리해보았다.

encrypt와 bcrypt의 근본적 차이

암호화 방향성

encrypt (양방향 암호화)

$encrypted = encrypt('신용카드번호');
$original = decrypt($encrypted); // 복호화 가능

용도: 나중에 원본 데이터가 필요한 경우
예시: 신용카드 번호, API 토큰, 개인정보
특징: APP_KEY를 사용하여 암호화/복호화

bcrypt (단방향 해싱)

$hashed = bcrypt('password123');
// 복호화 불가능, 검증만 가능
Hash::check('password123', $hashed); // true/false

용도: 원본을 절대 알 필요 없는 데이터
예시: 사용자 비밀번호
특징: 같은 입력값도 매번 다른 해시 생성

사용 기준

원본 데이터 필요 → encrypt() 사용
원본 데이터 불필요, 검증만 필요 → bcrypt() 사용

encrypt의 salt 방식

APP_KEY 의존성

// .env 파일
APP_KEY=base64:xvE7QxT8E9yP...

// 암호화
$encrypted = encrypt('민감한 데이터');

동작 원리:

Laravel의 APP_KEY를 암호화 키로 사용
같은 데이터도 매번 다른 암호문 생성 (내부적으로 랜덤 IV 사용)
복호화 시 동일한 APP_KEY 필요

프로젝트 간 이동 불가

// A 프로젝트 (APP_KEY: xxx)
$encrypted = encrypt('data');

// B 프로젝트 (APP_KEY: yyy)
decrypt($encrypted); // DecryptException 발생

특징:

APP_KEY가 다르면 복호화 불가능
APP_KEY 변경 시 기존 암호화 데이터 모두 무효화
단, 개발자가 구 키로 복호화 후 신 키로 재암호화 가능

bcrypt의 salt 방식

자체 salt 포함

$hash = bcrypt('password123');
// 결과: $2y$10$N9qo8uLOickgx2ZMRZoMye1234567890abcdefghijklmnopqr
// 구조: $알고리즘$cost$salt(22자)해시값(31자)

핵심 특징:

매번 랜덤 salt 자동 생성
salt가 해시 안에 포함되어 저장
APP_KEY 사용 안 함

동일한 비밀번호, 다른 해시

$hash1 = bcrypt('password123');
$hash2 = bcrypt('password123');

// $hash1 !== $hash2 (salt가 다름)
// 하지만 둘 다 검증 가능
Hash::check('password123', $hash1); // true
Hash::check('password123', $hash2); // true

프로젝트 간 이동 가능

// A 프로젝트
$hash = bcrypt('password123');

// B 프로젝트로 해시 복사
Hash::check('password123', $hash); // true
// salt가 해시에 포함되어 있어 어디서든 검증 가능

이동 가능한 이유:

salt가 해시 안에 포함됨
APP_KEY를 사용하지 않음
bcrypt 알고리즘이 표준이라 어디서든 동일하게 동작

bcrypt가 APP_KEY 없이도 안전한 이유

1. 작업 증명(Proof of Work) 방식

// bcrypt는 의도적으로 느리게 설계됨
$hash = bcrypt('password'); // 약 0.3초 소요

// 무차별 대입 공격 시
// 1억 개 시도 = 0.3초 × 100,000,000 = 347일
// 병렬 처리(100코어) = 3.47일

핵심:

각 시도마다 계산 비용 강제
하드웨어로 극복하기 어려움
GPU 가속 제한적

2. APP_KEY 추가의 실질적 이득 없음

DB만 유출된 경우:

 bcrypt 단독
 - 무차별 대입 필요 (347일)

 bcrypt + APP_KEY
 - APP_KEY 모르므로 정확한 입력 조합 불가능
 - 약간 더 안전할 수 있음

DB + .env 모두 유출된 경우:

bcrypt 단독
 - 무차별 대입 필요 (347일)

bcrypt + APP_KEY  
 - 무차별 대입 필요 (347일)
 - 보안 수준 동일

결론:

보안 향상: 매우 미미함
실무에서 .env 유출 = 서버 전체 장악 상황
이미 심각한 보안 사고이기에 bcrypt + APP_KEY로 막을 수 없음

3. 운영 리스크 vs 보안 이득

APP_KEY 변경 시 영향:

항목	encrypt 데이터	bcrypt 단독	bcrypt + APP_KEY
암호화 데이터	무효화	영향 없음	무효화
비밀번호	영향 없음	영향 없음	전체 무효화
복구 방법	재암호화 가능	불필요	전체 리셋 필요
사용자 액션	불필요	불필요	전체 리셋 필수

시나리오: APP_KEY 유출로 긴급 변경

 bcrypt 단독
 1. APP_KEY 즉시 변경
 2. 암호화 데이터만 재암호화
 3. 사용자는 계속 로그인 가능 ✓

 bcrypt + APP_KEY
 1. APP_KEY 변경 불가 (사용자 영향 고려)
 2. 또는 변경 후 전체 사용자 비밀번호 리셋
 3. 수천/수만 명 동시 로그인 불가
 4. CS 문의 폭증, 사용자 이탈

4. 보안 철학과 표준

Kerckhoffs의 원칙:

"암호 시스템의 안전성은 키의 비밀성에만 의존해야 하며, 알고리즘 자체는 공개되어도 안전해야 한다"

 bcrypt 단독
 ✓ 해시 알고리즘 공개
 ✓ 해시값 유출되어도 안전 (무차별 대입 필요)
 ✓ 단일 실패 지점 없음

 bcrypt + APP_KEY
 ✗ APP_KEY = 단일 실패 지점 생성
 ✗ 추가 의존성 = 복잡도 증가
 ✗ 실질적 보안 이득 미미

OWASP, NIST 권장사항:

비밀번호 해싱에 애플리케이션 시크릿 혼합 금지
bcrypt/argon2 자체 salt로 충분
"간단한 것이 안전하다" - 보안의 기본 원칙

5. 복구 가능성의 차이

 encrypt 데이터 (개인정보, 결제정보)
 - 양방향 암호화
 - 백업에서 복구 후 재암호화 가능
 - 개발자가 처리 가능
 - 사용자 액션 불필요

 bcrypt 비밀번호
 - 단방향 해싱
 - 백업에도 해시만 있음
 - 개발자가 복구 불가능
 - 사용자만 리셋 가능

이것이 bcrypt를 APP_KEY와 분리하는 핵심 이유:

개인정보: 개발자가 복구 가능 (시간은 걸려도)
비밀번호: 복구 불가능 (사용자만 가능)

후기

일단 첫째로 bcrypt/encrypt가 단/양방향 암호화라는걸 몰랐던 나 자신의 멍청함에 한 번 놀랐고 bcrypt로 암호화할때 app key로 추가 해싱해봤자 보안적으로 큰 이득이 없다는 사실에 또 한 번 놀랐다. 또한 app key가 유출 되어 변경할 경우 기존 암호화 데이터 복구 방안에 대한 내용은 전혀 생각치 못한 부분이라 많은 걸 배우게 된 것 같다.

Nginx - Too many open files 에러 / 1024 worker_connections are not enough 에러

Aleph Kim — Sun, 2 Nov 2025 18:40:53 +0900

개요

대용량 트래픽 테스트 중 Nginx 캐싱을 적용한 후, 추가적인 시스템 레벨 병목 현상을 발견하게 되었다. 캐시 설정만으로는 해결되지 않는 파일 디스크립터 부족과 워커 커넥션 한계 문제를 해결한 과정을 기록해보았다.

1. Too many open files 에러 해결

해결 방법

/etc/nginx/nginx.conf

다음 내용 추가:

worker_rlimit_nofile 65535;

시스템 서비스 설정

sudo systemctl edit nginx

다음 내용 추가:

[Service]
LimitNOFILE=65536

설정 후 재시작:

sudo systemctl daemon-reload
sudo systemctl restart nginx

worker_rlimit_nofile를 최대값(65535)으로 설정해도 되는 이유

Nginx 워커 프로세스별 제한: 각 워커 프로세스가 독립적으로 파일 디스크립터를 사용하므로 시스템 전체 한계와 별개
실제 사용량은 워커 커넥션에 의존: 실제 열리는 파일은 worker_connections 설정값과 동시 접속 수에 따라 결정됨
여유 확보: 캐시 파일, 로그 파일, 업스트림 연결 등을 고려하면 넉넉한 설정이 안전

2. worker_connections 부족 에러 해결

해결 방법

/etc/nginx/nginx.conf

worker_processes auto;
worker_rlimit_nofile 65535;

events {
    worker_connections 4096;
    use epoll;
    multi_accept on;
}

적정 worker_connections 설정 방법

중요: 표준 계산 공식은 존재하지 않음

실제 필요한 커넥션 수는 트래픽 패턴, keep-alive 설정, 응답 속도 등 다양한 요인에 따라 달라지므로 모니터링과 부하 테스트를 통한 점진적 조정이 필요하다.

일반적인 시작값:

소규모: 1024
중규모: 4096
대규모: 8192~16384

모니터링 기반 조정:

# 현재 활성 커넥션 수 확인
sudo netstat -an | grep :80 | wc -l

부하 테스트:

# Apache Bench 예시
ab -n 10000 -c 100 http://example.com

조정 기준:

"worker_connections are not enough" 로그 발생 → 값 증가
CPU 사용률 비정상 급증 → 커넥션 부족 가능성
정상 처리 중 → 현재 값 유지

최종 설정 예시:

worker_processes auto;  # CPU 코어 수 자동 설정
worker_rlimit_nofile 65535;

events {
    worker_connections 4096;  # 중규모 시작값
    multi_accept on;          # 동시 다중 연결 수락(메모리 사용량 증가, 처리 속도 향상)
}

주의사항:

worker_connections는 worker_rlimit_nofile보다 작아야 함
프록시 사용 시 커넥션 2배 소비 (클라이언트 ↔ Nginx ↔ 백엔드)
실제 환경에서 테스트 후 점진적으로 조정

후기

캐시 설정으로 PHP-FPM 부하를 줄였지만, Nginx 자체의 시스템 리소스 한계를 간과하면 또 다른 병목이 발생한다는 것을 배웠다. 특히 worker_connections는 이론적 공식이 없어 실제 트래픽 패턴에 맞춰 조정해야 하며, 모니터링과 부하 테스트를 통한 경험적 최적화가 필수적임을 알게 되었다.

PHP - Nginx 캐싱 설정

Aleph Kim — Sun, 2 Nov 2025 17:46:33 +0900

개요

laravel 서버의 대용량 트래픽 처리에 대해 테스트하다 PHP FPM 프로세스의 부족으로 인해 병목 현상이 발생함을 발견하게 되었고 서버 스펙을 무리하게 올리기 보다는 다른 방식으로 해결을 하는 것이 바람직하다 판단되어 Nginx 캐싱에 대해 찾아보게 되었다.

/etc/nginx/sites-available/default

# server 블록 상단에 추가
fastcgi_cache_path /dev/shm/nginx_cache
levels=1:2
keys_zone=PHPCACHE:100m
max_size=500m
inactive=60m
use_temp_path=off

fastcgi_cache_use_stale error timeout updating invalid_header http_500;
fastcgi_cache_background_update on;
fastcgi_cache_lock on;

server {

...

  location ~ \.php$ {
      set $skip_cache 1;  # 기본값: 캐시 안함

      # 예시) 메인페이지(빈 문자열 매칭), /project 페이지 캐시
      if ($request_uri ~* "^/(project|)$") {
          set $skip_cache 0;
      }

      # POST는 캐시 안함
      if ($request_method = POST) {
          set $skip_cache 1;
      }

      fastcgi_ignore_headers Cache-Control Expires Set-Cookie;
      fastcgi_cache_bypass $skip_cache;
      fastcgi_no_cache $skip_cache;

      fastcgi_cache PHPCACHE;
      fastcgi_cache_valid 200 10m;
      fastcgi_cache_key "$scheme$request_method$host$request_uri";
      add_header X-Cache-Status $upstream_cache_status always;

      fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
      fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
      include fastcgi_params;
  }

...

각 항목에 대한 설명 - server 블록 상단(전역 설정)

fastcgi_cache_path /dev/shm: 캐시 파일 저장 경로(RAM을 사용하는 경로)
levels: 해시값으로 a/bc/캐시파일 형태 생성
keys_zone: 공유 메모리 영역 이름과 크기 (1MB당 약 8,000개 키)
max_size: 최대 캐시 용량
inactive: 미사용 캐시 삭제 시간 (60분간 접근 없으면 자동 삭제, 만료된 캐시라도 추후 서버 장애등의 상황을 대비하기 위해 넉넉하게 설정)
use_temp_path: 임시 경로 사용 여부
fastcgi_cache_use_stale : 백엔드 오류 시 만료된 캐시 제공
- error: PHP-FPM 연결 실패
- timeout: 응답 지연
- updating: 캐시 갱신 중
- invalid_header: 잘못된 헤더
- http_500: 500 에러
fastcgi_cache_background_update: 활성화 시 캐시가 만료되면 백그라운드에서 갱신하고 기존 캐시 즉시 반환
fastcgi_cache_lock: 활성화 시 동일 요청이 동시 발생하면 하나만 백엔드 호출, 나머지는 대기 (Thundering herd 방지)

각 항목에 대한 설명 - server 블록 내부

fastcgi_ignore_headers: PHP 응답 헤더 무시 (Cache-Control, Expires, Set-Cookie 무시하고 Nginx가 캐시 제어)
fastcgi_cache_bypass: $skip_cache 변수가 true면 캐시 읽기 건너뛰고 백엔드 직접 호출
fastcgi_no_cache: $skip_cache 변수가 true면 응답을 캐시에 저장하지 않음
fastcgi_cache: 사용할 캐시 존 지정 (위에서 정의한 PHPCACHE 존 사용)
fastcgi_cache_valid: HTTP 200 응답을 10분간 캐시
fastcgi_cache_key: 캐시 키 생성 규칙 (스킴+메소드+호스트+URI 조합으로 고유 키 생성)
add_header X-Cache-Status: 응답 헤더에 캐시 상태 추가 (HIT/MISS/BYPASS 등 확인 가능)
- always: 모든 응답 코드에 헤더 추가
fastcgi_pass: PHP-FPM 소켓 경로 (Unix 소켓 사용)
fastcgi_param SCRIPT_FILENAME: PHP 스크립트 실제 경로 전달 ($realpath_root로 심볼릭 링크 해석)
include fastcgi_params: 표준 FastCGI 파라미터 포함

후기

사실 이전에 다니던 회사에서는 너무 다양하게 걸려있는 캐싱이 불필요하고 변동사항이 바로 확인되지 않아 혼란만 초래하니 다 없애버려야한다고 부정적으로만 생각했었는데 이제와 돌이켜보니 순간적으로 치솟는 트래픽에도 잘 버티기 위한 조치였음을 깨닫게 되었다. 물론 관리가 되지 않는 캐싱 시스템은 혼란만 초래할 수도 있지만 잘만 사용한다면 서버 리소스를 아낄 수 있는 양날의 검임을 다시 한 번 깨닫게 되었다.

Nginx - www, non-www redirect 시 도메인 검색엔진의 색인 방식

Aleph Kim — Thu, 30 Oct 2025 10:13:39 +0900

개요

Nginx에서 www 서브도메인을 메인 도메인으로 리다이렉트 설정 시, 검색엔진이 어떤 도메인을 색인하는지에 대한 내용을 정리해보았다.

검색엔진의 리다이렉트 처리

질문의 배경

Nginx에서 www.example.com을 example.com으로 301 리다이렉트 설정 시, 검색엔진(구글, 네이버)이 www 도메인을 노출할지에 대한 의문이 발생하였다.

검색엔진의 동작 방식

크롤러의 리다이렉트 추적

크롤러 접근: www.example.com
       ↓
Nginx 응답: 301 → example.com
       ↓
크롤러 인식: "example.com이 정규 URL"
       ↓
검색 결과: example.com으로 색인

핵심 사실:

검색엔진은 301 리다이렉트를 따라가며 최종 도착 URL을 정규 버전으로 인식
리다이렉트 대상(destination)이 검색 결과에 노출됨
www → non-www 리다이렉트 = non-www가 색인됨

Nginx 리다이렉트 설정

권장 설정

# www를 non-www로 리다이렉트
server {
    listen 80;
    server_name www.example.com;
    return 301 $scheme://example.com$request_uri;
}

결과:

검색 결과: example.com (www 없이)
사용자가 www로 접근해도 자동으로 non-www로 이동
모든 SEO 점수가 하나의 도메인에 집중

두 도메인 모두 노출 시도 (안티패턴)

왜 불가능하고 하면 안 되는가?

1. 검색엔진의 중복 콘텐츠 페널티

같은 내용이 2개 URL에 존재 = 검색 순위 하락
검색엔진이 임의로 하나만 선택

2. SEO 점수 분산

www로 받은 백링크와 non-www로 받은 백링크가 따로 계산
도메인 권위도(Domain Authority)가 분산되어 불리

3. 검색엔진의 강제 선택

리다이렉트 없으면 검색엔진이 마음대로 하나 선택
일관성 없는 검색 결과

올바른 방법

하나를 선택하고 나머지는 301 리다이렉트

# 옵션 1: non-www 선호 (일반적)
www.example.com → example.com

# 옵션 2: www 선호
example.com → www.example.com

추가 SEO 최적화:

Google Search Console에 대표 도메인 지정
sitemap.xml에는 선택한 버전만 포함
canonical 태그로 정규 URL 명시

핵심 포인트

반드시 이해할 사항

301 리다이렉트 = 영구 이동: "이 주소는 이제 저기로 완전히 옮겼어요"
검색엔진은 리다이렉트 대상을 색인: 출발지가 아닌 도착지 URL
하나의 정규 URL만 유지: SEO를 위한 필수 조건
리다이렉트 방향 선택: www/non-www 중 하나를 비즈니스 요구사항에 맞게 선택

실무 권장사항

대부분의 경우: non-www 사용 (간결함)
브랜드 강조 필요: www 사용 (전통적, 공식적 느낌)
일관성 유지: 한 번 선택하면 변경하지 않기

후기

도메인 정규화는 SEO의 기본이지만 간과하기 쉬운 부분이다. 처음부터 하나의 버전으로 통일하고 리다이렉트를 설정하는 것이 중요하다.

PHP -dom pdf로 html -> pdf 변환

Aleph Kim — Wed, 29 Oct 2025 13:58:57 +0900

개요

DomPDF로 PDF를 생성할 때 한글이 깨지는 문제가 발생하여 폰트 등록부터 인코딩 문제까지, 여러 시행착오를 겪어가며 해결하였다.
하지만 DomPDF로 PDF를 생성하는 방법은 font 관련 css를 넣었을때 또 깨지는 문제가 발생하고 일부 css가 먹질 않아서 폐기하게 되었다.
그리하여 결국에는 이 방식을 사용하지 않게 되었지만 그냥 갖다버리기는 아까워서 글로라도 남기려한다...

DomPDF 한글 깨짐 문제

문제의 원인

DomPDF는 기본 폰트(DejaVu Sans)에 한글 글리프가 없다. 한글을 표시하려면 한글을 지원하는 폰트를 명시적으로 등록해야 한다.

증상별 원인

? (물음표): 인코딩 문제 또는 폰트 미등록
□ (네모): 폰트에 해당 글리프 없음
깨진 문자: UTF-8 인코딩 미지정

해결 과정

1단계: 인코딩 확인

$this->dompdf->loadHtml($html, 'UTF-8'); // 명시적 인코딩 지정

2단계: 한글 지원 폰트 준비

Pretendard, Noto Sans KR, 나눔고딕 등
반드시 TTF 형식 사용 (OTF는 제한적)
폰트 파일을 public/fonts/에 배치

3단계: 폰트 수동 등록

$fontMetrics = $this->dompdf->getFontMetrics();
$fontMetrics->registerFont([
    'family' => 'Pretendard',
    'style' => 'normal',
    'weight' => 'normal'
], public_path('fonts/Pretendard.ttf'));

최종 구현 코드

PdfHelper 클래스

<?php

namespace App\Helpers;

use Dompdf\Dompdf;
use Dompdf\Options;
use Illuminate\Support\Facades\View;

class PdfHelper
{
    private Dompdf $dompdf;

    public function __construct()
    {
        $options = new Options();

        // HTML5 파서 활성화: 최신 HTML5 태그 및 속성 지원
        $options->set('isHtml5ParserEnabled', true);
        // 원격 리소스 비활성화: 외부 URL(이미지, CSS 등) 로드 차단 (보안)
        $options->set('isRemoteEnabled', false);
        // 파일 접근 루트 경로 설정: public/ 디렉토리로 제한하여 보안 강화
        $options->set('chroot', public_path());

        $this->dompdf = new Dompdf($options);

        $this->dompdf->setBasePath(public_path());

        // 폰트 수동 등록
        $fontMetrics = $this->dompdf->getFontMetrics();
        $fontMetrics->registerFont([
            'family' => 'Pretendard',
            'style' => 'normal',
            'weight' => 'normal'
        ], public_path('fonts/PretendardVariable.ttf'));
    }

    /**
     * pdf 파일을 생성하는 메서드
     * @param string $view pdf로 변환할 html 파일명
     * @param array $data html 내에 삽입할 데이터
     * @return $this pdf 객체를 render한 helper 객체
     */
    public function generate(string $view, array $data = []): self
    {
        $html = View::make($view, $data)->render();
        $this->dompdf->loadHtml($html);
        $this->dompdf->setPaper('A4', 'portrait');
        $this->dompdf->render();

        return $this;
    }

    /**
     * 생성한 pdf 파일을 로컬에 다운로드하는 메서드
     * @param string $filename 설정할 pdf 파일명
     */
    public function download(string $filename)
    {
        return response()->streamDownload(
            fn() => print($this->dompdf->output()),
            $filename,
            ['Content-Type' => 'application/pdf']
        );
    }

    /**
     * 생성한 pdf 파일을 브라우저에 뷰어로 노출하는 메서드
     * @param string $filename 설정할 pdf 파일명
     */
    public function stream(string $filename)
    {
        return response($this->dompdf->output(), 200, [
            'Content-Type' => 'application/pdf',
            'Content-Disposition' => 'inline; filename="' . $filename . '"',
        ]);
    }
}

사용 예시

// 컨트롤러에서
public function downloadPdf()
{
    $pdfHelper = new PdfHelper();

    return $pdfHelper
        ->generate('pdf.template', ['link' => 'https://example.com'])
        ->download('document.pdf');
}

HTML 템플릿

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <style>
        body {
            font-family: 'Pretendard', sans-serif;
            margin: 0;
            padding: 0;
        }
    </style>
</head>
<body>
    <h1>한글 제목</h1>
    <p>본문 내용입니다.</p>
</body>
</html>

핵심 포인트

반드시 체크할 사항

폰트 파일 형식: TTF 권장 (OTF 지원 제한적)
폰트 글리프 확인: 폰트 파일에 한글 포함 여부
인코딩 명시: loadHtml() 두 번째 인자에 'UTF-8' 지정
경로 설정: chroot와 setBasePath 설정

왜 CLI 명령어 대신 수동 등록인가?

# 이 방법은 사용하지 않음
php vendor/dompdf/dompdf/load_font.php

수동 등록의 장점:

배포 환경에서 추가 설정 불필요
코드로 관리되어 버전 관리 용이
CI/CD 파이프라인에서 별도 스크립트 실행 불필요

후기

한글이 기본적으로 지원되지 않는 부분은 이해가 되지만 css의 일부 문법이 사용할 수 없는 건 많이 아쉽다.. 추후에 꼭 DomPDF로 pdf를 생성해야만 하는 일이 생기질 않길 빌어야겠다.

PHP - aws t3 서버 사용 시 관련 스펙 정리

Aleph Kim — Wed, 29 Oct 2025 11:33:46 +0900

스펙 정리 표

aws t3 서버 스펙 공식문서

인스턴스 타입	RAM	vCPU	동시 접속	용도
t3.nano	0.5GB	2	2~5명	개발/테스트 전용
t3.micro	1GB	2	5~15명	매우 가벼운 사이트, 사내 도구
t3.small	2GB	2	20~50명	소규모 비즈니스 사이트
t3.medium	4GB	2	50~150명	중소 규모 서비스
t3.large	8GB	2	150~300명	중간 규모 서비스
t3.xlarge	16GB	4	300~600명	대규모 서비스
t3.2xlarge	32GB	8	600~1,200명	엔터프라이즈급

네트워크 성능 - 최대 5Gbps

동시 접속 가능량 계산

t3.micro (1GB RAM) 예시

OS + 기본 서비스: ~300MB
MariaDB: 200 ~ 300MB
Nginx: ~50MB
남은 여유: 350 ~ 450MB
PHP-FPM 프로세스 수: 7 ~ 15개 (프로세스당 평균 메모리 : 30 ~ 50MB)
이론적 동시 접속 가능량: 7~15명

fpm 프로세스당 메모리 사용량 계산

VIRT (Virtual): 접근 가능한 메모리 전체
RES (Resident): 실제 물리 메모리 사용량
SHR (Shared): 다른 프로세스와 공유하는 메모리

PID 135381: VIRT 245640KB, RES 79180KB, SHR 59564KB 
PID 97394: VIRT 245488KB, RES 79264KB, SHR 59720KB 
PID 135299: VIRT 245612KB, RES 79816KB, SHR 60204KB 

실제 독점 메모리 = RES - SHR 
- 135381: 79180 - 59564 = 19.6MB
- 97394: 79264 - 59720 = 19.5MB
- 135299: 79816 - 60204 = 19.6MB

마무리

서버 스펙을 어떻게 정해야할지 모르겠다면 t3.micro로 시작해서 CloudWatch로 모니터링을 하다 필요 시 스케일업하는 방식을 권장합니다.

Nginx - 리버스 프록시란?

Aleph Kim — Tue, 28 Oct 2025 14:25:33 +0900

개요

분명 이전에 공부했던 개념인 리버스 프록시에 대해 스스로 질문을 던졌더니 제대로 답변을 하지 못했다. 지금의 나보다 더 멍청할 미래의 나를 위해 정리해주도록 하자.

리버스 프록시란?

식당 비유로 이해하기

리버스 프록시는 식당에서 주문을 받는 직원과 같다.

일반적인 상황 (프록시 없음)

손님(사용자) → 직접 주방장(서버)에게 주문

리버스 프록시 사용

손님(사용자) → 직원(Nginx) → 주방장(서버)에게 전달

리버스 프록시의 주요 기능

로드 밸런싱: 트래픽이 많을 때 여러 서버로 요청 분산
보안: 실제 서버의 위치와 구조를 클라이언트로부터 숨김
캐싱: 자주 요청되는 콘텐츠를 미리 저장하여 빠른 응답 제공

실제 구조

사용자 브라우저 → Nginx → 서버(애플리케이션 레벨)

Nginx가 클라이언트의 요청을 받아 서버에 전달하고, 서버의 응답을 다시 클라이언트에게 반환한다.

프록시? 리버스 프록시?

Forward Proxy (일반 프록시)

사용자 → 프록시 → 인터넷의 여러 서버

클라이언트를 대신해서 요청을 보냄
클라이언트의 신원을 숨김
예시: VPN, 학교/회사 방화벽 우회

Reverse Proxy (리버스 프록시)

사용자 → 리버스 프록시 → 백엔드 서버

서버를 대신해서 요청을 받음
서버의 위치와 구조를 숨김
예시: Nginx, Apache, HAProxy

왜 "리버스(Reverse)"인가?

일반 프록시는 클라이언트 측에서 동작하지만, 리버스 프록시는 서버 측에서 동작하기 때문에 반대(Reverse)라는 이름이 붙었다.

간단 정리:

Forward Proxy = 나의 대리인 (내가 누군지 숨김)
Reverse Proxy = 서버의 대리인 (서버가 어디 있는지 숨김)

후기

이런 cs 지식은 까먹더라도 개발하는데에 지장이 생기지는 않지만 누군가가 물어봤을때 대답하지 못하면 쪽팔리니 꼭 기억하도록 하자.

Nginx - www 서브도메인을 non-www로 리다이렉트하기

Aleph Kim — Fri, 24 Oct 2025 16:17:21 +0900

개요

현재 단일 도메인으로 서비스를 운영하고 있는데, www.도메인으로 접속했을 때 기존 도메인으로 리다이렉트 시키고 싶었다. SEO 측면에서도 단일 도메인으로 통일하는 것이 좋고, 사용자 경험 측면에서도 일관된 URL을 제공하는 것이 중요하다고 판단했다.

설정 방법

1. DNS 레코드 추가

먼저 호스팅 사이트의 DNS 설정에서 www 서브도메인에 대한 CNAME 레코드를 추가했다.

-   레코드 타입: CNAME
-   호스트: www
-   값: 도메인. (호스팅 사이트에 따라 끝에 .을 붙이는 경우도 있다.)
-   TTL: 600 (10분)

TTL을 낮게 설정한 이유는 새로운 레코드를 추가하는 것이기 때문에 문제 발생 시 빠르게 수정할 수 있도록 하기 위함이다. 안정화된 후에는 3600(1시간) 이상으로 올려도 무방하다.

TTL(Time To Live)에 대하여

DNS 설정 시 입력하는 TTL은 DNS 레코드가 캐시에 저장되는 시간(초 단위)이다.

-   TTL 600 설정 시 → DNS 서버와 브라우저가 10분 동안 캐시 보관
-   TTL 동안은 DNS 서버에 재조회 없이 캐시된 IP 사용

TTL과 서버 부하

TTL을 낮추면 DNS 조회가 자주 발생하여 DNS 서버(도메인 등록업체의 네임서버)에 부하가 증가하지만, 실제 웹서버와는 무관하다. DNS 조회와 실제 HTTP 트래픽은 별개이기 때문이다.

DNS 전파 시간

TTL 600이라고 해서 10분 안에 무조건 전파되는 것은 아니다.

-   이미 캐시된 경우: 기존 TTL이 만료될 때까지 대기 필요
-   새 레코드인 경우: 대부분 즉시~수분 내 반영
-   ISP DNS 서버가 TTL을 무시하고 더 오래 캐시하는 경우도 있음

TTL 600이어도 완전 전파까지 30분~1시간 정도 여유를 두는 것이 안전하다.

DNS 캐시 삭제

로컬 DNS 캐시는 삭제할 수 있지만, 중간 DNS 서버(ISP, 공용 DNS 등)의 캐시는 직접 삭제할 수 없으며 TTL 만료까지 대기해야 한다.

2. DNS 전파 확인

DNS 설정 후 다음 명령어로 확인할 수 있다.

# 일반 조회
dig www.도메인

# 권한 네임서버에 직접 조회 (캐시 무시)
dig @ns.gabia.co.kr www.도메인

# 다른 공용 DNS로 조회
dig @8.8.8.8 www.도메인

처음 조회했을 때 status: NXDOMAIN 응답이 나왔는데, 이는 해당 도메인이 DNS 서버에 아직 등록되지 않았거나 전파 중임을 의미한다.

3. Nginx 리다이렉트 설정

애플리케이션 레벨에서도 처리할 수 있지만, 웹서버 레벨에서 처리하는 것이 성능상 더 효율적이다. Nginx 설정 파일에 다음과 같이 추가했다.

server {
    listen 80;
    listen 443 ssl http2;
    server_name www.도메인;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    return 301 $scheme://도메인$request_uri;
}

server {
    listen 80;
    listen 443 ssl http2;
    server_name 도메인;

    # 기존 설정...
}

설정 후 Nginx를 재시작한다.

sudo nginx -t
sudo systemctl reload nginx

4. SSL 인증서 설정

리다이렉트만 시켜줄 것이기 때문에 SSL 인증서가 필요 없을 거라고 생각했지만, 사용자가 https://www.도메인으로 접속하면 Nginx가 SSL 핸드셰이크를 먼저 처리해야 리다이렉트 응답을 보낼 수 있다. 인증서 없이는 브라우저에서 SSL 오류가 발생한다.

다행히 대부분의 SSL 인증서는 도메인과 www.도메인을 모두 커버하므로 동일한 인증서를 사용하면 된다.

후기

간단한 리다이렉트 설정이지만 그 안에는 까먹기 쉬운 개념들이 포함되어있었다. 조사를 하다보니 DNS 설정에 관해 조금 더 이해도가 높아지게 된 것 같은데 ISP DNS 서버가 TTL을 무시하고 더 오래 캐시하는 경우가 있다는 것을 알게 된 것이 큰 수확인 것 같다.

laravel - sail 컨테이너 apt-get update 지연 해결 방법

Aleph Kim — Sat, 30 Aug 2025 21:39:03 +0900

개요

laravel 프로젝트를 도커에 얹기 위해 sail로 컨테이너를 빌드하는데 apt-get update && apt-get upgrade ... 명령어에서 억겁의 시간이 걸리는 상황이 발생했다.

원인

sail로 컨테이너를 빌드할때 패키지 파일을 ports.ubuntu.com에서 받아오는데 이 서버가 영국에 있기 때문에 한국과 물리적으로 거리가 멀어 지연이 발생하는 것으로 확인되었다.

해결방법

권장되는 방법은 아닐 것 같지만~~(애초에 vendor 내의 파일을 수정하려고 하면 PhpStorm에서 안내 메시지가 나온다.)~~ vendor 디렉토리 내에 있는 기본 Dockerfile에서 저장소 서버의 url을 한국에 위치한 비공식 미러서버 url로 바꿔주는 명령어를 추가해 해결하였다.
이 방법에서 사용한 미러서버는 KAIST 학부 총학생회 산하 특별기구에서 제공하는 미러서버이다. ~~(사랑해요 카이스트)~~

추가할 명령어

RUN sed -i 's|ports.ubuntu.com|ftp.kaist.ac.kr|g' /etc/apt/sources.list.d/ubuntu.sources

Dockerfile 경로 찾기

현재 프로젝트에서 사용하는 Dockerfile의 경로는 php artisan sail:install 시 생성되는 compose.yaml파일에 명시되어있다.

vi vendor/laravel/sail/runtimes/8.5/Dockerfile

여담

추측하건데 sail의 버전에 따라 ubuntu 버전이 낮아진다면 카이스트 미러서버와는 호환이 안 되는 경우가 발생할 것 같다.

0.419 E: The repository 'http://archive/ubuntu-ports noble Release' does not have a Release file.

대충 위와 비슷한 에러가 발생할텐데 그럴 경우 구버전 ubuntu 패키지 저장소 서버를 미러링한 mirror.kakao.com나 kr.archive.ubuntu.com로 주소를 바꿔주면 해결이 될 것 같다.

기타 - 빈약한 도메인 모델(Anemic Domain Model)이란?

Aleph Kim — Fri, 25 Jul 2025 10:16:49 +0900

빈약 빈약!

빈약한 도메인 모델(Anemic Domain Model)이란?

빈약한 도메인 모델은 겉모습은 도메인 모델처럼 보이지만, 실제로는 데이터(속성)만 가지고 있고, 행동(비즈니스 로직)은 거의 없는 객체들을 말한다.
즉, 도메인 객체가 단순히 ‘데이터 보관용 그릇’ 역할만 하고, 핵심 로직은 전부 별도의 서비스 객체에 분리되어 있는 구조

왜 문제가 될까?

객체지향 설계의 기본 원칙 위반
객체지향 설계에서는 데이터와 그 데이터를 처리하는 행위(동작)를 한 객체 안에 함께 담는 것이 원칙
빈약한 도메인 모델은 이 원칙을 무시하고, 데이터를 가진 객체와 로직을 가진 서비스를 따로 분리해 놨기 때문에 사실상 절차지향 프로그래밍과 크게 다르지 않음
도메인 모델의 장점을 살리지 못함
도메인 모델을 잘 활용하면 비즈니스 로직을 객체 안에 편리하게 숨겨 복잡한 로직을 깔끔하게 관리할 수 있음
반면, 빈약한 도메인 모델은 핵심 로직을 서비스에 몰아넣기 때문에 도메인 모델의 이점이 사라짐
서비스(비즈니스 로직)와 데이터 객체가 따로 놀음
도메인 객체에는 데이터만 있고, 서비스에서 모든 로직과 데이터 변경을 담당합니다. 이러면 도메인 객체와 서비스 간의 연관성이 떨어지고, 유지보수가 어려워질 수 있습니다.

올바른 도메인 모델 설계는 어떠해야 할까?

도메인 객체에 비즈니스 로직을 담아야 한다
객체 안에 해당 도메인과 관련된 비즈니스 규칙, 검증, 계산 등 핵심 로직이 있어야 함
서비스 레이어는 얇고 단순하게 유지
서비스 레이어는 도메인 객체(도메인 모델) 사이의 작업을 조율하고, 외부와의 인터페이스 역할만 해야 함. 비즈니스 규칙은 도메인 객체가 함
계층간 역할 분리 지키기
도메인 로직은 도메인 계층에, 화면 처리나 데이터 저장 같은 기술적 관심사는 인프라스트럭처 계층에 맡김. 이 규칙을 어기면 안 됨

빈약한 도메인 모델이 흔한 이유?

많은 개발자들이 제대로 된 도메인 모델을 경험해보지 못했기 때문입니다. 특히 데이터 중심적 배경에서 온 경우 이런 설계를 쉽게 하게 됨
일부 프레임워크(예: 예전 J2EE의 Entity Beans)가 이런 패턴을 조장하기도 함
도메인 객체의 로직을 어디에 둬야 할지 혼란스러워서 결국 서비스에 몰아넣는 실수가 발생함

요약

빈약한 도메인 모델 (Anemic Domain Model)	풍부한 도메인 모델 (Rich Domain Model)
도메인 객체는 데이터(속성)만 가짐	도메인 객체가 데이터 + 비즈니스 로직을 모두 가짐
비즈니스 로직은 별도 서비스에 집중	비즈니스 로직은 도메인 객체 안에 내장됨
객체지향 설계 원칙 위반	객체지향 설계 원칙 준수
유지보수와 확장성 어려움	유지보수성과 확장성 뛰어남

PHP - Docker Prometheus Grafana 모니터링

Aleph Kim — Thu, 15 May 2025 15:35:42 +0900

제모옥은 그라파나로 하겠습니다. 근데 이제 Docker를 곁들인...

개요

php로 서비스를 운영하며 속도가 너무 느려 원인을 찾아보려 했으나 코드상에서 병목이 발생할만한 부분을 찾지 못했다.
서버 성능의 문제가 아닌가 싶었지만 원인을 분명히 하고 싶어 모니터링 시스템을 추가하게 되었고 많은 모니터링 시스템 중 Prometheus Grafana 조합을 선택하게 되었다.

왜 Prometheus + Grafana인가?

기준	Prometheus + Grafana	Zabbix	Nagios	InfluxDB + Chronograf	Datadog
데이터 수집	Pull 기반, PHP-FPM exporter로 PHP 메트릭 수집 가능, 다양한 exporter 지원	Push 기반, 에이전트 설치 필요, PHP 스크립트로 커스텀 메트릭 지원	스크립트 기반 체크, PHP 메트릭은 플러그인으로 제한적	Push 기반, Telegraf 플러그인으로 PHP 메트릭 수집 가능	에이전트 기반, PHP 통합 가능, 다양한 애플리케이션 메트릭 지원
시각화	Grafana의 강력한 대시보드, 다양한 차트와 템플릿 지원, 커뮤니티 대시보드 풍부	기본 대시보드 제공, Grafana 통합 가능하나 설정 복잡	기본 UI 제한적, 외부 도구(Grafana 등) 필요	Chronograf 제공, Grafana보다 시각화 옵션 제한적	고급 대시보드, 사용자 친화적이나 비용 발생
쿼리 기능	PromQL로 강력하고 유연한 쿼리, 복잡한 분석 가능	SQL 기반 쿼리, 복잡한 쿼리는 제한적	쿼리 기능 제한적, 스크립트에 의존	InfluxQL, PromQL보다 직관적이나 덜 유연함	자체 쿼리 언어, 유연하지만 학습 필요
확장성	Prometheus는 고가용성 설정 복잡(Thanos 등 필요), Grafana는 다중 데이터 소스 지원	대규모 환경 지원, 클러스터링 가능	소규모/정적 환경에 적합, 대규모는 복잡	고가용성 및 장기 저장 지원, 설정 간단	클라우드 기반, 높은 확장성, 관리 용이
설정 용이성	Docker로 배포 간단, PHP-FPM exporter 설정 쉬움, 초기 학습 필요	에이전트 설치 및 설정 복잡, UI 기반 설정 가능	플러그인 설치 및 구성 복잡, 수동 작업 많음	Telegraf 설정 간단, UI 기반 관리 가능	에이전트 설치 간단, 클라우드 기반으로 설정 최소화
PHP 통합	PHP-FPM exporter로 PHP 메트릭 수집 용이, 커스텀 메트릭 지원	PHP 스크립트로 커스텀 메트릭 가능, 설정 추가 필요	PHP 모니터링은 플러그인 개발 필요, 제한적	Telegraf로 PHP 메트릭 수집 가능, 추가 설정 필요	PHP-FPM 및 애플리케이션 메트릭 지원, 통합 쉬움
커뮤니티 지원	CNCF 졸업 프로젝트, 활발한 커뮤니티, 풍부한 문서 및 exporter	오픈소스, 대규모 커뮤니티, 다양한 플러그인	오래된 오픈소스, 플러그인 생태계 제한적	오픈소스, Prometheus보다 커뮤니티 작음	상용 솔루션, 커뮤니티 제한, 공식 지원 강력
비용	오픈소스, 무료, 관리형(Grafana Cloud 등)은 유료 옵션	오픈소스, 무료, 엔터프라이즈 지원 유료	오픈소스, 무료, 상용 버전(Nagios XI) 유료	오픈소스, 무료, InfluxCloud는 유료	유료, 구독 기반, 무료 티어 제한적

간단하게 요약하자면

Docker로 배포하기 쉽다.
PHP 메트릭 수집이 간단하다.
추후 진행할 mysql 모니터링 시스템도 추가하기 간단하다.
기본적인 기능이 무료이고 오픈소스다.
커뮤니티가 활발하게 운영되고 있어 자료 수집이 원활하다.
크게 위 5가지 이유로 Prometheus + Grafana를 선택하게 되었다.
~~그리고 Grafana 대시보드가 너무 예쁘다~~

디렉토리 구조

디렉토리 구조는 아래와 같다.

~
├── grafana
│    ├── prometheus.yml
│    ├── promtail-config.yml
│    └── docker-compose.yml
└── php
     └── logs

시스템 구조

모니터링 시스템 구조는 아래와 같다.

[Apache Logs] ------------> [Promtail] ----------> [Loki]
                                                      |
                                                      v
[Node Exporter] --------> [Prometheus] --------> [Grafana]
                                                      ^
                                                      |
[Apache server-status] --> [Apache Exporter] --> [Prometheus]

* 모든 서비스는 'local_net' 네트워크를 통해 연결
* 볼륨:
  - Prometheus: prometheus-data
  - Grafana: grafana-data
  - Loki: loki-data

Apache Logs: /var/log/apache2 디렉토리에서 생성된 로그를 Promtail이 읽음.
Promtail: 로그를 수집하여 Loki로 전송.
Loki: 로그를 저장하고 Grafana에서 시각화를 위해 사용
Node Exporter: 시스템 메트릭(CPU, 메모리 등)을 Prometheus로 제공
Apache Exporter: Apache 서버 상태(http://apache-server/server-status?auto)를 스크랩하여 Prometheus로 전송
Prometheus: 메트릭을 저장하고 Grafana로 데이터 제공
Grafana: Prometheus(메트릭)와 Loki(로그)를 소스로 사용하여 대시보드 제공
네트워크: 모든 서비스는 local_net 네트워크를 통해 통신
볼륨: 각 서비스의 데이터는 prometheus-data, grafana-data, loki-data에 저장

apache /server-status 설정

1. mod_status 모듈 활성화 확인

# status_module이 나타나면 활성화 되어있음
apachectl -M | grep status

# 나타나지 않으면 활성화
sudo a2enmod status

2. Apache 설정 파일 수정

# 설정 파일 열기
sudo vi /etc/apache2/conf-available/server-status.conf

<IfModule mod_status.c>
    # 자세한 상태 정보를 표시
    ExtendedStatus On
    <Location /server-status>
        # 핸들러 설정
        SetHandler server-status
    </Location>
</IfModule>

3. Apache 재시작

sudo service apache2 restart

4. 테스트

http://apache-server/server-status(본인의 아파치 서버 url)로 접속하여 페이지가 정상적으로 표시되는지 확인

모니터링 시스템 설정

1. grafana/prometheus.yml

# Prometheus 전역 설정
global:
  # 메트릭 수집 주기 설정 (15초마다 수집)
  scrape_interval: 15s

# 수집할 대상 설정
scrape_configs:
  # Node Exporter 설정 - 시스템 메트릭 수집
  - job_name: 'node'
    static_configs:
      - targets: ['grafana-node-exporter-1:9100']

  # Apache Exporter 설정 - Apache 웹서버 메트릭 수집
  - job_name: 'apache'
    static_configs:
      - targets: ['grafana-apache-exporter-1:9117']

2. grafana/promtail-config.yml

# Promtail 서버 설정
server:
  # HTTP 서버 포트 설정
  http_listen_port: 9080
  # gRPC 서버 비활성화
  grpc_listen_port: 0

# 로그 파일 위치 추적을 위한 설정
positions:
  filename: /tmp/positions.yaml

# Loki 서버 연결 설정
clients:
  - url: http://grafana-loki-1:3100/loki/api/v1/push

# 로그 수집 설정
scrape_configs:
  - job_name: system
    static_configs:
      # PHP 에러 로그 수집 설정
      - targets:
          - localhost
        labels:
          job: php-error
          __path__: /var/log/apache2/php_errors.log
      # PHP 액세스 로그 수집 설정
      - targets:
          - localhost
        labels:
          job: php-access
          __path__: /var/log/apache2/access.log
      # PHP 일반 로그 수집 설정
      - targets:
          - localhost
        labels:
          job: php-info
          __path__: /var/log/apache2/error.log

3. grafana/docker-compose.yml

# Docker Compose 버전 정의
version: '3.8'
services:
  # Prometheus: 메트릭 수집 및 저장을 위한 모니터링 시스템
  prometheus:
    image: prom/prometheus:v2.54.1
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml  # Prometheus 설정 파일
      - prometheus-data:/prometheus                      # 메트릭 데이터 저장소
    networks:
      - local_net

  # Grafana: 시각화 대시보드 도구
  grafana:
    image: grafana/grafana:11.2.0
    volumes:
      - grafana-data:/var/lib/grafana                   # Grafana 데이터 저장소
    ports:
      - "4000:3000"                                     # 외부 접속 포트:4000(기본적으로는 3000포트를 많이 사용하나, 보통 다른 서비스가 3000포트를 사용하는 경우가 많아 4000으로 설정), 내부 포트:3000
    networks:
      - local_net

  # Loki: 로그 수집 및 저장 시스템
  loki:
    image: grafana/loki:3.1.1
    volumes:
      - loki-data:/loki                                 # 로그 데이터 저장소
    networks:
      - local_net

  # Promtail: 로그 수집기
  promtail:
    image: grafana/promtail:3.1.1
    volumes:
      - ./promtail-config.yml:/etc/promtail/config.yml  # Promtail 설정 파일
      - ../php/logs:/var/log/apache2                 # Apache 로그 디렉토리
    networks:
      - local_net

  # Node Exporter: 시스템 메트릭 수집기
  node-exporter:
    image: prom/node-exporter:v1.8.2
    volumes:
      - /proc:/host/proc:ro                            # 프로세스 정보
      - /sys:/host/sys:ro                              # 시스템 정보
      - /:/rootfs:ro                                   # 루트 파일시스템
    command:
      - '--path.procfs=/host/proc'
      - '--path.sysfs=/host/sys'
      - '--path.rootfs=/rootfs'
    networks:
      - local_net

  # Apache Exporter: Apache 웹서버 메트릭 수집기
  apache-exporter:
    image: lusotycoon/apache-exporter:v1.0.9
    command:
      - --scrape_uri=http://apache-server/server-status?auto  # Apache 상태 페이지 URL
    networks:
      - local_net

# 영구 저장소 정의
volumes:
  prometheus-data:    # Prometheus 데이터 저장소
  grafana-data:       # Grafana 데이터 저장소
  loki-data:          # Loki 로그 데이터 저장소

# 네트워크 설정
networks:
  local_net:
    name: local_net

4. docker compose 실행

cd ~/grafana
docker compose up --build

5. 접속 확인

http://localhost:4000에 접속하여 그라파나에 정상적으로 접속이 가능한지 확인한다.

grafana 대시보드 설정

이제 거의 완료했다.
대시보드는 사용하는 사람이 편한 대로 설정하면 된다.
밑의 과정은 내 프로젝트에 적용한 예시이다.

1. 대시보드 로그인

초기 유저명/비밀번호는 admin/admin이다.

2. 데이터 소스 추가

로그인 후 보이는 첫 화면이다.

왼쪽 사이드바의 Connections -> data sources 탭으로 들어간다.

Add data source 버튼을 클릭한다.

Prometheus와 Loki data source를 각각 추가해야 한다.

Connection의 server URL을 http://prometheus:9090으로 지정해 주고 저장한다.

Connection의 server URL을 http://Loki:3100으로 지정해주고 저장한다.

각 데이터 소스가 추가된 것을 확인할 수 있다.

각 데이터 소스 페이지에 접속하면 url 끝에 uid가 나오는데 이를 복사해두어야 한다.

prometheus의 uid

loki의 uid

prometheus와 loki의 데이터 소스 추가가 완료되었다.

3. 대시보드 추가

왼쪽 사이드바의 Dashboards 탭으로 들어가 Create dashboard 버튼을 클릭한다.

import dashboard 버튼을 클릭한다.

아래 코드는 grafana에서 지원하는 dashboard json model이다.

아래 내용 중 datasource uid를 자신의 uid로 수정하여 Import via dashboard JSON model 입력창에 입력한다.

{
    "time": {
        "from": "now-1h",
        "to": "now"
    },
    "timezone": "browser",
    "title": "PHP Server Monitoring",
    "version": 1,
    "refresh": "5s",
    "schemaVersion": 39,
    "tags": [
        "php",
        "apache",
        "monitoring"
    ],
    "templating": {
        "list": [
            {
                "current": {
                    "text": "grafana-node-exporter-1:9100",
                    "value": "grafana-node-exporter-1:9100"
                },
                "datasource": {
                    "type": "prometheus",
                    "uid": "change me"
                },
                "name": "instance",
                "query": "label_values(node_cpu_seconds_total, instance)",
                "refresh": 1,
                "type": "query"
            }
        ]
    },
    "panels": [
        {
            "datasource": {
                "type": "prometheus",
                "uid": "change me"
            },
            "fieldConfig": {
                "defaults": {
                    "decimals": 1,
                    "mappings": [
                        {
                            "options": {
                                "match": "null",
                                "result": {
                                    "text": "N/A"
                                }
                            },
                            "type": "special"
                        }
                    ],
                    "thresholds": {
                        "mode": "absolute",
                        "steps": [
                            {
                                "color": "green",
                                "value": null
                            },
                            {
                                "color": "red",
                                "value": 80
                            }
                        ]
                    },
                    "unit": "s"
                }
            },
            "gridPos": {
                "h": 4,
                "w": 4,
                "x": 0,
                "y": 0
            },
            "options": {
                "colorMode": "none",
                "graphMode": "none",
                "reduceOptions": {
                    "calcs": [
                        "mean"
                    ]
                },
                "textMode": "auto"
            },
            "targets": [
                {
                    "datasource": {
                        "type": "prometheus",
                        "uid": "change me"
                    },
                    "expr": "apache_uptime_seconds_total",
                    "format": "time_series",
                    "refId": "A"
                }
            ],
            "title": "Uptime",
            "type": "stat"
        },
        {
            "datasource": {
                "type": "prometheus",
                "uid": "change me"
            },
            "fieldConfig": {
                "defaults": {
                    "color": {
                        "mode": "palette-classic"
                    },
                    "custom": {
                        "drawStyle": "line",
                        "fillOpacity": 100,
                        "lineWidth": 3,
                        "showPoints": "never"
                    },
                    "thresholds": {
                        "mode": "absolute",
                        "steps": [
                            {
                                "color": "green",
                                "value": null
                            },
                            {
                                "color": "red",
                                "value": 80
                            }
                        ]
                    },
                    "unit": "short"
                },
                "overrides": [
                    {
                        "matcher": {
                            "id": "byName",
                            "options": "Apache Down"
                        },
                        "properties": [
                            {
                                "id": "color",
                                "value": {
                                    "fixedColor": "#BF1B00",
                                    "mode": "fixed"
                                }
                            },
                            {
                                "id": "custom.transform",
                                "value": "negative-Y"
                            }
                        ]
                    }
                ]
            },
            "gridPos": {
                "h": 4,
                "w": 20,
                "x": 4,
                "y": 0
            },
            "options": {
                "legend": {
                    "calcs": [
                        "mean",
                        "lastNotNull",
                        "max",
                        "min"
                    ],
                    "displayMode": "table",
                    "placement": "right",
                    "showLegend": true
                }
            },
            "targets": [
                {
                    "datasource": {
                        "type": "prometheus",
                        "uid": "change me"
                    },
                    "expr": "count(apache_up == 1)",
                    "legendFormat": "Apache Up",
                    "refId": "A"
                },
                {
                    "datasource": {
                        "type": "prometheus",
                        "uid": "change me"
                    },
                    "expr": "scalar(count(apache_up == 0))",
                    "legendFormat": "Apache Down",
                    "refId": "B"
                }
            ],
            "title": "Apache Up / Down",
            "type": "timeseries"
        },
        {
            "datasource": {
                "type": "prometheus",
                "uid": "change me"
            },
            "fieldConfig": {
                "defaults": {
                    "color": {
                        "mode": "palette-classic"
                    },
                    "custom": {
                        "drawStyle": "line",
                        "fillOpacity": 10,
                        "lineWidth": 1,
                        "showPoints": "never"
                    },
                    "thresholds": {
                        "mode": "absolute",
                        "steps": [
                            {
                                "color": "green",
                                "value": null
                            },
                            {
                                "color": "red",
                                "value": 80
                            }
                        ]
                    },
                    "unit": "short"
                }
            },
            "gridPos": {
                "h": 10,
                "w": 12,
                "x": 0,
                "y": 4
            },
            "interval": "15s",
            "options": {
                "legend": {
                    "calcs": [
                        "mean",
                        "lastNotNull",
                        "max",
                        "min"
                    ],
                    "displayMode": "table",
                    "placement": "bottom",
                    "showLegend": true
                },
                "tooltip": {
                    "mode": "multi"
                }
            },
            "targets": [
                {
                    "datasource": {
                        "type": "prometheus",
                        "uid": "change me"
                    },
                    "expr": "rate(apache_accesses_total[1m])",
                    "legendFormat": "Accesses",
                    "refId": "A"
                }
            ],
            "title": "초당 평균 요청량",
            "type": "timeseries"
        },
        {
            "datasource": {
                "type": "prometheus",
                "uid": "change me"
            },
            "fieldConfig": {
                "defaults": {
                    "color": {
                        "mode": "palette-classic"
                    },
                    "custom": {
                        "drawStyle": "line",
                        "fillOpacity": 10,
                        "lineWidth": 1,
                        "showPoints": "never"
                    },
                    "thresholds": {
                        "mode": "absolute",
                        "steps": [
                            {
                                "color": "green",
                                "value": null
                            },
                            {
                                "color": "red",
                                "value": 80
                            }
                        ]
                    },
                    "unit": "deckbytes"
                }
            },
            "gridPos": {
                "h": 10,
                "w": 12,
                "x": 12,
                "y": 4
            },
            "options": {
                "legend": {
                    "calcs": [
                        "mean",
                        "lastNotNull",
                        "max",
                        "min"
                    ],
                    "displayMode": "table",
                    "placement": "bottom",
                    "showLegend": true
                },
                "tooltip": {
                    "mode": "multi"
                }
            },
            "targets": [
                {
                    "datasource": {
                        "type": "prometheus",
                        "uid": "change me"
                    },
                    "expr": "rate(apache_sent_kilobytes_total[1m])",
                    "legendFormat": "Kilobytes Sent",
                    "refId": "A"
                }
            ],
            "title": "초당 평균 전송량",
            "type": "timeseries"
        },
        {
            "datasource": {
                "type": "prometheus",
                "uid": "change me"
            },
            "fieldConfig": {
                "defaults": {
                    "color": {
                        "mode": "palette-classic"
                    },
                    "custom": {
                        "drawStyle": "line",
                        "fillOpacity": 10,
                        "lineWidth": 1,
                        "showPoints": "auto"
                    },
                    "max": 100,
                    "min": 0,
                    "thresholds": {
                        "mode": "absolute",
                        "steps": [
                            {
                                "color": "green",
                                "value": null
                            },
                            {
                                "color": "red",
                                "value": 80
                            }
                        ]
                    },
                    "unit": "percent"
                }
            },
            "gridPos": {
                "h": 8,
                "w": 12,
                "x": 0,
                "y": 14
            },
            "options": {
                "legend": {
                    "displayMode": "list",
                    "placement": "bottom",
                    "showLegend": true
                },
                "tooltip": {
                    "mode": "single"
                }
            },
            "targets": [
                {
                    "datasource": {
                        "type": "prometheus",
                        "uid": "change me"
                    },
                    "expr": "100 - (avg by(instance) (rate(node_cpu_seconds_total{mode=\"idle\",instance=\"$instance\"}[1m])) * 100)",
                    "legendFormat": "{{instance}}",
                    "refId": "A"
                }
            ],
            "title": "CPU 사용량",
            "type": "timeseries"
        },
        {
            "datasource": {
                "type": "prometheus",
                "uid": "change me"
            },
            "fieldConfig": {
                "defaults": {
                    "color": {
                        "mode": "thresholds"
                    },
                    "max": 100,
                    "min": 0,
                    "thresholds": {
                        "mode": "absolute",
                        "steps": [
                            {
                                "color": "green",
                                "value": null
                            },
                            {
                                "color": "yellow",
                                "value": 70
                            },
                            {
                                "color": "red",
                                "value": 90
                            }
                        ]
                    },
                    "unit": "percent"
                }
            },
            "gridPos": {
                "h": 8,
                "w": 12,
                "x": 12,
                "y": 14
            },
            "options": {
                "reduceOptions": {
                    "calcs": [
                        "lastNotNull"
                    ]
                },
                "showThresholdMarkers": true
            },
            "targets": [
                {
                    "datasource": {
                        "type": "prometheus",
                        "uid": "change me"
                    },
                    "expr": "(node_memory_MemTotal_bytes{instance=\"$instance\"} - node_memory_MemAvailable_bytes{instance=\"$instance\"}) / node_memory_MemTotal_bytes{instance=\"$instance\"} * 100",
                    "legendFormat": "Used Memory",
                    "refId": "A"
                }
            ],
            "title": "Memory 사용량",
            "type": "gauge"
        },
        {
            "datasource": {
                "type": "loki",
                "uid": "change me"
            },
            "gridPos": {
                "h": 8,
                "w": 24,
                "x": 0,
                "y": 30
            },
            "options": {
                "dedupStrategy": "none",
                "enableLogDetails": true,
                "showTime": true,
                "sortOrder": "Descending",
                "wrapLogMessage": true
            },
            "targets": [
                {
                    "expr": "{job=\"php-access\"}",
                    "refId": "A"
                }
            ],
            "title": "Access Logs",
            "type": "logs"
        },
        {
            "datasource": {
                "type": "loki",
                "uid": "change me"
            },
            "gridPos": {
                "h": 8,
                "w": 24,
                "x": 0,
                "y": 38
            },
            "options": {
                "dedupStrategy": "exact",
                "enableLogDetails": true,
                "showTime": true,
                "sortOrder": "Descending",
                "wrapLogMessage": true
            },
            "targets": [
                {
                    "expr": "{job=\"php-info\"}",
                    "refId": "A"
                }
            ],
            "title": "Info Logs",
            "type": "logs"
        }
    ]
}

예시

"datasource": {
    "type": "prometheus",
    "uid": "change me"
},

->

"datasource": {
    "type": "prometheus",
    "uid": "belx4b5wxrk74a"
},

대시보드의 이름을 지정해주고 Import 버튼을 클릭하여 저장한다.

대시보드 이름을 클릭하여 대시보드 페이지로 이동한다.

dashboard가 잘 추가된 것을 확인할 수 있다.

각 패널의 내용이 어떤 내용인지는 패널 제목으로 쉽게 유추가 가능하다.

Ex. 초당 평균 요청량 = 특정 시간의 15초(prometheus 설정에서 지정한 매트릭 수집 주기)동안 매 초 평균적으로 발생한 request 횟수

각 패널이 데이터를 가져오는 곳

- Uptime, Apache Up / Down, 초당 평균 요청량, 초당 평균 전송량 : Apache Exporter(prometheus)
- CPU 사용량, Memory 사용량 : Node Exporter(prometheus)
- Access Logs, Info Logs : ~/php/logs 경로에서 가져오는 apache log 파일 내용(Loki)

4. 테스트

apache 서버로 10,000번 정도 리퀘스트를 날려보면 위 이미지처럼 서버에 발생한 부하를 확인할 수 있다.

ab -n 10000 -c 100 http://apache-server/

# Ex. ab -n 10000 -c 100 http://localhost/

후기

다른 사람의 글을 여기저기 참고하고 ai의 도움도 많이 받았지만 결국 새로운 시스템에 대한 이해는 내 머릿속에서 혼자 해야 하고 이것저것 뒤져보려 하는 탐구심이 있어야 공부가 되는 것 같다. 이 모니터링 시스템에 대해 이해하기까지 너무 오랜 시간이 걸렸지만 불필요한 시간은 한순간도 없었던 것 같다.

또, 모니터링 시스템 구축뿐만 아니라 이것저것 하다 보니 처음 모니터링 시스템을 추가하려 한 때부터 이 글을 작성하기까지 너무 많은 시간이 흘렀다. 결과적으로 지식은 다양하게 늘었지만 한 가지 작업을 시작하기로 마음먹었으면 꾸준히 밀고 나가 완료시키는 끈기를 더욱 길러야 할 것 같다.

Ubuntu - 서버간 파일 전송(scp 명령어)

Aleph Kim — Mon, 12 May 2025 17:34:40 +0900

그의 이름은 linux mint입니다..

개요

여러 서버를 운영하다보면 가끔 필요해지는 서버간 파일 전송 방법에 대해 정리해보았다.
scp보다는 rsync를 사용하는게 안정적이라고는 들었으나 일단은 scp로도 충분한 것 같아 rsync는 추후에 사용하게 되면 그때 정리할 예정이다.

1. 서버 A에 SSH 접속

ssh 서버A유저@서버A의IP
# ex. ssh userA@123.123.123.123

2. SSH 키쌍 생성 (서버 A에서)

ssh-keygen -t rsa -b 4096

3. 생성된 키쌍 파일 확인

ls -al

4. pub key 내용 확인 및 복사

cat ~/.ssh/id_rsa.pub

5. 서버 B에 SSH 접속

ssh 서버B유저@서버B의IP
# ex. ssh userB@456.456.456.456

6. 서버 A의 pub key를 서버 B의 authorized_keys에 추가

echo [서버 A에서 복사한 공개키 내용] >> ~/.ssh/authorized_keys
# ex. echo ssh-rsa AAAAB3Nza...userA@123.123.123.123 >> ~/.ssh/authorized_keys

7. 서버 A에서 서버 B로 접속 테스트

ssh 서버B유저@서버B의IP
# ex. ssh userB@456.456.456.456

8. 서버 A에서 파일 전송

scp 전송할파일 서버B유저@서버B의IP:저장할경로
# ex. scp test.txt userB@456.456.456.456:/home/userB/test.txt

9. 서버 B에서 파일 확인

ls -al

폴더 전송

폴더 전체를 전송할 때는 -r 옵션을 사용한다.

scp -r 전송할폴더 서버B유저@서버B의IP:저장할경로
# ex. scp -r testFolder userB@456.456.456.456:/home/userB/testFolder

주의 사항

파일 저장 시 전송 대상 경로에 폴더가 없으면 에러 발생하므로 사전에 수동으로 생성해주어야 한다.

mkdir -p 저장할경로
# ex. mkdir -p /home/userB/testFolder

서버 B의 ~/.ssh/authorized_keys가 없을 경우

mkdir -p ~/.ssh
chmod 700 ~/.ssh
touch ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Nginx - Nginx Proxy Manager 502 bad gateway 에러 해결

Aleph Kim — Mon, 12 May 2025 14:59:37 +0900

개요

GCP 인스턴스에서 OCI 인스턴스로 서버를 이전하던 중 기존 GCP에서는 문제없이 작동하던 Docker 기반 네트워크 구조가 OCI에서는 제대로 동작하지 않았고, 그로 인해 Nginx Proxy Manager(이하 npm) 컨테이너가 다른 서비스 컨테이너와 통신을 할 수 없어 도메인을 연결할 수 없게 되었다.

이를 해결하기 위해 꽤나 많은 시간을 허비하게 되었고, 이는 그 과정을 압축한 글이다.

문제 상황

OCI로 서버를 옮긴 뒤 Docker 설정을 기존과 동일하게 구성했지만, npm이 다른 컨테이너와 통신하지 못했다.

1. GCP에서는 npm이 `172.17.0.1:[service port]`로 통신하면 정상 작동했지만 OCI에서 같은 방식으로 설정할 경우 502 bad gateway 에러 발생
2. `npm` 컨테이너 쉘에 접속해서 직접 `172.17.0.1:[service port]`로 curl 요청을 날려보았지만 실패
3. oci 서버의 Docker 버전이 gcp 서버와 차이가 있어 동일하게 맞춰봤지만 실패
4. npm을 Docker 기본 `bridge` 네트워크에 수동으로 연결해봤지만 실패
5. gcp 서버의 설정과 비교하며 모든 설정을 동일함을 확인했으나 여전히 실패

해결 방법

간단하게는 컨테이너의 내부 ip로 연결하는 방법도 있겠지만 컨테이너가 재시작될때마다 새로 설정을 해주어야 해서 실용성이 없다. 물론 컨테이너를 생성할때 ip가 고정되도록 설정할 수 있겠지만 추후에 컨테이너를 생성할때마다 옵션 명령어를 덕지덕지 붙여야해서 마음에 들지 않는다. 그래서 나는 아래 방법을 선택하게 되었다.

1. npm과 연결할 서비스 컨테이너를 같은 네트워크로 설정한다.

# network 연결 명령어(service 부분에 컨테이너명을 입력)
docker network connect nginx_default service

# network 연결 확인 명령어
docker inspect nginx_default

2. [컨테이너명]:[내부 포트]로 연결한다.

지긋지긋한 502 bad gateway 페이지가 사라졌다.

도커의 네트워크 구성에 대해 뜯어보다 알게된 사실

컨테이너명으로 DNS 접근은 기본 bridge 네트워크에서는 지원되지 않는다.
동일 네트워크 내에서는 내부 포트로 접근해야한다.

후기

아직도 왜 컨테이너 내부에서 기본 bridge 네트워크로 요청을 날릴 수 없는건지 이해가 되질 않는다.

하지만 최선의 방법을 찾아낸 것 같으니 여기까지만 하고 다른 작업을 시작해야겠다...

MAC 주소란?

Aleph Kim — Fri, 9 May 2025 15:43:25 +0900

MAC 주소란?

MAC 주소(Media Access Control Address)는 네트워크에 연결된 기기의 네트워크 인터페이스(예: Wi-Fi 칩, 이더넷 포트)에 부여된 고유한 식별자이다.
데이터 링크 계층(Layer 2)에서 로컬 네트워크(LAN) 내에서 기기를 식별하고, 데이터를 정확히 전달하는 데 사용된다.
애플의 mac과는 전혀 상관 없다. 애플에서는 혼동되지 않도록 mac 주소를 프로토콜 주소(Ex. 와이파이 주소) 같은 식으로 표기한다.

MAC 주소의 특징

형식: 48비트(6바이트) 16진수. 예: AA:BB:CC:DD:EE:FF
- 앞 24비트: OUI(제조사 고유 ID) — 예: 삼성, 애플 등
- 뒤 24비트: 제조사가 임의로 지정하는 고유 번호
고유성:
총 가능한 조합: 2^48 ≈ 281조 개 → 전 세계 기기 수 충분히 커버
제조사 실수로 중복될 수 있으나 매우 드묾
고정성:
기본적으로 하드웨어에 고정되지만, 소프트웨어로 스푸핑하거나
랜덤 MAC 주소(브라우저 시크릿모드 등)로 변경 가능
사용 범위:
LAN 내 통신에서만 사용됨. 인터넷 같은 외부 네트워크에서는 사용되지 않음

MAC 주소의 역할

기기 식별

같은 네트워크에 연결된 여러 기기를 구별
예: 스마트폰(MAC: AA:BB...)과 노트북(MAC: 11:22...)을 정확히 식별

데이터 프레임 전달

프레임 단위로 전송되는 데이터에 송/수신 MAC 주소가 포함됨
공유기나 스위치는 이를 기준으로 데이터를 전달

ARP (Address Resolution Protocol)

IP 주소 → MAC 주소로 변환
예: 192.168.1.100에 데이터 전송 시 해당 IP의 MAC 주소 조회

네트워크 보안 및 관리

MAC 필터링: 특정 MAC 주소만 Wi-Fi 접속 허용
관리자가 MAC 기반으로 사용자 추적 및 접속 제어

MAC 주소와 IP 주소

구분	MAC 주소	IP 주소
역할	LAN 내 기기 식별	네트워크 간 통신 위치 식별
계층	데이터 링크 계층 (Layer 2)	네트워크 계층 (Layer 3)
부여 시점	제조 시 하드웨어에 고정	네트워크 연결 시 DHCP/수동 할당
변경 가능성	스푸핑 등으로 가능	자주 변경 가능 (DHCP 등)
사용 범위	로컬 네트워크(LAN)	인터넷 포함 전 범위

MAC 주소와 Wi-Fi 공유기의 역할

Wi-Fi 공유기는 Layer 2와 Layer 3를 동시에 처리합니다.

Layer 2 (MAC 기반 내부 통신)

MAC 주소 기반 프레임 포워딩
ARP 테이블을 통해 IP ↔ MAC 변환
클라이언트 간 직접 통신도 MAC 주소로 처리

Layer 3 (IP 기반 외부 통신)

DHCP로 IP 주소 할당
NAT로 내부 IP ↔ 외부 공인 IP 변환
라우팅 기능을 통해 인터넷과 연결

실전 예시 – 웹사이트 로딩 시 MAC 주소의 역할

브라우저 → 웹 서버로 HTTP 요청
공유기 → 클라이언트의 MAC 주소로 요청 수신
NAT 처리 후 인터넷으로 전달
웹 서버 응답 → 공유기 → 클라이언트 MAC 주소로 전달

주요 질문 정리

MAC 주소는 왜 필요할까?
→ 로컬 네트워크에서 실제 기기를 식별해야 하므로 필수
바뀔 수 있나?
→ 기본은 고정이지만 스푸핑, 프라이버시 보호 목적으로 변경 가능
겹치면 어떻게 되나?
→ 이론적으로 가능, 실제로는 ARP 혼선 → 데이터 오작동 가능성
어떻게 확인하나?
- arp -a (로컬 ARP 테이블 확인)
- 라우터 관리자 페이지
- Fing, Nmap, Wireshark 등 툴 활용

결론

MAC 주소는 로컬 네트워크에서 기기를 물리적으로 식별하고
데이터 전달의 정확성을 보장하는 필수 요소이다.

IP 주소는 "어디로" 보낼지를 결정
MAC 주소는 "누구에게" 보낼지를 결정

간단하게 비유를 하자면

네트워크 = 회사
MAC 주소 = 직원의 사번
-   사번은 입사 시 부여되는 고유 ID, 바뀌지 않음
-   그 직원이 누구인지 회사 내에서 항상 이 번호로 식별
IP 주소 = 좌석 번호
-   직원이 매일 같은 자리에 앉지 않을 수도 있고, 부서 이동 시 자리를 바꿈
-   위치는 상황에 따라 유동적이며, 그날 그 순간만 유효
ARP = 좌석배치도  
-   누가 어느 자리에 앉아 있는지 알려주는 배치표
-   “사번 1234번 직원이 지금 5번 좌석에 앉아 있음”
공유기 = 부서 관리자
-   부서 간 문서를 전달하거나 전화 연결 등 소통 중개자 역할
-   사람 이름이나 부서가 아니라 사번으로 정확히 찾아 연결

인 셈이다.

Nginx - Nginx Proxy Manager Stream 설정

Aleph Kim — Thu, 8 May 2025 13:23:57 +0900

개요

최근 GCP 프리티어 VM이 너무 느린 것 같아 Oracle Cloud Infrastructure(OCI)의 프리티어로 서버를 옮기게 되었다. OCI는 상상 이상으로 쾌적하게 잘 작동했지만, 인스턴스 간 네트워크 구성에서 예상치 못한 문제가 발생했다.
OCI에서는 프리티어 기준으로 VM 인스턴스를 2개까지 생성 가능하지만, Public IP는 1개만 예약 가능하다.
그리하여 아래와 같이 구성했다.

main-instance: 실제 서비스 운영 (Nginx, 백엔드 API 등), Public IP 보유
db-instance: MySQL DB만 운영, 사설 IP만 존재

하지만 위 구조로 진행 중 DB 툴(MySQL Workbench, DBeaver 등)에서 MySQL에 접속하려고 할 때 문제가 발생했다.

원인

처음엔 단순히 main-instance의 Nginx Proxy Manager를 통해 프록시 설정을 하면 해결될 줄 알았다. 실제로 HTTP 프록시 기능을 이용해 여러 서비스들을 잘 연동하고 있었기 때문에 MySQL도 비슷할 거라고 생각했다.

하지만 문제는 MySQL은 HTTP 기반이 아닌 TCP 기반의 독자적인 프로토콜을 사용하는 서비스라는 점이었다. 기존 HTTP 프록시 설정으로는 전혀 동작하지 않았다.

이건 결국 OSI 7계층의 차이에서 비롯된 문제였다.

구분HTTP Proxy (기본 프록시)Stream Proxy (TCP/UDP)

계층	7계층 (Application Layer)	4계층 (Transport Layer)
사용 프로토콜	HTTP, HTTPS	TCP, UDP
사용 용도	웹 서비스, 리버스 프록시	DB 연결, SSH, 커스텀 포트
대표 예시	Web → Nginx Proxy	MySQL, Redis, SSH

해결

문제를 해결하기 위해 Nginx Proxy Manager의 고급 기능 중 하나인 stream 프록시를 사용했다. 이 기능은 HTTP가 아닌 TCP 또는 UDP 기반의 트래픽을 프록시해주는 기능이다.

✅ 설정 방법

Nginx Proxy Manager 대시보드 접속
"Streams" 메뉴 > Add Stream
다음과 같이 설정:

Incoming Port: 로컬 PC에서 접근할 포트(예: 3306)
Forward Host: db-instance의 Private IP (예: 10.0.0.5)
Forward Port: db-instance에서 접근할 포트(예: 3306)
TCP Forwarding: true

설정 저장 후, 로컬 PC에서 main-instance의 Public IP:3306으로 접속하면 MySQL에 정상적으로 연결된다.

로컬 PC - MySQL 접속 구조

[로컬 PC] --- TCP 3306 --> [main-instance (Public IP)]  
                                         |  
                                         | [Stream 프록시: 3306]  
                                         |  
                              [db-instance (사설 IP)]  
                                       MySQL

후기

아주 먼 옛날 고등학교 정보 시간에 배웠던 계층에 대한 내용을 실제 개발을 하며 마주하니 감회가 새로웠다.

단순히 구현만 잘하는 개발자보다는 폭 넓은 지식으로 다양한 시각으로 문제를 바라볼 수 있는 개발자가 되기 위해 꾸준히 노력해야겠다.

Docker - Dockerfile에서 crontab 설정하기

Aleph Kim — Fri, 25 Apr 2025 21:10:27 +0900

도커 덕분에 행복해요

개요

Docker 컨테이너 안에서 cron을 실행해야 하는 작업이 있어서 Dockerfile에 cron 설정을 추가했는데, 컨테이너는 잘 올라갔지만 cron이 실행되지 않는 문제가 발생했다.
crontab -l로 확인해보면 제대로 등록까지 되어 있었는데도 아무 반응이 없었고, 구글로 검색했더니 명확한 해결방법을 찾지 못해 수많은 삽질을 통해 찾게된 해결방법을 정리해본다(몹시 간단).

Dockerfile에 crontab 설정하기

처음에 사용한 Dockerfile은 대략 아래와 같았다

# 베이스 이미지
FROM ubuntu:20.04

# 패키지 설치
RUN apt-get update && apt-get install -y cron

# cron 파일 복사
COPY cronfile /etc/cron.d/cronfile

# cron 파일 실행 권한 부여
RUN chmod 0644 /etc/cron.d/cronfile

# cron 작업 정의
RUN crontab /etc/cron.d/cronfile

# cron 로그 디렉토리 생성
RUN touch /cron.log

# cron log 확인
ENTRYPOINT ["tail", "-f", "/cron.log"]

예시 cronfile

* * * * * echo "Hello, World!" >> /var/log/cron.log

이렇게 설정한 후 이미지를 빌드하고 컨테이너를 실행했는데, 로그가 생성되지 않았다.

crontab -l로 확인해보면?

docker exec -it <container_name> crontab -l

명령어로 확인해보면 분명히 crontab은 잘 등록되어 있었다.
그런데 로그는 전혀 찍히지 않았고, cron이 도는 흔적이 없었다.

원인

결론부터 말하면, crontab 등록만 해서는 cron 데몬이 자동으로 실행되지 않는다.
도커 컨테이너는 기본적으로 단일 프로세스를 실행하기 때문에, cron 서비스를 명시적으로 시작해주지 않으면 crontab만 등록된 상태로 끝난다.

해결 방법

Dockerfile에 cron 서비스를 실행하도록 명시적으로 추가해야 한다.

따라서 CMD 또는 ENTRYPOINT로 컨테이너 실행 시점에 cron을 실행하도록 해야 한다.

# 베이스 이미지
FROM ubuntu:20.04

# 패키지 설치
RUN apt-get update && apt-get install -y cron

# cron 파일 복사
COPY cronfile /etc/cron.d/cronfile

# cron 파일 실행 권한 부여
RUN chmod 0644 /etc/cron.d/cronfile

# cron 작업 정의
RUN crontab /etc/cron.d/cronfile

# cron 로그 디렉토리 생성
RUN touch /cron.log

# entrypoint.sh 파일 복사
COPY entrypoint.sh /entrypoint.sh

# entrypoint.sh 파일 실행 권한 부여
RUN chmod +x /entrypoint.sh

# 컨테이너 실행 시 cron 실행
ENTRYPOINT ["/bin/bash", "/entrypoint.sh"]

예시 entrypoint.sh

#!/bin/bash

# cron 서비스 시작
service cron start

# cron 로그 확인
tail -f /cron.log

이제 정상적으로 매 분마다 Hello World 로그가 추가된다.

추가 팁: 시간대 문제

cron이 정상적으로 등록되었는데도 지정한 시간에 실행되지 않는다면,
컨테이너의 시간대(timezone) 설정이 잘못되어 있을 가능성이 높다.

date 명령어로 현재 시간을 확인해보자:

docker exec -it <container_name> date

만약 한국 시간이 아니라면, Dockerfile에 다음 설정을 추가해주면 된다:

ENV TZ=Asia/Seoul
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

후기

docker에서 쌩으로 crontab을 돌려보는건 처음이라 좀 해메게 되었는데 덕분에 docker와 cron에 대해 조금 더 알아가는 시간이 된 것 같아 좋은 것 같다.
docker는 뭔 놈의 기술이 이렇게도 이해가 됐다 싶으면 멀어지고 또 이해가 됐다 싶으면 또 멀어지는지 알다가도 모르겠다.

기타 - compinit:480: compdump: function definition file not found 에러 해결(feat. m4 에어 마이그레이션)

Aleph Kim — Thu, 24 Apr 2025 11:34:14 +0900

사랑스러운 우리 맥부기맥북맥북어맥북스딱스맥부르크맥부가우가

개요

드디어 맥북을 업그레이드 했다. 오랜 기간 동고동락한 m1 에어를 보내주고 m4 에어를 질러버렸다.
기분좋게 마이그레이션까지 마치고 VScode에서 터미널을 열었는데 갑자기 아래와 같은 에러가 출력되기 시작했다.

compinit:480: compdump: function definition file not found
.zshrc:188: add-zsh-hook: function definition file not found

compinit 관련 에러

zsh에서 compinit은 자동 완성 기능을 초기화할 때 사용하는 함수인데, 뭔가 꼬였는지 함수 파일 자체를 못 찾는다고 에러가 발생했다.
그래서 .zshrc에 다음 스크립트를 추가해보았다

autoload -Uz compinit
compinit

autoload -U bashcompinit
bashcompinit

근데 이렇게 해도 여전히 같은 에러가 계속 발생.

Homebrew zsh 제거 시도

혹시 zsh가 이상하게 설치되어 있는 건가 싶어서 Homebrew로 설치된 zsh를 제거해보려 했다.

brew uninstall zsh

그런데 새로운 에러가 발생

Error: Permission denied @ rb_sysopen - /opt/homebrew/var/homebrew/locks/go.formula.lock

이번엔 brew가 내부 디렉터리 파일에 접근 권한이 없어서 에러가 발생하는 상황이었다.

원인 분석

해당 에러는 /opt/homebrew 아래에 있는 파일들이 admin 계정 소유로 되어 있어서 현재 사용자 권한으로는 접근이나 수정이 불가능한 상태였다.

ls -al /opt/homebrew 해보면 소유자가 admin으로 되어 있는 걸 확인할 수 있다.

해결 방법

권한 문제를 해결하기 위해 brew 설치 경로 전체의 소유자를 현재 사용자로 변경했다

sudo chown -R $(whoami) /opt/homebrew

이 명령을 실행한 후 brew uninstall zsh 명령도 잘 작동했고, .zshrc 관련 에러도 함께 사라졌다.

후기

다음에 비슷한 일이 생기면 brew 권한부터 의심해보자.

PHP - Apache server status 설정 + 프록시 IP 처리

Aleph Kim — Mon, 21 Apr 2025 18:45:58 +0900

개요

Grafana로 PHP 서버 상태를 모니터링하려고 하다가 Apache 환경에서의 설정과 보안 문제를 겪게 되어, 그 과정을 정리해보았다.
특히 server-status를 외부에서 접근 가능하게 열었을 때 생기는 보안 이슈와, Nginx 프록시 환경에서의 IP 처리 문제를 어떻게 해결했는지를 중심으로 다룬다.

Apache server-status 활성화

Apache에서는 mod_status 모듈을 활성화한 뒤 /server-status 엔드포인트를 열어 서버 상태 정보를 확인할 수 있다.
Grafana로 apache 서버를 모니터링 할때는 해당 데이터를 수집하기 위해 보통 Prometheus용 Apache Exporter와 연결하여 시각화한다.

처음에는 다음과 같은 설정으로 server-status를 활성화했었다.

<Location /server-status>
    SetHandler server-status
    Require all granted
</Location>

그런데 이렇게 설정하면 누구나 해당 경로에 접근 가능하게 되어버려 보안상 매우 위험하다.

IP 제한 설정

Apache Exporter는 내부망에서 동작하도록 구성되어 있었기 때문에, 내부망에서만 접근 가능하도록 IP 제한을 걸어주었다.
여기서 말하는 내부망은 172.16.0.0/12 대역이다.

참고: 172.16.0.0/12는 사설 IP 주소 대역 중 하나로,
172.16.0.0부터 172.31.255.255까지 포함하는 범위이다.
보통 기업 내부망이나 VPC 등에서 많이 사용된다.

그래서 아래처럼 IP 제한을 설정했다.

<Location /server-status>
    SetHandler server-status
    Require ip 172.16.0.0/12
</Location>

Nginx Proxy 환경에서의 문제

문제는 여기서 발생했다.
서버는 Nginx Reverse Proxy 뒤에 있었고, Apache는 클라이언트의 IP가 아닌 프록시 서버의 IP를 클라이언트 IP로 인식하고 있었다.
즉, 실제 클라이언트가 내부망에 있지 않더라도, Apache 입장에서는 Nginx의 IP만 보이는 상황이었다.

Client → Nginx Proxy (내부망) → Apache (내부망)

Apache는 클라이언트가 아닌 프록시 IP가 172.16.0.0/12에 포함되는지만 보고 판단했는데, 프록시 서버도 내부망에 있었기 때문에 사실상 모든 요청이 이미 IP 조건을 통과하고 있었던 상황이었고 결과적으로 Require ip 조건이 실제로는 제대로 작동하지 않고 있었다.

클라이언트의 실제 IP를 인식하도록 설정

이 문제를 제대로 해결하기 위해 Apache의 mod_remoteip 모듈을 사용해서 프록시가 전달하는 X-Forwarded-For 헤더를 신뢰하도록 설정했다:

<IfModule remoteip_module>
    RemoteIPHeader X-Forwarded-For
    RemoteIPInternalProxy 172.16.0.0/12
</IfModule>

RemoteIPHeader: 프록시 서버가 전달하는 헤더 이름 (X-Forwarded-For)
RemoteIPInternalProxy: 이 IP 대역에서 오는 요청만 프록시로 신뢰함

이렇게 하면 Apache는 172.16.0.0/12에 해당하는 프록시 서버에서 온 요청에 대해서만 X-Forwarded-For 헤더를 신뢰하고 클라이언트 IP로 간주한다.

X-Forwarded-For 보안 이슈?

하지만 위처럼 설정을 하고 나니 누군가가 직접 X-Forwarded-For 헤더를 조작하면 IP 제한을 우회할 수 있지 않을까 걱정되었다.
하지만 테스트를 해보니 그렇지 않았다. 그것은 apache서버의 요청 처리 방식 때문이었다.

Apache는 먼저 요청의 Remote IP가 RemoteIPInternalProxy 조건을 만족하는지 검사한다.
조건을 통과한 경우에만 X-Forwarded-For 값을 IP로 반영한다.
즉, 프록시 서버로부터 온 요청이 아니면 헤더를 무시하고, IP 제한은 정상 동작한다.

만약 사용자가 Remote IP 자체를 172.16.x.x로 조작하면?

그래도 Remote IP를 내부망처럼 보이게 해서 우회하는 것이 가능하지 않을까 생각할 수 있다.
예를 들어

출발지 IP를 172.16.0.10으로 스푸핑하고
X-Forwarded-For도 같이 조작해서 내부망 요청처럼 보이게 한다면?

라는 생각이 들 수 있는데, 실제로는 거의 불가능에 가까운 시나리오다.

Apache가 인식하는 Remote IP는 단순히 HTTP 헤더로 전달된 게 아니라,
커널 네트워크 계층에서 수신된 TCP 연결의 출발지 IP 주소다.

즉, RemoteAddr은 서버가 수신한 진짜 패킷의 IP이고, 이건 다음 조건을 모두 만족해야 한다:

TCP 3-way handshake가 완성되어야 함
서버가 응답을 보낸 IP와 다시 통신이 가능해야 함

그런데 출발지 IP를 위조하는 순간, 응답은 진짜 공격자에게 가지 않고 조작된 IP(예: 172.16.0.10)로 가게 된다.
그러면 TCP 연결이 성립되지 않고, Apache는 요청 자체를 수락하지 않는다.

결론

외부에서 단순히 curl이나 Postman 같은 도구로는 절대 Require ip와 RemoteIPInternalProxy 조건을 우회할 수 없다.
출발지 IP 자체를 속이는 건 커널 수준에서 막히며, 정말로 이걸 뚫으려면 네트워크 경로를 통제하거나 내부망 장비를 뚫어야 한다.

즉, 일반적인 환경에서는 이 설정으로 충분히 안전하다는 결론이다.

최종 코드

# 외부 프록시 헤더 사용
<IfModule remoteip_module>
    RemoteIPHeader X-Forwarded-For
    RemoteIPInternalProxy 172.16.0.0/12
</IfModule>

# /server-status 설정
<Location /server-status>
    SetHandler server-status
    Require ip 172.16.0.0/12
</Location>

후기

처음엔 단순히 Grafana 연동만 잘하면 되겠지 싶었는데, 프록시 구조나 보안 설정까지 챙기게 될 줄은 몰랐다.
특히 X-Forwarded-For 같은 헤더는 자칫 잘못 쓰면 보안 구멍이 될 수 있어서 신중하게 접근해야 했는데 다행히 Apache가 이런 시나리오를 잘 고려해놔서 설정만 잘 하면 안전하게 운영할 수 있다는 걸 확인했다.
앞으로도 이런 설정은 주기적으로 점검하면서 사용하는 게 좋겠다.

DB를 털리다.

Aleph Kim — Mon, 14 Apr 2025 20:14:01 +0900

피곤한 월요일, 여느 때와 같이 일을 하다 잠깐 쉬는 시간에 내 사이트는 잘 돌아가고 있나 들어가보았는데

메인페이지에서 500 에러가 발생하고 있었다.

경험상 잘 돌아가던 사이트의 메인페이지에서 에러가 발생하는 경우는 보통 db 연결에 장애가 생겨 그런 경우가 대부분이었어서 '뭐지 db가 꺼졌나?', 'cloudflare 연결한게 원인인가? 아닌데.. db는 ip로 연결해서 별 관련 없는데..' 하는 생각을 하며 서버에 접속을 해보았다.

흐으음... db는 안 내려갔고... 이상이 없는데? redis가 내려갔나? redis도 정상적인데....

원인을 찾지 못하고 애꿎은 서버 로그만 뒤적이고 있었다.

그

런

데

All your data is backed up. You must pay 0.0100 BTC to bc1qwvthsvr7agkmn36qxxn4ju2qe6mur37s453w43nl In 48 hours, your data will be publicly disclosed and deleted. (more information: go to https://해킹범.사이트)
After payment send mail to us: rambler+29eqk@xxx.org and we will provide a link for you to download your data. Your DBCODE is: 29EQK

해킹범이 내 데이터를 인질로 잡고 0.01 비트코인을 요구하고 있는 걸 알게 되었다. 근데 그게 얼마지?...

비트코인이 1억이면... 0.01 비트코인이면...

내가 120만원이 어디있어

애초에 천 원 한 장도 줄 생각 없었지만 120만원이라니 택도 없는 가격이었다.

아.. 해커도 먹고 살기 팍팍하구나...

그건 그렇고 어디서 털린거지?

이전 회사에서 열심히 구른 후 보안과 관련된 부분은 잘 준수하고 있다 생각했는데도 털려버리니 당황스러웠다.

인젝션인가? 아닌데... 잘 막아뒀는데...

브루트포스인가? 아닌데... 서버가 나약해서 못 버텼을텐데...

깃허브에 올라간 적이 있나? 아닌데... 그런 기본적인 실수를 했을리가...

grok한테 물어볼때 코드에 노출이 됐나? 머스크형이 ai로 수집한 데이터를 판매한다고?.... 그럴....수도 있겠는데?!

mysql 서버 로그는 해킹범이 싹 지워버려 확인도 못하고 여러가지 추측만 난무하던 차에 문득 든 생각!

postgresql은 안 털렸나?!

이전에 공부용으로 프로젝트를 진행하고 바꾸기 귀찮아서 올려둔 psql 서버가 생각 나 로그를 조회해봤다.

아아... psql좌.... 무슨 싸움을 하고 계셨던 겁니까...

psql 서버도 공격이 있었다!!!! 하지만 피해는 발생하지 않았다.

왜지? 무슨 차이지?

끝나지 않는 의문을 갖고 여기저기 뒤적뒤적 거리던 중

?ㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋ

설마 누가 내 서버를 해킹하겠어~ 하는 안일한 생각으로 설정한 비밀번호를 발견하게 되었다.

기본 3306 포트를 사용하면서 mysql 서버 root 계정의 비밀번호를 mysql로 하는 배짱 좋은 과거의 나를 마주하자 어이가 없어 헛웃음이 나왔다.

그래도 원인은 찾았으니 기존 mysql 서버는 보내주고 기존과 다른 포트, 비밀번호로 설정한 db를 새로 올려 서비스를 다시 정상적으로 운영할 수 있게 되었다.

이번 사태를 통해 느낀 점은 크게 3가지이다.

백업은 필수로 해야겠다.
아무리 작은 서비스라도 운영중인 서비스가 장애가 생겼을때 신속히 대처하려면 모니터링 툴을 사용해야겠구나
2000개 가량의 데이터를 날리게 되어 아주 귀찮아졌지만 덕분에 보안에 더 신경을 쓰게 되었으니 럭키비키다.

과거의 안일했던 나는 보내주고 더 성장하게 된 것 같아 오히려 기분이 좋았다.

그리하여 다음 포스팅은 그라파나를 사용한 php 서버 모니터링에 관한 글이 될 것 같다.

끝!

Nginx - Nginx Proxy Manager + Cloudflare ssl 적용

Aleph Kim — Fri, 11 Apr 2025 12:49:18 +0900

개요

가난한 개발자는 무료 서버를 사용할 수 밖에 없고 8,000km나 떨어진 서버를 사용하는 사이트에 접속하면 속도는 끔찍한 경우가 대부분이다.
특히나 메인페이지에 접속할때마다 자체 이미지 호스팅 서버에서 수많은 이미지를 불러오고, db 서버에서 복잡한 조회 쿼리를 실행하는 내 사이트의 속도는 최악 중의 최악에 치달았다.
이를 해결하기 위해 방법을 찾아보다 CDN 서비스라는 것을 알게 되었고, 그 중에 전세계 1등 CDN 서비스 회사인 Cloudflare를 사용하게 되었다.
DNS 설정을 하고, 처음보는 서비스가 신기해 이것저것 설정을 해본 후 속도가 얼마나 빨라졌나 기대를 하며 내 사이트에 접속을 하는데! 이게 뭐람? 정상적이던 내 사이트가 갑자기 접속이 안 되기 시작했다.
ERR_SSL_PROTOCOL_ERROR라는 유언을 남긴 내 서버를 살리기 위해 방법을 찾아본 결과 기존 NPM에서 설정한 ssl 인증서와 cloudflare의 ssl 설정에서 충돌이 발생한 것 같았다.
이를 해결하기 위해 NPM에서 cloudflare의 인증서를 사용하게끔 수정해보았다.

cloudflare api 토큰 세팅

1. 개요 탭에 접속하여 하단에 있는API 토큰 가져오기 페이지로 이동한다.

2. 토큰 생성 페이지로 이동한다.

3. 영역 DNS 편집 템플릿을 사용한다.

4. 영역 리소스를 모든 영역으로 설정한 후 요약 페이지로 이동한다.

5. 토큰 생성 버튼을 클릭한다.

6. 생성한 토큰을 복사해둔다.

NPM 세팅

1. NPM의 SSL Certificates 탭의 Add SSL Certificate 버튼을 클릭한다.

인증서 정보를 입력한 후 저장한다(저장 시 약간의 시간이 소요됨).
1. 범용 도메인명 입력
2. DNS Challenge 설정
  1. DNS Provider - Cloudflare로 설정
  2. Credentials File Content에 api_token 부분을 복사한 토큰으로 수정
3. 약관 동의

3. 기존 proxy host를 수정하거나 새 proxy host를 추가할때 ssl 탭에서 SSL Certificate를 저장한 인증서로 저장해준다.

후기

별게 아닌데 찾아보지도 않고 머리부터 들이밀었더니 많은 시간이 소요되었다.

하지만 헤매는 시간동안 SSL과 DNS에 대해 조금 더 이해를 하게 되었으니 럭키비키다.

Go - 이미지 리사이즈 기능(/h2non/bimg)

Aleph Kim — Fri, 28 Mar 2025 11:47:20 +0900

개요

Go로 이미지 호스팅 서버를 개발하던 중, 이미지 리사이즈 기능을 구현하는 과정에서 고민했던 점들을 정리해보았다.

go 주요 이미지 리사이즈 라이브러리 비교

라이브러리	장점	단점
bimg	- libvips 기반으로 매우 빠른 처리 속도 - 메모리 사용량이 적음 - 다양한 이미지 포맷 지원	- C 바인딩으로 인한 설치 복잡도 증가 - libvips 의존성 필요 - Windows 환경에서 설정이 까다로움
imaging	- 순수 Go로 작성되어 설치가 간단 - 크로스 플랫폼 지원이 용이 - API가 직관적이고 사용하기 쉬움	- 처리 속도가 상대적으로 느림 - 메모리 사용량이 많음 - 일부 고급 이미지 처리 기능 부재
nfnt/resize	- 가볍고 단순한 구현 - 순수 Go로 작성되어 의존성이 없음 - 기본적인 리사이즈 기능 제공	- 성능이 상대적으로 낮음 - 고급 이미지 처리 기능 부재 - 메모리 사용량이 많음 - 지원이 종료됨
imgproxy	- 다양한 이미지 처리 옵션 제공 - 캐싱 기능 내장 - 고성능 처리	- 별도의 서비스로 실행 필요 - 설정이 복잡함 - 리소스 사용량이 많음

라이브러리 선택 과정

1. 초기 고려사항
   - 순수 Go로 작성된 라이브러리 선호 (설치 간편성)
   - 기본적인 리사이즈 기능만 필요

2. 시도한 라이브러리들
   - `github.com/nfnt/resize`: 순수 Go로 작성되어 설치가 간단했으나, WebP 미지원
   - `github.com/disintegration/imaging`: 순수 Go로 작성되어 설치가 간단했으나, WebP 지원이 제한적

3. bimg 선택 이유
   - libvips 기반으로 매우 빠른 처리 속도
   - WebP를 포함한 다양한 이미지 포맷 지원
   - 메모리 효율적인 처리
   - Docker 환경에서 쉽게 설정 가능
   - 활발한 커뮤니티와 안정적인 업데이트

4. 선택 후 고려사항
   - libvips 설치 필요성
   - Docker 환경에서의 설정

webp 확장자를 지원하는 라이브러리 중 비교적 간단하게 관리할 수 있는 bimg를 선택하게 되었다.

코드를 작성하기 전에!

go 구동 환경에 libvips 설치가 필요하다.

macOS: Homebrew를 통한 설치

brew install vips

Ubuntu/Debian: apt를 통한 설치

sudo apt-get update
sudo apt-get install -y libvips-dev

Windows: MSYS2를 통한 설치

pacman -S mingw-w64-x86_64-libvips

설치 확인

# libvips 버전 확인
vips --version

코드

Go의 github.com/h2non/bimg 라이브러리를 사용하여 이미지 리사이즈 기능을 구현했다.
이 라이브러리는 libvips를 기반으로 하여 빠른 이미지 처리가 가능하다.

import (
    "fmt"
    "log"
    "strconv"
    "strings"

    "github.com/h2non/bimg"
)

/*
이미지를 주어진 크기로 리사이징

Parameters:
  - size: "width x height" 형식의 문자열 (예: "100x100")
  - filePath: 리사이징할 이미지 파일 경로

Returns:
  - []byte: 리사이징된 이미지 바이트
  - error: 에러 발생 시 에러 객체 반환
*/
func ResizeImage(size string, filePath string) ([]byte, error) {
    // 이미지 파일 확장자 체크
    if !strings.HasSuffix(strings.ToLower(filePath), ".jpg") &&
        !strings.HasSuffix(strings.ToLower(filePath), ".jpeg") &&
        !strings.HasSuffix(strings.ToLower(filePath), ".png") &&
        !strings.HasSuffix(strings.ToLower(filePath), ".webp") {
        return nil, fmt.Errorf("지원하지 않는 이미지 형식입니다")
    }

    // size 파라미터 파싱
    sizes := strings.Split(size, "x")
    if len(sizes) != 2 {
        return nil, fmt.Errorf("잘못된 크기 형식입니다. (예: 100x100)")
    }

    width, err := strconv.Atoi(sizes[0])
    if err != nil {
        return nil, fmt.Errorf("잘못된 너비 값입니다")
    }

    height, err := strconv.Atoi(sizes[1])
    if err != nil {
        return nil, fmt.Errorf("잘못된 높이 값입니다")
    }

    // 이미지 읽기
    buffer, err := bimg.Read(filePath)
    if err != nil {
        return nil, fmt.Errorf("이미지 처리 중 오류가 발생했습니다")
    }

    // 리사이즈 수행
    newImage, err := bimg.NewImage(buffer).Resize(width, height)
    if err != nil {
        return nil, fmt.Errorf("이미지 처리 중 오류가 발생했습니다")
    }

    return newImage, nil
}

후기

라이브러리를 사용하여 이미지 리사이즈 기능 자체를 구현하는 것은 어렵지 않았으나 webp 확장자를 지원하는 라이브러리를 찾느라 조금 헤매게 되었다.
그래도 정리하고 나니 뿌듯하다.

PHP - 클로저(Closure, 익명 함수)

Aleph Kim — Fri, 21 Mar 2025 20:55:08 +0900

개요

개발을 하다보면 변수를 넣어야하는 문자열을 또 변수로 사용하게 될때가 있는데 매번 문자열을 불러와서 변수를 .으로 붙여주거나 복잡하게 넣어주게 돼서 간단한 방법이 없나 찾아보다 클로저 함수라는 것을 사용하게 되었다.

사용 예시

// 문자열에 변수 추가
$exam_url = fn($id) => "https://example.com/user/$id";
echo $exam_url(123); // "https://example.com/user/123"

// 문자열에 변수 여러 개 추가
$profile = fn($name, $age) => "이름: $name, 나이: $age";
echo $profile("aleph", 26); // "이름: aleph, 나이: 26"

// 문자열에 삼항연산자로 변수 추가
$status = fn($point) => "상태: " . ($point > 50 ? "좋음" : "나쁨");
echo $status(70); // "상태: 좋음"
echo $status(30); // "상태: 나쁨"

// 배열에 사용
$numbers = [1, 2, 3, 4];
$double = array_map(fn($num) => "숫자: $num", $numbers);
print_r($double); // ["숫자: 1", "숫자: 2", "숫자: 3", "숫자: 4"]

후기

남발하면 가독성이 멸망하겠지만 간단히 url에 변수 넣는 용도쯤은 나쁘지 않은거 같다.

PHP - html 태그 추출기

Aleph Kim — Mon, 17 Mar 2025 09:57:29 +0900

개요

웹개발을 할때 svg 아이콘이 필요하면 유튜브에서 사용하는 svg 태그를 가져다 사용하고 있는데 유튜브에 존재하는 모든 svg를 미리 분류해두고 싶어 php를 사용해 유튜브 페이지의 전체 html에서 svg 태그만 추출하기 위해 php로 태그 추출기를 만들어보았다.

코드

<?php

// 추출할 태그명을 변수로 정의
$tagName = 'div'; // 원하는 태그명으로 변경 (예: 'div', 'p' 등)

// HTML 파일 읽기
$html = file_get_contents('input.html');

// 동적 태그명으로 패턴 생성
$pattern = "/<{$tagName}.*?>(.*?)<\/{$tagName}>/is";
preg_match_all($pattern, $html, $matches);

// 결과 처리
$output = implode("\n", $matches[0]);

// 파일로 저장
file_put_contents('output.html', $output);

echo "태그 추출이 완료되었습니다.";

사용 예시

input.html

<html>

<body>
  <div class="div1">
    <span></span>
  </div>
  <div class="div2">
    <p></p>
  </div>
  <p></p>
  <span></span>
  <div class="div3"></div>
</body>

</html>

위 html을 php 파일과 같은 경로에 input.html로 저장하고 php 파일의 $tagName 변수를 추출하고 싶은 태그(예시에서는 div)로 작성한 뒤 터미널에 php index.php 명령어를 사용하면 태그 추출이 완료되었습니다. 라는 메시지와 함께 아래의 내용이 담긴 output.html 파일이 저장된다.

output.html

<div class="div1">
    <span></span>
  </div>
<div class="div2">
    <p></p>
  </div>
<div class="div3"></div>

HTML, CSS - 별점 선택(Star Rating)

Aleph Kim — Thu, 13 Mar 2025 12:51:45 +0900

See the Pen Star Rating by 김채민 (@aleph-kim) on CodePen.

PHP - Docker-Compose 환경 PHP 프로젝트 빌드 시 Composer 설치

Aleph Kim — Tue, 11 Mar 2025 11:40:35 +0900

개요

php, docker compose로 프로젝트를 진행하면서 composer를 설치하려는데 뭐 컨테이너를 따로 만들고 어쩌구 볼륨을 설정하고 어쩌구 이상하리만치 복잡하길래 간단한 방법을 만들어보았다.

파일

docker-compose.yml

기본 compose 파일로 composer를 쓰나 안 쓰나 차이는 없다.

version: '3.8'

services:
  web:
    build: .
    ports:
      - "8080:80"
    volumes:
      - .:/var/www/html

Dockerfile

Dockerfile에서 직접 composer를 설치하고, 라이브러리도 설치한다.

# PHP 7.4와 Apache 이미지 사용
FROM php:7.4-apache

# Composer 설치에 필요한 패키지 설치 (curl, unzip, git)
RUN apt-get update && apt-get install -y \
    curl \
    unzip \
    git

# Composer 설치
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

# 작업 디렉토리 설정
WORKDIR /var/www/html

# 애플리케이션 파일 복사
COPY . /var/www/html/

# composer 라이브러리 설치 && Apache 서비스 시작
CMD bash -c "composer install --no-interaction --prefer-dist && apache2-foreground"

index.php

<?
require 'vendor/autoload.php'; // composer 라이브러리 autoload

use Carbon\Carbon; // 테스트용 라이브러리

$now = Carbon::now('Asia/Seoul'); // 현재 시간 출력
echo $now->toDateTimeString();

composer.json

{
    "require": {
        "nesbot/carbon": "^2.7.3" // 테스트용으로 사용할 php datetime 라이브러리
    }
}

후기

Dockerfile에서 북치고 장구치고 다 하게끔 만들어보았다. 이렇게 하면 컨테이너를 추가로 만들 필요도 없고 원래 하던대로 docker compose up 명령어 딸깍으로 composer를 사용할 수 있다.

Go - 파일 호스팅 서버 프로젝트 기술 설명서

Aleph Kim — Sun, 9 Mar 2025 23:21:17 +0900

프로젝트 기술 설명서

이 프로젝트는 파일 호스팅를 위한 RESTful API 서버입니다. Go 언어로 작성되었으며, Docker를 이용해 배포할 수 있도록 구성되었습니다. 서버는 사용자가 인증된 상태에서 파일을 업로드하고 관리할 수 있도록 기능을 제공합니다.

️ 기술 스택 ️

Go: 서버 사이드 로직 구현
Docker: 애플리케이션 컨테이너화 (개발 및 프로덕션 환경 지원)
Gorilla Mux: HTTP 라우팅
bcrypt: 안전한 비밀번호 해싱
JSON: 데이터 저장 및 응답 형식으로 사용

프로젝트 구조

  img-host-server
│
├── /cmd/server/main.go          : 서버 초기화 및 라우팅 설정
│
├── /internal
│   ├── handles
│   │   ├── file_handler.go      : 파일 업로드, 수정, 삭제, 다운로드 처리
│   │   └── user_handler.go      : 사용자 등록 및 관리 처리
│   ├── utils
│   │   ├── auth.go              : 사용자 인증 관련 함수 (비밀번호 검증, 사용자 정보 로딩)
│   │   ├── response.go          : JSON 형식의 응답을 처리하는 유틸리티
│   │   ├── file.go              : 파일 업로드 및 저장 관련 함수
│   │   └── sanitize.go          : 파일명 유효성 검사
│   └── db
│       └── users.json           : 사용자 정보 저장
│
├── .air.toml                    : 개발 환경 hotswap 라이브러리 설정 파일(air 라이브러리)
├── .env                         : 환경변수 관리(관리자 비밀번호)
├── /docker-compose.yml          : Docker 설정 파일
├── /Dockerfile.prod             : 프로덕션 환경을 위한 Dockerfile
├── /Dockerfile.dev              : 개발 환경을 위한 Dockerfile
├── /go.mod                      : Go 모듈 설정 파일
└── /go.sum                      : Go 의존성 정보 파일

API 엔드포인트

POST /files: 파일 업로드
PUT /files/{filename}: 파일 수정
GET /files/{username}/{filename}: 파일 다운로드
DELETE /files/{filename}: 파일 삭제
POST /users: 사용자 등록

프로젝트 실행 방법

GitHub에서 이 프로젝트를 Clone한 후, 로컬에서 실행하는 방법은 다음과 같습니다.

1️⃣ GitHub에서 프로젝트 Clone

git clone https://github.com/Aleph-Kim/img-host-server
cd img-host-server

2️⃣ 관리자 비밀번호 설정

.env 파일을 사용하여 관리자 비밀번호를 설정할 수 있습니다.

3️⃣ Docker 환경 설정

Docker를 이용하여 애플리케이션을 실행할 수 있습니다. docker-compose.yml 파일을 사용하여 개발 환경과 프로덕션 환경을 설정할 수 있습니다.

개발 환경 실행:
docker-compose up dev
프로덕션 환경 실행:
docker-compose up prod

4️⃣ 서버 실행

서버는 기본적으로 3000 포트에서 실행됩니다. 서버가 성공적으로 실행되면, 브라우저나 Postman 등을 통해 API를 테스트할 수 있습니다.

Docker 구성 설명

Dockerfile.prod: 프로덕션 환경용 Dockerfile로, 실제 배포용 설정이 포함되어 있습니다.
Dockerfile.dev: 개발 환경용 Dockerfile로, 소스 코드 변경 시 자동 반영되도록 설정되어 있습니다.
docker-compose.yml: 개발 및 프로덕션 환경을 동시에 지원하는 설정 파일로, 필요한 서비스를 자동으로 구성해줍니다.

주의 사항

.env 파일에 관리자의 비밀번호가 설정되어야 하며, 관리자 인증을 통해 사용자를 등록할 수 있습니다.
파일 업로드/수정/삭제 시 사용자 인증을 위해 X-Username과 X-Secret 헤더를 사용합니다.

이 프로젝트는 파일 업로드와 관리, 사용자 인증을 간편하고 안전하게 처리할 수 있도록 설계되었습니다. 추가적인 기능이 필요하면 언제든지 요구 사항을 반영할 수 있습니다.

Docker - sudo 없이 docker 명령어 사용하기

Aleph Kim — Sun, 9 Mar 2025 12:48:13 +0900

개요

현재 인스턴스 서버에서 docker 명령어를 실행할 때마다 sudo를 붙여야 하는 불편함이 있어 이를 해결하기 위해 방법을 찾아보았다.

1. 현재 사용자 Docker 그룹에 추가하기

# 현재 사용자를 docker 그룹에 추가하는 명령어
sudo usermod -aG docker $USER

2. 세션 재시작 또는 로그아웃 후 다시 로그인

그룹 변경 사항이 적용되기 위해 로그아웃 후 다시 로그인하거나 터미널을 재시작

3. 권한 확인

# 현재 사용자의 그룹 리스트 출력
groups

출력 결과에 docker 그룹이 포함되어 있다면 성공적으로 추가된 것이다.

Docker - Debian 서버에 docker, docker compose 설치하기

Aleph Kim — Sun, 9 Mar 2025 12:36:23 +0900

Docker 설치

# 필수 패키지 설치
sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates curl software-properties-common

# Docker GPG key 추가
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Docker 저장소 추가
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Docker 설치
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

# Docker 서비스 시작 및 자동 시작 설정
sudo systemctl start docker
sudo systemctl enable docker

# 설치 확인
docker -v

Docker Compose 설치

# Docker Compose 다운로드 및 설치
sudo curl -L "https://github.com/docker/compose/releases/download/$(curl -s https://api.github.com/repos/docker/compose/releases/latest | grep -Po '"tag_name": "\K.*?(?=")')/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# 실행 권한 추가
sudo chmod +x /usr/local/bin/docker-compose

# 설치 확인
docker-compose --version

Go - error strings should not end with punctuation or newlines (ST1005)

Aleph Kim — Sun, 9 Mar 2025 11:34:20 +0900

개요

Go로 새로운 프로젝트를 진행하던 중 vscode에서 errors.New("에러가 발생했습니다.") 부분에 노란색 밑줄이 생겼다.
그냥 냅둬도 서버 굴리는 데에 아무런 영향 없이 잘 돌아가지만 저 노란색 밑줄을 용납할 수 없어 조금 찾아보았다.

원인

오류 메시지의 문자열 첫 번째 글자가 대문자인 경우
오류 메시지의 문자열 끝에 마침표, 느낌표, 물음표 등의 구두점이나 개행 문자가 포함될 경우

해결방법

원인에 따라 첫 번째 글자를 소문자로 바꾸거나 끝에 특수문자가 들어가지 않도록 수정하면 된다.

하지만

하지만 한국인의 에러 메시지가 마침표로 끝나는 것은 일어날 수 있는 일이 아닌가? 나는 에러가 발생했습니다 라며 마침표 없이 끝나는 에러 메시지를 보고 싶지 않다.
고로 노란색 밑줄이 뜨지 않도록 vscode의 설정을 수정하기로 했다.

settings.json

"go.lintTool": "staticcheck",
"go.lintFlags": [
    "-exclude=ST1005"
]

파일을 저장한 후 vscode를 재시작하면 에러가 사라지게 된다.

Git - 특정 파일의 변경 사항 추적 제어 (올라간 파일 업데이트 안 하는 방법)

Aleph Kim — Sun, 9 Mar 2025 10:41:06 +0900

명령어	설명	예시
`git update-index --skip-worktree [파일명]`	지정한 파일에 대해 skip-worktree 플래그를 설정합니다. 로컬 변경 사항을 Git이 무시하도록 합니다.	`git update-index --skip-worktree config.txt`
`git update-index --no-skip-worktree [파일명]`	설정된 skip-worktree 플래그를 해제하여, 해당 파일의 변경 사항을 다시 추적하도록 합니다.	`git update-index --no-skip-worktree config.txt`
`git ls-files -v`	현재 추적 중인 파일들의 상태를 보여줍니다. `H`는 일반 상태, `S`는 skip-worktree가 설정된 파일입니다.	`git ls-files -v`

PHP - 내장 함수만으로 .env 파일 사용하기

Aleph Kim — Fri, 7 Mar 2025 10:25:10 +0900

개요

다른 라이브러리를 사용하지 않고 php 내장 함수만으로 .env 파일을 사용하는 방법에 관한 포스팅이다.

코드

loadEnv 함수

<?

<?php

/**
 * 환경 변수(.env) 파일을 로드하여 PHP의 환경 변수로 설정하는 함수
 *
 * @throws Exception .env 파일이 존재하지 않거나 읽을 수 없을 경우 예외를 발생
 * @return bool 환경 변수 로드가 성공하면 true를 반환
 */
function loadEnv() {
    // 루트 디렉토리에 있는 .env 파일 사용(환경에 따라 수정)
    $filePath = '/.env';

    // 파일이 존재하지 않으면 예외 처리
    if (!file_exists($filePath)) {
        throw new Exception("환경 변수 파일을 찾을 수 없습니다: $filePath");
    }

    // .env 파일을 한 번만 로드하도록 캐싱
    static $loaded = false;
    if ($loaded) return true;

    // 파일 읽기
    $lines = file($filePath, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);

    foreach ($lines as $line) {
        $line = trim($line);

        // 주석(#) 또는 빈 줄은 무시
        if ($line === '' || strpos($line, '#') === 0) continue;

        // '='가 없는 경우 예외 처리
        if (!strpos($line, '=')) continue;

        list($key, $value) = explode('=', $line, 2);
        $key = trim($key);
        $value = trim($value);

        // 환경 변수 설정 (중복 방지)
        if (!array_key_exists($key, $_ENV) && !array_key_exists($key, $_SERVER)) {
            putenv("$key=$value");
            $_ENV[$key] = $value;
            $_SERVER[$key] = $value;
        }
    }

    $loaded = true;
    return true;
}

사용 예시

<?

loadEnv();

// 환경 변수 가져오기
$db_host = getenv('DB_HOST');
$db_user = getenv('DB_USER');
$db_pass = getenv('DB_PASS');

echo "DB Host: $db_host, User: $db_user, Password: $db_pass";

후기

사랑해 php야 망하지만 말아줘...

HTML, CSS - song card slide

Aleph Kim — Thu, 6 Mar 2025 11:02:26 +0900

개요

프로젝트를 진행하며 flickity 라이브러리를 사용하여 만든 노래 슬라이드를 코드펜에 정리해보았다.

codepen

See the Pen song card slide by 김채민 (@aleph-kim) on CodePen.

CSS - 노멀라이즈 / 리셋

Aleph Kim — Wed, 5 Mar 2025 15:57:45 +0900

비교

특징	CSS 리셋 (Reset)	CSS 노멀라이즈 (Normalize)
기본 스타일 처리	브라우저 기본 스타일을 모두 제거하여 모든 요소를 초기화합니다.	브라우저 간 기본 스타일 차이를 보완하면서 유용한 기본 스타일은 그대로 유지합니다.
접근 방식	모든 요소의 스타일을 제거한 후, 개발자가 전부 직접 스타일을 정의합니다.	기본 스타일의 일관성을 높여 브라우저 차이를 줄이고 접근성을 개선합니다.
대표 라이브러리	Elad Shechter’s CSS Reset	normalize.css
장점	- 초기 상태에서 스타일링을 시작하여 예측 가능성이 높습니다. - 모든 요소를 동일한 상태로 만듭니다.	- 기본 스타일의 장점을 유지하면서 일관성을 제공합니다. - 접근성과 사용성을 개선합니다.
단점	- 기본 스타일을 모두 제거하므로 추가적인 스타일 설정이 필요합니다.	- 모든 브라우저 차이를 완벽하게 없애지는 못할 수 있습니다.

후기

복잡하게 생각하지 말고 그냥 reset.css 파일 하나 추가하는게 제일 간단할 것 같다.

reset.css

/***
    The new CSS reset - version 1.11.3 (last updated 25.08.2024)
    GitHub page: https://github.com/elad2412/the-new-css-reset
***/

/*
    Remove all the styles of the "User-Agent-Stylesheet", except for the 'display' property
    - The "symbol *" part is to solve Firefox SVG sprite bug
    - The "html" element is excluded, otherwise a bug in Chrome breaks the CSS hyphens property (https://github.com/elad2412/the-new-css-reset/issues/36)
 */
 *:where(:not(html, iframe, canvas, img, svg, video, audio):not(svg *, symbol *)) {
    all: unset;
    display: revert;
}

/* Preferred box-sizing value */
*,
*::before,
*::after {
    box-sizing: border-box;
}

/* Fix mobile Safari increase font-size on landscape mode */
html {
    -moz-text-size-adjust: none;
    -webkit-text-size-adjust: none;
    text-size-adjust: none;
}

/* Reapply the pointer cursor for anchor tags */
a, button {
    cursor: revert;
}

/* Remove list styles (bullets/numbers) */
ol, ul, menu, summary {
    list-style: none;
}

/* Firefox: solve issue where nested ordered lists continue numbering from parent (https://bugzilla.mozilla.org/show_bug.cgi?id=1881517) */
ol {
    counter-reset: revert;
}

/* For images to not be able to exceed their container */
img {
    max-inline-size: 100%;
    max-block-size: 100%;
}

/* removes spacing between cells in tables */
table {
    border-collapse: collapse;
}

/* Safari - solving issue when using user-select:none on the <body> text input doesn't working */
input, textarea {
    -webkit-user-select: auto;
}

/* revert the 'white-space' property for textarea elements on Safari */
textarea {
    white-space: revert;
}

/* minimum style to allow to style meter element */
meter {
    -webkit-appearance: revert;
    appearance: revert;
}

/* preformatted text - use only for this feature */
:where(pre) {
    all: revert;
    box-sizing: border-box;
}

/* reset default text opacity of input placeholder */
::placeholder {
    color: unset;
}

/* fix the feature of 'hidden' attribute.
   display:revert; revert to element instead of attribute */
:where([hidden]) {
    display: none;
}

/* revert for bug in Chromium browsers
   - fix for the content editable attribute will work properly.
   - webkit-user-select: auto; added for Safari in case of using user-select:none on wrapper element*/
:where([contenteditable]:not([contenteditable="false"])) {
    -moz-user-modify: read-write;
    -webkit-user-modify: read-write;
    overflow-wrap: break-word;
    -webkit-line-break: after-white-space;
    -webkit-user-select: auto;
}

/* apply back the draggable feature - exist only in Chromium and Safari */
:where([draggable="true"]) {
    -webkit-user-drag: element;
}

/* Revert Modal native behavior */
:where(dialog:modal) {
    all: revert;
    box-sizing: border-box;
}

/* Remove details summary webkit styles */
::-webkit-details-marker {
    display: none;
}

PHP - include, include_once, require, require_once 차이

Aleph Kim — Wed, 5 Mar 2025 12:10:31 +0900

함수	에러 처리	중복 포함	사용 용도	사용 용도 예시
include()	파일이 없으면 경고(E_WARNING) 발생, 실행 계속	중복 포함 가능	선택적 파일 포함	디자인 레이아웃 파일, 광고 배너, 언어 팩 파일
include_once()	파일이 없으면 경고(E_WARNING) 발생, 실행 계속 (단, 중복 방지)	중복 방지	선택적 파일 포함	플러그인 파일, 서브 기능 모듈, 임시 설정 파일
require()	파일이 없으면 치명적 오류(E_COMPILE_ERROR) 발생, 실행 중단	중복 포함 가능	필수 파일 포함	데이터베이스 연결 파일, 구성 파일, 핵심 라이브러리
require_once()	파일이 없으면 치명적 오류(E_COMPILE_ERROR) 발생, 실행 중단 (단, 중복 방지)	중복 방지	필수 파일 포함	프레임워크 초기화 파일, 핵심 모듈, 공통 유틸리티 클래스 파일

docker - docker compose networks 옵션과 드라이버 종류

Aleph Kim — Tue, 4 Mar 2025 23:02:42 +0900

개요

프로젝트를 진행하던 중 나의 작고 소중한 php 서버가 mysql 서버를 접근하지 못하여 찾아보니 컨테이너간 네트워크가 연결되어있지 않아 발생한 해프닝이었다.
딸깍만 하면 모든게 자동으로 되는 환경을 원하기 때문에 docker compose의 networks 옵션에 대해서 찾아보았다.

Docker Compose 네트워크 옵션

옵션	설명	예시
external	이미 만들어진 네트워크를 사용한다.(새로 만들지 않음)	`external: true`
name	네트워크의 이름을 정한다.	`name: my_custom_network`
driver	컨테이너들이 서로 연결되는 방식을 정한다.(default: bridge)	`driver: overlay`
driver_opts	드라이버가 필요로 하는 추가 설정한다.	`driver_opts: com.docker.network.driver.mtu: "1200"`
ipam	네트워크에서 사용할 IP 주소 범위, 서브넷, 게이트웨이를 정한다.	`ipam: driver: default; config: - subnet: "192.168.1.0/24", gateway: "192.168.1.1"`
internal	네트워크를 내부 전용으로 만들어 외부와 연결되지 않게 한다.	`internal: true`
attachable	Docker Swarm 모드에서 일반 컨테이너도 네트워크에 연결할 수 있게 한다.	`attachable: true`
labels	네트워크에 태그(이름표)를 붙여 쉽게 관리할 수 있게 한다.	`labels: project: my_project`

Docker 네트워크 드라이버 종류

드라이버	설명
bridge	한 컴퓨터 안에서 컨테이너끼리 서로 연결할 때 가장 기본적으로 사용하는 방식
overlay	여러 컴퓨터(서버)에서 컨테이너가 서로 연결될 수 있도록 한다.
host	컨테이너가 컴퓨터의 네트워크를 직접 사용한다. 속도가 빠르지만, 다른 컨테이너와 격리되지 않는다.
macvlan	컨테이너마다 고유한 네트워크 주소(MAC 주소)를 주어, 실제 다른 기기처럼 보이게 한다.
none	네트워크 연결을 하지 않는다. 컨테이너는 자기 자신만 사용할 수 있다.

옵션 사용 예시

version: '3.8'

services:
  app:
    image: nginx:latest
    networks:
      - external_net
      - custom_net

networks:
  # 이미 만들어진 네트워크 사용
  external_net:
    external: true

  # 이 Compose가 만드는 네트워크
  custom_net:
    name: custom_bridge_network  # 네트워크 이름
    driver: bridge               # bridge 드라이버 사용
    driver_opts:
      com.docker.network.driver.mtu: "1200"  # 추가 옵션 설정(최대 전송 단위를 1200로 제한)
    ipam:
      driver: default          # 기본 IP 관리 드라이버 사용
      config:
        - subnet: "192.168.10.0/24"  # 서브넷 범위 설정
          gateway: "192.168.10.1"     # 게이트웨이 설정
    internal: true             # 내부 전용 네트워크로 만듦
    attachable: true           # 일반 컨테이너도 연결 가능하게
    labels:
      project: my_project      # 태그

컨테이너간 네트워크 연결 예시 코드

mysql/docker-compose.yml

version: '3.8'

services:
  db:
    image: mysql:8.0
    container_name: mysql_dev
    restart: always
    ports:
      - 3306:3306
    environment:
      MYSQL_ROOT_PASSWORD: MYSQL_ROOT_PASSWORD
      TZ: Asia/Seoul
    networks:
      - mysql_net  # 사용할 네트워크 지정

networks:
  mysql_net:
    name: mysql_net  # 생성할 네트워크 이름

php/docker-compose.yml

version: '3.8'

services:
  web:
    build: .
    ports:
      - "8080:80"
    volumes:
      - .:/var/www/html
    networks:
      - mysql_net # 사용할 네트워크 지정

networks:
  mysql_net:
    external: true # 네트워크가 외부에 이미 존재함을 지정

후기

나는 단순히 컨테이너간 네트워크를 최대한 편하게 연결하고 싶었을 뿐인데 생각보다 깊어진 것 같다...

한글명언 OPEN API 기술 설명서

Aleph Kim — Tue, 4 Feb 2025 15:21:14 +0900

한글명언 OPEN API 기술설명서

본 문서는 한글명언 OPEN API 프로젝트의 전반적인 시스템 구성, 사용 기술(버전 포함), 모듈별 역할, 실행 방법, 배포 환경, 관련 링크 정보 및 CI/CD 파이프라인 설정에 관한 설명서입니다.

1. 개요

api key나 복잡한 인증 필요없이 한글로 번역한 명언을 받아볼 수 있는 OPEN API 서비스 구현

2. 관련 링크

아래는 프로젝트와 관련된 다양한 링크 정보입니다.

API 문서: https://quote.aleph.kr/api-docs/
(API 문서 페이지)
관리자 페이지: https://quote.aleph.kr/admin
(관리자 전용 명언 관리 페이지)
깃허브: https://github.com/Aleph-Kim/korean-quote
(프로젝트 소스 코드 페이지)

3. 시스템 아키텍처 ️

3.1. 시스템 구성

[클라이언트 (프론트엔드)]
• EJS 템플릿 엔진: 동적 HTML 페이지 렌더링
• Tailwind CSS: 빠르고 효율적인 UI 스타일링

[서버 (백엔드)]
• Express.js: RESTful API 엔드포인트 제공
• 미들웨어: 요청 파싱, 쿠키 및 세션 관리, CORS 설정 등

[데이터베이스]
• PostgreSQL: 명언 데이터를 저장
• Sequelize ORM: 데이터베이스와의 객체 지향적 인터랙션

[배포 및 인프라]
• Docker: 컨테이너 기반 배포 관리
• Nginx Proxy Manager: 프록시 관리 및 SSL/TLS 인증서 발급
• GCP (Google Cloud Platform): 클라우드 인프라 배포

3.2. 데이터 흐름

요청 처리 – 클라이언트가 /quote/random 등 API 엔드포인트로 HTTP 요청을 전송합니다.
비즈니스 로직 처리 – Express 라우터에서 요청을 처리하며, 필요시 Sequelize를 이용해 데이터베이스와 상호작용합니다.
응답 생성 – 조회된 데이터(랜덤 명언 등)를 JSON 형식 또는 EJS 템플릿을 통해 HTML로 응답합니다.
에러 처리 – 에러 발생 시 적절한 상태 코드와 메시지로 클라이언트에 응답합니다.

4. 사용 기술 및 버전 ️

4.1. 백엔드

Express.js – Node.js 기반 웹 프레임워크, 버전: ^4.19.2
EJS – 서버 사이드 템플릿 엔진, 버전: ^3.1.10
body-parser – HTTP 요청 데이터 파싱, 버전: 1.20.2
cookie-parser – 쿠키 파싱 미들웨어, 버전: ^1.4.7
express-session – 세션 관리, 버전: ^1.18.1
express-validator – 요청 데이터 유효성 검증, 버전: ^7.2.1
multer – 파일 업로드 처리, 버전: ^1.4.5-lts.1
cors – CORS 설정, 버전: ^2.8.5

4.2. 데이터베이스

PostgreSQL – 관계형 데이터베이스 시스템, 버전: ^16.4
Sequelize – ORM (Object Relational Mapping) 라이브러리, 버전: ^6.37.3

4.3. 기타 도구

dotenv – 환경 변수 관리, 버전: ^16.4.5
apidoc – API 문서 자동 생성 도구, 버전: ^1.2.0
Tailwind CSS – 유틸리티 클래스 기반 CSS 프레임워크, 버전: ^3.4.17
PostCSS – CSS 전처리 도구, 버전: ^8.5.1
Autoprefixer – 자동 벤더 프리픽스 추가 도구, 버전: ^10.4.20
nodemon – 파일 변경 시 자동 서버 재시작 도구, 버전: ^3.1.4

4.4. 배포 및 인프라 관련 도구

Docker – 컨테이너 기반 배포 관리 도구, 버전: ^26.1.4
Nginx Proxy Manager – 프록시 관리 및 SSL/TLS 인증서 발급 도구, 버전: ^2.11.3
GCP (Google Cloud Platform) – 클라우드 인프라 서비스

5. 모듈 구성 및 주요 기능

5.1. 서버 엔트리 포인트

파일: src/app.js
역할: Express 애플리케이션 인스턴스 생성, 미들웨어 설정( body-parser, cookie-parser, cors, session 등 ), 라우터 및 API 엔드포인트 연결, 에러 핸들링 미들웨어 설정, 서버 포트 리스닝 시작

5.2. 라우터 모듈

경로: src/routes/
주요 기능:
• 랜덤 명언 조회 API: GET /quote/random
• 오늘의 명언 조회 API: GET /quote/today
• 관리자페이지: GET /admin

5.3. 데이터베이스 모델

Sequelize 모델:
• Quote 모델 – 속성: id, body (명언 내용), author (남긴이), createdAt, updatedAt 등
• 모델 간 관계 및 데이터 유효성 검증 설정

5.4. 뷰 템플릿

EJS 템플릿
• 경로: views/
• 동적 HTML 렌더링을 통해 명언 데이터를 사용자에게 제공

6. 빌드 및 실행 환경

6.1. 의존성 설치

터미널에서 npm install 명령을 실행하여 의존성 패키지를 설치합니다.

6.2. 환경 변수 설정

프로젝트 루트에 .env 파일을 생성하고, 다음과 같이 설정합니다:

PORT=3000
DATABASE_URL=postgres://username:password@localhost:5432/database_name
SESSION_SECRET=your_secret_key

6.3. 실행 명령어

개발 모드 실행 (nodemon 사용): npm run dev
프로덕션 모드 실행: npm start
Tailwind CSS 빌드 (실시간 감시): npm run css
Tailwind CSS 정적 빌드: npm run build:css
API 문서 생성 (apidoc 사용): npm run api

7. 배포 및 인프라 설정 ☁️

7.1. Docker 기반 배포

Docker Compose 파일 (docker-compose.yml)

version: '3.8'

services:
  prod:
    build:
      context: .
      dockerfile: Dockerfile.prod
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      - NODE_ENV=development

  dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      - NODE_ENV=development

주요 내용

버전: Compose 파일 버전 3.8 사용
services: prod와 dev 두 가지 서비스로 구성
- prod 서비스:
  - 현재 디렉토리를 빌드 컨텍스트로 사용하며, Dockerfile.prod를 사용하여 이미지를 빌드
  - 포트 3000을 호스트와 컨테이너 간 매핑
  - 소스코드와 node_modules 디렉토리를 볼륨으로 연결하여 실시간 동기화
  - NODE_ENV 환경 변수를 development로 설정
- dev 서비스: prod와 동일한 방식으로 설정하지만, 별도의 Dockerfile.dev를 사용하여 개발 환경에 맞는 설정 가능

Dockerfile.prod

# 베이스 이미지 설정
FROM node:20

# 작업 디렉토리 설정
WORKDIR /app

# 패키지 설치를 위해 package.json 및 package-lock.json 복사
COPY package*.json ./

# 패키지 설치 (production 모드)
RUN npm install --production

# 어플리케이션 코드 복사
COPY . .

# Tailwind CSS 빌드
RUN npm run build:css

# 어플리케이션이 실행될 포트 설정
EXPOSE 3000

# 서버 실행
CMD [ "npm", "run", "start" ]

주요 내용

베이스 이미지: node:20 사용
작업 디렉토리: /app으로 설정
패키지 설치: package.json 및 package-lock.json 파일을 복사 후, production 모드로 의존성 설치
코드 복사: 전체 소스 코드를 컨테이너 내 /app 디렉토리로 복사
Tailwind CSS 빌드: npm run build:css를 통해 CSS 빌드 수행
포트 노출: 3000번 포트를 외부에 노출
실행 명령어: npm run start로 서버 실행

7.2. Nginx Proxy Manager 설정

역할: 도메인 프록시 설정, SSL 인증서 관리, Docker 컨테이너로 배포된 API 서버 접근 제어
설정 예시: API 서버 내부 주소(예: http://localhost:3000)를 프록시 대상으로 등록하고, HTTPS 및 필요한 포트 포워딩 설정

7.3. GCP 배포

활용 방법: Compute Engine, Kubernetes Engine 또는 Cloud Run을 통해 컨테이너 기반 애플리케이션 배포
Docker 이미지를 빌드 후 GCP Container Registry 또는 Artifact Registry에 업로드, 배포 진행
Nginx Proxy Manager와 연동하여 도메인 관리 및 SSL 인증서 적용

8. 에러 처리 및 로깅

8.1. 에러 처리

400 Bad Request – 요청 데이터가 올바르지 않을 경우, 상태 코드 400과 에러 메시지 반환
404 Not Found – 존재하지 않는 엔드포인트 접근 시, 상태 코드 404와 에러 메시지 반환
500 Internal Server Error – 서버 내부 오류 발생 시, 상태 코드 500과 에러 메시지 반환 및 로깅을 통해 원인 분석

8.2. 로깅

서버 로그는 콘솔 출력 및 필요에 따라 파일로 저장
에러 발생 시 스택 트레이스를 함께 기록하여 디버깅에 활용

9. 보안 고려 사항

환경 변수 관리: 민감한 정보는 .env 파일로 관리하고, 버전 관리 시스템에서 제외(.gitignore 설정)
세션 관리: express-session을 사용하여 세션을 안전하게 관리하며, SESSION_SECRET은 반드시 안전한 값으로 설정
CORS 정책: 허용된 도메인만 접근하도록 CORS 미들웨어 설정
데이터 유효성 검증: express-validator를 통해 입력 데이터 검증을 수행하여 SQL Injection 및 XSS 공격 대비

10. CI/CD Pipeline (GitHub Actions)

프로젝트는 GitHub Actions를 활용하여 CI/CD 파이프라인을 구축하고 있습니다.
파이프라인은 master 브랜치에 대한 push 또는 pull request 이벤트 발생 시 실행되며, Docker 이미지를 빌드하여 Docker Hub에 업로드 후, SSH를 통해 원격 서버에 배포합니다.

name: CI/CD Pipeline

on:
  push:
    branches:
      - master
  pull_request:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to DockerHub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build Docker image
        run: |
          docker build . -f Dockerfile.prod -t ${{ secrets.DOCKER_USERNAME }}/${{ secrets.PROJECT_NAME }}:${{ github.sha }}
          docker tag ${{ secrets.DOCKER_USERNAME }}/${{ secrets.PROJECT_NAME }}:${{ github.sha }} ${{ secrets.DOCKER_USERNAME }}/${{ secrets.PROJECT_NAME }}:latest

      - name: Push Docker image to Docker Hub
        run: |
          docker push ${{ secrets.DOCKER_USERNAME }}/${{ secrets.PROJECT_NAME }}:${{ github.sha }}
          docker push ${{ secrets.DOCKER_USERNAME }}/${{ secrets.PROJECT_NAME }}:latest

  deploy:
    runs-on: ubuntu-latest
    needs: build

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Deploy to server
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.SERVER_IP }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          port: 22
          script: |
            sudo docker pull ${{ secrets.DOCKER_USERNAME }}/${{ secrets.PROJECT_NAME }}:latest
            sudo docker stop ${{ secrets.PROJECT_NAME }} || true
            sudo docker rm ${{ secrets.PROJECT_NAME }} || true
            sudo docker run -d -p 3000:3000 --name ${{ secrets.PROJECT_NAME }} --env-file ${{ secrets.ENV_PATH }} ${{ secrets.DOCKER_USERNAME }}/${{ secrets.PROJECT_NAME }}:latest

주요 내용

트리거: push 및 pull_request 이벤트가 master 브랜치에서 발생하면 파이프라인 실행
빌드 단계: Repository 체크아웃, Docker Buildx 설정, Docker Hub 로그인, Dockerfile.prod를 사용한 이미지 빌드 및 태그 생성, Docker Hub로 이미지 업로드
배포 단계: 빌드 완료 후 SSH로 원격 서버 접속, 최신 이미지 pull, 기존 컨테이너 중지 및 삭제 후 새 컨테이너 실행 (포트 3000 매핑 및 환경 변수 파일 적용)

11. 마무리

추가 문의나 개선 요청이 있으시면 언제든지 연락 부탁드립니다.

개발자 이메일 : dktjdej@naver.com

감사합니다!

PostgreSQL - 한글 정렬

Aleph Kim — Tue, 4 Feb 2025 12:20:12 +0900

개요

PostgreSQL db로 프로젝트를 진행하던 중 한글 컬럼을 기준으로 정렬을 했더니 정렬이 이상하게 되는걸 발견했다. 이를 해결하는 방법을 정리해본다.

정렬이 이상하다..

방법 1 - pg_database 업데이트

첫 번째 방법은 데이터베이스의 collate 값을 업데이트하는 방식으로 간단하게 데이터베이스 전체에 로케일 변경이 가능하다.
이 방법은 시스템에 ko_KR.utf8 로케일이 미설치된 경우 실패하므로, 해당 로케일이 설치되어 있는지 확인(명령어: locale -a | grep ko_)해야한다.

select datname, datdba, encoding, datcollate, datctype from pg_database; -- 현재 데이터베이스 로케일 확인

UPDATE pg_database SET datcollate = 'ko_KR.utf8' WHERE datname = '데이터베이스명'; -- 로케일 변경

주의사항

ko_KR.utf8을 새로 설치한 경우 데이터베이스에 바로 적용 가능한 것이 아닌 이후로 생성하는 데이터베이스에만 적용이 가능하다. 따라서 기존 데이터베이스에 적용을 하고 싶다면 기존 데이터를 백업하고 데이터베이스를 재생성하는 과정이 불가피하다.
PostgreSQL에서 pg_database와 같은 시스템 카탈로그를 직접 수정하는 것은 공식적으로 권장하지 않는 방법이라고 한다.

방법 2 - ko_KR.utf8로 데이터베이스 생성

두 번째 방법은 데이터베이스 생성 시에 ko_KR.utf8로 데이터베이스를 생성하는 방법이다.
이 방법은 시스템에 ko_KR.utf8 로케일이 미설치된 경우 실패하므로, 해당 로케일이 설치되어 있는지 확인(명령어: locale -a | grep ko_)해야한다.

CREATE DATABASE 데이터베이스명
  LC_COLLATE 'ko_KR.utf8' -- 문자열 정렬 규칙을 지정
  LC_CTYPE 'ko_KR.utf8' -- 문자 분류(대소문자 구분, 문자 유형 등)를 지정
  TEMPLATE template0; -- 기본 템플릿이 아닌 template0을 사용함으로써, 데이터베이스 생성 시 기존의 로케일 설정이 영향을 주지 않도록

가능하다면 기존 데이터베이스를 백업한 후 해당 방법으로 데이터베이스를 재생성하는 것이 가장 바람직하다고 생각한다.

방법 3 - 컬럼에 COLLATE "ko-KR-x-icu" 설정

세 번째 방법은 테이블의 컬럼에 COLLATE "ko-KR-x-icu" 옵션을 설정하는 방식이다.

ko-KR-x-icu란?

ICU의 커스텀 국제화 규칙을 반영하는 ICU 라이브러리 전용 확장 로케일로 ko_KR.utf8과 큰 차이 없음

테이블 생성 시

CREATE TABLE example (
    name VARCHAR(100) COLLATE "ko-KR-x-icu"
);

테이블 수정 시

ALTER TABLE example
ALTER COLUMN name TYPE VARCHAR(255) COLLATE "ko-KR-x-icu" USING name::VARCHAR(255);

위와 같이 설정하면 복잡한 과정 없이 바로 한글 로케일 적용이 가능하다. 다만 개인적으로는 컬럼마다 일일히 설정하는 것이 임시방편에 불과하다고 생각해 2번 방법을 권장하고 싶다.

후기

이번에는 docker 컨테이너로 구성된 psql 서버라서 단순 한글 정렬로부터 파생된 추가 작업이 꼬리에 꼬리를 물고 이어지기 때문에 너무 귀찮아 임시방편으로 처리하게 되었지만 다음에 한글 정렬을 구현할 때는 데이터베이스 생성 시부터 ko_KR.utf8 로케일을 지정할 수 있도록 해야겠다.

어쨌든 완료!

git - 커밋 메시지 수정

Aleph Kim — Wed, 22 Jan 2025 15:15:50 +0900

개요

정리하고 싶지 않았지만 자꾸 찾아보게 되고... 안 찾고 기억을 더듬어 마음대로 하다가 하루종일 작업한 내용을 날릴 뻔하여 부랴부랴 정리하게 된 커밋 메시지 수정 방법에 관한 글이다.

방법

현재 브랜치의 마지막 커밋 메시지를 수정하기

git commit --amend

위 명령을 입력하면 마지막 커밋 메시지를 수정할 수 있다.
메시지를 원하는 대로 수정한 후 저장하고 종료(:wq!)하면 커밋 메시지가 변경된다.

이전 커밋 메시지 수정하기 (예: 마지막 3개의 커밋)

git rebase -i HEAD~3

위 명령을 실행하면 아래와 같은 목록이 열린다.

pick abcdef1 커밋 메시지 1
pick bcdefg2 커밋 메시지 2
pick cdefgh3 커밋 메시지 3

여기서 수정하고 싶은 커밋 앞의 pick을 reword(또는 줄여서 r)로 변경한다.

pick abcdef1 커밋 메시지 1
reword bcdefg2 커밋 메시지 2  # 여기서 커밋 메시지를 수정할 예정
pick cdefgh3 커밋 메시지 3

파일을 저장하고 종료하면, Git이 선택한 커밋들의 메시지를 수정할 수 있는 상태로 들어간다.

커밋 메시지 2

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Date:      Wed Jan 22 14:30:38 2025 +0900
...

메시지를 원하는 대로 수정한 후 저장하고 종료(:wq!)하면 커밋 메시지가 변경된다.

주의사항

커밋 메시지를 수정하면 커밋의 해시 값이 변경된다.
이미 공유된 커밋의 메시지를 변경할 경우, 다른 사용자와 충돌이 발생할 수 있으니 주의해야 한다.
특히 원격 저장소에 푸시된 커밋을 수정할 경우 강제 푸시(git push --force)가 필요하므로 신중하게 처리해야 한다.