증상부터 진단하기

연결 및 빌드 문제를 검증 가능한 단계로 나누어 해결하세요

이 안내서를 처음부터 끝까지 읽을 필요는 없습니다. 연결, 환경, 자동화, 네트워크 또는 저장 공간에서 시작점을 찾은 뒤 주소, 권한, 도구 버전과 로그를 차례로 확인하세요. 각 단계에는 예상 결과가 제시되어 있어 직접 점검을 계속할지 지원 티켓을 제출할지 판단하기 쉽습니다.

문제 해결 항목 보기 콘솔에서 지원 티켓 제출
6개 문서 항목
2가지 원격 연결 방식
5개 증상별 진단 경로
문서 색인

현재 수행 중인 작업을 먼저 선택하세요

각 항목은 이 페이지의 구체적인 점검 단계로 연결됩니다. 한 번에 하나의 변수만 변경하고 변경 전후의 명령어, 버전과 결과를 기록하는 것이 좋습니다.

최초 연결 자격 증명을 준비하고 호스트 지문을 확인한 뒤 키를 교체하고 세션을 올바르게 종료합니다. CONNECT 개발 환경 Xcode 경로, 빌드 대상, 의존성 해석 및 로그 보관 위치를 확인합니다. TOOLCHAIN 자동화 빌드 self-hosted runner를 등록하고 태그, 동시 실행 수와 작업 디렉터리를 계획합니다. RUNNER 네트워크 액세스 상세 로그로 주소 오류, 포트 연결 불가, 시간 초과 및 인증 실패를 구분합니다. NETWORK 저장 공간 관리 DerivedData, 캐시, 아카이브 및 작업 디렉터리의 저장 공간 사용량을 찾습니다. STORAGE 문제 해결 다섯 가지 증상별 의사결정 트리에서 다음에 검증할 작업을 확인합니다. RESOLVE
문제 해결 원칙: Xcode 업그레이드, 의존성 교체, 네트워크 변경 및 서명 설정 수정을 동시에 진행하지 마세요. 한 번에 하나만 변경해야 결과를 통해 실제 원인을 판단할 수 있습니다.
원격 연결

SSH와 VNC는 서로 다른 확인 절차를 사용합니다

SSH는 명령줄, 자동화 및 파일 전송에 적합하고 VNC는 macOS 그래픽 인터페이스가 필요한 작업에 적합합니다. 두 방식 모두 먼저 노드 주소를 확인한 다음 자격 증명을 검증해야 합니다.

명령줄 경로

SSH 연결 점검

  1. 01
    연결 정보 준비

    주문 전달 정보에서 호스트 주소, 포트, 사용자 이름과 임시 액세스 방식을 확인하세요. 변경되었을 수 있는 주소를 이전 터미널 기록에서 복사하지 마세요.

  2. 02
    최초 검증 실행

    신뢰할 수 있는 네트워크에서 먼저 상세 모드로 연결하고 호스트 지문을 확인한 뒤 계속 진행하세요. 지문이 전달 정보와 다르면 즉시 중단합니다.

  3. 03
    임시 자격 증명 교체

    자신의 SSH 공개 키를 인증 파일에 추가하고 새 세션으로 로그인할 수 있음을 확인한 뒤 더 이상 사용하지 않는 임시 액세스 항목을 제거하세요.

  4. 04
    세션 올바르게 종료

    포그라운드 작업을 먼저 중지하고 로그가 기록되었는지 확인한 다음 exit 를 사용해 종료하세요. 릴리스 작업이 실행 중인 터미널을 바로 닫지 마세요.

  5. 05
    액세스 이상 확인

    시간 초과가 발생하면 먼저 네트워크와 포트를 확인하고, 연결이 거부되면 주소와 서비스 상태를 확인하세요. 인증 실패 시 사용자 이름, 키 권한과 인증 파일을 점검합니다.

그래픽 인터페이스 경로

