레거시 클라이언트 설정
HandyCafe는 이전 V3 및 V4 클라이언트 설치와 충돌 없이 함께 실행됩니다. 레거시 클라이언트 설정 페이지에는 서로 독립적인 두 가지 기능이 있습니다.
- 런타임 프로토콜. V3 및 V4 클라이언트가 원래 포트로 이 서버에 연결할 수 있게 해 주는 네트워크 리스너를 활성화합니다.
- 데이터베이스 마이그레이션. 이전 로컬 설치에서 회원, 요금, 상품, 주문, 거래, 로그를 새 HandyCafe 데이터베이스로 선택적으로 가져옵니다. 이 기능은 Windows에서만 사용할 수 있습니다.
두 기능은 서로 독립적입니다. 데이터는 옮기지 않고 런타임 지원만 켜거나, 런타임 지원 없이 데이터만 마이그레이션하거나, 둘 다 할 수 있습니다.
런타임 프로토콜 섹션
레거시 클라이언트 지원 활성화
섹션 상단의 전체 토글입니다. 켜면 서버가 세 개의 네트워크 리스너를 시작합니다.
- 구성된 멀티캐스트 그룹을 듣는 UDP 리스너
UDP 포트 + 2의 TCP 명령 리스너UDP 포트 + 7의 TCP 파일 전송 리스너
토글을 끄면 이 세 리스너가 한 번에 중지됩니다. 비활성화 상태에서 포트 번호나 인코딩을 바꾼 뒤 다시 켜면 변경 사항이 적용됩니다.
구성 필드
| 필드 | 기본값 | 설명 |
|---|---|---|
| 인증 키 | HANDYCAFE | 10자 길이의 공유 키입니다. 모든 인바운드 및 아웃바운드 프레임에 이 문자열이 포함됩니다. 일치하지 않는 프레임은 버려집니다. 모든 레거시 클라이언트는 같은 키를 사용해야 합니다. |
| UDP 멀티캐스트 IP | 230.4.4.46 | 클라이언트 검색 비콘과 UDP 기반 명령 전달에 사용되는 멀티캐스트 그룹입니다. 대부분의 레거시 클라이언트 빌드에 하드코딩되어 있습니다. |
| 서버 UDP 포트 | 710 | 서버가 클라이언트 비콘과 명령을 듣는 UDP 포트입니다. 레거시 클라이언트는 이 포트로 전송합니다. |
| 클라이언트 UDP 포트 | 711 | 레거시 클라이언트가 듣는 UDP 포트입니다. 서버는 발견된 클라이언트 IP로 이 포트에 단일 전송 관리 명령을 보냅니다. |
| 인코딩 | cp1254 | 와이어 형식 문자열 필드의 문자 인코딩입니다. 터키 환경에는 cp1254, 서유럽 환경에는 cp1252를 사용하세요. 알 수 없는 값은 서버 로그의 경고와 함께 cp1254로 되돌아갑니다. |
| 서버 버전 | 3.4.01 | 모든 UDP 비콘에 브로드캐스트되는 버전 문자열입니다. 일부 레거시 클라이언트는 인식하지 못하는 버전의 프레임을 거부합니다. 원래 서버의 버전 문자열과 맞추세요. |
| 프로토콜 변형 | STE | 와이어 형식 선택입니다. 아래의 변형 비교를 참고하세요. |
| 비활성 타임아웃 | 10 | 초 단위의 MAC별 감시 타이머입니다. 이 시간 안에 클라이언트에서 트래픽이 오지 않으면 오프라인으로 표시됩니다. 2~3초마다 비콘을 보내는 레거시 클라이언트에는 10초가 적당합니다. |
파생 포트
양식 아래에는 파생된 TCP 포트를 보여 주는 읽기 전용 줄이 표시됩니다.
TCP 명령 포트: 712 파일 전송 포트: 717
이 포트들은 UDP 서버 포트를 기준으로 계산됩니다. 별도로 설정하지 않습니다. 서버 UDP 포트를 다른 값으로 바꾸면 파생 포트도 함께 바뀝니다.
프로토콜 변형
프로토콜 변형 필드는 서버가 사용하는 와이어 형식을 선택합니다. 레거시 서버가 어떤 빌드였는지에 맞는 변형을 고르세요.
| 변형 | 사용할 때 |
|---|---|
| STE (Smart/Turbo Edition) | 현대 레거시 코드베이스입니다. 프레임 구조 앞에 70바이트의 license-info 접두사가 추가됩니다. 프레임 크기는 1337바이트입니다. 레거시 설치가 Smart 또는 Turbo Edition이었다면 이 항목을 선택하세요. |
| Standard | 일반적인 기본 레거시 빌드입니다. license-info 접두사 없이 프레임 크기는 1267바이트입니다. 레거시 설치가 라이선스 등록이 없는 Standard Edition이었을 때만 선택하세요. |
잘못된 변형을 고르면 프레임이 버려지거나 잘못 해석됩니다. 증상으로는 클라이언트가 온라인처럼 보이지만 명령을 전혀 무시하거나, 70바이트 오프셋 때문에 명령 데이터가 어긋나 보이는 현상이 있습니다.
현대 클라이언트와의 공존
레거시 포트(710, 711, 712, 717)는 현대 HandyCafe 프로토콜 포트(TCP 5001, 5002, 5003, UDP 5004)와 완전히 분리됩니다. 두 프로토콜 스택은 충돌 없이 동시에 실행됩니다. 같은 LAN에서 구버전과 신버전 클라이언트를 섞어 사용해도 되며, 같은 관리자 패널에서 관리할 수 있습니다.
변경 적용
런타임 프로토콜 섹션의 모든 필드는 페이지 하단의 전역 저장 버튼으로 저장됩니다. 저장하면 서버는 다음 순서로 동작합니다.
- 실행 중이던 세 개의 레거시 리스너를 중지합니다.
- 인증 키를 검증합니다(비어 있으면 안 됩니다).
- 갱신된 필드로 새 리스너 구성을 만듭니다.
- 리스너를 동시에 다시 시작합니다.
- 세 리스너가 모두 온라인으로 돌아오면 알림을 보냅니다.
포트를 다른 프로세스가 이미 사용 중이면 서버가 오류를 보고하고 토글이 다시 꺼집니다. netstat로 방화벽과 다른 서비스를 확인하고, 비어 있는 포트 범위를 선택하세요.
데이터베이스 마이그레이션 섹션 (Windows 전용)
이 기능은 HandyCafe가 Windows에서 실행될 때만 사용할 수 있습니다. macOS와 Linux에서는 섹션에 "데이터베이스 마이그레이션은 Windows에서만 지원됩니다."라는 안내가 표시됩니다.
탐지
열리면 서버가 시스템에서 레거시 설치를 검색합니다. 다음 위치를 살펴봅니다.
- 레지스트리와
Program Files\HandyCafe,C:\HandyCafe같은 일반 설치 경로 - 설치와 함께 있는 데이터베이스 파일
- 설치 디렉터리의 구성 INI 파일
탐지에 성공하면 페이지에 다음 정보가 표시됩니다.
| 레이블 | 의미 |
|---|---|
| 설치 경로 | 레거시 설치가 있는 디스크 위치입니다. |
| 데이터베이스 경로 | 레거시 데이터베이스 파일의 전체 경로입니다. |
| 서버 버전 | 레거시 구성에서 파싱한 버전입니다. |
| INI 파일 수 | 감지된 구성 파일 수입니다. 설치가 온전한지 확인할 때 유용합니다. |
설치가 감지되지 않으면 페이지에 "레거시 설치가 감지되지 않았습니다."가 표시됩니다. 이 경우에도 런타임 지원은 켤 수 있으며, 마이그레이션 기능만 가져올 것이 없는 상태입니다.
마이그레이션 상태
페이지는 마이그레이션 이력을 추적합니다.
| 상태 | 의미 |
|---|---|
never |
아직 마이그레이션을 실행하지 않았습니다. |
in_progress |
현재 마이그레이션이 진행 중입니다. 이 상태에서는 서버를 닫지 마세요. |
completed |
가장 최근 마이그레이션이 경고 없이 완료되었습니다. |
completed_with_warnings |
가장 최근 마이그레이션이 완료되었지만 일부 레코드가 건너뛰어졌습니다(예: 인코딩 오류나 잘못된 날짜). 계속하기 전에 경고를 검토하세요. |
undone |
가장 최근 마이그레이션이 롤백되었습니다. |
첫 성공 실행 후에는 마이그레이션 시작 버튼이 마이그레이션 다시 실행으로 바뀝니다.
마이그레이션 대상
| 테이블 | 설명 |
|---|---|
| 회원 | 이름, 연락처, 계정 잔액이 포함된 고객 레코드입니다. |
| 요금 | 가격표와 시간대별 요금입니다. |
| 상품 | 상품 카탈로그 항목입니다. |
| 주문 | 세션 참조가 포함된 주문 기록입니다. |
| 거래 | 타임스탬프, 금액, 결제 수단이 포함된 원장 항목입니다. |
| 로그 | 레거시 데이터베이스의 감사 및 경고 항목입니다. |
"파일은 안전" 보장
페이지에는 파란색 안내가 표시됩니다. "원본 데이터베이스 파일은 삭제되지 않습니다. 마이그레이션이 확인되면 안전하게 삭제할 수 있습니다." 마이그레이션은 원본에 대해 읽기 전용입니다. 여러 번 실행해도 원본 레거시 데이터베이스는 그대로 유지됩니다. 그래서 가져오기를 시험해 보고, 개수를 검토하고, 위험 없이 되돌릴 수 있습니다.
시작, 다시 실행, 되돌리기
- 마이그레이션 시작. 진행 모달을 엽니다. 모달에는 현재 단계와 지금까지 처리된 레코드 수가 표시됩니다. 이 동안 HandyCafe를 닫지 마세요.
- 마이그레이션 다시 실행. 한 번 완료된 뒤에 사용할 수 있습니다. 처음부터 다시 가져옵니다. 새 가져오기는 HandyCafe의 이전 데이터를 대체합니다.
- 마이그레이션 되돌리기. 한 번 완료된 뒤에 사용할 수 있습니다. 확인 대화상자를 엽니다. 확인하면 마이그레이션된 모든 행이 HandyCafe에서 삭제됩니다. 레거시 원본은 건드리지 않습니다. 되돌린 뒤 상태는
never로 돌아갑니다.
경고와 함께 완료됨
마이그레이션이 completed_with_warnings로 끝나면 노란 배너와 함께 세부 정보 링크가 나타납니다. 클릭하면 건너뛴 레코드와 이유를 볼 수 있습니다. 흔한 이유는 다음과 같습니다.
- 인코딩 불일치. 원본 행에 구성된 인코딩으로 깨끗하게 해독되지 않는 문자가 있습니다. 인코딩 필드(cp1254 또는 cp1252)를 바꾸고 다시 실행하세요.
- 잘못된 날짜. 일부 레거시 레코드에 유효하지 않은 타임스탬프가 있습니다. 이들은 건너뛰되 유효한 행은 계속 가져옵니다.
- 중복 키. 같은 식별자를 가진 레코드가 이미 HandyCafe에 있습니다. 마이그레이션은 기존 레코드를 보존하고 중복은 건너뜁니다.
팁
- 마이그레이션 전에 레거시 서버를 중지하세요. 레거시 시스템이 여전히 데이터베이스에 쓰는 중이면 오래되었거나 부분적인 데이터가 들어올 수 있습니다.
- 첫 번째 마이그레이션 전에 인코딩 필드를 레거시 로케일에 맞추세요. 데이터를 가져온 뒤에 바꿔도 이미 손상된 이름은 복구되지 않습니다.
- 항상 먼저 테스트 마이그레이션을 실행하세요. "Last Counts" 아래의 레코드 수를 확인하고, 몇 개의 회원과 거래 행을 샘플로 점검한 뒤 새 시스템으로 전환하세요.
- 전환 기간 동안 런타임 지원을 켜고 레거시 클라이언트를 계속 연결해 두세요. 이렇게 하면 새 서버가 이전 서버와 동일하게 동작하는지 확인한 뒤에 옛 서버를 종료할 수 있습니다.
- 서버 UDP 포트를 바꾸면 파생되는 명령 및 파일 전송 포트도 함께 이동한다는 점을 기억하세요. 방화벽 규칙도 그에 맞게 업데이트해야 합니다.