엔지니어링 문제 빠른 진단

클라우드 Mac 도움말 센터

주문 확인부터 Xcode 빌드까지 문제를 실행 가능한 점검 단계로 나눴습니다. 먼저 이 페이지의 초기 진단을 완료하고, 해결되지 않으면 노드 ID, 발생 시간 및 비식별화된 로그를 첨부해 콘솔 티켓을 제출하세요.

각 주문에는 독립된 Mac mini 물리 노드가 할당되며 가상 머신이 아닙니다. 노드 가용성과 연결 정보는 콘솔에 실시간으로 표시되는 내용을 기준으로 합니다.

문제 유형별로 이동

먼저 범위를 선택한 다음 가장 짧은 점검 경로를 실행하세요

다섯 가지 진입점은 주문 수명 주기의 서로 다른 단계를 다룹니다. 분류를 전환하면 먼저 확인할 정보, 일반적인 원인과 다음 단계가 표시됩니다.

주문 수명 주기

주문 및 제공

결제 결과 확인 대기, 노드 정보 미표시, 지역·모델 확인, 최초 연결 자료 확인 문제에 적합합니다.

  • 콘솔의 주문 번호, 모델, 대여 기간 및 지역이 제출 내용과 일치하는지 확인하세요.
  • 결제 확인 후 시스템은 노드 할당, 상태 점검, 연결 정보 생성을 순서대로 진행하며 일반적으로 약 4분이 소요됩니다.
  • 일반적인 시간이 지나도 연결 정보가 없으면 주문을 다시 생성하지 말고 주문 번호를 기록해 티켓을 제출하세요.
빠른 진단

빈번한 장애 5가지의 초기 점검

각 카드는 ‘상태 확인, 변수 축소, 증거 보존’ 순서로 구성되어 있습니다. 한 번에 하나의 변수만 변경해야 어떤 단계에서 서비스가 복구됐는지 확인할 수 있습니다.

노드에 연결할 수 없음

  1. 콘솔에서 노드가 정상 실행 상태인지 확인하세요.
  2. 주소, 포트, 사용자 이름 및 연결 프로토콜을 하나씩 확인하세요.
  3. 다른 네트워크에서 같은 포트를 테스트해 로컬 네트워크 출구 또는 방화벽 제한을 배제하세요.
  4. 클라이언트 오류 원문과 발생 시간을 기록하고 비밀번호를 연속해서 여러 번 시도하지 마세요.
원격 액세스 가이드 보기

빌드가 갑자기 실패함

  1. 실패한 제출, 빌드 명령, 종료 코드 및 최초의 유효한 오류를 기록하세요.
  2. 다음을 실행하세요 xcodebuild -version 현재 도구 체인을 확인하세요.
  3. 의존성 잠금 파일, 환경 변수 및 서명 자산이 변경됐는지 확인하세요.
  4. 캐시 이상을 확인한 경우에만 해당 캐시를 정리하고, 먼저 모든 증거를 삭제하지 마세요.
Xcode 문제 해결 단계로 이동

디스크 공간 부족

  1. 다음 명령으로 df -h 볼륨 용량을 확인하세요. 단일 디렉터리만 보지 마세요.
  2. DerivedData, 아카이브, 시뮬레이터 데이터 및 패키지 관리자 캐시를 확인하세요.
  3. 먼저 재생성 가능한 콘텐츠를 삭제한 다음 빌드 산출물과 프로젝트 파일을 처리하세요.
  4. 계속 증가하는 디렉터리는 파이프라인 정리 규칙에 추가하고 용량 모니터링을 설정하세요.
안전한 정리 순서 보기

자격 증명 만료

  1. 시스템 로그인, SSH 키, 저장소 토큰 또는 서명 권한 중 무엇이 만료됐는지 구분하세요.
  2. 자격 증명의 유효 기간, 파일 권한 및 이를 호출하는 사용자 ID를 확인하세요.
  3. 자격 증명을 교체한 후 파이프라인 변수도 업데이트하고 이전 값을 폐기하세요.
  4. 전체 자격 증명을 명령 기록, 스크린샷 또는 티켓 본문에 붙여 넣지 마세요.
보안 및 권한 안내 보기

네트워크 지연 또는 불안정

  1. 로컬 도시, 통신사, 노드 지역 및 문제 발생 시간을 기록하세요.
  2. 여러 번 연속 테스트하고 중앙값을 사용하세요. 한 번의 최고값만으로 결론 내리지 마세요.
  3. 대화형 지연, 패킷 손실 및 대용량 파일 전송 처리량을 각각 확인하세요.
  4. 불필요한 오디오·비디오와 높은 색 품질을 끈 뒤 VNC 사용 환경을 비교하세요.
연결 최적화 방법 보기
핵심 용어

노드, 연결 및 빌드 맥락 이해하기

아래 정의는 이 서비스에서 실제로 사용되는 의미를 따릅니다. 티켓을 제출할 때 동일한 용어를 사용하면 문제 범위를 반복해서 확인하는 일을 줄일 수 있습니다.

