대상: 원격 Mac self-hosted 러너에서 GHCR·사설 레지스트리로 국경 간 docker pull을 다루는 팀. 산출물: 위험 체크리스트, 최소 권한 인증, 엔드포인트 표, 명령 자리표시자, 동시성·토큰 TTL·429/5xx 백오프·디스크 워터마크 표, FAQ. 블로그 목록·Git·Docker 풀 가속·홈은 공개 페이지만 연결했습니다.

시나리오와 위험 체크리스트

국경 간 docker pull의 대표 실패는 429, 5xx, 토큰 만료, 디스크 압박, TLS·프록시 불일치입니다. 동시성을 건드리기 전에 지배 시나리오에 라벨을 붙이세요.

공유 원격 Mac에서는 “CPU 한가함 + 레이어 정지”, APFS 지연, 동일 샤드 재시도 폭주가 겹칩니다. 사고를 429·5xx·인증·디스크로 분류하고 주간에 레버를 하나씩만 조정하세요.

1
릴리스 버스트: 동일 digest 몰림 → 에지 429. 릴레이 선풀이·레그 시차 없으면 완화 어렵습니다.
2
사설 우선 정책: GHCR 금지 후 단일 미러에도 백오프·한도 규율은 동일합니다.
3
멀티 테넌트 풀: 과한 max-concurrent-downloads는 공존 잡·SSD 대기열을 망칩니다.

매트릭스를 수용 기준으로 삼고, 429가 늘면 동시성을 한 단계 내리고 백오프를 늘리세요.

인증과 최소 권한

GHCR: read:packages PAT 또는 저장소 한정 fine-grained 토큰. 사설(Harbor·클라우드·distribution): 풀 전용 로봇·가능 시 OIDC·짧은 TTL.

공유 러너에 장기 자격 증명을 world-readable config.json에 두지 말고, 잡마다 docker login·trap으로 docker logout하거나 좁은 ACL credential helper를 쓰세요.

GitHub는 멤버십·가시성·스코프가 묶이고, Harbor류는 감사·로봇 계정이 강합니다. 서 있는 권한이 적은 쪽을 표준으로 잡고 순환 런북을 하나로 고정하세요.

  • 금지: 팀 전체에 관리자 개인 PAT를 재사용하는 것—순환이 곧 장애가 됩니다.
  • 원칙: 토큰은 최소 패키지 네임스페이스에만 스코프하고, CI 읽기와 릴리스 쓰기를 분리합니다.
  • 주기: 벤더 최대 TTL보다 짧은 달력 순환을 두어 만료 알림이 하드 컷오프보다 먼저 울리게 합니다.

국경 간 네트워크와 미러·레지스트리 엔드포인트 비교

ghcr.io vs 사설·캐시는 지연·컴플라이언스·운영의 트레이드오프입니다. 표로 1차·폴백을 문서화하세요.

엔드포인트 유형 강점 약점 이렇게 선택
GHCR(ghcr.io) GitHub·OIDC 일체형, 미러 부담 적음. 장거리 지연·공용 한도. 러너가 레지스트리에 가까울 때.
클라우드 벤더 사설 레지스트리(러너와 동일 리전) 과금·SLA·프라이빗 링크. GHCR 복제 파이프 추가. 상주 규정이 러너 인근을 요구할 때.
Pull-through 캐시·Harbor 프록시 공유 레이어·버스트 흡수(디스크 전제). SPOF·캐시 정책 명시 필요. 장거리 링크 비용·불안정 시.

이그레스 비용과 장애 격리도 지연만큼 중요합니다. 인근 레지스트리 1차 + GHCR 폴백(더 낮은 동시성)처럼 적어 두면 온콜이 덜 흔들립니다.

실행 가능한 매개변수 매트릭스(붙여넣기용 기본값)

아래 행은 출발점입니다. 429 비율·풀 p95·디스크를 일주일 잰 뒤 “공격적” 열로만 이동하세요.

