Nextcloud의 "데이터베이스에 일부 인덱스가 누락되었습니다" 경고를 해결하는 방법

Nextcloud 관리자 개요를 열었을 때 "데이터베이스에 일부 인덱스가 누락되었습니다."라는 메시지가 표시될 수 있습니다. 이 경고는 Nextcloud 업그레이드 후 발생할 수 있는데, Nextcloud는 시간이 지남에 따라 기존 테이블에 새 인덱스를 추가할 수 있지만 대규모 데이터베이스에서는 인덱스를 자동으로 생성하지 않는 경우가 있기 때문입니다. 인덱스가 누락되면 일부 데이터베이스 쿼리 속도가 느려질 수 있습니다. 지원되는 복구 방법은 내장 occ db:add-missing-indices명령어를 사용하는 것입니다.

스키마를 변경하기 전에 올바른 Nextcloud 설치 버전에 맞는 명령어를 실행하고 있는지 확인하고, 데이터베이스를 백업한 후 웹 서버의 운영 체제 사용자 계정으로 로그인하십시오. 명령어가 지원하는 버전에서는 `--preview` 명령어를 사용하여 제안된 SQL 문을 미리 볼 수 있습니다 --dry-run. 그런 다음 복구를 실행하고 관리 개요를 다시 확인하십시오.

경고의 의미는 무엇인가요?

데이터베이스 인덱스는 전체 테이블을 스캔하지 않고도 데이터베이스에서 특정 행을 찾을 수 있도록 도와주는 구조입니다. Nextcloud와 해당 앱들은 사용하는 테이블과 필드에 인덱스를 정의합니다. 새로운 Nextcloud 릴리스 또는 앱 버전에서 기존 설치에 아직 없는 인덱스가 도입될 경우, 관리자 페이지에 불일치 메시지가 표시될 수 있습니다. 이는 스키마 유지 관리 관련 경고이며, 그 자체로는 데이터베이스가 손상되었거나 사용자 파일이 누락되었다는 의미는 아닙니다.

Nextcloud 관리 설명서에 따르면 인덱스는 성능 향상을 포함하여 시간이 지남에 따라 추가될 수 있으며, 관리자는 명령어를 실행하도록 안내됩니다 occ db:add-missing-indices. 인덱스 추가는 특히 대규모 테이블의 경우 시간이 걸릴 수 있으며, 데이터베이스 부하 또는 잠금 동작은 데이터베이스 엔진 및 워크로드에 따라 달라질 수 있습니다. 인스턴스 사용량이 많은 경우 사용량이 적은 시간대에 변경 작업을 계획하십시오.

수리를 실행하기 전에

• 설치 경로와 버전을 확인하십시오. 설치 occ스크립트가 있는 디렉터리에서 명령을 실행하거나 전체 경로를 제공하십시오.
• 데이터베이스를 백업하십시오. MariaDB/MySQL, PostgreSQL 또는 SQLite에 대한 일반적인 백업 절차를 따르십시오. 백업이 완료되었는지, 그리고 복원 방법을 알고 있는지 확인하십시오.
• HTTP 사용자를 찾으세요. Nextcloud 웹 서버를 실행하는 계정을 사용하십시오. 일반적인 예로는 www-dataDebian 또는 Ubuntu, apacheFedora 또는 CentOS, httpArch 및 wwwrunopenSUSE가 있습니다. 배포 환경에 따라 다를 수 있습니다.
• 명령 옵션을 확인하세요. Nextcloud 35 안정 버전 관리 설명서를 참조하십시오 --dry-run. 설치된 버전에서 해당 옵션을 인식하지 못하는 경우, 해당 버전의 occ db:add-missing-indices --help출력 내용을 확인하고 옵션이 있다고 가정하지 말고 미리 보기를 건너뛰세요.

공식 백업 가이드에는 전체 백업 시 보존해야 하는 데이터베이스, 구성, 데이터 디렉터리 및 기타 설치 구성 요소가 나열되어 있습니다. 이 스키마 작업을 수행하기 전에 최소한 사용 중인 데이터베이스에 적합한 절차를 사용하여 테스트를 거친 데이터베이스 백업을 생성하십시오.

1단계: Nextcloud 설치 환경에서 셸을 엽니다.

