연결 계층부터 진단하기

클라우드 Mac에 문제가 생겼다면 계층별로 진단하세요

SSH, 그래픽 인터페이스와 파일 전송부터 Xcode, Runner, fastlane 및 노드 네트워크까지, 재현 가능한 명령으로 범위를 좁힌 뒤 설정을 수정할지 지원 티켓을 제출할지 결정하세요.

전용 물리 머신 macOS 그래픽 인터페이스 및 명령줄 4개 노드 네트워크 진단
여러 Mac mini 물리 노드와 네트워크 링크로 구성된 엔지니어링 클러스터
diagnose@mac-node — zsh

$ ssh -v "$MAC_USER@$MAC_HOST"

debug1: Authentication succeeded

$ xcodebuild -version

Xcode toolchain ready

$ scutil --dns | grep nameserver

Resolver path verified

최초 연결

검증 가능한 SSH 연결부터 설정하기

콘솔에서 해당 인스턴스를 열고 호스트 주소, 로그인 사용자 이름과 초기 인증 정보를 확인하세요. 최초 연결에서는 대상 호스트 확인, 시스템 로그인, 이후 키 기반 로그인 전환이라는 세 가지를 해결합니다.

  1. 01

    인스턴스와 로컬 환경 확인

    먼저 인스턴스가 정상 실행 중인지 확인하고, 콘솔에 표시된 호스트 주소와 사용자 이름을 각각 로컬 환경 변수에 입력하세요. 비밀번호, 개인 키 또는 전체 인증 정보를 저장소·대화 기록·자동화 로그에 남기지 마세요.

    export MAC_HOST="콘솔에 표시된 호스트 주소"
    export MAC_USER="콘솔에 표시된 사용자 이름"
    test -n "$MAC_HOST" && test -n "$MAC_USER" && echo "connection variables ready"
  2. 02

    최초 연결 후 호스트 지문 확인

    연결한 뒤 터미널에 표시된 지문을 콘솔 정보와 대조하세요. 호스트 주소가 바뀌었거나 재설치 후 지문이 변경되었거나 로컬에 이전 기록이 남아 있다면 경고를 무시하지 말고 동일한 인스턴스인지 먼저 확인하세요.

    ssh -v "$MAC_USER@$MAC_HOST"
    ssh-keygen -F "$MAC_HOST"
  3. 03

    전용 키 생성 및 설치

    클라우드 Mac 전용 Ed25519 키를 생성하면 교체와 폐기가 편리합니다. 공개 키를 설치한 뒤 현재 세션을 유지하고 새 터미널에서 키 로그인이 성공하는지 확인한 후 기존 세션을 종료하세요.

    ssh-keygen -t ed25519 -a 64 -f "$HOME/.ssh/macrents_build"
    cat "$HOME/.ssh/macrents_build.pub" | ssh "$MAC_USER@$MAC_HOST" 'umask 077; mkdir -p ~/.ssh; cat >> ~/.ssh/authorized_keys'
    ssh -i "$HOME/.ssh/macrents_build" "$MAC_USER@$MAC_HOST"
  4. 04

    클라이언트 설정 고정 및 기준 상태 점검

    해당 인스턴스에 전용 별칭, 키 경로와 연결 유지 옵션을 설정하세요. 시스템에 들어간 뒤 macOS 버전, 디스크 여유 공간, 현재 사용자와 시스템 시간을 기록하면 이후 빌드 실패 시 환경 변경 여부를 빠르게 판단할 수 있습니다.

    sw_vers
    whoami
    date
    df -h /
    uptime

연결 시간 초과와 인증 실패는 서로 다른 문제입니다

시간 초과가 발생하면 먼저 로컬 네트워크, 포트, 노드 라우팅과 소스 주소 제한을 확인하세요. Permission denied 가 표시되면 사용자 이름, 키 파일, 파일 권한과 서버 측 인증 기록을 먼저 확인하세요. 인증 오류가 날 때 DNS를 반복해서 바꾸거나 네트워크가 연결되지 않을 때 인증 정보를 계속 초기화하지 마세요.

원격 액세스

작업에 맞는 터미널·그래픽 인터페이스·파일 채널 선택

빌드와 자동화에는 SSH를 우선 사용하세요. 인터페이스 디버깅, 시뮬레이터 또는 데스크톱 도구가 필요할 때는 그래픽 원격 데스크톱을 사용하고, 프로젝트와 산출물을 대량 동기화할 때는 재개 가능한 파일 전송을 사용하세요.

