MySQL 버전 업그레이드 후 Kopano 데이터베이스 마이그레이션 오류 해결 방법

MySQL 또는 MariaDB 버전 업그레이드 직후 Kopano 데이터베이스 마이그레이션 오류가 발생하는 것은 일반적으로 애플리케이션과 데이터베이스 간에 이전에 암묵적으로 유지되었던 스키마 상태, 서버 기본 설정, SQL 동작, 인증 또는 업그레이드 경로 자체와 같은 요소에 대한 일관성이 깨졌음을 의미합니다. 진정한 목표는 단순히 kopano-server한 번 시작하는 것만이 아니라, 스키마 일관성을 유지하고, 데이터베이스 업그레이드 오류 없이 Kopano가 시작되고, 사용자가 상점을 열 수 있으며, 메일 흐름이 재시작 후에도 유지되는 상태를 달성하는 것입니다.

이 가이드는 증거에 중점을 둡니다. 각 단계에는 성공 신호와 동일한 해결 방법을 시도하는 것을 중단하고 방향을 전환해야 하는 시점이 포함되어 있습니다. Kopano의 공개 관리자 문서는 최신 MySQL 및 MariaDB 릴리스보다 오래되었으므로 모든 최신 데이터베이스 버전이 모든 이전 Kopano 빌드에서 지원된다고 가정하지 마십시오. 정확한 Kopano 패키지 버전, 데이터베이스 공급업체 및 서버 오류를 결정적인 증거로 사용하십시오.

원하는 결과부터 시작하세요

설정을 변경하기 전에 "수정됨"의 의미를 정의하십시오. 정상적인 복구는 일반적으로 다음과 같은 모든 징후를 보입니다.

• kopano-server서비스 재시작 후에도 계속 실행 상태를 유지합니다.
• Kopano 로그는 더 이상 데이터베이스 스키마 업그레이드 또는 SQL 실행 실패를 보고하지 않습니다.
• 설정된 Kopano 계정으로 데이터베이스를 읽고 쓸 수 있습니다.
• 기존 상점과 사용자가 표시되며, 새롭게 생성된 빈 스키마는 표시되지 않습니다.
• 우편물 접수 및 배송이 정상적으로 재개되었습니다.
• 두 번째 재시작도 동일하게 정상적인 결과를 보여줍니다.

첫 번째 항목만 달성했더라도 계속 테스트하십시오. sql_mode예를 들어 변경 후 일시적으로 시작하는 것만으로는 기본 스키마가 올바르다는 것을 증명할 수 없습니다.

1. Kopano 라이터를 중지하고 복원 가능한 데이터베이스 백업을 생성하십시오.

Kopano 업그레이드 문서에서는 업그레이드 작업을 시작하기 전에 데이터베이스 및 구성 파일을 백업하고 데이터베이스를 사용하는 서비스를 중지할 것을 권장합니다. 특히, 실행 중인 구성 요소 외에도 특정 구성 요소를 중지해야 한다고 명시되어 있습니다. 자세한 내용은 kopano-spoolerKopano kopano-serverCore 업그레이드 문서를 참조하십시오 .

sudo systemctl stop kopano-spooler
sudo systemctl stop kopano-server

mysqldump -u root -p --single-transaction kopano > /root/kopano-before-fix.sql
ls -lh /root/kopano-before-fix.sql

대규모 설치의 경우, /etc/kopano/첨부 파일 저장 위치를 ​​기록해 두고 기존 데이터베이스 백업 정책을 준수하십시오. 첨부 파일이 MySQL 외부에 저장되는 경우, SQL 덤프만으로는 완전한 Kopano 백업이 아닙니다.

데이터베이스에 쓰기 작업을 수행하는 Kopano 서비스를 중지하고 스키마 또는 서버 설정을 변경하기 전에 최신 덤프 파일이 있는지 확인하십시오.

성공 신호: 별도의 데이터베이스 인스턴스에 복원할 수 있는 백업이 생성되었고 외부 첨부 파일이 저장된 위치를 알고 있는 경우입니다. 다음과 같은 경우 접근 방식을 변경하십시오: 덤프 자체에 실패한 경우. Kopano 스키마 마이그레이션을 시도하기 전에 데이터베이스 손상, 권한, 디스크 공간 또는 연결 문제를 해결하십시오.

