ownCloud 빈 페이지/흰색 화면 오류 해결 방법: 올바른 복구 경로 선택

먼저 당신이 어떤 종류의 백지를 가지고 있는지부터 결정하세요.

ownCloud에서 발생하는 "하얀 화면 오류"는 증상일 뿐 진단이 아닙니다. 최적의 해결 방법은 브라우저가 서버 오류를 수신했는지, 유효한 HTML은 수신했지만 JavaScript 또는 CSS 로드에 실패했는지, 아니면 ownCloud에 전혀 연결할 수 없는 리버스 프록시에 연결되었는지에 따라 달라집니다.

이러한 차이점은 매우 중요합니다. 왜냐하면 각각의 장단점이 크게 다르기 때문입니다. PHP 예외 오류에서 특정 타사 앱이 지목될 경우, 해당 앱을 비활성화하는 것은 상대적으로 위험 부담이 적습니다. 하지만 전체 설치 환경에서 파일 소유권을 변경하는 것은 훨씬 더 심각한 문제이며, JavaScript 오류 발생 시 첫 번째 해결책으로 선택해서는 안 됩니다. 마찬가지로, 모든 서비스를 재시작하는 것은 PHP, 프록시, 업그레이드 또는 앱 중 어느 쪽에서 문제가 발생했는지 알 수 없이 일시적으로 문제를 숨길 수는 있습니다.

이 가이드는 ownCloud Classic에 대한 내용입니다. 현재 ownCloud Classic 11 문서에 따르면, 버전 11은 Docker 기반 배포를 지원하며, 운영 체제, PHP 런타임, 데이터베이스 및 Apache는 ownCloud에서 제공하는 컨테이너 내부에 설치됩니다. 이전 버전인 10.x 설치 환경에서는 기존 웹 서버 및 PHP-FPM 구성이 사용될 수 있습니다. 배포 환경에 맞는 명령 브랜치를 사용하십시오. ownCloud Classic 11 시스템 요구 사항을 참조하십시오 .

1. 빈 페이지가 HTTP 500 오류를 반환하는 건가요, 아니면 브라우저가 HTTP 200 이후에 오류를 발생시키는 건가요?

브라우저 개발자 도구를 열고 네트워크 탭 과 콘솔 탭을 모두 검사하세요. 또한 터미널에서 엔드포인트를 테스트해 보세요.

curl -I https://cloud.example.com/
curl -sS -o /dev/null -w '%{http_code}\n' https://cloud.example.com/

캡션: 서버 측 500 응답은 단순한 브라우저 렌더링 문제가 아니라 ownCloud, PHP, 데이터베이스 또는 웹 스택과 관련된 문제일 가능성이 높습니다.

메인 문서에서 500 또는 502/503 오류가 발생하는 경우 서버 및 프록시 로그를 우선적으로 확인하십시오. 메인 문서에서 200이 반환 되지만 JavaScript 번들에서 404, 403 오류 또는 스크립트 예외가 발생하는 경우 자산 경로, 역방향 프록시 재작성, 테마, 캐시 또는 앱 호환성을 우선적으로 확인하십시오. 특정 브라우저에서만 문제가 발생하는 경우 서버를 변경하기 전에 시크릿 모드와 다른 지원되는 브라우저에서 테스트하십시오.

2. 문제가 ownCloud 또는 PHP 업그레이드 후에 발생했습니까?

이 질문은 문제 발생 범위를 즉시 좁힐 수 있기 때문에 매우 중요합니다. ownCloud의 최신 릴리스 노트에 따르면 ownCloud Classic 11은 최소 PHP 버전을 PHP 8.3으로 상향 조정했으며, Docker 환경에서만 작동합니다. 기존 ownCloud 10.x 설치는 PHP 호환성 규칙이 다르므로 다른 주요 릴리스의 PHP 관련 권장 사항을 그대로 사용하지 마십시오.

기존 ownCloud 10.x 설치의 경우 ownCloud 디렉터리에서 다음 명령을 실행하십시오.

sudo -u www-data ./occ status
php -v

ownCloud Classic 11의 경우, Compose 배포를 통해 OCC를 실행하십시오.

docker compose exec owncloud occ status
docker compose exec owncloud php -v

캡션: 업그레이드 직후 흰색 화면 문제가 발생했을 경우, 설치된 ownCloud 및 PHP 버전을 확인하는 것이 특히 중요합니다.

