[인프라] rclone 동기화 실패 원인 분석과 NAS 무결성 대응 전략

rclone 동기화 실패는 단순 전송 에러로 끝나지 않는 경우가 많습니다. 홈랩이든 사내 NAS든, 잡이 한 번 돌았다는 사실보다 더 중요한 건 목적지가 정말 신뢰 가능한 상태로 닫혔는지거든요. 제가 이 에러를 볼 때 먼저 의심하는 건 세 가지입니다. 원본 목록을 끝까지 읽지 못했거나, 파일 비교 기준이 현재 백엔드 조합과 안 맞거나, 삭제를 허용하면 안 되는 타이밍인데 삭제 판단 직전까지 갔거나 하는 경우입니다.

특히 NAS 운영에서는 파일이 조용히 빠지는 패턴이 더 위험하더라고요. 전체 실패면 바로 티가 나는데, 일부 디렉터리만 권한 문제로 누락되거나 수정 시간 비교가 흔들려 같은 파일을 계속 덮어쓰는 일은 며칠 지나서야 드러나기 쉽습니다. 그래서 저는 rclone을 그냥 복사 도구로 보기보다 검증 가능한 동기화 파이프라인으로 다루는 편을 권합니다. 이 글은 명령어를 많이 나열하기보다, NAS 데이터 무결성을 지키려면 어떤 옵션을 왜 고르는지에 집중해 보겠습니다.

NAS 원본, 원격 저장소, 검증 로그가 어떻게 이어지는지 한눈에 보는 구조입니다.

왜 rclone 동기화 실패를 가볍게 보면 안 되나

<code>rclone sync는 목적지를 출발지와 같게 맞추는 명령입니다. 여기서 무서운 지점은 단순 복사 실패보다 정리 단계가 꼬이는 상황입니다. rclone은 기본적으로 실행 중 에러가 나면 목적지 삭제를 진행하지 않습니다. 이 보호 동작은 분명 안전장치지만, 그렇다고 데이터가 이미 맞는 상태라는 뜻은 아니어서 여기서 방심하면 사고가 납니다.

제가 현장에서 더 자주 본 패턴은 이렇습니다.

• 목록 조회 이상: 원본 트리를 끝까지 읽지 못해 대량 삭제 후보가 생깁니다.
• 부분 읽기 실패: 특정 하위 폴더나 파일만 계속 빠지는데, 잡 자체는 종료됩니다.
• 비교 기준 불일치: modtime 정밀도 차이, 공통 해시 부재, 대소문자 처리 차이 때문에 변경 감지가 흔들립니다.
• 운영 정책 불일치: 보관이 목적인데도 sync를 써서 삭제 전파 위험을 키웁니다.

제 기준에서 rclone 문제 해결의 출발점은 간단합니다. 왜 실패했는지만 보지 말고, 이 실패가 삭제 판단인지 비교 판단인지 목록 판단인지부터 나눠 보는 겁니다. 이 분류가 안 되면 로그를 오래 봐도 답이 잘 안 나옵니다.

핵심 개념: sync, copy, check, bisync를 역할별로 나눠야 합니다

이 부분이 흐려지면 뒤에서 옵션을 아무리 만져도 계속 헷갈립니다. 저는 기능 설명보다 운영 질문으로 구분합니다. 목적지를 원본과 똑같이 맞출 건지, 목적지에 남아 있는 파일을 보존할 건지, 지금 필요한 게 복사가 아니라 검증인지로 나누는 식이죠.

여기서 제 추천은 명확합니다. 백업 NAS라면 기본값은 sync + check이고, 삭제 전파가 아직 부담스럽다면 copy + check로 시작하는 편이 낫습니다. 반대로 한쪽이 원본인데도 bisync를 쓰는 건 문제를 줄이기보다 늘리는 경우가 많았습니다. bisync는 첫 실행, 필터 변경, 이전 오류 복구 같은 상황에서 --resync가 필요한 고급 워크플로라서, 양방향 같아 보인다는 이유만으로 바로 고를 도구는 아닙니다.

제가 먼저 확인하는 rclone 동기화 실패 모드 7가지

운영에서 시간을 가장 많이 잡아먹는 건 에러 문구 자체보다, 서로 다른 원인이 비슷한 로그를 만든다는 점입니다. 아래 표처럼 증상과 근본 원인을 분리해 두면 판단이 훨씬 빨라집니다.