러너 프로필 레이어 동시 풀 docker login 토큰 TTL·갱신 HTTP 429 백오프(초, +지터) HTTP 5xx·연결 백오프(초, 상한) 디스크 워터마크(경고·스로틀·중단)
보수적(공유 풀·불안정 WAN) max-concurrent-downloads: 2 · BuildKit 병렬 2 fine-grained PAT 벽시계 30–60일 · 잡 토큰 ≤6시간 · 잡마다 재로그인 Retry-After 우선, 없으면 4→8→16→32→64(최대 120) 1→3→9→27→60(최대 300) 데이터 볼륨 사용률 80%·85%·90% · 여유 공간 ≥18GB
균형(NVMe·안정 이그레스) max-concurrent-downloads: 3–4 · BuildKit 병렬 4 PAT 60–90일 · 달력 순환은 TTL 50% 시점 · 주간 드리프트 점검 2→4→8→16→32(최대 90) 1→2→6→18→45(최대 180) 82%·87%·92% · 여유 ≥25GB
공격적(전용 Mac·동일 리전 미러) max-concurrent-downloads: 5–6(디스크 p95 대기 안정 시만) 로봇 단기 토큰 12–24시간 + 자정 자동 갱신 1→2→4→8→16(최대 60) — 자체 캐시 뒤에서만 0.5→1→3→9(최대 60) 85%·90%·93% · 잡 사이 선제 docker image prune

구현: daemon JSON의 max-concurrent-downloads, 필요 시 BUILDKIT_MAX_PARALLELISM, 그리고 docker pull 래퍼 한곳에 백오프 사다리를 고정하세요.

동시 풀·디스크: 빌드 풀 FAQ.

CI 연동 단계(예시 명령 자리표시자)

자리표시자는 대문자 스네이크로 통일해 치환하세요.

  1. 디스크 게이트: df -h "$WORKSPACE_ROOT" — 사용률이 매트릭스의 THROTTLE_PERCENT 이상이면 비정상 종료.
  2. 인증: echo "$REGISTRY_TOKEN" | docker login REGISTRY_HOST -u REGISTRY_USER --password-stdin
  3. 다이제스트 고정 풀: docker pull REGISTRY_HOST/NAMESPACE/IMAGE@sha256:IMAGE_DIGEST
  4. 검증: docker image inspect REGISTRY_HOST/NAMESPACE/IMAGE@sha256:IMAGE_DIGEST --format '{{.Id}}'
  5. 정리 트랩: docker logout REGISTRY_HOST 및 디스크 > WARN_PERCENT일 때 선택적 docker image prune -f --filter "until=24h"

FAQ: 풀이 멈춤·인증서·프록시

레이어 정지: 동시 다운로드↓, 프록시 HTTP/2·MTU 점검, 저속 타임아웃 후 5xx 사다리 재시도.

x509: CA를 키체인·Docker 양쪽에, pull 호스트명=SAN. IP·DNS 혼용 주의.

프록시: 데몬·CLI HTTPS_PROXY 일치, ghcr.io·GitHub·사설 허용. blob 정지 시 curl --http1.1 -I.

구조화 데이터: 절차는 HowTo, FAQ는 FAQPage JSON-LD로 분리하면 단계·질문 단위 노출에 유리합니다.

요약: 엔드포인트를 고정하고, 동시성을 상한하고, 예측 가능한 용량으로 검증하세요

GitHub 중심·지연 허용 → GHCR 1차. 상주·버스트·이그레스 우선 → 동일 리전 사설·pull-through. TTL·디스크 워터마크·중앙 백오프로 스탬피드를 막으세요.

전용 Apple Silicon 노드에서 캐시 위치와 daemon 프로파일을 스스로 고정하고 싶다면 요금·구매·도움말 센터·기술 블로그·홈으로 이어지는 공개 페이지만 안내합니다(로그인 불필요).

레지스트리 튜닝 여유가 있는 원격 Mac CI

Mac Mini급 노드, SSH/VNC, 예측 가능한 디스크, 팀이 정한 정책을 그대로 적용하세요. 요금·구매·도움말·블로그는 로그인 없이 이용할 수 있습니다.

요금제 보기 구매하기 도움말 블로그