일반적인 Linux 설치의 경우 SSH를 통해 서버에 연결하고 Nextcloud 디렉토리로 이동하세요. 일반적인 Ubuntu 경로는 ` /var/www/nextcloud/Nextcloud.com/next ...

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

상태 출력에서 ​​예상대로 설치된 인스턴스가 표시되는지 확인하십시오. 셸의 기본값과 다른 PHP 바이너리를 웹 서버에 사용하는 경우 php, 동일한 호환 PHP 버전을 사용하십시오 occ. occHTTP 사용자로 실행하면 예상되는 파일 소유권 및 권한을 유지하는 데 도움이 됩니다.

2단계: 인덱스 변경 사항 미리 보기

설치된 버전에서 지원하는 경우, 먼저 모의 실행을 해보세요.

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

테스트 실행은 SQL 문을 적용하지 않고 미리 보여줍니다. 출력 결과를 읽고 복구하려는 누락된 인덱스와 관련된 내용인지 확인하십시오. 출력 결과에 알 수 없는 테이블이나 인덱스가 표시되면 정확한 이름을 기록하고 관련 애플리케이션이 설치되어 있고 최신 버전인지 확인하십시오. 미리 보기로 실행한 SQL 문을 데이터베이스 콘솔에 바로 붙여넣지 마십시오.

3단계: 누락된 인덱스를 추가합니다.

미리 보기가 예상되고 백업이 준비되면 문서에 설명된 복구 명령을 실행하십시오.

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

이 명령은 데이터베이스 테이블을 확인하고 스키마에 정의되어 있지만 현재 설치에 누락된 인덱스를 생성합니다. 완료될 때까지 기다리십시오. 대규모 데이터베이스의 경우 시간이 다소 걸릴 수 있습니다. 스키마 변경 중에는 중단하지 마십시오. Nextcloud 문서에 따르면 이 명령은 인스턴스가 온라인 상태인 동안 실행할 수 있으며, 이 특정 복구 작업에 유지 관리 모드가 필수 조건으로 명시되어 있지 않습니다. 유지 관리 기간이 필요한 경우 자체 변경 관리 프로세스를 따르십시오.

Docker 및 기타 설치 유형

컨테이너 기반 배포 환경에서는 occ데이터베이스 컨테이너가 아닌 Nextcloud 애플리케이션 컨테이너 내부에서 실행해야 합니다. 컨테이너 및 서비스 이름은 다를 수 있으므로 배포 환경을 확인하고 올바른 이름으로 바꿔야 합니다. 예를 들어, `<Nextcloud.app>`이라는 이름의 Docker 컨테이너의 경우 nextcloud, 이름 패턴은 다음과 같습니다.

docker exec --user www-data nextcloud php occ db:add-missing-indices

Docker Compose의 경우, 해당 패턴은 다음과 같습니다 docker compose exec -u www-data <nextcloud-service> php occ db:add-missing-indices. 일부 패키지 배포는 전용 명령이나 다른 컨테이너 사용자를 사용합니다. 해당 패키지에 대한 지침을 정확히 따르십시오. 다른 사람의 설정에서 컨테이너 이름을 복사할 때는 반드시 확인하십시오.

명령이 실패하거나 경고가 계속 표시되는 경우

• 권한이 거부되었습니다. HTTP 사용자와 설치 경로를 확인하십시오. 배포 설명서에서 특별히 권한 있는 래퍼 실행을 요구하지 않는 한, 루트 권한으로 명령을 실행하여 이 문제를 해결하지 마십시오. PHP 프로세스는 일반적으로 웹 서버 사용자 권한으로 실행되어야 합니다.
• 데이터베이스 연결 또는 PHP 오류: Nextcloud 로그, 데이터베이스 서비스 상태, 구성된 PHP 버전 및 명령 출력 결과를 확인하십시오. 스키마 명령을 다시 실행하기 전에 근본적인 연결 또는 런타임 문제를 해결하십시오.
• 중복 키 또는 고유 인덱스 오류: 작업을 중지하고 전체 오류 메시지를 보관하십시오. 이 오류는 고유 인덱스 생성을 방해하는 충돌하는 행이 있음을 나타낼 수 있습니다. 영향을 받는 앱과 테이블을 확인하고 앱 및 Nextcloud 버전을 확인한 후 앱 관리자 또는 해당 데이터베이스에 익숙한 관리자에게 문의하십시오. 데이터별 진단 및 백업 없이 행을 삭제하거나 인덱스를 삭제하지 마십시오.
• "명령을 찾을 수 없음" 또는 지원되지 않는 옵션이 표시되는 경우: 올바른 Nextcloud 설치 환경에 있는지 확인하고 HTTP 사용자로 로그인 php occ list했는지 확인하십시오. 이전 버전에서는 최신 옵션이 모두 표시되지 않을 수 있습니다.php occ help db:add-missing-indices
• 명령이 성공적으로 종료된 후에도 경고 메시지가 계속 표시됩니다 . 경고에 표시된 인덱스 및 테이블 이름을 확인하십시오. 누락된 인덱스가 두 개 이상 있거나, 애플리케이션 업데이트로 인해 새로 추가된 인덱스가 있거나, 데이터베이스 작업이 실패했거나, 이 명령에서 해결하지 못한 스키마 불일치가 있을 수 있습니다.

인덱스 누락과 열 또는 기본 키 누락을 혼동하지 마십시오. Nextcloud는 이러한 스키마 변경에 대한 별도의 명령(예: db:add-missing-columns및 ) 을 문서화하고 있습니다 db:add-missing-primary-keys. 관리자 경고 또는 버전별 문서에서 요구하는 경우에만 다른 복구 명령을 실행하십시오.

결과를 확인하세요

1. db:add-missing-indices종료 및 보고서 작성이 완료될 때까지 기다리십시오 .Done.
2. 관리자 개요를 다시 로드하고 특정 인덱스 누락 경고가 사라졌는지 확인하십시오.
3. 만약 문제가 해결되지 않으면, 명령 실행 결과를 그대로 따라하기보다는 해당 테이블과 인덱스 이름을 명령 출력 결과와 비교해 보세요.
4. Nextcloud 로그와 데이터베이스 상태를 확인하여 새로운 오류가 있는지 확인한 다음, 정상적인 파일 액세스와 해당 테이블을 사용하는 애플리케이션이 여전히 작동하는지 확인하십시오.
5. 인스턴스가 정상적으로 작동하고 보존 정책에 따라 삭제가 허용될 때까지 백업을 보관하십시오.

최신 명령 구문은 Nextcloud 데이터베이스 및 인덱스 명령 참조를 확인하세요 . 사용자 및 PHP 요구 사항은 occ 명령 사용 및 Nextcloud 백업 가이드를 참조하세요 . 이 안정적인 페이지는 2026년 10월 6일 확인 당시 Nextcloud Server 35 버전을 기준으로 작성되었으며, 다른 릴리스 또는 배포 유형에서는 경로, 옵션 및 패키징 지침이 다를 수 있습니다.