레거시 설치에서 이전하는 방법

이 가이드는 오래된 HandyCafe V3 또는 V4 설치의 기존 데이터를 현대 HandyCafe 서버로 가져오는 방법을 설명합니다. 마이그레이션은 원본을 훼손하지 않습니다. 원본 파일은 수정되거나 삭제되지 않습니다.

데이터베이스 마이그레이션은 Windows에서만 실행됩니다. 원래 프로토콜로 연결하는 레거시 클라이언트의 런타임 지원은 모든 플랫폼에서 작동합니다(레거시 클라이언트 설정 참고).

준비물

• 레거시 설치와 현대 HandyCafe 서버가 같은 시스템에 있는 Windows 컴퓨터, 또는 레거시 데이터베이스 파일에 접근할 수 있는 환경
• HandyCafe Server에 대한 관리자 접근 권한
• 중지된 레거시 서버. 마이그레이션 중 원본 데이터베이스는 계속 기록되면 안 됩니다.
• 레거시 데이터베이스 크기 이상만큼의 여유 디스크 공간(새 HandyCafe 데이터베이스 복사본용)
• 10~30분의 중단 없는 시간. 큰 데이터셋은 몇 분이 걸릴 수 있습니다. 실행 중에는 HandyCafe를 닫지 마세요.

1단계: 레거시 서버 중지

레거시 HandyCafe 서버 애플리케이션을 엽니다. 모든 세션을 종료하고 애플리케이션을 닫습니다. 레거시 서버가 Windows 서비스로 실행 중이라면 services.msc에서 서비스를 중지합니다.

예상 결과: 레거시 서버 프로세스가 더 이상 실행되지 않습니다. 데이터베이스 파일도 열린 상태가 아닙니다.

2단계: 레거시 클라이언트 설정 페이지 열기

1. HandyCafe를 실행합니다.
2. 사이드바에서 설정을 엽니다.
3. 레거시 클라이언트를 클릭합니다.
4. 데이터베이스 마이그레이션 섹션으로 스크롤합니다.

예상 결과: 시스템이 레거시 설치를 감지하면 설치 경로, 데이터베이스 경로, 서버 버전, INI 파일 수가 표시됩니다. 아무 것도 감지되지 않으면 페이지에 "레거시 설치가 감지되지 않았습니다."가 표시됩니다. 이 경우 Program Files\HandyCafe 또는 C:\HandyCafe 같은 표준 위치에 레거시 파일이 있는지 확인하세요.

3단계: 감지된 설치 검토

감지된 값이 알고 있는 레거시 설치와 일치하는지 확인합니다.

어떤 필드가 잘못되어 있으면 HandyCafe를 닫고 설치를 고친 뒤 다시 엽니다.

4단계: 인코딩 확인

마이그레이션을 실행하기 전에 런타임 프로토콜 섹션의 인코딩 필드가 원본 데이터에 맞게 설정되어 있는지 확인합니다. 이 필드는 같은 설정 페이지의 위쪽에 있습니다.

인코딩을 바꿨다면 계속하기 전에 저장을 클릭하세요.

예상 결과: 원본 문자열이 마이그레이션 중 깨끗하게 해독되어 completed_with_warnings 결과를 피할 수 있습니다.

5단계: 마이그레이션 시작

1. 마이그레이션 시작을 클릭합니다.
2. 진행 모달이 열립니다. 현재 단계와 지금까지 처리된 행 수가 표시됩니다.
3. HandyCafe를 닫거나 컴퓨터를 절전 모드로 두지 마세요.
4. 완료될 때까지 기다립니다. 작은 데이터셋은 1분 이내, 큰 데이터셋은 5~10분이 걸릴 수 있습니다.

예상 결과: 진행 모달이 닫히고 상태가 completed 또는 completed_with_warnings로 바뀝니다. 실행 완료를 알리는 알림이 표시됩니다.

6단계: 가져온 개수 검토

완료 후 페이지에는 가져온 레코드 수가 표시됩니다.

세부 정보 확장기를 클릭해 전체 내역을 봅니다. 수치가 예상과 대체로 맞는지 확인하세요.

예상 결과: 원본 테이블에 데이터가 있었다면 회원, 상품, 주문, 거래의 네 범주가 모두 0보다 큰 값을 보여야 합니다.

7단계: 경고 처리(있는 경우)

상태가 completed_with_warnings이면 경고 목록을 펼쳐 건너뛴 레코드를 검토합니다.

흔한 경고와 해결 방법은 다음과 같습니다.

예상 결과: 경고를 허용 가능한 손실로 받아들이거나, 근본 원인을 고친 뒤 다시 실행합니다.