이 표에서 중요한 건 에러 메시지 해석보다 증상과 조치의 연결입니다. 목적지 삭제가 안 됐다고 해서 삭제 옵션부터 손대면 거의 항상 순서가 틀리더라고요. 먼저 찾아야 할 건 그보다 앞서 발생한 읽기 실패, 해시 실패, 권한 실패입니다.

실전 시나리오: NAS 원본에서 원격 백업으로 보낼 때 제가 잡는 기준

제가 실무에서 가장 강하게 권하는 기준 하나만 꼽으면 변경 중인 라이브 트리를 바로 sync하지 말라는 겁니다. 이건 rclone만의 문제가 아닙니다. 가상머신 이미지, 데이터베이스 덤프 디렉터리, 감시 카메라 녹화 폴더처럼 쓰기 작업이 계속 일어나는 트리는 전송 도중에도 내용이 바뀝니다. 이 상태에서 실패가 나면 전송 실패와 원본이 계속 움직여서 생긴 차이가 한꺼번에 섞여 버립니다.

그래서 저는 가능하면 NAS 스냅샷 경로나 읽기 전용 스테이징 경로를 원본으로 잡습니다. Btrfs, ZFS, LVM 스냅샷이 있으면 그 경로가 가장 좋고, 없으면 최소한 애플리케이션이 파일을 쓰지 않는 시간대로 옮기는 편이 낫습니다. 이거 하나만 지켜도 로그 해석 난도가 꽤 낮아집니다. 관련해서 이 블로그의 스냅샷 운영이나 systemd 자동화 글도 함께 읽어 두면 운영 기준을 잡기 쉬워집니다.

1. 실제 원본이 아니라 가능한 한 정지된 스냅샷 경로를 사용합니다.
2. 소스와 목적지 목록이 예상과 맞는지 lsf 또는 lsjson으로 먼저 봅니다.
3. --dry-run에 삭제 상한과 로그 파일을 붙여 검토합니다.
4. 실제 sync는 삭제 안전장치와 재시도 값을 명시해서 실행합니다.
5. 종료 직후 check 리포트를 남겨 전송과 검증을 분리합니다.

# 1) 원본/목적지 경로가 정말 맞는지 샘플 목록부터 확인
rclone lsf /srv/nas-snapshots/daily-01 --files-only --max-depth 2
rclone lsf remote-backup:nas-data --files-only --max-depth 2

# 2) 삭제/변경 후보를 먼저 본다
rclone sync /srv/nas-snapshots/daily-01 remote-backup:nas-data \
  --dry-run \
  -vv \
  --use-json-log \
  --check-first \
  --checksum \
  --max-delete 20 \
  --backup-dir remote-backup:nas-quarantine/$(date -u +%F) \
  --log-file /var/log/rclone/nas-sync-dryrun.jsonl

여기서 몇 가지는 꼭 짚고 넘어가야 합니다.

• --use-json-log: 한 번 읽고 끝낼 로그보다, 다음 실행과 비교하고 알림 스크립트에 태우기 쉬운 형식입니다.
• --check-first: 전송보다 비교를 먼저 끝내서 왜 이 파일이 대상이 됐는지 읽기 쉽게 해 줍니다.
• --checksum: 양쪽이 비교 가능한 해시를 제공할 때 modtime 흔들림을 줄이는 데 유리합니다. 해시를 못 쓰는 조합이라면 기대만큼 효과가 안 나올 수 있습니다.
• --max-delete: 경로 오타나 목록 실패가 났을 때 대량 삭제를 기계적으로 끊는 안전장치입니다.
• --backup-dir: 삭제나 덮어쓰기 대상 파일을 별도 계층으로 우회시켜, 사고가 나도 복구 경로를 남깁니다.

제가 dry-run에서 가장 먼저 보는 건 삭제 개수 자체보다 삭제가 어느 디렉터리 묶음에서 몰려 나오는가입니다. 전체 트리에서 고르게 나타나면 정책 이슈일 때가 많고, 특정 공유 폴더 한 군데에서 몰리면 그 하위 트리의 마운트 문제, 권한 문제, 필터 문제일 가능성이 큽니다.

실제 동기화 전에 dry-run 로그를 검토하는 장면을 보여주는 이미지 자리입니다.

실제 적용: 안전한 sync와 검증을 분리해서 운영하는 방법

