Nextcloud 데이터베이스 업데이트 후 오류 발생 시 우선 확인 사항

Nextcloud 업데이트 후 "데이터베이스 오류" 예외가 발생하는 경우, nextcloud.log테이블을 변경하기 전에 먼저 기본 데이터베이스 오류를 확인하십시오. 데이터베이스 연결을 먼저 복원하고, 업데이트가 도중에 중단된 경우 업데이트를 완료한 다음 occ upgrade로그에 따라 필요한 경우에만 문서화된 복구 명령을 사용하십시오.

실제 실패 원인을 파악하십시오

브라우저 메시지는 증상일 뿐 진단은 아닙니다. Nextcloud가 MySQL/MariaDB 또는 PostgreSQL에 연결할 수 없거나, 데이터베이스 계정 인증에 실패했거나, 애플리케이션 코드와 스키마의 업그레이드 단계가 다를 수 있습니다. Nextcloud의 공식 문제 해결 가이드에서는 실패한 요청 ID를 서버 로그와 대조해 볼 것을 권장합니다.

1. 시간, 전체 브라우저 오류 메시지 및 표시된 요청 ID를 기록하십시오. 비밀 정보 및 개인 정보를 삭제하지 않고는 비공개 로그 항목을 게시하지 마십시오.
2. 구성된 데이터 디렉터리는 에서 찾을 수 있습니다 config/config.php. 기본 로그 파일은 이지만 data/nextcloud.log, 사용자 지정 배포의 경우 다른 위치에 로그가 기록될 수 있습니다.
3. 일반적인 Linux 설치 환경에서는 최근 항목을 확인한 다음 데이터베이스 서비스 로그를 확인하십시오. 실제 Nextcloud 경로로 바꿔야 합니다.

sudo tail -n 100 /var/www/nextcloud/data/nextcloud.log
sudo journalctl -u mariadb --since '30 minutes ago'

SQLSTATE두 번째 명령은 systemd에서 MariaDB를 실행하는 호스트에만 적용됩니다. 다른 배포 환경에서는 PostgreSQL 서비스 또는 컨테이너 로그를 사용하십시오. 마지막 스택 트레이스 줄에 의존하기보다는 예외 코드와 첫 번째 데이터베이스 관련 원인을 검색하십시오 .

처음 세 가지 예시는 Nextcloud의 문서화된 일반적인 오류에 설명되어 있습니다. 테이블 누락 메시지는 테이블을 수동으로 생성할 권한이 없다는 의미가 아닙니다. 먼저 정확한 마이그레이션 실패 원인을 파악해야 합니다.

수정 사항을 적용하기 전에 인스턴스를 보호하십시오.

마이그레이션을 다시 시도하기 전에 Nextcloud의 구성 및 데이터와 함께 복원 가능한 데이터베이스 백업을 생성하십시오. 공식 백업 절차에는 사용자 지정 앱 및 테마도 포함됩니다(있는 경우). 백업이 동일한 시점을 기준으로 생성되었는지 확인하십시오. 코드만 백업한 경우에는 부분적으로 변경된 데이터베이스를 복구할 수 없습니다.

• 가능한 경우, 특히 데이터베이스 쓰기 또는 업그레이드가 관련된 경우 복구 기간 동안 동기화 및 백그라운드 작업을 일시 중지하십시오.
• 이전 및 새 Nextcloud 버전, 데이터베이스 엔진/버전, PHP 버전, 업데이트 방법을 기록해 두십시오.
• 데이터베이스 테이블을 삭제하거나, 빈 스키마를 가져오거나, 포럼에서 찾은 임의의 SQL 쿼리를 실행하거나, 여러 부분으로 구성된 백업의 구성 요소 중 하나만 반복적으로 복원하지 마십시오.

아래 명령어는 일반적인 Debian/Ubuntu 설치 환경(경로: )에서 웹 서버 계정으로 실행되는 것을 /var/www/nextcloud가정 합니다. 적절한 HTTP 사용자 권한으로 실행하십시오. 패키지, Docker, Snap, AIO 및 관리형 설치의 경우 경로와 실행 방법이 다릅니다. occ 명령어 참조에서 이러한 요구 사항을 확인할 수 있습니다.www-dataocc

마이그레이션 전에 데이터베이스 연결을 복원하세요.

데이터베이스 서비스 및 Nextcloud 연결 설정을 확인하세요.

로그에 연결 거부, 연결할 수 없는 소켓 또는 사용할 수 없는 서버가 표시되는 경우 먼저 기존 데이터베이스 서비스가 실행 중인지 확인하십시오. 다음은 호스트 수준에서 수행할 수 있는 대체 검사이며, 무분별하게 실행해야 하는 목록이 아닙니다.

sudo systemctl status mariadb
sudo systemctl status postgresql

별도의 데이터베이스 서버를 사용하는 경우, DNS, 방화벽 규칙, 선택된 포트 및 Nextcloud 애플리케이션 호스트 또는 컨테이너에서의 네트워크 연결 가능성도 확인하십시오. `hostname`, `ports`, `socket` 등을 검사하십시오 . 구성 매개 config/config.php변수 참조 에서 호스트 이름, 포트 및 Unix 소켓 구문에 대한 설명을 확인할 수 있습니다. 공개 티켓이나 기록에 노출될 수 있는 셸 명령에 이러한 정보를 붙여넣지 마십시오 .dbtypedbhostdbnamedbuserdbpassword

