# 9. 운영 가이드 (Operations Guide) > **문서 버전**: 1.0 > **최종 업데이트**: 2025-11-15 --- ## 9.1 배포 ### 9.1.1 프로덕션 환경 요구사항 (Linux) #### 서버 사양 | 항목 | 최소 | 권장 | |------|------|------| | OS | Ubuntu 20.04 LTS | Ubuntu 22.04 LTS | | CPU | 2 Core | 4 Core | | RAM | 4 GB | 8 GB | | 디스크 | 50 GB | 100 GB SSD | #### 소프트웨어 요구사항 ```bash # PowerShell Core 7.0+ pwsh --version # .NET Runtime 6.0+ dotnet --list-runtimes # 추가 패키지 (선택) sudo apt-get install -y imagemagick # PNG 처리 보조 ``` --- ### 9.1.2 배포 절차 #### Step 1: 서버 준비 ```bash # 애플리케이션 사용자 생성 sudo useradd -m -s /bin/bash posterapp sudo usermod -aG sudo posterapp # 데이터 디렉토리 생성 sudo mkdir -p /data/{psd_template,machine,working} sudo chown -R posterapp:posterapp /data sudo chmod -R 755 /data ``` #### Step 2: 애플리케이션 배포 ```bash # 애플리케이션 디렉토리 sudo mkdir -p /app sudo chown posterapp:posterapp /app # Repository clone (posterapp 사용자로) su - posterapp cd /app git clone git@github.com:planitaicojp/poster-ai-create-psd.git cd poster-ai-create-psd ``` #### Step 3: DLL 및 라이선스 파일 배치 ```bash # aspose-packages 디렉토리 생성 mkdir -p /app/poster-ai-create-psd/aspose-packages # DLL 파일 복사 (안전한 방법으로 전송) scp Aspose.PSD.dll posterapp@server:/app/poster-ai-create-psd/aspose-packages/ scp Aspose.Drawing.dll posterapp@server:/app/poster-ai-create-psd/aspose-packages/ # ... 기타 DLL 파일 # 라이선스 파일 복사 scp Aspose.PSD.NET.lic posterapp@server:/app/poster-ai-create-psd/ ``` #### Step 4: 설정 파일 수정 ```bash # Linux 환경 설정 vi /app/poster-ai-create-psd/Create-PSD-config.ps1 ``` ```powershell # 프로덕션 경로 설정 $global:TemplateRootPath = "/data/psd_template" $global:MachineRootPath = "/data/machine" $global:WorkingRootPath = "/data/working" $global:PosterCsvPath = "/app/poster-ai-create-psd/poster.csv" # 로깅 설정 $global:LogLevel = "INFO" $global:DebugMode = $false ``` #### Step 5: 권한 설정 ```bash # 스크립트 실행 권한 chmod +x /app/poster-ai-create-psd/*.ps1 # 라이선스 파일 보안 (중요!) chmod 400 /app/poster-ai-create-psd/Aspose.PSD.NET.lic chown posterapp:posterapp /app/poster-ai-create-psd/Aspose.PSD.NET.lic ``` #### Step 6: 배포 검증 ```bash # 테스트 실행 cd /app/poster-ai-create-psd pwsh -f Create-PSD.ps1 -machineIds "1" -json # 성공 확인 echo $? # 0이면 성공 ``` --- ### 9.1.3 환경 변수 설정 #### systemd 서비스 파일 (선택) `/etc/systemd/system/poster-api.service`: ```ini [Unit] Description=Poster Generation API After=network.target [Service] Type=simple User=posterapp WorkingDirectory=/app/poster-api Environment="POSTER_SCRIPT_PATH=/app/poster-ai-create-psd/Create-PSD.ps1" ExecStart=/usr/bin/python3 /app/poster-api/main.py Restart=always [Install] WantedBy=multi-user.target ``` ```bash sudo systemctl daemon-reload sudo systemctl enable poster-api sudo systemctl start poster-api ``` --- ### 9.1.4 보안 고려사항 #### Aspose.PSD 라이선스 파일 관리 **중요**: 라이선스 파일은 민감한 정보입니다. ```bash # 파일 권한: 소유자만 읽기 chmod 400 Aspose.PSD.NET.lic # 소유자 확인 ls -l Aspose.PSD.NET.lic # 출력: -r-------- 1 posterapp posterapp 1258 ... Aspose.PSD.NET.lic ``` #### Git에서 제외 `.gitignore`: ``` Aspose.PSD.NET.lic aspose-packages/*.dll *.psd *.log /data/working/ ``` #### 파일 권한 설정 ```bash # 애플리케이션 디렉토리 chown -R posterapp:posterapp /app/poster-ai-create-psd chmod -R 755 /app/poster-ai-create-psd # 스크립트 실행 권한 chmod 755 /app/poster-ai-create-psd/*.ps1 # 데이터 디렉토리 chown -R posterapp:posterapp /data chmod -R 755 /data/psd_template chmod -R 755 /data/machine chmod -R 775 /data/working # 쓰기 권한 필요 ``` #### 민감 정보 보호 - 라이선스 파일 암호화 저장 고려 - 환경 변수로 경로 전달 - 로그에 민감 정보 출력 방지 --- ## 9.2 로깅 및 모니터링 ### 9.2.1 로그 파일 위치 및 구조 #### 로그 파일 위치 ``` /data/working/{timestamp}-{uuid}/create-psd.log ``` 각 실행마다 독립적인 로그 파일이 생성됩니다. #### 로그 파일 구조 ``` [2025-01-15 14:30:22] INFO: Starting PSD creation... [2025-01-15 14:30:23] INFO: Parameters: machineIds=107, orientation=vertical [2025-01-15 14:30:24] INFO: Template selected: /data/psd_template/... [2025-01-15 14:30:25] DEBUG: Loading Aspose.PSD library [2025-01-15 14:30:30] INFO: Processing machine 107 [2025-01-15 14:30:35] INFO: Machine name layer replaced: machine-name_g01 #1 [2025-01-15 14:30:45] INFO: PSD file saved: /data/working/.../file.psd [2025-01-15 14:30:45] INFO: Completed in 23.5 seconds ``` --- ### 9.2.2 로그 레벨 | 레벨 | 설명 | 사용 예 | |------|------|---------| | `DEBUG` | 상세 디버그 정보 | 개발/문제 해결 시 | | `INFO` | 일반 정보 | 프로덕션 기본값 | | `WARN` | 경고 메시지 | 비정상적이나 계속 가능 | | `ERROR` | 오류 메시지 | 처리 실패 | **설정**: ```powershell # Create-PSD-config.ps1 $global:LogLevel = "INFO" # 프로덕션 $global:LogLevel = "DEBUG" # 디버그 시 ``` --- ### 9.2.3 로그 분석 방법 #### 최근 실행 로그 확인 ```bash # 최근 로그 파일 찾기 find /data/working -name "create-psd.log" -type f -mtime -1 | sort -r | head -1 # 로그 내용 확인 tail -f $(find /data/working -name "create-psd.log" -type f -mtime -1 | sort -r | head -1) ``` #### 에러 로그 필터링 ```bash # ERROR 레벨만 추출 grep "\[ERROR\]" /data/working/*/create-psd.log # 특정 날짜 에러 확인 grep "2025-01-15.*\[ERROR\]" /data/working/*/create-psd.log ``` #### 성능 분석 ```bash # 실행 시간 추출 grep "Completed in" /data/working/*/create-psd.log ``` --- ### 9.2.4 성능 모니터링 #### 시스템 리소스 모니터링 ```bash # CPU 및 메모리 사용량 top -u posterapp # 디스크 사용량 df -h /data # 작업 디렉토리 크기 du -sh /data/working ``` #### 로그 로테이션 오래된 작업 디렉토리 정리: ```bash # 30일 이상 된 디렉토리 삭제 find /data/working -type d -mtime +30 -exec rm -rf {} + ``` Cron 설정: ```bash crontab -e ``` ```cron # 매일 새벽 2시에 30일 이상 된 작업 디렉토리 삭제 0 2 * * * find /data/working -type d -mtime +30 -exec rm -rf {} + ``` --- ## 9.3 트러블슈팅 ### 9.3.1 일반적인 오류 및 해결 방법 #### Module Loading Errors **증상**: ``` [ERROR] Failed to load Aspose.PSD.dll ``` **원인**: - DLL 파일 누락 - .NET Runtime 미설치 **해결**: ```bash # DLL 파일 확인 ls -la /app/poster-ai-create-psd/aspose-packages/ # .NET Runtime 확인 dotnet --list-runtimes # .NET Runtime 설치 (없는 경우) sudo apt-get install -y dotnet-runtime-6.0 ``` --- #### License Issues **증상**: ``` [ERROR] License file not found [ERROR] Invalid license file ``` **해결**: ```bash # 라이선스 파일 위치 확인 ls -la /app/poster-ai-create-psd/Aspose.PSD.NET.lic # 파일 권한 확인 -r-------- 1 posterapp posterapp 1258 ... # 정상 # 라이선스 유효성 테스트 pwsh -f test-aspose-load.ps1 ``` --- #### Template Not Found **증상**: ``` [ERROR] Template not found for orientation=vertical, logotype=grandOpen ``` **원인**: - 템플릿 디렉토리 구조 불일치 - 템플릿 파일 누락 **해결**: ```bash # 템플릿 디렉토리 구조 확인 tree /data/psd_template # 예상 경로 확인 ls -la /data/psd_template/vertical/grandOpen/machine_1/ ``` --- #### JSON Parse Errors **증상**: ``` [ERROR] Failed to parse JSON output ``` **원인**: - JSON 형식 오류 - 출력에 의도하지 않은 문자 포함 **해결**: ```bash # JSON 출력 검증 pwsh -f Create-PSD.ps1 -machineIds "1" -json | jq . # jq 명령으로 JSON 파싱 확인 ``` --- #### Machine Data Missing **증상**: ``` [WARN] Machine image not found: /data/machine/107/main.png ``` **해결**: ```bash # 머신 데이터 디렉토리 확인 ls -la /data/machine/107/ # 필수 파일 확인 ls -la /data/machine/107/main.png ls -la /data/machine/107/machine-text/gtwcs.png ``` --- #### 디스크 공간 부족 **증상**: ``` [ERROR] Failed to save PSD file: Disk full ``` **해결**: ```bash # 디스크 사용량 확인 df -h # 작업 디렉토리 정리 rm -rf /data/working/old-directory ``` --- ### 9.3.2 디버그 모드 활용 ```powershell # Create-PSD-config.ps1에서 디버그 활성화 $global:DebugMode = $true $global:LogLevel = "DEBUG" ``` 실행: ```bash pwsh -f Create-PSD.ps1 -machineIds "107" ``` 상세 로그로 문제 원인 추적. --- ### 9.3.3 로그 기반 문제 진단 #### 단계별 로그 확인 ```bash # 1. 초기화 단계 grep "Starting PSD creation" create-psd.log # 2. 템플릿 선택 grep "Template selected" create-psd.log # 3. 라이브러리 로드 grep "Loading Aspose.PSD" create-psd.log # 4. 머신 처리 grep "Processing machine" create-psd.log # 5. 완료 grep "Completed" create-psd.log ``` --- ### 9.3.4 FAQ #### Q: 포스터 생성이 너무 오래 걸립니다. **A**: - 템플릿 PSD 파일 크기 확인 (10MB 이하 권장) - 머신 이미지 해상도 최적화 - 서버 리소스 확인 (CPU, RAM) --- #### Q: JSON 모드에서 한글이 깨집니다. **A**: - UTF-8 인코딩 확인 - PowerShell 콘솔 인코딩 설정 ```powershell $OutputEncoding = [System.Text.Encoding]::UTF8 ``` --- #### Q: 여러 포스터를 동시에 생성할 수 있나요? **A**: - 가능 (각 실행은 독립적인 작업 디렉토리 사용) - 서버 리소스 고려하여 동시 실행 수 제한 권장 --- ## 9.4 성능 최적화 ### 9.4.1 대용량 처리 최적화 #### 템플릿 캐싱 (향후 구현 가능) 동일한 템플릿을 반복 사용 시 메모리 캐싱. #### 이미지 전처리 머신 이미지를 사전에 최적화된 크기로 변환. --- ### 9.4.2 리소스 사용량 관리 ```bash # PowerShell 프로세스 메모리 사용량 확인 ps aux | grep pwsh # 작업 디렉토리 정리 자동화 find /data/working -type d -mtime +7 -exec rm -rf {} + ``` --- ### 9.4.3 병렬 처리 고려사항 - 각 실행은 독립적 - 동시 실행 시 CPU/메모리 리소스 경합 주의 - 권장: 동시 실행 4개 이하 (서버 사양 4 Core, 8GB RAM 기준) --- ## 다음 단계 - **[10. 데이터 스키마](doc_10_data_schema.md)**: 데이터 구조 상세 - **[8. 개발자 가이드](doc_8_developer_guide.md)**: 디버깅 및 개발 --- **[← 목차로 돌아가기](doc_index.md)**