2. 정확한 데이터베이스 버전과 변경된 기본 설정을 기록하십시오.

MySQL의 주요 업그레이드는 기존 테이블을 수정하지 않고도 서버 기본값을 변경할 수 있습니다. 예를 들어 MySQL 8.0에서는 기본 서버 문자 집합이 로 utf8mb4, 기본 정렬 방식이 로 변경되었습니다 utf8mb4_0900_ai_ci. 또한 다른 기본값도 변경되었고, 이전 동작은 제거되거나 더 이상 사용되지 않게 되었습니다. Oracle은 이러한 변경 사항을 MySQL 8.0의 변경 사항 문서에 자세히 설명하고 있습니다 .

패키지 업그레이드가 어떤 결과를 가져왔는지 추측하는 대신, 서버의 실제 상태를 파악하십시오.

mysql -u root -p

SELECT VERSION();
SHOW VARIABLES LIKE 'sql_mode';
SHOW VARIABLES LIKE 'character_set_server';
SHOW VARIABLES LIKE 'collation_server';

Kopano가 현재 인식하는 데이터베이스 버전과 기본값을 기록해 두십시오. 이러한 값은 데이터베이스 업그레이드 후에만 발생한 오류를 설명하는 데 도움이 됩니다.

엄격한 SQL 모드를 즉시 비활성화하지 마십시오. 엄격 모드 오류는 수정해야 할 잘못된 레거시 데이터 또는 SQL을 드러낼 수 있습니다. 엄격 모드를 끄면 나중에 오류가 발생하는 데이터를 그대로 둔 채 증상이 가려질 수 있습니다. 먼저 Kopano 로그에서 정확한 오류 문장 또는 데이터베이스 오류를 캡처하십시오.

3. 최종 서비스 실패뿐만 아니라 첫 번째 SQL 오류도 읽어보세요.

Systemd는 종료되었다는 메시지만 표시하는 경우가 많습니다 kopano-server. 유용한 정보는 보통 저널이나 Kopano 로그의 앞부분에 있습니다. 다음부터 확인해 보세요.

journalctl -u kopano-server -n 100 --no-pager

다음으로 고장 원인을 분류하십시오. 아래 표는 모든 설치 환경에 하나의 원인이 적용된다는 주장이 아니라, 실용적인 문제 해결 지침서입니다.

Kopano의 변경 로그를 확인하면 일부 릴리스에서 특정 작업이 필요한 스키마 변경 사항이 도입되었음을 알 수 있습니다 . 또한 이전 MySQL 테이블 정의 및 utf8mb4 업그레이드와 관련된 오류를 포함하여 과거 데이터베이스 업그레이드 결함도 기록되어 있습니다. Kopano Core 변경 로그를kopano-dbadm 사용하여 사용 중인 Kopano 릴리스에 맞는 유지 관리 작업을 찾으십시오.

4. 기존 코파노 스키마와 새 서버 기본 설정을 비교합니다.

현재 스키마를 확인하십시오. 서버 기본 설정만으로는 기존 Kopano 테이블이 어떻게 정의되었는지 알 수 없습니다.

SHOW CREATE DATABASE kopano;
SHOW TABLE STATUS FROM kopano;

기존 Kopano 데이터베이스 정의 및 스토리지 엔진을 검사하고, 비교를 위해 원래 마이그레이션 오류를 표시해 둡니다.

데이터베이스가 이전 MySQL 릴리스에서 생성된 경우, 새로 생성되는 객체의 기본 문자 집합이 utf8mb4로 변경되더라도 테이블은 이전 문자 집합을 유지할 수 있습니다. MySQL은 5.7에서 8.0으로 업그레이드할 때 기존 데이터베이스 객체가 새 기본 문자 집합으로 자동으로 변환되지 않는다고 명시적으로 밝히고 있습니다. 이러한 차이점은 중요합니다. 새 열이나 인덱스가 인접한 객체와 다른 기본값으로 생성될 경우 마이그레이션이 실패할 수 있기 때문입니다.