VNC 연결 점검

  1. 01
    클라이언트와 주소 준비

    신뢰할 수 있는 VNC 클라이언트에서 전달 정보에 따라 노드 주소와 포트를 입력하세요. 연결 전에 클라이언트의 불필요한 자격 증명 저장 기능을 끄세요.

  2. 02
    최초 화면 검증 완료

    예상한 macOS 그래픽 인터페이스가 표시되는지 확인하고 지역과 기기 설정을 점검하세요. 화면에 이상이 있으면 바로 코드나 인증서를 가져오지 마세요.

  3. 03
    액세스 자격 증명 업데이트

    임시 비밀번호를 교체한 뒤 다시 연결해 새 자격 증명이 유효한지 확인하세요. 팀 채팅 기록이나 빌드 스크립트에 전체 자격 증명을 저장하지 마세요.

  4. 04
    유휴 세션 종료

    작업을 저장하고 민감한 창을 닫은 뒤 세션을 종료하세요. 여러 사람이 협업할 때 현재 사용자와 실행 중인 그래픽 작업을 기록합니다.

  5. 05
    화면 이상 원인 찾기

    검은 화면이면 먼저 다시 연결하고 세션 상태를 확인하세요. 끊김이 있으면 표시 품질을 낮추고, 연결할 수 없으면 주소, 포트와 로컬 네트워크를 다시 점검합니다.

연결 진단 기록

SSH 상세 로그를 이해하고 반복 재시도를 피하세요

상세 모드에서는 연결이 네트워크, 지문 또는 인증 단계 중 어디에서 멈췄는지 확인할 수 있습니다. 아래 주소는 예시일 뿐이며 실제 연결 정보는 주문 전달 내용을 기준으로 하세요.

support-check · ssh diagnostic 
$ ssh -v -p 22 build@203.0.113.24
OpenSSH: reading configuration data
debug1: Connecting to 203.0.113.24 port 22
debug1: Connection established
debug1: identity file ~/.ssh/id_ed25519 type 3

The authenticity of host cannot be established.
ED25519 key fingerprint is SHA256:verify-with-delivery-record
Continue connecting only after fingerprint verification.

debug1: Server host key accepted
debug1: Offering public key: ~/.ssh/id_ed25519
debug1: Authentication succeeded (publickey)
Connected to the dedicated physical Mac node

$ sw_vers
ProductName: macOS

$ exit
Connection closed.
TIMEOUT

Connecting 상태가 오래 지속됨

먼저 정상 작동이 확인된 네트워크로 전환한 다음 주소와 포트가 정확한지 확인하세요. 여러 네트워크에서 모두 시간 초과가 발생하면 발생 시각, 로컬 출구 환경과 전체 로그를 기록합니다.

FINGERPRINT

호스트 지문이 기록과 일치하지 않음

연결을 중지하고 로컬의 알려진 호스트 기록을 바로 삭제한 뒤 재시도하지 마세요. 먼저 주문 노드와 전달 정보를 확인한 다음 지원 티켓으로 변경 원인을 확인합니다.

AUTH

네트워크는 연결되지만 인증 실패

사용자 이름, 개인 키 경로, 파일 권한과 공개 키가 인증 파일에 완전히 기록되었는지 확인하세요. 로그를 제출할 때 키 내용은 숨기고 인증 단계 정보만 남깁니다.

개발 도구 체인

Xcode 선택을 먼저 고정한 뒤 프로젝트 수준 오류를 처리하세요

빌드 머신에서 가장 흔한 환경 차이는 명령줄 도구 경로, 대상 이름, 의존성 상태와 서명 변수가 일치하지 않아 발생합니다. 먼저 머신 수준을 확인한 뒤 프로젝트 수준으로 넘어가세요.

XCODE

명령줄 도구 선택 확인

다음을 실행하세요: xcode-select -p 현재 경로를 확인한 다음 xcodebuild -version 으로 버전을 확인하세요. 버전을 전환한 후 터미널을 다시 열어 이후 작업에서 일관된 환경을 사용합니다.