터미널 연결

저장소 가져오기, 종속성 설치, 빌드 실행과 상주 작업 관리에 적합합니다. 연결이 불안정하면 클라이언트 연결 유지를 활성화하고 상세 로그로 중단 지점이 핸드셰이크·인증·세션 중 어디인지 확인하세요.

ssh -vvv -o ServerAliveInterval=30 -o ServerAliveCountMax=4 "$MAC_USER@$MAC_HOST"

그래픽 원격 데스크톱

콘솔에서 그래픽 액세스 메뉴로 들어가 Xcode UI 디버깅, 시뮬레이터 확인과 데스크톱 상호작용이 필요한 도구에 사용하세요. 끊김이 있으면 먼저 해상도와 화면 주사율을 낮춘 뒤 터미널 지연 시간과 비교해 화면 인코딩 문제인지 전체 네트워크 문제인지 구분하세요.

파일 전송

소량 파일에는 scp을 사용할 수 있고, 대형 디렉터리와 빌드 캐시에는 rsync를 권장합니다. 전송 전 파생 데이터, 임시 아카이브와 종속성 캐시를 제외해 재생성 가능한 콘텐츠를 반복해서 장거리 전송하지 마세요.

rsync -azP --partial --exclude DerivedData/ ./project/ "$MAC_USER@$MAC_HOST:~/workspace/project/"

세션 보안 및 연결 복구

장시간 빌드를 단일 포그라운드 터미널에만 의존하지 마세요. 세션 관리자나 macOS 서비스 메커니즘으로 작업을 유지하고 로그를 관리되는 디렉터리에 주기적으로 기록하세요. 프로젝트를 떠날 때 더 이상 사용하지 않는 공개 키와 액세스 토큰을 폐기하세요.

tmux new -s build
tmux attach -t build
tail -n 200 "$HOME/logs/build.log"
빌드 도구 체인

Xcode 오류 전, 실제 사용 중인 도구 체인부터 확인하기

그래픽 인터페이스에서 보이는 Xcode와 명령줄에서 선택된 개발자 디렉터리는 서로 다른 버전일 수 있습니다. 경로, 버전, SDK, 시뮬레이터와 서명 환경을 먼저 기록한 뒤 최소 빌드 명령을 다시 실행하세요.

기본 점검 명령

xcode-select -p
xcodebuild -version
xcodebuild -showsdks
xcrun simctl list devices available
xcrun --find swift
swift --version
security list-keychains -d user
security find-identity -v -p codesigning
A

개발자 디렉터리

xcode-select -p 는 이번 빌드에 필요한 Xcode를 가리켜야 합니다. 경로가 다르면 먼저 Runner를 중지하고 디렉터리를 전환한 뒤 다시 시작해 실행 중인 작업이 이전 환경을 물려받지 않도록 하세요.

B

SDK 및 시뮬레이터

대상 SDK가 -showsdks 출력에 없으면 프로젝트 매개변수를 수정해도 도구 체인이 보완되지 않습니다. 시뮬레이터 작업에서는 기기 상태, 런타임 버전과 디스크 공간도 확인하세요.

C

서명 ID 및 키체인

서명 ID가 존재한다고 해서 자동화 프로세스가 개인 키를 읽을 수 있는 것은 아닙니다. 대화형 터미널과 Runner 서비스의 사용자, 키체인 검색 목록 및 잠금 해제 상태를 비교하세요.

D

최소 빌드 재현

작업 공간, scheme, configuration과 destination을 고정한 뒤 관련 없는 스크립트를 비활성화하세요. 전체 종료 코드와 마지막 로그를 보존하고 마지막 오류 한 줄만 잘라내지 마세요.

set -o pipefail
xcodebuild -workspace Project.xcworkspace -scheme Project -configuration Release -destination 'generic/platform=macOS' clean build | tee "$HOME/logs/xcode-build.log"
printf 'exit_code=%s\n' "$?"
자동화 연동

Runner가 등록되었다고 빌드 환경이 재현 가능한 것은 아닙니다

셀프 호스팅 Runner와 상주 에이전트는 실행 사용자, 작업 디렉터리, 도구 체인 경로, 캐시 범위와 키 접근 방식을 고정해야 합니다. 먼저 최소 작업 하나를 안정적으로 완료한 뒤 동시 실행, 캐시와 배포 단계를 단계적으로 복원하세요.