Kopano는 최신 Core 릴리스에서 utf8mb4 지원을 추가했으며, 기존 데이터베이스를 4바이트 유니코드 지원으로 업그레이드하는 특정 데이터베이스 유지 관리 단계를 문서화했습니다 kopano-dbadm usmp. MySQL이 이제 기본적으로 utf8mb4를 사용한다고 해서 해당 명령을 실행하지 마십시오. 설치된 Kopano 릴리스 문서 또는 서버 출력에서 ​​해당 명령을 실행하라고 요구하는 경우에만 실행하십시오.

5. MariaDB를 업그레이드한 경우, MariaDB 측 업그레이드를 먼저 완료하십시오.

백엔드가 Oracle MySQL이 아닌 MariaDB인 경우, Kopano를 탓하기 전에 데이터베이스 서버 자체의 업그레이드 절차를 완료하십시오. MariaDB 문서 mariadb-upgrade에 따르면, 이 도구는 주요 버전 변경 후 시스템 테이블을 업데이트하고 테이블을 검사합니다. 해당 문서에서는 모든 데이터베이스를 먼저 백업할 것을 권장합니다. 공식 mariadb-upgrade 참조 문서를 확인하십시오 .

이것은 특정 환경에 특화된 명령이지, 범용 명령이 아닙니다. Oracle MySQL을 대상으로 실행하지 마십시오 mariadb-upgrade. 마찬가지로, MySQL 8.0과 MariaDB 서버 모두 클라이언트 프로토콜을 지원한다고 해서 MySQL 8.0의 기본 가정을 MariaDB 서버에 적용하지 마십시오 mysql.

6. 코파노 데이터베이스 계정에 필요한 권한이 여전히 있는지 확인하십시오.

Kopano 관리자 설명서에 따르면 서버에는 Kopano 데이터베이스에 대한 ALTER, CREATE, CREATE ROUTINE, DELETE, DROP, INDEX, INSERT, LOCK TABLES, SELECT, 및 권한을 포함한 권한이 필요합니다 UPDATE. 데이터베이스 연결 매개변수는 MySQL 관련 설정에서 구성됩니다 /etc/kopano/server.cfg. KC 구성 요소 구성을 참조하십시오 .

MySQL 버전 마이그레이션 후 관리자는 사용자를 다시 생성하거나, 인증 플러그인을 변경하거나, 데이터베이스 호스트를 이동하거나, 권한을 불완전하게 복원할 수 있습니다. Kopano에서 사용하는 것과 동일한 호스트 이름과 계정으로 테스트하십시오. 마이그레이션 SQL이 실행되기 전에 인증에 실패하면 계정 또는 권한 문제를 먼저 해결해야 합니다.

7. 오류가 발생했음을 입증하는 부분만 수리하십시오.

이 시점에서 여러분은 구체적인 실패 유형을 하나 확보했을 것입니다. 그 실패 유형을 설명할 수 있는 최소한의 변경 사항을 적용하세요.

• Kopano 스키마 부분 업데이트: 설치된 버전에 따라 릴리스별 Kopano 업그레이드 또는 kopano-dbadm지침을 따르십시오. 다음 명령 실행을 위해 버전 표시를 삭제하거나 열을 수동으로 추가하지 마십시오.
• 문자 집합 또는 정렬 불일치: 먼저 영향을 받는 테이블과 열을 식별하십시오. 문자 집합 변경은 인덱스 크기와 비교 동작을 변경할 수 있으므로 프로덕션 환경에 적용하기 전에 복원된 복사본을 기준으로 변환 계획을 세우십시오.
• MariaDB 시스템 테이블 불일치: 문서에 설명된 MariaDB 업그레이드 절차를 완료한 후 Kopano를 다시 시도하십시오.
• 권한 또는 인증: Kopano DB 계정을 수정하고 Kopano 호스트에서 로그인이 제대로 되었는지 확인하십시오.
• 지원되지 않는 버전 조합입니다. 구성 실험을 중지하십시오. 업그레이드 전 데이터베이스 환경을 복원하거나 공급업체 또는 패키지 소스에서 지원하는 Kopano/데이터베이스 조합으로 변경하십시오.