결과를 실제로 실행 중인 버전의 릴리스 노트와 비교하십시오. ownCloud 공식 릴리스 노트가 최신 최소 버전 및 호환성이 깨지는 변경 사항에 대한 정확한 정보 출처입니다. 다운그레이드는 안전한 일반적인 해결 방법이 아닙니다. ownCloud 설명서에서는 다운그레이드 시 데이터가 손상될 수 있으므로 지원하지 않는다고 경고합니다.

3. 어떤 로그에서 처음으로 구체적인 오류가 발생했습니까?

일반적으로 로그는 시행착오를 통한 설정 변경보다 훨씬 유용합니다. ownCloud 관리 설명서에서는 문제 진단을 위해 ownCloud 로그를 활용할 것을 권장합니다. 기본적으로 로그는 별도로 logfile지정하지 않는 한 구성된 데이터 디렉터리에 저장됩니다.

기존 설치 방식의 예는 다음과 같습니다.

tail -n 100 /path/to/owncloud/data/owncloud.log
journalctl -u php-fpm --since "15 minutes ago"
journalctl -u apache2 --since "15 minutes ago"
journalctl -u nginx --since "15 minutes ago"

ownCloud Classic 11에서는 Compose 서비스를 검사하십시오.

docker compose logs --tail=200 owncloud
docker compose ps

캡션: PHP 치명적 오류 또는 스택 트레이스에 앱이나 클래스 이름이 포함되어 있으면 관련 없는 서버 설정을 변경하는 것보다 훨씬 안전한 문제 해결 대상을 찾을 수 있습니다.

실패한 요청과 관련된 첫 번째 치명적인 예외를 찾아야 하며, 최종 오류 연쇄만 살펴보지 마십시오. 일반적인 원인으로는 PHP 클래스 누락, 애플리케이션 호환성 문제, 데이터베이스 연결 실패, 읽을 수 없는 구성, 코드 파일 누락 또는 업그레이드 중 발생하는 예외 등이 있습니다.

ownCloud의 로깅 문서에 따르면 DEBUG 로깅은 진단에 도움이 될 수 있지만 상당한 양의 출력을 생성하여 성능에 영향을 줄 수 있습니다. 로그 레벨을 일시적으로 높인 경우 증거를 수집한 후에는 더 간략한 값으로 되돌려야 합니다. 자세한 내용은 ownCloud 로깅 구성을 참조하십시오 .

4. 타사 앱을 비활성화해야 할까요?

오류 메시지에 핵심 앱이 아닌 앱이 언급되거나, 앱 설치 또는 업데이트 후 빈 페이지가 나타나거나, ownCloud 업그레이드 중에 오류가 발생한 경우 이 경로를 선택하십시오. ownCloud의 문제 해결 지침에서는 문제 해결 및 업그레이드 전에 타사 앱을 비활성화할 것을 명시적으로 권장합니다.

먼저 앱 목록을 표시합니다. ownCloud 10.x 버전에서는 다음과 같습니다.

sudo -u www-data ./occ app:list
sudo -u www-data ./occ app:disable APP_ID

ownCloud 11에서:

docker compose exec owncloud occ app:list
docker compose exec owncloud occ app:disable APP_ID

설명: 로그에 의해 문제가 되는 앱만 비활성화하는 것이 여러 구성 요소를 비활성화하거나 전체 웹 스택을 변경하는 것보다 서비스 중단이 적습니다.

절충점은 기능상의 제약입니다. 사용자는 앱이 업데이트되거나 다시 활성화될 때까지 해당 앱을 사용할 수 없게 됩니다. 이는 일반적으로 ownCloud 핵심 서비스를 비활성화하는 것보다 나은 선택입니다. OCC 문서에는 DAV, FederatedFileSharing, Files, Files_External을 포함한 몇 가지 핵심 앱은 비활성화할 수 없다고 명시되어 있습니다. 공식 일반 문제 해결 지침 및 OCC 명령 참조를 확인하십시오 .

5. 권한 문제를 해결할 가치가 있는 경우는 언제인가요?

로그에 권한 문제가 포함되어 있거나 Permission denied, 최근 배포 과정에서 앱/구성 파일이 잘못된 사용자로 복사되었거나, 업그레이드 과정에서 파일 소유권이 잘못된 상태로 교체된 경우 권한 문제가 유력한 원인으로 의심됩니다. 하지만 브라우저 측 JavaScript 오류만 있는 경우에는 권한 문제가 원인일 가능성이 낮습니다.