dry-run이 정상이라면 그때 실동기화를 돌립니다. 이 단계에서 제가 중요하게 보는 건 속도보다 실패의 형태를 제어할 수 있느냐입니다. 회선이 가끔 흔들리는 원격지라면 무턱대고 병렬값을 올리기보다, --transfers와 --checkers를 줄여 요청 폭을 안정화하는 편이 더 낫더라고요. 반대로 API 호출 비용이 민감하고 전체 목록이 메모리에 들어가는 환경이라면 --fast-list가 거래 수를 줄이는 데 유리할 수 있지만, 아주 큰 트리에서는 메모리 사용량이 늘 수 있어 주의가 필요합니다.

rclone sync /srv/nas-snapshots/daily-01 remote-backup:nas-data \
  -vv \
  --use-json-log \
  --checksum \
  --check-first \
  --transfers 4 \
  --checkers 8 \
  --retries 3 \
  --low-level-retries 10 \
  --contimeout 15s \
  --timeout 2m \
  --max-delete 20 \
  --backup-dir remote-backup:nas-quarantine/$(date -u +%F) \
  --log-file /var/log/rclone/nas-sync.jsonl

rclone check /srv/nas-snapshots/daily-01 remote-backup:nas-data \
  --one-way \
  --combined /var/log/rclone/check.combined.txt \
  --differ /var/log/rclone/check.differ.txt \
  --missing-on-dst /var/log/rclone/check.missing-on-dst.txt \
  --missing-on-src /var/log/rclone/check.missing-on-src.txt \
  --error /var/log/rclone/check.error.txt

이 명령에서 선택 기준을 조금 더 현실적으로 풀어보면 이렇습니다.

• --transfers, --checkers: 느린 NAS CPU나 원격 API 타임아웃이 잦으면 올리기보다 낮춰서 안정화하는 쪽이 맞습니다.
• --contimeout: 연결 자체가 안 붙는 환경에서 기다림을 너무 길게 끌지 않게 해 줍니다.
• --timeout: 전송이 시작됐는데 오래 멈춘 세션을 끊는 데 유용합니다.
• --backup-dir: 삭제를 막지 않으면서도 복구 여지를 확보합니다. 보관 목적 백업에서 특히 실용적입니다.
• --one-way: 원본에 있는 파일이 목적지에 존재하는지 중심으로 검증할 때 해석이 단순합니다.

여기서 한 가지 더. rclone check는 기본적으로 크기와 해시를 중심으로 비교하므로, 양쪽 백엔드에 공통 해시가 없으면 검증 전략을 따로 잡아야 합니다. 이런 조합에서는 --download를 검토하거나, 비용이 부담되면 두 번째 sync 또는 copy 결과까지 함께 보는 식으로 운영 기준을 세우는 편이 현실적입니다. NAS의 권한, xattr, ownership 같은 메타데이터 자체가 중요하다면 목적지 지원 여부를 확인한 뒤 --metadata까지 검토해야 합니다.

[Unit]
Description=Rclone NAS Sync
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
User=backup
Group=backup
ExecStart=/bin/sh -lc '/usr/bin/rclone sync /srv/nas-snapshots/daily-01 remote-backup:nas-data --checksum --check-first --max-delete 20 --backup-dir remote-backup:nas-quarantine/$(date -u +%F) --log-file /var/log/rclone/nas-sync.jsonl --use-json-log'
ExecStartPost=/usr/bin/rclone check /srv/nas-snapshots/daily-01 remote-backup:nas-data --one-way --combined /var/log/rclone/check.combined.txt --error /var/log/rclone/check.error.txt
Nice=10
IOSchedulingClass=best-effort

[Install]
WantedBy=multi-user.target

크론도 나쁘진 않지만, 저는 실패 로그와 후처리 단계를 다루기 쉬워서 systemd를 더 자주 씁니다. 특히 sync와 check를 같은 서비스에서 순차 실행하면, 전송은 됐는데 검증이 안 돈 상태를 줄이기 좋았습니다. 위 예시처럼 날짜 치환이 필요하면 쉘을 명시해서 실행해야 한다는 점도 실무에서는 꽤 중요합니다.

자주 만나는 rclone 에러와 제가 했던 삽질

1. 권한 문제로 일부 파일만 계속 실패하는 경우

이건 NAS에서 정말 자주 봅니다. SMB로 생성된 파일을 로컬 쉘이나 SFTP 경로에서 읽을 때 권한 체계가 다르게 보이는 경우가 있고, ACL 때문에 일반 퍼미션만 보고 판단하면 놓치기 쉽습니다. 로그에 특정 파일만 계속 permission denied나 read failed로 남으면 네트워크보다 먼저 실행 계정이 그 파일을 실제로 읽을 수 있는지부터 확인해야 합니다.

