문제 해결
마이그레이션 중단
증상
외장 저장소 연결 해제, 시스템 충돌 또는 앱 강제 종료로 인해 마이그레이션이 중단됨.
해결 방법
AppPorts에 내장된 자동 복구 메커니즘이 있습니다. AppPorts를 재시작하면:
- 잔여 마이그레이션 데이터를 감지 (외부 복사본은 존재하지만 로컬 심볼릭 링크가 생성되지 않음)
- 로컬과 외부 디렉토리 크기를 자동 비교 (90% 임계값)
- 데이터가 완전하면 마이그레이션을 자동으로 완료 (로컬 원본 디렉토리 삭제, 심볼릭 링크 생성)
- 데이터가 불완전하면 잔여 외부 복사본을 정리하고 원래 상태로 복원
💡 수동 개입 불필요
AppPorts의 자동 복구 메커니즘이 다음 실행 시 중단된 마이그레이션을 처리합니다. 자동 복구가 실패하면 데이터 디렉토리 목록에 "정규화 필요" 또는 "재링크 필요" 상태가 표시될 수 있습니다 — 해당 작업을 수동으로 실행하기만 하면 됩니다.
외장 저장소 오프라인
증상
외장 저장소가 분리되거나 연결 해제된 후 마이그레이션된 앱을 실행할 수 없고 데이터 디렉토리에 빨간색 오류 상태가 표시됨.
해결 방법
- 외장 저장소를 다시 연결
- AppPorts의
FolderMonitor가 저장소 볼륨 마운팅을 자동으로 감지하고 재스캔을 트리거 - 앱과 데이터 디렉토리가 정상적으로 사용 가능해짐
⚠️ 참고
외장 저장소가 오프라인 상태일 때, 로컬 엔트리(Stub Portal)가 open을 호출하면 실패합니다; 앱은 충돌하지 않지만 실행할 수 없습니다. 데이터 디렉토리 심볼릭 링크가 잘못된 경로를 가리킴; 관련 앱이 데이터를 읽지 못할 수 있습니다.
서명 복원 실패
증상
원본 서명 복원을 시도하면 실패하거나, 복원 후에도 앱이 여전히 "손상됨"으로 표시됨.
가능한 원인 및 해결 방법
| 원인 | 해결 방법 |
|---|---|
| 백업 파일이 존재하지 않음 | 원본 서명 복원 불가; 대안으로 Ad-hoc 재서명 실행 |
| 원본 개발자 인증서가 로컬 Keychain에 없음 | AppPorts가 자동으로 Ad-hoc 서명으로 대체; 앱 실행 가능하지만 Keychain 접근이 비정상적일 수 있음 |
| Mac App Store 앱 (SIP 보호) | 재서명 불가; SIP가 시스템 앱 서명의 모든 수정을 방지 |
| 앱 디렉토리가 root 소유 | AppPorts가 관리자 권한으로 소유권 변경 시도; 팝업에서 인증 |
| Contents 심볼릭 링크 대상을 찾을 수 없음 | 서명 불가; 외부 데이터를 복원하거나 앱을 먼저 복원해야 함 |
자세한 메커니즘은 재서명 및 충돌 방지를 참조하세요.
App Store 앱이 외장 드라이브로 마이그레이션되지 않음
macOS 15.1 미만
macOS 15.1 이전 버전은 App Store 앱의 외장 드라이브 설치를 지원하지 않습니다. 다음을 수행해야 합니다:
- AppPorts 설정에서 "App Store 앱 마이그레이션" 활성화
- 마이그레이션 후 앱 업데이트 시 수동으로 재마이그레이션하여 덮어쓰기
macOS 15.1 이상
App Store가 외장 드라이브의 앱을 업데이트할 수 없는 경우:
- App Store 설정을 엽니다
- "외장 드라이브에 대용량 앱 다운로드 및 설치" 활성화
- AppPorts 외장 저장소 라이브러리와 동일한 외장 저장소 선택
마이그레이션 후 앱이 실행되지 않음
문제 해결 단계
- 외장 저장소 연결 확인: 외장 저장소가 연결되어 있고 접근 가능한지 확인
- 앱 상태 배지 확인:
- "Orphan Link" → 외부 앱이 손실됨; 수동 링크 해제 필요
- "Damaged" → 재서명 실행
- 잠금 상태 확인: 앱이 잠겨 있으면(uchg), 자체 업데이트 프로그램이 실행되지 못할 수 있음
- 로그 확인: 메뉴바 → 로그 → Finder에서 보기; 관련 오류 메시지 검색
- 로컬로 다시 이동: 외부 앱 라이브러리에서 "로컬로 다시 이동"을 선택하여 외장 저장소 문제인지 확인
데이터 디렉토리 표시 문제
증상
데이터 디렉토리 목록에 불완전하거나 잘못된 상태가 표시됨.
해결 방법
- AppPorts는
FolderMonitor를 사용하여 파일 시스템 변경을 모니터링; 일반적으로 자동으로 새로고침 - 자동 새로고침되지 않으면 다른 탭으로 전환했다가 돌아와서 재스캔 트리거
- 문제가 지속되면 로그에서 스캔 오류 메시지 확인