클라우드 Mac 연결 및 CI/CD 문제 해결 지원

01

콘솔에서 호스트 상태 확인

주문에 해당하는 클라우드 Mac이 연결 가능한 상태인지 확인하고, 노드 지역과 연결 정보가 동일한 물리 노드에 속하는지 대조하세요. 방금 관리 작업을 완료했다면 작업 시간과 현재 상태를 기록하고 같은 작업을 반복 제출하지 마세요.
통과 조건: 호스트 상태가 정상이며 주문 식별자, 노드 지역과 연결 대상이 일치합니다.
02
네트워크 접근성 확인

먼저 로컬 네트워크에서 대상 주소와 포트에 접근할 수 있는지 확인한 뒤 신뢰할 수 있는 다른 네트워크와 비교하세요. 사무실 네트워크에서만 실패한다면 외부 연결 정책을 확인하고, 모든 네트워크에서 실패하면 테스트 시간, 대상 포트와 오류 유형을 기록하세요.
```
nc -vz HOST PORT
ssh -vvv USER@HOST
```
통과 조건: 포트에 접근할 수 있으며 핸드셰이크 전에 연결 시간이 초과되지 않습니다.
03
SSH 또는 VNC 매개변수를 정확히 대조

호스트 주소, 포트, 사용자 이름과 연결 방식이 현재 주문 정보에서 가져온 것인지 확인하세요. SSH 설정 별칭이 포트나 키 경로를 덮어쓸 수 있으므로 상세 로그로 최종 매개변수를 확인하세요. VNC는 대상 주소, 디스플레이 설정과 클라이언트에 저장된 이전 기록을 대조해야 합니다.
```
ssh -G oak-node
ssh -v USER@HOST -p PORT
```
통과 조건: 클라이언트가 실제로 사용하는 매개변수가 콘솔 정보와 완전히 일치합니다.
04

로컬 방화벽 및 보안 정책 확인

임시 테스트 전에 기존 규칙을 기록하세요. 터미널, SSH 클라이언트 또는 VNC 클라이언트가 연결을 시작할 수 있는지, 기업 네트워크가 대상 포트를 제한하는지 확인하세요. 문제를 진단하기 위해 로컬 보호 기능 전체를 장기간 비활성화하지 마세요.
통과 조건: 대상 프로그램과 포트에 명확한 아웃바운드 권한이 있고 다른 네트워크 테스트 결과와 일치합니다.
05
인증 정보가 유효한지 확인

“네트워크 시간 초과”와 “인증 거부”를 구분하세요. 전자는 비밀번호를 바꿔 해결할 문제가 아니며, 후자는 사용자 이름, 키 파일, 파일 권한과 최근 인증 정보 변경 여부를 확인해야 합니다. 지원 요청에는 인증 오류 문구만 첨부하고 비밀번호나 개인 키 내용은 첨부하지 마세요.
```
chmod 600 ~/.ssh/id_ed25519
ssh-add -l
```
통과 조건: 핸드셰이크가 완료되고 인증에 성공하여 macOS 명령줄 또는 그래픽 인터페이스에 연결됩니다.

최소 증거 세트:주문 식별자, 노드 지역, 발생 시간과 시간대, 연결 방식, 클라이언트 오류 원문 및 확인한 단계를 포함하세요. 로그에서는 사용자 이름을 제외한 민감한 필드를 삭제하고 호스트 인증 정보, 키와 토큰을 가리세요.

TOOLCHAIN / 03

버전, 경로와 프로젝트 결과로 개발 환경을 확인하세요

“설치되어 있음”이 “파이프라인에서 사용 중”이라는 뜻은 아닙니다. 툴체인을 점검할 때는 실행 파일 경로, 버전, 현재 셸 환경과 프로젝트의 실제 호출 결과를 함께 기록해야 합니다.