예상 결과: 경로와 버전이 일치함
TARGET

실제로 사용 가능한 대상 나열

먼저 다음을 실행하세요: xcodebuild -listworkspace, project, scheme 및 configuration 이름을 확인한 뒤 정확한 이름을 자동화 명령어에 입력합니다.

예상 결과: 대상을 열거할 수 있음
SIGNING

서명 변수와 프로젝트 설정 분리

빌드에 필요한 변수가 현재 세션에 존재하는지 확인하고 민감한 값을 저장소에 기록하지 마세요. 변수의 존재 여부만 출력하고 로그에 전체 내용을 표시하지 않습니다.

예상 결과: 변수가 존재하며 노출되지 않음
LOGS

전체 빌드 기록 보관

각 작업의 명령어, 시작 시각, 종료 코드, 빌드 로그와 산출물 경로를 보관하세요. 실패 시 최초 오류 주변의 문맥도 함께 남기고 마지막 요약만 복사하지 마세요.

예상 결과: 실패를 재현할 수 있음
자동화 빌드

self-hosted runner를 식별 가능하고 격리되며 해제 가능한 상태로 운영하세요

runner 연결의 핵심은 첫 작업만 성공시키는 것이 아닙니다. 이후 작업이 어느 노드와 디렉터리에서 실행될지 알 수 있도록 하고, 사용 중지 시 등록 관계를 정리해야 합니다.

  1. 01

    등록 전 실행 계정 확인

    전용 실행 계정과 작업 디렉터리를 만들고, 해당 계정이 저장소를 읽고 빌드 디렉터리에 쓸 수 있는지 확인하세요. 빌드와 무관한 관리 권한은 기본적으로 부여하지 않습니다.

    검증: 동일한 계정으로 수동 작업을 완료할 수 있음
  2. 02

    실제 기능을 태그로 표현

    태그에는 지역, 칩 제품군, Xcode 주 버전과 용도를 표시하세요. 시간이 지나면 부정확해지는 ‘최신’, ‘최고 속도’ 같은 태그는 사용하지 않습니다.

    검증: 스케줄 조건이 대상 노드 하나와만 일치함
  3. 03

    작업 디렉터리 격리

    서로 다른 저장소나 파이프라인에는 별도 하위 디렉터리를 사용하고 캐시 디렉터리는 따로 관리하세요. 작업이 끝나면 임시 파일을 정리하되 재사용이 필요하고 출처가 명확한 캐시는 보존합니다.

    검증: 두 작업의 산출물이 서로 덮어쓰이지 않음
  4. 04

    동시 실행과 리소스 경합 제한

    먼저 단일 작업으로 시작해 CPU, 메모리, 디스크와 빌드 시간을 관찰한 뒤 동시 실행 수를 늘릴지 결정하세요. 그래픽 작업과 대규모 빌드를 기록 없이 동시에 실행하지 않습니다.

    검증: 피크 시간에도 스왑 공간이 계속 증가하지 않음
  5. 05

    사용 중지 시 완전히 등록 해제

    새 작업 수신을 먼저 중지하고 현재 작업이 끝날 때까지 기다린 다음 자동화 플랫폼에서 runner를 등록 해제하고 등록 토큰과 더 이상 필요하지 않은 작업 디렉터리를 제거하세요.

    검증: 기존 태그가 더 이상 작업을 받지 않음
동일한 작업 디렉터리를 여러 동시 작업에 할당하지 마세요. 의존성 캐시, DerivedData, 아카이브와 임시 서명 파일이 서로 덮어써 겉보기에는 무작위인 빌드 실패를 일으킬 수 있습니다.
용어 정리

먼저 여덟 가지 용어의 의미를 통일하세요

지원 티켓과 팀 문서에서 동일한 용어를 사용하면 네트워크, 기기, 세션과 빌드 도구를 뒤섞어 설명하는 일을 줄일 수 있습니다.

