sungro815/giftcon_dev

Fork 0

sungro815 0010cc69be 관리자 로그인

2026-02-04 16:55:00 +09:00

7.1 KiB

Raw Blame History

런타임 점검/테스트 & 장애 대응 체크리스트 (Gifticon Platform)

이 문서는 Gifticon Platform 도커 환경에서

연동관계가 정상 작동하는지 테스트
문제 발생(500/큐/스케줄/메일) 시 어디부터 확인할지
운영 배포 루틴

을 한 번에 정리한 문서다.

3. 런타임 정상 동작 점검 (필수)

3.2 Laravel 기본 상태 확인 (필수)

docker exec -it gifticon-app php artisan about

확인 포인트:

Environment: production
Debug Mode: OFF
Cache: redis
Session: redis
Queue: redis
Mail: smtp
URL: 프록시 뒤에서 도메인이 정상적으로 잡히는지 (Host/Forwarded 헤더 전달 정상 여부)

3.3 Redis 연결 확인

Redis 자체:

docker exec -it gifticon-redis redis-cli ping
# PONG 기대

Laravel cache 테스트:

docker exec -it -e HOME=/tmp gifticon-app php artisan tinker
> cache()->put('ping','pong',60);
> cache()->get('ping');
# "pong" 기대

3.4 DB 연결 확인

docker exec -it -e HOME=/tmp gifticon-app php artisan tinker
> \DB::select('select 1 as ok');
# ok=1 기대

3.5 Queue(워커) 동작 확인

권장: Job 클래스로 테스트

테스트 Job 예: QueuePingJob (ShouldQueue)

dispatch 후 워커가 처리했는지 로그로 확인

dispatch:

docker exec -it -e HOME=/tmp gifticon-app php artisan tinker
> dispatch(new \App\Jobs\QueuePingJob());

워커 로그:

docker logs --tail=200 gifticon-worker

Laravel log:

docker exec -it gifticon-app sh -lc "tail -n 200 storage/logs/laravel.log | tail -n 200"

중요:

dispatch(function(){ ... }) 형태의 Closure Job은 운영 금지
직렬화 오류(“Failed to serialize job…”)가 발생할 수 있음 → 항상 Job 클래스로 구현

3.6 Scheduler 동작 확인

스케줄 등록 확인:

docker exec -it gifticon-app php artisan schedule:list

스케줄러 컨테이너 실행 확인:

docker exec -it gifticon-scheduler ps aux
# php artisan schedule:work 확인

스케줄이 실제 실행되는지(로그 기반):

예: 매분 실행되는 Closure/Job을 하나 두고 로그 확인

3.7 Mail 발송 확인

메일은 “발송 성공/실패 로그”를 남기는 것이 운영에 유리하다.

메일 발송 로그 확인:

docker exec -it gifticon-app sh -lc "tail -n 200 storage/logs/laravel.log | egrep 'mail_send_attempt|mail_send_done|mail_send_debug|mail failed' | tail -n 200"

메일 템플릿 수정 후 반영이 안 되면:

view:clear + optimize:clear + gifticon-worker 재시작이 핵심

4. 장애/오류 발생 시 “우선 확인 순서”

4.1 사이트 500 에러 (웹/관리자 공통)

Nginx 로그 확인:

docker logs --tail=200 gifticon-web
docker logs --tail=200 gifticon-admin

Laravel 앱 로그 확인:

docker exec -it gifticon-app sh -lc "tail -n 300 storage/logs/laravel.log"

env/cache 꼬임 대응(가장 흔함):

docker exec -it gifticon-app php artisan optimize:clear
docker restart gifticon-app gifticon-worker gifticon-scheduler

퍼미션/스토리지 확인:

