자격 증명이 현재 노드에 해당하나요
사용자 이름, 키 또는 연결 비밀번호가 현재 주문에서 발급된 것인지 확인하고 종료된 주문의 연결 정보를 재사용하지 마세요. 키 파일 권한과 복사 과정에서 공백이나 줄바꿈이 추가되지 않았는지도 확인합니다.
작업 경로 복구
연결 확인부터 빌드 로그까지 순서대로 문제를 찾으세요
iOS, macOS, CI/CD 및 Apple Silicon 실험 작업을 위한 문제 해결 가이드입니다. 먼저 노드와 네트워크를 확인한 다음 도구 체인과 작업 로그를 점검해 여러 변수를 동시에 변경하지 마세요.
5
단계 연결 확인
4
가지 빌드 문제
6
개 판매 노드
실행 목록
현장을 보존한 뒤 하나씩 배제하세요
READY
A01
노드 정보 확인
리전, 호스트 주소, 연결 방식, 주문 상태
01
A02
로컬 경로 검증
DNS, 포트, 방화벽, 패킷 손실 및 지터
02
A03
도구 체인 범위 좁히기
Xcode, SDK, 종속성, 서명 및 테스트
03
A04
최소 증거 세트 제출
발생 시간, 재현 단계, 로그 및 영향 범위
04
비밀번호, 개인 키 또는 복구 코드를 보내지 마세요
SUPPORT / NODE
첫 연결
네 단계로 첫 연결 완료
콘솔에서 현재 주문에 해당하는 노드 정보를 확인할 수 있습니다. 필드를 복사할 때 원래 형식을 유지하고 주소, 사용자 이름 또는 포트를 추측해 입력하지 마세요.
-
01
노드 필드 확인
콘솔에 로그인해 주문, 리전, 호스트 주소, 사용자 이름 및 허용된 연결 방식을 확인하세요. 노드는 싱가포르, 일본(도쿄), 한국(서울), 홍콩, 미국 동부 또는 미국 서부 중 한 곳에 있습니다.
-
02
로컬 네트워크 확인
사내 네트워크가 대상 포트를 차단하지 않는지 확인하고 라우팅을 변경하는 임시 프록시를 끄세요. 유선, 무선 또는 다른 네트워크에서 연결 결과를 각각 기록합니다.
-
03
연결 방식 선택
명령줄, 파일 동기화 및 자동화 작업에는 SSH를 우선 사용하고, macOS 그래픽 인터페이스가 필요할 때는 VNC를 사용하세요. 첫 테스트에서는 한 가지 연결만 설정해 결과가 서로 영향을 주지 않게 합니다.
-
04
기준선 검증 완료
로그인 후 시스템 버전, 디스크 여유 공간, Xcode 경로 및 현재 네트워크 시간을 기록하세요. 먼저 최소 프로젝트를 실행한 뒤 전체 프로젝트와 빌드 캐시를 옮깁니다.
첫 로그인에서는 기본 연결 경로만 확인하세요
연결이 안정적인지 확인하기 전에는 프로젝트를 일괄 업로드하거나 시스템 설정을 변경하거나 CI runner를 등록하지 마세요. 재현 가능한 기준선 결과를 먼저 보존합니다.
연결 진단
정해진 순서로 SSH와 VNC 점검
연결에 실패하면 인증 정보부터 네트워크 외부 계층으로 이동하며 확인하세요. 각 단계에서는 조건 하나만 변경하고 명령 출력 또는 오류 메시지를 보존합니다.
로컬에서 포트에 도달할 수 있나요
콘솔에 표시된 포트로 연결성 테스트를 실행하세요. 시간 초과는 대개 네트워크 경로 문제이며, 즉시 거부되는 경우에는 대상에 도달했지만 서비스 또는 포트가 일치하지 않을 가능성이 큽니다.
로컬 방화벽이 차단하나요
엔드포인트 보안 소프트웨어, 기업 네트워크 출구 정책 및 라우터 규칙을 확인하세요. 이미 정상 작동하는 다른 네트워크로 다시 테스트하면 로컬 제한과 노드 측 문제를 빠르게 구분할 수 있습니다.
네트워크 경로가 안정적인가요
한 번의 ping만 보지 말고 지연 시간, 지터 및 패킷 손실을 기록하세요. VNC는 지속적인 지터에 더 민감하며 SSH 빌드도 다운로드 연결이 재설정되면 중단될 수 있습니다.
노드 상태가 정상인가요
콘솔로 돌아가 인스턴스와 주문 상태를 확인하세요. 여러 네트워크에서 모두 연결되지 않고 자격 증명도 올바르다면 발생 시간과 오류 원문을 보존한 뒤 노드 이상 지원 요청을 제출합니다.
도구 체인 점검
Xcode 문제는 버전 선택부터 확인한 뒤 프로젝트를 점검하세요
동일한 커밋도 도구 체인에 따라 결과가 달라질 수 있습니다. 시스템 환경과 프로젝트 종속성을 분리해 검증해야 문제가 노드, 도구 체인 또는 저장소 설정 중 어디에 속하는지 판단할 수 있습니다.
버전 및 경로
- 실행
xcodebuild -version하여 Xcode 및 빌드 버전을 기록하세요. - 실행
xcode-select -p하여 Command Line Tools가 예상 디렉터리를 가리키는지 확인하세요. - 스크립트에 이전 버전 Xcode 경로가 하드코딩되어 있는지 확인하세요.
SDK 및 종속성
- scheme, destination 및 SDK 이름이 존재하는지 확인하세요.
- Swift Package, CocoaPods 또는 기타 프로젝트 종속성을 다시 확인하세요.
- 잠금 파일, 종속성 소스 및 다운로드 실패 주소의 구체적인 유형을 비교하세요.
서명 환경
- 빌드 설정에서 읽는 서명 변수가 존재하는지 확인하세요.
- CI 프로세스가 필요한 자료에 액세스할 수 있고 해당 내용이 로그에 기록되지 않는지 확인하세요.
- 서명 실패와 컴파일 실패를 분리해 다시 실행하고 종료 코드를 기록하세요.
BASELINE
권장 최소 환경 스냅샷
sw_vers
xcodebuild -version
xcode-select -p
df -h
자동화 연결
self-hosted runner를 통제된 실행기로 운영하세요
runner 등록이 완료되었다고 워크플로가 안전하고 재현 가능해지는 것은 아닙니다. 실행 범위, 작업 디렉터리, 자격 증명 및 동시성 정책을 함께 적용해야 합니다.
실행기를 등록하고 레이블 지정
프로젝트 또는 조직에서 제공한 단기 등록 정보를 사용하고 칩, 리전 및 용도를 나타내는 레이블을 설정하세요. 등록이 끝나면 로컬 임시 명령 기록을 삭제합니다.
산출물: runner 이름 및 레이블 목록실행 범위 제한
신뢰할 수 있는 저장소, 보호된 브랜치 및 명시된 워크플로만 노드를 호출하도록 허용하세요. 외부 기여로 트리거된 작업은 검토를 거치게 하고 알 수 없는 스크립트가 노드 권한을 직접 얻지 못하게 합니다.
산출물: 저장소 및 브랜치 권한 규칙작업 디렉터리 정리
작업 전후에 임시 파일, 파생 데이터 및 불필요한 캐시를 처리하세요. 캐시를 보존할 경우 키, 출처 및 만료 조건을 기록해 오래된 산출물이 새 빌드를 오염시키지 않게 합니다.
산출물: 정리 스크립트 및 캐시 정책액세스 자격 증명 교체
토큰, SSH 키 및 서명 자료는 통제된 키 관리 절차에 넣으세요. 구성원이 팀을 떠나거나 저장소 권한이 변경되거나 비정상 로그가 발생하면 즉시 폐기하고 다시 발급합니다.
산출물: 자격 증명 담당자 및 교체 기록
로그 분류
첫 번째 유효 오류로 빌드 문제 유형을 판단하세요
로그 끝부분의 일반적인 종료 코드만 잘라내지 마세요. 전체 로그를 저장하고 첫 오류가 나타난 위치에서 위로 올라가 대상, 명령 및 종속성 컨텍스트를 확인합니다.
| 문제 유형 | 일반적인 로그 신호 | 먼저 확인할 항목 | 지원 요청에 첨부할 내용 |
|---|---|---|---|
| 종속성 확인 | 패키지 버전 충돌, 저장소 가져오기 실패, 잠금 파일 불일치 | 잠금 파일, 종속성 소스, 캐시 키 및 네트워크 다운로드 결과 | 종속성 관리 방식, 실패한 패키지 이름, 첫 오류 구간 |
| 서명 설정 | 인증서 일치 실패, 권한 사용 불가, 설정 변수 누락 | scheme, 빌드 설정 및 키 주입 절차 | 민감 정보가 제거된 오류 원문 및 빌드 대상 |
| 테스트 실패 | 어설션 실패, 시뮬레이션 환경 차이, 테스트 시간 초과 | 실패한 테스트 케이스, destination, 병렬 매개변수 및 재시도 결과 | 테스트 케이스 이름, 종료 코드, 재현 명령 |
| 네트워크 다운로드 | 연결 재설정, 이름 확인 실패, 다운로드 시간 초과 | 동일 주소 반복 요청, DNS, 프록시 및 네트워크 출구 경로 | 발생 시간, 대상 유형 및 네트워크 테스트 결과 |
01
전체 원본 로그 보존
02
첫 번째 유효 오류 확인
03
최소 명령으로 독립 재현
04
자격 증명을 삭제한 발췌본 제출
데이터 운영
프로젝트, 캐시 및 추가 SSD를 분리해 관리하세요
용량을 늘리는 것만으로는 데이터 분류와 백업을 대신할 수 없습니다. 먼저 보존해야 할 내용을 정한 다음 동기화, 캐싱 및 이전 방식을 결정하세요.
프로젝트 동기화
버전 관리 저장소로 소스 코드를 동기화하고 대용량 바이너리와 비공개 종속성은 통제된 스토리지 절차에 넣으세요. 첫 이전 후 커밋 해시, 서브모듈 및 잠금 파일을 비교합니다.
- 소스 코드와 설정을 별도로 확인
- 대용량 파일 동기화 방식 기록
- 이전 후 최소 빌드 실행
캐시 정리
DerivedData, 패키지 캐시 및 runner 작업 디렉터리는 모두 재현성에 영향을 줄 수 있습니다. 삭제하기 전에 디렉터리 크기와 캐시 키를 기록하고, 정리 후 빌드 시간과 오류 변화를 비교하세요.
- 먼저 디스크 여유 공간 측정
- 다시 생성할 수 있는 내용만 정리
- 동시 작업이 캐시를 동시에 변경하지 않도록 하기
추가 SSD 사용 범위
추가 SSD는 더 많은 작업 공간이 필요한 프로젝트, 캐시 또는 데이터 세트에 사용하세요. 정식 작업을 시작하기 전에 마운트 지점, 읽기·쓰기 경로 및 작업 권한을 확인해야 합니다.
- 데이터 저장 위치 명확히 하기
- 증가 속도와 잔여 용량 모니터링
- 이전 전에 파일 무결성 검증
이전 전에 사용자가 필요한 사본을 보관하세요
프로젝트 데이터, 서명 자료, 자격 증명 및 빌드 산출물은 팀 정책에 따라 백업해야 합니다. 이용 기간이 끝나기 전에 이전을 완료하고 사본을 읽을 수 있는지 확인하세요. 노드의 단일 사본을 장기 보관본으로 간주하지 마세요.
지원 요청 증거 세트
한 번의 제출로 문제 해결에 필요한 정보 제공
지원 요청이 구체적일수록 재현과 분석을 바로 시작하기 쉽습니다. 먼저 영향을 설명한 다음 타임라인과 최소 로그를 제공하고 비밀 값은 보내지 마세요.
요청 템플릿
필드를 복사해 사실을 입력하세요
CASE
- 노드 리전
- 싱가포르, 일본(도쿄), 한국(서울), 홍콩, 미국 동부 또는 미국 서부
- 발생 시간
- 현지 시간과 시간대를 명시하고 문제가 지속적인지 간헐적인지 설명하세요
- 재현 단계
- 로그인, 명령 실행부터 오류 발생까지 실제 순서대로 나열하세요
- 로그 발췌
- 첫 번째 유효 오류, 종료 코드 및 앞뒤에 필요한 컨텍스트를 포함하세요
- 영향 범위
- 단일 작업, 단일 구성원, 모든 빌드 또는 전체 노드 연결
- 완료한 확인
- 네트워크 변경, 명령 재시도, 캐시 정리 등 실행한 작업과 결과를 나열하세요
다음 내용은 제출하지 마세요
비밀번호, 개인 키, 복구 코드, 전체 토큰, 서명 자료 및 전체 결제 자격 증명. 로그에 비밀 값이 포함되어 있다면 먼저 삭제하거나 명확한 마스킹 표시로 바꾸세요.
기존 주문 연결
콘솔에 로그인해 지원 요청을 만들고 해당 주문을 선택하면 지원 담당자가 올바른 노드와 서비스 기록을 확인하는 데 도움이 됩니다.
콘솔에 로그인해 지원 요청 만들기
에스컬레이션 경로
문제 유형에 맞는 처리 대기열로 이동하세요
연결 중단, 노드 이상 및 결제 문의에는 서로 다른 증거가 필요합니다. 올바른 분류를 선택하고 같은 대화에 자료를 추가해 컨텍스트가 분리되지 않게 하세요.
자격 증명은 올바르지만 SSH 또는 VNC 연결을 설정할 수 없음
로컬 네트워크 유형, 대상 포트 테스트, 오류 원문 및 발생 시간을 첨부하세요. 다른 네트워크에서 복구되었다면 두 테스트의 차이도 작성합니다.
분류: 연결 및 액세스여러 작업이 동시에 실패하거나 노드 상태가 비정상임
영향 범위, 마지막 정상 시각, 인스턴스 상태 및 최소 재현 명령을 설명하세요. 연속 재시작이나 설정 일괄 변경으로 원래 상태를 덮어쓰지 마세요.
분류: 노드 운영주문 기간, 추가 항목 또는 결제 기록 확인 필요
주문 식별자, 결제 주기, 관련 추가 항목 및 문제 설명을 제공하세요. 모든 주문은 미국 달러(USD)로 결제되며 지원 요청에 전체 결제 자격 증명을 보내지 마세요.
분류: 주문 및 결제
같은 대화에서 계속 추적하세요
콘솔에서 지원 요청 추적
처리 진행 상황, 추가 질문 및 최종 결론은 콘솔의 해당 지원 요청에 업데이트하세요. 새 로그를 추가할 때 수집 시간과 이번 변경 사항을 표시하면 전후 결과를 비교하기 쉽습니다.
노드 정보를 준비한 뒤 재현 가능한 문제 해결을 시작하세요
새 주문에서는 두 가지 구성과 6개 노드 중에서 바로 선택할 수 있습니다. 기존 주문에 문제가 있다면 콘솔에 로그인해 관련 지원 요청을 제출하세요.