세 가지 통증: 전송 후에야 드러나는 불일치
통증1: 메타데이터 착시로 인한 조용한 건너뛰기. 기본 rsync는 크기와 mtime으로 재전송 여부를 판단합니다. 빌드 팜에서 타임스탬프를 맞추거나, 컨테이너가 아래 초를 반올림하거나, 복구 스크립트가 내용은 바꾸지 않고 mtime만 갱신하면손상된 파일을 건너뛰는 위음성이 날 수 있습니다. 수천 파일 dist에서는 CDN·코드 서명 단계에서야 드러나 조사 비용이 급증합니다.
통증2: 중단과 부분 파일. 대용량 아카이브를 --partial-dir 없이 재개하면 최종 이름 옆에 반쯤 쓰인 데이터가 남고 CI 재시도와 뒤섞입니다. 감사 로그에배치 ID가 없으면 마지막 종료 코드만으로는 설명할 수 없습니다.
통증3: SFTP 로그가 ‘누가 썼는지’ 답하지 못함. 공유 키·GUI 클라이언트는 인증 성공과 바이트 수만 남기는 경우가 많습니다.멀티테넌트·동시 한도와 맞출 때 파이프라인별 키와 디렉터리 라벨이 필수입니다.
mtime과 size만으로는 ‘내용 동일성’을 증명할 수 없는 이유
mtime·size는메타데이터 근사일 뿐내용의 충분조건이 아닙니다. 엄격한 릴리스에서는 빌드 시 manifest를 만들고 원격에서 shasum -c를 통과시키거나, rsync --checksum으로 전송 결정에 해시를 넣습니다. 후자는 CPU 부담이 클 수 있습니다. 매니페스트 방식은 원자 릴리스와 잘 맞고 releases/배치를 검증한 뒤 current를 바꿉니다. SFTP와 rsync는 심볼릭 링크·확장 속성 처리가 다르므로 플래그를 문서화하고 매니페스트에는 런타임에 필요한 파일만 넣습니다.
정책 표: 체크섬, 매니페스트, 샘플링
CPU와 리스크 트레이드오프를 드러내는 표입니다.
| 정책 | 적합한 경우 | 비용 | 실패 신호 |
|---|---|---|---|
rsync --checksum | 중간 규모 트리, CPU 여유, 단일 명령 선호 | 동기 스캔에서 전 파일 해시, 대규모는 시간 증가 | 로그에 건너뛰기·재전송 이유 |
매니페스트＋shasum -c | CI가 산출물 레이아웃을 고정 가능 | 매니페스트 생성·경로 정규화 유지보수 | 비정상 종료로 승격 중단 용이 |
| 배포 후 샘플링 | 거대 객체 저장소에서 전체 해시 불가 | 운영 비용 낮음 | 탐지 지연 |
| size·mtime만 | 신뢰 LAN 스모크 | 최저 | 프로덕션 승격 비권장 |
실전: 재개 가능 rsync와 다섯 단계 SHA256 게이트
프로덕션 전 스테이징에서 검증하고 호스트명·경로를 바꿉니다. 원자 릴리스에서는버전 디렉터리를 목적지로 합니다.
# 1단계: 빌드 측에서 manifest 생성(예: dist)
cd dist && find . -type f -print0 | sort -z | xargs -0 shasum -a 256 > ../manifest.sha256
# 2단계: partial-dir 포함 rsync
rsync -avP --partial --partial-dir=.rsync-partial \
--bwlimit=8000 \
-e "ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=6" \
./ ../manifest.sha256 \
deploy@remote-mac:/srv/app/releases/202603281200/
# 3단계: 원격 shasum -c (비정상이면 승격 금지)
ssh deploy@remote-mac "cd /srv/app/releases/202603281200 && shasum -a 256 -c manifest.sha256"
# 4단계: JSONL에 감사 행 추가
ssh deploy@remote-mac "echo '{\"ts\":\"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'\",\"batch\":\"202603281200\",\"gate\":\"shasum\",\"exit\":0}' >> /var/log/ci-publish-audit.jsonl"
# 5단계: 검증 후 ln -sfn (원자 릴리스 글 참고)
# ssh deploy@remote-mac "ln -sfn /srv/app/releases/202603281200 /srv/app/current"
GUI SFTP도 검증 전 프로덕션 경로에 직접 덮어쓰지 말고 releases 아래로 보낸 뒤 shasum -c 하세요.심볼릭 전환 모델과 맞습니다.
수치 기준: 디스크, 타임아웃, 보관
(1) 여유 공간은 최대 산출물의 2.5배 이상.(2) CI 타임아웃은 전송 P95의 3배를 가이드로 합니다. 300MB급은 대륙 간 45~180초까지 걸릴 수 있습니다.(3) 감사에는 파이프라인 ID, 커밋 SHA, 배치 디렉터리, 검증 종료 코드를 포함하고 90일 이상 보관을 권장합니다.(4) --checksum 도입 시 첫 전체 소요 시간을 기록합니다. 쓰기는 releases/*만, 읽기는 current 경로로.Chroot와 함께 쓸 때 CI를 단일 접두사로 제한할 수 있습니다.
FAQ와 호스팅 원격 Mac
부분 전송 디렉터리를 Git에 넣나요?
아니요. .rsync-partial은 .gitignore에 넣습니다.
매니페스트와 잠금 파일의 차이?
잠금 파일은 의존성 버전을 고정합니다. 매니페스트는빌드 산출물 바이트열을 고정합니다.
언제 게이트가 필수인가요?
서명·스토어 제출·유료 고객 배포이며 공용망·다단 프록시가 있으면 트래픽 전환 전 shasum -c를 권장합니다.
온프레미스든임대 원격 Mac이든 절차는 같습니다. 배포 빈도가 높을수록 디스크 알림과 키 순환 부담이 커집니다. SFTPMAC에서는 격리 경로에서 재개·SHA256·원자 릴리스를 계속할 수 있습니다. 스테이징에서 「동기화→검증→전환」을 먼저 고정하세요.
자체 운영 부담을 줄이면서 게이트를 유지하려면 SFTPMAC 플랜과 노드 사양을 확인하세요.