GitHub Actions

셀프 호스팅 Mac Runner

프로젝트 또는 조직 설정에서 일회성 등록 정보를 생성하고 클라우드 Mac에서 전용 시스템 사용자로 등록하세요. 레이블은 운영체제, 칩 등급과 용도를 구분해야 하며 워크플로는 macOS 작업을 해당 노드로만 라우팅해야 합니다.

  • 등록 후 상주 서비스로 설치
  • 빌드 디렉터리와 인증 정보 디렉터리 분리
  • 각 작업이 끝나면 임시 서명 자료 삭제
  • 먼저 동시 실행 수를 1로 제한한 뒤 대기열 평가
whoami
xcode-select -p
printenv | sort
df -h "$HOME"
GitLab CI

macOS Runner

등록 시 macOS에 적합한 실행 방식을 선택하고 보호된 레이블로 작업 출처를 제한하세요. 서비스 사용자는 프로젝트 디렉터리와 필요한 키체인에 접근할 수 있어야 하지만 빌드와 무관한 시스템 권한은 가져서는 안 됩니다.

  • 레이블과 보호 브랜치 규칙 확인
  • 캐시 키에 도구 체인 및 종속성 버전 포함
  • 일시적인 네트워크 단계에만 실패 재시도 적용
  • 산출물 업로드 전 체크섬과 크기 기록
git status --short
git rev-parse HEAD
shasum -a 256 "$HOME/artifacts/app.zip"
du -sh "$HOME/build-cache"
상주 빌드 에이전트

서비스로 실행

자체 개발 에이전트나 기타 빌드 에이전트는 macOS 서비스 메커니즘으로 관리하고 시작 사용자, 환경 변수 파일, 표준 출력과 종료 후 재시작 정책을 명확히 하세요. 원격 데스크톱 세션이 계속 연결되어 있다고 가정하지 마세요.

  • 안정적이고 고유한 작업 디렉터리 설정
  • 로그 크기를 제한하고 실패 상황 보존
  • 재시작 후 자동 복구하되 실패 반복은 방지
  • 도구 체인과 디스크 기준 상태 정기 검증
launchctl list | grep build
ps aux | grep '[b]uild-agent'
lsof -nP -iTCP -sTCP:ESTABLISHED
tail -n 200 "$HOME/logs/agent.log"

권장 최소 연동 순서

  1. 환경 프로브: 사용자, Xcode 경로, 버전, 디스크와 작업 디렉터리를 출력합니다.
  2. 저장소 작업: 체크아웃과 종속성 확인만 실행해 네트워크와 파일 권한을 확인합니다.
  3. 서명 없는 빌드: 컴파일과 테스트를 검증하고 인증서 변수를 배제합니다.
  4. 서명 아카이브: 관리되는 키체인과 필요한 환경 변수를 연결합니다.
  5. 산출물 업로드: 종료 코드, 파일 크기, 체크섬과 업로드 로그를 기록합니다.
  6. 동시 실행 확장: CPU, 통합 메모리, 디스크 읽기·쓰기와 대기열 시간을 확인한 뒤 작업 수를 늘립니다.
배포 자동화

fastlane 실패 시 인증서·권한·변수·로그 계층별 점검

처음부터 모든 종속성을 재설치하지 마세요. 서명 준비, 아카이브, 내보내기 또는 업로드 중 어느 단계에서 실패했는지 확인한 뒤 해당 단계의 입력, 종료 코드와 비식별화 로그를 수집하세요.