물리 노드
실제로 macOS를 실행하는 하드웨어 기기입니다. BookaMac 주문은 추상적인 공유 컴퓨팅 인스턴스가 아니라 물리 Mac mini에 해당합니다.
전용
대여 기간 동안 해당 기기는 주문에 따라 한 고객에게 제공되며 다른 고객의 워크로드와 동일한 물리 머신을 공유하지 않습니다.
클라우드 Mac
원격 노드에 위치하며 네트워크로 액세스할 수 있는 Mac입니다. 사용 위치와 액세스 방식을 설명하는 말이며 가상 머신을 의미하지 않습니다.
VNC
macOS 그래픽 인터페이스를 원격으로 보고 조작하는 연결 방식으로, 창·화면·대화형 작업이 필요한 경우에 적합합니다.
SSH
스크립트 실행, 파일 전송, 빌드 작업 관리와 진단 로그 수집에 적합한 암호화 명령줄 연결 방식입니다.
self-hosted runner
팀이 직접 등록하고 관리하는 자동화 작업 실행기로, 지정된 전용 물리 Mac 노드에서 작업을 실행합니다.
빌드 캐시
반복적인 다운로드와 컴파일을 줄이기 위해 보관하는 중간 데이터입니다. 캐시는 작업을 빠르게 하지만 버전 변경으로 환경 차이를 만들 수도 있습니다.
프로비저닝 프로파일
릴리스 및 테스트 과정에서 사용하는 서명 설정 자료 중 하나입니다. 프로젝트 권한에 따라 관리하고 환경 인수인계나 사용 종료 시 정리해야 합니다.
증상별 의사결정 트리

화면에 나타난 현상에서 다음 점검 단계로 이동하세요

가장 가까운 증상을 먼저 펼치세요. 한 점검을 완료한 뒤 다음으로 이동하고 결과를 기록하지 않은 상태에서 중간 단계를 건너뛰지 마세요.

노드에 연결할 수 없습니다. 무엇부터 확인해야 하나요?
  1. 주소 확인:현재 주문 전달 정보에서 호스트 주소, 포트와 사용자 이름을 다시 복사하세요.
  2. 시간 초과와 거부 구분:시간 초과는 보통 로컬 네트워크나 경로를 먼저 확인하고, 즉시 거부되면 주소, 포트와 연결 방식을 확인합니다.
  3. 상세 로그 열기:다음을 사용해 ssh -v 네트워크 연결이 이미 설정되었는지, 지문 검사를 통과했는지와 인증이 어느 단계에서 멈췄는지 확인합니다.
  4. 신뢰할 수 있는 다른 네트워크에서 재테스트:결과가 달라지면 두 네트워크 환경을 기록하고 ‘가끔 연결됨’이라고만 제출하지 마세요.
  5. 지원 요청으로 전환:여러 네트워크에서 모두 실패하면 주문 ID, 지역, 시각과 민감 정보가 제거된 상세 로그를 첨부해 지원 티켓을 제출하세요.
빌드 실패: Xcode, 프로젝트 또는 의존성 문제인가요?
  1. 버전 고정:다음 출력 결과를 기록하세요: xcode-select -p 및 xcodebuild -version .
  2. 대상 나열:scheme, configuration, workspace 또는 project 이름이 실제로 존재하는지 확인하세요.
  3. 첫 번째 오류 찾기:로그에서 처음 발생한 명확한 오류를 찾고 최종 실패 요약을 보고 역으로 추측하지 마세요.
  4. 의존성 검증:프로젝트 파일을 수정하지 않고 잠금 파일에 따라 의존성을 다시 해석해 결과를 비교하세요.
  5. 범위 좁히기:최소 대상을 단독으로 빌드해 실패가 환경, 프로젝트 설정 또는 특정 모듈에 속하는지 판단하세요.