도구	먼저 확인할 항목	권장 명령어	일반적인 불일치
Xcode	현재 개발자 디렉터리, 버전, SDK 목록	`xcode-select -p` `xcodebuild -version`	명령줄이 다른 Xcode를 가리키거나 프로젝트에 필요한 SDK가 현재 버전에 없음
Homebrew	바이너리 경로, 패키지 목록, 진단 결과	`brew --prefix` `brew doctor`	셸이 올바른 경로를 불러오지 않았거나 이전 후 패키지 목록과 로컬 환경이 불일치함
Git	버전, 원격 주소, 저장소 권한 및 사용자 설정	`git --version` `git remote -v`	runner와 대화형 셸이 서로 다른 인증 정보 또는 작업 디렉터리를 사용함
Fastlane	호출 출처, 종속성 고정, lane 및 환경 변수 이름	`bundle exec fastlane --version`	프로젝트 종속성 파일을 따르지 않고 전역 버전을 직접 호출함
언어 런타임	인터프리터 경로, 버전 관리자 및 프로젝트 고정 버전	`which ruby` `which node`	대화형 셸과 비대화형 작업이 서로 다른 초기화 파일을 불러옴

환경 기준선

머신에서 읽을 수 있는 목록을 보관하세요

macOS 버전, 칩 아키텍처, Xcode 버전, Homebrew 패키지 목록, Git 버전과 언어 런타임을 기록하세요. 업그레이드할 때는 한 번에 하나의 주요 구성 요소만 변경하고, 업그레이드 전후에 목록을 각각 저장하세요.

경로 관리

작업이 실제로 확인하는 PATH 점검

로컬 터미널에서는 실행되지만 runner에서 실패한다면 다음을 임시 진단 단계에 기록하세요. echo "$PATH" 및 which 버전 명령어를 함께 기록하세요. 확인이 끝나면 불필요한 환경 출력을 삭제하여 로그에 민감한 변수가 포함되지 않도록 하세요.

재현 가능한 검증

최소 프로젝트로 재현

먼저 종속성을 확인한 뒤 클린 빌드를 한 번 실행하고 산출물 경로와 종료 코드를 확인하세요. 최소 프로젝트는 성공하지만 실제 프로젝트가 실패한다면 프로젝트 설정, 종속성 고정과 스크립트 권한을 다시 확인하세요.

BASELINE COMMANDS

환경 스냅샷 명령어

다음 출력으로 기본 버전 기록을 만들 수 있습니다. 지원 요청을 제출하기 전에 디렉터리에서 프로젝트 이름과 민감한 매개변수를 삭제하세요.

uname -m
sw_vers
xcode-select -p
xcodebuild -version
brew --prefix
git --version
which ruby
which node
df -h /

CI/CD / 04

runner 온라인 상태에서 개별 작업 로그까지 추적하세요

CI/CD 문제는 “작업을 수락했는가, 작업 디렉터리에 진입했는가, 권한을 얻었는가, 종속성을 찾았는가, 빌드를 완료했는가”의 순서로 판단해야 합니다. 최종 실패 메시지만으로 결론을 내리지 마세요.

01

Runner 등록

runner 서비스가 실행 중이고 등록 관계가 유효하며 콘솔에 온라인으로 표시되는지 확인하세요. 재시작하기 전에 마지막 온라인 시간과 최근 성공한 작업을 기록하세요.

runner 이름과 대상 프로젝트 대조
서비스 프로세스와 시작 사용자 확인
시스템 재시작 후 자동으로 복구되는지 확인

02

태그 일치

작업이 오랫동안 대기 중인데 runner가 온라인이라면 작업에 요구된 태그와 runner의 실제 태그를 비교하세요. 태그의 대소문자, 공백 또는 아키텍처가 다르면 작업을 할당받지 못할 수 있습니다.

명확한 Apple Silicon 태그 하나 유지
사용하지 않는 이전 태그 삭제
대상 브랜치에서 해당 runner를 사용할 수 있는지 확인

03

권한 및 작업 디렉터리

runner 사용자가 저장소, 캐시와 산출물 디렉터리에 필요한 권한을 보유하는지 확인하세요. 모든 디렉터리의 권한을 확대하여 특정 경로 설정 오류를 숨기지 마세요.

작업이 실제로 실행되는 사용자 기록
스크립트에 실행 권한이 있는지 확인
임시 디렉터리에서 파일을 만들고 삭제할 수 있는지 확인

04