물리 노드
실제로 워크로드를 실행하는 독립 Mac mini 장비입니다. 칩, 메모리, 저장 공간 및 위치한 지역이 명확하며 공유 컴퓨팅 인스턴스가 아닙니다.
전용
대여 기간 동안 해당 노드의 컴퓨팅 리소스는 현재 주문에 할당되어 다른 고객의 워크로드와 함께 스케줄링되지 않습니다. 성능과 환경의 경계가 더 명확합니다.
VNC
macOS 그래픽 인터페이스에 액세스하는 원격 디스플레이 프로토콜입니다. 데스크톱 작업, Xcode 화면 확인 또는 시스템 설정 조정에 적합합니다.
SSH
암호화된 명령줄 연결에 사용하는 프로토콜입니다. 스크립트 실행, 파일 전송, runner 관리 및 그래픽 인터페이스 없이 수행하는 문제 해결에 적합합니다.
self-hosted runner
팀이 직접 관리하고 코드 호스팅 파이프라인에 연결하는 실행기입니다. 작업은 지정된 클라우드 Mac에서 실행되며 도구 체인, 캐시 및 동시성 정책을 팀이 제어합니다.
코드 서명
인증서, 개인 키 및 프로비저닝 프로파일로 앱의 출처와 권한 범위를 확인하는 절차입니다. 관련 자산의 권한을 제한하고 정기적으로 교체하며 저장소에 기록하지 마세요.
빌드 캐시
의존성, 컴파일 중간 결과 또는 도구 다운로드 콘텐츠를 재사용하는 데이터입니다. 빌드 시간을 줄일 수 있지만 잘못되거나 오래된 캐시는 불일치를 일으킬 수 있습니다.
노드 지역
Mac mini가 위치한 데이터 센터 지역입니다. 현재 제공 지역은 싱가포르, 일본(도쿄), 한국(서울), 홍콩, 미국 동부, 미국 서부의 6개 지역입니다.
제공 및 자격 증명

주문 확인부터 최초 보안 로그인까지

일반적인 제공에는 약 4분이 걸리며 네 단계로 진행됩니다. 실제 사용 가능 상태와 연결 정보는 콘솔에 실시간으로 표시되는 내용을 기준으로 합니다.

  1. 01

    주문 및 결제 확인

    약 1분

    모델, 대여 기간, 노드 지역 및 추가 옵션을 확인하세요. 결제 결과가 확인되면 주문이 할당 절차로 진행되며, 처리를 앞당기기 위해 결제를 반복하지 마세요.

    보관할 정보: 주문 번호, 결제 결과 식별자, 제출 시간.
  2. 02

    노드 할당

    약 1분

    시스템은 주문 카탈로그에 따라 독립된 Mac mini 물리 노드를 할당합니다. 두 모델 모두 싱가포르, 일본(도쿄), 한국(서울), 홍콩, 미국 동부, 미국 서부에서 선택할 수 있습니다.

    확인할 정보: 노드 ID, 모델, 지역.
  3. 03

    노드 상태 점검

    약 1분

    제공 전에 시스템 부팅, 네트워크 연결 및 원격 액세스 서비스를 점검합니다. 모든 노드는 365일 연중 정상 운영됩니다.

    대기할 상태: 콘솔 상태가 연결 가능으로 변경됨.
  4. 04

    연결 정보 전달

    약 1분

    콘솔에서 주소, 포트, 사용자 이름 및 임시 자격 증명을 제공합니다. 최초 로그인 후 즉시 임시 비밀번호를 변경하고 독립 SSH 키를 설정한 뒤 자격 증명을 관리형 키 관리 도구에 보관하세요.

    완료할 항목: 최초 로그인, 비밀번호 변경, SSH 키 확인.
자격 증명 관리 기준

스크린샷, 저장소, 빌드 로그 또는 티켓에 개인 키, 전체 비밀번호 및 전체 액세스 토큰을 제출하지 마세요. 자격 증명 유형을 설명해야 할 때는 용도, 생성 시간 및 끝부분의 일부 문자만 제공하세요.

Xcode 문제 해결 경로

버전 기준선부터 재현 가능한 로그까지

처음부터 모든 캐시를 비우거나 도구 체인을 재설치하지 마세요. 먼저 버전과 경로를 확인하고, 그다음 서명 자산을 점검한 후 범위를 정한 정리를 실행하세요.

01

Xcode 및 macOS 버전 확인

그래픽 인터페이스에 표시된 버전을 기록하고 파이프라인 사용자로도 명령을 실행하세요. 로컬 대화형 빌드는 성공하지만 runner가 실패한다면 두 실행 사용자의 환경 변수도 비교해야 합니다.

xcodebuild -version
sw_vers
whoami
02

명령줄 도구 선택 확인

다음 명령으로 xcode-select -p 현재 개발자 디렉터리를 확인하세요. 팀에서 여러 버전을 병렬로 관리한다면 파이프라인 시작 시 경로를 명시적으로 선택해 시스템 기본값 변경을 방지하세요.

xcode-select -p
xcrun --find xcodebuild
xcrun xcodebuild -version
03

인증서 및 프로비저닝 프로파일 확인