시스템을 유지보수 모드로 전환한 후, 시스템 작동에 지장을 주는 수리 작업을 진행하십시오. ownCloud 11의 경우:

docker compose exec owncloud occ maintenance:mode --on

기존 10.x 배포 방식의 경우:

sudo -u www-data ./occ maintenance:mode --on

설명: 유지 관리 모드는 로그 증거로 이미 확인된 소유권 또는 파일 권한 오류를 조사하는 동안 사용자 활동을 줄여줍니다.

관련 없는 릴리스의 권한 레시피를 일괄적으로 재귀적으로 실행하거나 복사하지 마십시오 chmod 777. 현재 ownCloud 11 매뉴얼에는 Docker 마운트된 디렉터리에 수동으로 추가된 파일의 소유권 및 모드에 대한 특정 정보가 문서화되어 있습니다 apps. config여기에는 소유권 www-data:root, 앱 파일 0644, 앱 디렉터리 0751및 추가된 구성 파일에 대한 내용이 포함 0644됩니다. 또한 0640수동으로 변경된 내용에 대한 정보 .htaccess도 문서화되어 있습니다 .user.ini. 릴리스별 참조 자료로 ownCloud 11 수동 업그레이드 문서를 활용하십시오.

6. PHP 모듈, OPcache 또는 메모리 설정을 변경해야 할까요?

로그나 호환성 검사에서 문제가 발견될 때만 해당됩니다. 이 방법은 단순히 문제가 있는 애플리케이션 하나를 비활성화하는 것보다 훨씬 더 광범위한 영향을 미칩니다. 필수 PHP 확장 프로그램이 누락되면 코드가 실행되지 않을 수 있고, PHP 구성이 잘못되면 호스트의 모든 PHP 애플리케이션에 영향을 미칠 수 있습니다.

기존 호스트 관리형 PHP 스택의 경우 웹 런타임이 실제로 로드하는 항목을 검사하십시오.

php -m
php --ini
php -r 'phpinfo();' | grep opcache.enable

캡션: PHP 모듈 및 OPcache 검사는 서버 로그에 확장 기능 누락이나 런타임 호환성 문제가 언급될 때 유용하지만, 근거 없이 가장 먼저 변경해서는 안 됩니다.

ownCloud 11의 경우 공식 이미지가 PHP 런타임을 관리하므로 호스트 PHP 패키지를 변경하는 것은 일반적으로 잘못된 접근 방식입니다. ownCloud 문서에 따르면 Docker 이미지에서 OPcache가 기본적으로 활성화되어 있습니다. ownCloud 메모리 캐싱 문서를 참조하세요 .

기존 설치 환경에서 PHP 파일을 수동으로 교체한 후 OPcache가 오래된 것으로 의심되는 경우, PHP-FPM 또는 관련 웹/PHP 서비스를 재시작하여 프로세스 로컬 opcode 캐시를 지울 수 있습니다. 단, 이로 인해 시스템이 잠시 중단되고 이후 캐시 성능이 저하될 수 있습니다. 오류를 식별하는 대신 이 방법을 사용하기보다는, 먼저 관련 파일을 수정한 후에 사용하십시오.

7. 업그레이드가 중단되었거나 핵심 파일의 일관성이 깨졌습니까?

업그레이드 도중 또는 직후에 흰색 페이지가 나타나면 먼저 업그레이드 상태를 확인하십시오. ownCloud의 업그레이드 관련 문서에서는 데이터베이스를 수동으로 조작하는 대신 OCC를 사용하여 업그레이드 및 복구 경로를 진행할 것을 권장합니다.

ownCloud 11의 경우:

docker compose exec owncloud occ status
docker compose exec owncloud occ upgrade
docker compose exec owncloud occ maintenance:repair
docker compose exec owncloud occ integrity:check-core

ownCloud 10.x의 경우 웹 서버 사용자 계정으로 다음 OCC 명령어를 사용하십시오.

sudo -u www-data ./occ status
sudo -u www-data ./occ maintenance:repair
sudo -u www-data ./occ integrity:check-core

캡션: OCC 복구는 중단되거나 일관성이 없는 업그레이드에 적합하며, 무결성 검사는 수정되었거나 누락된 서명된 코어 파일을 식별할 수 있습니다.

