diff --git a/deploys/ops-manual/08-troubleshooting.md b/deploys/ops-manual/08-troubleshooting.md index 7c92783..b45d9a1 100644 --- a/deploys/ops-manual/08-troubleshooting.md +++ b/deploys/ops-manual/08-troubleshooting.md @@ -395,6 +395,7 @@ try { | 로그 유실로 에러 추적 불가 | `ls -la current/storage/logs` | `storage/logs` → shared 심링크 확인 | | 한글 폰트 미설치 | `ls /usr/share/fonts/truetype/nanum/` | `sudo apt install fonts-nanum` | | FPDI/TCPDF 미설치 | `composer show setasign/fpdi` | `composer install` | +| TCPDF 폰트 정의 파일 오류 | 아래 "TCPDF 폰트 정의 파일 오류" 참고 | `registerKoreanFont()` 코드 수정 | **esign 디렉토리 권한 기준:** @@ -414,6 +415,62 @@ sudo chmod -R 2775 /home/webservice/mng/shared/storage/app/private/esign/ --- +### TCPDF 폰트 정의 파일 오류 (font definition file) + +**증상:** 전자계약 서명 페이지에서 `TCPDF ERROR: Could not include font definition file: pretendard` (또는 `nanumgothic`) 오류. + +**근본 원인:** + +운영 환경에서 `vendor/tecnickcom/tcpdf/fonts/` 디렉토리가 배포 사용자(`hskwon`) 소유이므로 PHP-FPM(`www-data`)이 쓰기 불가. +`TCPDF_FONTS::addTTFfont()`는 폰트 캐시 파일(.php, .z, .ctg.z)을 **생성만** 하고, +`$pdf->SetFont('폰트명')`은 `K_PATH_FONTS`(vendor 경로)에서 **찾기만** 해서 경로 불일치 발생. + +개발서버는 `vendor/` 권한이 `2775 pro:develop`이라 PHP가 직접 쓸 수 있어 문제없음. + +**진단:** + +```bash +# 폰트 캐시 존재 확인 (storage에 있으나 vendor에 없는 상태) +ls -la /home/webservice/mng/shared/storage/app/private/fonts/ +ls /home/webservice/mng/current/vendor/tecnickcom/tcpdf/fonts/pretendard* 2>/dev/null + +# vendor fonts 소유자 확인 +stat -c "%U:%G %a" /home/webservice/mng/current/vendor/tecnickcom/tcpdf/fonts/ + +# 에러 로그 확인 +grep -i "font definition\|Could not include" /home/webservice/mng/shared/storage/logs/laravel.log +``` + +**영구 해결 (코드 수정 - 2026-02-26 적용):** + +`PdfSignatureService.php`에서 `registerKoreanFont(Fpdi $pdf)` 메서드로 분리하여: +1. 폰트 캐시를 `storage/app/private/fonts/`에 생성 (vendor 의존 제거) +2. `$pdf->AddFont('pretendard', '', $fontDefFile)` — PDF 인스턴스에 **전체 경로로 등록** +3. 이후 `SetFont('pretendard')`가 이미 등록된 폰트를 사용하므로 K_PATH_FONTS 미참조 + +**긴급 임시 조치 (코드 수정 전):** + +```bash +# vendor 폰트 디렉토리 권한 변경 (배포 시마다 초기화됨) +sudo chown -R www-data:webservice /home/webservice/mng/current/vendor/tecnickcom/tcpdf/fonts/ +sudo chmod -R 775 /home/webservice/mng/current/vendor/tecnickcom/tcpdf/fonts/ + +# 기존 캐시 삭제 (코드 수정 후 새 경로로 재생성) +sudo rm -f /home/webservice/mng/shared/storage/app/private/fonts/pretendard.* +sudo rm -f /home/webservice/mng/shared/storage/app/private/fonts/nanumgothic.* +``` + +**개발 vs 운영 환경 차이:** + +| 항목 | 개발 서버 | 운영 서버 | +|------|----------|----------| +| vendor/ 소유자 | `pro:develop` (2775) | `hskwon:hskwon` (배포 사용자) | +| www-data vendor 쓰기 | ✅ 가능 | ❌ 불가 | +| 폰트 캐시 위치 | vendor 내부 (기본) | storage/app/private/fonts/ | +| `addTTFfont()` 결과 | vendor에 캐시 생성 → SetFont 성공 | storage에 캐시 생성 → SetFont 실패 (경로 불일치) | + +--- + ## 공통 장애 ### 디스크 공간 부족