캐시 및 동시 실행

캐시가 무효화되면 먼저 기존 캐시를 읽지 않는 비교 작업을 실행하세요. 동시 작업이 서로 파일을 덮어쓴다면 작업마다 별도 작업 디렉터리를 할당하고 Oak Core 또는 Oak Forge의 메모리와 스토리지가 작업 규모에 적합한지 확인하세요.

캐시 키와 종속성 잠금 파일 버전 기록
공유 캐시와 작업 디렉터리 구분
단일 작업과 동시 작업 결과 비교

05

로그 및 종료 코드

작업 시작 시간, runner 이름, 커밋 식별자, 주요 도구 버전, 실패 단계, 종료 코드와 마지막 로그를 보관하세요. 실패가 재현되면 가장 짧은 재현 절차를 기록하고, 간헐적이면 성공 사례와 실패 사례를 각각 한 번 이상 보관하세요.

주요 단계의 시작 및 종료 시간 출력
빌드 로그와 테스트 보고서를 산출물로 저장
업로드 전에 토큰, 키와 서명 자료 삭제

작업이 계속 대기 중

먼저 runner 온라인 상태, 프로젝트 권한과 태그를 확인하세요. 아직 빌드 단계에 진입하지 않았으므로 이때는 캐시를 정리하지 마세요.

작업 시작 직후 실패

작업 디렉터리, 스크립트 권한, 셸 초기화와 도구 경로를 먼저 확인하세요. 대화형 터미널과 runner 환경 변수를 비교하세요.

종속성 설치가 불안정함

잠금 파일, 캐시 키, 디스크 여유 공간과 네트워크 다운로드 로그를 확인하세요. 클린 캐시 작업을 한 번 실행해 비교 기준을 만들고 원본 증거를 연속해서 덮어쓰지 마세요.

동시 실행에서만 실패

메모리 사용량, 공유 디렉터리 쓰기 충돌, 포트 사용과 임시 파일 이름을 확인하세요. 먼저 동시 실행 수를 줄여 검증한 뒤 작업 분할이나 설정을 조정하세요.

GLOSSARY-MINI / 05

지원 요청에서 자주 쓰는 8가지 용어

일관된 용어를 사용하면 추가 확인을 줄일 수 있습니다. 문제를 설명할 때는 “서버를 사용할 수 없음”처럼 막연하게 쓰기보다 “도쿄 노드의 SSH 연결 시간 초과”처럼 구체적인 대상을 명시하세요.

클라우드 Mac: 네트워크를 통해 원격으로 사용하는 macOS 개발 환경으로, 그래픽 인터페이스, 명령줄, 빌드 작업과 자동화 흐름에 사용할 수 있습니다.
물리 노드: 실제로 배포된 Mac mini 장비입니다. Oakmini는 전용 물리 컴퓨터로 서비스를 제공하며 하나의 컴퓨팅 인스턴스를 가상 머신으로 나누어 여러 사용자에게 제공하지 않습니다.
전용: 주문 기간 동안 해당 사용자가 지정된 물리 노드의 리소스를 사용하여 빌드 동시 실행, 캐시와 도구 버전을 안정적으로 관리할 수 있습니다.
VNC: macOS 그래픽 인터페이스에 접근하는 원격 연결 방식입니다. 화질, 해상도와 로컬 네트워크 경로가 상호작용 환경에 영향을 줍니다.
SSH: 명령줄에 안전하게 접근하는 연결 방식으로, 호스트 주소, 포트, 사용자 이름과 유효한 인증 정보가 필요합니다.
self-hosted runner: 사용자가 관리하는 환경에 배포된 CI 실행 프로그램으로, 작업을 수락하고 작업 디렉터리에 진입해 빌드 스크립트를 실행합니다.
빌드 캐시: 반복적인 다운로드나 컴파일을 줄이기 위해 저장하는 중간 데이터입니다. 캐시 키, 종속성 버전과 작업 디렉터리가 일치하지 않으면 잘못된 결과가 발생할 수 있습니다.
노드 지역: 물리 노드가 위치한 지역입니다. 현재 판매 지역은 싱가포르, 일본(도쿄), 한국(서울), 홍콩과 미국 서부로 한정됩니다.