storage/logs, storage/framework/* 쓰기 실패 여부
UID/GID 매핑, 호스트 권한 점검

4.2 Queue 관련 장애

(A) RedisException: Connection refused

원인 후보:

redis 컨테이너 다운
env/config cache 꼬임으로 redis host가 127.0.0.1로 잡힘
워커가 예전 캐시 상태 유지

네트워크 점검:

docker exec -it gifticon-worker sh -lc 'getent hosts gifticon-redis || true'
docker exec -it gifticon-worker sh -lc 'nc -vz gifticon-redis 6379 || true'

조치:

docker exec -it gifticon-app php artisan optimize:clear
docker restart gifticon-worker gifticon-app

(B) Closure Job 직렬화 오류

증상:

“Failed to serialize job of type CallQueuedClosure …”

조치:

Closure dispatch 금지
Job 클래스로 전환

4.3 Scheduler 관련 장애

(A) withoutOverlapping 에러

증상:

“A scheduled event name is required…”

조치:

withoutOverlapping() 전에 ->name('...') 필수

(B) Class not found (Job 클래스 없음)

증상:

“Class App\Jobs\Xxx not found”

조치:

클래스 파일 존재/namespace 확인
캐시 제거 후 scheduler 재시작

docker exec -it gifticon-app php artisan optimize:clear
docker restart gifticon-scheduler

4.4 Mail 템플릿 반영 안 됨 / 변수 미정의

(A) 템플릿 수정했는데 메일이 그대로 옴

원인:

view cache
worker가 예전 캐시 상태로 계속 발송

조치:

docker exec -it gifticon-app php artisan view:clear
docker exec -it gifticon-app php artisan optimize:clear
docker restart gifticon-worker gifticon-app

(B) Undefined variable (Blade)

원인:

템플릿에서 사용 변수 준비(@php 블록)가 없거나 위치가 뒤에 있음
include/section 구조상 변수가 선언되기 전에 참조됨

조치:

@section('content') 시작 직후 @php ... @endphp로 변수를 선행 선언

5. 운영용 하드닝(보안/안정성) 권장

5.1 포트 직접 노출 최소화

운영에서는 8091/8092를 0.0.0.0로 열지 않고 reverse proxy 내부 네트워크로만 열어두는 구성을 권장.

5.2 healthcheck 추가 권장

mariadb: mysqladmin ping
redis: redis-cli ping
app: php-fpm 포트 확인 또는 간단 artisan health command
web/admin: curl localhost

5.3 read-only + tmpfs

Nginx 컨테이너는 가능하면:

read_only: true
tmpfs: /var/cache/nginx, /var/run 로 런타임 쓰기영역만 허용

5.4 관리자 접근 정책

관리자 도메인은 허용 IP만 접근 가능하게 (Nginx allow/deny)
비허용 IP는 웹 도메인으로 리다이렉트(정책 선택)
관리자 서비스는 web과 DB 권한/접근 범위를 분리하는 것이 최종 목표

6. 데이터 영속성/백업

6.1 MariaDB 데이터 보존

db_data 볼륨이 유지되는 한 데이터 보존
docker compose down은 기본적으로 볼륨 삭제하지 않음
아래는 데이터 삭제됨: docker compose down -v

6.2 Redis 데이터 보존

redis_data 볼륨이 유지되는 한 데이터 보존(appendonly)

6.3 개발 DB 백업 예시

docker exec -it gifticon-db sh -lc 'mariadb-dump -uroot -p"$MARIADB_ROOT_PASSWORD" gifticon > /tmp/gifticon.sql'
docker cp gifticon-db:/tmp/gifticon.sql ./backup/gifticon.sql

운영에서 RDS 사용 시:

RDS 자동 백업/스냅샷 정책 권장

7. 운영 배포 절차(권장 루틴)

코드 업데이트 (git pull 등)
빌드/업

docker compose up -d --build

Laravel 캐시 정리 및 재생성

docker exec -it gifticon-app php artisan optimize:clear
docker exec -it gifticon-app php artisan config:cache
docker exec -it gifticon-app php artisan route:cache
docker exec -it gifticon-app php artisan view:cache

worker/scheduler 재시작

docker restart gifticon-worker gifticon-scheduler

7.1 KiB Raw Blame History