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

이 문서는 Gifticon Platform 도커 환경에서  
- **연동관계가 정상 작동하는지 테스트**  
- **문제 발생(500/큐/스케줄/메일) 시 어디부터 확인할지**  
- **운영 배포 루틴**  

을 한 번에 정리한 문서다.

---

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

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

```bash
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 자체:

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

Laravel cache 테스트:

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

---

### 3.4 DB 연결 확인

```bash
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:

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

워커 로그:

```bash
docker logs --tail=200 gifticon-worker
```

Laravel log:

```bash
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 동작 확인

스케줄 등록 확인:

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

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

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

스케줄이 실제 실행되는지(로그 기반):
- 예: 매분 실행되는 Closure/Job을 하나 두고 로그 확인

---

### 3.7 Mail 발송 확인

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

메일 발송 로그 확인:

```bash
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 로그 확인:

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

Laravel 앱 로그 확인:

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

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

```bash
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로 잡힘
- 워커가 예전 캐시 상태 유지

네트워크 점검:

```bash
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'
```

조치:

```bash
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 재시작

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

---

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

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

원인:
- view cache
- worker가 예전 캐시 상태로 계속 발송

조치:

```bash
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 백업 예시
```bash
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. 운영 배포 절차(권장 루틴)

1) 코드 업데이트 (git pull 등)

2) 빌드/업
```bash
docker compose up -d --build
```

3) Laravel 캐시 정리 및 재생성
```bash
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
```

4) worker/scheduler 재시작
```bash
docker restart gifticon-worker gifticon-scheduler
```