Nextcloud 업데이트 후 웹GUI "데이터베이스 오류" 해결 방법: 실용적인 복구 가이드

업데이트 직후 Nextcloud 웹 GUI에 "예외: 데이터베이스 오류" 와 같은 메시지가 표시되는 경우, 일반적으로 웹 애플리케이션이 데이터베이스 계층까지는 로드되었지만 쿼리, 마이그레이션, 스키마 요구 사항, 연결 또는 애플리케이션별 데이터베이스 작업에 오류가 발생했음을 의미합니다. 테이블을 삭제하거나, Nextcloud를 다시 설치하거나, ​​이전 코드 디렉터리를 새 디렉터리 위에 복원하는 것부터 시작하지 마십시오. 더 안전한 해결 방법은 오류가 발생한 SQL 또는 마이그레이션을 식별하고, 지원되는 업데이트 경로를 완료하고, Nextcloud에서 복구할 수 있는 부분만 복구한 다음, 액세스를 다시 열기 전에 데이터베이스 서비스와 스키마를 확인하는 것입니다.

/var/www/nextcloud이 참조는 2026년 10월 기준으로 제공되는 Nextcloud 35 관리 문서를 따릅니다. 아래 명령어는 웹 서버 사용자가 있는 일반적인 Debian/Ubuntu 스타일 설치를 가정합니다 www-data. 배포 환경에 따라 경로, PHP 바이너리, 컨테이너 명령어 또는 HTTP 사용자를 조정하십시오.

빠른 진단: 오류가 일반적으로 나타내는 사항

1. 데이터베이스를 변경하기 전에 현재 상태를 보존하십시오.

업데이트 전 백업 파일이 있다면 그대로 보관하십시오. Nextcloud는 모든 업데이트 전에 백업을 권장하며, 내장된 업데이트 프로그램 백업 기능은 코드베이스는 백업하지만 데이터베이스나 데이터 디렉터리는 백업하지 않습니다 . 최신 데이터베이스 백업 파일이 없는 경우, SQL을 수동으로 변경하거나 복원하기 전에 데이터베이스 플랫폼의 일반 백업 도구를 사용하여 백업을 생성하십시오.

빠른 해결책으로 다운그레이드를 시도하지 마십시오. Nextcloud는 다운그레이드가 지원되지 않으며 데이터 손상을 초래할 수 있다고 명시하고 있습니다. 롤백이 필요한 경우, 지원되는 복구 모델은 이전 버전을 새로 설치한 후 해당 백업을 복원하는 것이며, 이미 마이그레이션이 시작된 데이터베이스에 이전 프로그램 파일을 복사하는 방식은 지원되지 않습니다. Nextcloud 내장 업데이트 프로그램 설명서를 참조하십시오 .

2. Nextcloud 로그에서 정확한 데이터베이스 예외 내용을 확인하세요.

파일 로깅을 사용하는 경우 기본 로그는 nextcloud.log구성된 데이터 디렉터리 내에 있습니다. Nextcloud의 문제 해결 가이드에서는 해당 로그와 필요한 경우 웹 서버 및 PHP 로그를 확인하도록 권장합니다. 오류 페이지에 요청 ID가 표시되면 해당 ID를 검색하여 일치하는 트랜잭션을 찾으십시오.

sudo -u www-data tail -n 100 /var/www/nextcloud/data/nextcloud.log

로그를 단순히 "데이터베이스 오류"라는 문구로만 축소하지 마십시오. SQLSTATE 코드, 예외 클래스, 오류가 발생한 테이블 또는 열, 그리고 스택 트레이스에 언급된 애플리케이션 또는 코어 구성 요소를 모두 기록해야 합니다. 예를 들어, "테이블이 존재하지 않습니다"는 "연결이 너무 많습니다" 또는 "MySQL 서버 연결이 끊어졌습니다"와는 완전히 다른 오류입니다. Nextcloud는 일반적인 문제 해결 문서 에 몇 가지 일반적인 SQLSTATE 유형 오류를 나열하고 있습니다 .

3. 업데이트가 실제로 완료되었는지 확인합니다.

내장된 업데이트 프로그램은 Nextcloud 코드 우선 방식으로 데이터베이스를 교체합니다. 데이터베이스 및 애플리케이션 마이그레이션은 별도의 단계로 진행됩니다. 명령줄 모드에서는 업데이트 프로그램을 occ upgrade바로 실행할 수 있지만, 그렇지 않은 경우에는 마이그레이션을 별도로 완료해야 합니다. 이러한 차이점 때문에 업데이트 프로그램이 "완료"된 것처럼 보이지만 일반 웹 GUI에서 데이터베이스 예외가 발생하는 경우가 종종 있습니다.

cd /var/www/nextcloud
sudo -E -u www-data php occ status

문제 해결 중에 인스턴스를 보호해야 하는 경우 유지 관리 모드를 활성화하십시오. Nextcloud는 유지 관리 모드를 업그레이드용으로 설계된 모드라고 설명합니다. 이 모드에서는 새 로그인이 차단되고 활성 세션이 잠깁니다.

