데이터 마이그레이션 작업 가이드
이 페이지는 데이터 디렉토리 마이그레이션의 실용적인 작업 흐름을 다룹니다. 기술 구현 세부 사항은 기본 구현을 참조하세요.
앱 관련 데이터 디렉토리 찾기
- AppPorts 메인 창에서 "데이터 디렉토리" 탭으로 전환합니다
- 왼쪽 패널에 설치된 모든 앱이 표시됩니다
- 앱을 클릭하면 오른쪽 패널에
~/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/ | 앱 이름 |
도구 디렉토리 (Dot-Folder)
AppPorts는 사용자의 홈 디렉토리에 있는 일반적인 개발 도구가 생성한 dot-folder를 자동으로 감지합니다:
- 데이터 디렉토리 탭에서 "도구 디렉토리" 하위 탭으로 전환합니다
- 페이지에 감지된 모든 도구 디렉토리와 크기가 표시됩니다
- 각 디렉토리에 우선순위 배지(recommended/optional)와 상태가 표시됩니다
전체 지원 목록은 도구 디렉토리 감지를 참조하세요.
마이그레이션 작업
단일 디렉토리 마이그레이션
- 데이터 디렉토리 목록에서 마이그레이션할 디렉토리를 찾습니다
- 오른쪽의 "마이그레이션" 버튼을 클릭합니다
- AppPorts가 다음 단계를 수행합니다:
- 디렉토리를 외장 저장소로 복사
- 관리 링크 메타데이터 기록
- 원본 로컬 디렉토리 삭제
- 심볼릭 링크 생성
자동 재서명
설정에서 '자동 재서명'을 활성화하면, 데이터 디렉토리 마이그레이션이 관련 앱의 서명을 자동으로 트리거합니다:
- 마이그레이션 전: 관련 앱의 실제 외부 경로에서 원본 서명 백업 (로컬 셸이 아닌)
- 마이그레이션 후: 실제 외부 앱에 대해 Ad-hoc 재서명 실행 (무음 모드; 실패 시 대화상자 표시 안 함)
연결된 앱의 경우, AppPorts는 Stub Portal 셸이나 심볼릭 링크 뒤의 실제 앱 경로를 자동으로 해결하여 무효한 로컬 셸이 아닌 실제 애플리케이션 패키지에 서명 변경이 적용되도록 보장합니다.
💡 수동 작업 불필요
자동 재서명을 활성화하면 데이터 디렉토리 마이그레이션 워크플로우가 완전히 자동화됩니다. 서명 백업과 재서명 모두 실제 앱 경로를 대상으로 하므로 수동 개입이 필요 없습니다.
로그 컨텍스트
데이터 디렉토리 작업 (마이그레이션, 복원, 정규화, 재링크)의 로그에는 관련 앱의 컨텍스트 정보가 자동으로 포함됩니다:
| 필드 | 설명 |
|---|---|
app_name | 관련 앱 이름 |
app_status | 앱 상태 (Linked, Local 등) |
app_is_resigned | 앱이 재서명되었는지 여부 |
app_bundle_id | 앱의 Bundle ID (실제 경로에서 읽음) |
app_real_path | 앱의 실제 외부 경로 |
이 필드들은 진단 패키지를 내보낼 때 문제를 더 정확하게 파악하는 데 도움이 됩니다.
일괄 마이그레이션
- 도구 디렉토리 목록에서 여러 디렉토리를 체크합니다
- 하단의 "일괄 마이그레이션" 버튼을 클릭합니다
- AppPorts가 순차적으로 마이그레이션을 실행합니다
💡 우선순위 권장 사항
데이터 디렉토리는 세 가지 우선순위 수준으로 분류됩니다:
- Critical (
critical): 마이그레이션 후 반드시 동작해야 함; 핵심 애플리케이션 기능에 영향 - Recommended (
recommended): 큰 공간 절약; 마이그레이션 효용이 높음 - Optional (
optional): 크기가 작거나 재구성 가능
"Recommended"로 표시된 디렉토리를 우선적으로 마이그레이션하는 것을 권장합니다.
복원 작업
- 데이터 디렉토리 목록에서 마이그레이션된 디렉토리를 찾습니다 (상태: "Linked")
- 오른쪽의 "복원" 버튼을 클릭합니다
- AppPorts가 다음 단계를 수행합니다:
- 로컬 심볼릭 링크 삭제
- 외장 저장소에서 로컬로 데이터 복사
- 외부 디렉토리 삭제 (최대한 시도)
비정상 상태 처리
정규화 필요
디렉토리가 AppPorts에 의해 관리되지만 외부 경로가 표준 위치에 있지 않습니다. "정규화"를 클릭하면; AppPorts가 외부 데이터를 표준 경로로 이동하고 심볼릭 링크를 재구성합니다.
재링크 필요
외장 저장소 데이터가 여전히 존재하지만 로컬 심볼릭 링크가 손실되었습니다. "재링크"를 클릭하면; AppPorts가 심볼릭 링크를 다시 생성합니다.
기존 소프트 링크
AppPorts가 아닌 사용자가 생성한 심볼릭 링크입니다. "관리 전환"을 선택할 수 있습니다; AppPorts가 관리 링크 메타데이터를 기록하고 앞으로 관리합니다.
트리 뷰
하위 디렉토리를 포함하는 데이터 디렉토리(예: Application Support 아래의 여러 앱 디렉토리)의 경우, AppPorts는 트리 그룹화 뷰를 제공합니다:
- 상위 디렉토리 왼쪽에 확장/축소 화살표 표시
- 하위 디렉토리에 계층적 들여쓰기 표시
- 각 노드가 독립적으로 크기와 상태 표시
- 개별 하위 디렉토리에 대해 마이그레이션/복원 작업 수행 가능