8단계: 가져온 데이터 샘플 확인

레거시 서버를 폐기하기 전에 각 레코드 유형의 샘플을 직접 확인합니다.

1. 사이드바에서 회원을 엽니다. 레거시 시스템에서 알고 있는 회원을 찾습니다. 이름, 잔액, 연락처를 확인합니다.
2. 설정 > 요금을 엽니다. 시간당 요금이 레거시 스케줄과 일치하는지 확인합니다.
3. 상품을 엽니다. 상품명과 가격을 확인합니다.
4. 최근 과거 날짜의 현금 보고서를 엽니다. 총액이 레거시 시스템과 일치하는지 확인합니다.

예상 결과: 무작위 샘플이 레거시 원본과 일치합니다. 특정 레코드가 잘못되었다면 그 문제를 기록합니다. 작은 서식 차이는 정상입니다. 큰 값 차이는 운영 전에 조사할 가치가 있는 인코딩 또는 데이터 무결성 문제를 의미할 수 있습니다.

9단계: 레거시 클라이언트 런타임 지원 활성화(선택 사항)

전환 기간 동안 기존 V3 또는 V4 클라이언트가 계속 연결되게 하려면 지금 런타임 프로토콜을 활성화하세요.

1. 레거시 클라이언트 설정 페이지 상단으로 스크롤합니다.
2. 레거시 클라이언트 지원 활성화를 켭니다.
3. 리스너 포트(UDP 710, TCP 712, 파일 전송 717)가 네트워크의 다른 것과 충돌하지 않는지 확인합니다.
4. 저장을 클릭합니다.

예상 결과: LAN의 레거시 클라이언트가 5~10초 안에 관리자 패널에 나타납니다. 패널에서 관리하는 방법은 레거시 클라이언트를 참고하세요.

마이그레이션 되돌리기

마이그레이션 결과가 예상과 다르면 완전히 되돌릴 수 있습니다. 원래 레거시 데이터베이스는 건드리지 않습니다.

1. 설정 > 레거시 클라이언트를 엽니다.
2. 데이터베이스 마이그레이션 섹션으로 스크롤합니다.
3. 마이그레이션 되돌리기를 클릭합니다.
4. 대화상자에서 확인합니다.

마이그레이션된 모든 행이 HandyCafe에서 삭제됩니다. 상태는 never로 돌아갑니다. 이후 근본 원인(인코딩, 원본 데이터 정리 등)을 고치고 다시 마이그레이션을 실행할 수 있습니다.

마이그레이션 다시 실행

다시 실행하면 가져온 데이터를 원본의 새 데이터로 교체합니다.

1. 설정 > 레거시 클라이언트를 엽니다.
2. 마이그레이션 다시 실행을 클릭합니다(첫 완료 후 버튼 이름이 바뀝니다).
3. 흐름은 처음 실행과 동일합니다.

다시 실행은 필요한 만큼 여러 번 사용해도 안전합니다. 기존 마이그레이션 결과를 대체하므로 데이터가 중복되지 않습니다.

흔한 실수

• 레거시 서버가 실행 중인데 마이그레이션을 돌리는 경우. 원본 데이터베이스가 잠겨 있거나 부분 쓰기만 포함할 수 있습니다. 항상 먼저 레거시 서버를 중지하세요.
• 인코딩 필드를 무시하는 경우. 잘못된 인코딩으로 실행하면 회원 이름과 로그 메시지가 손상됩니다. 나중에 고치려면 되돌리기 후 다시 실행해야 합니다.
• 마이그레이션 중 HandyCafe를 닫는 경우. 실행이 중단되고 부분 데이터가 기록됩니다. 복구하려면 되돌리기가 필요합니다. 항상 진행 모달이 끝날 때까지 기다리세요.
• 샘플 확인 단계를 건너뛰는 경우. 레코드 수만 믿으면 로케일 불일치나 반올림 오차 같은 미묘한 문제를 놓칠 수 있습니다.
• 레거시 설치를 너무 빨리 삭제하는 경우. 마이그레이션 후 최소 한 번의 전체 정산 주기 동안 원본 파일을 보관하세요. 월간 보고서에서 차이가 발견되면 원본 레코드를 참조할 수 있어야 합니다.
• 백업 없이 마이그레이션하는 경우. 첫 마이그레이션 전에 레거시 설치 폴더를 복사해 두세요. 원본은 마이그레이션으로 수정되지 않지만, 디스크 문제나 실수는 언제든 생길 수 있습니다. 백업은 값싼 보험입니다.