코드 무결성 검사 결과는 해석이 필요합니다. ownCloud 문서에서는 INVALID_HASH, FILE_MISSING, 및 EXTRA_FILE를 별개의 조건으로 취급합니다. 경고를 없애기 위해 문서를 수정하지 마십시오 signature.json. 현재 ownCloud 11 문서에서는 타사 앱의 서명이 설치, 업데이트 및 활성화에 필수적이라고 명시하고 있습니다. ownCloud 코드 서명 문서를 참조하십시오 .

8. 수정 사항이 제대로 적용되었는지 어떻게 확인해야 합니까?

제대로 된 복구는 단순히 "페이지가 더 이상 흰색이 아니다"라는 것만으로는 충분하지 않습니다. 전체 요청 경로를 확인해야 합니다.

• ownCloud 메인 페이지는 500/502/503 오류가 아닌 예상되는 HTTP 상태 코드를 반환합니다.
• 브라우저 개발자 도구에서 반복되는 치명적인 JavaScript 오류나 핵심 번들 누락이 나타나지 않습니다.
• ownCloud 로그는 동일한 요청에 대한 새로운 치명적인 예외를 즉시 기록하지 않습니다.
• occ status설치된 인스턴스가 있으며 예상치 못한 업그레이드 요구 사항이 없다고 보고합니다.
• 점검이 완료되면 유지보수 모드가 비활성화됩니다.
• 테스트 사용자는 로그인하여 파일 페이지를 열 수 있습니다.

ownCloud 11의 경우:

docker compose exec owncloud occ maintenance:mode --off
docker compose exec owncloud occ status
curl -I https://cloud.example.com/

캡션: 복구는 두 가지 계층 모두에서 확인되어야 합니다. 즉, ownCloud 인터페이스가 로드되는지, 그리고 서버 측 상태 및 HTTP 검사가 정상인지 확인해야 합니다.

어떤 해결책이 위험 대비 이익 측면에서 가장 균형이 잘 잡혀 있을까요?

ownCloud에서 흰색 화면이 나타날 때 하지 말아야 할 행동

• display_errors공개 운영 사이트에서 단순히 브라우저에 스택 트레이스를 노출하기 위해 PHP를 활성화하지 마십시오 . 대신 서버 로그를 사용하십시오.
• ownCloud 트리의 전체 영역에 대해 재귀적으로 쓰기 권한을 설정하지 마십시오.
• 호환되는 환경에 지원되는 백업을 복원하는 경우가 아니라면, 빠른 롤백을 위해 ownCloud 버전을 다운그레이드하지 마십시오.
• 데이터 디렉터리, 앱 데이터, 데이터베이스 테이블 또는 캐시 디렉터리를 임의로 삭제하지 마십시오.
• 특정 앱 하나만 비활성화할 수 있다면 모든 앱을 한꺼번에 비활성화하지 마세요.
• signature.json서명된 코어 파일을 편집하거나 무결성 오류를 숨기기 위해 편집 하지 마십시오 .

실험을 계속하는 대신 언제 단계를 높여야 할까요?

로그에 데이터베이스 손상, 암호화 키 문제, 정상 복원 후 반복되는 코어 무결성 실패 또는 문서화된 OCC 워크플로로 완료할 수 없는 업그레이드 상태가 표시되면 변경 작업을 중단하십시오. 또한 빈 페이지 오류가 프로덕션 클러스터에 영향을 미치고 데이터 일관성을 손상시킬 위험 없이 단일 노드를 격리할 수 없는 경우 문제를 에스컬레이션하십시오.

지원 사례를 접수하기 전에 ownCloud에서는 구성 보고서와 관련 로그를 수집하는 것을 권장합니다. ownCloud 10.x의 경우, 문서화된 명령어는 다음과 같습니다.

sudo -u www-data ./occ configreport:generate > config_report.txt

배포 환경에 맞는 OCC 실행 방법을 사용하고, 출력 결과를 조직 외부와 공유하기 전에 비밀 키가 포함되어 있는지 확인하십시오. ownCloud 로그 및 구성 수집 가이드에서는 지원 엔지니어가 일반적으로 필요로 하는 정보를 설명합니다.

공식 참조

• ownCloud Classic 11 일반 문제 해결
• ownCloud Classic 11 시스템 요구 사항
• ownCloud 서버 릴리스 노트
• ownCloud Classic 11 수동 업그레이드
• ownCloud 로깅 구성