데이터 마이그레이션 사용 안내

데이터 디렉토리를 실제로 마이그레이션하는 방법을 설명합니다. 기술적인 구현은 기본 구현을 참고하세요.

앱의 데이터 디렉토리 찾기

1. AppPorts 기본 창에서 ‘데이터 디렉토리’ 탭으로 이동합니다.
2. 상단에서 ‘도구 디렉토리 / 앱 데이터’를 전환합니다.
3. 앱 데이터를 볼 때 왼쪽에서 앱을 선택하면 오른쪽에 ~/Library/ 아래 연결된 디렉토리가 표시됩니다.

AppPorts는 Bundle ID 또는 앱 이름으로 다음 위치를 찾습니다.

스캔 경로	일치 기준	마이그레이션 방식
~/Library/Application Support/	Bundle ID 또는 앱 이름	심볼릭 링크
~/Library/Preferences/	Bundle ID 또는 앱 이름	심볼릭 링크
~/Library/Containers/	Bundle ID	마운트 마이그레이션
~/Library/Group Containers/	Bundle ID	마운트 마이그레이션
~/Library/Caches/	Bundle ID 또는 앱 이름	심볼릭 링크
~/Library/WebKit/	Bundle ID	심볼릭 링크
~/Library/HTTPStorages/	Bundle ID	심볼릭 링크
~/Library/Application Scripts/	Bundle ID	심볼릭 링크
~/Library/Logs/	앱 이름	심볼릭 링크
~/Library/Saved Application State/	앱 이름	심볼릭 링크

컨테이너 디렉토리를 다르게 처리하는 이유는 마운트 마이그레이션을 참고하세요.

도구 디렉토리

AppPorts는 개발 도구가 사용자 폴더에 만드는 일반적인 디렉토리(~/.npm, ~/.gradle 등)를 인식합니다.

1. ‘데이터 디렉토리’에서 ‘도구 디렉토리’로 전환합니다.
2. 인식한 디렉토리의 크기, 우선순위, 상태가 표시됩니다.

로컬 디렉토리는 없지만 외장 드라이브의 표준 위치에 AppPorts가 관리하는 디렉토리가 남아 있으면 ‘다시 연결 대기’로 표시합니다. 지원 목록은 도구 디렉토리 인식을 참고하세요.

디렉토리 마이그레이션 — 사용자 지정 폴더

‘Directory Migration’ 탭은 사용자 폴더 아래 임의의 폴더를 옮깁니다. 대형 프로젝트, 모델, 자료 라이브러리에 적합합니다.

1. ‘Directory Migration’으로 전환합니다.
2. ‘Local Folders’ 제목 옆의 ‘+’를 누릅니다.
3. 로컬 폴더를 선택한 뒤 외장 드라이브의 대상 루트 디렉토리를 선택합니다. 대상은 目标根目录/文件夹名입니다.

검증 규칙: 로컬 폴더는 사용자 폴더 안에 있어야 하지만 사용자 폴더 자체는 안 됩니다. 경로와 상위 경로가 심볼릭 링크여서는 안 되고, 관리 중인 다른 디렉토리와 서로 포함해서도 안 됩니다. 외장 대상은 사용자 폴더 안에 있을 수 없으며 로컬 폴더와도 서로 포함 관계가 될 수 없습니다.

마이그레이션 후 로컬 패널은 원래 경로의 상태, 외장 패널은 사본의 상태를 표시합니다. ‘다시 연결’ 또는 ‘복원’을 사용할 수 있습니다. 설정 제거는 기록만 지우며 데이터를 삭제하지 않습니다.

심볼릭 링크 마이그레이션

컨테이너 밖의 모든 디렉토리에 적용됩니다.

1. 디렉토리를 찾아 ‘마이그레이션’을 누릅니다.
2. AppPorts가 외장으로 복사하고 관리 표식을 기록한 뒤 원래 디렉토리를 안전 백업으로 이름 변경합니다. 원래 경로에 심볼릭 링크를 만들고 마지막에 백업을 정리합니다.
3. 완료 후 상태가 ‘연결됨’으로 바뀝니다.

마이그레이션 후 재서명

데이터 디렉토리 페이지 상단의 ‘마이그레이션 후 재서명’은 기본적으로 꺼져 있습니다. 켜면 완료 후 연결된 앱을 Ad-hoc 재서명합니다. 마이그레이션 뒤 손상 메시지가 나타나는 경우만을 위한 기능이며 샌드박스 앱은 건너뜁니다. 보통 켤 필요가 없습니다. 재서명과 충돌 방지를 참고하세요.

마운트 마이그레이션

Containers와 Group Containers 아래 디렉토리에 적용되며 버튼에 ‘마운트 마이그레이션’이 표시됩니다.

1. 외장 드라이브가 APFS인지 확인하고 해당 앱을 종료합니다.
2. ‘마운트 마이그레이션’을 누르고 확인 창의 세 가지 안내를 읽은 뒤 계속합니다.
3. AppPorts가 외장 볼륨을 만들고 데이터를 복사한 뒤 원래 디렉토리에 마운트합니다.
4. 상태가 ‘마운트됨’으로 바뀝니다. 처음 앱을 열 때 시스템 권한 창에서 허용하세요.

전체 설명은 마운트 마이그레이션을 참고하세요.

복원

심볼릭 링크로 옮긴 디렉토리(‘연결됨’): ‘복원’을 누르면 데이터를 이 Mac으로 복사하고 심볼릭 링크를 삭제한 뒤 외장 사본을 삭제합니다.

마운트 마이그레이션한 디렉토리(‘마운트됨’ 또는 ‘마운트 대기 중’): ‘복원’을 누르면 볼륨의 데이터를 이 Mac으로 복사하고 볼륨을 해제한 뒤 삭제합니다. 외장 드라이브를 계속 연결해 두세요.

두 방식 모두 먼저 복사한 뒤 전환하므로 도중에 실패해도 데이터를 잃지 않습니다.

비정상 상태 처리

상태	의미	작업
정리 필요	AppPorts 관리 링크지만 외장 경로가 표준 위치가 아님	‘정리’로 데이터를 표준 경로로 이동하고 링크 재생성
다시 연결 대기	외장 데이터는 있지만 로컬 링크가 사라짐	‘다시 연결’로 심볼릭 링크 재생성
기존 심볼릭 링크	AppPorts가 만들지 않은 링크	‘링크 세부 정보’에서 관리 대상으로 추가 가능
마운트 대기 중	마운트 마이그레이션 볼륨이 온라인이지만 미마운트	‘마운트’
외장 드라이브 연결 안 됨	마운트 마이그레이션 데이터 볼륨을 찾지 못함	외장 드라이브를 연결하면 자동으로 다시 연결

다시 연결과 정리는 디렉토리만 대상으로 합니다. 외장 대상을 일반 파일이 차지하고 있으면 중단하고 그 파일을 보존합니다.

로그 컨텍스트

데이터 디렉토리 작업 로그에는 진단을 위해 연결된 앱의 정보가 포함됩니다.

필드	설명
app_name	연결된 앱 이름
app_status	앱 상태
app_is_resigned	앱 재서명 여부
app_bundle_id	실제 앱의 Bundle ID
app_real_path	실제 앱 경로

마운트 마이그레이션은 볼륨 이름, Volume UUID, diskutil 명령 출력도 기록합니다.

트리 보기

하위 디렉토리가 있는 항목은 트리로 표시합니다. 부모 왼쪽에 펼치기 화살표가 있고 하위 항목은 들여쓰며, 각 노드가 크기와 상태, 작업 버튼을 따로 표시합니다.