OCC를 사용하여 Nextcloud 유지 관리 모드 오류를 안전하게 해결하세요

업데이트 또는 유지 관리 작업 후에도 Nextcloud에 "유지 관리 모드"가 계속 표시되는 경우, 먼저 데이터베이스 업그레이드가 완료되었는지 확인하십시오. 완료되었다는 occ status메시지가 표시 되면 해당 Nextcloud 설치 환경에서 웹 서버 사용자로 needsDbUpgrade: false명령을 실행하십시오 . 완료되지 않았다는 메시지가 표시되면 사이트를 다시 열기 전에 업그레이드 를 완료하십시오 .occ maintenance:mode --offtrueocc upgrade

플래그를 비활성화하면 로그인이 복원되지만, 실패한 업그레이드는 복구되지 않습니다. 목표는 유지 관리 플래그와 업그레이드 상태가 모두 확인된 상태로 인스턴스를 다시 온라인 상태로 만드는 것입니다.

1. 상태를 변경하기 전에 인스턴스를 확인하십시오.

해당 Nextcloud URL을 제공하는 호스트 또는 컨테이너에 연결합니다. Linux를 수동으로 설치한 경우, Nextcloud 디렉터리(일반적으로 `/nextcloud.com` /var/www/nextcloud)로 이동하여 HTTP 사용자로 상태를 확인합니다.

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

maintenance`maintenance` 와 `maintenance` 를 확인하세요 needsDbUpgrade. 일반적으로 `maintenance`가 `false`인 경우 유지보수 모드를 안전하게 비활성화할 수 있습니다 maintenance: true. needsDbUpgrade: false`maintenance`가 이미 `false`인 경우 브라우저가 오래된 페이지를 표시하거나 다른 백엔드에 연결하고 있을 수 있습니다. `maintenance`가 ` needsDbUpgradetrue`인 경우에는 아직 유지보수 모드를 해제하지 마세요.

Nextcloud는 파일 소유권을 일관되게 유지하기 위해 OCC를 HTTP 사용자로 실행해야 합니다. Debian 또는 Ubuntu에서는 일반적으로 `http` 사용자이지만 , 다른 배포판에서는 `http` , `http`, 또는 `http` 를 www-data사용할 수 있습니다 . 명령에서 사용자를 바꾸기 전에 설치된 서비스의 계정을 확인하십시오. 최신 Nextcloud OCC 설명서에는 사용자 차이점과 상태 명령에 대한 정보가 나와 있습니다.apachehttpwwwrun

2. OCC를 사용하여 유지 관리 모드를 비활성화합니다.

압축 파일 또는 패키지 설치의 경우, 올바른 스크립트가 포함된 디렉토리에서 명령을 실행하십시오 occ.

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

해당 명령은 유지 관리 모드가 비활성화되었음을 보고해야 합니다. 이 --off옵션은 유지 관리 상태를 변경하는 것이며, 마이그레이션을 실행하거나, 권한을 수정하거나, 중단된 파일 교체를 되돌리는 작업은 수행하지 않습니다.

설치 환경에 맞는 래퍼를 사용하세요. 공식 Nextcloud Docker 이미지의 경우, 프로젝트 문서에 docker execDocker Compose 예제가 모두 나와 있습니다. 샘플 컨테이너 또는 서비스 이름을 사용자의 이름으로 바꾸세요.

# Docker Compose; "app" is an example service name
docker compose exec --user www-data app php occ maintenance:mode --off

# Docker; replace CONTAINER_ID with the Nextcloud container
docker exec -it --user www-data CONTAINER_ID php occ maintenance:mode --off

Nextcloud Snap의 경우, Snap의 내부 디렉터리에 직접 접근하는 대신 호스트 측 OCC 래퍼를 사용하십시오.

sudo nextcloud.occ maintenance:mode --off

Snap 프로젝트 설명에 따르면 /snap/bin/nextcloud.occ해당 디렉터리가 셸의 PATH에 포함되어 있지 않은 경우 필요할 수 있습니다. Snap의 유지 관리 모드 지침을 참조하세요. Nextcloud Docker 이미지 의 공식 README 파일에는 컨테이너 명령 패턴이 설명되어 있습니다.

