라이믹스/매뉴얼/업로드 오류와 서버 진단

상위 문서: 라이믹스/매뉴얼

1. 진단 순서#

파일 업로드는 브라우저 → CDN·프록시 → 웹 서버 → PHP → 라이믹스의 파일·게시판 설정 → 저장소를 거친다. 각 단계의 제한과 오류를 따로 확인한다. 이 문서는 각 제품의 공식 동작 설명을 라이믹스 운영에 적용한 보충 안내이다.

1. 실패한 시각, URL, HTTP 상태 코드, 파일 크기·종류, 로그인 여부와 재현 순서를 기록한다.
2. 같은 계정으로 작은 텍스트 파일과 문제가 된 파일을 각각 시험한다. 모든 파일이 실패하는지, 특정 크기·종류만 실패하는지 구분한다.
3. 브라우저 개발자 도구의 네트워크에서 실패한 업로드 요청과 응답을 확인한다. 화면에 일반적인 오류만 보여도 응답은 413·403·500 등일 수 있다.
4. 같은 시각의 웹 서버·PHP·라이믹스 로그를 맞춰 보고 실패한 계층을 좁힌다. 로그 위치는 호스팅·배포판·설정에 따라 다르다.

2. 증상별 출발점#

증상	먼저 확인할 것	판별에 도움이 되는 자료
413	nginx·프록시·CDN의 요청 본문 크기 제한	해당 계층의 응답 헤더와 오류 로그
폼 내용·파일이 함께 비어 있음	PHP post_max_size 초과 여부	실제 요청 크기와 웹 PHP 설정
파일 쓰기 실패	PHP 임시 경로와 최종 저장 경로의 권한·용량·쿼터	업로드 오류 코드, PHP 로그
403	회원·게시판 업로드 권한, 허용 형식, WAF 차단	동일 파일의 계정별 결과, 차단 로그
500·빈 화면	PHP 치명적 오류, 확장 기능 충돌, 메모리 부족 등	오류가 난 시각의 서버 로그
502·504	웹 서버와 PHP-FPM 연결, 워커 부족·응답 지연 등	웹 서버와 FPM 로그를 함께 확인

상태 코드 하나로 원인이 확정되지는 않는다. 프록시가 만든 응답인지 애플리케이션이 만든 응답인지부터 확인한다.

3. 크기 제한의 관계#

• PHP의 upload_max_filesize는 파일 하나의 제한이다. post_max_size는 폼 전체 요청을 제한하므로 파일과 부가 데이터를 담을 여유가 필요하다. 이를 넘으면 $_POST와 $_FILES가 비어 있을 수 있다. PHP 설정 설명
• 여러 파일을 한 요청으로 보내는 구현은 합계 크기와 max_file_uploads도 확인한다. 라이믹스 및 에디터가 파일을 나누어 보낸다면 실제 요청 단위를 기준으로 판단한다.
• nginx의 client_max_body_size는 요청 본문의 상한이며 초과 시 413을 반환한다. nginx만 변경해도 PHP·라이믹스·CDN 제한이 자동으로 바뀌지는 않는다. nginx 공식 문서

예를 들어 파일당 20 MiB를 허용하고 한 요청에 하나만 보낸다면, 다음은 요청 부가 데이터에 여유를 둔 설정 관계의 예시이다. 다중 업로드·호스팅 제한에 따라 다시 산정한다.

; 웹 요청을 처리하는 PHP 설정의 예시
upload_max_filesize = 20M
post_max_size = 24M

# 해당 사이트 server/location의 예시
client_max_body_size 24m;

설정 파일의 적용 위치를 확인하고 웹 서버 문법 검사·설정 재적용 절차를 따른다. 모든 제한을 무제한으로 풀기보다 필요한 최대 크기를 정한다.

4. 웹 PHP와 CLI 구분#

php -v, php --ini, php -m은 터미널에서 실행한 PHP의 결과다. 실제 사이트가 다른 PHP 버전·SAPI·설정 파일을 사용할 수 있다. 웹 요청의 PHP 버전과 적용 설정은 호스팅 관리 화면 또는 접근을 제한한 진단 방법으로 확인한다. phpinfo()에는 환경 정보가 많이 담기므로 공개 진단 파일을 방치하지 않는다. PHP 설정 파일 검색 순서

5. 임시 경로와 이미지 처리#

• PHP 업로드 오류 코드 6은 임시 폴더 없음, 7은 디스크 쓰기 실패를 뜻한다. 임시 디렉터리와 최종 업로드 디렉터리를 구분하여 PHP 실행 계정의 권한, 남은 공간과 쿼터를 확인한다. PHP 업로드 오류 코드
• 파일 크기는 작아도 해상도가 큰 이미지는 썸네일·회전·변환 과정에서 메모리가 많이 필요할 수 있다. 원본 크기뿐 아니라 가로·세로 픽셀, 이미지 라이브러리, 실패 시점과 메모리 오류를 확인한다. 파일 하나의 바이트 수만큼만 메모리가 필요하다고 계산하지 않는다.
• 전체 사이트에 777을 적용하기 전에 실제 쓰기 주체와 실패한 경로를 확인한다. 라이믹스/매뉴얼/설치 환경 참고.

6. 문의할 때 첨부할 정보#

현재 라이믹스·웹 PHP·DB 버전, 사용 에디터·관련 확장 기능, 재현 순서, 파일 크기·형식, HTTP 상태와 해당 시각의 오류 메시지를 정리한다. 로그를 공개할 때 쿠키·세션·인증 토큰·DB 비밀번호·개인정보를 제거하고, 재현용 파일은 개인정보가 없는 것으로 대체한다.

7. 같이 보기#

• 라이믹스/매뉴얼/nginx 설정 방법
• 라이믹스/매뉴얼/설치 환경
• 라이믹스/매뉴얼/캐시와 성능 점검
• 라이믹스/매뉴얼/GitHub 이슈 및 PR 작성