From a68a9ba098022055533d008619ba954de41b7aaa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B6=8C=ED=98=81=EC=84=B1?= Date: Wed, 25 Feb 2026 10:48:23 +0900 Subject: [PATCH] =?UTF-8?q?docs:MNG=20500=20=EC=97=90=EB=9F=AC=20=EC=A7=84?= =?UTF-8?q?=EB=8B=A8=20=EA=B2=B0=EA=B3=BC=20=EB=B0=98=EC=98=81=20=E2=80=94?= =?UTF-8?q?=20php8.4-soap=20=EC=84=A4=EC=B9=98,=20=EB=A1=9C=EA=B7=B8=20?= =?UTF-8?q?=EA=B2=BD=EB=A1=9C/=EA=B6=8C=ED=95=9C=20=EB=AC=B8=EC=84=9C?= =?UTF-8?q?=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 11-server-setup: PHP 확장 목록에 php8.4-soap 추가 - 02-daily-operations: MNG 로그 경로 수정 (shared → current, 심링크 아님) - 03-service-prod: Redis 용도 정확하게 테이블로 정리 (캐시=redis, 세션=database) - 05-deployment: MNG 배포 시 storage/logs 권한 경고 추가, 배포 후 확인에 MNG 로그 추가 - 08-troubleshooting: MNG 500 에러 트러블슈팅 사례 추가 (2026-02-25 실제 사례) Co-Authored-By: Claude Opus 4.6 --- deploys/ops-manual/02-daily-operations.md | 4 +-- deploys/ops-manual/03-service-prod.md | 8 ++++- deploys/ops-manual/05-deployment.md | 11 ++++++ deploys/ops-manual/08-troubleshooting.md | 44 +++++++++++++++++++++++ deploys/ops-manual/11-server-setup.md | 2 +- 5 files changed, 65 insertions(+), 4 deletions(-) diff --git a/deploys/ops-manual/02-daily-operations.md b/deploys/ops-manual/02-daily-operations.md index b6712d6..ab664d1 100644 --- a/deploys/ops-manual/02-daily-operations.md +++ b/deploys/ops-manual/02-daily-operations.md @@ -95,8 +95,8 @@ sudo tail -f /var/log/php8.4-fpm.log # API 로그 sudo tail -f /home/webservice/api/shared/storage/logs/laravel.log -# Admin(MNG) 로그 -sudo tail -f /home/webservice/mng/shared/storage/logs/laravel.log +# Admin(MNG) 로그 — storage/logs가 shared 심링크가 아니므로 current 경로 사용 +sudo tail -f /home/webservice/mng/current/storage/logs/laravel.log # API Stage 로그 sudo tail -f /home/webservice/api-stage/shared/storage/logs/laravel.log diff --git a/deploys/ops-manual/03-service-prod.md b/deploys/ops-manual/03-service-prod.md index 4503ea2..c28d524 100644 --- a/deploys/ops-manual/03-service-prod.md +++ b/deploys/ops-manual/03-service-prod.md @@ -158,7 +158,13 @@ redis-cli ttl "키이름" # TTL 확인 redis-cli flushall # 전체 삭제 (주의: 세션도 삭제됨) ``` -**용도:** Laravel 캐시, 세션, 큐 (QUEUE_CONNECTION=redis) +**용도:** + +| 기능 | 드라이버 | .env 설정 | +|------|---------|----------| +| 캐시 | Redis | CACHE_STORE=redis | +| 세션 | Database | SESSION_DRIVER=database | +| 큐 | Redis | Supervisor에서 `queue:work redis` 명시 | --- diff --git a/deploys/ops-manual/05-deployment.md b/deploys/ops-manual/05-deployment.md index be171fa..486222c 100644 --- a/deploys/ops-manual/05-deployment.md +++ b/deploys/ops-manual/05-deployment.md @@ -573,6 +573,16 @@ ls -1dt */ | tail -n +4 | xargs rm -rf 2>/dev/null || true API와 동일한 releases/shared 구조. 차이점: npm build 추가, Queue Worker 재시작 불필요. +> **주의: storage/logs 권한 문제** +> MNG Jenkinsfile은 `storage/logs`를 shared로 심링크하지 않고 릴리즈 디렉토리에 `mkdir`로 생성한다. +> 이 디렉토리는 `hskwon:hskwon` 소유로 생성되므로, PHP-FPM(`www-data`)이 로그를 쓸 수 없다. +> 배포 후 500 에러가 발생하는데 로그가 비어있으면 다음을 실행: +> ```bash +> sudo chown www-data:webservice /home/webservice/mng/current/storage/logs/ +> sudo chown www-data:webservice /home/webservice/mng/current/storage/logs/laravel.log 2>/dev/null +> ``` +> 근본 해결: Jenkinsfile에 `chown` 명령 추가 또는 storage/logs를 shared 심링크로 변경. + ### Jenkinsfile (mng/Jenkinsfile) ```groovy @@ -868,6 +878,7 @@ sudo supervisorctl status # 에러 로그 sudo tail -20 /var/log/nginx/api.sam.it.kr.error.log sudo tail -20 /home/webservice/api/shared/storage/logs/laravel.log +sudo tail -20 /home/webservice/mng/current/storage/logs/laravel.log # HTTP 응답 확인 curl -sI https://api.sam.it.kr diff --git a/deploys/ops-manual/08-troubleshooting.md b/deploys/ops-manual/08-troubleshooting.md index 5c64847..3b2b27e 100644 --- a/deploys/ops-manual/08-troubleshooting.md +++ b/deploys/ops-manual/08-troubleshooting.md @@ -258,6 +258,50 @@ sudo chmod -R 775 /home/webservice/api/current/bootstrap/cache --- +### MNG 500 에러 (storage/logs 권한 + SOAP) + +**증상:** mng.codebridge-x.com 특정 페이지에서 500 에러. Laravel 로그에 기록 없음. + +**배경:** MNG Jenkinsfile 배포 시 `storage/logs`는 shared로 심링크되지 않고 릴리즈 디렉토리에 직접 생성됨. +따라서 `hskwon:hskwon` 소유로 생성되어 `www-data`(PHP-FPM)가 로그를 쓸 수 없음. + +**진단 순서:** + +```bash +# 1. 실제 로그 위치 확인 (shared가 아닌 current) +ls -la /home/webservice/mng/current/storage/logs/laravel.log + +# 2. 로그 파일 소유자 확인 — hskwon이면 www-data가 쓸 수 없음 +# 3. nginx 접근 로그에서 500 확인 +sudo tail -20 /var/log/nginx/mng.codebridge-x.com.access.log | grep " 500 " +``` + +**조치:** + +```bash +# 로그 권한 수정 (배포마다 필요) +sudo chown www-data:webservice /home/webservice/mng/current/storage/logs/ +sudo chown www-data:webservice /home/webservice/mng/current/storage/logs/laravel.log + +# 로그 확인 후 실제 에러 파악 +cat /home/webservice/mng/current/storage/logs/laravel.log +``` + +**실제 사례 (2026-02-25):** + +1. 최초 증상: `Table 'sam.cache' doesn't exist` → `CACHE_STORE=database`였으나 cache 테이블 미존재 +2. 해결: `.env`에서 `CACHE_STORE=redis`로 변경 + `php artisan config:cache` +3. 여전히 500 → 로그 파일 권한 문제로 에러 미기록 → 권한 수정 후 실제 에러 확인 +4. 실제 원인: `Class "SoapClient" not found` → `php8.4-soap` 미설치 +5. 최종 해결: `sudo apt install php8.4-soap && sudo systemctl restart php8.4-fpm` + +**교훈:** +- MNG 로그는 `current/storage/logs/`에 있음 (shared 아님) +- 500 에러인데 로그가 비어있으면 **파일 권한 문제**를 먼저 의심 +- PHP 확장 누락은 artisan tinker로 확인 가능: `php artisan tinker --execute="new SoapClient('test');"` + +--- + ## 공통 장애 ### 디스크 공간 부족 diff --git a/deploys/ops-manual/11-server-setup.md b/deploys/ops-manual/11-server-setup.md index cac90e2..f51b731 100644 --- a/deploys/ops-manual/11-server-setup.md +++ b/deploys/ops-manual/11-server-setup.md @@ -197,7 +197,7 @@ sudo apt update sudo apt install -y \ php8.4-fpm php8.4-mysql php8.4-mbstring php8.4-xml \ php8.4-curl php8.4-zip php8.4-gd php8.4-bcmath \ - php8.4-intl php8.4-redis php8.4-opcache + php8.4-intl php8.4-redis php8.4-opcache php8.4-soap curl -sS https://getcomposer.org/installer | php sudo mv composer.phar /usr/local/bin/composer