디스크 공간 부족: 어떤 디렉터리부터 확인해야 하나요?
  1. 전체 사용량 확인:다음 명령으로 df -h 볼륨 수준의 공간을 확인하세요. 단일 프로젝트 디렉터리만 보지 마세요.
  2. 대용량 디렉터리 찾기:DerivedData, 아카이브, 시뮬레이터 데이터, 의존성 캐시와 runner 작업 디렉터리를 확인하세요.
  3. 캐시와 산출물 구분:캐시는 다시 만들 수 있지만 배포 산출물과 진단 로그는 먼저 보관한 뒤 정리해야 합니다.
  4. 활성 작업 중지:정리하기 전에 빌드가 대상 디렉터리에 쓰고 있지 않은지 확인해 손상된 중간 상태가 생기지 않도록 하세요.
  5. 증가 원인 재확인:정리 후 다음 작업에서 늘어난 공간을 관찰해 계속 증가하는 실제 디렉터리를 찾으세요.
인증서 또는 프로비저닝 프로파일 이상: 무작정 재설치하지 않으려면 어떻게 해야 하나요?
  1. 원본 오류 기록:찾을 수 없음, 만료됨, 권한 부족과 설정 불일치를 구분하세요.
  2. 빌드 대상 확인:현재 scheme, configuration과 서명 설정이 예상한 프로젝트에 속하는지 확인하세요.
  3. 키체인 권한 확인:빌드를 실행하는 계정이 필요한 자료에 액세스할 수 있는지 검증하고 관련 없는 권한을 확대하지 마세요.
  4. 프로비저닝 프로파일 확인:파일이 현재 작업 요구 사항과 일치하는지 확인하고 구분하기 어려운 이전 버전을 여러 개 동시에 보관하지 마세요.
  5. 민감한 자료 보호:티켓에는 오류, 이름과 필요한 메타데이터만 제출하고 개인 키나 전체 자격 증명은 보내지 마세요.
연결 또는 빌드 속도가 변동합니다. 문제 위치를 어떻게 판단하나요?
  1. 시간 범위 제시:시작·종료 시각과 지속 여부를 기록하고 ‘최근에 느림’을 유일한 설명으로 사용하지 마세요.
  2. 분리 측정:원격 화면, 파일 전송, 의존성 다운로드와 로컬 빌드를 각각 관찰하고 하나의 속도 결론으로 합치지 마세요.
  3. 동시 작업 확인:다른 빌드, 인덱싱, 트랜스코딩 또는 모델 작업이 동시에 리소스를 사용하는지 확인하세요.
  4. 네트워크 비교:서로 다른 신뢰할 수 있는 네트워크에서 같은 작업을 다시 테스트해 로컬 경로와 원격 작업 부하를 구분하세요.
  5. 샘플 보존:지역, 시각, 명령어 실행 시간과 민감 정보가 제거된 로그를 제출해 동일 조건으로 재확인할 수 있게 하세요.
지원 요청 경로

바로 문제 해결을 시작할 수 있는 지원 티켓에는 무엇이 포함되어야 하나요?

사실을 먼저 정리한 다음 콘솔을 통해 제출하세요. 완전한 맥락을 제공하면 단편적인 스크린샷을 여러 번 추가하는 것보다 문제를 빠르게 찾을 수 있습니다.

01

주문 ID

필요한 주문 ID만 제공하고 결제 정보나 관련 없는 정보는 보내지 마세요.

02

노드 지역

싱가포르, 일본(도쿄), 한국(서울) 또는 홍콩과 실제 연결 방식을 명시하세요.

03

발생 시각

시간대, 최초 발생 시각, 지속 시간과 안정적으로 재현 가능한지를 적으세요.

04

민감 정보가 제거된 로그

명령어, 종료 코드와 오류 문맥은 보존하되 토큰, 비밀번호, 개인 키와 전체 자격 증명은 숨기세요.

문서로 재현한 뒤 증거를 티켓에 첨부하세요

콘솔에서는 기존 주문을 확인하고 기술 지원 티켓을 제출할 수 있습니다. 아직 구성을 선택하는 중이라면 두 가지 전용 물리 Mac mini의 사양과 적합한 워크플로를 먼저 비교해 보세요.

콘솔로 이동 구성 비교