마지막 경우가 중요합니다. 공개적으로 접근 가능한 Kopano Core 관리자 설명서는 이전 제품 세대를 기준으로 작성된 것이며, 현재 MySQL 및 MariaDB 릴리스는 지속적으로 변경되었습니다. 따라서 사용 중인 제품과 정확히 일치하는 지원 설명서를 찾을 수 없다고 해서 문서가 없다는 것이 호환성을 의미하는 것은 아닙니다.

8. Kopano를 시작하고 프로세스 상태 외에도 다른 항목들을 검증하십시오.

sudo systemctl start kopano-server
sudo systemctl start kopano-spooler

systemctl --no-pager --full status kopano-server
journalctl -u kopano-server -n 50 --no-pager

정상적인 서비스 상태는 필수적이지만 충분조건은 아닙니다. 시작 로그를 검토한 후 사용자 저장소와 메일 흐름을 검증하십시오.

서비스가 정상적으로 작동하면 실제 애플리케이션 동작으로 테스트하십시오. 기존 사서함을 하나 이상 열고 이전 폴더와 메시지가 있는지 확인하고, 로컬 계정 간에 메시지를 보내고, 발신 메시지를 하나 보내고, 수신 배달이 제대로 작동하는지 확인하십시오. IMAP, ActiveSync, 아카이빙, 다중 서버 구성 요소 또는 외부 첨부 파일 저장소를 사용하는 경우 해당 경로도 테스트하십시오.

언제 접근 방식을 바꿔야 할까요?

다음 조건 중 하나라도 발생하면 스키마 변경을 반복하지 마십시오.

• 수동으로 수정할 때마다 SQL 오류가 바뀌는 것으로 보아 스키마가 부분적으로만 마이그레이션된 것 같습니다.
• 복원된 업그레이드 전 데이터베이스는 이전 데이터베이스 버전에서는 작동하지만 새 버전에서는 지속적으로 오류가 발생합니다.
• Kopano 빌드가 설치된 MySQL 또는 MariaDB의 주요 버전을 지원하는지 확인할 수 없습니다.
• 테이블 검사에서 일반적인 스키마 비호환성이 아닌 데이터 손상이 보고됩니다.
• 문자 집합 변환은 롤백 테스트를 거치지 않고서는 많은 대규모 테이블을 변경해야 하는 작업입니다.

이러한 경우, 이전 데이터베이스 환경을 다시 구축하고, 정상적인 백업을 복원한 다음, 클론 환경에서 단계적 업그레이드를 계획하는 것이 더 안전한 방법입니다. Oracle은 MySQL 8.0에서 5.7로 다운그레이드하는 것은 제자리에서 지원되지 않으며, 업그레이드 전에 생성된 백업을 복원하는 것이 지원되는 대안이라고 명시하고 있습니다. MySQL 8.0 릴리스 노트를 참조하십시오 .

최종 확인 체크리스트

• 데이터베이스 백업과 Kopano 설정 백업은 보존됩니다.
• 정확한 MySQL 또는 MariaDB 버전이 기록됩니다.
• 첫 번째 실제 SQL 오류가 확인되었으며 설명이 제공되었습니다.
• 증거 없이 광범위한 SQL 모드 또는 문자 집합 관련 해결 방법을 적용하지 않았습니다.
• Kopano 스키마 유지 관리에 필요한 사항은 설치된 Kopano 릴리스와 일치해야 합니다.
• kopano-server두 번째 재시작에서도 살아남습니다.
• 기존 사서함, 폴더 및 메시지는 그대로 유지됩니다.
• 입고, 출고 및 지역 배송 테스트가 모두 성공했습니다.
• 사용자 환경에서 사용되는 선택적 구성 요소는 테스트를 완료했습니다.

데이터베이스 마이그레이션 문제는 오류 메시지가 사라졌다고 해서 해결된 것이 아니라, 스키마, 데이터베이스 서버 및 Kopano 버전이 다시 일치할 때 해결된 것입니다. 문제 해결 과정을 기록해 두십시오. 다음 데이터베이스 또는 Kopano 업그레이드 시에도 해당 정보가 필요합니다.