제가 여기서 많이 했던 실수는 rclone 옵션을 바꾸는 거였습니다. 원인은 도구가 아니라 데이터 소유권과 접근 경로인 경우가 더 많았거든요. 파일을 열고 있는 서비스가 있다면 동기화 시간대를 바꾸거나, 아예 스냅샷 경로를 읽는 게 더 깔끔합니다.

2. 수정 시간(modtime) 비교가 꼬여서 계속 다시 전송하는 경우

서로 다른 스토리지 조합에서는 수정 시각 정밀도가 다릅니다. 어떤 백엔드는 초 단위만 보존하고, 어떤 쪽은 더 세밀하게 들고 있죠. 시계 동기화까지 흔들리면 같은 파일을 자꾸 바뀐 것으로 보기 쉽습니다.

이럴 때는 파일 수는 많고 변경량은 적은데, 매번 동일 파일이 재전송된다는 패턴이 보이는지 먼저 봅니다. 그다음 --checksum이나 --modify-window를 검토하는 편이 맞습니다. 반대로 대용량 파일이 드물게 바뀌는 환경에서 해시 계산 비용이 너무 크다면 modtime 기반을 유지하고 스냅샷 시점의 안정성을 높이는 쪽이 더 낫더라고요.

3. 네트워크 흔들림 때문에 같은 객체에서 오래 머무는 경우

--low-level-retries는 개별 요청 레벨 재시도, --retries는 상위 작업 재시도 정도로 이해하면 운영 판단에는 충분합니다. 여기서 중요한 건 숫자를 크게 주는 것보다 어디서 반복되느냐를 보는 겁니다. 같은 파일 하나에만 오래 매달리면 파일 손상이나 원격 객체 이상일 가능성이 있고, 여러 파일에서 산발적으로 반복되면 네트워크 품질이나 원격 API 응답성 쪽으로 보는 게 맞았습니다.

제가 직접 겪은 케이스 중에는 병렬값을 높인 뒤 오히려 타임아웃이 늘어난 경우가 많았습니다. 회선이 느리거나 원격 서비스가 엄격한 환경에서는 --transfers와 --checkers를 낮춰서 요청 폭을 줄이는 편이 더 안정적이었습니다.

4. sync를 양방향처럼 오해해서 데이터가 덮이는 경우

이건 사람 실수인데, 사고 규모는 제일 큽니다. sync는 단방향입니다. 목적지가 보조본이어야지, 양쪽의 최신본을 알아서 합쳐 주는 명령은 아닙니다. 양쪽에서 파일을 수정하는 작업 폴더라면 sync 자체가 정책 미스입니다.

이럴 때는 bisync를 검토하되, 첫 실행이나 필터 변경 뒤에는 --resync가 필요할 수 있습니다. 바로 본 실행부터 넣기보다 --dry-run으로 델타를 먼저 확인하는 습관이 훨씬 안전합니다.

5. 필터를 바꿨더니 갑자기 삭제 후보가 폭증하는 경우

이건 문서만 읽고도 놓치기 쉬운 지점인데, 운영에서는 진짜 자주 터집니다. 제외 규칙을 손보면 rclone 입장에서는 원래 보이던 파일이 갑자기 안 보이는 것처럼 해석될 수 있습니다. 특히 --delete-excluded 같은 옵션과 섞이면 더 위험합니다.

제 경험상 필터를 건드린 날은 본 실행보다 dry-run diff를 길게 보는 날로 잡는 게 맞습니다. bisync를 쓴다면 필터 변경 후 --resync가 필요한지도 꼭 확인해야 합니다.

6. 대소문자만 다른 파일명이 섞여 있는 경우

Linux NAS에서는 정상인 트리가, 대소문자 비민감한 목적지에서는 충돌로 바뀌는 케이스가 있습니다. 이런 경우 파일 내용보다 이름 계층이 먼저 깨집니다. 같은 파일명인데 케이스만 다른 자산이 있다면 사전에 정리하고, 필요한 경우 --fix-case를 검토하는 편이 안전합니다.

동기화 실패의 대표 원인을 한 장에 요약하는 시각 자료 자리입니다.

rclone 동기화 실패 로그를 어떻게 읽어야 원인을 빨리 찾을까

저는 긴 로그를 처음부터 끝까지 읽지 않습니다. 세 갈래로 자릅니다. 무엇을 지우려 했는지, 무엇을 읽지 못했는지, 검증에서 무엇이 남았는지만 따로 봅니다. 이 흐름이 익숙해지면 원인 추적 속도가 훨씬 빨라집니다.