fastlane 일반 문제·점검 명령·판단 방법
진단 계층 일반적인 증상 먼저 확인할 항목 처리 원칙
인증서 서명 ID를 찾을 수 없거나 ID 수가 0 security find-identity -v -p codesigning 대상 키체인으로 가져왔는지, 인증서가 유효한지, 개인 키와 쌍을 이루는지 확인
프로비저닝 프로파일 식별자가 일치하지 않거나 권한 항목이 다름 대상 식별자, 팀 정보, 필요한 권한과 파일 내용 서로 다른 프로젝트나 환경의 프로파일을 혼용하지 않기
키체인 권한 터미널에서는 빌드되지만 Runner에서는 서명할 수 없음 실행 사용자, 검색 목록, 잠금 해제 상태와 개인 키 접근 제어 자동화 프로세스가 이번 작업에 필요한 서명 자료만 사용하도록 설정
환경 변수 대화형 실행은 성공하지만 서비스 실행에 매개변수가 없음 printenv 의 비식별화 차이와 서비스 시작 설정 변수를 명시적으로 주입하고 대화형 Shell 설정 파일에 의존하지 않기
업로드 로그 아카이브는 성공했지만 업로드가 중단되거나 0이 아닌 상태를 반환 전체 종료 코드, 재시도 횟수, 파일 크기와 네트워크 시간 흐름 먼저 산출물의 유효성을 확인하고 업로드 문제와 빌드 문제를 분리
터미널에서는 성공하는데 Runner에서는 왜 서명 ID를 찾을 수 없나요?

가장 일반적인 원인은 실행 사용자가 다르거나 서비스 프로세스가 대화형 세션의 키체인 검색 목록을 상속하지 못한 경우입니다. whoamisecurity list-keychains -d user 및 서명 ID 출력을 각각 기록한 뒤 두 실행 환경을 비교하세요. 모든 개인 키 권한을 완화해 사용자 경계 문제를 숨기지 마세요.

fastlane에 부족한 것이 프로젝트 설정이 아니라 환경 변수인지 어떻게 확인하나요?

동일한 커밋, Xcode 경로와 작업 디렉터리에서 대화형 터미널과 Runner의 비식별화 변수명 목록을 각각 출력하세요. 토큰 값은 출력하지 말고 변수 존재 여부만 비교하세요. 변수가 모두 있으면 작업 디렉터리, Shell 유형, 종속성 버전과 실행 사용자를 확인하세요.

fastlane 문제 제출 시 어떤 로그를 보존해야 하나요?

lane 이름, 실패 단계, 전체 종료 코드, Xcode 및 fastlane 버전, 작업 시작·종료 시간, 마지막 상황과 재현 명령을 보존하세요. 액세스 토큰, 인증서 비밀번호, 개인 키, 세션 정보와 개인정보를 삭제한 뒤 제출하세요. 마지막 오류 한 줄만 담긴 스크린샷으로는 보통 문제를 진단하기 어렵습니다.

4개 노드 네트워크

싱가포르·일본(도쿄)·한국(서울)·홍콩을 동일한 지표로 비교

노드는 팀 위치, 코드와 종속성 출처, 산출물 목적지 및 실제 경로를 기준으로 선택해야 합니다. 한 번의 지연 시간만 보지 말고 왕복 지연, 패킷 손실, DNS 확인과 라우팅 변화를 비교해 테스트 시간대도 기록하세요.

SG

싱가포르

동남아시아 대상 팀과 종속성 경로에 적합합니다. 지연 시간이 갑자기 늘면 사무실 네트워크, 모바일 네트워크와 다른 출구 회선을 비교해 현지 통신사 경로 변화인지 판단하세요.

JP

일본(도쿄)

일본 및 동북아 프로젝트에 적합합니다. 국가 간 연결을 점검할 때 직접 연결 지연, 라우팅 홉 수와 파일 전송 속도를 함께 기록하고 그래픽 데스크톱의 체감 부드러움만으로 판단하지 마세요.

KR

한국(서울)

한국과 인접 지역의 접속에 적합합니다. SSH는 가능하지만 대용량 파일 속도가 불안정하면 패킷 손실, 경로 MTU, 로컬 프록시와 동시 전송 수를 확인하세요.

HK

홍콩

아시아 지역 간 협업과 여러 지역의 팀에 적합합니다. 특정 네트워크에서는 연결되고 다른 네트워크에서는 시간 초과가 발생하면 두 라우팅 결과를 저장하고 출발 네트워크 유형을 기록하세요.

지연 시간 및 패킷 손실

단기 테스트는 연결 가능 여부를 확인하고, 지속 테스트는 지터와 간헐적 패킷 손실을 찾는 데 사용합니다. $MAC_HOST 를 현재 인스턴스 주소로 설정한 뒤 실행하세요:

ping -c 20 "$MAC_HOST"
nc -vz -w 5 "$MAC_HOST" 22
traceroute "$MAC_HOST"

DNS 및 로컬 확인

