314 lines
7.1 KiB
Markdown
314 lines
7.1 KiB
Markdown
|
|
|
|
|
|
# 런타임 점검/테스트 & 장애 대응 체크리스트 (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
|
|
```
|