sudo -E -u www-data php occ maintenance:mode --on
sudo -E -u www-data php occ status

4. occ 업그레이드를 사용하여 지원되는 데이터베이스 및 애플리케이션 마이그레이션을 완료합니다.

코드가 업데이트되었지만 마이그레이션이 완료되지 않은 경우 HTTP 사용자 권한으로 업그레이드 명령을 실행하십시오.

cd /var/www/nextcloud
sudo -E -u www-data php occ upgrade

명령이 성공적으로 완료되거나 특정 오류 발생 시 중지될 때까지 출력을 주시하십시오. 실패할 경우, 명령을 다시 실행하기 전에 해당 전제 조건을 해결하십시오. 일반적인 실패 원인으로는 호환되지 않는 애플리케이션, 지원되지 않는 PHP/데이터베이스 버전, 사용 불가능한 데이터베이스 서비스 또는 필요한 업데이트 작업을 방해하는 권한 문제 등이 있습니다. 마이그레이션이 실패하는 동안 웹 GUI를 반복적으로 새로 고치지 마십시오.

Nextcloud의 업그레이드 문서 에서도 주요 릴리스를 건너뛰지 말라고 경고합니다. 주요 버전을 변경할 때는 한 번에 하나의 주요 버전씩 업그레이드하십시오.

5. 마이그레이션 문제가 해결되면 Nextcloud의 복구 루틴을 실행하십시오.

maintenance:repairNextcloud 복구 단계를 실행하며 업그레이드 중에 자동으로 실행됩니다. 업데이트를 중단시킨 문제를 해결한 후 수동으로 실행하는 것이 좋습니다.

sudo -E -u www-data php occ maintenance:repair

이 방법 은 Nextcloud 코어 및 애플리케이션에서 복구 단계를 제공하므로 SQL 문을 직접 작성하는 것보다 안전합니다. 하지만 이 방법은 SQL 문을 완전히 대체하는 것은 아니며 occ upgrade, 작동하지 않는 데이터베이스 서버나 지원되지 않는 데이터베이스 버전을 복구하지는 않습니다. 해당 명령어는 Nextcloud 시스템 및 유지 관리 명령어 문서 에 설명되어 있습니다 .

6. 데이터베이스 서비스, 연결 설정 및 지원 버전을 확인합니다.

로그에 스키마 문제가 아닌 연결 문제가 표시되는 경우, 데이터베이스 서비스가 실행 중이고 Nextcloud PHP 환경에서 접근 가능한지 확인하십시오. 일반적인 MariaDB 호스트에서 유용한 확인 방법은 다음과 같습니다.

sudo systemctl status mariadb

그런 다음 데이터베이스 유형, 호스트, 데이터베이스 이름, 사용자 및 소켓 또는 포트 설정 등 데이터베이스 설정을 검토하십시오 config/config.php. Unix 소켓 오류는 "해당 파일 또는 디렉터리가 없습니다"라는 메시지로 나타날 수 있으며, 원격 데이터베이스 연결 실패는 라우팅, DNS, TLS, 방화벽 규칙, 자격 증명 또는 서버 자체의 문제로 인해 발생할 수 있습니다.

Nextcloud 주요 업데이트 후에는 버전 호환성이 중요합니다. Nextcloud 35의 공식 릴리스 노트에 따르면 MariaDB 10.6 및 MySQL 8.0은 더 이상 지원되지 않으며, 최소 요구 사항은 MariaDB 10.11 LTS 및 MySQL 8.4 LTS입니다. 데이터베이스를 개별적으로 업그레이드하기 전에 사용 중인 Nextcloud 주요 버전 에 대한 요구 사항을 확인하십시오 . Nextcloud 35로 업그레이드를 참조하십시오 .

7. 스키마 변경 사항을 검사하고 문서화된 누락된 구조만 추가합니다.

Nextcloud 35에는 db:schema:check설치된 코어 및 앱 마이그레이션에서 예상하는 스키마와 실제 스키마를 비교하는 기능이 추가되었습니다. 이 기능은 읽기 전용이며 데이터베이스를 변경하지 않고 차이점을 보고합니다.

sudo -E -u www-data php occ db:schema:check
sudo -E -u www-data php occ db:schema:check -v

관리자 개요 또는 명령 출력에 선택적 열, 인덱스 또는 기본 키가 누락되었다고 보고되는 경우, 문서화된 유지 관리 명령을 사용하십시오.

sudo -E -u www-data php occ db:add-missing-columns
sudo -E -u www-data php occ db:add-missing-indices
sudo -E -u www-data php occ db:add-missing-primary-keys

각 --dry-run명령은 SQL 미리보기를 지원합니다. 이러한 명령은 코어 마이그레이션 실패 시 대체 수단으로 사용해서는 안 됩니다. db:schema:check예상치 못한 객체 또는 열 속성 차이가 보고되는 경우, 변경하기 전에 해당 내용을 검토하십시오. Nextcloud는 일부 데이터베이스 전체 기본값이 예상 스키마 모델에서 벗어나 있음을 알려드립니다. 공식적인 명령 참조는 Nextcloud DAV 및 데이터베이스 명령 문서를 참조하십시오 .