서명 인증서가 만료되지 않았고 개인 키를 빌드 사용자가 읽을 수 있으며 프로비저닝 프로파일이 대상 식별자와 일치하는지 확인하세요. 자동 서명이 실패하면 먼저 원본 오류를 보존한 뒤 키체인 권한과 파이프라인 변수를 점검하세요.

security find-identity -v -p codesigning
ls -la ~/Library/MobileDevice/Provisioning\ Profiles
04

범위를 정해 DerivedData 정리

모든 프로젝트 캐시를 바로 비우기보다 현재 프로젝트에 해당하는 디렉터리를 우선 삭제하세요. 정리 전에 디스크 사용량과 실패 로그를 기록해 캐시가 실제 원인인지 판단할 수 있도록 하세요.

du -sh ~/Library/Developer/Xcode/DerivedData
find ~/Library/Developer/Xcode/DerivedData -maxdepth 1 -type d
05

xcodebuild 로그 수집

전체 명령, 종료 코드 및 최초의 유효한 오류를 보존하세요. 티켓 제출 전에 저장소 토큰, 서명 비밀, 사용자 경로 및 내부 주소를 삭제하되 마지막 한 줄만 잘라내지는 마세요.

set -o pipefail
xcodebuild test 2>&1 | tee build.log
printf "exit=%s\n" "$?"
지원 요청 작성법

지원 엔지니어가 즉시 재현할 수 있도록

완전한 요청이 모든 데이터를 업로드한다는 뜻은 아닙니다. 명확한 타임라인, 영향을 받은 범위 및 비식별화된 기술 증거를 제공하는 것이 목표입니다.

티켓 본문 권장 구조

노드 ID
콘솔에서 정확한 식별자를 복사하고 사용자 지정 장치 이름으로 대체하지 마세요.
발생 시간
날짜, 시간대, 시작 시간 및 마지막 정상 시간을 명시하세요.
노드 지역
주문의 지역을 입력하고 현지 도시만 입력하지 마세요.
영향 범위
단일 명령, 하나의 파이프라인, 모든 연결 또는 팀 전체 중 어디에 영향을 미쳤는지 설명하세요.
재현 단계
실제로 실행한 순서대로 명령, 입력, 예상 결과 및 실제 결과를 나열하세요.
수행한 점검
작업과 결과를 항목별로 작성하고 ‘다 해봤습니다’라고만 쓰지 마세요.

로그 비식별화 규칙

  • 액세스 토큰, 비밀번호 및 개인 키 내용을 명확한 비식별화 표기로 바꾸세요.
  • 저장소 주소는 플랫폼 유형을 남길 수 있지만 조직명, 프로젝트명 및 인증 매개변수는 삭제하세요.
  • 사용자 디렉터리는 일반 경로로 바꿀 수 있지만 상대 디렉터리 구조는 유지하세요.
  • 인증서 문제에는 이름, 유효 기간 및 오류 정보를 제공할 수 있으나 개인 키는 제출하지 마세요.
  • 결제 문제에는 주문 번호와 결과 식별자를 제공하고 전체 결제 정보는 제출하지 마세요.
  • 스크린샷을 찍기 전에 터미널 기록, 메뉴 막대, 파일 이름 및 알림 내용을 확인하세요.
업로드 금지

개인 키, 전체 로그인 자격 증명, 전체 액세스 토큰, 비식별화되지 않은 환경 변수 및 민감한 매개변수가 포함된 구성 파일.

언제 직접 점검을 건너뛰고 즉시 티켓을 제출해야 하나요?

비정상적인 자격 증명 활동, 호스트 지문의 예기치 않은 변경, 노드 상태와 실제 연결성의 현저한 불일치가 발생했거나 작업이 증거를 훼손할 수 있다면 반복 시도를 중단하고 즉시 콘솔 티켓을 제출하세요.

노드 작업에 주문 소유권 확인이 필요한 이유는 무엇인가요?

접근 권한 재설정, 노드 상태 변경 또는 민감한 설정 처리는 전용 물리 노드에 영향을 줄 수 있습니다. 지원팀은 무단 사용자의 노드 수준 작업 요청을 방지하기 위해 로그인 세션, 주문 번호 및 권한 관계를 확인해야 합니다.

연결과 빌드가 동시에 실패하면 티켓을 하나 제출해야 하나요, 여러 개 제출해야 하나요?

두 문제가 같은 시간에 발생했고 동일한 노드 상태가 원인일 가능성이 있다면 하나의 티켓에 연결 및 빌드 증거를 각각 기재하세요. 발생 시간, 노드 또는 담당 범위가 다르면 독립적으로 추적할 수 있도록 별도로 제출하세요.

지원 에스컬레이션

진단 결과를 첨부해 추적 가능한 요청 제출

기존 주문, 노드 연결, 빌드 장애 및 청구 문제는 우선 콘솔 티켓으로 제출하세요. 사전 평가, 팀 배포 및 보안 보고서는 문의 페이지에서 support@hexvm.com으로 보낼 수 있습니다. 노드 작업과 관련된 경우 주문 소유권 확인을 완료해야 합니다.