1. dry-run 삭제 후보: 예상보다 많으면 실행 중단입니다. 대량 삭제는 실제 변경보다 경로, 목록, 필터 이슈일 때가 많았습니다.
2. 첫 번째 ERROR: 후속 에러가 수십 줄 있어도 원인은 첫 에러 부근에 걸리는 경우가 많습니다.
3. check 리포트 분리: missing-on-dst, missing-on-src, differ, error를 섞어 읽지 않습니다.

리포트 해석도 저는 꽤 기계적으로 합니다.

• missing-on-dst가 많다: 원본엔 있는데 목적지에 없습니다. 전송 실패, 필터 제외, 권한 문제 순서로 봅니다.
• missing-on-src가 많다: 목적지에만 남은 파일이 많습니다. 보관 백업이라면 정상일 수도 있고, 미러링 정책이라면 왜 누적되는지 점검해야 합니다.
• differ가 나온다: 파일명은 같지만 내용이나 해시가 다를 가능성이 큽니다. 샘플 몇 개를 직접 비교해 원인이 modtime인지 실제 내용 차이인지 가릅니다.
• error가 남는다: 검증 자체가 끝나지 않은 상태입니다. 이 경우 성공 판정을 내리면 안 됩니다.

추가로 저는 일반 텍스트 로그보다 JSON 로그를 선호합니다. 한 번 실패했을 때만 보기엔 비슷하지만, 두 실행 간 패턴 비교를 하거나 알림 스크립트에서 ERROR 이벤트만 뽑아낼 때 차이가 큽니다. 자동화 단계로 넘어가면 이거 진짜 편하더라고요.

검증 결과를 어떻게 운영 기준으로 바꿀까

검증은 단순 통과나 실패 체크가 아니라 다음 행동을 자동으로 결정하기 위한 분류여야 합니다. 저는 아래 기준으로 운영합니다.

• 계속 진행: sync 중 경고는 있었어도 check 리포트가 비어 있고, 삭제 후보가 정책 범위 안입니다.
• 같은 조건으로 1회 재시도: error에 일시적 읽기나 해시 문제만 있고, 동일 파일 재현성이 낮습니다.
• 조건 바꿔서 재시도: 특정 파일 반복 실패, 특정 디렉터리 집중 실패, timeout 누적이면 병렬값, 시간대, 원본 경로를 바꿉니다.
• 즉시 중단: dry-run에서 대량 삭제, 소스 경로 비정상, 필터 변경 직후 대규모 누락이 보입니다.
• 정책 전환 검토: missing-on-src가 계속 누적되고 삭제 전파가 부담스럽다면 sync보다 copy + check가 더 맞습니다.

제 운영 원칙은 단순합니다. 삭제 허용은 가장 늦게, 검증은 가장 먼저 자동화입니다. 많은 분이 전송 자동화부터 시작하시는데, 실제 사고를 줄이는 건 검증 결과를 기준으로 잡을 멈추는 쪽이었습니다.

누락 파일, 차이 파일, 오류 파일 리포트를 한눈에 확인하는 결과 화면 이미지 자리입니다.

운영 권장안: 이럴 땐 A, 저럴 땐 B

환경이 다르면 정답도 달라집니다. 그래도 백업 정책만 분명하면 선택은 의외로 단순합니다.

제 실제 권고를 짧게 적으면 이렇습니다.

• 백업 NAS의 기본값은 sync + check + dry-run 선행입니다.
• 삭제 사고가 걱정되면 당분간은 copy + check로 운영하면서 로그 패턴부터 익히는 편이 낫습니다.
• 원본 트리가 계속 바뀌는 환경이라면 옵션 튜닝보다 먼저 스냅샷 경로를 확보하세요.
• 대량 삭제 방지는 --max-delete, 복구 여지는 --backup-dir로 확보하세요.
• 양방향 협업 폴더가 아니라면 bisync를 먼저 꺼낼 이유는 거의 없습니다.

마지막으로 제가 가장 많이 강조하는 문장은 이겁니다. rclone 동기화 실패는 도구가 약해서가 아니라, 운영자가 전송과 검증을 같은 일로 취급할 때 사고로 커집니다. 로그를 구조화해서 남기고, dry-run으로 삭제를 먼저 보고, check 리포트로 최종 상태를 닫으세요. 이 흐름으로 운영하면 NAS 데이터 동기화의 무결성을 훨씬 덜 불안하게 가져갈 수 있습니다.