REQUEST / 06

바로 재현할 수 있는 지원 요청 제출

Oakmini의 연락 방법은 두 가지뿐입니다. 콘솔에 로그인해 티켓을 제출하거나 support@oakmini.com으로 이메일을 보내세요. 기존 주문, 호스트 상태와 지속적인 진단 기록이 관련된 경우 티켓을 우선 사용하고, 구매 전 문의나 콘솔에 접속할 수 없는 경우 이메일을 사용하세요.

필수 제공 정보

문제 상황

주문 식별자:주문을 확인하는 데 필요한 식별자만 제공하고 결제 인증 정보는 보내지 마세요.
노드 지역:싱가포르, 일본(도쿄), 한국(서울), 홍콩 또는 미국 서부.
발생 시간:날짜, 정확한 시간과 시간대를 적고 재현 가능한지도 표시하세요.
연결 또는 작업 유형:SSH, VNC, Xcode 빌드, runner 작업 또는 콘솔 작업.
재현 절차:실행 순서에 따라 번호를 매기고 예상 결과와 실제 결과를 적으세요.
민감 정보 제거 로그:오류 원문, 종료 코드와 관련 맥락을 남기고 민감한 필드는 삭제하세요.

첨부 금지 항목

민감한 내용은 티켓이나 이메일에 포함하지 마세요

계정 비밀번호 문제 해결에 비밀번호 원문은 필요하지 않습니다.
개인 키 또는 액세스 토큰 키 유형이나 오류 정보는 제공할 수 있지만 키 내용은 제공하지 마세요.
서명 인증서 원문 인증서 용도, 유효 상태와 오류만 설명하고 전체 자료는 업로드하지 마세요.
결제 인증 정보 주문 식별자와 거래 상태만 제공하고 카드 또는 지갑의 민감한 데이터는 보내지 마세요.
민감 정보가 제거되지 않은 프로젝트 로그 먼저 저장소 주소, 환경 변수, 고객 데이터와 내부 경로를 삭제하세요.

COPYABLE STRUCTURE

지원 요청 구조

항목별로 작성하고 모르는 항목에는 “확인되지 않음”이라고 적으세요. 추측하지 마세요. 여러 번 시도한 문제라면 시간순으로 나열하세요.

제목: 주문 식별자 / 문제 유형 / 노드 지역
발생 시간 및 시간대:
연결 방식 또는 작업 유형:
예상 결과:
실제 결과:
재현 절차:
1.
2.
3.
완료한 진단:
오류 원문 및 종료 코드:
민감 정보 제거 로그 첨부 설명:

콘솔에 로그인해 티켓 제출 support@oakmini.com으로 이메일 보내기

PORTAL / 07

호스트 상태, 주문과 관리 작업은 모두 콘솔에서 처리하세요

지원 페이지에서는 문제 해결 순서, 명령어와 정보 준비 방법을 제공합니다. 실제 주문, 이용 연장, 주문 조회, 호스트 상태 확인과 클라우드 Mac 관리는 모두 콘솔에서 처리합니다. 모든 노드는 연중 365일 정상 운영됩니다. 상태와 실제 연결 결과가 일치하지 않으면 시간을 기록하고 티켓을 제출하세요.

콘솔: 주문 및 호스트 관리 지원 페이지: 진단 및 증거 준비 티켓 또는 이메일: 전문가 지원

클라우드 Mac 관리 첫 연결 가이드 보기

클라우드 Mac 문제를 재현 가능한 단계로 좁혀보세요

문제에 맞는 진단 경로부터 선택하세요

연결할 수 없음

개발 환경

CI/CD

스토리지

네트워크

계정 관리

공간을 사용하는 위치부터 찾기

상호작용 지연과 작업 소요 시간을 분리하세요

콘솔의 주문 상태를 기준으로 확인하세요

5단계 순서로 연결을 진단하세요

콘솔에서 호스트 상태 확인

네트워크 접근성 확인

SSH 또는 VNC 매개변수를 정확히 대조

로컬 방화벽 및 보안 정책 확인

인증 정보가 유효한지 확인