배포 중에 데이터베이스 암호가 변경되었거나 자격 증명이 수정된 경우, 암호 관리 워크플로를 사용하여 불일치를 수정하십시오. 서버에서 연결 수가 너무 많다고 보고되는 경우, 용량 변경을 고려하기 전에 활성 연결과 연결 누적 원인을 검사하십시오. 인덱스 명령으로는 연결 끊김 문제를 해결할 수 없습니다.

업데이트 후 런타임 호환성을 확인하세요

PHP 또는 데이터베이스 서버를 동시에 업그레이드하면 기존에 정상적으로 작동하던 설치가 손상될 수 있습니다. 현재 설치된 모든 드라이버 및 서버 버전이 계속 지원된다고 가정하지 말고, 목표로 하는 Nextcloud 릴리스의 공식 시스템 요구 사항 및 릴리스 정보를 확인하십시오. 확인된 Nextcloud 35 문서에 따르면 PHP 8.3~8.5 버전이 지원되며, 지원되는 데이터베이스 버전은 별도로 명시되어 있습니다. 이전 릴리스의 경우 지원 제한 사항이 다를 수 있습니다.

또한 선택한 엔진에 필요한 PHP 데이터베이스 드라이버가 명령줄 및 웹 PHP 환경 모두에서 활성화되어 있는지 확인하십시오. 스키마 마이그레이션 후 데이터베이스 서버를 무조건 다운그레이드하지 마십시오. 호환되고 일관된 백업 계획에서만 복원하십시오.

중단된 Nextcloud 업그레이드를 완료하거나 복구하세요.

데이터베이스에 접근 가능하고 백업이 안전하게 완료되면 Nextcloud 설치 디렉토리로 이동하여 상태를 확인하십시오.

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

Nextcloud에서 업그레이드가 보류 중이거나 완료되지 않았다고 표시되면 설치된 소스 및 대상 버전에 대해 지원되는 업그레이드 경로를 따르십시오. 일반적인 수동 설치를 하려면 다음 명령을 실행하십시오.

sudo -E -u www-data php occ upgrade

명령을 중단하거나 다른 업그레이드 프로세스를 동시에 실행하지 마십시오. 출력 결과를 확인하십시오. 마이그레이션 성공 여부는 데이터베이스 연결 예외와 다릅니다. Nextcloud의 수동 업그레이드 설명서에는occ upgrade 웹 기반 프로세스가 중단되는 경우와 maintenance:repair업그레이드 경로에 수정이 필요한 경우에 대한 명확한 권장 사항이 나와 있습니다 .

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

maintenance:repair오류 분석 후 사용하십시오 . 이 방법은 잘못된 자격 증명, 중지된 데이터베이스 또는 실제 호환되지 않는 런타임 문제를 해결하는 대체 수단이 아닙니다. occ upgrade특정 SQL 마이그레이션에서 오류가 발생하는 경우, 정확한 예외를 저장하고 버전별 수정 방법을 찾거나 전체 백업을 복원하십시오. 수동 DDL을 시도하지 마십시오.

업그레이드가 성공적으로 완료된 후에만 스키마 경고를 처리하십시오.

일부 마이그레이션은 의도적으로 연기됩니다. 정상적으로 작동하는 인스턴스의 관리자 개요에서 선택적 열, 인덱스 또는 기본 키를 요청할 수 있습니다. 이러한 명령은 해당 버전에서 지원되는 경우 시뮬레이션 실행 미리보기를 제공합니다.

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

--dry-run로그에 기록된 문제 또는 관리 점검에서 요구하고 제안된 변경 사항이 검토된 경우에만 해당 명령을 실행하십시오 . 이러한 유지 관리 작업은 대규모 데이터베이스에서 시간이 오래 걸릴 수 있습니다. Nextcloud 35에서는 이 기능이 추가로 문서화되어 있으므로 db:schema:check이전 버전에는 존재하지 않는다고 가정하지 마십시오. 버전별 동작은 데이터베이스 명령 참조를 확인하십시오.

복구를 확인하고 접근 권한을 다시 열어주세요.

1. 이 과정을 반복하십시오 sudo -E -u www-data php occ status. 설치된 버전이 의도한 릴리스와 일치하는지, 업그레이드가 필요한지, 그리고 새로운 치명적인 SQL 예외가 발생하지 않는지 확인하십시오.
2. 유지 관리 모드가 여전히 켜져 있고 업그레이드가 성공적으로 완료된 경우 , 다음 명령으로 유지 관리 모드를 비활성화하십시오 sudo -E -u www-data php occ maintenance:mode --off.
3. 웹 GUI를 열고 로그인한 다음 파일 목록을 확인하고 간단한 업로드 및 다운로드 작업을 수행하십시오. nextcloud.log이러한 과정 중에 새로운 데이터베이스 예외가 발생하는지 주의 깊게 살펴보십시오.
4. 예약된 작업과 클라이언트 동기화를 재개한 다음, 관리자 설정에서 남아 있는 데이터베이스 경고가 있는지 확인하십시오.

동일한 데이터베이스 예외가 발생하는 경우, 반복적인 마이그레이션을 중지하고 요청 ID, SQLSTATE 텍스트, 데이터베이스 서버 로그, 버전 쌍 및 실패 occ출력 내용을 수집하십시오. 이러한 정보를 통해 남은 문제가 연결 문제인지, 소프트웨어 호환성 문제인지, 아니면 특정 마이그레이션 실패인지 판단할 수 있습니다. 로그인 성공만으로는 모든 백그라운드 작업과 데이터베이스 쿼리가 정상적으로 작동한다는 것을 보장할 수 없습니다.