호스트 이름으로 연결한다면 먼저 확인 결과가 안정적인지 확인하세요. 주소를 직접 사용해도 실패한다면 보통 DNS가 원인이 아닙니다. 현재 로컬 리졸버와 조회 결과를 기록하세요:

scutil --dns
dscacheutil -q host -a name "$MAC_HOST"
dig "$MAC_HOST"

라우팅 및 인터페이스

트래픽이 예상 인터페이스에서 나가는지 확인하고 로컬 VPN, 프록시 또는 다중 네트워크 카드가 기본 경로를 바꾸는지 점검하세요. 테스트 후 원래 네트워크 설정으로 복원하고 여러 변수를 동시에 변경하지 마세요:

route -n get "$MAC_HOST"
netstat -rn
ifconfig
networkQuality

전송 계층 검증

SSH 핸드셰이크는 정상이지만 전송이 느리다면 고정 파일로 반복 테스트를 수행하고 파일 크기, 소요 시간과 클라이언트 네트워크를 기록하세요. 서로 다른 프로젝트 디렉터리나 압축 방식의 결과를 직접 비교하지 마세요:

time scp "$HOME/test-transfer.bin" "$MAC_USER@$MAC_HOST:~/"
shasum -a 256 "$HOME/test-transfer.bin"
ssh "$MAC_USER@$MAC_HOST" 'shasum -a 256 ~/test-transfer.bin'

모든 노드는 연중 365일 정상 운영

연결에 이상이 있으면 출발 네트워크, 대상 노드, 프로토콜과 시간 범위별로 증거를 수집하세요. 한 번의 속도 측정은 장기 경로 품질을 대표하지 않습니다. 동일한 테스트를 문제 네트워크와 비교 네트워크에서 각각 한 번 이상 실행해야 문제가 로컬 출구, 국가 간 경로 또는 대상 연결 계층에 있는지 판단할 수 있습니다.

전문 지원 요청

재현 가능한 상황과 함께 지원 티켓 제출

기존 사용자는 주문과 인스턴스를 연결할 수 있도록 먼저 콘솔에 로그인해 지원 티켓을 제출하세요. 콘솔에 들어갈 수 없다면 support@macrents.com으로 이메일을 보내세요. 두 방법 모두 동일한 지원 절차로 접수됩니다.

티켓에 포함할 내용

  • 주문 번호와 영향을 받은 인스턴스
  • 노드: 싱가포르, 일본(도쿄), 한국(서울) 또는 홍콩
  • 문제가 발생한 시간 범위와 시간대
  • 예상 결과, 실제 결과와 재현 단계
  • 클라이언트 시스템, 네트워크 유형과 사용한 프로토콜
  • 명령 종료 코드와 비식별화된 관련 로그
  • 이미 수행한 점검 단계와 결과

메시지에 보내지 말아야 할 내용

  • 개인 키 파일 또는 개인 키 원문
  • 전체 비밀번호, 액세스 토큰 또는 세션 정보
  • 인증서 비밀번호와 암호화되지 않은 서명 자료
  • 사용자 데이터가 포함된 전체 데이터베이스 또는 프로젝트 아카이브
  • 처리되지 않은 개인정보와 영업 기밀

로그의 호스트 주소는 필요한 일부를 남길 수 있지만 토큰, 비밀번호, 요청 헤더, 서명 자료와 개인정보는 삭제해야 합니다. 지원 담당자가 추가 정보를 필요로 하면 티켓에서 최소 범위를 명확히 안내합니다.

제출 후 처리 절차

주문 및 인스턴스 확인 재현 조건 재검토 연결 또는 환경 계층 진단 조치 단계 제공 복구 결과 확인

연결이 끊기거나 인스턴스에 액세스할 수 없거나 빌드 작업이 계속 실패하면 비즈니스 영향 범위를 명시하세요. 구입 전 구성 상담은 이메일로 문의할 수 있으며, 기존 주문·호스트 상태·로그와 관련된 기술 문제는 콘솔 티켓을 우선 이용하세요.

다음 단계

구성을 올바르게 선택하고 문제 해결 절차를 팀 프로세스에 연결하세요

세 가지 요금제 모두 전용 Mac mini 물리 노드이며 가상 머신이 아닙니다. 빌드 동시 실행 수, 통합 메모리 요구 사항과 대여 기간에 따라 선택하세요. 기존 인스턴스에 문제가 있으면 콘솔에 로그인해 바로 지원 티켓을 제출할 수 있습니다.