8. 웹GUI를 다시 열기 전에 타사 앱 오류를 격리하십시오.

스택 트레이스에 배포되지 않은 앱 이름이 표시되는 경우, 해당 앱의 마이그레이션이 새 서버 버전과 호환되지 않을 수 있습니다. Nextcloud 문제 해결 가이드에서는 업그레이드 및 문제 해결 시 타사/배포되지 않은 앱을 비활성화할 것을 권장합니다. 설치된 버전에 포함된 앱 명령어를 사용하여 명령줄에서 해당 앱을 비활성화한 후, 다시 실행하고 occ upgrade호환되는 릴리스를 확인한 후에만 앱을 다시 활성화하십시오.

이 분기는 핵심 테이블이 정상적으로 보이지만 예외 발생 시 특정 공급업체 네임스페이스 또는 앱에 속한 테이블이 언급될 때 특히 중요합니다. 해당 앱의 테이블을 수동으로 삭제하면 앱이 여전히 필요로 하는 데이터가 손상될 수 있으므로 위험합니다.

9. 유지보수 모드를 종료하고 로그인 페이지 이상의 내용을 확인하십시오.

완료 후 occ upgrade, 복구/스키마 검사에서 더 이상 차단 문제가 발생하지 않고 데이터베이스 서비스가 안정되면 유지 관리 모드를 비활성화하십시오.

sudo -E -u www-data php occ maintenance:mode --off

그런 다음 인스턴스를 단계별로 검증합니다. 로그인 페이지를 로드하고, 로그인하고, 파일 앱을 열고, 몇 개의 폴더를 탐색하고, 파일 업로드/다운로드를 테스트하고, 관리자 설정에서 경고를 확인하고, 최신 nextcloud.log항목을 검토합니다. 또한 cron/백그라운드 작업이 정상적으로 실행되고 있는지 확인합니다. 홈페이지가 복구되었다고 해서 앱 마이그레이션, 파일 작업 및 백그라운드 작업이 정상적으로 작동하고 있다고 보장할 수는 없습니다.

복구 체크리스트

• 업데이트 전 백업 파일을 보관하고 지원되지 않는 다운그레이드를 피하십시오.
• nextcloud.logSQLSTATE 및 추적에 언급된 구성 요소를 포함하여 전체 데이터베이스 예외를 읽으십시오 .
• occ status복구 중에 인스턴스를 확인 하고 유지 관리 모드로 전환하십시오.
• occ upgrade지원되는 코어 및 앱 마이그레이션을 완료하려면 실행하세요 .
• 데이터베이스 테이블을 무턱대고 수정하기보다는 가장 먼저 발생하는 구체적인 문제점을 해결하세요.
• maintenance:repair근본적인 오류가 수정된 후 실행하십시오 .
• 데이터베이스 서비스 상태, 연결 설정 및 버전 호환성을 확인합니다.
• Nextcloud 35에서 사용하시고 , 필요한 경우 db:schema:check문서화된 명령어를 사용하십시오.db:add-missing-*
• 오류 추적에서 타사 앱이 원인으로 명확하게 지적되는 경우, 해당 앱을 비활성화한 후 업그레이드를 다시 시도하십시오.
• CLI 검사가 통과된 후에만 유지 관리 모드를 해제하고 파일, 전송, 관리자 경고, 로그 및 백그라운드 작업을 테스트하십시오.

복구 대신 복원을 선택해야 하는 경우는 언제일까요?

데이터베이스 자체가 손상되었거나, 마이그레이션으로 인해 데이터가 부분적으로 변경되어 안전하게 되돌릴 수 없는 경우, 또는 필수 테이블/데이터가 Nextcloud 외부에서 삭제된 경우에는 내부적으로 일관성이 유지되는 정상 백업에서 복원하십시오. 데이터베이스, 구성, 데이터 디렉터리 및 코드 버전은 호환되는 복구 지점에 속해야 합니다. Nextcloud 유료 지원을 이용 중이거나 비즈니스에 중요한 배포 환경인 경우, 파괴적인 SQL 작업을 수행하기 전에 작업을 중단하고 전체 로그 항목, 정확한 원본 및 대상 Nextcloud 버전, 데이터베이스 유형/버전, PHP 버전, 관련 occ명령의 출력 결과를 제공하여 지원팀에 보고하십시오.

핵심 원칙은 간단합니다. 업데이트 후 발생하는 "데이터베이스 오류"는 SQL 쿼리를 추측할 이유가 되지 않습니다. 로그를 통해 오류 원인을 파악하고, occ upgrade계획된 마이그레이션을 완료하고, Nextcloud 자체의 복구 및 스키마 도구를 사용하고, 인스턴스를 다시 열기 전에 데이터베이스 플랫폼을 검증하십시오.