composer config 체인, GitLab CI의 동시성·프록시·재시도, COMPOSER_CACHE_DIR·캐시 키를 표로 묶었습니다. 교차 참고: Gradle·Maven, Go GOPROXY, 풀 안정성 FAQ. 홈·기술 블로그.
시나리오와 병목: 국경 간 풀 타임아웃, 인증, lock 일관성
composer install은 메타·dist·VCS가 연쇄로 열려 한 홉 지연이 전체 잡 정지처럼 보이기 쉽습니다. 원격 Mac은 회선·방화벽이 로컬과 다릅니다.
- 국경 간 타임아웃: 대형 트리에서
COMPOSER_PROCESS_TIMEOUT부족·프록시 TLS 지연이 겹치면 중간 단절. - 인증: GitLab Registry·GitHub 등 토큰/HTTP Basic 불일치 시 401. CI 스크립트에 비밀 노출·히스토리 유출 방지.
- lock 일관성: 미러 변경 후 lock 미갱신 시 해시·URL 불일치. 러너마다 다른 글로벌
repositories면 CI만 실패하는 패턴.
먼저 로그로 dist·메타·Git 중 어디가 깨졌는지 구분한 뒤 미러·토큰·depth를 고릅니다.
Packagist·국내(지역) 미러·엔터프라이즈 사설 저장소: 체인 폴백 대조표와 composer config
Composer 2는 repositories를 위→아래로 봅니다. 사설을 앞에 두고 미러·Packagist를 폴백으로 두세요. 공개 인덱스를 끌 때는 "packagist": false 후 승인 URL만 남기는 식이 흔합니다.
| 계층 | 역할 | 복붙 예시 (프로젝트 composer.json의 repositories 안 항목) |
|---|---|---|
| ① GitLab / 사내 Satis | 비공개 패키지·승인된 버전만 노출 | {"type":"composer","url":"https://gitlab.example.com/api/v4/projects/ID/packages/composer"} (조직·그룹 엔드포인트는 문서 확인) |
| ② 지역 미러 | 동일 리전 RTT 단축·대역 절약 | {"type":"composer","url":"https://mirrors.aliyun.com/composer/"} 등 조직 승인 미러 URL |
| ③ repo.packagist.org | 공개 패키지 기본 원본 | 미러만 쓸 때: 루트에 "packagist": false 후 {"type":"composer","url":"https://repo.packagist.org"}를 명시적으로 추가 |
러너 이미지에 글로벌로 고정하면 저장소 간 설정 편차가 줄어듭니다.
미러 동기 지연 시 체인 끝에 repo.packagist.org를 두거나 릴리스 직후 dist 정책을 문서화하세요.
GitLab CI와 병행할 때: 동시성, HTTP 프록시, 재시도·백오프 파라미터
동시 잡이 많으면 캐시 락·디스크 메타 IO가 먼저 병목입니다. resource_group으로 직렬화하거나 캐시 경로를 분리하세요.
| 파라미터·키워드 | 권장 용도 |
|---|---|
resource_group: composer-$CI_RUNNER_ID |
동일 러너에서 캐시 디렉터리 손상·락 충돌 방지 |
HTTP_PROXY / HTTPS_PROXY / NO_PROXY |
사내 프록시 경유 시; GitLab·미러 호스트를 NO_PROXY에 빼면 분기 디버깅이 쉬움 |
COMPOSER_PROCESS_TIMEOUT |
국경 간 링크에서 기본 타임아웃 상향(초 단위) |
composer install --no-interaction --prefer-dist --no-progress |
CI 로그 노이즈·TTY 질문 제거 |
| 쉘 백오프 (예: 2·4·8초, 최대 3회) | 일시적 5xx·연결 리셋 시 retry:와 병행 |
retry: (GitLab) |
네트워크 플레이크용; 근본 원인이 401이면 재시도만으로는 해결 안 됨 |
단일 잡 p95를 본 뒤 matrix를 넓히고, 프록시 환경에서만 실패하면 인증서·PAC·MITM 예외를 점검합니다.
원격 Mac 캐시 디렉터리, COMPOSER_CACHE_DIR, CI 캐시 키
공유 원격 Mac에서는 COMPOSER_CACHE_DIR를 명시하는 편이 안전합니다(프로젝트 하위 또는 풀 NVMe).
- 경로: 예)
$CI_PROJECT_DIR/.composer-cache— 다잡 공유 시 락 증가. - 캐시 키:
composer.lock·PHP 마이너·미러/레지스트리 버전;platform변경 시 키 갱신. - 무효화: 미러 URL 변경 후 오래된 dist 메타가 남을 수 있어 lock/미러 변경 시 캐시 미스 규칙을 둡니다.
cache: 예시 키FAQ: 401, rate limit, 해시 검증 실패
401: COMPOSER_AUTH·토큰 종류가 호스트와 맞는지 확인. composer config --list --source로 출처 추적, CI verbose는 최소화.
rate limit: 미인증 다운로드·API 호출을 줄이고 미러·캐시 히트를 올립니다. 동일 PAT 과다 공유는 피합니다.
해시 불일치: lock과 실제 dist가 어긋난 경우. 캐시 삭제 후 동일 미러로 재시도하거나 로컬에서 lock을 맞춰 커밋합니다.