3. 업그레이드가 아직 진행 중이라면 먼저 완료하세요.

상태 보고서에 needsDbUpgrade: true오류가 발생하면 Nextcloud는 코드와 데이터베이스 마이그레이션이 동기화되지 않았음을 나타냅니다. 이는 일반적으로 업데이트 프로그램이 코드를 교체했지만 마이그레이션 단계가 완료되지 않은 경우에 발생합니다. 이러한 상태에서는 제한된 OCC 명령만 사용할 수 있으며, 업그레이드 중에 사용자의 접근을 차단하기 위해 유지 관리 모드가 의도적으로 유지될 수 있습니다.

설치 유형에 맞는 업그레이드 경로를 사용하고, 진행하기 전에 업데이트 프로그램의 오류를 검토하십시오. 표준 아카이브 기반 설치의 경우, 원하는 Nextcloud 코드 버전이 있는지 확인하고, 데이터베이스 및 파일/구성 백업이 없는 경우 새로 백업한 후 다음 명령을 실행하십시오.

sudo -E -u www-data php occ upgrade

명령이 완료되고 보고된 오류가 해결될 때까지 기다리십시오. 마이그레이션 오류를 해결하기 위해 유지 관리 모드를 반복적으로 전환하지 마십시오. Nextcloud의 업그레이드 문서에 따르면 데이터베이스 마이그레이션은 서버 코드 교체 후에 진행되며, 업그레이드 전에 최신 백업을 생성하는 것이 좋습니다. Docker, Snap 및 관리형 패키지는 각각 고유한 업그레이드 절차를 가질 수 있습니다. 아카이브 기반 예제와 절차가 다른 경우 해당 지침을 따르십시오.

업그레이드가 성공적으로 완료되고 상태에 더 이상 보류 중인 데이터베이스 업그레이드가 표시되지 않으면 maintenance:mode --off위의 해당 명령을 실행하십시오. config.php데이터베이스를 직접 수정하거나 바로가기 명령으로 사용하는 것은 피하십시오. OCC에서 설정을 쓸 수 없는 경우, 올바른 설치 및 HTTP 사용자를 선택했는지 확인하고, 권한을 변경하기 전에 읽기 전용 구성 정책이나 파일 시스템 권한 오류가 있는지 검사하십시오.

4. 플래그와 실제 사이트를 확인합니다.

동일한 설치 경로, 컨테이너 및 사용자를 사용하여 상태를 다시 실행하십시오.

sudo -E -u www-data php occ status

maintenance: false와 를 모두 확인하십시오 needsDbUpgrade: false. Docker 또는 Snap 환경에서는 플래그를 비활성화하는 데 사용한 것과 동일한 래퍼를 통해 다시 확인하십시오. Nextcloud 상태 명령은 이러한 필드를 문서화하며, 기계 판독 가능한 형식은 입니다 occ status --output=json_pretty.

그런 다음 새 브라우저 탭에서 사이트를 새로 고침하고 정상적인 로그인 및 파일 목록 표시를 테스트하십시오. Nextcloud는 유지보수 모드 이전에 로그인한 사용자는 서버가 다시 온라인 상태가 된 후 브라우저를 새로 고쳐야 할 수 있다고 안내합니다. OCC에서 유지보수 상태가 아니라고 보고하지만 사이트에 여전히 유지보수 페이지가 표시되는 경우 호스트 이름 또는 로드 밸런서가 변경한 인스턴스와 동일한 인스턴스로 연결되는지 확인하십시오. 컨테이너 또는 노드가 여러 개인 경우 다른 백엔드가 여전히 유지보수 모드일 수 있습니다.

따라서 성공적인 수정은 단순히 "비활성화됨"이라는 명령 응답 이상의 의미를 갖습니다. OCC 상태에서 두 플래그가 모두 해제된 것으로 표시되어야 하며, 의도한 공개 URL에서 정상적으로 작동하는 인스턴스가 제공되어야 합니다. 업그레이드 플래그가 여전히 활성화되어 있거나 마이그레이션 명령이 실패하는 경우, 사용자의 접근을 차단하고 Nextcloud를 다시 열기 전에 해당 업그레이드 오류를 해결해야 합니다.